![\"devtron](\"https://cloud.githubusercontent.com/assets/1305617/17156618/9f9bcd72-533f-11e6-880d-389115f40a2a.png\")
\n\nDefine keyboard shortcuts.
\n
Accelerators are Strings that can contain multiple modifiers and a single key code,\ncombined by the + character, and are used to define keyboard shortcuts\nthroughout your application.
Examples:
\nCommandOrControl+ACommandOrControl+Shift+ZShortcuts are registered with the globalShortcut module\nusing the register\nmethod, i.e.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+Y' shortcut listener.\n globalShortcut.register('CommandOrControl+Y', () => {\n // Do stuff when Y and either Command/Control is pressed.\n })\n})\nOn Linux and Windows, the Command key does not have any effect so\nuse CommandOrControl which represents Command on macOS and Control on\nLinux and Windows to define some accelerators.
Use Alt instead of Option. The Option key only exists on macOS, whereas\nthe Alt key is available on all platforms.
The Super (or Meta) key is mapped to the Windows key on Windows and Linux and\nCmd on macOS.
Command (or Cmd for short)Control (or Ctrl for short)CommandOrControl (or CmdOrCtrl for short)AltOptionAltGrShiftSuperMeta0 to 9A to ZF1 to F24~, !, @, #, $, etc.PlusSpaceTabCapslockNumlockScrolllockBackspaceDeleteInsertReturn (or Enter as alias)Up, Down, Left and RightHome and EndPageUp and PageDownEscape (or Esc for short)VolumeUp, VolumeDown and VolumeMuteMediaNextTrack, MediaPreviousTrack, MediaStop and MediaPlayPausePrintScreennum0 - num9numdec - decimal keynumadd - numpad + keynumsub - numpad - keynummult - numpad * keynumdiv - numpad ÷ keyMaking accessible applications is important and we're happy to provide\nfunctionality to Devtron and Spectron that gives\ndevelopers the opportunity to make their apps better for everyone.
\nAccessibility concerns in Electron applications are similar to those of\nwebsites because they're both ultimately HTML. With Electron apps, however,\nyou can't use the online resources for accessibility audits because your app\ndoesn't have a URL to point the auditor to.
\nThese features bring those auditing tools to your Electron app. You can\nchoose to add audits to your tests with Spectron or use them within DevTools\nwith Devtron. Read on for a summary of the tools.
\nIn the testing framework Spectron, you can now audit each window and <webview>\ntag in your application. For example:
app.client.auditAccessibility().then(function (audit) {\n if (audit.failed) {\n console.error(audit.message)\n }\n})\nYou can read more about this feature in Spectron's documentation.
\nIn Devtron, there is an accessibility tab which will allow you to audit a\npage in your app, sort and filter the results.
\n
Both of these tools are using the Accessibility Developer Tools\nlibrary built by Google for Chrome. You can learn more about the accessibility\naudit rules this library uses on that repository's wiki.
\nIf you know of other great accessibility tools for Electron, add them to the\naccessibility documentation with a pull request.
\nElectron applications will automatically enable accessibility features in the\npresence of assistive technology (e.g. JAWS\non Windows or VoiceOver on macOS).\nSee Chrome's accessibility documentation for more details.
\nYou can also manually toggle these features either within your Electron application\nor by setting flags in third-party native software.
\nBy using the app.setAccessibilitySupportEnabled(enabled)\nAPI, you can manually expose Chrome's accessibility tree to users in the application preferences.\nNote that the user's system assistive utilities have priority over this setting and\nwill override it.
On macOS, third-party assistive technology can toggle accessibility features inside\nElectron applications by setting the AXManualAccessibility attribute\nprogrammatically:
CFStringRef kAXManualAccessibility = CFSTR(\"AXManualAccessibility\");\n\n+ (void)enableAccessibility:(BOOL)enable inElectronApplication:(NSRunningApplication *)app\n{\n AXUIElementRef appRef = AXUIElementCreateApplication(app.processIdentifier);\n if (appRef == nil)\n return;\n\n CFBooleanRef value = enable ? kCFBooleanTrue : kCFBooleanFalse;\n AXUIElementSetAttributeValue(appRef, kAXManualAccessibility, value);\n CFRelease(appRef);\n}\n\n\nControl your application's event lifecycle.
\n
Process: Main
\nThe following example shows how to quit the application when the last window is\nclosed:
\nconst { app } = require('electron')\napp.on('window-all-closed', () => {\n app.quit()\n})\nThe app object emits the following events:
Emitted when the application has finished basic startup. On Windows and Linux,\nthe will-finish-launching event is the same as the ready event; on macOS,\nthis event represents the applicationWillFinishLaunching notification of\nNSApplication. You would usually set up listeners for the open-file and\nopen-url events here, and start the crash reporter and auto updater.
In most cases, you should do everything in the ready event handler.
Returns:
\nevent EventlaunchInfo Record<string, any> | NotificationResponse macOSEmitted once, when Electron has finished initializing. On macOS, launchInfo\nholds the userInfo of the NSUserNotification or information from\nUNNotificationResponse that was used to open the\napplication, if it was launched from Notification Center. You can also call\napp.isReady() to check if this event has already fired and app.whenReady()\nto get a Promise that is fulfilled when Electron is initialized.
Emitted when all windows have been closed.
\nIf you do not subscribe to this event and all windows are closed, the default\nbehavior is to quit the app; however, if you subscribe, you control whether the\napp quits or not. If the user pressed Cmd + Q, or the developer called\napp.quit(), Electron will first try to close all the windows and then emit the\nwill-quit event, and in this case the window-all-closed event would not be\nemitted.
Returns:
\nevent EventEmitted before the application starts closing its windows.\nCalling event.preventDefault() will prevent the default behavior, which is\nterminating the application.
Note: If application quit was initiated by autoUpdater.quitAndInstall(),\nthen before-quit is emitted after emitting close event on all windows and\nclosing them.
Note: On Windows, this event will not be emitted if the app is closed due\nto a shutdown/restart of the system or a user logout.
\nReturns:
\nevent EventEmitted when all windows have been closed and the application will quit.\nCalling event.preventDefault() will prevent the default behavior, which is\nterminating the application.
See the description of the window-all-closed event for the differences between\nthe will-quit and window-all-closed events.
Note: On Windows, this event will not be emitted if the app is closed due\nto a shutdown/restart of the system or a user logout.
\nReturns:
\nevent EventexitCode IntegerEmitted when the application is quitting.
\nNote: On Windows, this event will not be emitted if the app is closed due\nto a shutdown/restart of the system or a user logout.
\nReturns:
\nevent Eventpath StringEmitted when the user wants to open a file with the application. The open-file\nevent is usually emitted when the application is already open and the OS wants\nto reuse the application to open the file. open-file is also emitted when a\nfile is dropped onto the dock and the application is not yet running. Make sure\nto listen for the open-file event very early in your application startup to\nhandle this case (even before the ready event is emitted).
You should call event.preventDefault() if you want to handle this event.
On Windows, you have to parse process.argv (in the main process) to get the\nfilepath.
Returns:
\nevent Eventurl StringEmitted when the user wants to open a URL with the application. Your application's\nInfo.plist file must define the URL scheme within the CFBundleURLTypes key, and\nset NSPrincipalClass to AtomApplication.
You should call event.preventDefault() if you want to handle this event.
Returns:
\nevent EventhasVisibleWindows BooleanEmitted when the application is activated. Various actions can trigger\nthis event, such as launching the application for the first time, attempting\nto re-launch the application when it's already running, or clicking on the\napplication's dock or taskbar icon.
\nReturns:
\nevent EventEmitted when mac application become active. Difference from activate event is\nthat did-become-active is emitted every time the app becomes active, not only\nwhen Dock icon is clicked or application is re-launched.
Returns:
\nevent Eventtype String - A string identifying the activity. Maps to\nNSUserActivity.activityType.userInfo unknown - Contains app-specific state stored by the activity on\nanother device.details ObjectwebpageURL String (optional) - A string identifying the URL of the webpage accessed by the activity on another device, if available.Emitted during Handoff when an activity from a different device wants\nto be resumed. You should call event.preventDefault() if you want to handle\nthis event.
A user activity can be continued only in an app that has the same developer Team\nID as the activity's source app and that supports the activity's type.\nSupported activity types are specified in the app's Info.plist under the\nNSUserActivityTypes key.
Returns:
\nevent Eventtype String - A string identifying the activity. Maps to\nNSUserActivity.activityType.Emitted during Handoff before an activity from a different device wants\nto be resumed. You should call event.preventDefault() if you want to handle\nthis event.
Returns:
\nevent Eventtype String - A string identifying the activity. Maps to\nNSUserActivity.activityType.error String - A string with the error's localized description.Emitted during Handoff when an activity from a different device\nfails to be resumed.
\nReturns:
\nevent Eventtype String - A string identifying the activity. Maps to\nNSUserActivity.activityType.userInfo unknown - Contains app-specific state stored by the activity.Emitted during Handoff after an activity from this device was successfully\nresumed on another one.
\nReturns:
\nevent Eventtype String - A string identifying the activity. Maps to\nNSUserActivity.activityType.userInfo unknown - Contains app-specific state stored by the activity.Emitted when Handoff is about to be resumed on another device. If you need to update the state to be transferred, you should call event.preventDefault() immediately, construct a new userInfo dictionary and call app.updateCurrentActivity() in a timely manner. Otherwise, the operation will fail and continue-activity-error will be called.
Returns:
\nevent EventEmitted when the user clicks the native macOS new tab button. The new\ntab button is only visible if the current BrowserWindow has a\ntabbingIdentifier
Returns:
\nevent Eventwindow BrowserWindowEmitted when a browserWindow gets blurred.
\nReturns:
\nevent Eventwindow BrowserWindowEmitted when a browserWindow gets focused.
\nReturns:
\nevent Eventwindow BrowserWindowEmitted when a new browserWindow is created.
\nReturns:
\nevent EventwebContents WebContentsEmitted when a new webContents is created.
\nReturns:
\nevent EventwebContents WebContentsurl Stringerror String - The error codecertificate Certificatecallback FunctionisTrusted Boolean - Whether to consider the certificate as trustedisMainFrame BooleanEmitted when failed to verify the certificate for url, to trust the\ncertificate you should prevent the default behavior with\nevent.preventDefault() and call callback(true).
const { app } = require('electron')\n\napp.on('certificate-error', (event, webContents, url, error, certificate, callback) => {\n if (url === 'https://github.com') {\n // Verification logic.\n event.preventDefault()\n callback(true)\n } else {\n callback(false)\n }\n})\nReturns:
\nevent EventwebContents WebContentsurl URLcertificateList Certificate[]callback Functioncertificate Certificate (optional)Emitted when a client certificate is requested.
\nThe url corresponds to the navigation entry requesting the client certificate\nand callback can be called with an entry filtered from the list. Using\nevent.preventDefault() prevents the application from using the first\ncertificate from the store.
const { app } = require('electron')\n\napp.on('select-client-certificate', (event, webContents, url, list, callback) => {\n event.preventDefault()\n callback(list[0])\n})\nReturns:
\nevent EventwebContents WebContentsauthenticationResponseDetails Objecturl URLauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (optional)password String (optional)Emitted when webContents wants to do basic auth.
The default behavior is to cancel all authentications. To override this you\nshould prevent the default behavior with event.preventDefault() and call\ncallback(username, password) with the credentials.
const { app } = require('electron')\n\napp.on('login', (event, webContents, details, authInfo, callback) => {\n event.preventDefault()\n callback('username', 'secret')\n})\nIf callback is called without a username or password, the authentication\nrequest will be cancelled and the authentication error will be returned to the\npage.
Emitted whenever there is a GPU info update.
\nReturns:
\nevent Eventkilled BooleanEmitted when the GPU process crashes or is killed.
\nDeprecated: This event is superceded by the child-process-gone event\nwhich contains more information about why the child process disappeared. It\nisn't always because it crashed. The killed boolean can be replaced by\nchecking reason === 'killed' when you switch to that event.
Returns:
\nevent EventwebContents WebContentskilled BooleanEmitted when the renderer process of webContents crashes or is killed.
Deprecated: This event is superceded by the render-process-gone event\nwhich contains more information about why the render process disappeared. It\nisn't always because it crashed. The killed boolean can be replaced by\nchecking reason === 'killed' when you switch to that event.
Returns:
\nevent EventwebContents WebContentsdetails Objectreason String - The reason the render process is gone. Possible values:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Integer - The exit code of the process, unless reason is\nlaunch-failed, in which case exitCode will be a platform-specific\nlaunch failure error code.Emitted when the renderer process unexpectedly disappears. This is normally\nbecause it was crashed or killed.
\nReturns:
\nevent Eventdetails Objecttype String - Process type. One of the following values:UtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownreason String - The reason the child process is gone. Possible values:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Number - The exit code for the process\n(e.g. status from waitpid if on posix, from GetExitCodeProcess on Windows).serviceName String (optional) - The non-localized name of the process.name String (optional) - The name of the process.\nExamples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.Emitted when the child process unexpectedly disappears. This is normally\nbecause it was crashed or killed. It does not include renderer processes.
\nReturns:
\nevent EventaccessibilitySupportEnabled Boolean - true when Chrome's accessibility\nsupport is enabled, false otherwise.Emitted when Chrome's accessibility support changes. This event fires when\nassistive technologies, such as screen readers, are enabled or disabled.\nSee https://www.chromium.org/developers/design-documents/accessibility for more\ndetails.
\nReturns:
\nsession SessionEmitted when Electron has created a new session.
const { app } = require('electron')\n\napp.on('session-created', (session) => {\n console.log(session)\n})\nReturns:
\nevent Eventargv String[] - An array of the second instance's command line argumentsworkingDirectory String - The second instance's working directoryThis event will be emitted inside the primary instance of your application\nwhen a second instance has been executed and calls app.requestSingleInstanceLock().
argv is an Array of the second instance's command line arguments,\nand workingDirectory is its current working directory. Usually\napplications respond to this by making their primary window focused and\nnon-minimized.
Note: If the second instance is started by a different user than the first, the argv array will not include the arguments.
This event is guaranteed to be emitted after the ready event of app\ngets emitted.
Note: Extra command line arguments might be added by Chromium,\nsuch as --original-process-start-time.
Returns:
\nevent EventwebContents WebContentsEmitted when desktopCapturer.getSources() is called in the renderer process of webContents.\nCalling event.preventDefault() will make it return empty sources.
The app object has the following methods:
Note: Some methods are only available on specific operating systems and are\nlabeled as such.
\napp.quit()Try to close all windows. The before-quit event will be emitted first. If all\nwindows are successfully closed, the will-quit event will be emitted and by\ndefault the application will terminate.
This method guarantees that all beforeunload and unload event handlers are\ncorrectly executed. It is possible that a window cancels the quitting by\nreturning false in the beforeunload event handler.
app.exit([exitCode])exitCode Integer (optional)Exits immediately with exitCode. exitCode defaults to 0.
All windows will be closed immediately without asking the user, and the before-quit\nand will-quit events will not be emitted.
app.relaunch([options])Relaunches the app when current instance exits.
\nBy default, the new instance will use the same working directory and command line\narguments with current instance. When args is specified, the args will be\npassed as command line arguments instead. When execPath is specified, the\nexecPath will be executed for relaunch instead of current app.
Note that this method does not quit the app when executed, you have to call\napp.quit or app.exit after calling app.relaunch to make the app restart.
When app.relaunch is called for multiple times, multiple instances will be\nstarted after current instance exited.
An example of restarting current instance immediately and adding a new command\nline argument to the new instance:
\nconst { app } = require('electron')\n\napp.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) })\napp.exit(0)\napp.isReady()Returns Boolean - true if Electron has finished initializing, false otherwise.\nSee also app.whenReady().
app.whenReady()Returns Promise<void> - fulfilled when Electron is initialized.\nMay be used as a convenient alternative to checking app.isReady()\nand subscribing to the ready event if the app is not ready yet.
app.focus([options])options Object (optional)steal Boolean macOS - Make the receiver the active app even if another app is\ncurrently active.On Linux, focuses on the first visible window. On macOS, makes the application\nthe active app. On Windows, focuses on the application's first window.
\nYou should seek to use the steal option as sparingly as possible.
app.hide() macOSHides all application windows without minimizing them.
\napp.show() macOSShows application windows after they were hidden. Does not automatically focus\nthem.
\napp.setAppLogsPath([path])path String (optional) - A custom path for your logs. Must be absolute.Sets or creates a directory your app's logs which can then be manipulated with app.getPath() or app.setPath(pathName, newPath).
Calling app.setAppLogsPath() without a path parameter will result in this directory being set to ~/Library/Logs/YourAppName on macOS, and inside the userData directory on Linux and Windows.
app.getAppPath()Returns String - The current application directory.
app.getPath(name)name String - You can request the following paths by the name:home User's home directory.appData Per-user application data directory, which by default points to:%APPDATA% on Windows$XDG_CONFIG_HOME or ~/.config on Linux~/Library/Application Support on macOSuserData The directory for storing your app's configuration files, which by\ndefault it is the appData directory appended with your app's name.cachetemp Temporary directory.exe The current executable file.module The libchromiumcontent library.desktop The current user's Desktop directory.documents Directory for a user's \"My Documents\".downloads Directory for a user's downloads.music Directory for a user's music.pictures Directory for a user's pictures.videos Directory for a user's videos.recent Directory for the user's recent files (Windows only).logs Directory for your app's log folder.crashDumps Directory where crash dumps are stored.Returns String - A path to a special directory or file associated with name. On\nfailure, an Error is thrown.
If app.getPath('logs') is called without called app.setAppLogsPath() being called first, a default log directory will be created equivalent to calling app.setAppLogsPath() without a path parameter.
app.getFileIcon(path[, options])path Stringoptions Object (optional)size Stringsmall - 16x16normal - 32x32large - 48x48 on Linux, 32x32 on Windows, unsupported on macOS.Returns Promise<NativeImage> - fulfilled with the app's icon, which is a NativeImage.
Fetches a path's associated icon.
\nOn Windows, there a 2 kinds of icons:
\n.mp3, .png, etc..exe, .dll, .ico.On Linux and macOS, icons depend on the application associated with file mime type.
\napp.setPath(name, path)name Stringpath StringOverrides the path to a special directory or file associated with name.\nIf the path specifies a directory that does not exist, an Error is thrown.\nIn that case, the directory should be created with fs.mkdirSync or similar.
You can only override paths of a name defined in app.getPath.
By default, web pages' cookies and caches will be stored under the userData\ndirectory. If you want to change this location, you have to override the\nuserData path before the ready event of the app module is emitted.
app.getVersion()Returns String - The version of the loaded application. If no version is found in the\napplication's package.json file, the version of the current bundle or\nexecutable is returned.
app.getName()Returns String - The current application's name, which is the name in the application's\npackage.json file.
Usually the name field of package.json is a short lowercase name, according\nto the npm modules spec. You should usually also specify a productName\nfield, which is your application's full capitalized name, and which will be\npreferred over name by Electron.
app.setName(name)name StringOverrides the current application's name.
\nNote: This function overrides the name used internally by Electron; it does not affect the name that the OS uses.
\napp.getLocale()Returns String - The current application locale, fetched using Chromium's l10n_util library.\nPossible return values are documented here.
To set the locale, you'll want to use a command line switch at app startup, which may be found here.
\nNote: When distributing your packaged app, you have to also ship the\nlocales folder.
Note: On Windows, you have to call it after the ready events gets emitted.
app.getLocaleCountryCode()Returns String - User operating system's locale two-letter ISO 3166 country code. The value is taken from native OS APIs.
Note: When unable to detect locale country code, it returns empty string.
\napp.addRecentDocument(path) macOS Windowspath StringAdds path to the recent documents list.
This list is managed by the OS. On Windows, you can visit the list from the task\nbar, and on macOS, you can visit it from dock menu.
\napp.clearRecentDocuments() macOS WindowsClears the recent documents list.
\napp.setAsDefaultProtocolClient(protocol[, path, args])protocol String - The name of your protocol, without ://. For example,\nif you want your app to handle electron:// links, call this method with\nelectron as the parameter.path String (optional) Windows - The path to the Electron executable.\nDefaults to process.execPathargs String Windows - Arguments passed to the executable.\nDefaults to an empty arrayReturns Boolean - Whether the call succeeded.
Sets the current executable as the default handler for a protocol (aka URI\nscheme). It allows you to integrate your app deeper into the operating system.\nOnce registered, all links with your-protocol:// will be opened with the\ncurrent executable. The whole link, including protocol, will be passed to your\napplication as a parameter.
Note: On macOS, you can only register protocols that have been added to\nyour app's info.plist, which cannot be modified at runtime. However, you can\nchange the file during build time via Electron Forge,\nElectron Packager, or by editing info.plist with a text\neditor. Please refer to Apple's documentation for details.
Note: In a Windows Store environment (when packaged as an appx) this API\nwill return true for all calls but the registry key it sets won't be accessible\nby other applications. In order to register your Windows Store application\nas a default protocol handler you must declare the protocol in your manifest.
The API uses the Windows Registry and LSSetDefaultHandlerForURLScheme internally.
app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windowsprotocol String - The name of your protocol, without ://.path String (optional) Windows - Defaults to process.execPathargs String Windows - Defaults to an empty arrayReturns Boolean - Whether the call succeeded.
This method checks if the current executable as the default handler for a\nprotocol (aka URI scheme). If so, it will remove the app as the default handler.
\napp.isDefaultProtocolClient(protocol[, path, args])protocol String - The name of your protocol, without ://.path String (optional) Windows - Defaults to process.execPathargs String Windows - Defaults to an empty arrayReturns Boolean - Whether the current executable is the default handler for a\nprotocol (aka URI scheme).
Note: On macOS, you can use this method to check if the app has been\nregistered as the default protocol handler for a protocol. You can also verify\nthis by checking ~/Library/Preferences/com.apple.LaunchServices.plist on the\nmacOS machine. Please refer to\nApple's documentation for details.
The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internally.
app.getApplicationNameForProtocol(url)url String - a URL with the protocol name to check. Unlike the other\nmethods in this family, this accepts an entire URL, including :// at a\nminimum (e.g. https://).Returns String - Name of the application handling the protocol, or an empty\nstring if there is no handler. For instance, if Electron is the default\nhandler of the URL, this could be Electron on Windows and Mac. However,\ndon't rely on the precise format which is not guaranteed to remain unchanged.\nExpect a different format on Linux, possibly with a .desktop suffix.
This method returns the application name of the default handler for the protocol\n(aka URI scheme) of a URL.
\napp.getApplicationInfoForProtocol(url) macOS Windowsurl String - a URL with the protocol name to check. Unlike the other\nmethods in this family, this accepts an entire URL, including :// at a\nminimum (e.g. https://).Returns Promise<Object> - Resolve with an object containing the following:
icon NativeImage - the display icon of the app handling the protocol.path String - installation path of the app handling the protocol.name String - display name of the app handling the protocol.This method returns a promise that contains the application name, icon and path of the default handler for the protocol\n(aka URI scheme) of a URL.
\napp.setUserTasks(tasks) Windowstasks Task[] - Array of Task objectsAdds tasks to the Tasks category of the Jump List on Windows.
tasks is an array of Task objects.
Returns Boolean - Whether the call succeeded.
Note: If you'd like to customize the Jump List even more use\napp.setJumpList(categories) instead.
app.getJumpListSettings() WindowsReturns Object:
minItems Integer - The minimum number of items that will be shown in the\nJump List (for a more detailed description of this value see the\nMSDN docs).removedItems JumpListItem[] - Array of JumpListItem\nobjects that correspond to items that the user has explicitly removed from custom categories in the\nJump List. These items must not be re-added to the Jump List in the next\ncall to app.setJumpList(), Windows will not display any custom category\nthat contains any of the removed items.app.setJumpList(categories) Windowscategories JumpListCategory[] | null - Array of JumpListCategory objects.Sets or removes a custom Jump List for the application, and returns one of the\nfollowing strings:
\nok - Nothing went wrong.error - One or more errors occurred, enable runtime logging to figure out\nthe likely cause.invalidSeparatorError - An attempt was made to add a separator to a\ncustom category in the Jump List. Separators are only allowed in the\nstandard Tasks category.fileTypeRegistrationError - An attempt was made to add a file link to\nthe Jump List for a file type the app isn't registered to handle.customCategoryAccessDeniedError - Custom categories can't be added to the\nJump List due to user privacy or group policy settings.If categories is null the previously set custom Jump List (if any) will be\nreplaced by the standard Jump List for the app (managed by Windows).
Note: If a JumpListCategory object has neither the type nor the name\nproperty set then its type is assumed to be tasks. If the name property\nis set but the type property is omitted then the type is assumed to be\ncustom.
Note: Users can remove items from custom categories, and Windows will not\nallow a removed item to be added back into a custom category until after\nthe next successful call to app.setJumpList(categories). Any attempt to\nre-add a removed item to a custom category earlier than that will result in the\nentire custom category being omitted from the Jump List. The list of removed\nitems can be obtained using app.getJumpListSettings().
Note: The maximum length of a Jump List item's description property is\n260 characters. Beyond this limit, the item will not be added to the Jump\nList, nor will it be displayed.
Here's a very simple example of creating a custom Jump List:
\nconst { app } = require('electron')\n\napp.setJumpList([\n {\n type: 'custom',\n name: 'Recent Projects',\n items: [\n { type: 'file', path: 'C:\\\\Projects\\\\project1.proj' },\n { type: 'file', path: 'C:\\\\Projects\\\\project2.proj' }\n ]\n },\n { // has a name so `type` is assumed to be \"custom\"\n name: 'Tools',\n items: [\n {\n type: 'task',\n title: 'Tool A',\n program: process.execPath,\n args: '--run-tool-a',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool A'\n },\n {\n type: 'task',\n title: 'Tool B',\n program: process.execPath,\n args: '--run-tool-b',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool B'\n }\n ]\n },\n { type: 'frequent' },\n { // has no name and no type so `type` is assumed to be \"tasks\"\n items: [\n {\n type: 'task',\n title: 'New Project',\n program: process.execPath,\n args: '--new-project',\n description: 'Create a new project.'\n },\n { type: 'separator' },\n {\n type: 'task',\n title: 'Recover Project',\n program: process.execPath,\n args: '--recover-project',\n description: 'Recover Project'\n }\n ]\n }\n])\napp.requestSingleInstanceLock()Returns Boolean
The return value of this method indicates whether or not this instance of your\napplication successfully obtained the lock. If it failed to obtain the lock,\nyou can assume that another instance of your application is already running with\nthe lock and exit immediately.
\nI.e. This method returns true if your process is the primary instance of your\napplication and your app should continue loading. It returns false if your\nprocess should immediately quit as it has sent its parameters to another\ninstance that has already acquired the lock.
On macOS, the system enforces single instance automatically when users try to open\na second instance of your app in Finder, and the open-file and open-url\nevents will be emitted for that. However when users start your app in command\nline, the system's single instance mechanism will be bypassed, and you have to\nuse this method to ensure single instance.
An example of activating the window of primary instance when a second instance\nstarts:
\nconst { app } = require('electron')\nlet myWindow = null\n\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Someone tried to run a second instance, we should focus our window.\n if (myWindow) {\n if (myWindow.isMinimized()) myWindow.restore()\n myWindow.focus()\n }\n })\n\n // Create myWindow, load the rest of the app, etc...\n app.whenReady().then(() => {\n myWindow = createWindow()\n })\n}\napp.hasSingleInstanceLock()Returns Boolean
This method returns whether or not this instance of your app is currently\nholding the single instance lock. You can request the lock with\napp.requestSingleInstanceLock() and release with\napp.releaseSingleInstanceLock()
app.releaseSingleInstanceLock()Releases all locks that were created by requestSingleInstanceLock. This will\nallow multiple instances of the application to once again run side by side.
app.setUserActivity(type, userInfo[, webpageURL]) macOStype String - Uniquely identifies the activity. Maps to\nNSUserActivity.activityType.userInfo any - App-specific state to store for use by another device.webpageURL String (optional) - The webpage to load in a browser if no suitable app is\ninstalled on the resuming device. The scheme must be http or https.Creates an NSUserActivity and sets it as the current activity. The activity\nis eligible for Handoff to another device afterward.
app.getCurrentActivityType() macOSReturns String - The type of the currently running activity.
app.invalidateCurrentActivity() macOSInvalidates the current Handoff user activity.
\napp.resignCurrentActivity() macOSMarks the current Handoff user activity as inactive without invalidating it.
\napp.updateCurrentActivity(type, userInfo) macOStype String - Uniquely identifies the activity. Maps to\nNSUserActivity.activityType.userInfo any - App-specific state to store for use by another device.Updates the current activity if its type matches type, merging the entries from\nuserInfo into its current userInfo dictionary.
app.setAppUserModelId(id) Windowsid StringChanges the Application User Model ID to id.
app.setActivationPolicy(policy) macOSpolicy String - Can be 'regular', 'accessory', or 'prohibited'.Sets the activation policy for a given app.
\nActivation policy types:
\napp.importCertificate(options, callback) Linuxoptions Objectcertificate String - Path for the pkcs12 file.password String - Passphrase for the certificate.callback Functionresult Integer - Result of import.Imports the certificate in pkcs12 format into the platform certificate store.\ncallback is called with the result of import operation, a value of 0\nindicates success while any other value indicates failure according to Chromium net_error_list.
app.configureHostResolver(options)options ObjectenableBuiltInResolver Boolean (optional) - Whether the built-in host\nresolver is used in preference to getaddrinfo. When enabled, the built-in\nresolver will attempt to use the system's DNS settings to do DNS lookups\nitself. Enabled by default on macOS, disabled by default on Windows and\nLinux.secureDnsMode String (optional) - Can be \"off\", \"automatic\" or \"secure\".\nConfigures the DNS-over-HTTP mode. When \"off\", no DoH lookups will be\nperformed. When \"automatic\", DoH lookups will be performed first if DoH is\navailable, and insecure DNS lookups will be performed as a fallback. When\n\"secure\", only DoH lookups will be performed. Defaults to \"automatic\".secureDnsServers String[] (optional) - A list of DNS-over-HTTP\nserver templates. See RFC8484 § 3 for details on the template format.\nMost servers support the POST method; the template for such servers is\nsimply a URI. Note that for some DNS providers, the\nresolver will automatically upgrade to DoH unless DoH is explicitly\ndisabled, even if there are no DoH servers provided in this list.enableAdditionalDnsQueryTypes Boolean (optional) - Controls whether additional DNS\nquery types, e.g. HTTPS (DNS type 65) will be allowed besides the\ntraditional A and AAAA queries when a request is being made via insecure\nDNS. Has no effect on Secure DNS which always allows additional types.\nDefaults to true.Configures host resolution (DNS and DNS-over-HTTPS). By default, the following\nresolvers will be used, in order:
\ngetaddrinfo).This can be configured to either restrict usage of non-encrypted DNS\n(secureDnsMode: \"secure\"), or disable DNS-over-HTTPS (secureDnsMode: \"off\"). It is also possible to enable or disable the built-in resolver.
To disable insecure DNS, you can specify a secureDnsMode of \"secure\". If you do\nso, you should make sure to provide a list of DNS-over-HTTPS servers to use, in\ncase the user's DNS configuration does not include a provider that supports\nDoH.
app.configureHostResolver({\n secureDnsMode: 'secure',\n secureDnsServers: [\n 'https://cloudflare-dns.com/dns-query'\n ]\n})\nThis API must be called after the ready event is emitted.
app.disableHardwareAcceleration()Disables hardware acceleration for current app.
\nThis method can only be called before app is ready.
\napp.disableDomainBlockingFor3DAPIs()By default, Chromium disables 3D APIs (e.g. WebGL) until restart on a per\ndomain basis if the GPU processes crashes too frequently. This function\ndisables that behavior.
\nThis method can only be called before app is ready.
\napp.getAppMetrics()Returns ProcessMetric[]: Array of ProcessMetric objects that correspond to memory and CPU usage statistics of all the processes associated with the app.
app.getGPUFeatureStatus()Returns GPUFeatureStatus - The Graphics Feature Status from chrome://gpu/.
Note: This information is only usable after the gpu-info-update event is emitted.
app.getGPUInfo(infoType)infoType String - Can be basic or complete.Returns Promise<unknown>
For infoType equal to complete:\nPromise is fulfilled with Object containing all the GPU Information as in chromium's GPUInfo object. This includes the version and driver information that's shown on chrome://gpu page.
For infoType equal to basic:\nPromise is fulfilled with Object containing fewer attributes than when requested with complete. Here's an example of basic response:
{\n auxAttributes:\n {\n amdSwitchable: true,\n canSupportThreadedTextureMailbox: false,\n directComposition: false,\n directRendering: true,\n glResetNotificationStrategy: 0,\n inProcessGpu: true,\n initializationTime: 0,\n jpegDecodeAcceleratorSupported: false,\n optimus: false,\n passthroughCmdDecoder: false,\n sandboxed: false,\n softwareRendering: false,\n supportsOverlays: false,\n videoDecodeAcceleratorFlags: 0\n },\n gpuDevice:\n [{ active: true, deviceId: 26657, vendorId: 4098 },\n { active: false, deviceId: 3366, vendorId: 32902 }],\n machineModelName: 'MacBookPro',\n machineModelVersion: '11.5'\n}\nUsing basic should be preferred if only basic information like vendorId or driverId is needed.
app.setBadgeCount([count]) Linux macOScount Integer (optional) - If a value is provided, set the badge to the provided value otherwise, on macOS, display a plain white dot (e.g. unknown number of notifications). On Linux, if a value is not provided the badge will not display.Returns Boolean - Whether the call succeeded.
Sets the counter badge for current app. Setting the count to 0 will hide the\nbadge.
On macOS, it shows on the dock icon. On Linux, it only works for Unity launcher.
\nNote: Unity launcher requires a .desktop file to work. For more information,\nplease read the Unity integration documentation.
app.getBadgeCount() Linux macOSReturns Integer - The current value displayed in the counter badge.
app.isUnityRunning() LinuxReturns Boolean - Whether the current desktop environment is Unity launcher.
app.getLoginItemSettings([options]) macOS Windowsoptions Object (optional)If you provided path and args options to app.setLoginItemSettings, then you\nneed to pass the same arguments here for openAtLogin to be set correctly.
Returns Object:
openAtLogin Boolean - true if the app is set to open at login.openAsHidden Boolean macOS - true if the app is set to open as hidden at login.\nThis setting is not available on MAS builds.wasOpenedAtLogin Boolean macOS - true if the app was opened at login\nautomatically. This setting is not available on MAS builds.wasOpenedAsHidden Boolean macOS - true if the app was opened as a hidden login\nitem. This indicates that the app should not open any windows at startup.\nThis setting is not available on MAS builds.restoreState Boolean macOS - true if the app was opened as a login item that\nshould restore the state from the previous session. This indicates that the\napp should restore the windows that were open the last time the app was\nclosed. This setting is not available on MAS builds.executableWillLaunchAtLogin Boolean Windows - true if app is set to open at login and its run key is not deactivated. This differs from openAtLogin as it ignores the args option, this property will be true if the given executable would be launched at login with any arguments.launchItems Object[] Windowsname String Windows - name value of a registry entry.path String Windows - The executable to an app that corresponds to a registry entry.args String[] Windows - the command-line arguments to pass to the executable.scope String Windows - one of user or machine. Indicates whether the registry entry is under HKEY_CURRENT USER or HKEY_LOCAL_MACHINE.enabled Boolean Windows - true if the app registry key is startup approved and therefore shows as enabled in Task Manager and Windows settings.app.setLoginItemSettings(settings) macOS Windowssettings ObjectopenAtLogin Boolean (optional) - true to open the app at login, false to remove\nthe app as a login item. Defaults to false.openAsHidden Boolean (optional) macOS - true to open the app as hidden. Defaults to\nfalse. The user can edit this setting from the System Preferences so\napp.getLoginItemSettings().wasOpenedAsHidden should be checked when the app\nis opened to know the current value. This setting is not available on MAS builds.path String (optional) Windows - The executable to launch at login.\nDefaults to process.execPath.args String Windows - The command-line arguments to pass to\nthe executable. Defaults to an empty array. Take care to wrap paths in\nquotes.enabled Boolean (optional) Windows - true will change the startup approved registry key and enable / disable the App in Task Manager and Windows Settings.\nDefaults to true.name String (optional) Windows - value name to write into registry. Defaults to the app's AppUserModelId().\nSet the app's login item settings.To work with Electron's autoUpdater on Windows, which uses Squirrel,\nyou'll want to set the launch path to Update.exe, and pass arguments that specify your\napplication name. For example:
const appFolder = path.dirname(process.execPath)\nconst updateExe = path.resolve(appFolder, '..', 'Update.exe')\nconst exeName = path.basename(process.execPath)\n\napp.setLoginItemSettings({\n openAtLogin: true,\n path: updateExe,\n args: [\n '--processStart', `\"${exeName}\"`,\n '--process-start-args', `\"--hidden\"`\n ]\n})\napp.isAccessibilitySupportEnabled() macOS WindowsReturns Boolean - true if Chrome's accessibility support is enabled,\nfalse otherwise. This API will return true if the use of assistive\ntechnologies, such as screen readers, has been detected. See\nhttps://www.chromium.org/developers/design-documents/accessibility for more\ndetails.
app.setAccessibilitySupportEnabled(enabled) macOS Windowsenabled Boolean - Enable or disable accessibility tree renderingManually enables Chrome's accessibility support, allowing to expose accessibility switch to users in application settings. See Chromium's accessibility docs for more\ndetails. Disabled by default.
\nThis API must be called after the ready event is emitted.
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
\napp.showAboutPanel()Show the app's about panel options. These options can be overridden with app.setAboutPanelOptions(options).
app.setAboutPanelOptions(options)options ObjectapplicationName String (optional) - The app's name.applicationVersion String (optional) - The app's version.copyright String (optional) - Copyright information.version String (optional) macOS - The app's build version number.credits String (optional) macOS Windows - Credit information.authors String Linux - List of app authors.website String (optional) Linux - The app's website.iconPath String (optional) Linux Windows - Path to the app's icon in a JPEG or PNG file format. On Linux, will be shown as 64x64 pixels while retaining aspect ratio.Set the about panel options. This will override the values defined in the app's .plist file on macOS. See the Apple docs for more details. On Linux, values must be set in order to be shown; there are no defaults.
If you do not set credits but still wish to surface them in your app, AppKit will look for a file named \"Credits.html\", \"Credits.rtf\", and \"Credits.rtfd\", in that order, in the bundle returned by the NSBundle class method main. The first file found is used, and if none is found, the info area is left blank. See Apple documentation for more information.
app.isEmojiPanelSupported()Returns Boolean - whether or not the current OS version allows for native emoji pickers.
app.showEmojiPanel() macOS WindowsShow the platform's native emoji picker.
\napp.startAccessingSecurityScopedResource(bookmarkData) masbookmarkData String - The base64 encoded security scoped bookmark data returned by the dialog.showOpenDialog or dialog.showSaveDialog methods.Returns Function - This function must be called once you have finished accessing the security scoped file. If you do not remember to stop accessing the bookmark, kernel resources will be leaked and your app will lose its ability to reach outside the sandbox completely, until your app is restarted.
// Start accessing the file.\nconst stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)\n// You can now access the file outside of the sandbox 🎉\n\n// Remember to stop accessing the file once you've finished with it.\nstopAccessingSecurityScopedResource()\nStart accessing a security scoped resource. With this method Electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See Apple's documentation for a description of how this system works.
\napp.enableSandbox()Enables full sandbox mode on the app. This means that all renderers will be launched sandboxed, regardless of the value of the sandbox flag in WebPreferences.
This method can only be called before app is ready.
\napp.isInApplicationsFolder() macOSReturns Boolean - Whether the application is currently running from the\nsystems Application folder. Use in combination with app.moveToApplicationsFolder()
app.moveToApplicationsFolder([options]) macOSoptions Object (optional)conflictHandler Function\\conflictType String - The type of move conflict encountered by the handler; can be exists or existsAndRunning, where exists means that an app of the same name is present in the Applications directory and existsAndRunning means both that it exists and that it's presently running.Returns Boolean - Whether the move was successful. Please note that if\nthe move is successful, your application will quit and relaunch.
No confirmation dialog will be presented by default. If you wish to allow\nthe user to confirm the operation, you may do so using the\ndialog API.
NOTE: This method throws errors if anything other than the user causes the\nmove to fail. For instance if the user cancels the authorization dialog, this\nmethod returns false. If we fail to perform the copy, then this method will\nthrow an error. The message in the error should be informative and tell\nyou exactly what went wrong.
\nBy default, if an app of the same name as the one being moved exists in the Applications directory and is not running, the existing app will be trashed and the active app moved into its place. If it is running, the pre-existing running app will assume focus and the previously active app will quit itself. This behavior can be changed by providing the optional conflict handler, where the boolean returned by the handler determines whether or not the move conflict is resolved with default behavior. i.e. returning false will ensure no further action is taken, returning true will result in the default behavior and the method continuing.
For example:
\napp.moveToApplicationsFolder({\n conflictHandler: (conflictType) => {\n if (conflictType === 'exists') {\n return dialog.showMessageBoxSync({\n type: 'question',\n buttons: ['Halt Move', 'Continue Move'],\n defaultId: 0,\n message: 'An app of this name already exists'\n }) === 1\n }\n }\n})\nWould mean that if an app already exists in the user directory, if the user chooses to 'Continue Move' then the function would continue with its default behavior and the existing app will be trashed and the active app moved into its place.
\napp.isSecureKeyboardEntryEnabled() macOSReturns Boolean - whether Secure Keyboard Entry is enabled.
By default this API will return false.
app.setSecureKeyboardEntryEnabled(enabled) macOSenabled Boolean - Enable or disable Secure Keyboard EntrySet the Secure Keyboard Entry is enabled in your application.
By using this API, important information such as password and other sensitive information can be prevented from being intercepted by other processes.
\nSee Apple's documentation for more\ndetails.
\nNote: Enable Secure Keyboard Entry only when it is needed and disable it when it is no longer needed.
app.accessibilitySupportEnabled macOS WindowsA Boolean property that's true if Chrome's accessibility support is enabled, false otherwise. This property will be true if the use of assistive technologies, such as screen readers, has been detected. Setting this property to true manually enables Chrome's accessibility support, allowing developers to expose accessibility switch to users in application settings.
See Chromium's accessibility docs for more details. Disabled by default.
\nThis API must be called after the ready event is emitted.
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
\napp.applicationMenuA Menu | null property that returns Menu if one has been set and null otherwise.\nUsers can pass a Menu to set this property.
app.badgeCount Linux macOSAn Integer property that returns the badge count for current app. Setting the count to 0 will hide the badge.
On macOS, setting this with any nonzero integer shows on the dock icon. On Linux, this property only works for Unity launcher.
\nNote: Unity launcher requires a .desktop file to work. For more information,\nplease read the Unity integration documentation.
Note: On macOS, you need to ensure that your application has the permission\nto display notifications for this property to take effect.
\napp.commandLine ReadonlyA CommandLine object that allows you to read and manipulate the\ncommand line arguments that Chromium uses.
app.dock macOS ReadonlyA Dock | undefined object that allows you to perform actions on your app icon in the user's\ndock on macOS.
app.isPackaged ReadonlyA Boolean property that returns true if the app is packaged, false otherwise. For many apps, this property can be used to distinguish development and production environments.
app.nameA String property that indicates the current application's name, which is the name in the application's package.json file.
Usually the name field of package.json is a short lowercase name, according\nto the npm modules spec. You should usually also specify a productName\nfield, which is your application's full capitalized name, and which will be\npreferred over name by Electron.
app.userAgentFallbackA String which is the user agent string Electron will use as a global fallback.
This is the user agent that will be used when no user agent is set at the\nwebContents or session level. It is useful for ensuring that your entire\napp has the same user agent. Set to a custom value as early as possible\nin your app's initialization to ensure that your overridden value is used.
app.runningUnderRosettaTranslation macOS Readonly DeprecatedA Boolean which when true indicates that the app is currently running\nunder the Rosetta Translator Environment.
You can use this property to prompt users to download the arm64 version of\nyour application when they are running the x64 version under Rosetta\nincorrectly.
\nDeprecated: This property is superceded by the runningUnderARM64Translation\nproperty which detects when the app is being translated to ARM64 in both macOS\nand Windows.
app.runningUnderARM64Translation Readonly macOS WindowsA Boolean which when true indicates that the app is currently running under\nan ARM64 translator (like the macOS\nRosetta Translator Environment\nor Windows WOW).
You can use this property to prompt users to download the arm64 version of\nyour application when they are running the x64 version under Rosetta\nincorrectly.
", "title": "app", "description": "Control your application's event lifecycle." }, "/docs/tutorial/application-debugging": { "locale": "en-US", "slug": "application-debugging", "href": "/docs/tutorial/application-debugging", "crowdinFileId": "256175", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/application-debugging.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Whenever your Electron application is not behaving the way you wanted it to,\nan array of debugging tools might help you find coding errors, performance\nbottlenecks, or optimization opportunities.
\nThe most comprehensive tool to debug individual renderer processes is the\nChromium Developer Toolset. It is available for all renderer processes,\nincluding instances of BrowserWindow, BrowserView, and WebView. You\ncan open them programmatically by calling the openDevTools() API on the\nwebContents of the instance:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.webContents.openDevTools()\nGoogle offers excellent documentation for their developer tools.\nWe recommend that you make yourself familiar with them - they are usually one\nof the most powerful utilities in any Electron Developer's tool belt.
\nDebugging the main process is a bit trickier, since you cannot open\ndeveloper tools for them. The Chromium Developer Tools can be used\nto debug Electron's main process thanks to a closer collaboration\nbetween Google / Chrome and Node.js, but you might encounter oddities like\nrequire not being present in the console.
For more information, see the Debugging the Main Process documentation.
\nIf the V8 context crashes, the DevTools will display this message.
\nDevTools was disconnected from the page. Once page is reloaded, DevTools will automatically reconnect.
Chromium logs can be enabled via the ELECTRON_ENABLE_LOGGING environment variable. For more information, see the environment variables documentation.
Alternatively, the command line argument --enable-logging can be passed. More information is available in the command line switches documentation.
To distribute your app with Electron, you need to package and rebrand it.\nTo do this, you can either use specialized tooling or manual approaches.
\nYou can use the following tools to distribute your application:
\n\nThese tools will take care of all the steps you need to take to end up with a\ndistributable Electron application, such as bundling your application,\nrebranding the executable, and setting the right icons.
\nYou can check the example of how to package your app with electron-forge in\nthe Quick Start guide.
To distribute your app manually, you need to download Electron's prebuilt\nbinaries. Next, the folder\ncontaining your app should be named app and placed in Electron's resources\ndirectory as shown in the following examples.
\n\nNOTE: the location of Electron's prebuilt binaries is indicated\nwith
\nelectron/in the examples below.
On macOS:
\nelectron/Electron.app/Contents/Resources/app/\n├── package.json\n├── main.js\n└── index.html\nOn Windows and Linux:
\nelectron/resources/app\n├── package.json\n├── main.js\n└── index.html\nThen execute Electron.app on macOS, electron on Linux, or electron.exe\non Windows, and Electron will start as your app. The electron directory\nwill then be your distribution to deliver to users.
Instead of from shipping your app by copying all of its source files, you can\npackage your app into an asar archive to improve the performance of reading\nfiles on platforms like Windows, if you are not already using a bundler such\nas Parcel or Webpack.
\nTo use an asar archive to replace the app folder, you need to rename the\narchive to app.asar, and put it under Electron's resources directory like\nbelow, and Electron will then try to read the archive and start from it.
On macOS:
\nelectron/Electron.app/Contents/Resources/\n└── app.asar\nOn Windows and Linux:
\nelectron/resources/\n└── app.asar\nYou can find more details on how to use asar in the\nelectron/asar repository.
After bundling your app into Electron, you will want to rebrand Electron\nbefore distributing it to users.
\nYou can rename Electron.app to any name you want, and you also have to rename\nthe CFBundleDisplayName, CFBundleIdentifier and CFBundleName fields in the\nfollowing files:
Electron.app/Contents/Info.plistElectron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plistYou can also rename the helper app to avoid showing Electron Helper in the\nActivity Monitor, but make sure you have renamed the helper app's executable\nfile's name.
The structure of a renamed app would be like:
\nMyApp.app/Contents\n├── Info.plist\n├── MacOS/\n│ └── MyApp\n└── Frameworks/\n └── MyApp Helper.app\n ├── Info.plist\n └── MacOS/\n └── MyApp Helper\nYou can rename electron.exe to any name you like, and edit its icon and other\ninformation with tools like rcedit.
You can rename the electron executable to any name you like.
It is also possible to rebrand Electron by changing the product name and\nbuilding it from source. To do this you need to set the build argument\ncorresponding to the product name (electron_product_name = \"YourProductName\")\nin the args.gn file and rebuild.
\n\nEnable apps to automatically update themselves.
\n
Process: Main
\nSee also: A detailed guide about how to implement updates in your application.
\nautoUpdater is an EventEmitter.
Currently, only macOS and Windows are supported. There is no built-in support\nfor auto-updater on Linux, so it is recommended to use the\ndistribution's package manager to update your app.
\nIn addition, there are some subtle differences on each platform:
\nOn macOS, the autoUpdater module is built upon Squirrel.Mac,\nmeaning you don't need any special setup to make it work. For server-side\nrequirements, you can read Server Support. Note that App\nTransport Security (ATS) applies to all requests made as part of the\nupdate process. Apps that need to disable ATS can add the\nNSAllowsArbitraryLoads key to their app's plist.
Note: Your application must be signed for automatic updates on macOS.\nThis is a requirement of Squirrel.Mac.
On Windows, you have to install your app into a user's machine before you can\nuse the autoUpdater, so it is recommended that you use the\nelectron-winstaller, electron-forge or the grunt-electron-installer package to generate a Windows installer.
When using electron-winstaller or electron-forge make sure you do not try to update your app the first time it runs (Also see this issue for more info). It's also recommended to use electron-squirrel-startup to get desktop shortcuts for your app.
\nThe installer generated with Squirrel will create a shortcut icon with an\nApplication User Model ID in the format of\ncom.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE, examples are\ncom.squirrel.slack.Slack and com.squirrel.code.Code. You have to use the\nsame ID for your app with app.setAppUserModelId API, otherwise Windows will\nnot be able to pin your app properly in task bar.
Like Squirrel.Mac, Windows can host updates on S3 or any other static file host.\nYou can read the documents of Squirrel.Windows to get more details\nabout how Squirrel.Windows works.
\nThe autoUpdater object emits the following events:
Returns:
\nerror ErrorEmitted when there is an error while updating.
\nEmitted when checking if an update has started.
\nEmitted when there is an available update. The update is downloaded\nautomatically.
\nEmitted when there is no available update.
\nReturns:
\nevent EventreleaseNotes StringreleaseName StringreleaseDate DateupdateURL StringEmitted when an update has been downloaded.
\nOn Windows only releaseName is available.
Note: It is not strictly necessary to handle this event. A successfully\ndownloaded update will still be applied the next time the application starts.
\nThis event is emitted after a user calls quitAndInstall().
When this API is called, the before-quit event is not emitted before all windows are closed. As a result you should listen to this event if you wish to perform actions before the windows are closed while a process is quitting, as well as listening to before-quit.
The autoUpdater object has the following methods:
autoUpdater.setFeedURL(options)options Objecturl Stringheaders Record<String, String> (optional) macOS - HTTP request headers.serverType String (optional) macOS - Can be json or default, see the Squirrel.Mac\nREADME for more information.Sets the url and initialize the auto updater.
autoUpdater.getFeedURL()Returns String - The current update feed URL.
autoUpdater.checkForUpdates()Asks the server whether there is an update. You must call setFeedURL before\nusing this API.
Note: If an update is available it will be downloaded automatically.\nCalling autoUpdater.checkForUpdates() twice will download the update two times.
autoUpdater.quitAndInstall()Restarts the app and installs the update after it has been downloaded. It\nshould only be called after update-downloaded has been emitted.
Under the hood calling autoUpdater.quitAndInstall() will close all application\nwindows first, and automatically call app.quit() after all windows have been\nclosed.
Note: It is not strictly necessary to call this function to apply an update,\nas a successfully downloaded update will always be applied the next time the\napplication starts.
", "title": "autoUpdater", "description": "Enable apps to automatically update themselves." }, "/docs/tutorial/automated-testing-with-a-custom-driver": { "locale": "en-US", "slug": "automated-testing-with-a-custom-driver", "href": "/docs/tutorial/automated-testing-with-a-custom-driver", "crowdinFileId": "256179", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/automated-testing-with-a-custom-driver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "To write automated tests for your Electron app, you will need a way to \"drive\" your application. Spectron is a commonly-used solution which lets you emulate user actions via WebDriver. However, it's also possible to write your own custom driver using node's builtin IPC-over-STDIO. The benefit of a custom driver is that it tends to require less overhead than Spectron, and lets you expose custom methods to your test suite.
\nTo create a custom driver, we'll use Node.js' child_process API. The test suite will spawn the Electron process, then establish a simple messaging protocol:
\nconst childProcess = require('child_process')\nconst electronPath = require('electron')\n\n// spawn the process\nconst env = { /* ... */ }\nconst stdio = ['inherit', 'inherit', 'inherit', 'ipc']\nconst appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })\n\n// listen for IPC messages from the app\nappProcess.on('message', (msg) => {\n // ...\n})\n\n// send an IPC message to the app\nappProcess.send({ my: 'message' })\nFrom within the Electron app, you can listen for messages and send replies using the Node.js process API:
\n// listen for IPC messages from the test suite\nprocess.on('message', (msg) => {\n // ...\n})\n\n// send an IPC message to the test suite\nprocess.send({ my: 'message' })\nWe can now communicate from the test suite to the Electron app using the appProcess object.
For convenience, you may want to wrap appProcess in a driver object that provides more high-level functions. Here is an example of how you can do this:
class TestDriver {\n constructor ({ path, args, env }) {\n this.rpcCalls = []\n\n // start child process\n env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages\n this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })\n\n // handle rpc responses\n this.process.on('message', (message) => {\n // pop the handler\n const rpcCall = this.rpcCalls[message.msgId]\n if (!rpcCall) return\n this.rpcCalls[message.msgId] = null\n // reject/resolve\n if (message.reject) rpcCall.reject(message.reject)\n else rpcCall.resolve(message.resolve)\n })\n\n // wait for ready\n this.isReady = this.rpc('isReady').catch((err) => {\n console.error('Application failed to start', err)\n this.stop()\n process.exit(1)\n })\n }\n\n // simple RPC call\n // to use: driver.rpc('method', 1, 2, 3).then(...)\n async rpc (cmd, ...args) {\n // send rpc request\n const msgId = this.rpcCalls.length\n this.process.send({ msgId, cmd, args })\n return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))\n }\n\n stop () {\n this.process.kill()\n }\n}\nIn the app, you'd need to write a simple handler for the RPC calls:
\nif (process.env.APP_TEST_DRIVER) {\n process.on('message', onMessage)\n}\n\nasync function onMessage ({ msgId, cmd, args }) {\n let method = METHODS[cmd]\n if (!method) method = () => new Error('Invalid method: ' + cmd)\n try {\n const resolve = await method(...args)\n process.send({ msgId, resolve })\n } catch (err) {\n const reject = {\n message: err.message,\n stack: err.stack,\n name: err.name\n }\n process.send({ msgId, reject })\n }\n}\n\nconst METHODS = {\n isReady () {\n // do any setup needed\n return true\n }\n // define your RPC-able methods here\n}\nThen, in your test suite, you can use your test-driver as follows:
\nconst test = require('ava')\nconst electronPath = require('electron')\n\nconst app = new TestDriver({\n path: electronPath,\n args: ['./app'],\n env: {\n NODE_ENV: 'test'\n }\n})\ntest.before(async t => {\n await app.isReady\n})\ntest.after.always('cleanup', async t => {\n await app.stop()\n})\nElectron CI on Windows uses AppVeyor, which in turn uses Azure VM images to run. Occasionally, these VM images need to be updated due to changes in Chromium requirements. In order to update you will need PowerShell and the Azure PowerShell module.
\nOccasionally we need to update these images owing to changes in Chromium or other miscellaneous build requirement changes.
\nExample Use Case:\n* We need VS15.9 and we have VS15.7 installed; this would require us to update an Azure image.
Identify the image you wish to modify.
\nGet the Azure storage account key
\nappveyorlibccbuilds Disk Storage Account Name you'd look for appveyorlibccbuilds in the list of storage accounts @ Home < Storage AccountsAccess Keys, and then you can use any of the keys present in the list.Get the full virtual machine image URI from Azure
\n$ACCT_NAME < Blobs < ImagesCopy the image using the Copy Master Image PowerShell script.
\n(images)libcc-20core-vs2017-15.9-2019-04-15.vhdSpin up a new VM using the Create Master VM from VHD PowerShell.
\nps1 file with ./create_master_vm_from_vhd.ps1Standard_F32s_v2East USLog back into Azure and find the VM you just created in Home < Virtual Machines < $YOUR_NEW_VM
Using Microsoft Remote Desktop, click Connect to connect to the VM.
AppVeyor Enterprise master VM credentials.Modify the VM as required.
\nShut down the VM and then delete it in Azure.
\nAdd the new image to the Appveyor Cloud settings or modify an existing image to point to the new VHD.
\ndeviceName StringdeviceId StringElectron development is unopinionated - there is no \"one true way\" to develop,\nbuild, package, or release an Electron application. Additional features for\nElectron, both for build- and run-time, can usually be found on\nnpm in individual packages, allowing developers to build both\nthe app and build pipeline they need.
\nThat level of modularity and extendability ensures that all developers working\nwith Electron, both big and small in team-size, are never restricted in what\nthey can or cannot do at any time during their development lifecycle. However,\nfor many developers, one of the community-driven boilerplates or command line\ntools might make it dramatically easier to compile, package, and release an\napp.
\nA boilerplate is only a starting point - a canvas, so to speak - from which\nyou build your application. They usually come in the form of a repository you\ncan clone and customize to your heart's content.
\nA command line tool on the other hand continues to support you throughout the\ndevelopment and release. They are more helpful and supportive but enforce\nguidelines on how your code should be structured and built. Especially for\nbeginners, using a command line tool is likely to be helpful.
\nA \"complete tool for building modern Electron applications\". Electron Forge\nunifies the existing (and well maintained) build tools for Electron development\ninto a cohesive package so that anyone can jump right in to Electron\ndevelopment.
\nForge comes with a ready-to-use template using Webpack as a bundler. It includes an example typescript configuration and provides two configuration files to enable easy customization. It uses the same core modules used by the\ngreater Electron community (like electron-packager) –\nchanges made by Electron maintainers (like Slack) benefit Forge's users, too.
You can find more information and documentation on electronforge.io.
\nA \"complete solution to package and build a ready-for-distribution Electron app\"\nthat focuses on an integrated experience. electron-builder adds one\nsingle dependency focused on simplicity and manages all further requirements\ninternally.
electron-builder replaces features and modules used by the Electron\nmaintainers (such as the auto-updater) with custom ones. They are generally\ntighter integrated but will have less in common with popular Electron apps\nlike Atom, Visual Studio Code, or Slack.
You can find more information and documentation in the repository.
\nIf you don't want any tools but only a solid boilerplate to build from,\nCT Lin's electron-react-boilerplate might be worth\na look. It's quite popular in the community and uses electron-builder\ninternally.
The \"Awesome Electron\" list contains more tools and boilerplates\nto choose from. If you find the length of the list intimidating, don't\nforget that adding tools as you go along is a valid approach, too.
", "title": "Boilerplates and CLIs", "description": "" }, "/docs/breaking-changes": { "locale": "en-US", "slug": "breaking-changes", "href": "/docs/breaking-changes", "crowdinFileId": "256117", "githubUrl": "https://github.com/electron/electron/tree/main/docs/breaking-changes.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least one major version before the change is made.
\nThis document uses the following convention to categorize breaking changes:
\nremote moduleThe remote module was deprecated in Electron 12, and will be removed in\nElectron 14. It is replaced by the\n@electron/remote module.
// Deprecated in Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// Replace with:\nconst { BrowserWindow } = require('@electron/remote')\n\n// In the main process:\nrequire('@electron/remote/main').initialize()\napp.allowRendererProcessReuseThe app.allowRendererProcessReuse property will be removed as part of our plan to\nmore closely align with Chromium's process model for security, performance and maintainability.
For more detailed information see #18397.
\nThe affinity option when constructing a new BrowserWindow will be removed\nas part of our plan to more closely align with Chromium's process model for security,\nperformance and maintainability.
For more detailed information see #18397.
\nwindow.open()The optional parameter frameName will no longer set the title of the window. This now follows the specification described by the native documentation under the corresponding parameter windowName.
If you were using this parameter to set the title of a window, you can instead use win.setTitle(title).
\nworldSafeExecuteJavaScriptIn Electron 14, worldSafeExecuteJavaScript will be removed. There is no alternative, please\nensure your code works with this property enabled. It has been enabled by default since Electron\n12.
You will be affected by this change if you use either webFrame.executeJavaScript or webFrame.executeJavaScriptInIsolatedWorld. You will need to ensure that values returned by either of those methods are supported by the Context Bridge API as these methods use the same value passing semantics.
nativeWindowOpen defaults to truePrior to Electron 14, window.open was by default shimmed to use\nBrowserWindowProxy. This meant that window.open('about:blank') did not work\nto open synchronously scriptable child windows, among other incompatibilities.\nnativeWindowOpen is no longer experimental, and is now the default.
See the documentation for window.open in Electron\nfor more details.
\nPrior to Electron 14, windows opened with window.open would inherit\nBrowserWindow constructor options such as transparent and resizable from\ntheir parent window. Beginning with Electron 14, this behavior is removed, and\nwindows will not inherit any BrowserWindow constructor options from their\nparents.
Instead, explicitly set options for the new window with setWindowOpenHandler:
webContents.setWindowOpenHandler((details) => {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n // ...\n }\n }\n})\nadditionalFeaturesThe deprecated additionalFeatures property in the new-window and\ndid-create-window events of WebContents has been removed. Since new-window\nuses positional arguments, the argument is still present, but will always be\nthe empty array []. (Though note, the new-window event itself is\ndeprecated, and is replaced by setWindowOpenHandler.) Bare keys in window\nfeatures will now present as keys with the value true in the options object.
// Removed in Electron 14\n// Triggered by window.open('...', '', 'my-key')\nwebContents.on('did-create-window', (window, details) => {\n if (details.additionalFeatures.includes('my-key')) {\n // ...\n }\n})\n\n// Replace with\nwebContents.on('did-create-window', (window, details) => {\n if (details.options['my-key']) {\n // ...\n }\n})\nsession.setPermissionCheckHandler(handler)The handler methods first parameter was previously always a webContents, it can now sometimes be null. You should use the requestingOrigin, embeddingOrigin and securityOrigin properties to respond to the permission check correctly. As the webContents can be null it can no longer be relied on.
// Old code\nsession.setPermissionCheckHandler((webContents, permission) => {\n if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {\n return true\n }\n return false\n})\n\n// Replace with\nsession.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {\n return true\n }\n return false\n})\nshell.moveItemToTrash()The deprecated synchronous shell.moveItemToTrash() API has been removed. Use\nthe asynchronous shell.trashItem() instead.
// Removed in Electron 13\nshell.moveItemToTrash(path)\n// Replace with\nshell.trashItem(path).then(/* ... */)\nBrowserWindow extension APIsThe deprecated extension APIs have been removed:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()Use the session APIs instead:
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Removed in Electron 13\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Replace with\nsession.defaultSession.loadExtension(path)\n// Removed in Electron 13\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// Replace with\nsession.defaultSession.removeExtension(extension_id)\n// Removed in Electron 13\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Replace with\nsession.defaultSession.getAllExtensions()\nsystemPreferencesThe following systemPreferences methods have been deprecated:
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()Use the following nativeTheme properties instead:
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Removed in Electron 13\nsystemPreferences.isDarkMode()\n// Replace with\nnativeTheme.shouldUseDarkColors\n\n// Removed in Electron 13\nsystemPreferences.isInvertedColorScheme()\n// Replace with\nnativeTheme.shouldUseInvertedColorScheme\n\n// Removed in Electron 13\nsystemPreferences.isHighContrastColorScheme()\n// Replace with\nnativeTheme.shouldUseHighContrastColors\nnew-window eventThe new-window event of WebContents has been deprecated. It is replaced by webContents.setWindowOpenHandler().
// Deprecated in Electron 13\nwebContents.on('new-window', (event) => {\n event.preventDefault()\n})\n\n// Replace with\nwebContents.setWindowOpenHandler((details) => {\n return { action: 'deny' }\n})\nChromium has removed support for Flash, and so we must follow suit. See\nChromium's Flash Roadmap for more\ndetails.
\nworldSafeExecuteJavaScript defaults to trueIn Electron 12, worldSafeExecuteJavaScript will be enabled by default. To restore\nthe previous behavior, worldSafeExecuteJavaScript: false must be specified in WebPreferences.\nPlease note that setting this option to false is insecure.
This option will be removed in Electron 14 so please migrate your code to support the default\nvalue.
\ncontextIsolation defaults to trueIn Electron 12, contextIsolation will be enabled by default. To restore\nthe previous behavior, contextIsolation: false must be specified in WebPreferences.
We recommend having contextIsolation enabled for the security of your application.
\nAnother implication is that require() cannot be used in the renderer process unless\nnodeIntegration is true and contextIsolation is false.
For more details see: https://github.com/electron/electron/issues/23506
\ncrashReporter.getCrashesDirectory()The crashReporter.getCrashesDirectory method has been removed. Usage\nshould be replaced by app.getPath('crashDumps').
// Removed in Electron 12\ncrashReporter.getCrashesDirectory()\n// Replace with\napp.getPath('crashDumps')\ncrashReporter methods in the renderer processThe following crashReporter methods are no longer available in the renderer\nprocess:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryThey should be called only from the main process.
\nSee #23265 for more details.
\ncrashReporter.start({ compress: true })The default value of the compress option to crashReporter.start has changed\nfrom false to true. This means that crash dumps will be uploaded to the\ncrash ingestion server with the Content-Encoding: gzip header, and the body\nwill be compressed.
If your crash ingestion server does not support compressed payloads, you can\nturn off compression by specifying { compress: false } in the crash reporter\noptions.
remote moduleThe remote module is deprecated in Electron 12, and will be removed in\nElectron 14. It is replaced by the\n@electron/remote module.
// Deprecated in Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// Replace with:\nconst { BrowserWindow } = require('@electron/remote')\n\n// In the main process:\nrequire('@electron/remote/main').initialize()\nshell.moveItemToTrash()The synchronous shell.moveItemToTrash() has been replaced by the new,\nasynchronous shell.trashItem().
// Deprecated in Electron 12\nshell.moveItemToTrash(path)\n// Replace with\nshell.trashItem(path).then(/* ... */)\nBrowserView.{destroy, fromId, fromWebContents, getAllViews} and id property of BrowserViewThe experimental APIs BrowserView.{destroy, fromId, fromWebContents, getAllViews}\nhave now been removed. Additionally, the id property of BrowserView\nhas also been removed.
For more detailed information, see #23578.
\ncompanyName argument to crashReporter.start()The companyName argument to crashReporter.start(), which was previously\nrequired, is now optional, and further, is deprecated. To get the same\nbehavior in a non-deprecated way, you can pass a companyName value in\nglobalExtra.
// Deprecated in Electron 10\ncrashReporter.start({ companyName: 'Umbrella Corporation' })\n// Replace with\ncrashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })\ncrashReporter.getCrashesDirectory()The crashReporter.getCrashesDirectory method has been deprecated. Usage\nshould be replaced by app.getPath('crashDumps').
// Deprecated in Electron 10\ncrashReporter.getCrashesDirectory()\n// Replace with\napp.getPath('crashDumps')\ncrashReporter methods in the renderer processCalling the following crashReporter methods from the renderer process is\ndeprecated:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryThe only non-deprecated methods remaining in the crashReporter module in the\nrenderer are addExtraParameter, removeExtraParameter and getParameters.
All above methods remain non-deprecated when called from the main process.
\nSee #23265 for more details.
\ncrashReporter.start({ compress: false })Setting { compress: false } in crashReporter.start is deprecated. Nearly\nall crash ingestion servers support gzip compression. This option will be\nremoved in a future version of Electron.
enableRemoteModule defaults to falseIn Electron 9, using the remote module without explicitly enabling it via the\nenableRemoteModule WebPreferences option began emitting a warning. In\nElectron 10, the remote module is now disabled by default. To use the remote\nmodule, enableRemoteModule: true must be specified in WebPreferences:
const w = new BrowserWindow({\n webPreferences: {\n enableRemoteModule: true\n }\n})\nWe recommend moving away from the remote\nmodule.
\nprotocol.unregisterProtocolprotocol.uninterceptProtocolThe APIs are now synchronous and the optional callback is no longer needed.
\n// Deprecated\nprotocol.unregisterProtocol(scheme, () => { /* ... */ })\n// Replace with\nprotocol.unregisterProtocol(scheme)\nprotocol.registerFileProtocolprotocol.registerBufferProtocolprotocol.registerStringProtocolprotocol.registerHttpProtocolprotocol.registerStreamProtocolprotocol.interceptFileProtocolprotocol.interceptStringProtocolprotocol.interceptBufferProtocolprotocol.interceptHttpProtocolprotocol.interceptStreamProtocolThe APIs are now synchronous and the optional callback is no longer needed.
\n// Deprecated\nprotocol.registerFileProtocol(scheme, handler, () => { /* ... */ })\n// Replace with\nprotocol.registerFileProtocol(scheme, handler)\nThe registered or intercepted protocol does not have effect on current page\nuntil navigation happens.
\nprotocol.isProtocolHandledThis API is deprecated and users should use protocol.isProtocolRegistered\nand protocol.isProtocolIntercepted instead.
// Deprecated\nprotocol.isProtocolHandled(scheme).then(() => { /* ... */ })\n// Replace with\nconst isRegistered = protocol.isProtocolRegistered(scheme)\nconst isIntercepted = protocol.isProtocolIntercepted(scheme)\nAs of Electron 9 we do not allow loading of non-context-aware native modules in\nthe renderer process. This is to improve security, performance and maintainability\nof Electron as a project.
\nIf this impacts you, you can temporarily set app.allowRendererProcessReuse to false\nto revert to the old behavior. This flag will only be an option until Electron 11 so\nyou should plan to update your native modules to be context aware.
For more detailed information see #18397.
\nBrowserWindow extension APIsThe following extension APIs have been deprecated:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()Use the session APIs instead:
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Deprecated in Electron 9\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Replace with\nsession.defaultSession.loadExtension(path)\n// Deprecated in Electron 9\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// Replace with\nsession.defaultSession.removeExtension(extension_id)\n// Deprecated in Electron 9\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Replace with\nsession.defaultSession.getAllExtensions()\n<webview>.getWebContents()This API, which was deprecated in Electron 8.0, is now removed.
\n// Removed in Electron 9.0\nwebview.getWebContents()\n// Replace with\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium has removed support for changing the layout zoom level limits, and it\nis beyond Electron's capacity to maintain it. The function was deprecated in\nElectron 8.x, and has been removed in Electron 9.x. The layout zoom level limits\nare now fixed at a minimum of 0.25 and a maximum of 5.0, as defined\nhere.
\nIn Electron 8.0, IPC was changed to use the Structured Clone Algorithm,\nbringing significant performance improvements. To help ease the transition, the\nold IPC serialization algorithm was kept and used for some objects that aren't\nserializable with Structured Clone. In particular, DOM objects (e.g. Element,\nLocation and DOMMatrix), Node.js objects backed by C++ classes (e.g.\nprocess.env, some members of Stream), and Electron objects backed by C++\nclasses (e.g. WebContents, BrowserWindow and WebFrame) are not\nserializable with Structured Clone. Whenever the old algorithm was invoked, a\ndeprecation warning was printed.
In Electron 9.0, the old serialization algorithm has been removed, and sending\nsuch non-serializable objects will now throw an \"object could not be cloned\"\nerror.
\nshell.openItem is now shell.openPathThe shell.openItem API has been replaced with an asynchronous shell.openPath API.\nYou can see the original API proposal and reasoning here.
The algorithm used to serialize objects sent over IPC (through\nipcRenderer.send, ipcRenderer.sendSync, WebContents.send and related\nmethods) has been switched from a custom algorithm to V8's built-in Structured\nClone Algorithm, the same algorithm used to serialize messages for\npostMessage. This brings about a 2x performance improvement for large\nmessages, but also brings some breaking changes in behavior.
undefined.// Previously:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => results in { value: 3 } arriving in the main process\n\n// From Electron 8:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => throws Error(\"() => {} could not be cloned.\")\nNaN, Infinity and -Infinity will now be correctly serialized, instead\nof being converted to null.null.Set, Map, Error and RegExp values will be correctly serialized,\ninstead of being converted to {}.BigInt values will be correctly serialized, instead of being converted to\nnull.nulls.Date objects will be transferred as Date objects, instead of being\nconverted to their ISO string representation.Uint8Array, Uint16Array, Uint32Array and so on)\nwill be transferred as such, instead of being converted to Node.js Buffer.Buffer objects will be transferred as Uint8Arrays. You can\nconvert a Uint8Array back to a Node.js Buffer by wrapping the underlying\nArrayBuffer:Buffer.from(value.buffer, value.byteOffset, value.byteLength)\nSending any objects that aren't native JS types, such as DOM objects (e.g.\nElement, Location, DOMMatrix), Node.js objects (e.g. process.env,\nStream), or Electron objects (e.g. WebContents, BrowserWindow,\nWebFrame) is deprecated. In Electron 8, these objects will be serialized as\nbefore with a DeprecationWarning message, but starting in Electron 9, sending\nthese kinds of objects will throw a 'could not be cloned' error.
<webview>.getWebContents()This API is implemented using the remote module, which has both performance\nand security implications. Therefore its usage should be explicit.
// Deprecated\nwebview.getWebContents()\n// Replace with\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nHowever, it is recommended to avoid using the remote module altogether.
// main\nconst { ipcMain, webContents } = require('electron')\n\nconst getGuestForWebContents = (webContentsId, contents) => {\n const guest = webContents.fromId(webContentsId)\n if (!guest) {\n throw new Error(`Invalid webContentsId: ${webContentsId}`)\n }\n if (guest.hostWebContents !== contents) {\n throw new Error('Access denied to webContents')\n }\n return guest\n}\n\nipcMain.handle('openDevTools', (event, webContentsId) => {\n const guest = getGuestForWebContents(webContentsId, event.sender)\n guest.openDevTools()\n})\n\n// renderer\nconst { ipcRenderer } = require('electron')\n\nipcRenderer.invoke('openDevTools', webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium has removed support for changing the layout zoom level limits, and it\nis beyond Electron's capacity to maintain it. The function will emit a warning\nin Electron 8.x, and cease to exist in Electron 9.x. The layout zoom level\nlimits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined\nhere.
\nsystemPreferencesThe following systemPreferences events have been deprecated:
inverted-color-scheme-changedhigh-contrast-color-scheme-changedUse the new updated event on the nativeTheme module instead.
// Deprecated\nsystemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })\nsystemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })\n\n// Replace with\nnativeTheme.on('updated', () => { /* ... */ })\nsystemPreferencesThe following systemPreferences methods have been deprecated:
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()Use the following nativeTheme properties instead:
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Deprecated\nsystemPreferences.isDarkMode()\n// Replace with\nnativeTheme.shouldUseDarkColors\n\n// Deprecated\nsystemPreferences.isInvertedColorScheme()\n// Replace with\nnativeTheme.shouldUseInvertedColorScheme\n\n// Deprecated\nsystemPreferences.isHighContrastColorScheme()\n// Replace with\nnativeTheme.shouldUseHighContrastColors\nThis is the URL specified as disturl in a .npmrc file or as the --dist-url\ncommand line flag when building native Node modules. Both will be supported for\nthe foreseeable future but it is recommended that you switch.
Deprecated: https://atom.io/download/electron
\nReplace with: https://electronjs.org/headers
\nsession.clearAuthCache() no longer accepts optionsThe session.clearAuthCache API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.
// Deprecated\nsession.clearAuthCache({ type: 'password' })\n// Replace with\nsession.clearAuthCache()\npowerMonitor.querySystemIdleState is now powerMonitor.getSystemIdleState// Removed in Electron 7.0\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime is now powerMonitor.getSystemIdleTime// Removed in Electron 7.0\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\nwebFrame.setIsolatedWorldInfo replaces separate methods// Removed in Electron 7.0\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Replace with\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nmarked property on getBlinkMemoryInfoThis property was removed in Chromium 77, and as such is no longer available.
\nwebkitdirectory attribute for <input type=\"file\"/> now lists directory contentsThe webkitdirectory property on HTML file inputs allows them to select folders.\nPrevious versions of Electron had an incorrect implementation where the event.target.files\nof the input returned a FileList that returned one File corresponding to the selected folder.
As of Electron 7, that FileList is now list of all files contained within\nthe folder, similarly to Chrome, Firefox, and Edge\n(link to MDN docs).
As an illustration, take a folder with this structure:
\nfolder\n├── file1\n├── file2\n└── file3\nIn Electron <=6, this would return a FileList with a File object for:
path/to/folder\nIn Electron 7, this now returns a FileList with a File object for:
/path/to/folder/file3\n/path/to/folder/file2\n/path/to/folder/file1\nNote that webkitdirectory no longer exposes the path to the selected folder.\nIf you require the path to the selected folder rather than the folder contents,\nsee the dialog.showOpenDialog API (link).
Electron 5 and Electron 6 introduced Promise-based versions of existing\nasynchronous APIs and deprecated their older, callback-based counterparts.\nIn Electron 7, all deprecated callback-based APIs are now removed.
\nThese functions now only return Promises:
\napp.getFileIcon() #15742app.dock.show() #16904contentTracing.getCategories() #16583contentTracing.getTraceBufferUsage() #16600contentTracing.startRecording() #16584contentTracing.stopRecording() #16584contents.executeJavaScript() #17312cookies.flushStore() #16464cookies.get() #16464cookies.remove() #16464cookies.set() #16464debugger.sendCommand() #16861dialog.showCertificateTrustDialog() #17181inAppPurchase.getProducts() #17355inAppPurchase.purchaseProduct()#17355netLog.stopLogging() #16862session.clearAuthCache() #17259session.clearCache() #17185session.clearHostResolverCache() #17229session.clearStorageData() #17249session.getBlobData() #17303session.getCacheSize() #17185session.resolveProxy() #17222session.setProxy() #17222shell.openExternal() #16176webContents.loadFile() #15855webContents.loadURL() #15855webContents.hasServiceWorker() #16535webContents.printToPDF() #16795webContents.savePage() #16742webFrame.executeJavaScript() #17312webFrame.executeJavaScriptInIsolatedWorld() #17312webviewTag.executeJavaScript() #17312win.capturePage() #15743These functions now have two forms, synchronous and Promise-based asynchronous:
\ndialog.showMessageBox()/dialog.showMessageBoxSync() #17298dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054win.setMenu(null) is now win.removeMenu()// Deprecated\nwin.setMenu(null)\n// Replace with\nwin.removeMenu()\nelectron.screen in the renderer process should be accessed via remote// Deprecated\nrequire('electron').screen\n// Replace with\nrequire('electron').remote.screen\nrequire()ing node builtins in sandboxed renderers no longer implicitly loads the remote version// Deprecated\nrequire('child_process')\n// Replace with\nrequire('electron').remote.require('child_process')\n\n// Deprecated\nrequire('fs')\n// Replace with\nrequire('electron').remote.require('fs')\n\n// Deprecated\nrequire('os')\n// Replace with\nrequire('electron').remote.require('os')\n\n// Deprecated\nrequire('path')\n// Replace with\nrequire('electron').remote.require('path')\npowerMonitor.querySystemIdleState replaced with powerMonitor.getSystemIdleState// Deprecated\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime replaced with powerMonitor.getSystemIdleTime// Deprecated\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\napp.enableMixedSandbox() is no longer needed// Deprecated\napp.enableMixedSandbox()\nMixed-sandbox mode is now enabled by default.
\nTray.setHighlightModeUnder macOS Catalina our former Tray implementation breaks.\nApple's native substitute doesn't support changing the highlighting behavior.
\n// Deprecated\ntray.setHighlightMode(mode)\n// API will be removed in v7.0 without replacement.\nnodeIntegration and webviewTag default to false, contextIsolation defaults to trueThe following webPreferences option default values are deprecated in favor of the new defaults listed below.
| Property | Deprecated Default | New Default |
|---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration if set else true | false |
E.g. Re-enabling the webviewTag
\nconst w = new BrowserWindow({\n webPreferences: {\n webviewTag: true\n }\n})\nnodeIntegration in child windows opened via nativeWindowOpenChild windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is true.
Renderer process APIs webFrame.registerURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed.\nA new API, protocol.registerSchemesAsPrivileged has been added and should be used for registering custom schemes with the required privileges. Custom schemes are required to be registered before app ready.
webFrame.setIsolatedWorld* replaced with webFrame.setIsolatedWorldInfo// Deprecated\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Replace with\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nwebFrame.setSpellCheckProvider now takes an asynchronous callbackThe spellCheck callback is now asynchronous, and autoCorrectWord parameter has been removed.
// Deprecated\nwebFrame.setSpellCheckProvider('en-US', true, {\n spellCheck: (text) => {\n return !spellchecker.isMisspelled(text)\n }\n})\n// Replace with\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck: (words, callback) => {\n callback(words.filter(text => spellchecker.isMisspelled(text)))\n }\n})\nwebContents.getZoomLevel and webContents.getZoomFactor are now synchronouswebContents.getZoomLevel and webContents.getZoomFactor no longer take callback parameters,\ninstead directly returning their number values.
// Deprecated\nwebContents.getZoomLevel((level) => {\n console.log(level)\n})\n// Replace with\nconst level = webContents.getZoomLevel()\nconsole.log(level)\n// Deprecated\nwebContents.getZoomFactor((factor) => {\n console.log(factor)\n})\n// Replace with\nconst factor = webContents.getZoomFactor()\nconsole.log(factor)\nThe following list includes the breaking API changes made in Electron 4.0.
\napp.makeSingleInstance// Deprecated\napp.makeSingleInstance((argv, cwd) => {\n /* ... */\n})\n// Replace with\napp.requestSingleInstanceLock()\napp.on('second-instance', (event, argv, cwd) => {\n /* ... */\n})\napp.releaseSingleInstance// Deprecated\napp.releaseSingleInstance()\n// Replace with\napp.releaseSingleInstanceLock()\napp.getGPUInfoapp.getGPUInfo('complete')\n// Now behaves the same with `basic` on macOS\napp.getGPUInfo('basic')\nwin_delay_load_hookWhen building native modules for windows, the win_delay_load_hook variable in\nthe module's binding.gyp must be true (which is the default). If this hook is\nnot present, then the native module will fail to load on Windows, with an error\nmessage like Cannot find module. See the native module\nguide for more.
The following list includes the breaking API changes in Electron 3.0.
\napp// Deprecated\napp.getAppMemoryInfo()\n// Replace with\napp.getAppMetrics()\n\n// Deprecated\nconst metrics = app.getAppMetrics()\nconst { memory } = metrics[0] // Deprecated property\nBrowserWindow// Deprecated\nconst optionsA = { webPreferences: { blinkFeatures: '' } }\nconst windowA = new BrowserWindow(optionsA)\n// Replace with\nconst optionsB = { webPreferences: { enableBlinkFeatures: '' } }\nconst windowB = new BrowserWindow(optionsB)\n\n// Deprecated\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play_pause') {\n // do something\n }\n})\n// Replace with\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play-pause') {\n // do something\n }\n})\nclipboard// Deprecated\nclipboard.readRtf()\n// Replace with\nclipboard.readRTF()\n\n// Deprecated\nclipboard.writeRtf()\n// Replace with\nclipboard.writeRTF()\n\n// Deprecated\nclipboard.readHtml()\n// Replace with\nclipboard.readHTML()\n\n// Deprecated\nclipboard.writeHtml()\n// Replace with\nclipboard.writeHTML()\ncrashReporter// Deprecated\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n autoSubmit: true\n})\n// Replace with\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n uploadToServer: true\n})\nnativeImage// Deprecated\nnativeImage.createFromBuffer(buffer, 1.0)\n// Replace with\nnativeImage.createFromBuffer(buffer, {\n scaleFactor: 1.0\n})\nprocess// Deprecated\nconst info = process.getProcessMemoryInfo()\nscreen// Deprecated\nscreen.getMenuBarHeight()\n// Replace with\nscreen.getPrimaryDisplay().workArea\nsession// Deprecated\nses.setCertificateVerifyProc((hostname, certificate, callback) => {\n callback(true)\n})\n// Replace with\nses.setCertificateVerifyProc((request, callback) => {\n callback(0)\n})\nTray// Deprecated\ntray.setHighlightMode(true)\n// Replace with\ntray.setHighlightMode('on')\n\n// Deprecated\ntray.setHighlightMode(false)\n// Replace with\ntray.setHighlightMode('off')\nwebContents// Deprecated\nwebContents.openDevTools({ detach: true })\n// Replace with\nwebContents.openDevTools({ mode: 'detach' })\n\n// Removed\nwebContents.setSize(options)\n// There is no replacement for this API\nwebFrame// Deprecated\nwebFrame.registerURLSchemeAsSecure('app')\n// Replace with\nprotocol.registerStandardSchemes(['app'], { secure: true })\n\n// Deprecated\nwebFrame.registerURLSchemeAsPrivileged('app', { secure: true })\n// Replace with\nprotocol.registerStandardSchemes(['app'], { secure: true })\n<webview>// Removed\nwebview.setAttribute('disableguestresize', '')\n// There is no replacement for this API\n\n// Removed\nwebview.setAttribute('guestinstance', instanceId)\n// There is no replacement for this API\n\n// Keyboard listeners no longer work on webview tag\nwebview.onkeydown = () => { /* handler */ }\nwebview.onkeyup = () => { /* handler */ }\nThis is the URL specified as disturl in a .npmrc file or as the --dist-url\ncommand line flag when building native Node modules.
Deprecated: https://atom.io/download/atom-shell
\nReplace with: https://atom.io/download/electron
\nThe following list includes the breaking API changes made in Electron 2.0.
\nBrowserWindow// Deprecated\nconst optionsA = { titleBarStyle: 'hidden-inset' }\nconst windowA = new BrowserWindow(optionsA)\n// Replace with\nconst optionsB = { titleBarStyle: 'hiddenInset' }\nconst windowB = new BrowserWindow(optionsB)\nmenu// Removed\nmenu.popup(browserWindow, 100, 200, 2)\n// Replaced with\nmenu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })\nnativeImage// Removed\nnativeImage.toPng()\n// Replaced with\nnativeImage.toPNG()\n\n// Removed\nnativeImage.toJpeg()\n// Replaced with\nnativeImage.toJPEG()\nprocessprocess.versions.electron and process.version.chrome will be made\nread-only properties for consistency with the other process.versions\nproperties set by Node.webContents// Removed\nwebContents.setZoomLevelLimits(1, 2)\n// Replaced with\nwebContents.setVisualZoomLevelLimits(1, 2)\nwebFrame// Removed\nwebFrame.setZoomLevelLimits(1, 2)\n// Replaced with\nwebFrame.setVisualZoomLevelLimits(1, 2)\n<webview>// Removed\nwebview.setZoomLevelLimits(1, 2)\n// Replaced with\nwebview.setVisualZoomLevelLimits(1, 2)\nEach Electron release includes two identical ARM builds with slightly different\nfilenames, like electron-v1.7.3-linux-arm.zip and\nelectron-v1.7.3-linux-armv7l.zip. The asset with the v7l prefix was added\nto clarify to users which ARM version it supports, and to disambiguate it from\nfuture armv6l and arm64 assets that may be produced.
The file without the prefix is still being published to avoid breaking any\nsetups that may be consuming it. Starting at 2.0, the unprefixed file will\nno longer be published.
\nFor details, see\n6986\nand\n7189.
", "title": "Breaking Changes", "description": "" }, "/docs/api/browser-view": { "locale": "en-US", "slug": "browser-view", "href": "/docs/api/browser-view", "crowdinFileId": "256283", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-view.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "A BrowserView can be used to embed additional web content into a\nBrowserWindow. It is like a child window, except that it is positioned\nrelative to its owning window. It is meant to be an alternative to the\nwebview tag.
\n\nCreate and control views.
\n
Process: Main
\n// In the main process.\nconst { BrowserView, BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nconst view = new BrowserView()\nwin.setBrowserView(view)\nview.setBounds({ x: 0, y: 0, width: 300, height: 300 })\nview.webContents.loadURL('https://electronjs.org')\nnew BrowserView([options]) Experimentaloptions Object (optional)webPreferences Object (optional) - See BrowserWindow.Objects created with new BrowserView have the following properties:
view.webContents ExperimentalA WebContents object owned by this view.
Objects created with new BrowserView have the following instance methods:
view.setAutoResize(options) Experimentaloptions Objectwidth Boolean (optional) - If true, the view's width will grow and shrink together\nwith the window. false by default.height Boolean (optional) - If true, the view's height will grow and shrink\ntogether with the window. false by default.horizontal Boolean (optional) - If true, the view's x position and width will grow\nand shrink proportionally with the window. false by default.vertical Boolean (optional) - If true, the view's y position and height will grow\nand shrink proportionally with the window. false by default.view.setBounds(bounds) Experimentalbounds RectangleResizes and moves the view to the supplied bounds relative to the window.
\nview.getBounds() ExperimentalReturns Rectangle
The bounds of this BrowserView instance as Object.
view.setBackgroundColor(color) Experimentalcolor String - Color in #aarrggbb or #argb form. The alpha channel is\noptional.\n\nCreate and control browser windows.
\n
Process: Main
\n// In the main process.\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\n// Load a remote URL\nwin.loadURL('https://github.com')\n\n// Or load a local HTML file\nwin.loadFile('index.html')\nTo create a window without chrome, or a transparent window in arbitrary shape,\nyou can use the Frameless Window API.
\nWhen loading a page in the window directly, users may see the page load incrementally,\nwhich is not a good experience for a native app. To make the window display\nwithout a visual flash, there are two solutions for different situations.
\nready-to-show eventWhile loading the page, the ready-to-show event will be emitted when the renderer\nprocess has rendered the page for the first time if the window has not been shown yet. Showing\nthe window after this event will have no visual flash:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ show: false })\nwin.once('ready-to-show', () => {\n win.show()\n})\nThis event is usually emitted after the did-finish-load event, but for\npages with many remote resources, it may be emitted before the did-finish-load\nevent.
Please note that using this event implies that the renderer will be considered \"visible\" and\npaint even though show is false. This event will never fire if you use paintWhenInitiallyHidden: false
backgroundColor propertyFor a complex app, the ready-to-show event could be emitted too late, making\nthe app feel slow. In this case, it is recommended to show the window\nimmediately, and use a backgroundColor close to your app's background:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ backgroundColor: '#2e2c29' })\nwin.loadURL('https://github.com')\nNote that even for apps that use ready-to-show event, it is still recommended\nto set backgroundColor to make app feel more native.
By using parent option, you can create child windows:
const { BrowserWindow } = require('electron')\n\nconst top = new BrowserWindow()\nconst child = new BrowserWindow({ parent: top })\nchild.show()\ntop.show()\nThe child window will always show on top of the top window.
A modal window is a child window that disables parent window, to create a modal\nwindow, you have to set both parent and modal options:
const { BrowserWindow } = require('electron')\n\nconst child = new BrowserWindow({ parent: top, modal: true, show: false })\nchild.loadURL('https://github.com')\nchild.once('ready-to-show', () => {\n child.show()\n})\nThe Page Visibility API works as follows:
\nhidden. On other platforms, the\nvisibility state will be hidden only when the window is minimized or\nexplicitly hidden with win.hide().BrowserWindow is created with show: false, the initial visibility\nstate will be visible despite the window actually being hidden.backgroundThrottling is disabled, the visibility state will remain\nvisible even if the window is minimized, occluded, or hidden.It is recommended that you pause expensive operations when the visibility\nstate is hidden in order to minimize power consumption.
dialog.\n\nCreate and control browser windows.
\n
Process: Main
\nBrowserWindow is an EventEmitter.
It creates a new BrowserWindow with native properties as set by the options.
new BrowserWindow([options])options Object (optional)width Integer (optional) - Window's width in pixels. Default is 800.height Integer (optional) - Window's height in pixels. Default is 600.x Integer (optional) - (required if y is used) Window's left offset from screen.\nDefault is to center the window.y Integer (optional) - (required if x is used) Window's top offset from screen.\nDefault is to center the window.useContentSize Boolean (optional) - The width and height would be used as web\npage's size, which means the actual window's size will include window\nframe's size and be slightly larger. Default is false.center Boolean (optional) - Show window in the center of the screen.minWidth Integer (optional) - Window's minimum width. Default is 0.minHeight Integer (optional) - Window's minimum height. Default is 0.maxWidth Integer (optional) - Window's maximum width. Default is no limit.maxHeight Integer (optional) - Window's maximum height. Default is no limit.resizable Boolean (optional) - Whether window is resizable. Default is true.movable Boolean (optional) - Whether window is movable. This is not implemented\non Linux. Default is true.minimizable Boolean (optional) - Whether window is minimizable. This is not\nimplemented on Linux. Default is true.maximizable Boolean (optional) - Whether window is maximizable. This is not\nimplemented on Linux. Default is true.closable Boolean (optional) - Whether window is closable. This is not implemented\non Linux. Default is true.focusable Boolean (optional) - Whether the window can be focused. Default is\ntrue. On Windows setting focusable: false also implies setting\nskipTaskbar: true. On Linux setting focusable: false makes the window\nstop interacting with wm, so the window will always stay on top in all\nworkspaces.alwaysOnTop Boolean (optional) - Whether the window should always stay on top of\nother windows. Default is false.fullscreen Boolean (optional) - Whether the window should show in fullscreen. When\nexplicitly set to false the fullscreen button will be hidden or disabled\non macOS. Default is false.fullscreenable Boolean (optional) - Whether the window can be put into fullscreen\nmode. On macOS, also whether the maximize/zoom button should toggle full\nscreen mode or maximize window. Default is true.simpleFullscreen Boolean (optional) - Use pre-Lion fullscreen on macOS. Default is false.skipTaskbar Boolean (optional) - Whether to show the window in taskbar. Default is\nfalse.kiosk Boolean (optional) - Whether the window is in kiosk mode. Default is false.title String (optional) - Default window title. Default is \"Electron\". If the HTML tag <title> is defined in the HTML file loaded by loadURL(), this property will be ignored.icon (NativeImage | String) (optional) - The window icon. On Windows it is\nrecommended to use ICO icons to get best visual effects, you can also\nleave it undefined so the executable's icon will be used.show Boolean (optional) - Whether window should be shown when created. Default is\ntrue.paintWhenInitiallyHidden Boolean (optional) - Whether the renderer should be active when show is false and it has just been created. In order for document.visibilityState to work correctly on first load with show: false you should set this to false. Setting this to false will cause the ready-to-show event to not fire. Default is true.frame Boolean (optional) - Specify false to create a\nFrameless Window. Default is true.parent BrowserWindow (optional) - Specify parent window. Default is null.modal Boolean (optional) - Whether this is a modal window. This only works when the\nwindow is a child window. Default is false.acceptFirstMouse Boolean (optional) - Whether clicking an inactive window will also\nclick through to the web contents. Default is false on macOS. This option is not\nconfigurable on other platforms.disableAutoHideCursor Boolean (optional) - Whether to hide cursor when typing.\nDefault is false.autoHideMenuBar Boolean (optional) - Auto hide the menu bar unless the Alt\nkey is pressed. Default is false.enableLargerThanScreen Boolean (optional) - Enable the window to be resized larger\nthan screen. Only relevant for macOS, as other OSes allow\nlarger-than-screen windows by default. Default is false.backgroundColor String (optional) - Window's background color as a hexadecimal value,\nlike #66CD00 or #FFF or #80FFFFFF (alpha in #AARRGGBB format is supported if\ntransparent is set to true). Default is #FFF (white).hasShadow Boolean (optional) - Whether window should have a shadow. Default is true.opacity Number (optional) - Set the initial opacity of the window, between 0.0 (fully\ntransparent) and 1.0 (fully opaque). This is only implemented on Windows and macOS.darkTheme Boolean (optional) - Forces using dark theme for the window, only works on\nsome GTK+3 desktop environments. Default is false.transparent Boolean (optional) - Makes the window transparent.\nDefault is false. On Windows, does not work unless the window is frameless.type String (optional) - The type of window, default is normal window. See more about\nthis below.visualEffectState String (optional) - Specify how the material appearance should reflect window activity state on macOS. Must be used with the vibrancy property. Possible values are:followWindow - The backdrop should automatically appear active when the window is active, and inactive when it is not. This is the default.active - The backdrop should always appear active.inactive - The backdrop should always appear inactive.titleBarStyle String (optional) macOS Windows - The style of window title bar.\nDefault is default. Possible values are:default - Results in the standard title bar for macOS or Windows respectively.hidden - Results in a hidden title bar and a full size content window. On macOS, the window still has the standard window controls (“traffic lights”) in the top left. On Windows, when combined with titleBarOverlay: true it will activate the Window Controls Overlay (see titleBarOverlay for more information), otherwise no window controls will be shown.hiddenInset - Only on macOS, results in a hidden title bar with an alternative look\nwhere the traffic light buttons are slightly more inset from the window edge.customButtonsOnHover - Only on macOS, results in a hidden title bar and a full size\ncontent window, the traffic light buttons will display when being hovered\nover in the top left of the window. Note: This option is currently\nexperimental.trafficLightPosition Point (optional) - Set a\ncustom position for the traffic light buttons in frameless windows.roundedCorners Boolean (optional) - Whether frameless window should have\nrounded corners on macOS. Default is true.fullscreenWindowTitle Boolean (optional) Deprecated - Shows the title in\nthe title bar in full screen mode on macOS for hiddenInset titleBarStyle.\nDefault is false.thickFrame Boolean (optional) - Use WS_THICKFRAME style for frameless windows on\nWindows, which adds standard window frame. Setting it to false will remove\nwindow shadow and window animations. Default is true.vibrancy String (optional) - Add a type of vibrancy effect to the window, only on\nmacOS. Can be appearance-based, light, dark, titlebar, selection,\nmenu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, or under-page. Please note that appearance-based, light, dark, medium-light, and ultra-dark are deprecated and have been removed in macOS Catalina (10.15).zoomToPageWidth Boolean (optional) - Controls the behavior on macOS when\noption-clicking the green stoplight button on the toolbar or by clicking the\nWindow > Zoom menu item. If true, the window will grow to the preferred\nwidth of the web page when zoomed, false will cause it to zoom to the\nwidth of the screen. This will also affect the behavior when calling\nmaximize() directly. Default is false.tabbingIdentifier String (optional) - Tab group name, allows opening the\nwindow as a native tab on macOS 10.12+. Windows with the same tabbing\nidentifier will be grouped together. This also adds a native new tab button\nto your window's tab bar and allows your app and window to receive the\nnew-window-for-tab event.webPreferences Object (optional) - Settings of web page's features.devTools Boolean (optional) - Whether to enable DevTools. If it is set to false, can not use BrowserWindow.webContents.openDevTools() to open DevTools. Default is true.nodeIntegration Boolean (optional) - Whether node integration is enabled.\nDefault is false.nodeIntegrationInWorker Boolean (optional) - Whether node integration is\nenabled in web workers. Default is false. More about this can be found\nin Multithreading.nodeIntegrationInSubFrames Boolean (optional) - Experimental option for\nenabling Node.js support in sub-frames such as iframes and child windows. All your preloads will load for\nevery iframe, you can use process.isMainFrame to determine if you are\nin the main frame or not.preload String (optional) - Specifies a script that will be loaded before other\nscripts run in the page. This script will always have access to node APIs\nno matter whether node integration is turned on or off. The value should\nbe the absolute file path to the script.\nWhen node integration is turned off, the preload script can reintroduce\nNode global symbols back to the global scope. See example\nhere.sandbox Boolean (optional) - If set, this will sandbox the renderer\nassociated with the window, making it compatible with the Chromium\nOS-level sandbox and disabling the Node.js engine. This is not the same as\nthe nodeIntegration option and the APIs available to the preload script\nare more limited. Read more about the option here.session Session (optional) - Sets the session used by the\npage. Instead of passing the Session object directly, you can also choose to\nuse the partition option instead, which accepts a partition string. When\nboth session and partition are provided, session will be preferred.\nDefault is the default session.partition String (optional) - Sets the session used by the page according to the\nsession's partition string. If partition starts with persist:, the page\nwill use a persistent session available to all pages in the app with the\nsame partition. If there is no persist: prefix, the page will use an\nin-memory session. By assigning the same partition, multiple pages can share\nthe same session. Default is the default session.zoomFactor Number (optional) - The default zoom factor of the page, 3.0 represents\n300%. Default is 1.0.javascript Boolean (optional) - Enables JavaScript support. Default is true.webSecurity Boolean (optional) - When false, it will disable the\nsame-origin policy (usually using testing websites by people), and set\nallowRunningInsecureContent to true if this options has not been set\nby user. Default is true.allowRunningInsecureContent Boolean (optional) - Allow an https page to run\nJavaScript, CSS or plugins from http URLs. Default is false.images Boolean (optional) - Enables image support. Default is true.imageAnimationPolicy String (optional) - Specifies how to run image animations (E.g. GIFs). Can be animate, animateOnce or noAnimation. Default is animate.textAreasAreResizable Boolean (optional) - Make TextArea elements resizable. Default\nis true.webgl Boolean (optional) - Enables WebGL support. Default is true.plugins Boolean (optional) - Whether plugins should be enabled. Default is false.experimentalFeatures Boolean (optional) - Enables Chromium's experimental features.\nDefault is false.scrollBounce Boolean (optional) - Enables scroll bounce (rubber banding) effect on\nmacOS. Default is false.enableBlinkFeatures String (optional) - A list of feature strings separated by ,, like\nCSSVariables,KeyboardEventKey to enable. The full list of supported feature\nstrings can be found in the RuntimeEnabledFeatures.json5\nfile.disableBlinkFeatures String (optional) - A list of feature strings separated by ,,\nlike CSSVariables,KeyboardEventKey to disable. The full list of supported\nfeature strings can be found in the\nRuntimeEnabledFeatures.json5 file.defaultFontFamily Object (optional) - Sets the default font for the font-family.standard String (optional) - Defaults to Times New Roman.serif String (optional) - Defaults to Times New Roman.sansSerif String (optional) - Defaults to Arial.monospace String (optional) - Defaults to Courier New.cursive String (optional) - Defaults to Script.fantasy String (optional) - Defaults to Impact.defaultFontSize Integer (optional) - Defaults to 16.defaultMonospaceFontSize Integer (optional) - Defaults to 13.minimumFontSize Integer (optional) - Defaults to 0.defaultEncoding String (optional) - Defaults to ISO-8859-1.backgroundThrottling Boolean (optional) - Whether to throttle animations and timers\nwhen the page becomes background. This also affects the\nPage Visibility API. Defaults to true.offscreen Boolean (optional) - Whether to enable offscreen rendering for the browser\nwindow. Defaults to false. See the\noffscreen rendering tutorial for\nmore details.contextIsolation Boolean (optional) - Whether to run Electron APIs and\nthe specified preload script in a separate JavaScript context. Defaults\nto true. The context that the preload script runs in will only have\naccess to its own dedicated document and window globals, as well as\nits own set of JavaScript builtins (Array, Object, JSON, etc.),\nwhich are all invisible to the loaded content. The Electron API will only\nbe available in the preload script and not the loaded page. This option\nshould be used when loading potentially untrusted remote content to ensure\nthe loaded content cannot tamper with the preload script and any\nElectron APIs being used. This option uses the same technique used by\nChrome Content Scripts. You can access this\ncontext in the dev tools by selecting the 'Electron Isolated Context'\nentry in the combo box at the top of the Console tab.nativeWindowOpen Boolean (optional) - Whether to use native\nwindow.open(). Defaults to true. Child windows will always have node\nintegration disabled unless nodeIntegrationInSubFrames is true.webviewTag Boolean (optional) - Whether to enable the <webview> tag.\nDefaults to false. Note: The\npreload script configured for the <webview> will have node integration\nenabled when it is executed so you should ensure remote/untrusted content\nis not able to create a <webview> tag with a possibly malicious preload\nscript. You can use the will-attach-webview event on webContents\nto strip away the preload script and to validate or alter the\n<webview>'s initial settings.additionalArguments String - A list of strings that will be appended\nto process.argv in the renderer process of this app. Useful for passing small\nbits of data down to renderer process preload scripts.safeDialogs Boolean (optional) - Whether to enable browser style\nconsecutive dialog protection. Default is false.safeDialogsMessage String (optional) - The message to display when\nconsecutive dialog protection is triggered. If not defined the default\nmessage would be used, note that currently the default message is in\nEnglish and not localized.disableDialogs Boolean (optional) - Whether to disable dialogs\ncompletely. Overrides safeDialogs. Default is false.navigateOnDragDrop Boolean (optional) - Whether dragging and dropping a\nfile or link onto the page causes a navigation. Default is false.autoplayPolicy String (optional) - Autoplay policy to apply to\ncontent in the window, can be no-user-gesture-required,\nuser-gesture-required, document-user-activation-required. Defaults to\nno-user-gesture-required.disableHtmlFullscreenWindowResize Boolean (optional) - Whether to\nprevent the window from resizing when entering HTML Fullscreen. Default\nis false.accessibleTitle String (optional) - An alternative title string provided only\nto accessibility tools such as screen readers. This string is not directly\nvisible to users.spellcheck Boolean (optional) - Whether to enable the builtin spellchecker.\nDefault is true.enableWebSQL Boolean (optional) - Whether to enable the WebSQL api.\nDefault is true.v8CacheOptions String (optional) - Enforces the v8 code caching policy\nused by blink. Accepted values arenone - Disables code cachingcode - Heuristic based code cachingbypassHeatCheck - Bypass code caching heuristics but with lazy compilationbypassHeatCheckAndEagerCompile - Same as above except compilation is eager.\nDefault policy is code.enablePreferredSizeMode Boolean (optional) - Whether to enable\npreferred size mode. The preferred size is the minimum size needed to\ncontain the layout of the document—without requiring scrolling. Enabling\nthis will cause the preferred-size-changed event to be emitted on the\nWebContents when the preferred size changes. Default is false.titleBarOverlay Object | Boolean (optional) - When using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS or using a titleBarStyle so that the standard window controls (\"traffic lights\" on macOS) are visible, this property enables the Window Controls Overlay JavaScript APIs and CSS Environment Variables. Specifying true will result in an overlay with default system colors. Default is false.color String (optional) Windows - The CSS color of the Window Controls Overlay when enabled. Default is the system color.symbolColor String (optional) Windows - The CSS color of the symbols on the Window Controls Overlay when enabled. Default is the system color.When setting minimum or maximum window size with minWidth/maxWidth/\nminHeight/maxHeight, it only constrains the users. It won't prevent you from\npassing a size that does not follow size constraints to setBounds/setSize or\nto the constructor of BrowserWindow.
The possible values and behaviors of the type option are platform dependent.\nPossible values are:
desktop, dock, toolbar, splash,\nnotification.desktop, textured.textured type adds metal gradient appearance\n(NSTexturedBackgroundWindowMask).desktop type places the window at the desktop background window level\n(kCGDesktopWindowLevel - 1). Note that desktop window will not receive\nfocus, keyboard or mouse events, but you can use globalShortcut to receive\ninput sparingly.toolbar.Objects created with new BrowserWindow emit the following events:
Note: Some events are only available on specific operating systems and are\nlabeled as such.
\nReturns:
\nevent Eventtitle StringexplicitSet BooleanEmitted when the document changed its title, calling event.preventDefault()\nwill prevent the native window's title from changing.\nexplicitSet is false when title is synthesized from file URL.
Returns:
\nevent EventEmitted when the window is going to be closed. It's emitted before the\nbeforeunload and unload event of the DOM. Calling event.preventDefault()\nwill cancel the close.
Usually you would want to use the beforeunload handler to decide whether the\nwindow should be closed, which will also be called when the window is\nreloaded. In Electron, returning any value other than undefined would cancel the\nclose. For example:
window.onbeforeunload = (e) => {\n console.log('I do not want to be closed')\n\n // Unlike usual browsers that a message box will be prompted to users, returning\n // a non-void value will silently cancel the close.\n // It is recommended to use the dialog API to let the user confirm closing the\n // application.\n e.returnValue = false // equivalent to `return false` but not recommended\n}\nNote: There is a subtle difference between the behaviors of window.onbeforeunload = handler and window.addEventListener('beforeunload', handler). It is recommended to always set the event.returnValue explicitly, instead of only returning a value, as the former works more consistently within Electron.
Emitted when the window is closed. After you have received this event you should\nremove the reference to the window and avoid using it any more.
\nEmitted when window session is going to end due to force shutdown or machine restart\nor session log off.
\nEmitted when the web page becomes unresponsive.
\nEmitted when the unresponsive web page becomes responsive again.
\nEmitted when the window loses focus.
\nEmitted when the window gains focus.
\nEmitted when the window is shown.
\nEmitted when the window is hidden.
\nEmitted when the web page has been rendered (while not being shown) and window can be displayed without\na visual flash.
\nPlease note that using this event implies that the renderer will be considered \"visible\" and\npaint even though show is false. This event will never fire if you use paintWhenInitiallyHidden: false
Emitted when window is maximized.
\nEmitted when the window exits from a maximized state.
\nEmitted when the window is minimized.
\nEmitted when the window is restored from a minimized state.
\nReturns:
\nevent EventnewBounds Rectangle - Size the window is being resized to.details Objectedge (String) - The edge of the window being dragged for resizing. Can be bottom, left, right, top-left, top-right, bottom-left or bottom-right.Emitted before the window is resized. Calling event.preventDefault() will prevent the window from being resized.
Note that this is only emitted when the window is being resized manually. Resizing the window with setBounds/setSize will not emit this event.
The possible values and behaviors of the edge option are platform dependent. Possible values are:
bottom, top, left, right, top-left, top-right, bottom-left, bottom-right.bottom and right.bottom is used to denote vertical resizing.right is used to denote horizontal resizing.Emitted after the window has been resized.
\nEmitted once when the window has finished being resized.
\nThis 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.
Returns:
\nevent EventnewBounds Rectangle - Location the window is being moved to.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 resized manually. Resizing the window with setBounds/setSize will not emit this event.
Emitted when the window is being moved to a new position.
\nEmitted once when the window is moved to a new position.
\nNote: On macOS this event is an alias of move.
Emitted when the window enters a full-screen state.
\nEmitted when the window leaves a full-screen state.
\nEmitted when the window enters a full-screen state triggered by HTML API.
\nEmitted when the window leaves a full-screen state triggered by HTML API.
\nReturns:
\nevent EventisAlwaysOnTop BooleanEmitted when the window is set or unset to show always on top of other windows.
\nReturns:
\nevent Eventcommand StringEmitted when an App Command\nis invoked. These are typically related to keyboard media keys or browser\ncommands, as well as the \"Back\" button built into some mice on Windows.
\nCommands are lowercased, underscores are replaced with hyphens, and the\nAPPCOMMAND_ prefix is stripped off.\ne.g. APPCOMMAND_BROWSER_BACKWARD is emitted as browser-backward.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.on('app-command', (e, cmd) => {\n // Navigate the window back when the user hits their mouse back button\n if (cmd === 'browser-backward' && win.webContents.canGoBack()) {\n win.webContents.goBack()\n }\n})\nThe following app commands are explicitly supported on Linux:
\nbrowser-backwardbrowser-forwardEmitted when scroll wheel event phase has begun.
\nEmitted when scroll wheel event phase has ended.
\nEmitted when scroll wheel event phase filed upon reaching the edge of element.
\nReturns:
\nevent Eventdirection StringEmitted on 3-finger swipe. Possible directions are up, right, down, left.
The method underlying this event is built to handle older macOS-style trackpad swiping,\nwhere the content on the screen doesn't move with the swipe. Most macOS trackpads are not\nconfigured to allow this kind of swiping anymore, so in order for it to emit properly the\n'Swipe between pages' preference in System Preferences > Trackpad > More Gestures must be\nset to 'Swipe with two or three fingers'.
Returns:
\nevent Eventrotation FloatEmitted on trackpad rotation gesture. Continually emitted until rotation gesture is\nended. The rotation value on each emission is the angle in degrees rotated since\nthe last emission. The last emitted event upon a rotation gesture will always be of\nvalue 0. Counter-clockwise rotation values are positive, while clockwise ones are\nnegative.
Emitted when the window opens a sheet.
\nEmitted when the window has closed a sheet.
\nEmitted when the native new tab button is clicked.
\nReturns:
\nevent Eventpoint Point - The screen coordinates the context menu was triggered atEmitted when the system context menu is triggered on the window, this is\nnormally only triggered when the user right clicks on the non-client area\nof your window. This is the window titlebar or any area you have declared\nas -webkit-app-region: drag in a frameless window.
Calling event.preventDefault() will prevent the menu from being displayed.
The BrowserWindow class has the following static methods:
BrowserWindow.getAllWindows()Returns BrowserWindow[] - An array of all opened browser windows.
BrowserWindow.getFocusedWindow()Returns BrowserWindow | null - The window that is focused in this application, otherwise returns null.
BrowserWindow.fromWebContents(webContents)webContents WebContentsReturns BrowserWindow | null - The window that owns the given webContents\nor null if the contents are not owned by a window.
BrowserWindow.fromBrowserView(browserView)browserView BrowserViewReturns BrowserWindow | null - The window that owns the given browserView. If the given view is not attached to any window, returns null.
BrowserWindow.fromId(id)id IntegerReturns BrowserWindow | null - The window with the given id.
Objects created with new BrowserWindow have the following properties:
const { BrowserWindow } = require('electron')\n// In this example `win` is our instance\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('https://github.com')\nwin.webContents ReadonlyA WebContents object this window owns. All web page related events and\noperations will be done via it.
See the webContents documentation for its methods and\nevents.
win.id ReadonlyA Integer property representing the unique ID of the window. Each ID is unique among all BrowserWindow instances of the entire Electron application.
win.autoHideMenuBarA Boolean property that determines whether the window menu bar should hide itself automatically. Once set, the menu bar will only show when users press the single Alt key.
If the menu bar is already visible, setting this property to true won't\nhide it immediately.
win.simpleFullScreenA Boolean property that determines whether the window is in simple (pre-Lion) fullscreen mode.
win.fullScreenA Boolean property that determines whether the window is in fullscreen mode.
win.focusable Windows macOSA Boolean property that determines whether the window is focusable.
win.visibleOnAllWorkspacesA Boolean property that determines whether the window is visible on all workspaces.
Note: Always returns false on Windows.
\nwin.shadowA Boolean property that determines whether the window has a shadow.
win.menuBarVisible Windows LinuxA 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.kioskA Boolean property that determines whether the window is in kiosk mode.
win.documentEdited macOSA 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 macOSA String property that determines the pathname of the file the window represents,\nand the icon of the file will show in window's title bar.
win.titleA 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.
\nwin.minimizableA Boolean property that determines whether the window can be manually minimized by user.
On Linux the setter is a no-op, although the getter returns true.
win.maximizableA Boolean property that determines whether the window can be manually maximized by user.
On Linux the setter is a no-op, although the getter returns true.
win.fullScreenableA Boolean property that determines whether the maximize/zoom window button toggles fullscreen mode or\nmaximizes the window.
win.resizableA Boolean property that determines whether the window can be manually resized by user.
win.closableA Boolean property that determines whether the window can be manually closed by user.
On Linux the setter is a no-op, although the getter returns true.
win.movableA Boolean property that determines Whether the window can be moved by user.
On Linux the setter is a no-op, although the getter returns true.
win.excludedFromShownWindowsMenu macOSA Boolean property that determines whether the window is excluded from the application’s Windows menu. false by default.
const win = new BrowserWindow({ height: 600, width: 600 })\n\nconst template = [\n {\n role: 'windowmenu'\n }\n]\n\nwin.excludedFromShownWindowsMenu = true\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nwin.accessibleTitleA String property that defines an alternative title provided only to\naccessibility tools such as screen readers. This string is not directly\nvisible to users.
Objects created with new BrowserWindow have the following instance methods:
Note: Some methods are only available on specific operating systems and are\nlabeled as such.
\nwin.destroy()Force closing the window, the unload and beforeunload event won't be emitted\nfor the web page, and close event will also not be emitted\nfor this window, but it guarantees the closed event will be emitted.
win.close()Try to close the window. This has the same effect as a user manually clicking\nthe close button of the window. The web page may cancel the close though. See\nthe close event.
\nwin.focus()Focuses on the window.
\nwin.blur()Removes focus from the window.
\nwin.isFocused()Returns Boolean - Whether the window is focused.
win.isDestroyed()Returns Boolean - Whether the window is destroyed.
win.show()Shows and gives focus to the window.
\nwin.showInactive()Shows the window but doesn't focus on it.
\nwin.hide()Hides the window.
\nwin.isVisible()Returns Boolean - Whether the window is visible to the user.
win.isModal()Returns Boolean - Whether current window is a modal window.
win.maximize()Maximizes the window. This will also show (but not focus) the window if it\nisn't being displayed already.
\nwin.unmaximize()Unmaximizes the window.
\nwin.isMaximized()Returns Boolean - Whether the window is maximized.
win.minimize()Minimizes the window. On some platforms the minimized window will be shown in\nthe Dock.
\nwin.restore()Restores the window from minimized state to its previous state.
\nwin.isMinimized()Returns Boolean - Whether the window is minimized.
win.setFullScreen(flag)flag BooleanSets whether the window should be in fullscreen mode.
\nwin.isFullScreen()Returns Boolean - Whether the window is in fullscreen mode.
win.setSimpleFullScreen(flag) macOSflag BooleanEnters or leaves simple fullscreen mode.
\nSimple fullscreen mode emulates the native fullscreen behavior found in versions of macOS prior to Lion (10.7).
\nwin.isSimpleFullScreen() macOSReturns Boolean - Whether the window is in simple (pre-Lion) fullscreen mode.
win.isNormal()Returns Boolean - Whether the window is in normal state (not maximized, not minimized, not in fullscreen mode).
win.setAspectRatio(aspectRatio[, extraSize])aspectRatio Float - The aspect ratio to maintain for some portion of the\ncontent view.extraSize Size (optional) macOS - The extra size not to be included while\nmaintaining the aspect ratio.This will make a window maintain an aspect ratio. The extra size allows a\ndeveloper to have space, specified in pixels, not included within the aspect\nratio calculations. This API already takes into account the difference between a\nwindow's size and its content size.
\nConsider a normal window with an HD video player and associated controls.\nPerhaps there are 15 pixels of controls on the left edge, 25 pixels of controls\non the right edge and 50 pixels of controls below the player. In order to\nmaintain a 16:9 aspect ratio (standard aspect ratio for HD @1920x1080) within\nthe player itself we would call this function with arguments of 16/9 and\n{ width: 40, height: 50 }. The second argument doesn't care where the extra width and height\nare within the content view--only that they exist. Sum any extra width and\nheight areas you have within the overall content view.
\nThe aspect ratio is not respected when window is resized programmatically with\nAPIs like win.setSize.
win.setBackgroundColor(backgroundColor)backgroundColor String - Window's background color as a hexadecimal value,\nlike #66CD00 or #FFF or #80FFFFFF (alpha is supported if transparent\nis true). Default is #FFF (white).Sets the background color of the window. See Setting\nbackgroundColor.
win.previewFile(path[, displayName]) macOSpath String - The absolute path to the file to preview with QuickLook. This\nis important as Quick Look uses the file name and file extension on the path\nto determine the content type of the file to open.displayName String (optional) - The name of the file to display on the\nQuick Look modal view. This is purely visual and does not affect the content\ntype of the file. Defaults to path.Uses Quick Look to preview a file at a given path.
\nwin.closeFilePreview() macOSCloses the currently open Quick Look panel.
\nwin.setBounds(bounds[, animate])bounds Partial<Rectangle>animate Boolean (optional) macOSResizes and moves the window to the supplied bounds. Any properties that are not supplied will default to their current values.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\n// set all bounds properties\nwin.setBounds({ x: 440, y: 225, width: 800, height: 600 })\n\n// set a single bounds property\nwin.setBounds({ width: 100 })\n\n// { x: 440, y: 225, width: 100, height: 600 }\nconsole.log(win.getBounds())\nwin.getBounds()Returns Rectangle - The bounds of the window as Object.
win.getBackgroundColor()Returns String - Gets the background color of the window. See Setting\nbackgroundColor.
win.setContentBounds(bounds[, animate])bounds Rectangleanimate Boolean (optional) macOSResizes and moves the window's client area (e.g. the web page) to\nthe supplied bounds.
\nwin.getContentBounds()Returns Rectangle - The bounds of the window's client area as Object.
win.getNormalBounds()Returns Rectangle - Contains the window bounds of the normal state
Note: whatever the current state of the window : maximized, minimized or in fullscreen, this function always returns the position and size of the window in normal state. In normal state, getBounds and getNormalBounds returns the same Rectangle.
win.setEnabled(enable)enable BooleanDisable or enable the window.
\nwin.isEnabled()Returns Boolean - whether the window is enabled.
win.setSize(width, height[, animate])width Integerheight Integeranimate Boolean (optional) macOSResizes the window to width and height. If width or height are below any set minimum size constraints the window will snap to its minimum size.
win.getSize()Returns Integer[] - Contains the window's width and height.
win.setContentSize(width, height[, animate])width Integerheight Integeranimate Boolean (optional) macOSResizes the window's client area (e.g. the web page) to width and height.
win.getContentSize()Returns Integer[] - Contains the window's client area's width and height.
win.setMinimumSize(width, height)width Integerheight IntegerSets the minimum size of window to width and height.
win.getMinimumSize()Returns Integer[] - Contains the window's minimum width and height.
win.setMaximumSize(width, height)width Integerheight IntegerSets the maximum size of window to width and height.
win.getMaximumSize()Returns Integer[] - Contains the window's maximum width and height.
win.setResizable(resizable)resizable BooleanSets whether the window can be manually resized by the user.
\nwin.isResizable()Returns Boolean - Whether the window can be manually resized by the user.
win.setMovable(movable) macOS Windowsmovable BooleanSets whether the window can be moved by user. On Linux does nothing.
\nwin.isMovable() macOS WindowsReturns Boolean - Whether the window can be moved by user.
On Linux always returns true.
win.setMinimizable(minimizable) macOS Windowsminimizable BooleanSets whether the window can be manually minimized by user. On Linux does nothing.
\nwin.isMinimizable() macOS WindowsReturns Boolean - Whether the window can be manually minimized by the user.
On Linux always returns true.
win.setMaximizable(maximizable) macOS Windowsmaximizable BooleanSets whether the window can be manually maximized by user. On Linux does nothing.
\nwin.isMaximizable() macOS WindowsReturns Boolean - Whether the window can be manually maximized by user.
On Linux always returns true.
win.setFullScreenable(fullscreenable)fullscreenable BooleanSets whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
\nwin.isFullScreenable()Returns Boolean - Whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
win.setClosable(closable) macOS Windowsclosable BooleanSets whether the window can be manually closed by user. On Linux does nothing.
\nwin.isClosable() macOS WindowsReturns Boolean - Whether the window can be manually closed by user.
On Linux always returns true.
win.setAlwaysOnTop(flag[, level][, relativeLevel])flag Booleanlevel String (optional) macOS Windows - Values include normal,\nfloating, torn-off-menu, modal-panel, main-menu, status,\npop-up-menu, screen-saver, and dockfloating when flag is true. The level is reset to normal when the\nflag is false. Note that from floating to status included, the window is\nplaced below the Dock on macOS and below the taskbar on Windows. From\npop-up-menu to a higher it is shown above the Dock on macOS and above the\ntaskbar on Windows. See the macOS docs for more details.relativeLevel Integer (optional) macOS - The number of layers higher to set\nthis window relative to the given level. The default is 0. Note that Apple\ndiscourages setting levels higher than 1 above screen-saver.Sets whether the window should show always on top of other windows. After\nsetting this, the window is still a normal window, not a toolbox window which\ncan not be focused on.
\nwin.isAlwaysOnTop()Returns Boolean - Whether the window is always on top of other windows.
win.moveAbove(mediaSourceId)mediaSourceId String - Window id in the format of DesktopCapturerSource's id. For example \"window:1869:0\".Moves window above the source window in the sense of z-order. If the\nmediaSourceId is not of type window or if the window does not exist then\nthis method throws an error.
win.moveTop()Moves window to top(z-order) regardless of focus
\nwin.center()Moves window to the center of the screen.
\nwin.setPosition(x, y[, animate])x Integery Integeranimate Boolean (optional) macOSMoves window to x and y.
win.getPosition()Returns Integer[] - Contains the window's current position.
win.setTitle(title)title StringChanges the title of native window to title.
win.getTitle()Returns String - The title of the native window.
Note: The title of the web page can be different from the title of the native\nwindow.
\nwin.setSheetOffset(offsetY[, offsetX]) macOSoffsetY FloatoffsetX Float (optional)Changes the attachment point for sheets on macOS. By default, sheets are\nattached just below the window frame, but you may want to display them beneath\na HTML-rendered toolbar. For example:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nconst toolbarRect = document.getElementById('toolbar').getBoundingClientRect()\nwin.setSheetOffset(toolbarRect.height)\nwin.flashFrame(flag)flag BooleanStarts or stops flashing the window to attract user's attention.
\nwin.setSkipTaskbar(skip)skip BooleanMakes the window not show in the taskbar.
\nwin.setKiosk(flag)flag BooleanEnters or leaves kiosk mode.
\nwin.isKiosk()Returns Boolean - Whether the window is in kiosk mode.
win.isTabletMode() WindowsReturns Boolean - Whether the window is in Windows 10 tablet mode.
Since Windows 10 users can use their PC as tablet,\nunder this mode apps can choose to optimize their UI for tablets, such as\nenlarging the titlebar and hiding titlebar buttons.
\nThis API returns whether the window is in tablet mode, and the resize event\ncan be be used to listen to changes to tablet mode.
win.getMediaSourceId()Returns String - Window id in the format of DesktopCapturerSource's id. For example \"window:1324:0\".
More precisely the format is window:id:other_id where id is HWND on\nWindows, CGWindowID (uint64_t) on macOS and Window (unsigned long) on\nLinux. other_id is used to identify web contents (tabs) so within the same\ntop level window.
win.getNativeWindowHandle()Returns Buffer - The platform-specific handle of the window.
The native type of the handle is HWND on Windows, NSView* on macOS, and\nWindow (unsigned long) on Linux.
win.hookWindowMessage(message, callback) Windowsmessage Integercallback FunctionwParam any - The wParam provided to the WndProclParam any - The lParam provided to the WndProcHooks a windows message. The callback is called when\nthe message is received in the WndProc.
win.isWindowMessageHooked(message) Windowsmessage IntegerReturns Boolean - true or false depending on whether the message is hooked.
win.unhookWindowMessage(message) Windowsmessage IntegerUnhook the window message.
\nwin.unhookAllWindowMessages() WindowsUnhooks all of the window messages.
\nwin.setRepresentedFilename(filename) macOSfilename StringSets the pathname of the file the window represents, and the icon of the file\nwill show in window's title bar.
\nwin.getRepresentedFilename() macOSReturns String - The pathname of the file the window represents.
win.setDocumentEdited(edited) macOSedited BooleanSpecifies whether the window’s document has been edited, and the icon in title\nbar will become gray when set to true.
win.isDocumentEdited() macOSReturns Boolean - Whether the window's document has been edited.
win.focusOnWebView()win.blurWebView()win.capturePage([rect])rect Rectangle (optional) - The bounds to captureReturns Promise<NativeImage> - Resolves with a NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page. If the page is not visible, rect may be empty.
win.loadURL(url[, options])url Stringoptions Object (optional)httpReferrer (String | Referrer) (optional) - An HTTP Referrer URL.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base URL (with trailing path separator) for files to be loaded by the data URL. This is needed only if the specified url is a data URL and needs to load other files.Returns Promise<void> - the promise will resolve when the page has finished loading\n(see did-finish-load), and rejects\nif the page fails to load (see did-fail-load).
Same as webContents.loadURL(url[, options]).
The url can be a remote address (e.g. http://) or a path to a local\nHTML file using the file:// protocol.
To ensure that file URLs are properly formatted, it is recommended to use\nNode's url.format\nmethod:
const url = require('url').format({\n protocol: 'file',\n slashes: true,\n pathname: require('path').join(__dirname, 'index.html')\n})\n\nwin.loadURL(url)\nYou can load a URL using a POST request with URL-encoded data by doing\nthe following:
win.loadURL('http://localhost:8000/post', {\n postData: [{\n type: 'rawData',\n bytes: Buffer.from('hello=world')\n }],\n extraHeaders: 'Content-Type: application/x-www-form-urlencoded'\n})\nwin.loadFile(filePath[, options])filePath Stringoptions Object (optional)query Record<String, String> (optional) - Passed to url.format().search String (optional) - Passed to url.format().hash String (optional) - Passed to url.format().Returns Promise<void> - the promise will resolve when the page has finished loading\n(see did-finish-load), and rejects\nif the page fails to load (see did-fail-load).
Same as webContents.loadFile, filePath should be a path to an HTML\nfile relative to the root of your application. See the webContents docs\nfor more information.
win.reload()Same as webContents.reload.
win.setMenu(menu) Linux Windowsmenu Menu | nullSets the menu as the window's menu bar.
win.removeMenu() Linux WindowsRemove the window's menu bar.
\nwin.setProgressBar(progress[, options])progress Doubleoptions Object (optional)mode String Windows - Mode for the progress bar. Can be none, normal, indeterminate, error or paused.Sets progress value in progress bar. Valid range is [0, 1.0].
\nRemove progress bar when progress < 0;\nChange to indeterminate mode when progress > 1.
\nOn Linux platform, only supports Unity desktop environment, you need to specify\nthe *.desktop file name to desktopName field in package.json. By default,\nit will assume {app.name}.desktop.
On Windows, a mode can be passed. Accepted values are none, normal,\nindeterminate, error, and paused. If you call setProgressBar without a\nmode set (but with a value within the valid range), normal will be assumed.
win.setOverlayIcon(overlay, description) Windowsoverlay NativeImage | null - the icon to display on the bottom\nright corner of the taskbar icon. If this parameter is null, the overlay is\ncleareddescription String - a description that will be provided to Accessibility\nscreen readersSets a 16 x 16 pixel overlay onto the current taskbar icon, usually used to\nconvey some sort of application status or to passively notify the user.
\nwin.setHasShadow(hasShadow)hasShadow BooleanSets whether the window should have a shadow.
\nwin.hasShadow()Returns Boolean - Whether the window has a shadow.
win.setOpacity(opacity) Windows macOSopacity Number - between 0.0 (fully transparent) and 1.0 (fully opaque)Sets the opacity of the window. On Linux, does nothing. Out of bound number\nvalues are clamped to the [0, 1] range.
\nwin.getOpacity()Returns Number - between 0.0 (fully transparent) and 1.0 (fully opaque). On\nLinux, always returns 1.
win.setShape(rects) Windows Linux Experimentalrects Rectangle[] - Sets a shape on the window.\nPassing an empty list reverts the window to being rectangular.Setting a window shape determines the area within the window where the system\npermits drawing and user interaction. Outside of the given region, no pixels\nwill be drawn and no mouse events will be registered. Mouse events outside of\nthe region will not be received by that window, but will fall through to\nwhatever is behind the window.
\nwin.setThumbarButtons(buttons) Windowsbuttons ThumbarButton[]Returns Boolean - Whether the buttons were added successfully
Add a thumbnail toolbar with a specified set of buttons to the thumbnail image\nof a window in a taskbar button layout. Returns a Boolean object indicates\nwhether the thumbnail has been added successfully.
The number of buttons in thumbnail toolbar should be no greater than 7 due to\nthe limited room. Once you setup the thumbnail toolbar, the toolbar cannot be\nremoved due to the platform's limitation. But you can call the API with an empty\narray to clean the buttons.
\nThe buttons is an array of Button objects:
Button Objecticon NativeImage - The icon showing in thumbnail\ntoolbar.click Functiontooltip String (optional) - The text of the button's tooltip.flags String - Control specific states and behaviors of the\nbutton. By default, it is ['enabled'].The flags is an array that can include following Strings:
enabled - The button is active and available to the user.disabled - The button is disabled. It is present, but has a visual state\nindicating it will not respond to user action.dismissonclick - When the button is clicked, the thumbnail window closes\nimmediately.nobackground - Do not draw a button border, use only the image.hidden - The button is not shown to the user.noninteractive - The button is enabled but not interactive; no pressed\nbutton state is drawn. This value is intended for instances where the button\nis used in a notification.win.setThumbnailClip(region) Windowsregion Rectangle - Region of the windowSets the region of the window to show as the thumbnail image displayed when\nhovering over the window in the taskbar. You can reset the thumbnail to be\nthe entire window by specifying an empty region:\n{ x: 0, y: 0, width: 0, height: 0 }.
win.setThumbnailToolTip(toolTip) WindowstoolTip StringSets the toolTip that is displayed when hovering over the window thumbnail\nin the taskbar.
\nwin.setAppDetails(options) Windowsoptions ObjectappId String (optional) - Window's App User Model ID.\nIt has to be set, otherwise the other options will have no effect.appIconPath String (optional) - Window's Relaunch Icon.appIconIndex Integer (optional) - Index of the icon in appIconPath.\nIgnored when appIconPath is not set. Default is 0.relaunchCommand String (optional) - Window's Relaunch Command.relaunchDisplayName String (optional) - Window's Relaunch Display Name.Sets the properties for the window's taskbar button.
\nNote: relaunchCommand and relaunchDisplayName must always be set\ntogether. If one of those properties is not set, then neither will be used.
win.showDefinitionForSelection() macOSSame as webContents.showDefinitionForSelection().
win.setIcon(icon) Windows Linuxicon NativeImage | StringChanges window icon.
\nwin.setWindowButtonVisibility(visible) macOSvisible BooleanSets whether the window traffic light buttons should be visible.
\nwin.setAutoHideMenuBar(hide)hide BooleanSets whether the window menu bar should hide itself automatically. Once set the\nmenu 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()Returns Boolean - Whether menu bar automatically hides itself.
win.setMenuBarVisibility(visible) Windows Linuxvisible BooleanSets whether the menu bar should be visible. If the menu bar is auto-hide, users can still bring up the menu bar by pressing the single Alt key.
win.isMenuBarVisible()Returns Boolean - Whether the menu bar is visible.
win.setVisibleOnAllWorkspaces(visible[, options])visible Booleanoptions Object (optional)visibleOnFullScreen Boolean (optional) macOS - Sets whether\nthe window should be visible above fullscreen windows.skipTransformProcessType Boolean (optional) macOS - Calling\nsetVisibleOnAllWorkspaces will by default transform the process\ntype between UIElementApplication and ForegroundApplication to\nensure the correct behavior. However, this will hide the window\nand dock for a short time every time it is called. If your window\nis already of type UIElementApplication, you can bypass this\ntransformation by passing true to skipTransformProcessType.Sets whether the window should be visible on all workspaces.
\nNote: This API does nothing on Windows.
\nwin.isVisibleOnAllWorkspaces()Returns Boolean - Whether the window is visible on all workspaces.
Note: This API always returns false on Windows.
\nwin.setIgnoreMouseEvents(ignore[, options])ignore Booleanoptions Object (optional)forward Boolean (optional) macOS Windows - If true, forwards mouse move\nmessages to Chromium, enabling mouse related events such as mouseleave.\nOnly used when ignore is true. If ignore is false, forwarding is always\ndisabled regardless of this value.Makes the window ignore all mouse events.
\nAll mouse events happened in this window will be passed to the window below\nthis window, but if this window has focus, it will still receive keyboard\nevents.
\nwin.setContentProtection(enable) macOS Windowsenable BooleanPrevents the window contents from being captured by other apps.
\nOn macOS it sets the NSWindow's sharingType to NSWindowSharingNone.\nOn Windows it calls SetWindowDisplayAffinity with WDA_EXCLUDEFROMCAPTURE.\nFor Windows 10 version 2004 and up the window will be removed from capture entirely,\nolder Windows versions behave as if WDA_MONITOR is applied capturing a black window.
win.setFocusable(focusable) macOS Windowsfocusable BooleanChanges whether the window can be focused.
\nOn macOS it does not remove the focus from the window.
\nwin.isFocusable() macOS WindowsReturns whether the window can be focused.
\nwin.setParentWindow(parent)parent BrowserWindow | nullSets parent as current window's parent window, passing null will turn\ncurrent window into a top-level window.
win.getParentWindow()Returns BrowserWindow - The parent window.
win.getChildWindows()Returns BrowserWindow[] - All child windows.
win.setAutoHideCursor(autoHide) macOSautoHide BooleanControls whether to hide cursor when typing.
\nwin.selectPreviousTab() macOSSelects the previous tab when native tabs are enabled and there are other\ntabs in the window.
\nwin.selectNextTab() macOSSelects the next tab when native tabs are enabled and there are other\ntabs in the window.
\nwin.mergeAllWindows() macOSMerges all windows into one window with multiple tabs when native tabs\nare enabled and there is more than one open window.
\nwin.moveTabToNewWindow() macOSMoves the current tab into a new window if native tabs are enabled and\nthere is more than one tab in the current window.
\nwin.toggleTabBar() macOSToggles the visibility of the tab bar if native tabs are enabled and\nthere is only one tab in the current window.
\nwin.addTabbedWindow(browserWindow) macOSbrowserWindow BrowserWindowAdds a window as a tab on this window, after the tab for the window instance.
\nwin.setVibrancy(type) macOStype String | null - Can be appearance-based, light, dark, titlebar,\nselection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, or under-page. See\nthe macOS documentation for more details.Adds a vibrancy effect to the browser window. Passing null or an empty string\nwill remove the vibrancy effect on the window.
Note that appearance-based, light, dark, medium-light, and ultra-dark have been\ndeprecated and will be removed in an upcoming version of macOS.
win.setTrafficLightPosition(position) macOSposition PointSet a custom position for the traffic light buttons in frameless window.
\nwin.getTrafficLightPosition() macOSReturns Point - The custom position for the traffic light buttons in\nframeless window.
win.setTouchBar(touchBar) macOStouchBar TouchBar | nullSets the touchBar layout for the current window. Specifying null or\nundefined clears the touch bar. This method only has an effect if the\nmachine has a touch bar and is running on macOS 10.12.1+.
Note: The TouchBar API is currently experimental and may change or be\nremoved in future Electron releases.
\nwin.setBrowserView(browserView) ExperimentalbrowserView BrowserView | null - Attach browserView to win.\nIf there are other BrowserViews attached, they will be removed from\nthis window.win.getBrowserView() ExperimentalReturns BrowserView | null - The BrowserView attached to win. Returns null\nif one is not attached. Throws an error if multiple BrowserViews are attached.
win.addBrowserView(browserView) ExperimentalbrowserView BrowserViewReplacement API for setBrowserView supporting work with multi browser views.
\nwin.removeBrowserView(browserView) ExperimentalbrowserView BrowserViewwin.setTopBrowserView(browserView) ExperimentalbrowserView BrowserViewRaises browserView above other BrowserViews attached to win.\nThrows an error if browserView is not attached to win.
win.getBrowserViews() ExperimentalReturns BrowserView[] - an array of all BrowserViews that have been attached\nwith addBrowserView or setBrowserView.
Note: The BrowserView API is currently experimental and may change or be\nremoved in future Electron releases.
", "title": "BrowserWindow", "description": "Create and control browser windows." }, "/docs/api/browser-window-proxy": { "locale": "en-US", "slug": "browser-window-proxy", "href": "/docs/api/browser-window-proxy", "crowdinFileId": "256285", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-window-proxy.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nManipulate the child browser window
\n
Process: Renderer
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The BrowserWindowProxy object is returned from window.open and provides\nlimited functionality with the child window.
The BrowserWindowProxy object has the following instance methods:
win.blur()Removes focus from the child window.
\nwin.close()Forcefully closes the child window without calling its unload event.
\nwin.eval(code)code StringEvaluates the code in the child window.
\nwin.focus()Focuses the child window (brings the window to front).
\nwin.print()Invokes the print dialog on the child window.
\nwin.postMessage(message, targetOrigin)message anytargetOrigin StringSends a message to the child window with the specified origin or * for no\norigin preference.
In addition to these methods, the child window implements window.opener object\nwith no properties and a single method.
The BrowserWindowProxy object has the following instance properties:
win.closedA Boolean that is set to true after the child window gets closed.
Follow the guidelines below for building Electron itself, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nCheck the build prerequisites for your platform before proceeding
\n\nElectron's Build Tools automate much of the setup for compiling Electron from source with different configurations and build targets. If you wish to set up the environment manually, the instructions are listed below.
\nYou'll need to install depot_tools, the toolset\nused for fetching Chromium and its dependencies.
Also, on Windows, you'll need to set the environment variable\nDEPOT_TOOLS_WIN_TOOLCHAIN=0. To do so, open Control Panel → System and Security → System → Advanced system settings and add a system variable\nDEPOT_TOOLS_WIN_TOOLCHAIN with value 0. This tells depot_tools to use\nyour locally installed version of Visual Studio (by default, depot_tools will\ntry to download a Google-internal version that only Googlers have access to).
If you plan on checking out Electron more than once (for example, to have\nmultiple parallel directories checked out to different branches), using the git\ncache will speed up subsequent calls to gclient. To do this, set a\nGIT_CACHE_PATH environment variable:
$ export GIT_CACHE_PATH=\"${HOME}/.git_cache\"\n$ mkdir -p \"${GIT_CACHE_PATH}\"\n# This will use about 16G.\n$ mkdir electron && cd electron\n$ gclient config --name \"src/electron\" --unmanaged https://github.com/electron/electron\n$ gclient sync --with_branch_heads --with_tags\n# This will take a while, go get a coffee.\n\n\nInstead of
\nhttps://github.com/electron/electron, you can use your own fork\nhere (something likehttps://github.com/<username>/electron).
If you intend to git pull or git push from the official electron\nrepository in the future, you now need to update the respective folder's\norigin URLs.
$ cd src/electron\n$ git remote remove origin\n$ git remote add origin https://github.com/electron/electron\n$ git checkout main\n$ git branch --set-upstream-to=origin/main\n$ cd -\n📝 gclient works by checking a file called DEPS inside the\nsrc/electron folder for dependencies (like Chromium or Node.js).\nRunning gclient sync -f ensures that all dependencies required\nto build Electron match that file.
So, in order to pull, you'd run the following commands:
\n$ cd src/electron\n$ git pull\n$ gclient sync -f\n$ cd src\n$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nOr on Windows (without the optional argument):
\n$ cd src\n$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\\buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\")\"\nThis will generate a build directory out/Testing under src/ with\nthe testing build configuration. You can replace Testing with another name,\nbut it should be a subdirectory of out.\nAlso you shouldn't have to run gn gen again—if you want to change the\nbuild arguments, you can run gn args out/Testing to bring up an editor.
To see the list of available build configuration options, run gn args out/Testing --list.
For generating Testing build config of\nElectron:
\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nFor generating Release (aka \"non-component\" or \"static\") build config of\nElectron:
\n$ gn gen out/Release --args=\"import(\\\"//electron/build/args/release.gn\\\") $GN_EXTRA_ARGS\"\nTo build, run ninja with the electron target:\nNota Bene: This will also take a while and probably heat up your lap.
For the testing configuration:
\n$ ninja -C out/Testing electron\nFor the release configuration:
\n$ ninja -C out/Release electron\nThis will build all of what was previously 'libchromiumcontent' (i.e. the\ncontent/ directory of chromium and its dependencies, incl. WebKit and V8),\nso it will take a while.
The built executable will be under ./out/Testing:
$ ./out/Testing/Electron.app/Contents/MacOS/Electron\n# or, on Windows\n$ ./out/Testing/electron.exe\n# or, on Linux\n$ ./out/Testing/electron\nOn linux, first strip the debugging and symbol information:
\nelectron/script/strip-binaries.py -d out/Release\nTo package the electron build as a distributable zip file:
\nninja -C out/Release electron:electron_dist_zip\nTo compile for a platform that isn't the same as the one you're building on,\nset the target_cpu and target_os GN arguments. For example, to compile an\nx86 target from an x64 host, specify target_cpu = \"x86\" in gn args.
$ gn gen out/Testing-x86 --args='... target_cpu = \"x86\"'\nNot all combinations of source and target CPU/OS are supported by Chromium.
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Host | Target | Status |
|---|---|---|
| Windows x64 | Windows arm64 | Experimental |
| Windows x64 | Windows x86 | Automatically tested |
| Linux x64 | Linux x86 | Automatically tested |
If you test other combinations and find them to work, please update this document :)
\nSee the GN reference for allowable values of target_os\nand target_cpu.
To cross-compile for Windows on Arm, follow Chromium's guide to get the necessary dependencies, SDK and libraries, then build with ELECTRON_BUILDING_WOA=1 in your environment before running gclient sync.
set ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nOr (if using PowerShell):
\n$env:ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nNext, run gn gen as above with target_cpu=\"arm64\".
To run the tests, you'll first need to build the test modules against the\nsame version of Node.js that was built as part of the build process. To\ngenerate build headers for the modules to compile against, run the following\nunder src/ directory.
$ ninja -C out/Testing third_party/electron_node:headers\nYou can now run the tests.
\nIf you're debugging something, it can be helpful to pass some extra flags to\nthe Electron binary:
\n$ npm run test -- \\\n --enable-logging -g 'BrowserWindow module'\nIt is possible to share the gclient git cache with other machines by exporting it as\nSMB share on linux, but only one process/machine can be using the cache at a\ntime. The locks created by git-cache script will try to prevent this, but it may\nnot work perfectly in a network.
\nOn Windows, SMBv2 has a directory cache that will cause problems with the git\ncache script, so it is necessary to disable it by setting the registry key
\nHKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\\DirectoryCacheLifetime\nto 0. More information: https://stackoverflow.com/a/9935126
\nThis can be set quickly in powershell (ran as administrator):
\nNew-ItemProperty -Path \"HKLM:\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force\nIf gclient sync is interrupted the git tree may be left in a bad state, leading to a cryptic message when running gclient sync in the future:
2> Conflict while rebasing this branch.\n2> Fix the conflict and run gclient again.\n2> See man git-rebase for details.\nIf there are no git conflicts or rebases in src/electron, you may need to abort a git am in src:
$ cd ../\n$ git am --abort\n$ cd electron\n$ gclient sync -f\nIf you see a prompt for Username for 'https://chrome-internal.googlesource.com': when running gclient sync on Windows, it's probably because the DEPOT_TOOLS_WIN_TOOLCHAIN environment variable is not set to 0. Open Control Panel → System and Security → System → Advanced system settings and add a system variable\nDEPOT_TOOLS_WIN_TOOLCHAIN with value 0. This tells depot_tools to use\nyour locally installed version of Visual Studio (by default, depot_tools will\ntry to download a Google-internal version that only Googlers have access to).
Follow the guidelines below for building Electron itself on Linux, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nAt least 25GB disk space and 8GB RAM.
\nPython 2.7.x. Some distributions like CentOS 6.x still use Python 2.6.x\nso you may need to check your Python version with python -V.
Please also ensure that your system and Python version support at least TLS 1.2.\nFor a quick test, run the following script:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security\nprotocol, use your system's package manager to update Python to the latest\nversion in the 2.7.x branch. Alternatively, visit https://www.python.org/downloads/\nfor detailed instructions.
\nNode.js. There are various ways to install Node. You can download\nsource code from nodejs.org and compile it.\nDoing so permits installing Node on your own home directory as a standard user.\nOr try repositories such as NodeSource.
\nclang 3.4 or later.
\nDevelopment headers of GTK 3 and libnotify.
\nOn Ubuntu, install the following libraries:
\n$ sudo apt-get install build-essential clang libdbus-1-dev libgtk-3-dev \\\n libnotify-dev libgnome-keyring-dev \\\n libasound2-dev libcap-dev libcups2-dev libxtst-dev \\\n libxss1 libnss3-dev gcc-multilib g++-multilib curl \\\n gperf bison python-dbusmock openjdk-8-jre\nOn RHEL / CentOS, install the following libraries:
\n$ sudo yum install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Fedora, install the following libraries:
\n$ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Arch Linux / Manjaro, install the following libraries:
\n$ sudo pacman -Syu base-devel clang libdbus gtk2 libnotify \\\n libgnome-keyring alsa-lib libcap libcups libxtst \\\n libxss nss gcc-multilib curl gperf bison \\\n python2 python-dbusmock jdk8-openjdk\nOther distributions may offer similar packages for installation via package\nmanagers such as pacman. Or one can compile from source code.
\nIf you want to build for an arm target you should also install the following\ndependencies:
$ sudo apt-get install libc6-dev-armhf-cross linux-libc-dev-armhf-cross \\\n g++-arm-linux-gnueabihf\nSimilarly for arm64, install the following:
$ sudo apt-get install libc6-dev-arm64-cross linux-libc-dev-arm64-cross \\\n g++-aarch64-linux-gnu\nAnd to cross-compile for arm or ia32 targets, you should pass the\ntarget_cpu parameter to gn gen:
$ gn gen out/Testing --args='import(...) target_cpu=\"arm\"'\nPrebuilt clang will try to link to libtinfo.so.5. Depending on the host\narchitecture, symlink to appropriate libncurses:
$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5\nThe default building configuration is targeted for major desktop Linux\ndistributions. To build for a specific distribution or device, the following\ninformation may help you.
\nclang instead of downloaded clang binariesBy default Electron is built with prebuilt\nclang binaries provided by the\nChromium project. If for some reason you want to build with the clang\ninstalled in your system, you can specify the clang_base_path argument in the\nGN args.
For example if you installed clang under /usr/local/bin/clang:
$ gn gen out/Testing --args='import(\"//electron/build/args/testing.gn\") clang_base_path = \"/usr/local/bin\"'\nclangBuilding Electron with compilers other than clang is not supported.
Follow the guidelines below for building Electron itself on macOS, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nPlease also ensure that your system and Python version support at least TLS 1.2.\nThis depends on both your version of macOS and Python. For a quick test, run:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security\nprotocol, you can either update macOS to High Sierra or install a new version\nof Python 2.7.x. To upgrade Python, use Homebrew:
\n$ brew install python@2 && brew link python@2 --force\nIf you are using Python as provided by Homebrew, you also need to install\nthe following Python modules:
\nYou can use pip to install it:
$ pip install pyobjc\nIf you're developing Electron and don't plan to redistribute your\ncustom Electron build, you may skip this section.
\nOfficial Electron builds are built with Xcode 12.2, and the macOS 11.0 SDK. Building with a newer SDK works too, but the releases currently use the 11.0 SDK.
\nFollow the guidelines below for building Electron itself on Windows, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nvs2019_install = DRIVE:\\path\\to\\Microsoft Visual Studio\\2019\\Community, replacing 2019 and Community with your installed versions and replacing DRIVE: with the drive that Visual Studio is on. Often, this will be C:.WINDOWSSDKDIR = DRIVE:\\path\\to\\Windows Kits\\10, replacing DRIVE: with the drive that Windows Kits is on. Often, this will be C:.symstore.exe is used for creating a symbol\nstore from .pdb files.Modify → Individual Components, scroll down and select the appropriate\nWindows SDK to install. Another option would be to look at the\nWindows SDK and emulator archive\nand download the standalone version of the SDK respectively.Control Panel → Programs → Programs and Features → Select the \"Windows Software Development Kit\" →\nChange → Change → Check \"Debugging Tools For Windows\" → Change.\nOr, you can download the standalone SDK installer and use it to install the Debugging Tools.If you don't currently have a Windows installation,\ndev.microsoftedge.com\nhas timebombed versions of Windows that you can use to build Electron.
\nBuilding Electron is done entirely with command-line scripts and cannot be done\nwith Visual Studio. You can develop Electron with any editor but support for\nbuilding with Visual Studio will come in the future.
\nNote: Even though Visual Studio is not used for building, it's still\nrequired because we need the build toolchains it provides.
\nWindows Security doesn't like one of the files in the Chromium source code\n(see https://crbug.com/441184), so it will constantly delete it, causing gclient sync issues.\nYou can exclude the source tree from being monitored by Windows Security by\nfollowing these instructions.
To build for the 32bit target, you need to pass target_cpu = \"x86\" as a GN\narg. You can build the 32bit target alongside the 64bit target by using a\ndifferent output directory for GN, e.g. out/Release-x86, with different\narguments.
$ gn gen out/Release-x86 --args=\"import(\\\"//electron/build/args/release.gn\\\") target_cpu=\\\"x86\\\"\"\nThe other building steps are exactly the same.
\nTo generate a Visual Studio project, you can pass the --ide=vs2017 parameter\nto gn gen:
$ gn gen out/Testing --ide=vs2017\nIf you encountered an error like Command xxxx not found, you may try to use\nthe VS2015 Command Prompt console to execute the build scripts.
Make sure you have the latest Visual Studio update installed.
\nTry reinstalling 32bit Node.js.
\nCreating that directory should fix the problem:
\n$ mkdir ~\\AppData\\Roaming\\npm\nYou may get this error if you are using Git Bash for building, you should use\nPowerShell or VS2015 Command Prompt instead.
\nnode.js has some extremely long pathnames, and by default git on windows doesn't handle long pathnames correctly (even though windows supports them). This should fix it:
\n$ git config --system core.longpaths true\nThis can happen during build, when Debugging Tools for Windows has been installed with Windows Driver Kit. Uninstall Windows Driver Kit and install Debugging Tools with steps described above.
\nMake sure you have installed pywin32 with pip install pywin32.
This bug is a \"feature\" of Windows' command prompt. It happens when clicking inside the prompt window with\nQuickEdit enabled and is intended to allow selecting and copying output text easily.\nSince each accidental click will pause the build process, you might want to disable this\nfeature in the command prompt properties.
Electron uses GN for project generation and\nninja for building. Project configurations can\nbe found in the .gn and .gni files.
The following gn files contain the main rules for building Electron:
BUILD.gn defines how Electron itself is built and\nincludes the default configurations for linking with Chromium.build/args/{debug,release,all}.gn contain the default build arguments for\nbuilding Electron.Since Chromium is quite a large project, the final linking stage can take\nquite a few minutes, which makes it hard for development. In order to solve\nthis, Chromium introduced the \"component build\", which builds each component as\na separate shared library, making linking very quick but sacrificing file size\nand performance.
\nElectron inherits this build option from Chromium. In Debug builds, the\nbinary will be linked to a shared library version of Chromium's components to\nachieve fast linking time; for Release builds, the binary will be linked to\nthe static library versions, so we can have the best possible binary size and\nperformance.
NB this section is out of date and contains information that is no longer\nrelevant to the GN-built electron.
\nTest your changes conform to the project coding style using:
\n$ npm run lint\nTest functionality using:
\n$ npm test\nWhenever you make changes to Electron source code, you'll need to re-run the\nbuild before the tests:
\n$ npm run build && npm test\nYou can make the test suite run faster by isolating the specific test or block\nyou're currently working on using Mocha's\nexclusive tests feature. Append\n.only to any describe or it function call:
describe.only('some feature', () => {\n // ... only tests in this block will be run\n})\nAlternatively, you can use mocha's grep option to only run tests matching the\ngiven regular expression pattern:
$ npm test -- --grep child_process\nTests that include native modules (e.g. runas) can't be executed with the\ndebug build (see #2558 for\ndetails), but they will work with the release build.
To run the tests with the release build use:
\n$ npm test -- -R\ndata String - PEM encoded dataissuer CertificatePrincipal - Issuer principalissuerName String - Issuer's Common NameissuerCert Certificate - Issuer certificate (if not self-signed)subject CertificatePrincipal - Subject principalsubjectName String - Subject's Common NameserialNumber String - Hex value represented stringvalidStart Number - Start date of the certificate being valid in secondsvalidExpiry Number - End date of the certificate being valid in secondsfingerprint String - Fingerprint of the certificatecommonName String - Common Name.organizations String[] - Organization names.organizationUnits String[] - Organization Unit names.locality String - Locality.state String - State or province.country String - Country or region.\n\nA collection of resources for learning about Chromium and tracking its development
\n
See also V8 Development
", "title": "Chromium Development", "description": "A collection of resources for learning about Chromium and tracking its development" }, "/docs/development/clang-format": { "locale": "en-US", "slug": "clang-format", "href": "/docs/development/clang-format", "crowdinFileId": "256143", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/clang-format.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "clang-format is a tool to\nautomatically format C/C++/Objective-C code, so that developers don't need to\nworry about style issues during code reviews.
It is highly recommended to format your changed C++ code before opening pull\nrequests, which will save you and the reviewers' time.
\nYou can install clang-format and git-clang-format via\nnpm install -g clang-format.
To automatically format a file according to Electron C++ code style, run\nclang-format -i path/to/electron/file.cc. It should work on macOS/Linux/Windows.
The workflow to format your changed code:
\ngit add your_changed_file.cc.git-clang-format, and you will probably see modifications in\nyour_changed_file.cc, these modifications are generated from clang-format.git add your_changed_file.cc, and commit your change.If you want to format the changed code on your latest git commit (HEAD), you can\nrun git-clang-format HEAD~1. See git-clang-format -h for more details.
You can also integrate clang-format directly into your favorite editors.\nFor further guidance on setting up editor integration, see these pages:
clang-tidy is a tool to\nautomatically check C/C++/Objective-C code for style violations, programming\nerrors, and best practices.
Electron's clang-tidy integration is provided as a linter script which can\nbe run with npm run lint:clang-tidy. While clang-tidy checks your on-disk\nfiles, you need to have built Electron so that it knows which compiler flags\nwere used. There is one required option for the script --output-dir, which\ntells the script which build directory to pull the compilation information\nfrom. A typical usage would be:\nnpm run lint:clang-tidy --out-dir ../out/Testing
With no filenames provided, all C/C++/Objective-C files will be checked.\nYou can provide a list of files to be checked by passing the filenames after\nthe options:\nnpm run lint:clang-tidy --out-dir ../out/Testing shell/browser/api/electron_api_app.cc
While clang-tidy has a\nlong list\nof possible checks, in Electron only a few are enabled by default. At the\nmoment Electron doesn't have a .clang-tidy config, so clang-tidy will\nfind the one from Chromium at src/.clang-tidy and use the checks which\nChromium has enabled. You can change which checks are run by using the\n--checks= option. This is passed straight through to clang-tidy, so see\nits documentation for full details. Wildcards can be used, and checks can\nbe disabled by prefixing a -. By default any checks listed are added to\nthose in .clang-tidy, so if you'd like to limit the checks to specific\nones you should first exclude all checks then add back what you want, like\n--checks=-*,performance*.
Running clang-tidy is rather slow - internally it compiles each file and\nthen runs the checks so it will always be some factor slower than compilation.\nWhile you can use parallel runs to speed it up using the --jobs|-j option,\nclang-tidy also uses a lot of memory during its checks, so it can easily\nrun into out-of-memory errors. As such the default number of jobs is one.
\n\nMake HTTP/HTTPS requests.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
ClientRequest implements the Writable Stream\ninterface and is therefore an EventEmitter.
new ClientRequest(options)options (Object | String) - If options is a String, it is interpreted as\nthe request URL. If it is an object, it is expected to fully specify an HTTP request via the\nfollowing properties:method String (optional) - The HTTP request method. Defaults to the GET\nmethod.url String (optional) - The request URL. Must be provided in the absolute\nform with the protocol scheme specified as http or https.session Session (optional) - The Session instance with\nwhich the request is associated.partition String (optional) - The name of the partition\nwith which the request is associated. Defaults to the empty string. The\nsession option supersedes partition. Thus if a session is explicitly\nspecified, partition is ignored.credentials String (optional) - Can be include or omit. Whether to\nsend credentials with this\nrequest. If set to include, credentials from the session associated with\nthe request will be used. If set to omit, credentials will not be sent\nwith the request (and the 'login' event will not be triggered in the\nevent of a 401). This matches the behavior of the\nfetch\noption of the same name. If this option is not specified, authentication\ndata from the session will be sent, and cookies will not be sent (unless\nuseSessionCookies is set).useSessionCookies Boolean (optional) - Whether to send cookies with this\nrequest from the provided session. If credentials is specified, this\noption has no effect. Default is false.protocol String (optional) - Can be http: or https:. The protocol\nscheme in the form 'scheme:'. Defaults to 'http:'.host String (optional) - The server host provided as a concatenation of\nthe hostname and the port number 'hostname:port'.hostname String (optional) - The server host name.port Integer (optional) - The server's listening port number.path String (optional) - The path part of the request URL.redirect String (optional) - Can be follow, error or manual. The\nredirect mode for this request. When mode is error, any redirection will\nbe aborted. When mode is manual the redirection will be cancelled unless\nrequest.followRedirect is invoked synchronously\nduring the redirect event. Defaults to follow.origin String (optional) - The origin URL of the request.options properties such as protocol, host, hostname, port and path\nstrictly follow the Node.js model as described in the\nURL module.
For instance, we could have created the same request to 'github.com' as follows:
\nconst request = net.request({\n method: 'GET',\n protocol: 'https:',\n hostname: 'github.com',\n port: 443,\n path: '/'\n})\nReturns:
\nresponse IncomingMessage - An object representing the HTTP response message.Returns:
\nauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (optional)password String (optional)Emitted when an authenticating proxy is asking for user credentials.
\nThe callback function is expected to be called back with user credentials:
username Stringpassword Stringrequest.on('login', (authInfo, callback) => {\n callback('username', 'password')\n})\nProviding empty credentials will cancel the request and report an authentication\nerror on the response object:
\nrequest.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`);\n response.on('error', (error) => {\n console.log(`ERROR: ${JSON.stringify(error)}`)\n })\n})\nrequest.on('login', (authInfo, callback) => {\n callback()\n})\nEmitted just after the last chunk of the request's data has been written into\nthe request object.
Emitted when the request is aborted. The abort event will not be fired if\nthe request is already closed.
Returns:
\nerror Error - an error object providing some information about the failure.Emitted when the net module fails to issue a network request. Typically when\nthe request object emits an error event, a close event will subsequently\nfollow and no response object will be provided.
Emitted as the last event in the HTTP request-response transaction. The close\nevent indicates that no more events will be emitted on either the request or\nresponse objects.
Returns:
\nstatusCode Integermethod StringredirectUrl StringresponseHeaders Record<String, String[]>Emitted when the server returns a redirect response (e.g. 301 Moved\nPermanently). Calling request.followRedirect will\ncontinue with the redirection. If this event is handled,\nrequest.followRedirect must be called\nsynchronously, otherwise the request will be cancelled.
request.chunkedEncodingA Boolean specifying whether the request will use HTTP chunked transfer encoding\nor not. Defaults to false. The property is readable and writable, however it can\nbe set only before the first write operation as the HTTP headers are not yet put\non the wire. Trying to set the chunkedEncoding property after the first write\nwill throw an error.
Using chunked encoding is strongly recommended if you need to send a large\nrequest body as data will be streamed in small chunks instead of being\ninternally buffered inside Electron process memory.
\nrequest.setHeader(name, value)name String - An extra HTTP header name.value String - An extra HTTP header value.Adds an extra HTTP header. The header name will be issued as-is without\nlowercasing. It can be called only before first write. Calling this method after\nthe first write will throw an error. If the passed value is not a String, its\ntoString() method will be called to obtain the final value.
Certain headers are restricted from being set by apps. These headers are\nlisted below. More information on restricted headers can be found in\nChromium's header utils.
\nContent-LengthHostTrailer or TeUpgradeCookie2Keep-AliveTransfer-EncodingAdditionally, setting the Connection header to the value upgrade is also disallowed.
request.getHeader(name)name String - Specify an extra header name.Returns String - The value of a previously set extra header name.
request.removeHeader(name)name String - Specify an extra header name.Removes a previously set extra header name. This method can be called only\nbefore first write. Trying to call it after the first write will throw an error.
\nrequest.write(chunk[, encoding][, callback])chunk (String | Buffer) - A chunk of the request body's data. If it is a\nstring, it is converted into a Buffer using the specified encoding.encoding String (optional) - Used to convert string chunks into Buffer\nobjects. Defaults to 'utf-8'.callback Function (optional) - Called after the write operation ends.callback is essentially a dummy function introduced in the purpose of keeping\nsimilarity with the Node.js API. It is called asynchronously in the next tick\nafter chunk content have been delivered to the Chromium networking layer.\nContrary to the Node.js implementation, it is not guaranteed that chunk\ncontent have been flushed on the wire before callback is called.
Adds a chunk of data to the request body. The first write operation may cause\nthe request headers to be issued on the wire. After the first write operation,\nit is not allowed to add or remove a custom header.
\nrequest.end([chunk][, encoding][, callback])chunk (String | Buffer) (optional)encoding String (optional)callback Function (optional)Sends the last chunk of the request data. Subsequent write or end operations\nwill not be allowed. The finish event is emitted just after the end operation.
request.abort()Cancels an ongoing HTTP transaction. If the request has already emitted the\nclose event, the abort operation will have no effect. Otherwise an ongoing\nevent will emit abort and close events. Additionally, if there is an ongoing\nresponse object,it will emit the aborted event.
request.followRedirect()Continues any pending redirection. Can only be called during a 'redirect'\nevent.
request.getUploadProgress()Returns Object:
active Boolean - Whether the request is currently active. If this is false\nno other properties will be setstarted Boolean - Whether the upload has started. If this is false both\ncurrent and total will be set to 0.current Integer - The number of bytes that have been uploaded so fartotal Integer - The number of bytes that will be uploaded this requestYou can use this method in conjunction with POST requests to get the progress\nof a file upload or other data transfer.
\n\n\nPerform copy and paste operations on the system clipboard.
\n
On Linux, there is also a selection clipboard. To manipulate it\nyou need to pass selection to each method:
const { clipboard } = require('electron')\n\nclipboard.writeText('Example String', 'selection')\nconsole.log(clipboard.readText('selection'))\nThe clipboard module has the following methods:
Note: Experimental APIs are marked as such and could be removed in future.
\nclipboard.readText([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Returns String - The content in the clipboard as plain text.
const { clipboard } = require('electron')\n\nclipboard.writeText('hello i am a bit of text!')\n\nconst text = clipboard.readText()\nconsole.log(text)\n// hello i am a bit of text!'\nclipboard.writeText(text[, type])text Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Writes the text into the clipboard as plain text.
const { clipboard } = require('electron')\n\nconst text = 'hello i am a bit of text!'\nclipboard.writeText(text)\nclipboard.readHTML([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Returns String - The content in the clipboard as markup.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b>')\nconst html = clipboard.readHTML()\n\nconsole.log(html)\n// <meta charset='utf-8'><b>Hi</b>\nclipboard.writeHTML(markup[, type])markup Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Writes markup to the clipboard.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b')\nclipboard.readImage([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Returns NativeImage - The image content in the clipboard.
clipboard.writeImage(image[, type])image NativeImagetype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Writes image to the clipboard.
clipboard.readRTF([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Returns String - The content in the clipboard as RTF.
const { clipboard } = require('electron')\n\nclipboard.writeRTF('{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}')\n\nconst rtf = clipboard.readRTF()\nconsole.log(rtf)\n// {\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}\nclipboard.writeRTF(text[, type])text Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Writes the text into the clipboard in RTF.
const { clipboard } = require('electron')\n\nconst rtf = '{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}'\nclipboard.writeRTF(rtf)\nclipboard.readBookmark() macOS WindowsReturns Object:
title Stringurl StringReturns an Object containing title and url keys representing the bookmark in\nthe clipboard. The title and url values will be empty strings when the\nbookmark is unavailable.
clipboard.writeBookmark(title, url[, type]) macOS Windowstitle Stringurl Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Writes the title and url into the clipboard as a bookmark.
Note: Most apps on Windows don't support pasting bookmarks into them so\nyou can use clipboard.write to write both a bookmark and fallback text to the\nclipboard.
const { clipboard } = require('electron')\n\nclipboard.writeBookmark({\n text: 'https://electronjs.org',\n bookmark: 'Electron Homepage'\n})\nclipboard.readFindText() macOSReturns String - The text on the find pasteboard, which is the pasteboard that holds information about the current state of the active application’s find panel.
This method uses synchronous IPC when called from the renderer process.\nThe cached value is reread from the find pasteboard whenever the application is activated.
\nclipboard.writeFindText(text) macOStext StringWrites the text into the find pasteboard (the pasteboard that holds information about the current state of the active application’s find panel) as plain text. This method uses synchronous IPC when called from the renderer process.
clipboard.clear([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Clears the clipboard content.
\nclipboard.availableFormats([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Returns String[] - An array of supported formats for the clipboard type.
const { clipboard } = require('electron')\n\nconst formats = clipboard.availableFormats()\nconsole.log(formats)\n// [ 'text/plain', 'text/html' ]\nclipboard.has(format[, type]) Experimentalformat Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Returns Boolean - Whether the clipboard supports the specified format.
const { clipboard } = require('electron')\n\nconst hasFormat = clipboard.has('<p>selection</p>')\nconsole.log(hasFormat)\n// 'true' or 'false'\nclipboard.read(format) Experimentalformat StringReturns String - Reads format type from the clipboard.
format should contain valid ASCII characters and have / separator.\na/c, a/bc are valid formats while /abc, abc/, a/, /a, a\nare not valid.
clipboard.readBuffer(format) Experimentalformat StringReturns Buffer - Reads format type from the clipboard.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('this is binary', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\n\nconst ret = clipboard.readBuffer('public/utf8-plain-text')\n\nconsole.log(buffer.equals(out))\n// true\nclipboard.writeBuffer(format, buffer[, type]) Experimentalformat Stringbuffer Buffertype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Writes the buffer into the clipboard as format.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('writeBuffer', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\nclipboard.write(data[, type])data Objecttext String (optional)html String (optional)image NativeImage (optional)rtf String (optional)bookmark String (optional) - The title of the URL at text.type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Writes data to the clipboard.
const { clipboard } = require('electron')\n\nclipboard.write({\n text: 'test',\n html: '<b>Hi</b>',\n rtf: '{\\\\rtf1\\\\utf8 text}',\n bookmark: 'a title'\n})\n\nconsole.log(clipboard.readText())\n// 'test'\n\nconsole.log(clipboard.readHTML())\n// <meta charset='utf-8'><b>Hi</b>\n\nconsole.log(clipboard.readRTF())\n// '{\\\\rtf1\\\\utf8 text}'\n\nconsole.log(clipboard.readBookmark())\n// { title: 'a title', url: 'test' }\nCode signing is a security technology that you use to certify that an app was\ncreated by you.
\nOn macOS the system can detect any change to the app, whether the change is\nintroduced accidentally or by malicious code.
\nOn Windows, the system assigns a trust level to your code signing certificate\nwhich if you don't have, or if your trust level is low, will cause security\ndialogs to appear when users start using your application. Trust level builds\nover time so it's better to start code signing as early as possible.
\nWhile it is possible to distribute unsigned apps, it is not recommended. Both\nWindows and macOS will, by default, prevent either the download or the execution\nof unsigned applications. Starting with macOS Catalina (version 10.15), users\nhave to go through multiple manual steps to open unsigned applications.
\n![\"macOS](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/gatekeeper.png\")
As you can see, users get two options: Move the app straight to the trash or\ncancel running it. You don't want your users to see that dialog.
\nIf you are building an Electron app that you intend to package and distribute,\nit should be code-signed.
\nProperly preparing macOS applications for release requires two steps: First, the\napp needs to be code-signed. Then, the app needs to be uploaded to Apple for a\nprocess called \"notarization\", where automated systems will further verify that\nyour app isn't doing anything to endanger its users.
\nTo start the process, ensure that you fulfill the requirements for signing and\nnotarizing your app:
\nElectron's ecosystem favors configuration and freedom, so there are multiple\nways to get your application signed and notarized.
\nelectron-forgeIf you're using Electron's favorite build tool, getting your application signed\nand notarized requires a few additions to your configuration. Forge is a\ncollection of the official Electron tools, using electron-packager,\nelectron-osx-sign, and electron-notarize under the hood.
Let's take a look at an example configuration with all required fields. Not all\nof them are required: the tools will be clever enough to automatically find a\nsuitable identity, for instance, but we recommend that you are explicit.
{\n \"name\": \"my-app\",\n \"version\": \"0.0.1\",\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"osxSign\": {\n \"identity\": \"Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)\",\n \"hardened-runtime\": true,\n \"entitlements\": \"entitlements.plist\",\n \"entitlements-inherit\": \"entitlements.plist\",\n \"signature-flags\": \"library\"\n },\n \"osxNotarize\": {\n \"appleId\": \"felix@felix.fun\",\n \"appleIdPassword\": \"my-apple-id-password\",\n }\n }\n }\n }\n}\nThe plist file referenced here needs the following macOS-specific entitlements\nto assure the Apple security mechanisms that your app is doing these things\nwithout meaning any harm:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nNote that up until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required\nas well. However, it should not be used anymore if it can be avoided.
To see all of this in action, check out Electron Fiddle's source code,\nespecially its electron-forge configuration\nfile.
If you plan to access the microphone or camera within your app using Electron's APIs, you'll also\nneed to add the following entitlements:
\n<key>com.apple.security.device.audio-input</key>\n<true/>\n<key>com.apple.security.device.camera</key>\n<true/>\nIf these are not present in your app's entitlements when you invoke, for example:
\nconst { systemPreferences } = require('electron')\n\nconst microphone = systemPreferences.askForMediaAccess('microphone')\nYour app may crash. See the Resource Access section in Hardened Runtime for more information and entitlements you may need.
\nelectron-builderElectron Builder comes with a custom solution for signing your application. You\ncan find its documentation here.
\nelectron-packagerIf you're not using an integrated build pipeline like Forge or Builder, you\nare likely using electron-packager, which includes electron-osx-sign and\nelectron-notarize.
If you're using Packager's API, you can pass in configuration that both signs\nand notarizes your\napplication.
\nconst packager = require('electron-packager')\n\npackager({\n dir: '/path/to/my/app',\n osxSign: {\n identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',\n 'hardened-runtime': true,\n entitlements: 'entitlements.plist',\n 'entitlements-inherit': 'entitlements.plist',\n 'signature-flags': 'library'\n },\n osxNotarize: {\n appleId: 'felix@felix.fun',\n appleIdPassword: 'my-apple-id-password'\n }\n})\nThe plist file referenced here needs the following macOS-specific entitlements\nto assure the Apple security mechanisms that your app is doing these things\nwithout meaning any harm:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nUp until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required\nas well. However, it should not be used anymore if it can be avoided.
See the Mac App Store Guide.
\nBefore signing Windows builds, you must do the following:
\nYou can get a code signing certificate from a lot of resellers. Prices vary, so\nit may be worth your time to shop around. Popular resellers include:
\nThere are a number of tools for signing your packaged app:
\nelectron-winstaller will generate an installer for windows and sign it for\nyouelectron-forge can sign installers it generates through the\nSquirrel.Windows or MSI targets.electron-builder can sign some of its windows targetsSee the Windows Store Guide.
", "title": "Code Signing", "description": "" }, "/docs/development/coding-style": { "locale": "en-US", "slug": "coding-style", "href": "/docs/development/coding-style", "crowdinFileId": "256147", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/coding-style.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "These are the style guidelines for coding in Electron.
\nYou can run npm run lint to show any style issues detected by cpplint and\neslint.
path)ipc, app)@)path.join() to concatenate filenames.os.tmpdir() rather than /tmp when you need to reference the\ntemporary directory.return when returning explicitly at the end of a function.return null, return undefined, null or undefinedFor C++ and Python, we follow Chromium's Coding\nStyle. You can use\nclang-format to format the C++ code automatically. There is\nalso a script script/cpplint.py to check whether all files conform.
The Python version we are using now is Python 2.7.
\nThe C++ code uses a lot of Chromium's abstractions and types, so it's\nrecommended to get acquainted with them. A good place to start is\nChromium's Important Abstractions and Data Structures\ndocument. The document mentions some special types, scoped types (that\nautomatically release their memory when going out of scope), logging mechanisms\netc.
\nYou can run npm run lint-docs to ensure that your documentation changes are\nformatted correctly.
- instead of _, e.g.\nfile-name.js rather than file_name.js, because in\ngithub/atom module names are usually in\nthe module-name form. This rule only applies to .js files.const\nfor requires and other constants. If the value is a primitive, use uppercase naming (eg const NUMBER_OF_RETRIES = 5).let\nfor defining variablesfunction () { }+Electron APIs uses the same capitalization scheme as Node.js:
\nBrowserWindow, use PascalCase.globalShortcut, use camelCase.win.webContents, use mixedCase.<webview> Tag or\nProcess Object.When creating a new API, it is preferred to use getters and setters instead of\njQuery's one-function style. For example, .getText() and .setText(text)\nare preferred to .text([text]). There is a\ndiscussion on this.
\n\nManipulate the command line arguments for your app that Chromium reads
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The following example shows how to check if the --disable-gpu flag is set.
const { app } = require('electron')\napp.commandLine.hasSwitch('disable-gpu')\nFor more information on what kinds of flags and switches you can use, check\nout the Command Line Switches\ndocument.
\ncommandLine.appendSwitch(switch[, value])switch String - A command-line switch, without the leading --value String (optional) - A value for the given switchAppend a switch (with optional value) to Chromium's command line.
Note: This will not affect process.argv. The intended usage of this function is to\ncontrol Chromium's behavior.
commandLine.appendArgument(value)value String - The argument to append to the command lineAppend an argument to Chromium's command line. The argument will be quoted\ncorrectly. Switches will precede arguments regardless of appending order.
\nIf you're appending an argument like --switch=value, consider using appendSwitch('switch', 'value') instead.
Note: This will not affect process.argv. The intended usage of this function is to\ncontrol Chromium's behavior.
commandLine.hasSwitch(switch)switch String - A command-line switchReturns Boolean - Whether the command-line switch is present.
commandLine.getSwitchValue(switch)switch String - A command-line switchReturns String - The command-line switch value.
Note: When the switch is not present or has no value, it returns empty string.
", "title": "CommandLine", "description": "Manipulate the command line arguments for your app that Chromium reads" }, "/docs/api/command-line-switches": { "locale": "en-US", "slug": "command-line-switches", "href": "/docs/api/command-line-switches", "crowdinFileId": "256293", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/command-line-switches.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCommand line switches supported by Electron.
\n
You can use app.commandLine.appendSwitch to append them in\nyour app's main script before the ready event of the app module\nis emitted:
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('remote-debugging-port', '8315')\napp.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')\n\napp.whenReady().then(() => {\n // Your code here\n})\nurlA comma-separated list of servers for which integrated authentication is enabled.
\nFor example:
\n--auth-server-whitelist='*example.com, *foobar.com, *baz'\nthen any url ending with example.com, foobar.com, baz will be considered\nfor integrated authentication. Without * prefix the URL has to match exactly.
urlA comma-separated list of servers for which delegation of user credentials is required.\nWithout * prefix the URL has to match exactly.
Disables NTLM v2 for posix platforms, no effect elsewhere.
\nDisables the disk cache for HTTP requests.
\nDisable HTTP/2 and SPDY/3.1 protocols.
\nPrevents Chromium from lowering the priority of invisible pages' renderer\nprocesses.
\nThis flag is global to all renderer processes, if you only want to disable\nthrottling in one window, you can take the hack of\nplaying silent audio.
\nsizeForces the maximum disk space to be used by the disk cache, in bytes.
\nEnables caller stack logging for the following APIs (filtering events):
\ndesktopCapturer.getSources() / desktop-capturer-get-sourcesPrints Chromium's logging to stderr (or a log file).
\nThe ELECTRON_ENABLE_LOGGING environment variable has the same effect as\npassing --enable-logging.
Passing --enable-logging will result in logs being printed on stderr.\nPassing --enable-logging=file will result in logs being saved to the file\nspecified by --log-file=..., or to electron_debug.log in the user-data\ndirectory if --log-file is not specified.
\n\nNote: On Windows, logs from child processes cannot be sent to stderr.\nLogging to a file is the most reliable way to collect logs on Windows.
\n
See also --log-file, --log-level, --v, and --vmodule.
trialsField trials to be forcefully enabled or disabled.
\nFor example: WebRTC-Audio-Red-For-Opus/Enabled/
rulesA comma-separated list of rules that control how hostnames are mapped.
For example:
\nMAP * 127.0.0.1 Forces all hostnames to be mapped to 127.0.0.1MAP *.google.com proxy Forces all google.com subdomains to be resolved to\n\"proxy\".MAP test.com [::1]:77 Forces \"test.com\" to resolve to IPv6 loopback. Will\nalso force the port of the resulting socket address to be 77.MAP * baz, EXCLUDE www.google.com Remaps everything to \"baz\", except for\n\"www.google.com\".These mappings apply to the endpoint host in a net request (the TCP connect\nand host resolver in a direct connection, and the CONNECT in an HTTP proxy\nconnection, and the endpoint host in a SOCKS proxy connection).
rulesLike --host-rules but these rules only apply to the host resolver.
Ignores certificate related errors.
\ndomainsIgnore the connections limit for domains list separated by ,.
flagsSpecifies the flags passed to the Node.js engine. It has to be passed when starting\nElectron if you want to enable the flags in the main process.
$ electron --js-flags=\"--harmony_proxies --harmony_collections\" your-app\nSee the Node.js documentation or run node --help in your terminal for a list of available flags. Additionally, run node --v8-options to see a list of flags that specifically refer to Node.js's V8 JavaScript engine.
Set a custom locale.
\npathIf --enable-logging is specified, logs will be written to the given path. The\nparent directory must exist.
Setting the ELECTRON_LOG_FILE environment variable is equivalent to passing\nthis flag. If both are present, the command-line switch takes precedence.
pathEnables net log events to be saved and writes them to path.
NSets the verbosity of logging when used together with --enable-logging.\nN should be one of Chrome's LogSeverities.
Note that two complimentary logging mechanisms in Chromium -- LOG()\nand VLOG() -- are controlled by different switches. --log-level\ncontrols LOG() messages, while --v and --vmodule control VLOG()\nmessages. So you may want to use a combination of these three switches\ndepending on the granularity you want and what logging calls are made\nby the code you're trying to watch.
See Chromium Logging source for more information on how\nLOG() and VLOG() interact. Loosely speaking, VLOG() can be thought\nof as sub-levels / per-module levels inside LOG(INFO) to control the\nfirehose of LOG(INFO) data.
See also --enable-logging, --log-level, --v, and --vmodule.
Don't use a proxy server and always make direct connections. Overrides any other\nproxy server flags that are passed.
\nDisables the Chromium sandbox.\nForces renderer process and Chromium helper processes to run un-sandboxed.\nShould only be used for testing.
\nhostsInstructs Electron to bypass the proxy server for the given semi-colon-separated\nlist of hosts. This flag has an effect only if used in tandem with\n--proxy-server.
For example:
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')\nWill use the proxy server for all hosts except for local addresses (localhost,\n127.0.0.1 etc.), google.com subdomains, hosts that contain the suffix\nfoo.com and anything at 1.2.3.4:5678.
urlUses the PAC script at the specified url.
address:portUse a specified proxy server, which overrides the system setting. This switch\nonly affects requests with HTTP protocol, including HTTPS and WebSocket\nrequests. It is also noteworthy that not all proxy servers support HTTPS and\nWebSocket requests. The proxy URL does not support username and password\nauthentication per Chromium issue.
\nportEnables remote debugging over HTTP on the specified port.
log_levelGives the default maximal active V-logging level; 0 is the default. Normally\npositive values are used for V-logging levels.
\nThis switch only works when --enable-logging is also passed.
See also --enable-logging, --log-level, and --vmodule.
patternGives the per-module maximal V-logging levels to override the value given by\n--v. E.g. my_module=2,foo*=3 would change the logging level for all code in\nsource files my_module.* and foo*.*.
Any pattern containing a forward or backward slash will be tested against the\nwhole pathname and not only the module. E.g. */foo/bar/*=2 would change the\nlogging level for all code in the source files under a foo/bar directory.
This switch only works when --enable-logging is also passed.
See also --enable-logging, --log-level, and --v.
Force using discrete GPU when there are multiple GPUs available.
\nForce using integrated GPU when there are multiple GPUs available.
\nElectron supports some of the CLI flags supported by Node.js.
\nNote: Passing unsupported command line switches to Electron when it is not running in ELECTRON_RUN_AS_NODE will have no effect.
Activate inspector on host:port and break at start of user script. Default host:port is 127.0.0.1:9229.
\nAliased to --debug-brk=[host:]port.
Set the host:port to be used when the inspector is activated. Useful when activating the inspector by sending the SIGUSR1 signal. Default host is 127.0.0.1.
Aliased to --debug-port=[host:]port.
Activate inspector on host:port. Default is 127.0.0.1:9229.
V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug and profile Electron instances. The tools attach to Electron instances via a TCP port and communicate using the Chrome DevTools Protocol.
\nSee the Debugging the Main Process guide for more details.
\nAliased to --debug[=[host:]port.
Specify ways of the inspector web socket url exposure.
\nBy default inspector websocket url is available in stderr and under /json/list endpoint on http://host:port/json/list.
", "title": "Supported Command Line Switches", "description": "Command line switches supported by Electron." }, "/docs/api/content-tracing": { "locale": "en-US", "slug": "content-tracing", "href": "/docs/api/content-tracing", "crowdinFileId": "256297", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/content-tracing.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCollect tracing data from Chromium to find performance bottlenecks and slow operations.
\n
Process: Main
\nThis module does not include a web interface. To view recorded traces, use\ntrace viewer, available at chrome://tracing in Chrome.
Note: You should not use this module until the ready event of the app\nmodule is emitted.
const { app, contentTracing } = require('electron')\n\napp.whenReady().then(() => {\n (async () => {\n await contentTracing.startRecording({\n included_categories: ['*']\n })\n console.log('Tracing started')\n await new Promise(resolve => setTimeout(resolve, 5000))\n const path = await contentTracing.stopRecording()\n console.log('Tracing data recorded to ' + path)\n })()\n})\nThe contentTracing module has the following methods:
contentTracing.getCategories()Returns Promise<String[]> - resolves with an array of category groups once all child processes have acknowledged the getCategories request
Get a set of category groups. The category groups can change as new code paths\nare reached. See also the list of built-in tracing\ncategories.
\n\n\nNOTE: Electron adds a non-default tracing category called
\n\"electron\".\nThis category can be used to capture Electron-specific tracing events.
contentTracing.startRecording(options)options (TraceConfig | TraceCategoriesAndOptions)Returns Promise<void> - resolved once all child processes have acknowledged the startRecording request.
Start recording on all processes.
\nRecording begins immediately locally and asynchronously on child processes\nas soon as they receive the EnableRecording request.
\nIf a recording is already running, the promise will be immediately resolved, as\nonly one trace operation can be in progress at a time.
\ncontentTracing.stopRecording([resultFilePath])resultFilePath String (optional)Returns Promise<String> - resolves with a path to a file that contains the traced data once all child processes have acknowledged the stopRecording request
Stop recording on all processes.
\nChild processes typically cache trace data and only rarely flush and send\ntrace data back to the main process. This helps to minimize the runtime overhead\nof tracing since sending trace data over IPC can be an expensive operation. So,\nto end tracing, Chromium asynchronously asks all child processes to flush any\npending trace data.
\nTrace data will be written into resultFilePath. If resultFilePath is empty\nor not provided, trace data will be written to a temporary file, and the path\nwill be returned in the promise.
contentTracing.getTraceBufferUsage()Returns Promise<Object> - Resolves with an object containing the value and percentage of trace buffer maximum usage
value Numberpercentage NumberGet the maximum usage across processes of trace buffer as a percentage of the\nfull state.
", "title": "contentTracing", "description": "Collect tracing data from Chromium to find performance bottlenecks and slow operations." }, "/docs/api/context-bridge": { "locale": "en-US", "slug": "context-bridge", "href": "/docs/api/context-bridge", "crowdinFileId": "256299", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/context-bridge.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCreate a safe, bi-directional, synchronous bridge across isolated contexts
\n
Process: Renderer
\nAn example of exposing an API to a renderer from an isolated preload script is given below:
\n// Preload (Isolated World)\nconst { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing')\n }\n)\n// Renderer (Main World)\n\nwindow.electron.doThing()\nThe \"Main World\" is the JavaScript context that your main renderer code runs in. By default, the\npage you load in your renderer executes code in this world.
\nWhen contextIsolation is enabled in your webPreferences (this is the default behavior since Electron 12.0.0), your preload scripts run in an\n\"Isolated World\". You can read more about context isolation and what it affects in the\nsecurity docs.
The contextBridge module has the following methods:
contextBridge.exposeInMainWorld(apiKey, api)apiKey String - The key to inject the API onto window with. The API will be accessible on window[apiKey].api any - Your API, more information on what this API can be and how it works is available below.The api provided to exposeInMainWorld must be a Function, String, Number, Array, Boolean, or an object\nwhose keys are strings and values are a Function, String, Number, Array, Boolean, or another nested object that meets the same conditions.
Function values are proxied to the other context and all other values are copied and frozen. Any data / primitives sent in\nthe API become immutable and updates on either side of the bridge do not result in an update on the other side.
An example of a complex API is shown below:
\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing'),\n myPromises: [Promise.resolve(), Promise.reject(new Error('whoops'))],\n anAsyncFunction: async () => 123,\n data: {\n myFlags: ['a', 'b', 'c'],\n bootTime: 1234\n },\n nestedAPI: {\n evenDeeper: {\n youCanDoThisAsMuchAsYouWant: {\n fn: () => ({\n returnData: 123\n })\n }\n }\n }\n }\n)\nFunction values that you bind through the contextBridge are proxied through Electron to ensure that contexts remain isolated. This\nresults in some key limitations that we've outlined below.
Because parameters, errors and return values are copied when they are sent over the bridge, there are only certain types that can be used.\nAt a high level, if the type you want to use can be serialized and deserialized into the same object it will work. A table of type support\nhas been included below for completeness:
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Type | Complexity | Parameter Support | Return Value Support | Limitations |
|---|---|---|---|---|
String | Simple | ✅ | ✅ | N/A |
Number | Simple | ✅ | ✅ | N/A |
Boolean | Simple | ✅ | ✅ | N/A |
Object | Complex | ✅ | ✅ | Keys must be supported using only \"Simple\" types in this table. Values must be supported in this table. Prototype modifications are dropped. Sending custom classes will copy values but not the prototype. |
Array | Complex | ✅ | ✅ | Same limitations as the Object type |
Error | Complex | ✅ | ✅ | Errors that are thrown are also copied, this can result in the message and stack trace of the error changing slightly due to being thrown in a different context |
Promise | Complex | ✅ | ✅ | Promises are only proxied if they are the return value or exact parameter. Promises nested in arrays or objects will be dropped. |
Function | Complex | ✅ | ✅ | Prototype modifications are dropped. Sending classes or constructors will not work. |
| Cloneable Types | Simple | ✅ | ✅ | See the linked document on cloneable types |
Element | Complex | ✅ | ✅ | Prototype modifications are dropped. Sending custom elements will not work. |
Blob | Complex | ✅ | ✅ | N/A |
Symbol | N/A | ❌ | ❌ | Symbols cannot be copied across contexts so they are dropped |
If the type you care about is not in the above table, it is probably not supported.
\nThe contextBridge can be used by the preload script to give your renderer access to Node APIs.\nThe table of supported types described above also applies to Node APIs that you expose through contextBridge.\nPlease note that many Node APIs grant access to local system resources.\nBe very cautious about which globals and APIs you expose to untrusted remote content.
const { contextBridge } = require('electron')\nconst crypto = require('crypto')\ncontextBridge.exposeInMainWorld('nodeCrypto', {\n sha256sum (data) {\n const hash = crypto.createHash('sha256')\n hash.update(data)\n return hash.digest('hex')\n }\n})\nContext Isolation is a feature that ensures that both your preload scripts and Electron's internal logic run in a separate context to the website you load in a webContents. This is important for security purposes as it helps prevent the website from accessing Electron internals or the powerful APIs your preload script has access to.
This means that the window object that your preload script has access to is actually a different object than the website would have access to. For example, if you set window.hello = 'wave' in your preload script and context isolation is enabled, window.hello will be undefined if the website tries to access it.
Context isolation has been enabled by default since Electron 12, and it is a recommended security setting for all applications.
\n\n\nWithout context isolation, I used to provide APIs from my preload script using
\nwindow.X = apiObject. Now what?
Exposing APIs from your preload script to a loaded website in the renderer process is a common use-case. With context isolation disabled, your preload script would share a common global window object with the renderer. You could then attach arbitrary properties to a preload script:
// preload with contextIsolation disabled\nwindow.myAPI = {\n doAThing: () => {}\n}\nThe doAThing() function could then be used directly in the renderer process:
// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nThere is a dedicated module in Electron to help you do this in a painless way. The contextBridge module can be used to safely expose APIs from your preload script's isolated context to the context the website is running in. The API will also be accessible from the website on window.myAPI just like it was before.
// preload with contextIsolation enabled\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n doAThing: () => {}\n})\n// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nPlease read the contextBridge documentation linked above to fully understand its limitations. For instance, you can't send custom prototypes or symbols over the bridge.
Just enabling contextIsolation and using contextBridge does not automatically mean that everything you do is safe. For instance, this code is unsafe.
// ❌ Bad code\ncontextBridge.exposeInMainWorld('myAPI', {\n send: ipcRenderer.send\n})\nIt directly exposes a powerful API without any kind of argument filtering. This would allow any website to send arbitrary IPC messages, which you do not want to be possible. The correct way to expose IPC-based APIs would instead be to provide one method per IPC message.
\n// ✅ Good code\ncontextBridge.exposeInMainWorld('myAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nIf you're building your Electron app with TypeScript, you'll want to add types to your APIs exposed over the context bridge. The renderer's window object won't have the correct typings unless you extend the types with a declaration file.
For example, given this preload.ts script:
contextBridge.exposeInMainWorld('electronAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nYou can create a renderer.d.ts declaration file and globally augment the Window interface:
export interface IElectronAPI {\n loadPreferences: () => Promise<void>,\n}\n\ndeclare global {\n interface Window {\n electronAPI: IElectronAPI\n }\n}\nDoing so will ensure that the TypeScript compiler will know about the electronAPI property on your global window object when writing scripts in your renderer process:
window.electronAPI.loadPreferences()\nname String - The name of the cookie.value String - The value of the cookie.domain String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains.hostOnly Boolean (optional) - Whether the cookie is a host-only cookie; this will only be true if no domain was passed.path String (optional) - The path of the cookie.secure Boolean (optional) - Whether the cookie is marked as secure.httpOnly Boolean (optional) - Whether the cookie is marked as HTTP only.session Boolean (optional) - Whether the cookie is a session cookie or a persistent\ncookie with an expiration date.expirationDate Double (optional) - The expiration date of the cookie as\nthe number of seconds since the UNIX epoch. Not provided for session\ncookies.sameSite String - The Same Site policy applied to this cookie. Can be unspecified, no_restriction, lax or strict.\n\nQuery and modify a session's cookies.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Instances of the Cookies class are accessed by using cookies property of\na Session.
For example:
\nconst { session } = require('electron')\n\n// Query all cookies.\nsession.defaultSession.cookies.get({})\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// Query all cookies associated with a specific url.\nsession.defaultSession.cookies.get({ url: 'http://www.github.com' })\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// Set a cookie with the given cookie data;\n// may overwrite equivalent cookies if they exist.\nconst cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }\nsession.defaultSession.cookies.set(cookie)\n .then(() => {\n // success\n }, (error) => {\n console.error(error)\n })\nThe following events are available on instances of Cookies:
Returns:
\nevent Eventcookie Cookie - The cookie that was changed.cause String - The cause of the change with one of the following values:explicit - The cookie was changed directly by a consumer's action.overwrite - The cookie was automatically removed due to an insert\noperation that overwrote it.expired - The cookie was automatically removed as it expired.evicted - The cookie was automatically evicted during garbage collection.expired-overwrite - The cookie was overwritten with an already-expired\nexpiration date.removed Boolean - true if the cookie was removed, false otherwise.Emitted when a cookie is changed because it was added, edited, removed, or\nexpired.
\nThe following methods are available on instances of Cookies:
cookies.get(filter)filter Objecturl String (optional) - Retrieves cookies which are associated with\nurl. Empty implies retrieving cookies of all URLs.name String (optional) - Filters cookies by name.domain String (optional) - Retrieves cookies whose domains match or are\nsubdomains of domains.path String (optional) - Retrieves cookies whose path matches path.secure Boolean (optional) - Filters cookies by their Secure property.session Boolean (optional) - Filters out session or persistent cookies.Returns Promise<Cookie[]> - A promise which resolves an array of cookie objects.
Sends a request to get all cookies matching filter, and resolves a promise with\nthe response.
cookies.set(details)details Objecturl String - The URL to associate the cookie with. The promise will be rejected if the URL is invalid.name String (optional) - The name of the cookie. Empty by default if omitted.value String (optional) - The value of the cookie. Empty by default if omitted.domain String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains. Empty by default if omitted.path String (optional) - The path of the cookie. Empty by default if omitted.secure Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to\nfalse unless Same Site=None attribute is used.httpOnly Boolean (optional) - Whether the cookie should be marked as HTTP only.\nDefaults to false.expirationDate Double (optional) - The expiration date of the cookie as the number of\nseconds since the UNIX epoch. If omitted then the cookie becomes a session\ncookie and will not be retained between sessions.sameSite String (optional) - The Same Site policy to apply to this cookie. Can be unspecified, no_restriction, lax or strict. Default is no_restriction.Returns Promise<void> - A promise which resolves when the cookie has been set
Sets a cookie with details.
cookies.remove(url, name)url String - The URL associated with the cookie.name String - The name of cookie to remove.Returns Promise<void> - A promise which resolves when the cookie has been removed
Removes the cookies matching url and name
cookies.flushStore()Returns Promise<void> - A promise which resolves when the cookie store has been flushed
Writes any unwritten cookies data to disk.
", "title": "Cookies", "description": "Query and modify a session's cookies." }, "/docs/api/structures/cpu-usage": { "locale": "en-US", "slug": "cpu-usage", "href": "/docs/api/structures/cpu-usage", "crowdinFileId": "256419", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/cpu-usage.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "percentCPUUsage Number - Percentage of CPU used since the last call to getCPUUsage.\nFirst call returns 0.idleWakeupsPerSecond Number - The number of average idle CPU wakeups per second\nsince the last call to getCPUUsage. First call returns 0. Will always return 0 on\nWindows.date Dateid String\n\n\nSubmit crash reports to a remote server.
\n
The following is an example of setting up Electron to automatically submit\ncrash reports to a remote server:
\nconst { crashReporter } = require('electron')\n\ncrashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })\nFor setting up a server to accept and process crash reports, you can use\nfollowing projects:
\n\nOr use a 3rd party hosted solution:
\n\nCrash reports are stored temporarily before being uploaded in a directory\nunderneath the app's user data directory (called 'Crashpad' on Windows and Mac,\nor 'Crash Reports' on Linux). You can override this directory by calling\napp.setPath('crashDumps', '/path/to/crashes') before starting the crash\nreporter.
On Windows and macOS, Electron uses\ncrashpad\nto monitor and report crashes. On Linux, Electron uses\nbreakpad. This\nis an implementation detail driven by Chromium, and it may change in future. In\nparticular, crashpad is newer and will likely eventually replace breakpad on\nall platforms.
\nIf you are using the Node.js child_process module and want to report crashes\nfrom those processes on Linux, there is an extra step you will need to take to\nproperly initialize the crash reporter in the child process. This is not\nnecessary on Mac or Windows, as those platforms use Crashpad, which\nautomatically monitors child processes.
Since require('electron') is not available in Node child processes, the\nfollowing APIs are available on the process object in Node child processes.\nNote that, on Linux, each Node child process has its own separate instance of\nthe breakpad crash reporter. This is dissimilar to renderer child processes,\nwhich have a \"stub\" breakpad reporter which returns information to the main\nprocess for reporting.
process.crashReporter.start(options)process.crashReporter.getParameters()See crashReporter.getParameters().
process.crashReporter.addExtraParameter(key, value)See crashReporter.addExtraParameter(key, value).
process.crashReporter.removeExtraParameter(key)See crashReporter.removeExtraParameter(key).
The crashReporter module has the following methods:
crashReporter.start(options)options ObjectsubmitURL String (optional) - URL that crash reports will be sent to as\nPOST. Required unless uploadToServer is false.productName String (optional) - Defaults to app.name.companyName String (optional) Deprecated - Deprecated alias for\n{ globalExtra: { _companyName: ... } }.uploadToServer Boolean (optional) - Whether crash reports should be sent\nto the server. If false, crash reports will be collected and stored in the\ncrashes directory, but not uploaded. Default is true.ignoreSystemCrashHandler Boolean (optional) - If true, crashes generated\nin the main process will not be forwarded to the system crash handler.\nDefault is false.rateLimit Boolean (optional) macOS Windows - If true, limit the\nnumber of crashes uploaded to 1/hour. Default is false.compress Boolean (optional) - If true, crash reports will be compressed\nand uploaded with Content-Encoding: gzip. Default is true.extra Record<String, String> (optional) - Extra string key/value\nannotations that will be sent along with crash reports that are generated\nin the main process. Only string values are supported. Crashes generated in\nchild processes will not contain these extra\nparameters to crash reports generated from child processes, call\naddExtraParameter from the\nchild process.globalExtra Record<String, String> (optional) - Extra string key/value\nannotations that will be sent along with any crash reports generated in any\nprocess. These annotations cannot be changed once the crash reporter has\nbeen started. If a key is present in both the global extra parameters and\nthe process-specific extra parameters, then the global one will take\nprecedence. By default, productName and the app version are included, as\nwell as the Electron version.This method must be called before using any other crashReporter APIs. Once\ninitialized this way, the crashpad handler collects crashes from all\nsubsequently created processes. The crash reporter cannot be disabled once\nstarted.
This method should be called as early as possible in app startup, preferably\nbefore app.on('ready'). If the crash reporter is not initialized at the time\na renderer process is created, then that renderer process will not be monitored\nby the crash reporter.
Note: You can test out the crash reporter by generating a crash using\nprocess.crash().
Note: If you need to send additional/updated extra parameters after your\nfirst call start you can call addExtraParameter.
Note: Parameters passed in extra, globalExtra or set with\naddExtraParameter have limits on the length of the keys and values. Key names\nmust be at most 39 bytes long, and values must be no longer than 127 bytes.\nKeys with names longer than the maximum will be silently ignored. Key values\nlonger than the maximum length will be truncated.
Note: This method is only available in the main process.
\ncrashReporter.getLastCrashReport()Returns CrashReport - The date and ID of the\nlast crash report. Only crash reports that have been uploaded will be returned;\neven if a crash report is present on disk it will not be returned until it is\nuploaded. In the case that there are no uploaded reports, null is returned.
Note: This method is only available in the main process.
\ncrashReporter.getUploadedReports()Returns CrashReport[]:
Returns all uploaded crash reports. Each report contains the date and uploaded\nID.
\nNote: This method is only available in the main process.
\ncrashReporter.getUploadToServer()Returns Boolean - Whether reports should be submitted to the server. Set through\nthe start method or setUploadToServer.
Note: This method is only available in the main process.
\ncrashReporter.setUploadToServer(uploadToServer)uploadToServer Boolean - Whether reports should be submitted to the server.This would normally be controlled by user preferences. This has no effect if\ncalled before start is called.
Note: This method is only available in the main process.
\ncrashReporter.addExtraParameter(key, value)key String - Parameter key, must be no longer than 39 bytes.value String - Parameter value, must be no longer than 127 bytes.Set an extra parameter to be sent with the crash report. The values specified\nhere will be sent in addition to any values set via the extra option when\nstart was called.
Parameters added in this fashion (or via the extra parameter to\ncrashReporter.start) are specific to the calling process. Adding extra\nparameters in the main process will not cause those parameters to be sent along\nwith crashes from renderer or other child processes. Similarly, adding extra\nparameters in a renderer process will not result in those parameters being sent\nwith crashes that occur in other renderer processes or in the main process.
Note: Parameters have limits on the length of the keys and values. Key\nnames must be no longer than 39 bytes, and values must be no longer than 20320\nbytes. Keys with names longer than the maximum will be silently ignored. Key\nvalues longer than the maximum length will be truncated.
\nNote: On linux values that are longer than 127 bytes will be chunked into\nmultiple keys, each 127 bytes in length. E.g. addExtraParameter('foo', 'a'.repeat(130))\nwill result in two chunked keys foo__1 and foo__2, the first will contain\nthe first 127 bytes and the second will contain the remaining 3 bytes. On\nyour crash reporting backend you should stitch together keys in this format.
crashReporter.removeExtraParameter(key)key String - Parameter key, must be no longer than 39 bytes.Remove an extra parameter from the current set of parameters. Future crashes\nwill not include this parameter.
\ncrashReporter.getParameters()Returns Record<String, String> - The current 'extra' parameters of the crash reporter.
The crash reporter will send the following data to the submitURL as\na multipart/form-data POST:
ver String - The version of Electron.platform String - e.g. 'win32'.process_type String - e.g. 'renderer'.guid String - e.g. '5e1286fc-da97-479e-918b-6bfb0c3d1c72'._version String - The version in package.json._productName String - The product name in the crashReporter options\nobject.prod String - Name of the underlying product. In this case Electron._companyName String - The company name in the crashReporter options\nobject.upload_file_minidump File - The crash report in the format of minidump.extra object in the crashReporter\noptions object.scheme String - Custom schemes to be registered with options.privileges Object (optional)standard Boolean (optional) - Default false.secure Boolean (optional) - Default false.bypassCSP Boolean (optional) - Default false.allowServiceWorkers Boolean (optional) - Default false.supportFetchAPI Boolean (optional) - Default false.corsEnabled Boolean (optional) - Default false.stream Boolean (optional) - Default false.\"Native interfaces\" include the file picker, window border, dialogs, context\nmenus, and more - anything where the UI comes from your operating system and\nnot from your app. The default behavior is to opt into this automatic theming\nfrom the OS.
\nIf your app has its own dark mode, you should toggle it on and off in sync with\nthe system's dark mode setting. You can do this by using the\n[prefer-color-scheme] CSS media query.
\nIf you want to manually switch between light/dark modes, you can do this by\nsetting the desired mode in the\nthemeSource\nproperty of the nativeTheme module. This property's value will be propagated\nto your Renderer process. Any CSS rules related to prefers-color-scheme will\nbe updated accordingly.
In macOS 10.14 Mojave, Apple introduced a new system-wide dark mode\nfor all macOS computers. If your Electron app has a dark mode, you can make it\nfollow the system-wide dark mode setting using\nthe nativeTheme api.
In macOS 10.15 Catalina, Apple introduced a new \"automatic\" dark mode option\nfor all macOS computers. In order for the nativeTheme.shouldUseDarkColors and\nTray APIs to work correctly in this mode on Catalina, you need to use Electron\n>=7.0.0, or set NSRequiresAquaSystemAppearance to false in your\nInfo.plist file for older versions. Both Electron Packager\nand Electron Forge have a\ndarwinDarkModeSupport option\nto automate the Info.plist changes during app build time.
If you wish to opt-out while using Electron > 8.0.0, you must\nset the NSRequiresAquaSystemAppearance key in the Info.plist file to\ntrue. Please note that Electron 8.0.0 and above will not let you opt-out\nof this theming, due to the use of the macOS 10.14 SDK.
This example demonstrates an Electron application that derives its theme colors from the\nnativeTheme. Additionally, it provides theme toggle and reset controls using IPC channels.
Starting with the index.html file:
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n <link rel=\"stylesheet\" type=\"text/css\" href=\"./styles.css\">\n</head>\n<body>\n <h1>Hello World!</h1>\n <p>Current theme source: <strong id=\"theme-source\">System</strong></p>\n\n <button id=\"toggle-dark-mode\">Toggle Dark Mode</button>\n <button id=\"reset-to-system\">Reset to System Theme</button>\n\n <script src=\"renderer.js\"></script>\n </body>\n</body>\n</html>\nAnd the styles.css file:
@media (prefers-color-scheme: dark) {\n body { background: #333; color: white; }\n}\n\n@media (prefers-color-scheme: light) {\n body { background: #ddd; color: black; }\n}\nThe example renders an HTML page with a couple elements. The <strong id=\"theme-source\">\nelement shows which theme is currently selected, and the two <button> elements are the\ncontrols. The CSS file uses the prefers-color-scheme media query\nto set the <body> element background and text colors.
The preload.js script adds a new API to the window object called darkMode. This API\nexposes two IPC channels to the renderer process, 'dark-mode:toggle' and 'dark-mode:system'.\nIt also assigns two methods, toggle and system, which pass messages from the renderer to the\nmain process.
const { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld('darkMode', {\n toggle: () => ipcRenderer.invoke('dark-mode:toggle'),\n system: () => ipcRenderer.invoke('dark-mode:system')\n})\nNow the renderer process can communicate with the main process securely and perform the necessary\nmutations to the nativeTheme object.
The renderer.js file is responsible for controlling the <button> functionality.
document.getElementById('toggle-dark-mode').addEventListener('click', async () => {\n const isDarkMode = await window.darkMode.toggle()\n document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'\n})\n\ndocument.getElementById('reset-to-system').addEventListener('click', async () => {\n await window.darkMode.system()\n document.getElementById('theme-source').innerHTML = 'System'\n})\nUsing addEventListener, the renderer.js file adds 'click' event listeners\nto each button element. Each event listener handler makes calls to the respective window.darkMode\nAPI methods.
Finally, the main.js file represents the main process and contains the actual nativeTheme API.
const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n\n ipcMain.handle('dark-mode:toggle', () => {\n if (nativeTheme.shouldUseDarkColors) {\n nativeTheme.themeSource = 'light'\n } else {\n nativeTheme.themeSource = 'dark'\n }\n return nativeTheme.shouldUseDarkColors\n })\n\n ipcMain.handle('dark-mode:system', () => {\n nativeTheme.themeSource = 'system'\n })\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nThe ipcMain.handle methods are how the main process responds to the click events from the buttons\non the HTML page.
The 'dark-mode:toggle' IPC channel handler method checks the shouldUseDarkColors boolean property,\nsets the corresponding themeSource, and then returns the current shouldUseDarkColors property.\nLooking back on the renderer process event listener for this IPC channel, the return value from this\nhandler is utilized to assign the correct text to the <strong id='theme-source'> element.
The 'dark-mode:system' IPC channel handler method assigns the string 'system' to the themeSource\nand returns nothing. This also corresponds with the relative renderer process event listener as the\nmethod is awaited with no return value expected.
Run the example using Electron Fiddle and then click the \"Toggle Dark Mode\" button; the app should\nstart alternating between a light and dark background color.
\n![\"Dark](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/dark_mode.gif\")
If you experience crashes or issues in Electron that you believe are not caused\nby your JavaScript application, but instead by Electron itself, debugging can\nbe a little bit tricky, especially for developers not used to native/C++\ndebugging. However, using Visual Studio, Electron's hosted Symbol Server,\nand the Electron source code, you can enable step-through debugging\nwith breakpoints inside Electron's source code.
\nSee also: There's a wealth of information on debugging Chromium, much of which also applies to Electron, on the Chromium developers site: Debugging Chromium on Windows.
\nA debug build of Electron: The easiest way is usually building it\nyourself, using the tools and prerequisites listed in the\nbuild instructions for Windows. While you can\nattach to and debug Electron as you can download it directly, you will\nfind that it is heavily optimized, making debugging substantially more\ndifficult: The debugger will not be able to show you the content of all\nvariables and the execution path can seem strange because of inlining,\ntail calls, and other compiler optimizations.
\nVisual Studio with C++ Tools: The free community editions of Visual\nStudio 2013 and Visual Studio 2015 both work. Once installed,\nconfigure Visual Studio to use Electron's Symbol server.\nIt will enable Visual Studio to gain a better understanding of what happens\ninside Electron, making it easier to present variables in a human-readable\nformat.
\nProcMon: The free SysInternals tool allows you to inspect\na processes parameters, file handles, and registry operations.
\nTo start a debugging session, open up PowerShell/CMD and execute your debug\nbuild of Electron, using the application to open as a parameter.
\n$ ./out/Testing/electron.exe ~/my-electron-app/\nThen, open up Visual Studio. Electron is not built with Visual Studio and hence\ndoes not contain a project file - you can however open up the source code files\n\"As File\", meaning that Visual Studio will open them up by themselves. You can\nstill set breakpoints - Visual Studio will automatically figure out that the\nsource code matches the code running in the attached process and break\naccordingly.
\nRelevant code files can be found in ./shell/.
You can attach the Visual Studio debugger to a running process on a local or\nremote computer. After the process is running, click Debug / Attach to Process\n(or press CTRL+ALT+P) to open the \"Attach to Process\" dialog box. You can use\nthis capability to debug apps that are running on a local or remote computer,\ndebug multiple processes simultaneously.
If Electron is running under a different user account, select the\nShow processes from all users check box. Notice that depending on how many\nBrowserWindows your app opened, you will see multiple processes. A typical\none-window app will result in Visual Studio presenting you with two\nElectron.exe entries - one for the main process and one for the renderer\nprocess. Since the list only gives you names, there's currently no reliable\nway of figuring out which is which.
Code executed within the main process (that is, code found in or eventually run\nby your main JavaScript file) will run inside the main process, while other\ncode will execute inside its respective renderer process.
\nYou can be attached to multiple programs when you are debugging, but only one\nprogram is active in the debugger at any time. You can set the active program\nin the Debug Location toolbar or the Processes window.
While Visual Studio is fantastic for inspecting specific code paths, ProcMon's\nstrength is really in observing everything your application is doing with the\noperating system - it captures File, Registry, Network, Process, and Profiling\ndetails of processes. It attempts to log all events occurring and can be\nquite overwhelming, but if you seek to understand what and how your application\nis doing to the operating system, it can be a valuable resource.
\nFor an introduction to ProcMon's basic and advanced debugging features, go check\nout this video tutorial provided by Microsoft.
", "title": "Debugging on Windows", "description": "" }, "/docs/api/debugger": { "locale": "en-US", "slug": "debugger", "href": "/docs/api/debugger", "crowdinFileId": "256305", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/debugger.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nAn alternate transport for Chrome's remote debugging protocol.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Chrome Developer Tools has a special binding available at JavaScript\nruntime that allows interacting with pages and instrumenting them.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\ntry {\n win.webContents.debugger.attach('1.1')\n} catch (err) {\n console.log('Debugger attach failed : ', err)\n}\n\nwin.webContents.debugger.on('detach', (event, reason) => {\n console.log('Debugger detached due to : ', reason)\n})\n\nwin.webContents.debugger.on('message', (event, method, params) => {\n if (method === 'Network.requestWillBeSent') {\n if (params.request.url === 'https://www.github.com') {\n win.webContents.debugger.detach()\n }\n }\n})\n\nwin.webContents.debugger.sendCommand('Network.enable')\nReturns:
\nevent Eventreason String - Reason for detaching debugger.Emitted when the debugging session is terminated. This happens either when\nwebContents is closed or devtools is invoked for the attached webContents.
Returns:
\nevent Eventmethod String - Method name.params any - Event parameters defined by the 'parameters'\nattribute in the remote debugging protocol.sessionId String - Unique identifier of attached debugging session,\nwill match the value sent from debugger.sendCommand.Emitted whenever the debugging target issues an instrumentation event.
\ndebugger.attach([protocolVersion])protocolVersion String (optional) - Requested debugging protocol version.Attaches the debugger to the webContents.
debugger.isAttached()Returns Boolean - Whether a debugger is attached to the webContents.
debugger.detach()Detaches the debugger from the webContents.
debugger.sendCommand(method[, commandParams, sessionId])method String - Method name, should be one of the methods defined by the\nremote debugging protocol.commandParams any (optional) - JSON object with request parameters.sessionId String (optional) - send command to the target with associated\ndebugging session id. The initial value can be obtained by sending\nTarget.attachToTarget message.Returns Promise<any> - A promise that resolves with the response defined by\nthe 'returns' attribute of the command description in the remote debugging protocol\nor is rejected indicating the failure of the command.
Send given command to the debugging target.
", "title": "Debugger", "description": "An alternate transport for Chrome's remote debugging protocol." }, "/docs/development/debugging-instructions-macos": { "locale": "en-US", "slug": "debugging-instructions-macos", "href": "/docs/development/debugging-instructions-macos", "crowdinFileId": "256153", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "If you experience crashes or issues in Electron that you believe are not caused\nby your JavaScript application, but instead by Electron itself, debugging can\nbe a little bit tricky, especially for developers not used to native/C++\ndebugging. However, using lldb, and the Electron source code, you can enable\nstep-through debugging with breakpoints inside Electron's source code.\nYou can also use XCode for debugging if\nyou prefer a graphical interface.
\nA debug build of Electron: The easiest way is usually building it\nyourself, using the tools and prerequisites listed in the\nbuild instructions for macOS. While you can\nattach to and debug Electron as you can download it directly, you will\nfind that it is heavily optimized, making debugging substantially more\ndifficult: The debugger will not be able to show you the content of all\nvariables and the execution path can seem strange because of inlining,\ntail calls, and other compiler optimizations.
\nXcode: In addition to Xcode, also install the Xcode command line tools.\nThey include LLDB, the default debugger in Xcode on macOS. It supports\ndebugging C, Objective-C and C++ on the desktop and iOS devices and simulator.
\n.lldbinit: Create or edit ~/.lldbinit to allow Chromium code to be properly source-mapped.
# e.g: ['~/electron/src/tools/lldb']\nscript sys.path[:0] = ['<...path/to/electron/src/tools/lldb>']\nscript import lldbinit\nTo start a debugging session, open up Terminal and start lldb, passing a non-release\nbuild of Electron as a parameter.
$ lldb ./out/Testing/Electron.app\n(lldb) target create \"./out/Testing/Electron.app\"\nCurrent executable set to './out/Testing/Electron.app' (x86_64).\nLLDB is a powerful tool and supports multiple strategies for code inspection. For\nthis basic introduction, let's assume that you're calling a command from JavaScript\nthat isn't behaving correctly - so you'd like to break on that command's C++\ncounterpart inside the Electron source.
\nRelevant code files can be found in ./shell/.
Let's assume that you want to debug app.setName(), which is defined in browser.cc\nas Browser::SetName(). Set the breakpoint using the breakpoint command, specifying\nfile and line to break on:
(lldb) breakpoint set --file browser.cc --line 117\nBreakpoint 1: where = Electron Framework`atom::Browser::SetName(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) + 20 at browser.cc:118, address = 0x000000000015fdb4\nThen, start Electron:
\n(lldb) run\nThe app will immediately be paused, since Electron sets the app's name on launch:
\n(lldb) run\nProcess 25244 launched: '/Users/fr/Code/electron/out/Testing/Electron.app/Contents/MacOS/Electron' (x86_64)\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1\n frame #0: 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118\n 115 }\n 116\n 117 void Browser::SetName(const std::string& name) {\n-> 118 name_override_ = name;\n 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n(lldb)\nTo show the arguments and local variables for the current frame, run frame variable (or fr v),\nwhich will show you that the app is currently setting the name to \"Electron\".
(lldb) frame variable\n(atom::Browser *) this = 0x0000000108b14f20\n(const string &) name = \"Electron\": {\n [...]\n}\nTo do a source level single step in the currently selected thread, execute step (or s).\nThis would take you into name_override_.empty(). To proceed and do a step over,\nrun next (or n).
(lldb) step\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119, queue = 'com.apple.main-thread', stop reason = step in\n frame #0: 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119\n 116\n 117 void Browser::SetName(const std::string& name) {\n 118 name_override_ = name;\n-> 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n 122 return badge_count_;\nNOTE: If you don't see source code when you think you should, you may not have added the ~/.lldbinit file above.
To finish debugging at this point, run process continue. You can also continue until a certain\nline is hit in this thread (thread until 100). This command will run the thread in the current\nframe till it reaches line 100 in this frame or stops if it leaves the current frame.
Now, if you open up Electron's developer tools and call setName, you will once again hit the\nbreakpoint.
LLDB is a powerful tool with a great documentation. To learn more about it, consider\nApple's debugging documentation, for instance the LLDB Command Structure Reference\nor the introduction to Using LLDB as a Standalone Debugger.
\nYou can also check out LLDB's fantastic manual and tutorial, which\nwill explain more complex debugging scenarios.
", "title": "Debugging on macOS", "description": "" }, "/docs/development/debugging-instructions-macos-xcode": { "locale": "en-US", "slug": "debugging-instructions-macos-xcode", "href": "/docs/development/debugging-instructions-macos-xcode", "crowdinFileId": "256151", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos-xcode.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Run gn gen with the --ide=xcode argument.
$ gn gen out/Testing --ide=xcode\nThis will generate the electron.ninja.xcworkspace. You will have to open this workspace\nto set breakpoints and inspect.
\nSee gn help gen for more information on generating IDE projects with GN.
Launch Electron app after build.\nYou can now open the xcode workspace created above and attach to the Electron process\nthrough the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug\nthe renderer process, you need to attach to the Electron Helper as well.]
\nYou can now set breakpoints in any of the indexed files. However, you will not be able\nto set breakpoints directly in the Chromium source.\nTo set break points in the Chromium source, you can choose Debug > Breakpoints > Create\nSymbolic Breakpoint and set any function name as the symbol. This will set the breakpoint\nfor all functions with that name, from all the classes if there are more than one.\nYou can also do this step of setting break points prior to attaching the debugger,\nhowever, actual breakpoints for symbolic breakpoint functions may not show up until the\ndebugger is attached to the app.
", "title": "Debugging with XCode", "description": "" }, "/docs/tutorial/debugging-main-process": { "locale": "en-US", "slug": "debugging-main-process", "href": "/docs/tutorial/debugging-main-process", "crowdinFileId": "256189", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/debugging-main-process.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "The DevTools in an Electron browser window can only debug JavaScript that's\nexecuted in that window (i.e. the web pages). To debug JavaScript that's\nexecuted in the main process you will need to use an external debugger and\nlaunch Electron with the --inspect or --inspect-brk switch.
Use one of the following command line switches to enable debugging of the main\nprocess:
\n--inspect=[port]Electron will listen for V8 inspector protocol messages on the specified port,\nan external debugger will need to connect on this port. The default port is\n5858.
electron --inspect=5858 your/app\n--inspect-brk=[port]Like --inspect but pauses execution on the first line of JavaScript.
You will need to use a debugger that supports the V8 inspector protocol.
\nchrome://inspect and selecting to inspect the\nlaunched Electron app present there.This guide goes over how to set up VSCode debugging for both your own Electron project as well as the native Electron codebase.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json with the following configuration:{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"Debug Main Process\",\n \"type\": \"node\",\n \"request\": \"launch\",\n \"cwd\": \"${workspaceFolder}\",\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron\",\n \"windows\": {\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron.cmd\"\n },\n \"args\" : [\".\"],\n \"outputCapture\": \"std\"\n }\n ]\n}\nSet some breakpoints in main.js, and start debugging in the Debug View. You should be able to hit the breakpoints.
Here is a pre-configured project that you can download and directly debug in VSCode: https://github.com/octref/vscode-electron-debug/tree/master/electron-quick-start
\nIf you want to build Electron from source and modify the native Electron codebase, this section will help you in testing your modifications.
\nFor those unsure where to acquire this code or how to build it, Electron's Build Tools automates and explains most of this process. If you wish to manually set up the environment, you can instead use these build instructions.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json with the following configuration:{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"(Windows) Launch\",\n \"type\": \"cppvsdbg\",\n \"request\": \"launch\",\n \"program\": \"${workspaceFolder}\\\\out\\\\your-executable-location\\\\electron.exe\",\n \"args\": [\"your-electron-project-path\"],\n \"stopAtEntry\": false,\n \"cwd\": \"${workspaceFolder}\",\n \"environment\": [\n {\"name\": \"ELECTRON_ENABLE_LOGGING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_ENABLE_STACK_DUMPING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_RUN_AS_NODE\", \"value\": \"\"},\n ],\n \"externalConsole\": false,\n \"sourceFileMap\": {\n \"o:\\\\\": \"${workspaceFolder}\",\n },\n },\n ]\n}\nConfiguration Notes
\ncppvsdbg requires the built-in C/C++ extension be enabled.${workspaceFolder} is the full path to Chromium's src directory.your-executable-location will be one of the following depending on a few items:Testing: If you are using the default settings of Electron's Build-Tools or the default instructions when building from source.Release: If you built a Release build rather than a Testing build.your-directory-name: If you modified this during your build process from the default, this will be whatever you specified.args array string \"your-electron-project-path\" should be the absolute path to either the directory or main.js file of the Electron project you are using for testing. In this example, it should be your path to electron-quick-start.Set some breakpoints in the .cc files of your choosing in the native Electron C++ code, and start debugging in the Debug View.
", "title": "Debugging in VSCode", "description": "" }, "/docs/api/desktop-capturer": { "locale": "en-US", "slug": "desktop-capturer", "href": "/docs/api/desktop-capturer", "crowdinFileId": "256307", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/desktop-capturer.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n\nAccess information about media sources that can be used to capture audio and\nvideo from the desktop using the
\nnavigator.mediaDevices.getUserMediaAPI.
The following example shows how to capture video from a desktop window whose\ntitle is Electron:
// In the renderer process.\nconst { desktopCapturer } = require('electron')\n\ndesktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources => {\n for (const source of sources) {\n if (source.name === 'Electron') {\n try {\n const stream = await navigator.mediaDevices.getUserMedia({\n audio: false,\n video: {\n mandatory: {\n chromeMediaSource: 'desktop',\n chromeMediaSourceId: source.id,\n minWidth: 1280,\n maxWidth: 1280,\n minHeight: 720,\n maxHeight: 720\n }\n }\n })\n handleStream(stream)\n } catch (e) {\n handleError(e)\n }\n return\n }\n }\n})\n\nfunction handleStream (stream) {\n const video = document.querySelector('video')\n video.srcObject = stream\n video.onloadedmetadata = (e) => video.play()\n}\n\nfunction handleError (e) {\n console.log(e)\n}\nTo capture video from a source provided by desktopCapturer the constraints\npassed to navigator.mediaDevices.getUserMedia must include\nchromeMediaSource: 'desktop', and audio: false.
To capture both audio and video from the entire desktop the constraints passed\nto navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop',\nfor both audio and video, but should not include a chromeMediaSourceId constraint.
const constraints = {\n audio: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n },\n video: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n }\n}\nThe desktopCapturer module has the following methods:
desktopCapturer.getSources(options)options Objecttypes String[] - An array of Strings that lists the types of desktop sources\nto be captured, available types are screen and window.thumbnailSize Size (optional) - The size that the media source thumbnail\nshould be scaled to. Default is 150 x 150. Set width or height to 0 when you do not need\nthe thumbnails. This will save the processing time required for capturing the content of each\nwindow and screen.fetchWindowIcons Boolean (optional) - Set to true to enable fetching window icons. The default\nvalue is false. When false the appIcon property of the sources return null. Same if a source has\nthe type screen.Returns Promise<DesktopCapturerSource[]> - Resolves with an array of DesktopCapturerSource objects, each DesktopCapturerSource represents a screen or an individual window that can be captured.
Note Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher,\nwhich can detected by systemPreferences.getMediaAccessStatus.
navigator.mediaDevices.getUserMedia does not work on macOS for audio capture due to a fundamental limitation whereby apps that want to access the system's audio require a signed kernel extension. Chromium, and by extension Electron, does not provide this.
It is possible to circumvent this limitation by capturing system audio with another macOS app like Soundflower and passing it through a virtual audio input device. This virtual device can then be queried with navigator.mediaDevices.getUserMedia.
id String - The identifier of a window or screen that can be used as a\nchromeMediaSourceId constraint when calling\n[navigator.webkitGetUserMedia]. The format of the identifier will be\nwindow:XX:YY or screen:ZZ:0. XX is the windowID/handle. YY is 1 for\nthe current process, and 0 for all others. ZZ is a sequential number\nthat represents the screen, and it does not equal to the index in the\nsource's name.name String - A screen source will be named either Entire Screen or\nScreen <index>, while the name of a window source will match the window\ntitle.thumbnail NativeImage - A thumbnail image. Note:\nThere is no guarantee that the size of the thumbnail is the same as the\nthumbnailSize specified in the options passed to\ndesktopCapturer.getSources. The actual size depends on the scale of the\nscreen or window.display_id String - A unique identifier that will correspond to the id of\nthe matching Display returned by the Screen API.\nOn some platforms, this is equivalent to the XX portion of the id field\nabove and on others it will differ. It will be an empty string if not\navailable.appIcon NativeImage - An icon image of the\napplication that owns the window or null if the source has a type screen.\nThe size of the icon is not known in advance and depends on what\nthe application provides.Like Chromium based browsers, Electron provides access to device hardware\nthrough web APIs. For the most part these APIs work like they do in a browser,\nbut there are some differences that need to be taken into account. The primary\ndifference between Electron and browsers is what happens when device access is\nrequested. In a browser, users are presented with a popup where they can grant\naccess to an individual device. In Electron APIs are provided which can be\nused by a developer to either automatically pick a device or prompt users to\npick a device via a developer created interface.
\nThe Web Bluetooth API can be used to communicate\nwith bluetooth devices. In order to use this API in Electron, developers will\nneed to handle the select-bluetooth-device event on the webContents\nassociated with the device request.
This example demonstrates an Electron application that automatically selects\nthe first available bluetooth device when the Test Bluetooth button is\nclicked.
The WebHID API can be used to access HID devices such\nas keyboards and gamepads. Electron provides several APIs for working with\nthe WebHID API:
\nselect-hid-device event on the Session\ncan be used to select a HID device when a call to\nnavigator.hid.requestDevice is made. Additionally the hid-device-added\nand hid-device-removed events\non the Session can be used to handle devices being plugged in or unplugged during the\nnavigator.hid.requestDevice process.ses.setDevicePermissionHandler(handler)\ncan be used to provide default permissioning to devices without first calling\nfor permission to devices via navigator.hid.requestDevice. Additionally,\nthe default behavior of Electron is to store granted device permision through\nthe lifetime of the corresponding WebContents. If longer term storage is\nneeded, a developer can store granted device permissions (eg when handling\nthe select-hid-device event) and then read from that storage with\nsetDevicePermissionHandler.ses.setPermissionCheckHandler(handler)\ncan be used to disable HID access for specific origins.By default Electron employs the same blocklist\nused by Chromium. If you wish to override this behavior, you can do so by\nsetting the disable-hid-blocklist flag:
app.commandLine.appendSwitch('disable-hid-blocklist')\nThis example demonstrates an Electron application that automatically selects\nHID devices through ses.setDevicePermissionHandler(handler)\nand through select-hid-device event on the Session\nwhen the Test WebHID button is clicked.
The Web Serial API can be used to access serial\ndevices that are connected via serial port, USB, or Bluetooth. In order to use\nthis API in Electron, developers will need to handle the\nselect-serial-port event on the Session\nassociated with the serial port request.
There are several additional APIs for working with the Web Serial API:
\nserial-port-added\nand serial-port-removed events\non the Session can be used to handle devices being plugged in or unplugged during the\nnavigator.serial.requestPort process.ses.setPermissionCheckHandler(handler)\ncan be used to disable serial access for specific origins.This example demonstrates an Electron application that automatically selects\nthe first available Arduino Uno serial device (if connected) through\nselect-serial-port event on the Session\nwhen the Test Web Serial button is clicked.
Electron supports Chrome DevTools extensions, which can\nbe used to extend the ability of Chrome's developer tools for debugging\npopular web frameworks.
\nThe easiest way to load a DevTools extension is to use third-party tooling to automate the\nprocess for you. electron-devtools-installer is a popular\nNPM package that does just that.
\nIf you don't want to use the tooling approach, you can also do all of the necessary\noperations by hand. To load an extension in Electron, you need to download it via Chrome,\nlocate its filesystem path, and then load it into your Session by calling the\n[ses.loadExtension] API.
Using the React Developer Tools as an example:
\nInstall the extension in Google Chrome.
\nNavigate to chrome://extensions, and find its extension ID, which is a hash\nstring like fmkadmapgofadopljbjfkapdkoienihi.
Find out the filesystem location used by Chrome for storing extensions:
\n%LOCALAPPDATA%\\Google\\Chrome\\User Data\\Default\\Extensions;~/.config/google-chrome/Default/Extensions/~/.config/google-chrome-beta/Default/Extensions/~/.config/google-chrome-canary/Default/Extensions/~/.config/chromium/Default/Extensions/~/Library/Application Support/Google/Chrome/Default/Extensions.Pass the location of the extension to the ses.loadExtension\nAPI. For React Developer Tools v4.9.0, it looks something like:
const { app, session } = require('electron')\n const path = require('path')\n const os = require('os')\n\n // on macOS\n const reactDevToolsPath = path.join(\n os.homedir(),\n '/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.9.0_0'\n )\n\n app.whenReady().then(async () => {\n await session.defaultSession.loadExtension(reactDevToolsPath)\n })\nNotes:
\nloadExtension returns a Promise with an Extension object,\nwhich contains metadata about the extension that was loaded. This promise needs to\nresolve (e.g. with an await expression) before loading a page. Otherwise, the\nextension won't be guaranteed to load.loadExtension cannot be called before the ready event of the app module\nis emitted, nor can it be called on in-memory (non-persistent) sessions.loadExtension must be called on every boot of your app if you want the\nextension to be loaded.You can pass the extension's ID to the ses.removeExtension API to\nremove it from your Session. Loaded extensions are not persisted between\napp launches.
Electron only supports\na limited set of chrome.* APIs,\nso extensions using unsupported chrome.* APIs under the hood may not work.
The following Devtools extensions have been tested to work in Electron:
\nFirst, please make sure the extension is still being maintained and is compatible\nwith the latest version of Google Chrome. We cannot provide additional support for\nunsupported extensions.
\nIf the extension works on Chrome but not on Electron, file a bug in Electron's\nissue tracker and describe which part\nof the extension is not working as expected.
", "title": "DevTools Extension", "description": "" }, "/docs/api/dialog": { "locale": "en-US", "slug": "dialog", "href": "/docs/api/dialog", "crowdinFileId": "256309", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/dialog.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nDisplay native system dialogs for opening and saving files, alerting, etc.
\n
Process: Main
\nAn example of showing a dialog to select multiple files:
\nconst { dialog } = require('electron')\nconsole.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))\nThe dialog module has the following methods:
dialog.showOpenDialogSync([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objecttitle String (optional)defaultPath String (optional)buttonLabel String (optional) - Custom label for the confirmation button, when\nleft empty the default label will be used.filters FileFilter[] (optional)properties String[] (optional) - Contains which features the dialog should\nuse. The following values are supported:openFile - Allow files to be selected.openDirectory - Allow directories to be selected.multiSelections - Allow multiple paths to be selected.showHiddenFiles - Show hidden files in dialog.createDirectory macOS - Allow creating new directories from dialog.promptToCreate Windows - Prompt for creation if the file path entered\nin the dialog does not exist. This does not actually create the file at\nthe path but allows non-existent paths to be returned that should be\ncreated by the application.noResolveAliases macOS - Disable the automatic alias (symlink) path\nresolution. Selected aliases will now return the alias path instead of\ntheir target path.treatPackageAsDirectory macOS - Treat packages, such as .app folders,\nas a directory instead of a file.dontAddToRecent Windows - Do not add the item being opened to the recent documents list.message String (optional) macOS - Message to display above input\nboxes.securityScopedBookmarks Boolean (optional) macOS mas - Create security scoped bookmarks when packaged for the Mac App Store.Returns String[] | undefined, the file paths chosen by the user; if the dialog is cancelled it returns undefined.
The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
The filters specifies an array of file types that can be displayed or\nselected when you want to limit the user to a specific type. For example:
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nThe extensions array should contain extensions without wildcards or dots (e.g.\n'png' is good but '.png' and '*.png' are bad). To show all files, use the\n'*' wildcard (no other wildcard is supported).
Note: On Windows and Linux an open dialog can not be both a file selector\nand a directory selector, so if you set properties to\n['openFile', 'openDirectory'] on these platforms, a directory selector will be\nshown.
dialog.showOpenDialogSync(mainWindow, {\n properties: ['openFile', 'openDirectory']\n})\ndialog.showOpenDialog([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objecttitle String (optional)defaultPath String (optional)buttonLabel String (optional) - Custom label for the confirmation button, when\nleft empty the default label will be used.filters FileFilter[] (optional)properties String[] (optional) - Contains which features the dialog should\nuse. The following values are supported:openFile - Allow files to be selected.openDirectory - Allow directories to be selected.multiSelections - Allow multiple paths to be selected.showHiddenFiles - Show hidden files in dialog.createDirectory macOS - Allow creating new directories from dialog.promptToCreate Windows - Prompt for creation if the file path entered\nin the dialog does not exist. This does not actually create the file at\nthe path but allows non-existent paths to be returned that should be\ncreated by the application.noResolveAliases macOS - Disable the automatic alias (symlink) path\nresolution. Selected aliases will now return the alias path instead of\ntheir target path.treatPackageAsDirectory macOS - Treat packages, such as .app folders,\nas a directory instead of a file.dontAddToRecent Windows - Do not add the item being opened to the recent documents list.message String (optional) macOS - Message to display above input\nboxes.securityScopedBookmarks Boolean (optional) macOS mas - Create security scoped bookmarks when packaged for the Mac App Store.Returns Promise<Object> - Resolve with an object containing the following:
canceled Boolean - whether or not the dialog was canceled.filePaths String[] - An array of file paths chosen by the user. If the dialog is cancelled this will be an empty array.bookmarks String[] (optional) macOS mas - An array matching the filePaths array of base64 encoded strings which contains security scoped bookmark data. securityScopedBookmarks must be enabled for this to be populated. (For return values, see table here.)The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
The filters specifies an array of file types that can be displayed or\nselected when you want to limit the user to a specific type. For example:
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nThe extensions array should contain extensions without wildcards or dots (e.g.\n'png' is good but '.png' and '*.png' are bad). To show all files, use the\n'*' wildcard (no other wildcard is supported).
Note: On Windows and Linux an open dialog can not be both a file selector\nand a directory selector, so if you set properties to\n['openFile', 'openDirectory'] on these platforms, a directory selector will be\nshown.
dialog.showOpenDialog(mainWindow, {\n properties: ['openFile', 'openDirectory']\n}).then(result => {\n console.log(result.canceled)\n console.log(result.filePaths)\n}).catch(err => {\n console.log(err)\n})\ndialog.showSaveDialogSync([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objecttitle String (optional) - The dialog title. Cannot be displayed on some Linux desktop environments.defaultPath String (optional) - Absolute directory path, absolute file\npath, or file name to use by default.buttonLabel String (optional) - Custom label for the confirmation button, when\nleft empty the default label will be used.filters FileFilter[] (optional)message String (optional) macOS - Message to display above text fields.nameFieldLabel String (optional) macOS - Custom label for the text\ndisplayed in front of the filename text field.showsTagField Boolean (optional) macOS - Show the tags input box,\ndefaults to true.properties String[] (optional)showHiddenFiles - Show hidden files in dialog.createDirectory macOS - Allow creating new directories from dialog.treatPackageAsDirectory macOS - Treat packages, such as .app folders,\nas a directory instead of a file.showOverwriteConfirmation Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.dontAddToRecent Windows - Do not add the item being saved to the recent documents list.securityScopedBookmarks Boolean (optional) macOS mas - Create a security scoped bookmark when packaged for the Mac App Store. If this option is enabled and the file doesn't already exist a blank file will be created at the chosen path.Returns String | undefined, the path of the file chosen by the user; if the dialog is cancelled it returns undefined.
The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
The filters specifies an array of file types that can be displayed, see\ndialog.showOpenDialog for an example.
dialog.showSaveDialog([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objecttitle String (optional) - The dialog title. Cannot be displayed on some Linux desktop environments.defaultPath String (optional) - Absolute directory path, absolute file\npath, or file name to use by default.buttonLabel String (optional) - Custom label for the confirmation button, when\nleft empty the default label will be used.filters FileFilter[] (optional)message String (optional) macOS - Message to display above text fields.nameFieldLabel String (optional) macOS - Custom label for the text\ndisplayed in front of the filename text field.showsTagField Boolean (optional) macOS - Show the tags input box, defaults to true.properties String[] (optional)showHiddenFiles - Show hidden files in dialog.createDirectory macOS - Allow creating new directories from dialog.treatPackageAsDirectory macOS - Treat packages, such as .app folders,\nas a directory instead of a file.showOverwriteConfirmation Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.dontAddToRecent Windows - Do not add the item being saved to the recent documents list.securityScopedBookmarks Boolean (optional) macOS mas - Create a security scoped bookmark when packaged for the Mac App Store. If this option is enabled and the file doesn't already exist a blank file will be created at the chosen path.Returns Promise<Object> - Resolve with an object containing the following:
canceled Boolean - whether or not the dialog was canceled.filePath String (optional) - If the dialog is canceled, this will be undefined.bookmark String (optional) macOS mas - Base64 encoded string which contains the security scoped bookmark data for the saved file. securityScopedBookmarks must be enabled for this to be present. (For return values, see table here.)The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
The filters specifies an array of file types that can be displayed, see\ndialog.showOpenDialog for an example.
Note: On macOS, using the asynchronous version is recommended to avoid issues when\nexpanding and collapsing the dialog.
\ndialog.showMessageBoxSync([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objectmessage String - Content of the message box.type String (optional) - Can be \"none\", \"info\", \"error\", \"question\" or\n\"warning\". On Windows, \"question\" displays the same icon as \"info\", unless\nyou set an icon using the \"icon\" option. On macOS, both \"warning\" and\n\"error\" display the same warning icon.buttons String[] (optional) - Array of texts for buttons. On Windows, an empty array\nwill result in one button labeled \"OK\".defaultId Integer (optional) - Index of the button in the buttons array which will\nbe selected by default when the message box opens.title String (optional) - Title of the message box, some platforms will not show it.detail String (optional) - Extra information of the message.icon (NativeImage | String) (optional)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (optional) - The index of the button to be used to cancel the dialog, via\nthe Esc key. By default this is assigned to the first button with \"cancel\" or \"no\" as the\nlabel. If no such labeled buttons exist and this option is not set, 0 will be used as the\nreturn value.noLink Boolean (optional) - On Windows Electron will try to figure out which one of\nthe buttons are common buttons (like \"Cancel\" or \"Yes\"), and show the\nothers as command links in the dialog. This can make the dialog appear in\nthe style of modern Windows apps. If you don't like this behavior, you can\nset noLink to true.normalizeAccessKeys Boolean (optional) - Normalize the keyboard access keys\nacross platforms. Default is false. Enabling this assumes & is used in\nthe button labels for the placement of the keyboard shortcut access key\nand labels will be converted so they work correctly on each platform, &\ncharacters are removed on macOS, converted to _ on Linux, and left\nuntouched on Windows. For example, a button label of Vie&w will be\nconverted to Vie_w on Linux and View on macOS and can be selected\nvia Alt-W on Windows and Linux.Returns Integer - the index of the clicked button.
Shows a message box, it will block the process until the message box is closed.\nIt returns the index of the clicked button.
\nThe browserWindow argument allows the dialog to attach itself to a parent window, making it modal.\nIf browserWindow is not shown dialog will not be attached to it. In such case it will be displayed as an independent window.
dialog.showMessageBox([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objectmessage String - Content of the message box.type String (optional) - Can be \"none\", \"info\", \"error\", \"question\" or\n\"warning\". On Windows, \"question\" displays the same icon as \"info\", unless\nyou set an icon using the \"icon\" option. On macOS, both \"warning\" and\n\"error\" display the same warning icon.buttons String[] (optional) - Array of texts for buttons. On Windows, an empty array\nwill result in one button labeled \"OK\".defaultId Integer (optional) - Index of the button in the buttons array which will\nbe selected by default when the message box opens.signal AbortSignal (optional) - Pass an instance of AbortSignal to\noptionally close the message box, the message box will behave as if it was\ncancelled by the user. On macOS, signal does not work with message boxes\nthat do not have a parent window, since those message boxes run\nsynchronously due to platform limitations.title String (optional) - Title of the message box, some platforms will not show it.detail String (optional) - Extra information of the message.checkboxLabel String (optional) - If provided, the message box will\ninclude a checkbox with the given label.checkboxChecked Boolean (optional) - Initial checked state of the\ncheckbox. false by default.icon NativeImage (optional)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (optional) - The index of the button to be used to cancel the dialog, via\nthe Esc key. By default this is assigned to the first button with \"cancel\" or \"no\" as the\nlabel. If no such labeled buttons exist and this option is not set, 0 will be used as the\nreturn value.noLink Boolean (optional) - On Windows Electron will try to figure out which one of\nthe buttons are common buttons (like \"Cancel\" or \"Yes\"), and show the\nothers as command links in the dialog. This can make the dialog appear in\nthe style of modern Windows apps. If you don't like this behavior, you can\nset noLink to true.normalizeAccessKeys Boolean (optional) - Normalize the keyboard access keys\nacross platforms. Default is false. Enabling this assumes & is used in\nthe button labels for the placement of the keyboard shortcut access key\nand labels will be converted so they work correctly on each platform, &\ncharacters are removed on macOS, converted to _ on Linux, and left\nuntouched on Windows. For example, a button label of Vie&w will be\nconverted to Vie_w on Linux and View on macOS and can be selected\nvia Alt-W on Windows and Linux.Returns Promise<Object> - resolves with a promise containing the following properties:
response Number - The index of the clicked button.checkboxChecked Boolean - The checked state of the checkbox if\ncheckboxLabel was set. Otherwise false.Shows a message box.
\nThe browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
dialog.showErrorBox(title, content)title String - The title to display in the error box.content String - The text content to display in the error box.Displays a modal dialog that shows an error message.
\nThis API can be called safely before the ready event the app module emits,\nit is usually used to report errors in early stage of startup. If called\nbefore the app readyevent on Linux, the message will be emitted to stderr,\nand no GUI dialog will appear.
dialog.showCertificateTrustDialog([browserWindow, ]options) macOS WindowsbrowserWindow BrowserWindow (optional)options Objectcertificate Certificate - The certificate to trust/import.message String - The message to display to the user.Returns Promise<void> - resolves when the certificate trust dialog is shown.
On macOS, this displays a modal dialog that shows a message and certificate\ninformation, and gives the user the option of trusting/importing the\ncertificate. If you provide a browserWindow argument the dialog will be\nattached to the parent window, making it modal.
On Windows the options are more limited, due to the Win32 APIs used:
\nmessage argument is not used, as the OS provides its own confirmation\ndialog.browserWindow argument is ignored since it is not possible to make\nthis confirmation dialog modal.showOpenDialog, showOpenDialogSync, showSaveDialog, and showSaveDialogSync will return a bookmarks array.
| Build Type | securityScopedBookmarks boolean | Return Type | Return Value |
|---|---|---|---|
| macOS mas | True | Success | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | Error | [''] (array of empty string) |
| macOS mas | False | NA | [] (empty array) |
| non mas | any | NA | [] (empty array) |
On macOS, dialogs are presented as sheets attached to a window if you provide\na BrowserWindow reference in the browserWindow parameter, or modals if no\nwindow is provided.
You can call BrowserWindow.getCurrentWindow().setSheetOffset(offset) to change\nthe offset from the window frame where sheets are attached.
id Number - Unique identifier associated with the display.rotation Number - Can be 0, 90, 180, 270, represents screen rotation in\nclock-wise degrees.scaleFactor Number - Output device's pixel scale factor.touchSupport String - Can be available, unavailable, unknown.monochrome Boolean - Whether or not the display is a monochrome display.accelerometerSupport String - Can be available, unavailable, unknown.colorSpace String - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversionscolorDepth Number - The number of bits per pixel.depthPerComponent Number - The number of bits per color component.displayFrequency Number - The display refresh rate.bounds Rectangle - the bounds of the display in DIP points.size SizeworkArea Rectangle - the work area of the display in DIP points.workAreaSize Sizeinternal Boolean - true for an internal display and false for an external displayThe Display object represents a physical display connected to the system. A\nfake Display may exist on a headless system, or a Display may correspond to\na remote, virtual display.
\n\nControl your app in the macOS dock
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The following example shows how to bounce your icon on the dock.
\nconst { app } = require('electron')\napp.dock.bounce()\ndock.bounce([type]) macOStype String (optional) - Can be critical or informational. The default is\ninformationalReturns Integer - an ID representing the request.
When critical is passed, the dock icon will bounce until either the\napplication becomes active or the request is canceled.
When informational is passed, the dock icon will bounce for one second.\nHowever, the request remains active until either the application becomes active\nor the request is canceled.
Nota Bene: This method can only be used while the app is not focused; when the app is focused it will return -1.
\ndock.cancelBounce(id) macOSid IntegerCancel the bounce of id.
dock.downloadFinished(filePath) macOSfilePath StringBounces the Downloads stack if the filePath is inside the Downloads folder.
\ndock.setBadge(text) macOStext StringSets the string to be displayed in the dock’s badging area.
\ndock.getBadge() macOSReturns String - The badge string of the dock.
dock.hide() macOSHides the dock icon.
\ndock.show() macOSReturns Promise<void> - Resolves when the dock icon is shown.
dock.isVisible() macOSReturns Boolean - Whether the dock icon is visible.
dock.setMenu(menu) macOSmenu MenuSets the application's [dock menu][dock-menu].
\ndock.getMenu() macOSReturns Menu | null - The application's [dock menu][dock-menu].
dock.setIcon(image) macOSimage (NativeImage | String)Sets the image associated with this dock icon.
\n\nControl file downloads from remote sources.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
DownloadItem is an EventEmitter that represents a download item in Electron.\nIt is used in will-download event of Session class, and allows users to\ncontrol the download item.
// In the main process.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.session.on('will-download', (event, item, webContents) => {\n // Set the save path, making Electron not to prompt a save dialog.\n item.setSavePath('/tmp/save.pdf')\n\n item.on('updated', (event, state) => {\n if (state === 'interrupted') {\n console.log('Download is interrupted but can be resumed')\n } else if (state === 'progressing') {\n if (item.isPaused()) {\n console.log('Download is paused')\n } else {\n console.log(`Received bytes: ${item.getReceivedBytes()}`)\n }\n }\n })\n item.once('done', (event, state) => {\n if (state === 'completed') {\n console.log('Download successfully')\n } else {\n console.log(`Download failed: ${state}`)\n }\n })\n})\nReturns:
\nevent Eventstate String - Can be progressing or interrupted.Emitted when the download has been updated and is not done.
\nThe state can be one of following:
progressing - The download is in-progress.interrupted - The download has interrupted and can be resumed.Returns:
\nevent Eventstate String - Can be completed, cancelled or interrupted.Emitted when the download is in a terminal state. This includes a completed\ndownload, a cancelled download (via downloadItem.cancel()), and interrupted\ndownload that can't be resumed.
The state can be one of following:
completed - The download completed successfully.cancelled - The download has been cancelled.interrupted - The download has interrupted and can not resume.The downloadItem object has the following methods:
downloadItem.setSavePath(path)path String - Set the save file path of the download item.The API is only available in session's will-download callback function.\nIf path doesn't exist, Electron will try to make the directory recursively.\nIf user doesn't set the save path via the API, Electron will use the original\nroutine to determine the save path; this usually prompts a save dialog.
downloadItem.getSavePath()Returns String - The save path of the download item. This will be either the path\nset via downloadItem.setSavePath(path) or the path selected from the shown\nsave dialog.
downloadItem.setSaveDialogOptions(options)options SaveDialogOptions - Set the save file dialog options. This object has the same\nproperties as the options parameter of dialog.showSaveDialog().This API allows the user to set custom options for the save dialog that opens\nfor the download item by default.\nThe API is only available in session's will-download callback function.
downloadItem.getSaveDialogOptions()Returns SaveDialogOptions - Returns the object previously set by downloadItem.setSaveDialogOptions(options).
downloadItem.pause()Pauses the download.
\ndownloadItem.isPaused()Returns Boolean - Whether the download is paused.
downloadItem.resume()Resumes the download that has been paused.
\nNote: To enable resumable downloads the server you are downloading from must support range requests and provide both Last-Modified and ETag header values. Otherwise resume() will dismiss previously received bytes and restart the download from the beginning.
downloadItem.canResume()Returns Boolean - Whether the download can resume.
downloadItem.cancel()Cancels the download operation.
\ndownloadItem.getURL()Returns String - The origin URL where the item is downloaded from.
downloadItem.getMimeType()Returns String - The files mime type.
downloadItem.hasUserGesture()Returns Boolean - Whether the download has user gesture.
downloadItem.getFilename()Returns String - The file name of the download item.
Note: The file name is not always the same as the actual one saved in local\ndisk. If user changes the file name in a prompted download saving dialog, the\nactual name of saved file will be different.
\ndownloadItem.getTotalBytes()Returns Integer - The total size in bytes of the download item.
If the size is unknown, it returns 0.
\ndownloadItem.getReceivedBytes()Returns Integer - The received bytes of the download item.
downloadItem.getContentDisposition()Returns String - The Content-Disposition field from the response\nheader.
downloadItem.getState()Returns String - The current state. Can be progressing, completed, cancelled or interrupted.
Note: The following methods are useful specifically to resume a\ncancelled item when session is restarted.
downloadItem.getURLChain()Returns String[] - The complete URL chain of the item including any redirects.
downloadItem.getLastModifiedTime()Returns String - Last-Modified header value.
downloadItem.getETag()Returns String - ETag header value.
downloadItem.getStartTime()Returns Double - Number of seconds since the UNIX epoch when the download was\nstarted.
downloadItem.savePathA String property that determines the save file path of the download item.
The property is only available in session's will-download callback function.\nIf user doesn't set the save path via the property, Electron will use the original\nroutine to determine the save path; this usually prompts a save dialog.
Special notes:
\n-beta.1 and stable dates are our solid release dates.| Electron | Alpha | Beta | Stable | Chrome | Node |
|---|---|---|---|---|---|
| 2.0.0 | -- | 2018-Feb-21 | 2018-May-01 | M61 | v8.9 |
| 3.0.0 | -- | 2018-Jun-21 | 2018-Sep-18 | M66 | v10.2 |
| 4.0.0 | -- | 2018-Oct-11 | 2018-Dec-20 | M69 | v10.11 |
| 5.0.0 | -- | 2019-Jan-22 | 2019-Apr-24 | M73 | v12.0 |
| 6.0.0 | -- | 2019-May-01 | 2019-Jul-30 | M76 | v12.4 |
| 7.0.0 | -- | 2019-Aug-01 | 2019-Oct-22 | M78 | v12.8 |
| 8.0.0 | -- | 2019-Oct-24 | 2020-Feb-04 | M80 | v12.13 |
| 9.0.0 | -- | 2020-Feb-06 | 2020-May-19 | M83 | v12.14 |
| 10.0.0 | -- | 2020-May-21 | 2020-Aug-25 | M85 | v12.16 |
| 11.0.0 | -- | 2020-Aug-27 | 2020-Nov-17 | M87 | v12.18 |
| 12.0.0 | -- | 2020-Nov-19 | 2021-Mar-02 | M89 | v14.16 |
| 13.0.0 | -- | 2021-Mar-04 | 2021-May-25 | M91 | v14.16 |
| 14.0.0 | -- | 2021-May-27 | 2021-Aug-31 | M93 | v14.17 |
| 15.0.0 | 2021-Jul-20 | 2021-Sep-01 | 2021-Sep-21 | M94 | v16.5 |
| 16.0.0 | -- | 2021-Sep-23 | 2021-Nov-16 | M96 | TBD |
\n\nA detailed look at our versioning policy and implementation.
\n
As of version 2.0.0, Electron follows SemVer. The following command will install the most recent stable build of Electron:
\nnpm install --save-dev electron\nTo update an existing project to use the latest stable version:
\nnpm install --save-dev electron@latest\nElectron versions < 2.0 did not conform to the SemVer spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. While convenient for developers merging features, it creates problems for developers of client-facing applications. The QA testing cycles of major apps like Slack, Stride, Teams, Skype, VS Code, Atom, and Desktop can be lengthy and stability is a highly desired outcome. There is a high risk in adopting new features while trying to absorb bug fixes.
\nHere is an example of the 1.x strategy:
\n![\"1.x](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/versioning-sketch-0.png\")
An app developed with 1.8.1 cannot take the 1.8.3 bug fix without either absorbing the 1.8.2 feature, or by backporting the fix and maintaining a new release line.
There are several major changes from our 1.x strategy outlined below. Each change is intended to satisfy the needs and priorities of developers/maintainers and app developers.
\n-beta tagsmaster branch is versionless; only stabilization branches contain version informationWe will cover in detail how git branching works, how npm tagging works, what developers should expect to see, and how one can backport changes.
\nFrom 2.0 onward, Electron will follow SemVer.
\nBelow is a table explicitly mapping types of changes to their corresponding category of SemVer (e.g. Major, Minor, Patch).
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Major Version Increments | Minor Version Increments | Patch Version Increments |
|---|---|---|
| Electron breaking API changes | Electron non-breaking API changes | Electron bug fixes |
| Node.js major version updates | Node.js minor version updates | Node.js patch version updates |
| Chromium version updates | fix-related chromium patches |
Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
\nStabilization branches are branches that run parallel to master, taking in only cherry-picked commits that are related to security or stability. These branches are never merged back to master.
\n![\"Stabilization](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/versioning-sketch-1.png\")
Since Electron 8, stabilization branches are always major version lines, and named against the following template $MAJOR-x-y e.g. 8-x-y. Prior to that we used minor version lines and named them as $MAJOR-$MINOR-x e.g. 2-0-x
We allow for multiple stabilization branches to exist simultaneously, and intend to support at least two in parallel at all times, backporting security fixes as necessary.\n![\"Multiple](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/versioning-sketch-2.png\")
Older lines will not be supported by GitHub, but other groups can take ownership and backport stability and security fixes on their own. We discourage this, but recognize that it makes life easier for many app developers.
\nDevelopers want to know which releases are safe to use. Even seemingly innocent features can introduce regressions in complex applications. At the same time, locking to a fixed version is dangerous because you’re ignoring security patches and bug fixes that may have come out since your version. Our goal is to allow the following standard semver ranges in package.json :
~2.0.0 to admit only stability or security related fixes to your 2.0.0 release.^2.0.0 to admit non-breaking reasonably stable feature work as well as security and bug fixes.What’s important about the second point is that apps using ^ should still be able to expect a reasonable level of stability. To accomplish this, SemVer allows for a pre-release identifier to indicate a particular version is not yet safe or stable.
Whatever you choose, you will periodically have to bump the version in your package.json as breaking changes are a fact of Chromium life.
The process is as follows:
\nbeta.N, e.g. 2.0.0-beta.1. After the first beta, subsequent beta releases must meet all of the following conditions:2.0.0-beta.2.2.0.0. After the first stable, all changes must be backwards-compatible bug or security fixes.2.0.1.Specifically, the above means:
\nFor each major and minor bump, you should expect to see something like the following:
\n2.0.0-beta.1\n2.0.0-beta.2\n2.0.0-beta.3\n2.0.0\n2.0.1\n2.0.2\nAn example lifecycle in pictures:
\n2.0.0-beta.1.\n![\"New](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/versioning-sketch-3.png\")
2.0.0-beta.2.\n![\"Bugfix](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/versioning-sketch-4.png\")
2.0.0.\n![\"Beta](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/versioning-sketch-5.png\")
2-0-x line and release 2.0.1.\n![\"Security](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/versioning-sketch-6.png\")
A few examples of how various SemVer ranges will pick up new releases:
\n![\"Semvers](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/versioning-sketch-7.png\")
Our strategy has a few tradeoffs, which for now we feel are appropriate. Most importantly that new features in master may take a while before reaching a stable release line. If you want to try a new feature immediately, you will have to build Electron yourself.
\nAs a future consideration, we may introduce one or both of the following:
\nFeature flags are a common practice in Chromium, and are well-established in the web-development ecosystem. In the context of Electron, a feature flag or soft branch must have the following properties:
\nWe seek to increase clarity at all levels of the update and releases process. Starting with 2.0.0 we will require pull requests adhere to the Conventional Commits spec, which can be summarized as follows:
Commits that would result in a SemVer major bump must start their body with BREAKING CHANGE:.
Commits that would result in a SemVer minor bump must start with feat:.
Commits that would result in a SemVer patch bump must start with fix:.
We allow squashing of commits, provided that the squashed message adheres to the above message format.
\nIt is acceptable for some commits in a pull request to not include a semantic prefix, as long as the pull request title contains a meaningful encompassing semantic message.
\nmastermaster branch will always contain the next major version X.0.0-nightly.DATE in its package.jsonpackage.jsonmaster is always versioned as the next theoretical release branchLike NW.js, Electron provides a platform to write desktop applications with web\ntechnologies. Both platforms enable developers to utilize HTML, JavaScript, and\nNode.js. On the surface, they seem very similar.
\nThere are however fundamental differences between the two projects that make\nElectron a completely separate product from NW.js.
\nIn NW.js, the main entry point of an application can be an HTML web page. In\nthat case, NW.js will open the given entry point in a browser window.
\nIn Electron, the entry point is always a JavaScript script. Instead of providing a\nURL directly, you manually create a browser window and load an HTML file using\nthe API. You also need to listen to window events to decide when to quit the\napplication.
\nElectron works more like the Node.js runtime. Electron's APIs are lower level so\nyou can use it for browser testing in place of\nPhantomJS.
\nIn NW.js, the Node integration in web pages requires patching Chromium to work,\nwhile in Electron we chose a different way to integrate the libuv loop with\neach platform's message loop to avoid hacking Chromium. See the\nnode_bindings code for how that was done.
If you are an experienced NW.js user, you should be familiar with the concept of\nNode context and web context. These concepts were invented because of how NW.js\nwas implemented.
\nBy using the\nmulti-context\nfeature of Node, Electron doesn't introduce a new JavaScript context in web\npages.
\nNote: NW.js has optionally supported multi-context since 0.13.
\nNW.js still offers a \"legacy release\" that supports Windows XP. It doesn't\nreceive security updates.
\nGiven that hardware manufacturers, Microsoft, Chromium, and Node.js haven't\nreleased even critical security updates for that system, we have to warn you\nthat using Windows XP is wildly insecure and outright irresponsible.
\nHowever, we understand that requirements outside our wildest imagination may\nexist, so if you're looking for something like Electron that runs on Windows XP,\nthe NW.js legacy release might be the right fit for you.
\nThere are numerous differences in the amount of supported features. Electron has\na bigger community, more production apps using it, and a large amount of\nuserland modules available on npm.
\nAs an example, Electron has built-in support for automatic updates and countless\ntools that make the creation of installers easier. As an example in favor of\nNW.js, NW.js supports more Chrome.* APIs for the development of Chrome Apps.
Naturally, we believe that Electron is the better platform for polished\nproduction applications built with web technologies (like Visual Studio Code,\nSlack, or Facebook Messenger); however, we want to be fair to our web technology\nfriends. If you have feature needs that Electron does not meet, you might want\nto try NW.js.
", "title": "Technical Differences Between Electron and NW.js", "description": "" }, "/docs/api/environment-variables": { "locale": "en-US", "slug": "environment-variables", "href": "/docs/api/environment-variables", "crowdinFileId": "256315", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/environment-variables.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nControl application configuration and behavior without changing code.
\n
Certain Electron behaviors are controlled by environment variables because they\nare initialized earlier than the command line flags and the app's code.
\nPOSIX shell example:
\n$ export ELECTRON_ENABLE_LOGGING=true\n$ electron\nWindows console example:
\n> set ELECTRON_ENABLE_LOGGING=true\n> electron\nThe following environment variables are intended primarily for use at runtime\nin packaged Electron applications.
\nNODE_OPTIONSElectron includes support for a subset of Node's NODE_OPTIONS. The majority are supported with the exception of those which conflict with Chromium's use of BoringSSL.
Example:
\nexport NODE_OPTIONS=\"--no-warnings --max-old-space-size=2048\"\nUnsupported options are:
\n--use-bundled-ca\n--force-fips\n--enable-fips\n--openssl-config\n--use-openssl-ca\nNODE_OPTIONS are explicitly disallowed in packaged apps, except for the following:
--max-http-header-size\n--http-parser\nGOOGLE_API_KEYGeolocation support in Electron requires the use of Google Cloud Platform's\ngeolocation webservice. To enable this feature, acquire a\nGoogle API key\nand place the following code in your main process file, before opening any\nbrowser windows that will make geolocation requests:
\nprocess.env.GOOGLE_API_KEY = 'YOUR_KEY_HERE'\nBy default, a newly generated Google API key may not be allowed to make geolocation requests.\nTo enable the geolocation webservice for your project, enable it through the\nAPI library.
\nN.B. You will need to add a\nBilling Account\nto the project associated to the API key for the geolocation webservice to work.
\nELECTRON_NO_ASARDisables ASAR support. This variable is only supported in forked child processes\nand spawned child processes that set ELECTRON_RUN_AS_NODE.
ELECTRON_RUN_AS_NODEStarts the process as a normal Node.js process.
\nIn this mode, you will be able to pass cli options to Node.js as\nyou would when running the normal Node.js executable, with the exception of the following flags:
\nThese flags are disabled owing to the fact that Electron uses BoringSSL instead of OpenSSL when building Node.js'\ncrypto module, and so will not work as designed.
ELECTRON_NO_ATTACH_CONSOLE WindowsDon't attach to the current console session.
\nELECTRON_FORCE_WINDOW_MENU_BAR LinuxDon't use the global menu bar on Linux.
\nELECTRON_TRASH LinuxSet the trash implementation on Linux. Default is gio.
Options:
\ngvfs-trashtrash-clikioclient5kioclientThe following environment variables are intended primarily for development and\ndebugging purposes.
\nELECTRON_ENABLE_LOGGINGPrints Chromium's internal logging to the console.
\nSetting this variable is the same as passing --enable-logging\non the command line. For more info, see --enable-logging in command-line\nswitches.
ELECTRON_LOG_FILESets the file destination for Chromium's internal logging.
\nSetting this variable is the same as passing --log-file\non the command line. For more info, see --log-file in command-line\nswitches.
ELECTRON_DEBUG_DRAG_REGIONSAdds coloration to draggable regions on BrowserViews on macOS - draggable regions will be colored\ngreen and non-draggable regions will be colored red to aid debugging.
ELECTRON_DEBUG_NOTIFICATIONSAdds extra logs to Notification lifecycles on macOS to aid in debugging. Extra logging will be displayed when new Notifications are created or activated. They will also be displayed when common a\ntions are taken: a notification is shown, dismissed, its button is clicked, or it is replied to.
Sample output:
\nNotification created (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification displayed (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification activated (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification replied to (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nELECTRON_LOG_ASAR_READSWhen Electron reads from an ASAR file, log the read offset and file path to\nthe system tmpdir. The resulting file can be provided to the ASAR module\nto optimize file ordering.
ELECTRON_ENABLE_STACK_DUMPINGPrints the stack trace to the console when Electron crashes.
\nThis environment variable will not work if the crashReporter is started.
ELECTRON_DEFAULT_ERROR_MODE WindowsShows the Windows's crash dialog when Electron crashes.
\nThis environment variable will not work if the crashReporter is started.
ELECTRON_OVERRIDE_DIST_PATHWhen running from the electron package, this variable tells\nthe electron command to use the specified build of Electron instead of\nthe one downloaded by npm install. Usage:
export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing\nElectron sets some variables in your environment at runtime.
\nORIGINAL_XDG_CURRENT_DESKTOPThis variable is set to the value of XDG_CURRENT_DESKTOP that your application\noriginally launched with. Electron sometimes modifies the value of XDG_CURRENT_DESKTOP\nto affect other logic within Chromium so if you want access to the original value\nyou should look up this environment variable instead.
GlobalEventpreventDefault VoidFunctionSome of Electrons APIs are tagged with _Experimental_ in the documentation.\nThis tag indicates that the API may not be considered stable and the API may\nbe removed or modified more frequently than other APIs with less warning.
Anyone can request an API be tagged as experimental in a feature PR, disagreements\non the experimental nature of a feature can be discussed in the API WG if they\ncan't be resolved in the PR.
\nOnce an API has been stable and in at least two major stable release lines it\ncan be nominated to have its experimental tag removed. This discussion should\nhappen at an API WG meeting. Things to consider when discussing / nominating:
\nid Stringmanifest any - Copy of the extension's manifest data.name Stringpath String - The extension's file path.version Stringurl String - The extension's chrome-extension:// URL.name Stringversion StringElectron supports a subset of the Chrome Extensions\nAPI, primarily to support DevTools extensions and\nChromium-internal extensions, but it also happens to support some other\nextension capabilities.
\n\n\nNote: Electron does not support arbitrary Chrome extensions from the\nstore, and it is a non-goal of the Electron project to be perfectly\ncompatible with Chrome's implementation of Extensions.
\n
Electron only supports loading unpacked extensions (i.e., .crx files do not\nwork). Extensions are installed per-session. To load an extension, call\nses.loadExtension:
const { session } = require('electron')\n\nsession.loadExtension('path/to/unpacked/extension').then(({ id }) => {\n // ...\n})\nLoaded extensions will not be automatically remembered across exits; if you do\nnot call loadExtension when the app runs, the extension will not be loaded.
Note that loading extensions is only supported in persistent sessions.\nAttempting to load an extension into an in-memory session will throw an error.
\nSee the session documentation for more information about\nloading, unloading, and querying active extensions.
We support the following extensions APIs, with some caveats. Other APIs may\nadditionally be supported, but support for any APIs not listed here is\nprovisional and may be removed.
\nchrome.devtools.inspectedWindowAll features of this API are supported.
\nchrome.devtools.networkAll features of this API are supported.
\nchrome.devtools.panelsAll features of this API are supported.
\nchrome.extensionThe following properties of chrome.extension are supported:
chrome.extension.lastErrorThe following methods of chrome.extension are supported:
chrome.extension.getURLchrome.extension.getBackgroundPagechrome.runtimeThe following properties of chrome.runtime are supported:
chrome.runtime.lastErrorchrome.runtime.idThe following methods of chrome.runtime are supported:
chrome.runtime.getBackgroundPagechrome.runtime.getManifestchrome.runtime.getPlatformInfochrome.runtime.getURLchrome.runtime.connectchrome.runtime.sendMessagechrome.runtime.reloadThe following events of chrome.runtime are supported:
chrome.runtime.onStartupchrome.runtime.onInstalledchrome.runtime.onSuspendchrome.runtime.onSuspendCanceledchrome.runtime.onConnectchrome.runtime.onMessagechrome.storageOnly chrome.storage.local is supported; chrome.storage.sync and\nchrome.storage.managed are not.
chrome.tabsThe following methods of chrome.tabs are supported:
chrome.tabs.sendMessagechrome.tabs.executeScript\n\nNote: In Chrome, passing
\n-1as a tab ID signifies the \"currently active\ntab\". Since Electron has no such concept, passing-1as a tab ID is not\nsupported and will raise an error.
chrome.managementThe following methods of chrome.management are supported:
chrome.management.getAllchrome.management.getchrome.management.getSelfchrome.management.getPermissionWarningsByIdchrome.management.getPermissionWarningsByManifestchrome.management.onEnabledchrome.management.onDisabledchrome.webRequestAll features of this API are supported.
\n\n", "title": "Chrome Extension Support", "description": "Note: Electron does not support arbitrary Chrome extensions from the\nstore, and it is a non-goal of the Electron project to be perfectly\ncompatible with Chrome's implementation of Extensions." }, "/docs/faq": { "locale": "en-US", "slug": "faq", "href": "/docs/faq", "crowdinFileId": "256121", "githubUrl": "https://github.com/electron/electron/tree/main/docs/faq.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "NOTE: Electron's
\nwebRequestmodule takes precedence overchrome.webRequestif there are conflicting handlers.
When running npm install electron, some users occasionally encounter\ninstallation errors.
In almost all cases, these errors are the result of network problems and not\nactual issues with the electron npm package. Errors like ELIFECYCLE,\nEAI_AGAIN, ECONNRESET, and ETIMEDOUT are all indications of such\nnetwork problems. The best resolution is to try switching networks, or\nwait a bit and try installing again.
You can also attempt to download Electron directly from\nelectron/electron/releases\nif installing via npm is failing.
The Chrome version of Electron is usually bumped within one or two weeks after\na new stable Chrome version gets released. This estimate is not guaranteed and\ndepends on the amount of work involved with upgrading.
\nOnly the stable channel of Chrome is used. If an important fix is in beta or dev\nchannel, we will back-port it.
\nFor more information, please see the security introduction.
\nWhen a new version of Node.js gets released, we usually wait for about a month\nbefore upgrading the one in Electron. So we can avoid getting affected by bugs\nintroduced in new Node.js versions, which happens very often.
\nNew features of Node.js are usually brought by V8 upgrades, since Electron is\nusing the V8 shipped by Chrome browser, the shiny new JavaScript feature of a\nnew Node.js version is usually already in Electron.
\nTo share data between web pages (the renderer processes) the simplest way is to\nuse HTML5 APIs which are already available in browsers. Good candidates are\nStorage API, localStorage,\nsessionStorage, and IndexedDB.
Alternatively, you can use the IPC primitives that are provided by Electron. To\nshare data between the main and renderer processes, you can use the\nipcMain and ipcRenderer modules.\nTo communicate directly between web pages, you can send a\nMessagePort from one to the other, possibly via the main process\nusing ipcRenderer.postMessage().\nSubsequent communication over message ports is direct and does not detour through\nthe main process.
This happens when the variable which is used to store the tray gets\ngarbage collected.
\nIf you encounter this problem, the following articles may prove helpful:
\n\nIf you want a quick fix, you can make the variables global by changing your\ncode from this:
\nconst { app, Tray } = require('electron')\napp.whenReady().then(() => {\n const tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\nto this:
\nconst { app, Tray } = require('electron')\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\nDue to the Node.js integration of Electron, there are some extra symbols\ninserted into the DOM like module, exports, require. This causes problems\nfor some libraries since they want to insert the symbols with the same names.
To solve this, you can turn off node integration in Electron:
\n// In the main process.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n webPreferences: {\n nodeIntegration: false\n }\n})\nwin.show()\nBut if you want to keep the abilities of using Node.js and Electron APIs, you\nhave to rename the symbols in the page before including other libraries:
\n<head>\n<script>\nwindow.nodeRequire = require;\ndelete window.require;\ndelete window.exports;\ndelete window.module;\n</script>\n<script type=\"text/javascript\" src=\"jquery.js\"></script>\n</head>\nrequire('electron').xxx is undefined.When using Electron's built-in module you might encounter an error like this:
\n> require('electron').webFrame.setZoomFactor(1.0)\nUncaught TypeError: Cannot read property 'setZoomLevel' of undefined\nIt is very likely you are using the module in the wrong process. For example\nelectron.app can only be used in the main process, while electron.webFrame\nis only available in renderer processes.
If sub-pixel anti-aliasing is deactivated, then fonts on LCD screens can look blurry. Example:
\n![\"subpixel](\"/docs/images/subpixel-rendering-screenshot.gif\"){kind=tracking}
Sub-pixel anti-aliasing needs a non-transparent background of the layer containing the font glyphs. (See this issue for more info).
\nTo achieve this goal, set the background in the constructor for BrowserWindow:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n backgroundColor: '#fff'\n})\nThe effect is visible only on (some?) LCD screens. Even if you don't see a difference, some of your users may. It is best to always set the background this way, unless you have reasons not to do so.
\nNotice that just setting the background in the CSS does not have the desired effect.
", "title": "Electron FAQ", "description": "" }, "/docs/api/structures/file-filter": { "locale": "en-US", "slug": "file-filter", "href": "/docs/api/structures/file-filter", "crowdinFileId": "256435", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/file-filter.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "name Stringextensions String[]File Object\n\nUse the HTML5
\nFileAPI to work natively with files on the filesystem.
The DOM's File interface provides abstraction around native files in order to\nlet users work on native files directly with the HTML5 file API. Electron has\nadded a path attribute to the File interface which exposes the file's real\npath on filesystem.
Example of getting a real path from a dragged-onto-the-app file:
\n<div id=\"holder\">\n Drag your file here\n</div>\n\n<script>\n document.addEventListener('drop', (e) => {\n e.preventDefault();\n e.stopPropagation();\n\n for (const f of e.dataTransfer.files) {\n console.log('File(s) you dragged here: ', f.path)\n }\n });\n document.addEventListener('dragover', (e) => {\n e.preventDefault();\n e.stopPropagation();\n });\n</script>\npath String - The path to the file to send.headers Record<string, string> (optional) - Additional headers to be sent.\n\nOpen a window without toolbars, borders, or other graphical \"chrome\".
\n
A frameless window is a window that has no\nchrome, the parts of\nthe window, like toolbars, that are not a part of the web page. These are\noptions on the BrowserWindow class.
To create a frameless window, you need to set frame to false in\nBrowserWindow's options:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600, frame: false })\nwin.show()\nThere's an alternative way to specify a chromeless window on macOS and Windows.\nInstead of setting frame to false which disables both the titlebar and window controls,\nyou may want to have the title bar hidden and your content extend to the full window size,\nyet still preserve the window controls (\"traffic lights\" on macOS) for standard window actions.\nYou can do so by specifying the titleBarStyle option:
hiddenResults in a hidden title bar and a full size content window. On macOS, the title bar still has the standard window controls (“traffic lights”) in the top left.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hidden' })\nwin.show()\nhiddenInsetResults in a hidden title bar with an alternative look where the traffic light buttons are slightly more inset from the window edge.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })\nwin.show()\ncustomButtonsOnHoverUses custom drawn close, and miniaturize buttons that display\nwhen hovering in the top left of the window. The fullscreen button\nis not available due to restrictions of frameless windows as they\ninterface with Apple's macOS window masks. These custom buttons prevent\nissues with mouse events that occur with the standard window toolbar buttons.\nThis option is only applicable for frameless windows.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover', frame: false })\nwin.show()\nWhen using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS, using one of the titleBarStyles as described above so\nthat the traffic lights are visible, or using titleBarStyle: hidden on Windows, you can access the Window Controls Overlay JavaScript APIs and\nCSS Environment Variables by setting the titleBarOverlay option to true. Specifying true will result in an overlay with default system colors.
On Windows, you can also specify the color of the overlay and its symbols by setting titleBarOverlay to an object with the options color and symbolColor. If an option is not specified, the color will default to its system color for the window control buttons:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: true\n})\nwin.show()\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: {\n color: '#2f3241',\n symbolColor: '#74b1be'\n }\n})\nwin.show()\nBy setting the transparent option to true, you can also make the frameless\nwindow transparent:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ transparent: true, frame: false })\nwin.show()\nresizable to true may make\na transparent window stop working on some platforms.blur filter only applies to the web page, so there is no way to apply\nblur effect to the content below the window (i.e. other applications open on\nthe user's system).--enable-transparent-visuals --disable-gpu in\nthe command line to disable GPU and allow ARGB to make transparent window,\nthis is caused by an upstream bug that alpha channel doesn't work on some\nNVidia drivers on\nLinux.To create a click-through window, i.e. making the window ignore all mouse\nevents, you can call the win.setIgnoreMouseEvents(ignore)\nAPI:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.setIgnoreMouseEvents(true)\nIgnoring mouse messages makes the web page oblivious to mouse movement, meaning\nthat mouse movement events will not be emitted. On Windows operating systems an\noptional parameter can be used to forward mouse move messages to the web page,\nallowing events such as mouseleave to be emitted:
const { ipcRenderer } = require('electron')\nconst el = document.getElementById('clickThroughElement')\nel.addEventListener('mouseenter', () => {\n ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })\n})\nel.addEventListener('mouseleave', () => {\n ipcRenderer.send('set-ignore-mouse-events', false)\n})\n\n// Main process\nconst { ipcMain } = require('electron')\nipcMain.on('set-ignore-mouse-events', (event, ...args) => {\n BrowserWindow.fromWebContents(event.sender).setIgnoreMouseEvents(...args)\n})\nThis makes the web page click-through when over el, and returns to normal\noutside it.
By default, the frameless window is non-draggable. Apps need to specify\n-webkit-app-region: drag in CSS to tell Electron which regions are draggable\n(like the OS's standard titlebar), and apps can also use\n-webkit-app-region: no-drag to exclude the non-draggable area from the\ndraggable region. Note that only rectangular shapes are currently supported.
Note: -webkit-app-region: drag is known to have problems while the developer tools are open. See this GitHub issue for more information including a workaround.
To make the whole window draggable, you can add -webkit-app-region: drag as\nbody's style:
<body style=\"-webkit-app-region: drag\">\n</body>\nAnd note that if you have made the whole window draggable, you must also mark\nbuttons as non-draggable, otherwise it would be impossible for users to click on\nthem:
\nbutton {\n -webkit-app-region: no-drag;\n}\nIf you're only setting a custom titlebar as draggable, you also need to make all\nbuttons in titlebar non-draggable.
\nIn a frameless window the dragging behavior may conflict with selecting text.\nFor example, when you drag the titlebar you may accidentally select the text on\nthe titlebar. To prevent this, you need to disable text selection within a\ndraggable area like this:
\n.titlebar {\n -webkit-user-select: none;\n -webkit-app-region: drag;\n}\nOn some platforms, the draggable area will be treated as a non-client frame, so\nwhen you right click on it a system menu will pop up. To make the context menu\nbehave correctly on all platforms you should never use a custom context menu on\ndraggable areas.
", "title": "Frameless Window", "description": "Open a window without toolbars, borders, or other graphical \"chrome\"." }, "/docs/tutorial/fuses": { "locale": "en-US", "slug": "fuses", "href": "/docs/tutorial/fuses", "crowdinFileId": "256201", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/fuses.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nPackage time feature toggles
\n
For a subset of Electron functionality it makes sense to disable certain features for an entire application. For example, 99% of apps don't make use of ELECTRON_RUN_AS_NODE, these applications want to be able to ship a binary that is incapable of using that feature. We also don't want Electron consumers building Electron from source as that is both a massive technical challenge and has a high cost of both time and money.
Fuses are the solution to this problem, at a high level they are \"magic bits\" in the Electron binary that can be flipped when packaging your Electron app to enable / disable certain features / restrictions. Because they are flipped at package time before you code sign your app the OS becomes responsible for ensuring those bits aren't flipped back via OS level code signing validation (Gatekeeper / App Locker).
\nWe've made a handy module @electron/fuses to make flipping these fuses easy. Check out the README of that module for more details on usage and potential error cases.
require('@electron/fuses').flipFuses(\n // Path to electron\n require('electron'),\n // Fuses to flip\n {\n runAsNode: false\n }\n)\nManually flipping fuses requires editing the Electron binary and modifying the fuse wire to be the sequence of bytes that represent the state of the fuses you want.
\nSomewhere in the Electron binary there will be a sequence of bytes that look like this:
\n| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |\nsentinel_bytes is always this exact string dL7pKGdnNz796PbbjQWNKmHXBZaB9tsXfuse_version is a single byte whose unsigned integer value represents the version of the fuse schemafuse_wire_length is a single byte whose unsigned integer value represents the number of fuses in the following fuse wirefuse_wire is a sequence of N bytes, each byte represents a single fuse and its state.To flip a fuse you find its position in the fuse wire and change it to \"0\" or \"1\" depending on the state you'd like.
\nYou can view the current schema here.
", "title": "Electron Fuses", "description": "Package time feature toggles" }, "/docs/api/global-shortcut": { "locale": "en-US", "slug": "global-shortcut", "href": "/docs/api/global-shortcut", "crowdinFileId": "256323", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/global-shortcut.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nDetect keyboard events when the application does not have keyboard focus.
\n
Process: Main
\nThe globalShortcut module can register/unregister a global keyboard shortcut\nwith the operating system so that you can customize the operations for various\nshortcuts.
Note: The shortcut is global; it will work even if the app does\nnot have the keyboard focus. This module cannot be used before the ready\nevent of the app module is emitted.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+X' shortcut listener.\n const ret = globalShortcut.register('CommandOrControl+X', () => {\n console.log('CommandOrControl+X is pressed')\n })\n\n if (!ret) {\n console.log('registration failed')\n }\n\n // Check whether a shortcut is registered.\n console.log(globalShortcut.isRegistered('CommandOrControl+X'))\n})\n\napp.on('will-quit', () => {\n // Unregister a shortcut.\n globalShortcut.unregister('CommandOrControl+X')\n\n // Unregister all shortcuts.\n globalShortcut.unregisterAll()\n})\nThe globalShortcut module has the following methods:
globalShortcut.register(accelerator, callback)accelerator Acceleratorcallback FunctionReturns Boolean - Whether or not the shortcut was registered successfully.
Registers a global shortcut of accelerator. The callback is called when\nthe registered shortcut is pressed by the user.
When the accelerator is already taken by other applications, this call will\nsilently fail. This behavior is intended by operating systems, since they don't\nwant applications to fight for global shortcuts.
\nThe following accelerators will not be registered successfully on macOS 10.14 Mojave unless\nthe app has been authorized as a trusted accessibility client:
\nglobalShortcut.registerAll(accelerators, callback)accelerators String[] - an array of Accelerators.callback FunctionRegisters a global shortcut of all accelerator items in accelerators. The callback is called when any of the registered shortcuts are pressed by the user.
When a given accelerator is already taken by other applications, this call will\nsilently fail. This behavior is intended by operating systems, since they don't\nwant applications to fight for global shortcuts.
\nThe following accelerators will not be registered successfully on macOS 10.14 Mojave unless\nthe app has been authorized as a trusted accessibility client:
\nglobalShortcut.isRegistered(accelerator)accelerator AcceleratorReturns Boolean - Whether this application has registered accelerator.
When the accelerator is already taken by other applications, this call will\nstill return false. This behavior is intended by operating systems, since they\ndon't want applications to fight for global shortcuts.
globalShortcut.unregister(accelerator)accelerator AcceleratorUnregisters the global shortcut of accelerator.
globalShortcut.unregisterAll()Unregisters all of the global shortcuts.
", "title": "globalShortcut", "description": "Detect keyboard events when the application does not have keyboard focus." }, "/docs/glossary": { "locale": "en-US", "slug": "glossary", "href": "/docs/glossary", "crowdinFileId": "256123", "githubUrl": "https://github.com/electron/electron/tree/main/docs/glossary.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "This page defines some terminology that is commonly used in Electron development.
\nASAR stands for Atom Shell Archive Format. An asar archive is a simple\ntar-like format that concatenates files into a single file. Electron can read\narbitrary files from it without unpacking the whole file.
The ASAR format was created primarily to improve performance on Windows when\nreading large quantities of small files (e.g. when loading your app's JavaScript\ndependency tree from node_modules).
Code signing is a process where an app developer digitally signs their code to\nensure that it hasn't been tampered with after packaging. Both Windows and\nmacOS implement their own version of code signing. As a desktop app developer,\nit's important that you sign your code if you plan on distributing it to the\ngeneral public.
\nFor more information, read the Code Signing tutorial.
\nContext isolation is a security measure in Electron that ensures that your\npreload script cannot leak privileged Electron or Node.js APIs to the web\ncontents in your renderer process. With context isolation enabled, the\nonly way to expose APIs from your preload script is through the\ncontextBridge API.
For more information, read the Context Isolation tutorial.
\nSee also: preload script, renderer process
\nThe C Runtime Library (CRT) is the part of the C++ Standard Library that\nincorporates the ISO C99 standard library. The Visual C++ libraries that\nimplement the CRT support native code development, and both mixed native and\nmanaged code, and pure managed code for .NET development.
\nAn Apple Disk Image is a packaging format used by macOS. DMG files are\ncommonly used for distributing application \"installers\".
\nInput Method Editor. A program that allows users to enter characters and\nsymbols not found on their keyboard. For example, this allows users of Latin\nkeyboards to input Chinese, Japanese, Korean and Indic characters.
\nInterface description language. Write function signatures and data types in a\nformat that can be used to generate interfaces in Java, C++, JavaScript, etc.
\nIPC stands for inter-process communication. Electron uses IPC to send\nserialized JSON messages between the main and renderer processes.
\nsee also: main process, renderer process
\nThe main process, commonly a file named main.js, is the entry point to every\nElectron app. It controls the life of the app, from open to close. It also\nmanages native elements such as the Menu, Menu Bar, Dock, Tray, etc. The\nmain process is responsible for creating each new renderer process in the app.\nThe full Node API is built in.
Every app's main process file is specified in the main property in\npackage.json. This is how electron . knows what file to execute at startup.
In Chromium, this process is referred to as the \"browser process\". It is\nrenamed in Electron to avoid confusion with renderer processes.
\nSee also: process, renderer process
\nAcronym for Apple's Mac App Store. For details on submitting your app to the\nMAS, see the Mac App Store Submission Guide.
\nAn IPC system for communicating intra- or inter-process, and that's important\nbecause Chrome is keen on being able to split its work into separate processes\nor not, depending on memory pressures etc.
\nSee https://chromium.googlesource.com/chromium/src/+/master/mojo/README.md
\nSee also: IPC
\nOn Windows, MSI packages are used by the Windows Installer\n(also known as Microsoft Installer) service to install and configure\napplications.
\nMore information can be found in Microsoft's documentation.
\nNative modules (also called addons in\nNode.js) are modules written in C or C++ that can be loaded into Node.js or\nElectron using the require() function, and used as if they were an\nordinary Node.js module. They are used primarily to provide an interface\nbetween JavaScript running in Node.js and C/C++ libraries.
\nNative Node modules are supported by Electron, but since Electron is very\nlikely to use a different V8 version from the Node binary installed in your\nsystem, you have to manually specify the location of Electron’s headers when\nbuilding native modules.
\nFor more information, read the [Native Node Modules] tutorial.
\nNotarization is a macOS-specific process where a developer can send a\ncode-signed app to Apple servers to get verified for malicious\ncomponents through an automated service.
\nSee also: code signing
\nOSR (offscreen rendering) can be used for loading heavy page in\nbackground and then displaying it after (it will be much faster).\nIt allows you to render page without showing it on screen.
\nFor more information, read the [Offscreen Rendering][osr] tutorial.
\nPreload scripts contain code that executes in a renderer process\nbefore its web contents begin loading. These scripts run within\nthe renderer context, but are granted more privileges by having\naccess to Node.js APIs.
\nSee also: renderer process, context isolation
\nA process is an instance of a computer program that is being executed. Electron\napps that make use of the main and one or many renderer process are\nactually running several programs simultaneously.
\nIn Node.js and Electron, each running process has a process object. This\nobject is a global that provides information about, and control over, the\ncurrent process. As a global, it is always available to applications without\nusing require().
See also: main process, renderer process
\nThe renderer process is a browser window in your app. Unlike the main process,\nthere can be multiple of these and each is run in a separate process.\nThey can also be hidden.
\nSee also: process, main process
\nThe sandbox is a security feature inherited from Chromium that restricts\nyour renderer processes to a limited set of permissions.
\nFor more information, read the Process Sandboxing tutorial.
\nSee also: process
\nSquirrel is an open-source framework that enables Electron apps to update\nautomatically as new versions are released. See the autoUpdater API for\ninfo about getting started with Squirrel.
\nThis term originated in the Unix community, where \"userland\" or \"userspace\"\nreferred to programs that run outside of the operating system kernel. More\nrecently, the term has been popularized in the Node and npm community to\ndistinguish between the features available in \"Node core\" versus packages\npublished to the npm registry by the much larger \"user\" community.
\nLike Node, Electron is focused on having a small set of APIs that provide\nall the necessary primitives for developing multi-platform desktop applications.\nThis design philosophy allows Electron to remain a flexible tool without being\noverly prescriptive about how it should be used. Userland enables users to\ncreate and share tools that provide additional functionality on top of what is\navailable in \"core\".
\nV8 is Google's open source JavaScript engine. It is written in C++ and is\nused in Google Chrome. V8 can run standalone, or can be embedded into any C++ application.
\nElectron builds V8 as part of Chromium and then points Node to that V8 when\nbuilding it.
\nV8's version numbers always correspond to those of Google Chrome. Chrome 59\nincludes V8 5.9, Chrome 58 includes V8 5.8, etc.
\n\nwebview tags are used to embed 'guest' content (such as external web pages) in\nyour Electron app. They are similar to iframes, but differ in that each\nwebview runs in a separate process. It doesn't have the same\npermissions as your web page and all interactions between your app and\nembedded content will be asynchronous. This keeps your app safe from the\nembedded content.
\n\nGoma is a distributed compiler service for open-source projects such as\nChromium and Android.
\n
Electron has a deployment of a custom Goma Backend that we make available to\nall Electron Maintainers. See the Access section below for details\non authentication. There is also a cache-only Goma endpoint that will be\nused by default if you do not have credentials. Requests to the cache-only\nGoma will not hit our cluster, but will read from our cache and should result\nin significantly faster build times.
Currently the only supported way to use Goma is to use our Build Tools.\nGoma configuration is automatically included when you set up build-tools.
If you are a maintainer and have access to our cluster, please ensure that you run\ne init with --goma=cluster in order to configure build-tools to use\nthe Goma cluster. If you have an existing config, you can just set \"goma\": \"cluster\"\nin your config file.
When you are using Goma you can run ninja with a substantially higher j\nvalue than would normally be supported by your machine.
Please do not set a value higher than 200 on Windows or Linux and\n50 on macOS. We monitor Goma system usage, and users found to be abusing\nit with unreasonable concurrency will be de-activated.
\nninja -C out/Testing electron -j 200\nIf you're using build-tools, appropriate -j values will automatically\nbe used for you.
If you access http://localhost:8088 on your local\nmachine you can monitor compile jobs as they flow through the goma system.
\nFor security and cost reasons, access to Electron's Goma cluster is currently restricted\nto Electron Maintainers. If you want access please head to #access-requests in\nSlack and ping @goma-squad to ask for access. Please be aware that being a\nmaintainer does not automatically grant access and access is determined on a\ncase by case basis.
We have automated monitoring of our Goma cluster and cache at https://status.notgoma.com
\nWe do not provide support for usage of Goma and any issues raised asking for help / having\nissues will probably be closed without much reason, we do not have the capacity to handle\nthat kind of support.
", "title": "Goma", "description": "Goma is a distributed compiler service for open-source projects such as\nChromium and Android." }, "/docs/api/structures/gpu-feature-status": { "locale": "en-US", "slug": "gpu-feature-status", "href": "/docs/api/structures/gpu-feature-status", "crowdinFileId": "256439", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/gpu-feature-status.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "2d_canvas String - Canvas.flash_3d String - Flash.flash_stage3d String - Flash Stage3D.flash_stage3d_baseline String - Flash Stage3D Baseline profile.gpu_compositing String - Compositing.multiple_raster_threads String - Multiple Raster Threads.native_gpu_memory_buffers String - Native GpuMemoryBuffers.rasterization String - Rasterization.video_decode String - Video Decode.video_encode String - Video Encode.vpx_decode String - VPx Video Decode.webgl String - WebGL.webgl2 String - WebGL2.Possible values:
\ndisabled_software - Software only. Hardware acceleration disabled (yellow)disabled_off - Disabled (red)disabled_off_ok - Disabled (yellow)unavailable_software - Software only, hardware acceleration unavailable (yellow)unavailable_off - Unavailable (red)unavailable_off_ok - Unavailable (yellow)enabled_readback - Hardware accelerated but at reduced performance (yellow)enabled_force - Hardware accelerated on all pages (green)enabled - Hardware accelerated (green)enabled_on - Enabled (green)enabled_force_on - Force enabled (green)deviceId String - Unique identifier for the device.name String - Name of the device.vendorId Integer - The USB vendor ID.productId Integer - The USB product ID.serialNumber String (optional) - The USB device serial number.guid String (optional) - Unique identifier for the HID interface. A device may have multiple HID interfaces.\n\nIn-app purchases on Mac App Store.
\n
Process: Main
\nThe inAppPurchase module emits the following events:
Emitted when one or more transactions have been updated.
\nReturns:
\nevent Eventtransactions Transaction[] - Array of Transaction objects.The inAppPurchase module has the following methods:
inAppPurchase.purchaseProduct(productID[, quantity])productID String - The identifiers of the product to purchase. (The identifier of com.example.app.product1 is product1).quantity Integer (optional) - The number of items the user wants to purchase.Returns Promise<Boolean> - Returns true if the product is valid and added to the payment queue.
You should listen for the transactions-updated event as soon as possible and certainly before you call purchaseProduct.
inAppPurchase.getProducts(productIDs)productIDs String[] - The identifiers of the products to get.Returns Promise<Product[]> - Resolves with an array of Product objects.
Retrieves the product descriptions.
\ninAppPurchase.canMakePayments()Returns Boolean - whether a user can make a payment.
inAppPurchase.restoreCompletedTransactions()Restores finished transactions. This method can be called either to install purchases on additional devices, or to restore purchases for an application that the user deleted and reinstalled.
\nThe payment queue delivers a new transaction for each previously completed transaction that can be restored. Each transaction includes a copy of the original transaction.
\ninAppPurchase.getReceiptURL()Returns String - the path to the receipt.
inAppPurchase.finishAllTransactions()Completes all pending transactions.
\ninAppPurchase.finishTransactionByDate(date)date String - The ISO formatted date of the transaction to finish.Completes the pending transactions corresponding to the date.
", "title": "inAppPurchase", "description": "In-app purchases on Mac App Store." }, "/docs/tutorial/in-app-purchases": { "locale": "en-US", "slug": "in-app-purchases", "href": "/docs/tutorial/in-app-purchases", "crowdinFileId": "256203", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/in-app-purchases.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "If you haven't already, you’ll need to sign the Paid Applications Agreement and set up your banking and tax information in iTunes Connect.
\niTunes Connect Developer Help: Agreements, tax, and banking overview
\nThen, you'll need to configure your in-app purchases in iTunes Connect, and include details such as name, pricing, and description that highlights the features and functionality of your in-app purchase.
\niTunes Connect Developer Help: Create an in-app purchase
\nTo test In-App Purchase in development with Electron you'll have to change the CFBundleIdentifier in node_modules/electron/dist/Electron.app/Contents/Info.plist. You have to replace com.github.electron by the bundle identifier of the application you created with iTunes Connect.
<key>CFBundleIdentifier</key>\n<string>com.example.app</string>\nHere is an example that shows how to use In-App Purchases in Electron. You'll have to replace the product ids by the identifiers of the products created with iTunes Connect (the identifier of com.example.app.product1 is product1). Note that you have to listen to the transactions-updated event as soon as possible in your app.
// Main process\nconst { inAppPurchase } = require('electron')\nconst PRODUCT_IDS = ['id1', 'id2']\n\n// Listen for transactions as soon as possible.\ninAppPurchase.on('transactions-updated', (event, transactions) => {\n if (!Array.isArray(transactions)) {\n return\n }\n\n // Check each transaction.\n transactions.forEach(function (transaction) {\n const payment = transaction.payment\n\n switch (transaction.transactionState) {\n case 'purchasing':\n console.log(`Purchasing ${payment.productIdentifier}...`)\n break\n\n case 'purchased': {\n console.log(`${payment.productIdentifier} purchased.`)\n\n // Get the receipt url.\n const receiptURL = inAppPurchase.getReceiptURL()\n\n console.log(`Receipt URL: ${receiptURL}`)\n\n // Submit the receipt file to the server and check if it is valid.\n // @see https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html\n // ...\n // If the receipt is valid, the product is purchased\n // ...\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n }\n\n case 'failed':\n\n console.log(`Failed to purchase ${payment.productIdentifier}.`)\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n case 'restored':\n\n console.log(`The purchase of ${payment.productIdentifier} has been restored.`)\n\n break\n case 'deferred':\n\n console.log(`The purchase of ${payment.productIdentifier} has been deferred.`)\n\n break\n default:\n break\n }\n })\n})\n\n// Check if the user is allowed to make in-app purchase.\nif (!inAppPurchase.canMakePayments()) {\n console.log('The user is not allowed to make in-app purchase.')\n}\n\n// Retrieve and display the product descriptions.\ninAppPurchase.getProducts(PRODUCT_IDS).then(products => {\n // Check the parameters.\n if (!Array.isArray(products) || products.length <= 0) {\n console.log('Unable to retrieve the product informations.')\n return\n }\n\n // Display the name and price of each product.\n products.forEach(product => {\n console.log(`The price of ${product.localizedTitle} is ${product.formattedPrice}.`)\n })\n\n // Ask the user which product he/she wants to purchase.\n const selectedProduct = products[0]\n const selectedQuantity = 1\n\n // Purchase the selected product.\n inAppPurchase.purchaseProduct(selectedProduct.productIdentifier, selectedQuantity).then(isProductValid => {\n if (!isProductValid) {\n console.log('The product is not valid.')\n return\n }\n\n console.log('The payment has been added to the payment queue.')\n })\n})\n\n\nHandle responses to HTTP/HTTPS requests.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
IncomingMessage implements the Readable Stream\ninterface and is therefore an EventEmitter.
Returns:
\nchunk Buffer - A chunk of response body's data.The data event is the usual method of transferring response data into\napplicative code.
Indicates that response body has ended. Must be placed before 'data' event.
\nEmitted when a request has been canceled during an ongoing HTTP transaction.
\nReturns:
\nerror Error - Typically holds an error string identifying failure root cause.
Emitted when an error was encountered while streaming response data events. For\ninstance, if the server closes the underlying while the response is still\nstreaming, an error event will be emitted on the response object and a close\nevent will subsequently follow on the request object.
An IncomingMessage instance has the following readable properties:
response.statusCodeAn Integer indicating the HTTP response status code.
response.statusMessageA String representing the HTTP status message.
response.headersA Record<string, string | string[]> representing the HTTP response headers. The headers object is\nformatted as follows:
age, authorization, content-length, content-type,\netag, expires, from, host, if-modified-since, if-unmodified-since,\nlast-modified, location, max-forwards, proxy-authorization, referer,\nretry-after, server, or user-agent are discarded.set-cookie is always an array. Duplicates are added to the array.cookie headers, the values are joined together with '; '.response.httpVersionA String indicating the HTTP protocol version number. Typical values are '1.0'\nor '1.1'. Additionally httpVersionMajor and httpVersionMinor are two\nInteger-valued readable properties that return respectively the HTTP major and\nminor version numbers.
response.httpVersionMajorAn Integer indicating the HTTP protocol major version number.
response.httpVersionMinorAn Integer indicating the HTTP protocol minor version number.
modifiers String - An array of modifiers of the event, can\nbe shift, control, ctrl, alt, meta, command, cmd, isKeypad,\nisAutoRepeat, leftButtonDown, middleButtonDown, rightButtonDown,\ncapsLock, numLock, left, right.To install prebuilt Electron binaries, use npm.\nThe preferred method is to install Electron as a development dependency in your\napp:
npm install electron --save-dev\nSee the Electron versioning doc for info on how to\nmanage Electron versions in your apps.
\nIf you're in a pinch and would prefer to not use npm install in your local\nproject, you can also run Electron ad-hoc using the npx command runner\nbundled with npm:
npx electron .\nThe above command will run the current working directory with Electron. Note that\nany dependencies in your app will not be installed.
\nIf you want to change the architecture that is downloaded (e.g., ia32 on an\nx64 machine), you can use the --arch flag with npm install or set the\nnpm_config_arch environment variable:
npm install --arch=ia32 electron\nIn addition to changing the architecture, you can also specify the platform\n(e.g., win32, linux, etc.) using the --platform flag:
npm install --platform=win32 electron\nIf you need to use an HTTP proxy, you need to set the ELECTRON_GET_USE_PROXY variable to any\nvalue, plus additional environment variables depending on your host system's Node version:
During installation, the electron module will call out to\n@electron/get to download prebuilt binaries of\nElectron for your platform. It will do so by contacting GitHub's\nrelease download page (https://github.com/electron/electron/releases/tag/v$VERSION,\nwhere $VERSION is the exact version of Electron).
If you are unable to access GitHub or you need to provide a custom build, you\ncan do so by either providing a mirror or an existing cache directory.
\nYou can use environment variables to override the base URL, the path at which to\nlook for Electron binaries, and the binary filename. The URL used by @electron/get\nis composed as follows:
url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME\nFor instance, to use the China CDN mirror:
\nELECTRON_MIRROR=\"https://cdn.npm.taobao.org/dist/electron/\"\nBy default, ELECTRON_CUSTOM_DIR is set to v$VERSION. To change the format,\nuse the {{ version }} placeholder. For example, version-{{ version }}\nresolves to version-5.0.0, {{ version }} resolves to 5.0.0, and\nv{{ version }} is equivalent to the default. As a more concrete example, to\nuse the China non-CDN mirror:
ELECTRON_MIRROR=\"https://npm.taobao.org/mirrors/electron/\"\nELECTRON_CUSTOM_DIR=\"{{ version }}\"\nThe above configuration will download from URLs such as\nhttps://npm.taobao.org/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip.
If your mirror serves artifacts with different checksums to the official\nElectron release you may have to set ELECTRON_USE_REMOTE_CHECKSUMS=1 to\nforce Electron to use the remote SHASUMS256.txt file to verify the checksum\ninstead of the embedded checksums.
Alternatively, you can override the local cache. @electron/get will cache\ndownloaded binaries in a local directory to not stress your network. You can use\nthat cache folder to provide custom builds of Electron or to avoid making contact\nwith the network at all.
$XDG_CACHE_HOME or ~/.cache/electron/~/Library/Caches/electron/$LOCALAPPDATA/electron/Cache or ~/AppData/Local/electron/Cache/On environments that have been using older versions of Electron, you might find the\ncache also in ~/.electron.
You can also override the local cache location by providing a electron_config_cache\nenvironment variable.
The cache contains the version's official zip file as well as a checksum, stored as\na text file. A typical cache might look like this:
\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9electron-v1.7.9-darwin-x64.zip\n│ └── electron-v1.7.9-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1electron-v1.8.1-darwin-x64.zip\n│ └── electron-v1.8.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1electron-v1.8.2-beta.1-darwin-x64.zip\n│ └── electron-v1.8.2-beta.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2electron-v1.8.2-beta.2-darwin-x64.zip\n│ └── electron-v1.8.2-beta.2-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3electron-v1.8.2-beta.3-darwin-x64.zip\n│ └── electron-v1.8.2-beta.3-darwin-x64.zip\n└── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3SHASUMS256.txt\n └── SHASUMS256.txt\nUnder the hood, Electron's JavaScript API binds to a binary that contains its\nimplementations. Because this binary is crucial to the function of any Electron app,\nit is downloaded by default in the postinstall step every time you install electron\nfrom the npm registry.
However, if you want to install your project's dependencies but don't need to use\nElectron functionality, you can set the ELECTRON_SKIP_BINARY_DOWNLOAD environment\nvariable to prevent the binary from being downloaded. For instance, this feature can\nbe useful in continuous integration environments when running unit tests that mock\nout the electron module.
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install\nWhen running npm install electron, some users occasionally encounter\ninstallation errors.
In almost all cases, these errors are the result of network problems and not\nactual issues with the electron npm package. Errors like ELIFECYCLE,\nEAI_AGAIN, ECONNRESET, and ETIMEDOUT are all indications of such\nnetwork problems. The best resolution is to try switching networks, or\nwait a bit and try installing again.
You can also attempt to download Electron directly from\nelectron/electron/releases\nif installing via npm is failing.
If installation fails with an EACCESS error you may need to\nfix your npm permissions.
If the above error persists, the unsafe-perm flag may need to be\nset to true:
\nsudo npm install electron --unsafe-perm=true\nOn slower networks, it may be advisable to use the --verbose flag in order to\nshow download progress:
npm install --verbose electron\nIf you need to force a re-download of the asset and the SHASUM file set the\nforce_no_cache environment variable to true.
Welcome to the Electron documentation! If this is your first time developing\nan Electron app, read through this Getting Started section to get familiar with the\nbasics. Otherwise, feel free to explore our guides and API documentation!
\nElectron is a framework for building desktop applications using JavaScript,\nHTML, and CSS. By embedding Chromium and Node.js into its\nbinary, Electron allows you to maintain one JavaScript codebase and create\ncross-platform apps that work on Windows, macOS, and Linux — no native development\nexperience required.
\nThese docs operate under the assumption that the reader is familiar with both\nNode.js and general web development. If you need to get more comfortable with\neither of these areas, we recommend the following resources:
\n\nMoreover, you'll have a better time understanding how Electron works if you get\nacquainted with Chromium's process model. You can get a brief overview of\nChrome architecture with the Chrome comic, which was released alongside\nChrome's launch back in 2008. Although it's been over a decade since then, the\ncore principles introduced in the comic remain helpful to understand Electron.
\nElectron Fiddle is a sandbox app written with Electron and supported by\nElectron's maintainers. We highly recommend installing it as a learning tool to\nexperiment with Electron's APIs or to prototype features during development.
\nFiddle also integrates nicely with our documentation. When browsing through examples\nin our tutorials, you'll frequently see an \"Open in Electron Fiddle\" button underneath\na code block. If you have Fiddle installed, this button will open a\nfiddle.electronjs.org link that will automatically load the example into Fiddle,\nno copy-pasting required.
Are you getting stuck anywhere? Here are a few links to places to look:
\nelectron package, please check\nthe GitHub issue tracker to see if any existing issues match your\nproblem. If not, feel free to fill out our bug report template and submit a new issue.readOperationCount Number - The number of I/O read operations.writeOperationCount Number - The number of I/O write operations.otherOperationCount Number - Then number of I/O other operations.readTransferCount Number - The number of I/O read transfers.writeTransferCount Number - The number of I/O write transfers.otherTransferCount Number - Then number of I/O other transfers.\n\nCommunicate asynchronously from the main process to renderer processes.
\n
Process: Main
\nThe ipcMain module is an Event Emitter. When used in the main\nprocess, it handles asynchronous and synchronous messages sent from a renderer\nprocess (web page). Messages sent from a renderer will be emitted to this\nmodule.
It is also possible to send messages from the main process to the renderer\nprocess, see webContents.send for more information.
\nchannel.event.returnValue.event.reply(...). This helper method will automatically handle messages\ncoming from frames that aren't the main frame (e.g. iframes) whereas\nevent.sender.send(...) will always send to the main frame.An example of sending and handling messages between the render and main\nprocesses:
\n// In main process.\nconst { ipcMain } = require('electron')\nipcMain.on('asynchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.reply('asynchronous-reply', 'pong')\n})\n\nipcMain.on('synchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.returnValue = 'pong'\n})\n// In renderer process (web page).\n// NB. Electron APIs are only accessible from preload, unless contextIsolation is disabled.\n// See https://www.electronjs.org/docs/tutorial/process-model#preload-scripts for more details.\nconst { ipcRenderer } = require('electron')\nconsole.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // prints \"pong\"\n\nipcRenderer.on('asynchronous-reply', (event, arg) => {\n console.log(arg) // prints \"pong\"\n})\nipcRenderer.send('asynchronous-message', 'ping')\nThe ipcMain module has the following method to listen for events:
ipcMain.on(channel, listener)channel Stringlistener Functionevent IpcMainEvent...args any[]Listens to channel, when a new message arrives listener would be called with\nlistener(event, args...).
ipcMain.once(channel, listener)channel Stringlistener Functionevent IpcMainEvent...args any[]Adds a one time listener function for the event. This listener is invoked\nonly the next time a message is sent to channel, after which it is removed.
ipcMain.removeListener(channel, listener)channel Stringlistener Function...args any[]Removes the specified listener from the listener array for the specified\nchannel.
ipcMain.removeAllListeners([channel])channel String (optional)Removes listeners of the specified channel.
ipcMain.handle(channel, listener)channel Stringlistener Function<Promise\\event IpcMainInvokeEvent...args any[]Adds a handler for an invokeable IPC. This handler will be called whenever a\nrenderer calls ipcRenderer.invoke(channel, ...args).
If listener returns a Promise, the eventual result of the promise will be\nreturned as a reply to the remote caller. Otherwise, the return value of the\nlistener will be used as the value of the reply.
// Main process\nipcMain.handle('my-invokable-ipc', async (event, ...args) => {\n const result = await somePromise(...args)\n return result\n})\n\n// Renderer process\nasync () => {\n const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)\n // ...\n}\nThe event that is passed as the first argument to the handler is the same as\nthat passed to a regular event listener. It includes information about which\nWebContents is the source of the invoke request.
Errors thrown through handle in the main process are not transparent as they\nare serialized and only the message property from the original error is\nprovided to the renderer process. Please refer to\n#24427 for details.
ipcMain.handleOnce(channel, listener)channel Stringlistener Function<Promise\\event IpcMainInvokeEvent...args any[]Handles a single invokeable IPC message, then removes the listener. See\nipcMain.handle(channel, listener).
ipcMain.removeHandler(channel)channel StringRemoves any handler for channel, if present.
The documentation for the event object passed to the callback can be found\nin the ipc-main-event structure docs.
The documentation for the event object passed to handle callbacks can be\nfound in the ipc-main-invoke-event\nstructure docs.
EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagereturnValue any - Set this to the value to be returned in a synchronous messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this messageports MessagePortMain[] - A list of MessagePorts that were transferred with this messagereply Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to \"reply\" to the sent message in order to guarantee the reply will go to the correct process and frame.channel String...args any[]EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this message\n\nCommunicate asynchronously from a renderer process to the main process.
\n
Process: Renderer
\nThe ipcRenderer module is an EventEmitter. It provides a few\nmethods so you can send synchronous and asynchronous messages from the render\nprocess (web page) to the main process. You can also receive replies from the\nmain process.
See ipcMain for code examples.
\nThe ipcRenderer module has the following method to listen for events and send messages:
ipcRenderer.on(channel, listener)channel Stringlistener Functionevent IpcRendererEvent...args any[]Listens to channel, when a new message arrives listener would be called with\nlistener(event, args...).
ipcRenderer.once(channel, listener)channel Stringlistener Functionevent IpcRendererEvent...args any[]Adds a one time listener function for the event. This listener is invoked\nonly the next time a message is sent to channel, after which it is removed.
ipcRenderer.removeListener(channel, listener)channel Stringlistener Function...args any[]Removes the specified listener from the listener array for the specified\nchannel.
ipcRenderer.removeAllListeners(channel)channel StringRemoves all listeners, or those of the specified channel.
ipcRenderer.send(channel, ...args)channel String...args any[]Send an asynchronous message to the main process via channel, along with\narguments. Arguments will be serialized with the Structured Clone\nAlgorithm, just like window.postMessage, so prototype chains will not be\nincluded. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will\nthrow an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or\nspecial Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as\n
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over\nElectron's IPC to the main process, as the main process would have no way to decode\nthem. Attempting to send such objects over IPC will result in an error.
The main process handles it by listening for channel with the\nipcMain module.
If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you want to receive a single response from the main process, like the result of a method call, consider using ipcRenderer.invoke.
ipcRenderer.invoke(channel, ...args)channel String...args any[]Returns Promise<any> - Resolves with the response from the main process.
Send a message to the main process via channel and expect a result\nasynchronously. Arguments will be serialized with the Structured Clone\nAlgorithm, just like window.postMessage, so prototype chains will not be\nincluded. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will\nthrow an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or\nspecial Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as\n
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over\nElectron's IPC to the main process, as the main process would have no way to decode\nthem. Attempting to send such objects over IPC will result in an error.
The main process should listen for channel with\nipcMain.handle().
For example:
\n// Renderer process\nipcRenderer.invoke('some-name', someArgument).then((result) => {\n // ...\n})\n\n// Main process\nipcMain.handle('some-name', async (event, someArgument) => {\n const result = await doSomeWork(someArgument)\n return result\n})\nIf you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you do not need a response to the message, consider using ipcRenderer.send.
ipcRenderer.sendSync(channel, ...args)channel String...args any[]Returns any - The value sent back by the ipcMain handler.
Send a message to the main process via channel and expect a result\nsynchronously. Arguments will be serialized with the Structured Clone\nAlgorithm, just like window.postMessage, so prototype chains will not be\nincluded. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will\nthrow an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or\nspecial Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as\n
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over\nElectron's IPC to the main process, as the main process would have no way to decode\nthem. Attempting to send such objects over IPC will result in an error.
The main process handles it by listening for channel with ipcMain module,\nand replies by setting event.returnValue.
\n\n⚠️ WARNING: Sending a synchronous message will block the whole\nrenderer process until the reply is received, so use this method only as a\nlast resort. It's much better to use the asynchronous version,\n
\ninvoke().
ipcRenderer.postMessage(channel, message, [transfer])Send a message to the main process, optionally transferring ownership of zero\nor more MessagePort objects.
The transferred MessagePort objects will be available in the main process as\nMessagePortMain objects by accessing the ports\nproperty of the emitted event.
For example:
\n// Renderer process\nconst { port1, port2 } = new MessageChannel()\nipcRenderer.postMessage('port', { message: 'hello' }, [port1])\n\n// Main process\nipcMain.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nFor more information on using MessagePort and MessageChannel, see the MDN\ndocumentation.
ipcRenderer.sendTo(webContentsId, channel, ...args)webContentsId Numberchannel String...args any[]Sends a message to a window with webContentsId via channel.
ipcRenderer.sendToHost(channel, ...args)channel String...args any[]Like ipcRenderer.send but the event will be sent to the <webview> element in\nthe host page instead of the main process.
The documentation for the event object passed to the callback can be found\nin the ipc-renderer-event structure docs.
Eventsender IpcRenderer - The IpcRenderer instance that emitted the event originallysenderId Integer - The webContents.id that sent the message, you can call event.sender.sendTo(event.senderId, ...) to reply to the message, see ipcRenderer.sendTo for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set event.senderId to 0.ports MessagePort[] - A list of MessagePorts that were transferred with this messageFor any issue, there are fundamentally three ways an individual can\ncontribute:
\nelectron/electron issue tracker.electron/electron in a\nconcrete and reviewable manner.\"Finding Support\" has a\nlist of resources for getting programming help, reporting security issues,\ncontributing, and more. Please use the issue tracker for bugs only!
\nTo submit a bug report:
\nWhen opening a new issue in the electron/electron issue tracker, users\nwill be presented with a template that should be filled in.
If you believe that you have found a bug in Electron, please fill out the template\nto the best of your ability.
\nThe two most important pieces of information needed to evaluate the report are\na description of the bug and a simple test case to recreate it. It is easier to fix\na bug if it can be reproduced.
\nSee How to create a Minimal, Complete, and Verifiable example.
\nIt's common for open issues to involve discussion. Some contributors may\nhave differing opinions, including whether the behavior is a bug or feature.\nThis discussion is part of the process and should be kept focused, helpful,\nand professional.
\nTerse responses that provide neither additional context nor supporting detail\nare not helpful or professional. To many, such responses are annoying and\nunfriendly.
\nContributors are encouraged to solve issues collaboratively and help one\nanother make progress. If you encounter an issue that you feel is invalid, or\nwhich contains incorrect information, explain why you feel that way with\nadditional supporting context, and be willing to be convinced that you may\nbe wrong. By doing so, we can often reach the correct outcome faster.
\nMost issues are resolved by opening a pull request. The process for opening and\nreviewing a pull request is similar to that of opening and triaging issues, but\ncarries with it a necessary review and approval workflow that ensures that the\nproposed changes meet the minimal quality and functional guidelines of the\nElectron project.
", "title": "Issues In Electron", "description": "" }, "/docs/api/structures/jump-list-category": { "locale": "en-US", "slug": "jump-list-category", "href": "/docs/api/structures/jump-list-category", "crowdinFileId": "256451", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/jump-list-category.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "type String (optional) - One of the following:tasks - Items in this category will be placed into the standard Tasks\ncategory. There can be only one such category, and it will always be\ndisplayed at the bottom of the Jump List.frequent - Displays a list of files frequently opened by the app, the\nname of the category and its items are set by Windows.recent - Displays a list of files recently opened by the app, the name\nof the category and its items are set by Windows. Items may be added to\nthis category indirectly using app.addRecentDocument(path).custom - Displays tasks or file links, name must be set by the app.name String (optional) - Must be set if type is custom, otherwise it should be\nomitted.items JumpListItem - Array of JumpListItem objects if type is tasks or\ncustom, otherwise it should be omitted.Note: If a JumpListCategory object has neither the type nor the name\nproperty set then its type is assumed to be tasks. If the name property\nis set but the type property is omitted then the type is assumed to be\ncustom.
Note: The maximum length of a Jump List item's description property is\n260 characters. Beyond this limit, the item will not be added to the Jump\nList, nor will it be displayed.
type String (optional) - One of the following:task - A task will launch an app with specific arguments.separator - Can be used to separate items in the standard Tasks\ncategory.file - A file link will open a file using the app that created the\nJump List, for this to work the app must be registered as a handler for\nthe file type (though it doesn't have to be the default handler).path String (optional) - Path of the file to open, should only be set if type is\nfile.program String (optional) - Path of the program to execute, usually you should\nspecify process.execPath which opens the current program. Should only be\nset if type is task.args String (optional) - The command line arguments when program is executed. Should\nonly be set if type is task.title String (optional) - The text to be displayed for the item in the Jump List.\nShould only be set if type is task.description String (optional) - Description of the task (displayed in a tooltip).\nShould only be set if type is task. Maximum length 260 characters.iconPath String (optional) - The absolute path to an icon to be displayed in a\nJump List, which can be an arbitrary resource file that contains an icon\n(e.g. .ico, .exe, .dll). You can usually specify process.execPath to\nshow the program icon.iconIndex Number (optional) - The index of the icon in the resource file. If a\nresource file contains multiple icons this value can be used to specify the\nzero-based index of the icon that should be displayed for this task. If a\nresource file contains only one icon, this property should be set to zero.workingDirectory String (optional) - The working directory. Default is empty.ctrlKey Boolean (optional) - whether the Control key was used in an accelerator to trigger the EventmetaKey Boolean (optional) - whether a meta key was used in an accelerator to trigger the EventshiftKey Boolean (optional) - whether a Shift key was used in an accelerator to trigger the EventaltKey Boolean (optional) - whether an Alt key was used in an accelerator to trigger the EventtriggeredByAccelerator Boolean (optional) - whether an accelerator was used to trigger the event as opposed to another user gesture like mouse clickInputEventtype String - The type of the event, can be keyDown, keyUp or char.keyCode String - The character that will be sent\nas the keyboard event. Should only use the valid key codes in\nAccelerator.This feature allows you to configure local and global keyboard shortcuts\nfor your Electron application.
\nLocal keyboard shortcuts are triggered only when the application is focused.\nTo configure a local keyboard shortcut, you need to specify an accelerator\nproperty when creating a MenuItem within the Menu module.
Starting with a working application from the\nQuick Start Guide, update the main.js file with the\nfollowing lines:
const { Menu, MenuItem } = require('electron')\n\nconst menu = new Menu()\nmenu.append(new MenuItem({\n label: 'Electron',\n submenu: [{\n role: 'help',\n accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Alt+Shift+I',\n click: () => { console.log('Electron rocks!') }\n }]\n}))\n\nMenu.setApplicationMenu(menu)\n\n\nNOTE: In the code above, you can see that the accelerator differs based on the\nuser's operating system. For MacOS, it is
\nAlt+Cmd+I, whereas for Linux and\nWindows, it isAlt+Shift+I.
After launching the Electron application, you should see the application menu\nalong with the local shortcut you just defined:
\n![\"Menu](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/local-shortcut.png\")
If you click Help or press the defined accelerator and then open the terminal\nthat you ran your Electron application from, you will see the message that was\ngenerated after triggering the click event: \"Electron rocks!\".
To configure a global keyboard shortcut, you need to use the globalShortcut\nmodule to detect keyboard events even when the application does not have\nkeyboard focus.
\nStarting with a working application from the\nQuick Start Guide, update the main.js file with the\nfollowing lines:
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n globalShortcut.register('Alt+CommandOrControl+I', () => {\n console.log('Electron loves global shortcuts!')\n })\n}).then(createWindow)\n\n\nNOTE: In the code above, the
\nCommandOrControlcombination usesCommand\non macOS andControlon Windows/Linux.
After launching the Electron application, if you press the defined key\ncombination then open the terminal that you ran your Electron application from,\nyou will see that Electron loves global shortcuts!
\nIf you want to handle keyboard shortcuts within a BrowserWindow, you can\nlisten for the keyup and keydown DOM events inside the\nrenderer process using the addEventListener() API.
function handleKeyPress(event) {\n // You can put code here to handle the keypress.\n document.getElementById(\"last-keypress\").innerText = event.key;\n console.log(`You pressed ${event.key}`);\n}\n\nwindow.addEventListener('keyup', handleKeyPress, true);\n\n\nNote: the third parameter
\ntrueindicates that the listener will always receive\nkey presses before other listeners so they can't havestopPropagation()\ncalled on them.
The before-input-event event\nis emitted before dispatching keydown and keyup events in the page. It can\nbe used to catch and handle custom shortcuts that are not visible in the menu.
Starting with a working application from the\nQuick Start Guide, update the main.js file with the\nfollowing lines:
const { app, BrowserWindow } = require('electron')\n\napp.whenReady().then(() => {\n const win = new BrowserWindow({ width: 800, height: 600 })\n\n win.loadFile('index.html')\n win.webContents.on('before-input-event', (event, input) => {\n if (input.control && input.key.toLowerCase() === 'i') {\n console.log('Pressed Control+I')\n event.preventDefault()\n }\n })\n})\nAfter launching the Electron application, if you open the terminal that you ran\nyour Electron application from and press Ctrl+I key combination, you will\nsee that this key combination was successfully intercepted.
If you don't want to do manual shortcut parsing, there are libraries that do\nadvanced key detection, such as mousetrap. Below are examples of usage of the\nmousetrap running in the Renderer process:
Mousetrap.bind('4', () => { console.log('4') })\nMousetrap.bind('?', () => { console.log('show shortcuts!') })\nMousetrap.bind('esc', () => { console.log('escape') }, 'keyup')\n\n// combinations\nMousetrap.bind('command+shift+k', () => { console.log('command shift k') })\n\n// map multiple combinations to the same callback\nMousetrap.bind(['command+k', 'ctrl+k'], () => {\n console.log('command k or control k')\n\n // return false to prevent default behavior and stop event from bubbling\n return false\n})\n\n// gmail style sequences\nMousetrap.bind('g i', () => { console.log('go to inbox') })\nMousetrap.bind('* a', () => { console.log('select all') })\n\n// konami code!\nMousetrap.bind('up up down down left right left right b a enter', () => {\n console.log('konami code')\n})\ntitle: Launching Your Electron App From a URL In Another App\ndescription: This guide will take you through the process of setting your electron app as the default handler for a specific protocol.\nslug: launch-app-from-url-in-another-app
\nThis guide will take you through the process of setting your Electron app as the default\nhandler for a specific protocol.
\nBy the end of this tutorial, we will have set our app to intercept and handle\nany clicked URLs that start with a specific protocol. In this guide, the protocol\nwe will use will be \"electron-fiddle://\".
First, we will import the required modules from electron. These modules help\ncontrol our application lifecycle and create a native browser window.
const { app, BrowserWindow, shell } = require('electron')\nconst path = require('path')\nNext, we will proceed to register our application to handle all \"electron-fiddle://\" protocols.
if (process.defaultApp) {\n if (process.argv.length >= 2) {\n app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])\n }\n} else {\n app.setAsDefaultProtocolClient('electron-fiddle')\n}\nWe will now define the function in charge of creating our browser window and load our application's index.html file.
const createWindow = () => {\n // Create the browser window.\n mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n mainWindow.loadFile('index.html')\n}\nIn this next step, we will create our BrowserWindow and tell our application how to handle an event in which an external protocol is clicked.
This code will be different in Windows compared to MacOS and Linux. This is due to Windows requiring additional code in order to open the contents of the protocol link within the same Electron instance. Read more about this here.
\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Someone tried to run a second instance, we should focus our window.\n if (mainWindow) {\n if (mainWindow.isMinimized()) mainWindow.restore()\n mainWindow.focus()\n }\n })\n\n // Create mainWindow, load the rest of the app, etc...\n app.whenReady().then(() => {\n createWindow()\n })\n\n // Handle the protocol. In this case, we choose to show an Error Box.\n app.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n })\n}\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// Some APIs can only be used after this event occurs.\napp.whenReady().then(() => {\n createWindow()\n})\n\n// Handle the protocol. In this case, we choose to show an Error Box.\napp.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n})\nFinally, we will add some additional code to handle when someone closes our application.
\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') app.quit()\n})\nOn macOS and Linux, this feature will only work when your app is packaged. It will not work when\nyou're launching it in development from the command-line. When you package your app you'll need to\nmake sure the macOS Info.plist and the Linux .desktop files for the app are updated to include\nthe new protocol handler. Some of the Electron tools for bundling and distributing apps handle\nthis for you.
If you're using Electron Forge, adjust packagerConfig for macOS support, and the configuration for\nthe appropriate Linux makers for Linux support, in your Forge\nconfiguration (please note the following example only\nshows the bare minimum needed to add the configuration changes):
{\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"protocols\": [\n {\n \"name\": \"Electron Fiddle\",\n \"schemes\": [\"electron-fiddle\"]\n }\n ]\n },\n \"makers\": [\n {\n \"name\": \"@electron-forge/maker-deb\",\n \"config\": {\n \"mimeType\": [\"x-scheme-handler/electron-fiddle\"]\n }\n }\n ]\n }\n }\n}\nFor macOS support:
\nIf you're using Electron Packager's API, adding support for protocol handlers is similar to how\nElectron Forge is handled, except\nprotocols is part of the Packager options passed to the packager function.
const packager = require('electron-packager')\n\npackager({\n // ...other options...\n protocols: [\n {\n name: 'Electron Fiddle',\n schemes: ['electron-fiddle']\n }\n ]\n\n}).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))\n .catch(err => console.error(`ERROR: ${err.message}`))\nIf you're using Electron Packager's CLI, use the --protocol and --protocol-name flags. For\nexample:
npx electron-packager . --protocol=electron-fiddle --protocol-name=\"Electron Fiddle\"\nAfter you start your Electron app, you can enter in a URL in your browser that contains the custom\nprotocol, for example \"electron-fiddle://open\" and observe that the application will respond and\nshow an error dialog box.
On many Linux environments, you can add custom entries to the system launcher\nby modifying the .desktop file. For Canonical's Unity documentation, see\nAdding Shortcuts to a Launcher. For details on a more generic\nimplementation, see the freedesktop.org Specification.
![\"audacious\"](\"https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles?action=AttachFile&do=get&target=shortcuts.png\")
\n\nNOTE: The screenshot above is an example of launcher shortcuts in Audacious\naudio player
\n
To create a shortcut, you need to provide Name and Exec properties for the\nentry you want to add to the shortcut menu. Unity will execute the command\ndefined in the Exec field after the user clicked the shortcut menu item.\nAn example of the .desktop file may look as follows:
Actions=PlayPause;Next;Previous\n\n[Desktop Action PlayPause]\nName=Play-Pause\nExec=audacious -t\nOnlyShowIn=Unity;\n\n[Desktop Action Next]\nName=Next\nExec=audacious -f\nOnlyShowIn=Unity;\n\n[Desktop Action Previous]\nName=Previous\nExec=audacious -r\nOnlyShowIn=Unity;\nThe preferred way for Unity to instruct your application on what to do is using\nparameters. You can find them in your application in the global variable\nprocess.argv.
This guide provides information on:
\nTo sign Electron apps, the following tools must be installed first:
\nYou also have to register an Apple Developer account and join the\nApple Developer Program.
\nElectron apps can be distributed through Mac App Store or outside it. Each way\nrequires different ways of signing and testing. This guide focuses on\ndistribution via Mac App Store, but will also mention other methods.
\nThe following steps describe how to get the certificates from Apple, how to sign\nElectron apps, and how to test them.
\nThe simplest way to get signing certificates is to use Xcode:
\nThe \"Apple Development\" certificate is used to sign apps for development and\ntesting, on machines that have been registered on Apple Developer website. The\nmethod of registration will be described in\nPrepare provisioning profile.
\nApps signed with the \"Apple Development\" certificate cannot be submitted to Mac\nApp Store. For that purpose, apps must be signed with the \"Apple Distribution\"\ncertificate instead. But note that apps signed with the \"Apple Distribution\"\ncertificate cannot run directly, they must be re-signed by Apple to be able to\nrun, which will only be possible after being downloaded from the Mac App Store.
\nYou may notice that there are also other kinds of certificates.
\nThe \"Developer ID Application\" certificate is used to sign apps before\ndistributing them outside the Mac App Store.
\nThe \"Developer ID Installer\" and \"Mac Installer Distribution\" certificates are\nused to sign the Mac Installer Package instead of the app itself. Most Electron\napps do not use Mac Installer Package so they are generally not needed.
\nThe full list of certificate types can be found\nhere.
\nApps signed with \"Apple Development\" and \"Apple Distribution\" certificates can\nonly run under App Sandbox, so they must use the MAS build of\nElectron. However, the \"Developer ID Application\" certificate does not have this\nrestrictions, so apps signed with it can use either the normal build or the MAS\nbuild of Electron.
\nApple has been changing the names of certificates during past years, you might\nencounter them when reading old documentations, and some utilities are still\nusing one of the old names.
\nIf you want to test your app on your local machine before submitting your app to\nthe Mac App Store, you have to sign the app with the \"Apple Development\"\ncertificate with the provisioning profile embedded in the app bundle.
\nTo create a provisioning profile,\nyou can follow the below steps:
\n/path/to/yourapp.provisionprofile.Apps submitted to the Mac App Store must run under Apple's\nApp Sandbox, and only the MAS build of Electron can run with\nthe App Sandbox. The standard darwin build of Electron will fail to launch\nwhen run under App Sandbox.
\nWhen signing the app with electron-osx-sign, it will automatically add the\nnecessary entitlements to your app's entitlements, but if you are using custom\nentitlements, you must ensure App Sandbox capacity is added:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n </dict>\n</plist>\nelectron-osx-signIf you are signing your app without using electron-osx-sign, you must ensure\nthe app bundle's entitlements have at least following keys:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.application-groups</key>\n <array>\n <string>TEAM_ID.your.bundle.id</string>\n </array>\n </dict>\n</plist>\nThe TEAM_ID should be replaced with your Apple Developer account's Team ID,\nand the your.bundle.id should be replaced with the App ID of the app.
And the following entitlements must be added to the binaries and helpers in\nthe app's bundle:
\n\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.inherit</key>\n <true/>\n </dict>\n</plist>\nAnd the app bundle's Info.plist must include ElectronTeamID key, which has\nyour Apple Developer account's Team ID as its value:
<plist version=\"1.0\">\n<dict>\n ...\n <key>ElectronTeamID</key>\n <string>TEAM_ID</string>\n</dict>\n</plist>\nWhen using electron-osx-sign the ElectronTeamID key will be added\nautomatically by extracting the Team ID from the certificate's name. You may\nneed to manually add this key if electron-osx-sign could not find the correct\nTeam ID.
To sign an app that can run on your development machine, you must sign it with\nthe \"Apple Development\" certificate and pass the provisioning profile to\nelectron-osx-sign.
electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile\nIf you are signing without electron-osx-sign, you must place the provisioning\nprofile to YourApp.app/Contents/embedded.provisionprofile.
The signed app can only run on the machines that registered by the provisioning\nprofile, and this is the only way to test the signed app before submitting to\nMac App Store.
\nTo sign an app that will be submitted to Mac App Store, you must sign it with\nthe \"Apple Distribution\" certificate. Note that apps signed with this\ncertificate will not run anywhere, unless it is downloaded from Mac App Store.
\nelectron-osx-sign YourApp.app --identity='Apple Distribution'\nIf you don't plan to submit the app to Mac App Store, you can sign it the\n\"Developer ID Application\" certificate. In this way there is no requirement on\nApp Sandbox, and you should use the normal darwin build of Electron if you don't\nuse App Sandbox.
\nelectron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess\nBy passing --no-gatekeeper-assess, the electron-osx-sign will skip the macOS\nGateKeeper check as your app usually has not been notarized yet by this step.
This guide does not cover App Notarization, but you might\nwant to do it otherwise Apple may prevent users from using your app outside Mac\nApp Store.
\nAfter signing the app with the \"Apple Distribution\" certificate, you can\ncontinue to submit it to Mac App Store.
\nHowever, this guide do not ensure your app will be approved by Apple; you\nstill need to read Apple's Submitting Your App guide on\nhow to meet the Mac App Store requirements.
\nThe Application Loader should be used to upload the signed app to iTunes\nConnect for processing, making sure you have created a record\nbefore uploading.
\nIf you are seeing errors like private APIs uses, you should check if the app is\nusing the MAS build of Electron.
\nAfter uploading, you should submit your app for review.
\nIn order to satisfy all requirements for app sandboxing, the following modules\nhave been disabled in the MAS build:
\ncrashReporterautoUpdaterand the following behaviors have been changed:
\nAlso, due to the usage of app sandboxing, the resources which can be accessed by\nthe app are strictly limited; you can read App Sandboxing for\nmore information.
\nDepending on which Electron APIs your app uses, you may need to add additional\nentitlements to your app's entitlements file. Otherwise, the App Sandbox may\nprevent you from using them.
\nEnable outgoing network connections to allow your app to connect to a server:
\n<key>com.apple.security.network.client</key>\n<true/>\nEnable incoming network connections to allow your app to open a network\nlistening socket:
\n<key>com.apple.security.network.server</key>\n<true/>\nSee the Enabling Network Access documentation for more\ndetails.
\n<key>com.apple.security.files.user-selected.read-only</key>\n<true/>\nSee the Enabling User-Selected File Access documentation for\nmore details.
\n<key>com.apple.security.files.user-selected.read-write</key>\n<true/>\nSee the Enabling User-Selected File Access documentation for\nmore details.
\nDepending on the countries in which you are releasing your app, you may be\nrequired to provide information on the cryptographic algorithms used in your\nsoftware. See the encryption export compliance docs for\nmore information.
\nElectron uses following cryptographic algorithms:
\nElectron has APIs to configure the app's icon in the macOS Dock. A macOS-only\nAPI exists to create a custom dock menu, but Electron also uses the app dock\nicon as the entry point for cross-platform features like\nrecent documents and application progress.
\nThe custom dock is commonly used to add shortcuts to tasks the user wouldn't\nwant to open the whole app window for.
\nDock menu of Terminal.app:
\n![\"Dock](\"https://cloud.githubusercontent.com/assets/639601/5069962/6032658a-6e9c-11e4-9953-aa84006bdfff.png\")
To set your custom dock menu, you need to use the\napp.dock.setMenu API,\nwhich is only available on macOS.
Starting with a working application from the\nQuick Start Guide, update the main.js file with the\nfollowing lines:
const { app, BrowserWindow, Menu } = require('electron')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n })\n\n win.loadFile('index.html')\n}\n\nconst dockMenu = Menu.buildFromTemplate([\n {\n label: 'New Window',\n click () { console.log('New Window') }\n }, {\n label: 'New Window with Settings',\n submenu: [\n { label: 'Basic' },\n { label: 'Pro' }\n ]\n },\n { label: 'New Command...' }\n])\n\napp.whenReady().then(() => {\n if (process.platform === 'darwin') {\n app.dock.setMenu(dockMenu)\n }\n}).then(createWindow)\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n\nAfter launching the Electron application, right click the application icon.\nYou should see the custom menu you just defined:
\n![\"macOS](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/macos-dock-menu.png\")
workingSetSize Integer - The amount of memory currently pinned to actual physical RAM.peakWorkingSetSize Integer - The maximum amount of memory that has ever been pinned\nto actual physical RAM.privateBytes Integer (optional) Windows - The amount of memory not shared by other processes, such as\nJS heap or HTML content.Note that all statistics are reported in Kilobytes.
", "title": "MemoryInfo Object", "description": "" }, "/docs/api/structures/memory-usage-details": { "locale": "en-US", "slug": "memory-usage-details", "href": "/docs/api/structures/memory-usage-details", "crowdinFileId": "256461", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/memory-usage-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "count Numbersize NumberliveSize Number\n\nCreate native application menus and context menus.
\n
Process: Main
\nnew Menu()Creates a new menu.
\nThe Menu class has the following static methods:
Menu.setApplicationMenu(menu)menu Menu | nullSets menu as the application menu on macOS. On Windows and Linux, the\nmenu will be set as each window's top menu.
Also on Windows and Linux, you can use a & in the top-level item name to\nindicate which letter should get a generated accelerator. For example, using\n&File for the file menu would result in a generated Alt-F accelerator that\nopens the associated menu. The indicated character in the button label then gets an\nunderline, and the & character is not displayed on the button label.
In order to escape the & character in an item name, add a proceeding &. For example, &&File would result in &File displayed on the button label.
Passing null will suppress the default menu. On Windows and Linux,\nthis has the additional effect of removing the menu bar from the window.
Note: The default menu will be created automatically if the app does not set one.\nIt contains standard items such as File, Edit, View, Window and Help.
Menu.getApplicationMenu()Returns Menu | null - The application menu, if set, or null, if not set.
Note: The returned Menu instance doesn't support dynamic addition or\nremoval of menu items. Instance properties can still\nbe dynamically modified.
Menu.sendActionToFirstResponder(action) macOSaction StringSends the action to the first responder of application. This is used for\nemulating default macOS menu behaviors. Usually you would use the\nrole property of a MenuItem.
See the macOS Cocoa Event Handling Guide\nfor more information on macOS' native actions.
\nMenu.buildFromTemplate(template)template (MenuItemConstructorOptions | MenuItem)[]Returns Menu
Generally, the template is an array of options for constructing a\nMenuItem. The usage can be referenced above.
You can also attach other fields to the element of the template and they will become properties of the constructed menu items.
The menu object has the following instance methods:
menu.popup([options])options Object (optional)window BrowserWindow (optional) - Default is the focused window.x Number (optional) - Default is the current mouse cursor position.\nMust be declared if y is declared.y Number (optional) - Default is the current mouse cursor position.\nMust be declared if x is declared.positioningItem Number (optional) macOS - The index of the menu item to\nbe positioned under the mouse cursor at the specified coordinates. Default\nis -1.callback Function (optional) - Called when menu is closed.Pops up this menu as a context menu in the BrowserWindow.
menu.closePopup([browserWindow])browserWindow BrowserWindow (optional) - Default is the focused window.Closes the context menu in the browserWindow.
menu.append(menuItem)menuItem MenuItemAppends the menuItem to the menu.
menu.getMenuItemById(id)id StringReturns MenuItem | null the item with the specified id
menu.insert(pos, menuItem)pos IntegermenuItem MenuItemInserts the menuItem to the pos position of the menu.
Objects created with new Menu or returned by Menu.buildFromTemplate emit the following events:
Note: Some events are only available on specific operating systems and are\nlabeled as such.
\nReturns:
\nevent EventEmitted when menu.popup() is called.
Returns:
\nevent EventEmitted when a popup is closed either manually or with menu.closePopup().
menu objects also have the following properties:
menu.itemsA MenuItem[] array containing the menu's items.
Each Menu consists of multiple MenuItems and each MenuItem\ncan have a submenu.
An example of creating the application menu with the simple template API:
\nconst { app, Menu } = require('electron')\n\nconst isMac = process.platform === 'darwin'\n\nconst template = [\n // { role: 'appMenu' }\n ...(isMac ? [{\n label: app.name,\n submenu: [\n { role: 'about' },\n { type: 'separator' },\n { role: 'services' },\n { type: 'separator' },\n { role: 'hide' },\n { role: 'hideOthers' },\n { role: 'unhide' },\n { type: 'separator' },\n { role: 'quit' }\n ]\n }] : []),\n // { role: 'fileMenu' }\n {\n label: 'File',\n submenu: [\n isMac ? { role: 'close' } : { role: 'quit' }\n ]\n },\n // { role: 'editMenu' }\n {\n label: 'Edit',\n submenu: [\n { role: 'undo' },\n { role: 'redo' },\n { type: 'separator' },\n { role: 'cut' },\n { role: 'copy' },\n { role: 'paste' },\n ...(isMac ? [\n { role: 'pasteAndMatchStyle' },\n { role: 'delete' },\n { role: 'selectAll' },\n { type: 'separator' },\n {\n label: 'Speech',\n submenu: [\n { role: 'startSpeaking' },\n { role: 'stopSpeaking' }\n ]\n }\n ] : [\n { role: 'delete' },\n { type: 'separator' },\n { role: 'selectAll' }\n ])\n ]\n },\n // { role: 'viewMenu' }\n {\n label: 'View',\n submenu: [\n { role: 'reload' },\n { role: 'forceReload' },\n { role: 'toggleDevTools' },\n { type: 'separator' },\n { role: 'resetZoom' },\n { role: 'zoomIn' },\n { role: 'zoomOut' },\n { type: 'separator' },\n { role: 'togglefullscreen' }\n ]\n },\n // { role: 'windowMenu' }\n {\n label: 'Window',\n submenu: [\n { role: 'minimize' },\n { role: 'zoom' },\n ...(isMac ? [\n { type: 'separator' },\n { role: 'front' },\n { type: 'separator' },\n { role: 'window' }\n ] : [\n { role: 'close' }\n ])\n ]\n },\n {\n role: 'help',\n submenu: [\n {\n label: 'Learn More',\n click: async () => {\n const { shell } = require('electron')\n await shell.openExternal('https://electronjs.org')\n }\n }\n ]\n }\n]\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nTo create menus initiated by the renderer process, send the required\ninformation to the main process using IPC and have the main process display the\nmenu on behalf of the renderer.
\nBelow is an example of showing a menu when the user right clicks the page:
\n// renderer\nwindow.addEventListener('contextmenu', (e) => {\n e.preventDefault()\n ipcRenderer.send('show-context-menu')\n})\n\nipcRenderer.on('context-menu-command', (e, command) => {\n // ...\n})\n\n// main\nipcMain.on('show-context-menu', (event) => {\n const template = [\n {\n label: 'Menu Item 1',\n click: () => { event.sender.send('context-menu-command', 'menu-item-1') }\n },\n { type: 'separator' },\n { label: 'Menu Item 2', type: 'checkbox', checked: true }\n ]\n const menu = Menu.buildFromTemplate(template)\n menu.popup(BrowserWindow.fromWebContents(event.sender))\n})\nmacOS has a completely different style of application menu from Windows and\nLinux. Here are some notes on making your app's menu more native-like.
\nOn macOS there are many system-defined standard menus, like the Services and\nWindows menus. To make your menu a standard menu, you should set your menu's\nrole to one of the following and Electron will recognize them and make them\nbecome standard menus:
windowhelpservicesmacOS has provided standard actions for some menu items, like About xxx,\nHide xxx, and Hide Others. To set the action of a menu item to a standard\naction, you should set the role attribute of the menu item.
On macOS the label of the application menu's first item is always your app's\nname, no matter what label you set. To change it, modify your app bundle's\nInfo.plist file. See\nAbout Information Property List Files\nfor more information.
The setMenu method of browser windows can set the menu of certain\nbrowser windows.
You can make use of before, after, beforeGroupContaining, afterGroupContaining and id to control how the item will be placed when building a menu with Menu.buildFromTemplate.
before - Inserts this item before the item with the specified label. If the\nreferenced item doesn't exist the item will be inserted at the end of\nthe menu. Also implies that the menu item in question should be placed in the same “group” as the item.after - Inserts this item after the item with the specified label. If the\nreferenced item doesn't exist the item will be inserted at the end of\nthe menu. Also implies that the menu item in question should be placed in the same “group” as the item.beforeGroupContaining - Provides a means for a single context menu to declare\nthe placement of their containing group before the containing group of the item with the specified label.afterGroupContaining - Provides a means for a single context menu to declare\nthe placement of their containing group after the containing group of the item with the specified label.By default, items will be inserted in the order they exist in the template unless one of the specified positioning keywords is used.
\nTemplate:
\n[\n { id: '1', label: 'one' },\n { id: '2', label: 'two' },\n { id: '3', label: 'three' },\n { id: '4', label: 'four' }\n]\nMenu:
\n- 1\n- 2\n- 3\n- 4\nTemplate:
\n[\n { id: '1', label: 'one' },\n { type: 'separator' },\n { id: '3', label: 'three', beforeGroupContaining: ['1'] },\n { id: '4', label: 'four', afterGroupContaining: ['2'] },\n { type: 'separator' },\n { id: '2', label: 'two' }\n]\nMenu:
\n- 3\n- 4\n- ---\n- 1\n- ---\n- 2\nTemplate:
\n[\n { id: '1', label: 'one', after: ['3'] },\n { id: '2', label: 'two', before: ['1'] },\n { id: '3', label: 'three' }\n]\nMenu:
\n- ---\n- 3\n- 2\n- 1\n\n\nAdd items to native application menus and context menus.
\n
Process: Main
\nSee Menu for examples.
new MenuItem(options)options Objectclick Function (optional) - Will be called with\nclick(menuItem, browserWindow, event) when the menu item is clicked.menuItem MenuItembrowserWindow BrowserWindow | undefined - This will not be defined if no window is open.event KeyboardEventrole String (optional) - Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu - Define the action of the menu item, when specified the\nclick property will be ignored. See roles.type String (optional) - Can be normal, separator, submenu, checkbox or\nradio.label String (optional)sublabel String (optional)toolTip String (optional) macOS - Hover text for this menu item.accelerator Accelerator (optional)icon (NativeImage | String) (optional)enabled Boolean (optional) - If false, the menu item will be greyed out and\nunclickable.acceleratorWorksWhenHidden Boolean (optional) macOS - default is true, and when false will prevent the accelerator from triggering the item if the item is not visible`.visible Boolean (optional) - If false, the menu item will be entirely hidden.checked Boolean (optional) - Should only be specified for checkbox or radio type\nmenu items.registerAccelerator Boolean (optional) Linux Windows - If false, the accelerator won't be registered\nwith the system, but it will still be displayed. Defaults to true.sharingItem SharingItem (optional) macOS - The item to share when the role is shareMenu.submenu (MenuItemConstructorOptions[] | Menu) (optional) - Should be specified\nfor submenu type menu items. If submenu is specified, the type: 'submenu' can be omitted.\nIf the value is not a Menu then it will be automatically converted to one using\nMenu.buildFromTemplate.id String (optional) - Unique within a single menu. If defined then it can be used\nas a reference to this item by the position attribute.before String - Inserts this item before the item with the specified label. If\nthe referenced item doesn't exist the item will be inserted at the end of the menu. Also implies\nthat the menu item in question should be placed in the same “group” as the item.after String - Inserts this item after the item with the specified label. If the\nreferenced item doesn't exist the item will be inserted at the end of\nthe menu.beforeGroupContaining String - Provides a means for a single context menu to declare\nthe placement of their containing group before the containing group of the item\nwith the specified label.afterGroupContaining String - Provides a means for a single context menu to declare\nthe placement of their containing group after the containing group of the item\nwith the specified label.Note: acceleratorWorksWhenHidden is specified as being macOS-only because accelerators always work when items are hidden on Windows and Linux. The option is exposed to users to give them the option to turn it off, as this is possible in native macOS development. This property is only usable on macOS High Sierra 10.13 or newer.
Roles allow menu items to have predefined behaviors.
\nIt is best to specify role for any menu item that matches a standard role,\nrather than trying to manually implement the behavior in a click function.\nThe built-in role behavior will give the best native experience.
The label and accelerator values are optional when using a role and will\ndefault to appropriate values for each platform.
Every menu item must have either a role, label, or in the case of a separator\na type.
The role property can have following values:
undoabout - Trigger a native about panel (custom message box on Window, which does not provide its own).redocutcopypastepasteAndMatchStyleselectAlldeleteminimize - Minimize current window.close - Close current window.quit - Quit the application.reload - Reload the current window.forceReload - Reload the current window ignoring the cache.toggleDevTools - Toggle developer tools in the current window.togglefullscreen - Toggle full screen mode on the current window.resetZoom - Reset the focused page's zoom level to the original size.zoomIn - Zoom in the focused page by 10%.zoomOut - Zoom out the focused page by 10%.toggleSpellChecker - Enable/disable builtin spell checker.fileMenu - Whole default \"File\" menu (Close / Quit)editMenu - Whole default \"Edit\" menu (Undo, Copy, etc.).viewMenu - Whole default \"View\" menu (Reload, Toggle Developer Tools, etc.)windowMenu - Whole default \"Window\" menu (Minimize, Zoom, etc.).The following additional roles are available on macOS:
\nappMenu - Whole default \"App\" menu (About, Services, etc.)hide - Map to the hide action.hideOthers - Map to the hideOtherApplications action.unhide - Map to the unhideAllApplications action.startSpeaking - Map to the startSpeaking action.stopSpeaking - Map to the stopSpeaking action.front - Map to the arrangeInFront action.zoom - Map to the performZoom action.toggleTabBar - Map to the toggleTabBar action.selectNextTab - Map to the selectNextTab action.selectPreviousTab - Map to the selectPreviousTab action.mergeAllWindows - Map to the mergeAllWindows action.moveTabToNewWindow - Map to the moveTabToNewWindow action.window - The submenu is a \"Window\" menu.help - The submenu is a \"Help\" menu.services - The submenu is a \"Services\" menu. This is only intended for use in the Application Menu and is not the same as the \"Services\" submenu used in context menus in macOS apps, which is not implemented in Electron.recentDocuments - The submenu is an \"Open Recent\" menu.clearRecentDocuments - Map to the clearRecentDocuments action.shareMenu - The submenu is share menu. The sharingItem property must also be set to indicate the item to share.When specifying a role on macOS, label and accelerator are the only\noptions that will affect the menu item. All other options will be ignored.\nLowercase role, e.g. toggledevtools, is still supported.
Nota Bene: The enabled and visibility properties are not available for top-level menu items in the tray on macOS.
The following properties are available on instances of MenuItem:
menuItem.idA String indicating the item's unique id, this property can be\ndynamically changed.
menuItem.labelA String indicating the item's visible label.
menuItem.clickA Function that is fired when the MenuItem receives a click event.\nIt can be called with menuItem.click(event, focusedWindow, focusedWebContents).
event KeyboardEventfocusedWindow BrowserWindowfocusedWebContents WebContentsmenuItem.submenuA Menu (optional) containing the menu\nitem's submenu, if present.
menuItem.typeA String indicating the type of the item. Can be normal, separator, submenu, checkbox or radio.
menuItem.roleA String (optional) indicating the item's role, if set. Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu
menuItem.acceleratorAn Accelerator (optional) indicating the item's accelerator, if set.
menuItem.userAccelerator Readonly macOSAn Accelerator | null indicating the item's user-assigned accelerator for the menu item.
Note: This property is only initialized after the MenuItem has been added to a Menu. Either via Menu.buildFromTemplate or via Menu.append()/insert(). Accessing before initialization will just return null.
menuItem.iconA NativeImage | String (optional) indicating the\nitem's icon, if set.
menuItem.sublabelA String indicating the item's sublabel.
menuItem.toolTip macOSA String indicating the item's hover text.
menuItem.enabledA Boolean indicating whether the item is enabled, this property can be\ndynamically changed.
menuItem.visibleA Boolean indicating whether the item is visible, this property can be\ndynamically changed.
menuItem.checkedA Boolean indicating whether the item is checked, this property can be\ndynamically changed.
A checkbox menu item will toggle the checked property on and off when\nselected.
A radio menu item will turn on its checked property when clicked, and\nwill turn off that property for all adjacent items in the same menu.
You can add a click function for additional behavior.
menuItem.registerAcceleratorA Boolean indicating if the accelerator should be registered with the\nsystem or just displayed.
This property can be dynamically changed.
\nmenuItem.sharingItem macOSA SharingItem indicating the item to share when the role is shareMenu.
This property can be dynamically changed.
\nmenuItem.commandIdA Number indicating an item's sequential unique id.
menuItem.menuA Menu that the item is a part of.
MessageChannelMain is the main-process-side equivalent of the DOM\nMessageChannel object. Its singular function is to create a pair of\nconnected MessagePortMain objects.
See the Channel Messaging API documentation for more information on using\nchannel messaging.
\n\n\nChannel interface for channel messaging in the main process.
\n
Process: Main
\nExample:
\n// Main process\nconst { MessageChannelMain } = require('electron')\nconst { port1, port2 } = new MessageChannelMain()\nw.webContents.postMessage('port', null, [port2])\nport1.postMessage({ some: 'message' })\n\n// Renderer process\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('port', (e) => {\n // e.ports is a list of ports sent along with this message\n e.ports[0].on('message', (messageEvent) => {\n console.log(messageEvent.data)\n })\n})\nchannel.port1A MessagePortMain property.
channel.port2A MessagePortMain property.
MessagePortMain is the main-process-side equivalent of the DOM\nMessagePort object. It behaves similarly to the DOM version, with the\nexception that it uses the Node.js EventEmitter event system, instead of the\nDOM EventTarget system. This means you should use port.on('message', ...)\nto listen for events, instead of port.onmessage = ... or\nport.addEventListener('message', ...)
See the Channel Messaging API documentation for more information on using\nchannel messaging.
\nMessagePortMain is an [EventEmitter][event-emitter].
\n\nPort interface for channel messaging in the main process.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
port.postMessage(message, [transfer])Sends a message from the port, and optionally, transfers ownership of objects\nto other browsing contexts.
\nport.start()Starts the sending of messages queued on the port. Messages will be queued\nuntil this method is called.
\nport.close()Disconnects the port, so it is no longer active.
\nReturns:
\nmessageEvent Objectdata anyports MessagePortMain[]Emitted when a MessagePortMain object receives a message.
\nEmitted when the remote end of a MessagePortMain object becomes disconnected.
", "title": "MessagePortMain", "description": "Port interface for channel messaging in the main process." }, "/docs/tutorial/message-ports": { "locale": "en-US", "slug": "message-ports", "href": "/docs/tutorial/message-ports", "crowdinFileId": "256219", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/message-ports.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "MessagePorts are a web feature that allow passing messages between\ndifferent contexts. It's like window.postMessage, but on different channels.\nThe goal of this document is to describe how Electron extends the Channel\nMessaging model, and to give some examples of how you might use MessagePorts in\nyour app.
Here is a very brief example of what a MessagePort is and how it works:
\n// renderer.js ///////////////////////////////////////////////////////////////\n// MessagePorts are created in pairs. A connected pair of message ports is\n// called a channel.\nconst channel = new MessageChannel()\n\n// The only difference between port1 and port2 is in how you use them. Messages\n// sent to port1 will be received by port2 and vice-versa.\nconst port1 = channel.port1\nconst port2 = channel.port2\n\n// It's OK to send a message on the channel before the other end has registered\n// a listener. Messages will be queued until a listener is registered.\nport2.postMessage({ answer: 42 })\n\n// Here we send the other end of the channel, port1, to the main process. It's\n// also possible to send MessagePorts to other frames, or to Web Workers, etc.\nipcRenderer.postMessage('port', null, [port1])\n// main.js ///////////////////////////////////////////////////////////////////\n// In the main process, we receive the port.\nipcMain.on('port', (event) => {\n // When we receive a MessagePort in the main process, it becomes a\n // MessagePortMain.\n const port = event.ports[0]\n\n // MessagePortMain uses the Node.js-style events API, rather than the\n // web-style events API. So .on('message', ...) instead of .onmessage = ...\n port.on('message', (event) => {\n // data is { answer: 42 }\n const data = event.data\n })\n\n // MessagePortMain queues messages until the .start() method has been called.\n port.start()\n})\nThe Channel Messaging API documentation is a great way to learn more about\nhow MessagePorts work.
\nIn the renderer, the MessagePort class behaves exactly as it does on the web.\nThe main process is not a web page, though—it has no Blink integration—and so\nit does not have the MessagePort or MessageChannel classes. In order to\nhandle and interact with MessagePorts in the main process, Electron adds two\nnew classes: MessagePortMain and MessageChannelMain. These behave\nsimilarly to the analogous classes in the renderer.
MessagePort objects can be created in either the renderer or the main\nprocess, and passed back and forth using the ipcRenderer.postMessage and\nWebContents.postMessage methods. Note that the usual IPC methods like\nsend and invoke cannot be used to transfer MessagePorts, only the\npostMessage methods can transfer MessagePorts.
By passing MessagePorts via the main process, you can connect two pages that\nmight not otherwise be able to communicate (e.g. due to same-origin\nrestrictions).
close eventElectron adds one feature to MessagePort that isn't present on the web, in\norder to make MessagePorts more useful. That is the close event, which is\nemitted when the other end of the channel is closed. Ports can also be\nimplicitly closed by being garbage-collected.
In the renderer, you can listen for the close event either by assigning to\nport.onclose or by calling port.addEventListener('close', ...). In the main\nprocess, you can listen for the close event by calling port.on('close', ...).
In this example, your app has a worker process implemented as a hidden window.\nYou want the app page to be able to communicate directly with the worker\nprocess, without the performance overhead of relaying via the main process.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, ipcMain, MessageChannelMain } = require('electron')\n\napp.whenReady().then(async () => {\n // The worker process is a hidden BrowserWindow, so that it will have access\n // to a full Blink context (including e.g. <canvas>, audio, fetch(), etc.)\n const worker = new BrowserWindow({\n show: false,\n webPreferences: { nodeIntegration: true }\n })\n await worker.loadFile('worker.html')\n\n // The main window will send work to the worker process and receive results\n // over a MessagePort.\n const mainWindow = new BrowserWindow({\n webPreferences: { nodeIntegration: true }\n })\n mainWindow.loadFile('app.html')\n\n // We can't use ipcMain.handle() here, because the reply needs to transfer a\n // MessagePort.\n ipcMain.on('request-worker-channel', (event) => {\n // For security reasons, let's make sure only the frames we expect can\n // access the worker.\n if (event.senderFrame === mainWindow.webContents.mainFrame) {\n // Create a new channel ...\n const { port1, port2 } = new MessageChannelMain()\n // ... send one end to the worker ...\n worker.webContents.postMessage('new-client', null, [port1])\n // ... and the other end to the main window.\n event.senderFrame.postMessage('provide-worker-channel', null, [port2])\n // Now the main window and the worker can communicate with each other\n // without going through the main process!\n }\n })\n})\n<!-- worker.html ------------------------------------------------------------>\n<script>\nconst { ipcRenderer } = require('electron')\n\nfunction doWork(input) {\n // Something cpu-intensive.\n return input * 2\n}\n\n// We might get multiple clients, for instance if there are multiple windows,\n// or if the main window reloads.\nipcRenderer.on('new-client', (event) => {\n const [ port ] = event.ports\n port.onmessage = (event) => {\n // The event data can be any serializable object (and the event could even\n // carry other MessagePorts with it!)\n const result = doWork(event.data)\n port.postMessage(result)\n }\n})\n</script>\n<!-- app.html --------------------------------------------------------------->\n<script>\nconst { ipcRenderer } = require('electron')\n\n// We request that the main process sends us a channel we can use to\n// communicate with the worker.\nipcRenderer.send('request-worker-channel')\n\nipcRenderer.once('provide-worker-channel', (event) => {\n // Once we receive the reply, we can take the port...\n const [ port ] = event.ports\n // ... register a handler to receive results ...\n port.onmessage = (event) => {\n console.log('received result:', event.data)\n }\n // ... and start sending it work!\n port.postMessage(21)\n})\n</script>\nElectron's built-in IPC methods only support two modes: fire-and-forget\n(e.g. send), or request-response (e.g. invoke). Using MessageChannels, you\ncan implement a \"response stream\", where a single request responds with a\nstream of data.
// renderer.js ///////////////////////////////////////////////////////////////\n\nfunction makeStreamingRequest (element, callback) {\n // MessageChannels are lightweight--it's cheap to create a new one for each\n // request.\n const { port1, port2 } = new MessageChannel()\n\n // We send one end of the port to the main process ...\n ipcRenderer.postMessage(\n 'give-me-a-stream',\n { element, count: 10 },\n [port2]\n )\n\n // ... and we hang on to the other end. The main process will send messages\n // to its end of the port, and close it when it's finished.\n port1.onmessage = (event) => {\n callback(event.data)\n }\n port1.onclose = () => {\n console.log('stream ended')\n }\n}\n\nmakeStreamingRequest(42, (data) => {\n console.log('got response data:', event.data)\n})\n// We will see \"got response data: 42\" 10 times.\n// main.js ///////////////////////////////////////////////////////////////////\n\nipcMain.on('give-me-a-stream', (event, msg) => {\n // The renderer has sent us a MessagePort that it wants us to send our\n // response over.\n const [replyPort] = event.ports\n\n // Here we send the messages synchronously, but we could just as easily store\n // the port somewhere and send messages asynchronously.\n for (let i = 0; i < msg.count; i++) {\n replyPort.postMessage(msg.element)\n }\n\n // We close the port when we're done to indicate to the other end that we\n // won't be sending any more messages. This isn't strictly necessary--if we\n // didn't explicitly close the port, it would eventually be garbage\n // collected, which would also trigger the 'close' event in the renderer.\n replyPort.close()\n})\nWhen context isolation is enabled, IPC messages from the main process to\nthe renderer are delivered to the isolated world, rather than to the main\nworld. Sometimes you want to deliver messages to the main world directly,\nwithout having to step through the isolated world.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, MessageChannelMain } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(async () => {\n // Create a BrowserWindow with contextIsolation enabled.\n const bw = new BrowserWindow({\n webPreferences: {\n contextIsolation: true,\n preload: path.join(__dirname, 'preload.js')\n }\n })\n bw.loadURL('index.html')\n\n // We'll be sending one end of this channel to the main world of the\n // context-isolated page.\n const { port1, port2 } = new MessageChannelMain()\n\n // It's OK to send a message on the channel before the other end has\n // registered a listener. Messages will be queued until a listener is\n // registered.\n port2.postMessage({ test: 21 })\n\n // We can also receive messages from the main world of the renderer.\n port2.on('message', (event) => {\n console.log('from renderer main world:', event.data)\n })\n port2.start()\n\n // The preload script will receive this IPC message and transfer the port\n // over to the main world.\n bw.webContents.postMessage('main-world-port', null, [port1])\n})\n// preload.js ////////////////////////////////////////////////////////////////\nconst { ipcRenderer } = require('electron')\n\n// We need to wait until the main world is ready to receive the message before\n// sending the port. We create this promise in the preload so it's guaranteed\n// to register the onload listener before the load event is fired.\nconst windowLoaded = new Promise(resolve => {\n window.onload = resolve\n})\n\nipcRenderer.on('main-world-port', async (event) => {\n await windowLoaded\n // We use regular window.postMessage to transfer the port from the isolated\n // world to the main world.\n window.postMessage('main-world-port', '*', event.ports)\n})\n<!-- index.html ------------------------------------------------------------->\n<script>\nwindow.onmessage = (event) => {\n // event.source === window means the message is coming from the preload\n // script, as opposed to from an <iframe> or other source.\n if (event.source === window && event.data === 'main-world-port') {\n const [ port ] = event.ports\n // Once we have the port, we can communicate directly with the main\n // process.\n port.onmessage = (event) => {\n console.log('from main process:', event.data)\n port.postMessage(event.data * 2)\n }\n }\n}\n</script>\nmimeType String (optional) - MIME type of the buffer.charset String (optional) - Charset of the buffer.data Buffer - The actual Buffer content.InputEventtype String - The type of the event, can be mouseDown,\nmouseUp, mouseEnter, mouseLeave, contextMenu, mouseWheel or mouseMove.x Integery Integerbutton String (optional) - The button pressed, can be left, middle, right.globalX Integer (optional)globalY Integer (optional)movementX Integer (optional)movementY Integer (optional)clickCount Integer (optional)MouseInputEventtype String - The type of the event, can be mouseWheel.deltaX Integer (optional)deltaY Integer (optional)wheelTicksX Integer (optional)wheelTicksY Integer (optional)accelerationRatioX Integer (optional)accelerationRatioY Integer (optional)hasPreciseScrollingDeltas Boolean (optional)canScroll Boolean (optional)With Web Workers, it is possible to run JavaScript in OS-level\nthreads.
\nIt is possible to use Node.js features in Electron's Web Workers, to do\nso the nodeIntegrationInWorker option should be set to true in\nwebPreferences.
const win = new BrowserWindow({\n webPreferences: {\n nodeIntegrationInWorker: true\n }\n})\nThe nodeIntegrationInWorker can be used independent of nodeIntegration, but\nsandbox must not be set to true.
All built-in modules of Node.js are supported in Web Workers, and asar\narchives can still be read with Node.js APIs. However none of Electron's\nbuilt-in modules can be used in a multi-threaded environment.
Any native Node.js module can be loaded directly in Web Workers, but it is\nstrongly recommended not to do so. Most existing native modules have been\nwritten assuming single-threaded environment, using them in Web Workers will\nlead to crashes and memory corruptions.
\nNote that even if a native Node.js module is thread-safe it's still not safe to\nload it in a Web Worker because the process.dlopen function is not thread\nsafe.
The only way to load a native module safely for now, is to make sure the app\nloads no native modules after the Web Workers get started.
\nprocess.dlopen = () => {\n throw new Error('Load native module is not safe')\n}\nconst worker = new Worker('script.js')\nCertain kinds of applications that manipulate files might want to support\nthe operating system's native file drag & drop feature. Dragging files into\nweb content is common and supported by many websites. Electron additionally\nsupports dragging files and content out from web content into the operating\nsystem's world.
\nTo implement this feature in your app, you need to call the\nwebContents.startDrag(item)\nAPI in response to the ondragstart event.
An example demonstrating how you can create a file on the fly to be dragged out of the window.
\nIn preload.js use the contextBridge to inject a method window.electron.startDrag(...) that will send an IPC message to the main process.
const { contextBridge, ipcRenderer } = require('electron')\nconst path = require('path')\n\ncontextBridge.exposeInMainWorld('electron', {\n startDrag: (fileName) => {\n ipcRenderer.send('ondragstart', path.join(process.cwd(), fileName))\n }\n})\nAdd a draggable element to index.html, and reference your renderer script:
<div style=\"border:2px solid black;border-radius:3px;padding:5px;display:inline-block\" draggable=\"true\" id=\"drag\">Drag me</div>\n<script src=\"renderer.js\"></script>\nIn renderer.js set up the renderer process to handle drag events by calling the method you added via the contextBridge above.
document.getElementById('drag').ondragstart = (event) => {\n event.preventDefault()\n window.electron.startDrag('drag-and-drop.md')\n}\nIn the Main process (main.js file), expand the received event with a path to the file that is\nbeing dragged and an icon:
const { ipcMain } = require('electron')\n\nipcMain.on('ondragstart', (event, filePath) => {\n event.sender.startDrag({\n file: filePath,\n icon: '/path/to/icon.png'\n })\n})\nAfter launching the Electron application, try dragging and dropping\nthe item from the BrowserWindow onto your desktop. In this guide,\nthe item is a Markdown file located in the root of the project:
\n![\"Drag](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/drag-and-drop.gif\")
\n\n\nCreate tray, dock, and application icons using PNG or JPG files.
\n
In Electron, for the APIs that take images, you can pass either file paths or\nNativeImage instances. An empty image will be used when null is passed.
For example, when creating a tray or setting a window's icon, you can pass an\nimage file path as a String:
const { BrowserWindow, Tray } = require('electron')\n\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconst win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })\nconsole.log(appIcon, win)\nOr read the image from the clipboard, which returns a NativeImage:
const { clipboard, Tray } = require('electron')\nconst image = clipboard.readImage()\nconst appIcon = new Tray(image)\nconsole.log(appIcon)\nCurrently PNG and JPEG image formats are supported. PNG is recommended\nbecause of its support for transparency and lossless compression.
On Windows, you can also load ICO icons from file paths. For best visual\nquality, it is recommended to include at least the following sizes in the:
Check the Size requirements section in this article.
\nOn platforms that have high-DPI support such as Apple Retina displays, you can\nappend @2x after image's base filename to mark it as a high resolution image.
For example, if icon.png is a normal image that has standard resolution, then\nicon@2x.png will be treated as a high resolution image that has double DPI\ndensity.
If you want to support displays with different DPI densities at the same time,\nyou can put images with different sizes in the same folder and use the filename\nwithout DPI suffixes. For example:
\nimages/\n├── icon.png\n├── icon@2x.png\n└── icon@3x.png\nconst { Tray } = require('electron')\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconsole.log(appIcon)\nThe following suffixes for DPI are also supported:
\n@1x@1.25x@1.33x@1.4x@1.5x@1.8x@2x@2.5x@3x@4x@5xTemplate images consist of black and an alpha channel.\nTemplate images are not intended to be used as standalone images and are usually\nmixed with other content to create the desired final appearance.
\nThe most common case is to use template images for a menu bar icon, so it can\nadapt to both light and dark menu bars.
\nNote: Template image is only supported on macOS.
\nTo mark an image as a template image, its filename should end with the word\nTemplate. For example:
xxxTemplate.pngxxxTemplate@2x.pngThe nativeImage module has the following methods, all of which return\nan instance of the NativeImage class:
nativeImage.createEmpty()Returns NativeImage
Creates an empty NativeImage instance.
nativeImage.createThumbnailFromPath(path, maxSize) macOS Windowspath String - path to a file that we intend to construct a thumbnail out of.maxSize Size - the maximum width and height (positive numbers) the thumbnail returned can be. The Windows implementation will ignore maxSize.height and scale the height according to maxSize.width.Returns Promise<NativeImage> - fulfilled with the file's thumbnail preview image, which is a NativeImage.
nativeImage.createFromPath(path)path StringReturns NativeImage
Creates a new NativeImage instance from a file located at path. This method\nreturns an empty image if the path does not exist, cannot be read, or is not\na valid image.
const nativeImage = require('electron').nativeImage\n\nconst image = nativeImage.createFromPath('/Users/somebody/images/icon.png')\nconsole.log(image)\nnativeImage.createFromBitmap(buffer, options)buffer Bufferoptions Objectwidth Integerheight IntegerscaleFactor Double (optional) - Defaults to 1.0.Returns NativeImage
Creates a new NativeImage instance from buffer that contains the raw bitmap\npixel data returned by toBitmap(). The specific format is platform-dependent.
nativeImage.createFromBuffer(buffer[, options])buffer Bufferoptions Object (optional)width Integer (optional) - Required for bitmap buffers.height Integer (optional) - Required for bitmap buffers.scaleFactor Double (optional) - Defaults to 1.0.Returns NativeImage
Creates a new NativeImage instance from buffer. Tries to decode as PNG or JPEG first.
nativeImage.createFromDataURL(dataURL)dataURL StringReturns NativeImage
Creates a new NativeImage instance from dataURL.
nativeImage.createFromNamedImage(imageName[, hslShift]) macOSReturns NativeImage
Creates a new NativeImage instance from the NSImage that maps to the\ngiven image name. See System Icons\nfor a list of possible values.
The hslShift is applied to the image with the following rules:
hsl_shift[0] (hue): The absolute hue value for the image - 0 and 1 map\nto 0 and 360 on the hue color wheel (red).hsl_shift[1] (saturation): A saturation shift for the image, with the\nfollowing key values:\n0 = remove all color.\n0.5 = leave unchanged.\n1 = fully saturate the image.hsl_shift[2] (lightness): A lightness shift for the image, with the\nfollowing key values:\n0 = remove all lightness (make all pixels black).\n0.5 = leave unchanged.\n1 = full lightness (make all pixels white).This means that [-1, 0, 1] will make the image completely white and\n[-1, 1, 0] will make the image completely black.
In some cases, the NSImageName doesn't match its string representation; one example of this is NSFolderImageName, whose string representation would actually be NSFolder. Therefore, you'll need to determine the correct string representation for your image before passing it in. This can be done with the following:
echo -e '#import <Cocoa/Cocoa.h>\\nint main() { NSLog(@\"%@\", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test
where SYSTEM_IMAGE_NAME should be replaced with any value from this list.
\n\nNatively wrap images such as tray, dock, and application icons.
\n
Process: Main, Renderer
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The following methods are available on instances of the NativeImage class:
image.toPNG([options])options Object (optional)scaleFactor Double (optional) - Defaults to 1.0.Returns Buffer - A Buffer that contains the image's PNG encoded data.
image.toJPEG(quality)quality Integer - Between 0 - 100.Returns Buffer - A Buffer that contains the image's JPEG encoded data.
image.toBitmap([options])options Object (optional)scaleFactor Double (optional) - Defaults to 1.0.Returns Buffer - A Buffer that contains a copy of the image's raw bitmap pixel\ndata.
image.toDataURL([options])options Object (optional)scaleFactor Double (optional) - Defaults to 1.0.Returns String - The data URL of the image.
image.getBitmap([options])options Object (optional)scaleFactor Double (optional) - Defaults to 1.0.Returns Buffer - A Buffer that contains the image's raw bitmap pixel data.
The difference between getBitmap() and toBitmap() is that getBitmap() does not\ncopy the bitmap data, so you have to use the returned Buffer immediately in\ncurrent event loop tick; otherwise the data might be changed or destroyed.
image.getNativeHandle() macOSReturns Buffer - A Buffer that stores C pointer to underlying native handle of\nthe image. On macOS, a pointer to NSImage instance would be returned.
Notice that the returned pointer is a weak pointer to the underlying native\nimage instead of a copy, so you must ensure that the associated\nnativeImage instance is kept around.
image.isEmpty()Returns Boolean - Whether the image is empty.
image.getSize([scaleFactor])scaleFactor Double (optional) - Defaults to 1.0.Returns Size.
If scaleFactor is passed, this will return the size corresponding to the image representation most closely matching the passed value.
image.setTemplateImage(option)option BooleanMarks the image as a template image.
\nimage.isTemplateImage()Returns Boolean - Whether the image is a template image.
image.crop(rect)rect Rectangle - The area of the image to crop.Returns NativeImage - The cropped image.
image.resize(options)options Objectwidth Integer (optional) - Defaults to the image's width.height Integer (optional) - Defaults to the image's height.quality String (optional) - The desired quality of the resize image.\nPossible values are good, better, or best. The default is best.\nThese values express a desired quality/speed tradeoff. They are translated\ninto an algorithm-specific method that depends on the capabilities\n(CPU, GPU) of the underlying platform. It is possible for all three methods\nto be mapped to the same algorithm on a given platform.Returns NativeImage - The resized image.
If only the height or the width are specified then the current aspect ratio\nwill be preserved in the resized image.
image.getAspectRatio([scaleFactor])scaleFactor Double (optional) - Defaults to 1.0.Returns Float - The image's aspect ratio.
If scaleFactor is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value.
image.getScaleFactors()Returns Float[] - An array of all scale factors corresponding to representations for a given nativeImage.
image.addRepresentation(options)options ObjectscaleFactor Double - The scale factor to add the image representation for.width Integer (optional) - Defaults to 0. Required if a bitmap buffer\nis specified as buffer.height Integer (optional) - Defaults to 0. Required if a bitmap buffer\nis specified as buffer.buffer Buffer (optional) - The buffer containing the raw image data.dataURL String (optional) - The data URL containing either a base 64\nencoded PNG or JPEG image.Add an image representation for a specific scale factor. This can be used\nto explicitly add different scale factor representations to an image. This\ncan be called on empty images.
\nnativeImage.isMacTemplateImage macOSA Boolean property that determines whether the image is considered a template image.
Please note that this property only has an effect on macOS.
", "title": "nativeImage", "description": "Create tray, dock, and application icons using PNG or JPG files." }, "/docs/api/native-theme": { "locale": "en-US", "slug": "native-theme", "href": "/docs/api/native-theme", "crowdinFileId": "256343", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/native-theme.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRead and respond to changes in Chromium's native color theme.
\n
Process: Main
\nThe nativeTheme module emits the following events:
Emitted when something in the underlying NativeTheme has changed. This normally\nmeans that either the value of shouldUseDarkColors,\nshouldUseHighContrastColors or shouldUseInvertedColorScheme has changed.\nYou will have to check them to determine which one has changed.
The nativeTheme module has the following properties:
nativeTheme.shouldUseDarkColors ReadonlyA Boolean for if the OS / Chromium currently has a dark mode enabled or is\nbeing instructed to show a dark-style UI. If you want to modify this value you\nshould use themeSource below.
nativeTheme.themeSourceA String property that can be system, light or dark. It is used to override and supersede\nthe value that Chromium has chosen to use internally.
Setting this property to system will remove the override and\neverything will be reset to the OS default. By default themeSource is system.
Settings this property to dark will have the following effects:
nativeTheme.shouldUseDarkColors will be true when accessedprefers-color-scheme CSS query will match dark mode.updated event will be emittedSettings this property to light will have the following effects:
nativeTheme.shouldUseDarkColors will be false when accessedprefers-color-scheme CSS query will match light mode.updated event will be emittedThe usage of this property should align with a classic \"dark mode\" state machine in your application\nwhere the user has three options.
\nFollow OS --> themeSource = 'system'Dark Mode --> themeSource = 'dark'Light Mode --> themeSource = 'light'Your application should then always use shouldUseDarkColors to determine what CSS to apply.
nativeTheme.shouldUseHighContrastColors macOS Windows ReadonlyA Boolean for if the OS / Chromium currently has high-contrast mode enabled\nor is being instructed to show a high-contrast UI.
nativeTheme.shouldUseInvertedColorScheme macOS Windows ReadonlyA Boolean for if the OS / Chromium currently has an inverted color scheme\nor is being instructed to use an inverted color scheme.
\n\nIssue HTTP/HTTPS requests using Chromium's native networking library
\n
Process: Main
\nThe net module is a client-side API for issuing HTTP(S) requests. It is\nsimilar to the HTTP and\nHTTPS modules of Node.js but uses\nChromium's native networking library instead of the Node.js implementation,\noffering better support for web proxies. It also supports checking network status.
The following is a non-exhaustive list of why you may consider using the net\nmodule instead of the native Node.js modules:
The API components (including classes, methods, properties and event names) are similar to those used in\nNode.js.
\nExample usage:
\nconst { app } = require('electron')\napp.whenReady().then(() => {\n const { net } = require('electron')\n const request = net.request('https://github.com')\n request.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`)\n console.log(`HEADERS: ${JSON.stringify(response.headers)}`)\n response.on('data', (chunk) => {\n console.log(`BODY: ${chunk}`)\n })\n response.on('end', () => {\n console.log('No more data in response.')\n })\n })\n request.end()\n})\nThe net API can be used only after the application emits the ready event.\nTrying to use the module before the ready event will throw an error.
The net module has the following methods:
net.request(options)options (ClientRequestConstructorOptions | String) - The ClientRequest constructor options.Returns ClientRequest
Creates a ClientRequest instance using the provided\noptions which are directly forwarded to the ClientRequest constructor.\nThe net.request method would be used to issue both secure and insecure HTTP\nrequests according to the specified protocol scheme in the options object.
net.isOnline()Returns Boolean - Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user\nwon't be able to connect to remote sites. However, a return value of\ntrue is inconclusive; even if some link is up, it is uncertain\nwhether a particular connection attempt to a particular remote site\nwill be successful.
net.online ReadonlyA Boolean property. Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user\nwon't be able to connect to remote sites. However, a return value of\ntrue is inconclusive; even if some link is up, it is uncertain\nwhether a particular connection attempt to a particular remote site\nwill be successful.
\n\nLogging network events for a session.
\n
Process: Main
\nconst { netLog } = require('electron')\n\napp.whenReady().then(async () => {\n await netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nSee --log-net-log to log network events throughout the app's lifecycle.
Note: All methods unless specified can only be used after the ready event\nof the app module gets emitted.
netLog.startLogging(path[, options])path String - File path to record network logs.options Object (optional)captureMode String (optional) - What kinds of data should be captured. By\ndefault, only metadata about requests will be captured. Setting this to\nincludeSensitive will include cookies and authentication data. Setting\nit to everything will include all bytes transferred on sockets. Can be\ndefault, includeSensitive or everything.maxFileSize Number (optional) - When the log grows beyond this size,\nlogging will automatically stop. Defaults to unlimited.Returns Promise<void> - resolves when the net log has begun recording.
Starts recording network events to path.
netLog.stopLogging()Returns Promise<void> - resolves when the net log has been flushed to disk.
Stops recording network events. If not called, net logging will automatically end when app quits.
\nnetLog.currentlyLogging ReadonlyA Boolean property that indicates whether network logs are currently being recorded.
EventnewGuest BrowserWindow (optional)\n\nCreate OS desktop notifications
\n
Process: Main
\nIf you want to show Notifications from a renderer process you should use the HTML5 Notification API
\n\n\nCreate OS desktop notifications
\n
Process: Main
\nNotification is an EventEmitter.
It creates a new Notification with native properties as set by the options.
The Notification class has the following static methods:
Notification.isSupported()Returns Boolean - Whether or not desktop notifications are supported on the current system
new Notification([options])options Object (optional)title String (optional) - A title for the notification, which will be shown at the top of the notification window when it is shown.subtitle String (optional) macOS - A subtitle for the notification, which will be displayed below the title.body String (optional) - The body text of the notification, which will be displayed below the title or subtitle.silent Boolean (optional) - Whether or not to emit an OS notification noise when showing the notification.icon (String | NativeImage) (optional) - An icon to use in the notification.hasReply Boolean (optional) macOS - Whether or not to add an inline reply option to the notification.timeoutType String (optional) Linux Windows - The timeout duration of the notification. Can be 'default' or 'never'.replyPlaceholder String (optional) macOS - The placeholder to write in the inline reply input field.sound String (optional) macOS - The name of the sound file to play when the notification is shown.urgency String (optional) Linux - The urgency level of the notification. Can be 'normal', 'critical', or 'low'.actions NotificationAction[] (optional) macOS - Actions to add to the notification. Please read the available actions and limitations in the NotificationAction documentation.closeButtonText String (optional) macOS - A custom title for the close button of an alert. An empty string will cause the default localized text to be used.toastXml String (optional) Windows - A custom description of the Notification on Windows superseding all properties above. Provides full customization of design and behavior of the notification.Objects created with new Notification emit the following events:
Note: Some events are only available on specific operating systems and are\nlabeled as such.
\nReturns:
\nevent EventEmitted when the notification is shown to the user, note this could be fired\nmultiple times as a notification can be shown multiple times through the\nshow() method.
Returns:
\nevent EventEmitted when the notification is clicked by the user.
\nReturns:
\nevent EventEmitted when the notification is closed by manual intervention from the user.
\nThis event is not guaranteed to be emitted in all cases where the notification\nis closed.
\nReturns:
\nevent Eventreply String - The string the user entered into the inline reply field.Emitted when the user clicks the \"Reply\" button on a notification with hasReply: true.
Returns:
\nevent Eventindex Number - The index of the action that was activated.Returns:
\nevent Eventerror String - The error encountered during execution of the show() method.Emitted when an error is encountered while creating and showing the native notification.
\nObjects created with new Notification have the following instance methods:
notification.show()Immediately shows the notification to the user, please note this means unlike the\nHTML5 Notification implementation, instantiating a new Notification does\nnot immediately show it to the user, you need to call this method before the OS\nwill display it.
If the notification has been shown before, this method will dismiss the previously\nshown notification and create a new one with identical properties.
\nnotification.close()Dismisses the notification.
\nnotification.titleA String property representing the title of the notification.
notification.subtitleA String property representing the subtitle of the notification.
notification.bodyA String property representing the body of the notification.
notification.replyPlaceholderA String property representing the reply placeholder of the notification.
notification.soundA String property representing the sound of the notification.
notification.closeButtonTextA String property representing the close button text of the notification.
notification.silentA Boolean property representing whether the notification is silent.
notification.hasReplyA Boolean property representing whether the notification has a reply action.
notification.urgency LinuxA String property representing the urgency level of the notification. Can be 'normal', 'critical', or 'low'.
Default is 'low' - see NotifyUrgency for more information.
\nnotification.timeoutType Linux WindowsA String property representing the type of timeout duration for the notification. Can be 'default' or 'never'.
If timeoutType is set to 'never', the notification never expires. It stays open until closed by the calling API or the user.
notification.actionsA NotificationAction[] property representing the actions of the notification.
notification.toastXml WindowsA String property representing the custom Toast XML of the notification.
On macOS, you can specify the name of the sound you'd like to play when the\nnotification is shown. Any of the default sounds (under System Preferences >\nSound) can be used, in addition to custom sound files. Be sure that the sound\nfile is copied under the app bundle (e.g., YourApp.app/Contents/Resources),\nor one of the following locations:
~/Library/Sounds/Library/Sounds/Network/Library/Sounds/System/Library/SoundsSee the NSSound docs for more information.
type String - The type of action, can be button.text String (optional) - The label for the given action.| Action Type | Platform Support | Usage of text | Default text | Limitations |
|---|---|---|---|---|
button | macOS | Used as the label for the button | \"Show\" (or a localized string by system default if first of such button, otherwise empty) | Only the first one is used. If multiple are provided, those beyond the first will be listed as additional actions (displayed when mouse active over the action button). Any such action also is incompatible with hasReply and will be ignored if hasReply is true. |
In order for extra notification buttons to work on macOS your app must meet the\nfollowing criteria.
\nNSUserNotificationAlertStyle set to alert in the Info.plist.If either of these requirements are not met the button won't appear.
", "title": "NotificationAction Object", "description": "" }, "/docs/api/structures/notification-response": { "locale": "en-US", "slug": "notification-response", "href": "/docs/api/structures/notification-response", "crowdinFileId": "256473", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/notification-response.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "actionIdentifier String - The identifier string of the action that the user selected.date Number - The delivery date of the notification.identifier String - The unique identifier for this notification request.userInfo Record<String, any> - A dictionary of custom information associated with the notification.userText String (optional) - The text entered or chosen by the user.All three operating systems provide means for applications to send\nnotifications to the user. The technique of showing notifications is different\nfor the Main and Renderer processes.
\nFor the Renderer process, Electron conveniently allows developers to send\nnotifications with the HTML5 Notification API,\nusing the currently running operating system's native notification APIs\nto display it.
\nTo show notifications in the Main process, you need to use the\nNotification module.
\nStarting with a working application from the\nQuick Start Guide, add the following line to the\nindex.html file before the closing </body> tag:
<script src=\"renderer.js\"></script>\n...and add the renderer.js file:
const NOTIFICATION_TITLE = 'Title'\nconst NOTIFICATION_BODY = 'Notification from the Renderer process. Click to log to console.'\nconst CLICK_MESSAGE = 'Notification clicked'\n\nnew Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY })\n .onclick = () => console.log(CLICK_MESSAGE)\nAfter launching the Electron application, you should see the notification:
\n![\"Notification](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/notification-renderer.png\")
Additionally, if you click on the notification, the DOM will update to show \"Notification clicked!\".
\nStarting with a working application from the\nQuick Start Guide, update the main.js file with the following lines:
const { Notification } = require('electron')\n\nconst NOTIFICATION_TITLE = 'Basic Notification'\nconst NOTIFICATION_BODY = 'Notification from the Main process'\n\nfunction showNotification () {\n new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()\n}\n\napp.whenReady().then(createWindow).then(showNotification)\nAfter launching the Electron application, you should see the system notification:
\n![\"Notification](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/notification-main.png\")
While code and user experience across operating systems are similar, there\nare subtle differences.
\nnode_modules\\electron\\dist\\electron.exe to your Start Menu also does the\ntrick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'.\nYou will then need to add the line app.setAppUserModelId(process.execPath) to\nyour main process to see notifications.Electron attempts to automate the work around the Application User Model ID. When\nElectron is used together with the installation and update framework Squirrel,\nshortcuts will automatically be set correctly. Furthermore,\nElectron will detect that Squirrel was used and will automatically call\napp.setAppUserModelId() with the correct value. During development, you may have\nto call app.setAppUserModelId() yourself.
Furthermore, in Windows 8, the maximum length for the notification body is 250\ncharacters, with the Windows team recommending that notifications should be kept\nto 200 characters. That said, that limitation has been removed in Windows 10, with\nthe Windows team asking developers to be reasonable. Attempting to send gigantic\namounts of text to the API (thousands of characters) might result in instability.
\nLater versions of Windows allow for advanced notifications, with custom templates,\nimages, and other flexible elements. To send those notifications (from either the\nmain process or the renderer process), use the userland module\nelectron-windows-notifications,\nwhich uses native Node addons to send ToastNotification and TileNotification objects.
While notifications including buttons work with electron-windows-notifications,\nhandling replies requires the use of\nelectron-windows-interactive-notifications,\nwhich helps with registering the required COM components and calling your\nElectron app with the entered user data.
To detect whether or not you're allowed to send a notification, use the\nuserland module electron-notification-state.
\nThis allows you to determine ahead of time whether or not Windows will\nsilently throw the notification away.
\nNotifications are straight-forward on macOS, but you should be aware of\nApple's Human Interface guidelines regarding notifications.
\nNote that notifications are limited to 256 bytes in size and will be truncated\nif you exceed that limit.
\nTo detect whether or not you're allowed to send a notification, use the userland module\nelectron-notification-state.
\nThis will allow you to detect ahead of time whether or not the notification will be displayed.
\nNotifications are sent using libnotify which can show notifications on any\ndesktop environment that follows Desktop Notifications\nSpecification, including Cinnamon, Enlightenment, Unity,\nGNOME, KDE.
Offscreen rendering lets you obtain the content of a BrowserWindow in a\nbitmap, so it can be rendered anywhere, for example, on texture in a 3D scene.\nThe offscreen rendering in Electron uses a similar approach to that of the\nChromium Embedded Framework\nproject.
Notes:
\npaint event to be more efficient.GPU accelerated rendering means that the GPU is used for composition. Because of\nthat, the frame has to be copied from the GPU which requires more resources,\nthus this mode is slower than the Software output device. The benefit of this\nmode is that WebGL and 3D CSS animations are supported.
\nThis mode uses a software output device for rendering in the CPU, so the frame\ngeneration is much faster. As a result, this mode is preferred over the GPU\naccelerated one.
\nTo enable this mode, GPU acceleration has to be disabled by calling the\napp.disableHardwareAcceleration() API.
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\n\napp.disableHardwareAcceleration()\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ webPreferences: { offscreen: true } })\n\n win.loadURL('https://github.com')\n win.webContents.on('paint', (event, dirty, image) => {\n fs.writeFileSync('ex.png', image.toPNG())\n })\n win.webContents.setFrameRate(60)\n})\nAfter launching the Electron application, navigate to your application's\nworking folder, where you'll find the rendered image.
", "title": "Offscreen Rendering", "description": "" }, "/docs/tutorial/online-offline-events": { "locale": "en-US", "slug": "online-offline-events", "href": "/docs/tutorial/online-offline-events", "crowdinFileId": "256229", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/online-offline-events.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Online and offline event\ndetection can be implemented in the Renderer process using the\nnavigator.onLine\nattribute, part of standard HTML5 API.
The navigator.onLine attribute returns:
false if all network requests are guaranteed to fail (e.g. when disconnected from the network).true in all other cases.Since many cases return true, you should treat with care situations of\ngetting false positives, as we cannot always assume that true value means\nthat Electron can access the Internet. For example, in cases when the computer\nis running a virtualization software that has virtual Ethernet adapters in \"always\nconnected\" state. Therefore, if you want to determine the Internet access\nstatus of Electron, you should develop additional means for this check.
Starting with an HTML file index.html, this example will demonstrate how the navigator.onLine API can be used to build a connection status indicator.
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n</head>\n<body>\n <h1>Connection status: <strong id='status'></strong></h1>\n <script src=\"renderer.js\"></script>\n</body>\n</html>\nIn order to mutate the DOM, create a renderer.js file that adds event listeners to the 'online' and 'offline' window events. The event handler sets the content of the <strong id='status'> element depending on the result of navigator.onLine.
function updateOnlineStatus () {\n document.getElementById('status').innerHTML = navigator.onLine ? 'online' : 'offline'\n}\n\nwindow.addEventListener('online', updateOnlineStatus)\nwindow.addEventListener('offline', updateOnlineStatus)\n\nupdateOnlineStatus()\nFinally, create a main.js file for main process that creates the window.
const { app, BrowserWindow } = require('electron')\n\nfunction createWindow () {\n const onlineStatusWindow = new BrowserWindow({\n width: 400,\n height: 100\n })\n\n onlineStatusWindow.loadFile('index.html')\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nAfter launching the Electron application, you should see the notification:
\n![\"Connection](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/connection-status.png\")
\n", "title": "Online/Offline Event Detection", "description": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API." }, "/docs/development/patches": { "locale": "en-US", "slug": "patches", "href": "/docs/development/patches", "crowdinFileId": "256161", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/patches.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API.
\n
Electron is built on two major upstream projects: Chromium and Node.js. Each of these projects has several of their own dependencies, too. We try our best to use these dependencies exactly as they are but sometimes we can't achieve our goals without patching those upstream dependencies to fit our use cases.
\nEvery patch in Electron is a maintenance burden. When upstream code changes, patches can break—sometimes without even a patch conflict or a compilation error. It's an ongoing effort to keep our patch set up-to-date and effective. So we strive to keep our patch count at a minimum. To that end, every patch must describe its reason for existence in its commit message. That reason must be one of the following:
\nProfile). Include reasoning about why the change cannot be implemented without a patch (e.g. by subclassing or copying the code).In general, all the upstream projects we work with are friendly folks and are often happy to accept refactorings that allow the code in question to be compatible with both Electron and the upstream project. (See e.g. this change in Chromium, which allowed us to remove a patch that did the same thing, or this change in Node, which was a no-op for Node but fixed a bug in Electron.) We should aim to upstream changes whenever we can, and avoid indefinite-lifetime patches.
\nIf you find yourself in the unfortunate position of having to make a change which can only be made through patching an upstream project, you'll need to know how to manage patches in Electron.
\nAll patches to upstream projects in Electron are contained in the patches/ directory. Each subdirectory of patches/ contains several patch files, along with a .patches file which lists the order in which the patches should be applied. Think of these files as making up a series of git commits that are applied on top of the upstream project after we check it out.
patches\n├── config.json <-- this describes which patchset directory is applied to what project\n├── chromium\n│ ├── .patches\n│ ├── accelerator.patch\n│ ├── add_contentgpuclient_precreatemessageloop_callback.patch\n│ ⋮\n├── node\n│ ├── .patches\n│ ├── add_openssl_is_boringssl_guard_to_oaep_hash_check.patch\n│ ├── build_add_gn_build_files.patch\n│ ⋮\n⋮\nTo help manage these patch sets, we provide two tools: git-import-patches and git-export-patches. git-import-patches imports a set of patch files into a git repository by applying each patch in the correct order and creating a commit for each one. git-export-patches does the reverse; it exports a series of git commits in a repository into a set of files in a directory and an accompanying .patches file.
\n\nSide note: the reason we use a
\n.patchesfile to maintain the order of applied patches, rather than prepending a number like001-to each file, is because it reduces conflicts related to patch ordering. It prevents the situation where two PRs both add a patch at the end of the series with the same numbering and end up both getting merged resulting in a duplicate identifier, and it also reduces churn when a patch is added or deleted in the middle of the series.
$ cd src/third_party/electron_node\n$ vim some/code/file.cc\n$ git commit\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\n\n\nNOTE:
\ngit-export-patchesignores any uncommitted files, so you must create a commit if you want your changes to be exported. The subject line of the commit message will be used to derive the patch file name, and the body of the commit message should include the reason for the patch's existence.
Re-exporting patches will sometimes cause shasums in unrelated patches to change. This is generally harmless and can be ignored (but go ahead and add those changes to your PR, it'll stop them from showing up for other people).
\n$ cd src/v8\n$ vim some/code/file.cc\n$ git log\n# Find the commit sha of the patch you want to edit.\n$ git commit --fixup [COMMIT_SHA]\n$ git rebase --autosquash -i [COMMIT_SHA]^\n$ ../electron/script/git-export-patches -o ../electron/patches/v8\n$ vim src/electron/patches/node/.patches\n# Delete the line with the name of the patch you want to remove\n$ cd src/third_party/electron_node\n$ git reset --hard refs/patches/upstream-head\n$ ../../electron/script/git-import-patches ../../electron/patches/node\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\nNote that git-import-patches will mark the commit that was HEAD when it was run as refs/patches/upstream-head. This lets you keep track of which commits are from Electron patches (those that come after refs/patches/upstream-head) and which commits are in upstream (those before refs/patches/upstream-head).
When updating an upstream dependency, patches may fail to apply cleanly. Often, the conflict can be resolved automatically by git with a 3-way merge. You can instruct git-import-patches to use the 3-way merge algorithm by passing the -3 argument:
$ cd src/third_party/electron_node\n# If the patch application failed midway through, you can reset it with:\n$ git am --abort\n# And then retry with 3-way merge:\n$ ../../electron/script/git-import-patches -3 ../../electron/patches/node\nIf git-import-patches -3 encounters a merge conflict that it can't resolve automatically, it will pause and allow you to resolve the conflict manually. Once you have resolved the conflict, git add the resolved files and continue to apply the rest of the patches by running git am --continue.
Developers frequently ask about strategies to optimize the performance of\nElectron applications. Software engineers, consumers, and framework developers\ndo not always agree on one single definition of what \"performance\" means. This\ndocument outlines some of the Electron maintainers' favorite ways to reduce the\namount of memory, CPU, and disk resources being used while ensuring that your\napp is responsive to user input and completes operations as quickly as\npossible. Furthermore, we want all performance strategies to maintain a high\nstandard for your app's security.
\nWisdom and information about how to build performant websites with JavaScript\ngenerally applies to Electron apps, too. To a certain extent, resources\ndiscussing how to build performant Node.js applications also apply, but be\ncareful to understand that the term \"performance\" means different things for\na Node.js backend than it does for an application running on a client.
\nThis list is provided for your convenience – and is, much like our\nsecurity checklist – not meant to exhaustive. It is probably possible\nto build a slow Electron app that follows all the steps outlined below. Electron\nis a powerful development platform that enables you, the developer, to do more\nor less whatever you want. All that freedom means that performance is largely\nyour responsibility.
\nThe list below contains a number of steps that are fairly straightforward and\neasy to implement. However, building the most performant version of your app\nwill require you to go beyond a number of steps. Instead, you will have to\nclosely examine all the code running in your app by carefully profiling and\nmeasuring. Where are the bottlenecks? When the user clicks a button, what\noperations take up the brunt of the time? While the app is simply idling, which\nobjects take up the most memory?
\nTime and time again, we have seen that the most successful strategy for building\na performant Electron app is to profile the running code, find the most\nresource-hungry piece of it, and to optimize it. Repeating this seemingly\nlaborious process over and over again will dramatically increase your app's\nperformance. Experience from working with major apps like Visual Studio Code or\nSlack has shown that this practice is by far the most reliable strategy to\nimprove performance.
\nTo learn more about how to profile your app's code, familiarize yourself with\nthe Chrome Developer Tools. For advanced analysis looking at multiple processes\nat once, consider the Chrome Tracing tool.
\nChances are that your app could be a little leaner, faster, and generally less\nresource-hungry if you attempt these steps.
\nBefore adding a Node.js module to your application, examine said module. How\nmany dependencies does that module include? What kind of resources does\nit need to simply be called in a require() statement? You might find\nthat the module with the most downloads on the NPM package registry or the most stars on GitHub\nis not in fact the leanest or smallest one available.
The reasoning behind this recommendation is best illustrated with a real-world\nexample. During the early days of Electron, reliable detection of network\nconnectivity was a problem, resulting many apps to use a module that exposed a\nsimple isOnline() method.
That module detected your network connectivity by attempting to reach out to a\nnumber of well-known endpoints. For the list of those endpoints, it depended on\na different module, which also contained a list of well-known ports. This\ndependency itself relied on a module containing information about ports, which\ncame in the form of a JSON file with more than 100,000 lines of content.\nWhenever the module was loaded (usually in a require('module') statement),\nit would load all its dependencies and eventually read and parse this JSON\nfile. Parsing many thousands lines of JSON is a very expensive operation. On\na slow machine it can take up whole seconds of time.
In many server contexts, startup time is virtually irrelevant. A Node.js server\nthat requires information about all ports is likely actually \"more performant\"\nif it loads all required information into memory whenever the server boots at\nthe benefit of serving requests faster. The module discussed in this example is\nnot a \"bad\" module. Electron apps, however, should not be loading, parsing, and\nstoring in memory information that it does not actually need.
\nIn short, a seemingly excellent module written primarily for Node.js servers\nrunning Linux might be bad news for your app's performance. In this particular\nexample, the correct solution was to use no module at all, and to instead use\nconnectivity checks included in later versions of Chromium.
\nWhen considering a module, we recommend that you check:
\nrequire()) itGenerating a CPU profile and a heap memory profile for loading a module can be done\nwith a single command on the command line. In the example below, we're looking at\nthe popular module request.
node --cpu-prof --heap-prof -e \"require('request')\"\nExecuting this command results in a .cpuprofile file and a .heapprofile\nfile in the directory you executed it in. Both files can be analyzed using\nthe Chrome Developer Tools, using the Performance and Memory tabs\nrespectively.
![\"Performance](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/performance-cpu-prof.png\")
![\"Performance](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/performance-heap-prof.png\")
In this example, on the author's machine, we saw that loading request took\nalmost half a second, whereas node-fetch took dramatically less memory\nand less than 50ms.
If you have expensive setup operations, consider deferring those. Inspect all\nthe work being executed right after the application starts. Instead of firing\noff all operations right away, consider staggering them in a sequence more\nclosely aligned with the user's journey.
\nIn traditional Node.js development, we're used to putting all our require()\nstatements at the top. If you're currently writing your Electron application\nusing the same strategy and are using sizable modules that you do not\nimmediately need, apply the same strategy and defer loading to a more\nopportune time.
Loading modules is a surprisingly expensive operation, especially on Windows.\nWhen your app starts, it should not make users wait for operations that are\ncurrently not necessary.
\nThis might seem obvious, but many applications tend to do a large amount of\nwork immediately after the app has launched - like checking for updates,\ndownloading content used in a later flow, or performing heavy disk I/O\noperations.
\nLet's consider Visual Studio Code as an example. When you open a file, it will\nimmediately display the file to you without any code highlighting, prioritizing\nyour ability to interact with the text. Once it has done that work, it will\nmove on to code highlighting.
\nLet's consider an example and assume that your application is parsing files\nin the fictitious .foo format. In order to do that, it relies on the\nequally fictitious foo-parser module. In traditional Node.js development,\nyou might write code that eagerly loads dependencies:
const fs = require('fs')\nconst fooParser = require('foo-parser')\n\nclass Parser {\n constructor () {\n this.files = fs.readdirSync('.')\n }\n\n getParsedFiles () {\n return fooParser.parse(this.files)\n }\n}\n\nconst parser = new Parser()\n\nmodule.exports = { parser }\nIn the above example, we're doing a lot of work that's being executed as soon\nas the file is loaded. Do we need to get parsed files right away? Could we\ndo this work a little later, when getParsedFiles() is actually called?
// \"fs\" is likely already being loaded, so the `require()` call is cheap\nconst fs = require('fs')\n\nclass Parser {\n async getFiles () {\n // Touch the disk as soon as `getFiles` is called, not sooner.\n // Also, ensure that we're not blocking other operations by using\n // the asynchronous version.\n this.files = this.files || await fs.readdir('.')\n\n return this.files\n }\n\n async getParsedFiles () {\n // Our fictitious foo-parser is a big and expensive module to load, so\n // defer that work until we actually need to parse files.\n // Since `require()` comes with a module cache, the `require()` call\n // will only be expensive once - subsequent calls of `getParsedFiles()`\n // will be faster.\n const fooParser = require('foo-parser')\n const files = await this.getFiles()\n\n return fooParser.parse(files)\n }\n}\n\n// This operation is now a lot cheaper than in our previous example\nconst parser = new Parser()\n\nmodule.exports = { parser }\nIn short, allocate resources \"just in time\" rather than allocating them all\nwhen your app starts.
\nElectron's main process (sometimes called \"browser process\") is special: It is\nthe parent process to all your app's other processes and the primary process\nthe operating system interacts with. It handles windows, interactions, and the\ncommunication between various components inside your app. It also houses the\nUI thread.
\nUnder no circumstances should you block this process and the UI thread with\nlong-running operations. Blocking the UI thread means that your entire app\nwill freeze until the main process is ready to continue processing.
\nThe main process and its UI thread are essentially the control tower for major\noperations inside your app. When the operating system tells your app about a\nmouse click, it'll go through the main process before it reaches your window.\nIf your window is rendering a buttery-smooth animation, it'll need to talk to\nthe GPU process about that – once again going through the main process.
\nElectron and Chromium are careful to put heavy disk I/O and CPU-bound operations\nonto new threads to avoid blocking the UI thread. You should do the same.
\nElectron's powerful multi-process architecture stands ready to assist you with\nyour long-running tasks, but also includes a small number of performance traps.
\n1) For long running CPU-heavy tasks, make use of\nworker threads, consider moving them to the BrowserWindow, or\n(as a last resort) spawn a dedicated process.
\n2) Avoid using the synchronous IPC and the remote module as much as possible.\nWhile there are legitimate use cases, it is far too easy to unknowingly block\nthe UI thread using the remote module.
3) Avoid using blocking I/O operations in the main process. In short, whenever\ncore Node.js modules (like fs or child_process) offer a synchronous or an\nasynchronous version, you should prefer the asynchronous and non-blocking\nvariant.
Since Electron ships with a current version of Chrome, you can make use of the\nlatest and greatest features the Web Platform offers to defer or offload heavy\noperations in a way that keeps your app smooth and responsive.
\nYour app probably has a lot of JavaScript to run in the renderer process. The\ntrick is to execute operations as quickly as possible without taking away\nresources needed to keep scrolling smooth, respond to user input, or animations\nat 60fps.
\nOrchestrating the flow of operations in your renderer's code is\nparticularly useful if users complain about your app sometimes \"stuttering\".
\nGenerally speaking, all advice for building performant web apps for modern\nbrowsers apply to Electron's renderers, too. The two primary tools at your\ndisposal are currently requestIdleCallback() for small operations and\nWeb Workers for long-running operations.
requestIdleCallback() allows developers to queue up a function to be\nexecuted as soon as the process is entering an idle period. It enables you to\nperform low-priority or background work without impacting the user experience.\nFor more information about how to use it,\ncheck out its documentation on MDN.
Web Workers are a powerful tool to run code on a separate thread. There are\nsome caveats to consider – consult Electron's\nmultithreading documentation and the\nMDN documentation for Web Workers. They're an ideal solution\nfor any operation that requires a lot of CPU power for an extended period of\ntime.
\nOne of Electron's great benefits is that you know exactly which engine will\nparse your JavaScript, HTML, and CSS. If you're re-purposing code that was\nwritten for the web at large, make sure to not polyfill features included in\nElectron.
\nWhen building a web application for today's Internet, the oldest environments\ndictate what features you can and cannot use. Even though Electron supports\nwell-performing CSS filters and animations, an older browser might not. Where\nyou could use WebGL, your developers may have chosen a more resource-hungry\nsolution to support older phones.
\nWhen it comes to JavaScript, you may have included toolkit libraries like\njQuery for DOM selectors or polyfills like the regenerator-runtime to support\nasync/await.
It is rare for a JavaScript-based polyfill to be faster than the equivalent\nnative feature in Electron. Do not slow down your Electron app by shipping your\nown version of standard web platform features.
\nOperate under the assumption that polyfills in current versions of Electron\nare unnecessary. If you have doubts, check caniuse.com\nand check if the version of Chromium used in your Electron version\nsupports the feature you desire.
\nIn addition, carefully examine the libraries you use. Are they really necessary?\njQuery, for example, was such a success that many of its features are now part\nof the standard JavaScript feature set available.
If you're using a transpiler/compiler like TypeScript, examine its configuration\nand ensure that you're targeting the latest ECMAScript version supported by\nElectron.
\nAvoid fetching rarely changing resources from the internet if they could easily\nbe bundled with your application.
\nMany users of Electron start with an entirely web-based app that they're\nturning into a desktop application. As web developers, we are used to loading\nresources from a variety of content delivery networks. Now that you are\nshipping a proper desktop application, attempt to \"cut the cord\" where possible\nand avoid letting your users wait for resources that never change and could\neasily be included in your app.
\nA typical example is Google Fonts. Many developers make use of Google's\nimpressive collection of free fonts, which comes with a content delivery\nnetwork. The pitch is straightforward: Include a few lines of CSS and Google\nwill take care of the rest.
\nWhen building an Electron app, your users are better served if you download\nthe fonts and include them in your app's bundle.
\nIn an ideal world, your application wouldn't need the network to operate at\nall. To get there, you must understand what resources your app is downloading\n- and how large those resources are.
\nTo do so, open up the developer tools. Navigate to the Network tab and check\nthe Disable cache option. Then, reload your renderer. Unless your app\nprohibits such reloads, you can usually trigger a reload by hitting Cmd + R\nor Ctrl + R with the developer tools in focus.
The tools will now meticulously record all network requests. In a first pass,\ntake stock of all the resources being downloaded, focusing on the larger files\nfirst. Are any of them images, fonts, or media files that don't change and\ncould be included with your bundle? If so, include them.
\nAs a next step, enable Network Throttling. Find the drop-down that currently\nreads Online and select a slower speed such as Fast 3G. Reload your\nrenderer and see if there are any resources that your app is unnecessarily\nwaiting for. In many cases, an app will wait for a network request to complete\ndespite not actually needing the involved resource.
As a tip, loading resources from the Internet that you might want to change\nwithout shipping an application update is a powerful strategy. For advanced\ncontrol over how resources are being loaded, consider investing in\nService Workers.
\nAs already pointed out in\n\"Loading and running code too soon\",\ncalling require() is an expensive operation. If you are able to do so,\nbundle your application's code into a single file.
Modern JavaScript development usually involves many files and modules. While\nthat's perfectly fine for developing with Electron, we heavily recommend that\nyou bundle all your code into one single file to ensure that the overhead\nincluded in calling require() is only paid once when your application loads.
There are numerous JavaScript bundlers out there and we know better than to\nanger the community by recommending one tool over another. We do however\nrecommend that you use a bundler that is able to handle Electron's unique\nenvironment that needs to handle both Node.js and browser environments.
\nAs of writing this article, the popular choices include Webpack,\nParcel, and rollup.js.
", "title": "Performance", "description": "" }, "/docs/api/structures/point": { "locale": "en-US", "slug": "point", "href": "/docs/api/structures/point", "crowdinFileId": "256475", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/point.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "x Numbery NumberNote: Both x and y must be whole integers, when providing a point object\nas input to an Electron API we will automatically round your x and y values\nto the nearest whole integer.
data (UploadRawData | UploadFile)[] - The post data to be sent to the\nnew window.contentType String - The content-type header used for the data. One of\napplication/x-www-form-urlencoded or multipart/form-data. Corresponds to\nthe enctype attribute of the submitted HTML form.boundary String (optional) - The boundary used to separate multiple parts of\nthe message. Only valid when contentType is multipart/form-data.Note that keys starting with -- are not currently supported. For example, this will errantly submit as multipart/form-data when nativeWindowOpen is set to false in webPreferences:
<form\n target=\"_blank\"\n method=\"POST\"\n enctype=\"application/x-www-form-urlencoded\"\n action=\"https://postman-echo.com/post\"\n>\n <input type=\"text\" name=\"--theKey\">\n <input type=\"submit\">\n</form>\n\n\nMonitor power state changes.
\n
Process: Main
\nThe powerMonitor module emits the following events:
Emitted when the system is suspending.
\nEmitted when system is resuming.
\nEmitted when the system changes to AC power.
\nEmitted when system changes to battery power.
\nEmitted when the system is about to reboot or shut down. If the event handler\ninvokes e.preventDefault(), Electron will attempt to delay system shutdown in\norder for the app to exit cleanly. If e.preventDefault() is called, the app\nshould exit as soon as possible by calling something like app.quit().
Emitted when the system is about to lock the screen.
\nEmitted as soon as the systems screen is unlocked.
\nEmitted when a login session is activated. See documentation for more information.
\nEmitted when a login session is deactivated. See documentation for more information.
\nThe powerMonitor module has the following methods:
powerMonitor.getSystemIdleState(idleThreshold)idleThreshold IntegerReturns String - The system's current state. Can be active, idle, locked or unknown.
Calculate the system idle state. idleThreshold is the amount of time (in seconds)\nbefore considered idle. locked is available on supported systems only.
powerMonitor.getSystemIdleTime()Returns Integer - Idle time in seconds
Calculate system idle time in seconds.
\npowerMonitor.isOnBatteryPower()Returns Boolean - Whether the system is on battery power.
To monitor for changes in this property, use the on-battery and on-ac\nevents.
powerMonitor.onBatteryPowerA Boolean property. True if the system is on battery power.
See powerMonitor.isOnBatteryPower().
\n\nBlock the system from entering low-power (sleep) mode.
\n
Process: Main
\nFor example:
\nconst { powerSaveBlocker } = require('electron')\n\nconst id = powerSaveBlocker.start('prevent-display-sleep')\nconsole.log(powerSaveBlocker.isStarted(id))\n\npowerSaveBlocker.stop(id)\nThe powerSaveBlocker module has the following methods:
powerSaveBlocker.start(type)type String - Power save blocker type.prevent-app-suspension - Prevent the application from being suspended.\nKeeps system active but allows screen to be turned off. Example use cases:\ndownloading a file or playing audio.prevent-display-sleep - Prevent the display from going to sleep. Keeps\nsystem and screen active. Example use case: playing video.Returns Integer - The blocker ID that is assigned to this power blocker.
Starts preventing the system from entering lower-power mode. Returns an integer\nidentifying the power save blocker.
\nNote: prevent-display-sleep has higher precedence over\nprevent-app-suspension. Only the highest precedence type takes effect. In\nother words, prevent-display-sleep always takes precedence over\nprevent-app-suspension.
For example, an API calling A requests for prevent-app-suspension, and\nanother calling B requests for prevent-display-sleep. prevent-display-sleep\nwill be used until B stops its request. After that, prevent-app-suspension\nis used.
powerSaveBlocker.stop(id)id Integer - The power save blocker id returned by powerSaveBlocker.start.Stops the specified power save blocker.
\npowerSaveBlocker.isStarted(id)id Integer - The power save blocker id returned by powerSaveBlocker.start.Returns Boolean - Whether the corresponding powerSaveBlocker has started.
name String - the name of the printer as understood by the OS.displayName String - the name of the printer as shown in Print Preview.description String - a longer description of the printer's type.status Number - the current status of the printer.isDefault Boolean - whether or not a given printer is set as the default printer on the OS.options Object - an object containing a variable number of platform-specific printer information.The number represented by status means different things on different platforms: on Windows its potential values can be found here, and on Linux and macOS they can be found here.
Below is an example of some of the additional options that may be set which\nmay be different on each platform.
\n{\n name: 'Austin_4th_Floor_Printer___C02XK13BJHD4',\n displayName: 'Austin 4th Floor Printer @ C02XK13BJHD4',\n description: 'TOSHIBA ColorMFP',\n status: 3,\n isDefault: false,\n options: {\n copies: '1',\n 'device-uri': 'dnssd://Austin%204th%20Floor%20Printer%20%40%20C02XK13BJHD4._ipps._tcp.local./?uuid=71687f1e-1147-3274-6674-22de61b110bd',\n finishings: '3',\n 'job-cancel-after': '10800',\n 'job-hold-until': 'no-hold',\n 'job-priority': '50',\n 'job-sheets': 'none,none',\n 'marker-change-time': '0',\n 'number-up': '1',\n 'printer-commands': 'ReportLevels,PrintSelfTestPage,com.toshiba.ColourProfiles.update,com.toshiba.EFiling.update,com.toshiba.EFiling.checkPassword',\n 'printer-info': 'Austin 4th Floor Printer @ C02XK13BJHD4',\n 'printer-is-accepting-jobs': 'true',\n 'printer-is-shared': 'false',\n 'printer-is-temporary': 'false',\n 'printer-location': '',\n 'printer-make-and-model': 'TOSHIBA ColorMFP',\n 'printer-state': '3',\n 'printer-state-change-time': '1573472937',\n 'printer-state-reasons': 'offline-report,com.toshiba.snmp.failed',\n 'printer-type': '10531038',\n 'printer-uri-supported': 'ipp://localhost/printers/Austin_4th_Floor_Printer___C02XK13BJHD4',\n system_driverinfo: 'T'\n }\n}\n\n\n\nExtensions to process object.
\n
Electron's process object is extended from the\nNode.js process object.\nIt adds the following events, properties, and methods:
In sandboxed renderers the process object contains only a subset of the APIs:
crash()hang()getCreationTime()getHeapStatistics()getBlinkMemoryInfo()getProcessMemoryInfo()getSystemMemoryInfo()getSystemVersion()getCPUUsage()getIOCounters()uptime()argvexecPathenvpidarchplatformsandboxedcontextIsolatedtypeversionversionsmaswindowsStorecontextIdEmitted when Electron has loaded its internal initialization script and is\nbeginning to load the web page or the main script.
\nprocess.defaultApp ReadonlyA Boolean. When app is started by being passed as parameter to the default app, this\nproperty is true in the main process, otherwise it is undefined.
process.isMainFrame ReadonlyA Boolean, true when the current renderer context is the \"main\" renderer\nframe. If you want the ID of the current frame you should use webFrame.routingId.
process.mas ReadonlyA Boolean. For Mac App Store build, this property is true, for other builds it is\nundefined.
process.noAsarA Boolean that controls ASAR support inside your application. Setting this to true\nwill disable the support for asar archives in Node's built-in modules.
process.noDeprecationA Boolean that controls whether or not deprecation warnings are printed to stderr.\nSetting this to true will silence deprecation warnings. This property is used\ninstead of the --no-deprecation command line flag.
process.resourcesPath ReadonlyA String representing the path to the resources directory.
process.sandboxed ReadonlyA Boolean. When the renderer process is sandboxed, this property is true,\notherwise it is undefined.
process.contextIsolated ReadonlyA Boolean that indicates whether the current renderer context has contextIsolation enabled.\nIt is undefined in the main process.
process.throwDeprecationA Boolean that controls whether or not deprecation warnings will be thrown as\nexceptions. Setting this to true will throw errors for deprecations. This\nproperty is used instead of the --throw-deprecation command line flag.
process.traceDeprecationA Boolean that controls whether or not deprecations printed to stderr include\ntheir stack trace. Setting this to true will print stack traces for deprecations.\nThis property is instead of the --trace-deprecation command line flag.
process.traceProcessWarningsA Boolean that controls whether or not process warnings printed to stderr include\ntheir stack trace. Setting this to true will print stack traces for process warnings\n(including deprecations). This property is instead of the --trace-warnings command\nline flag.
process.type ReadonlyA String representing the current process's type, can be:
browser - The main processrenderer - A renderer processworker - In a web workerprocess.versions.chrome ReadonlyA String representing Chrome's version string.
process.versions.electron ReadonlyA String representing Electron's version string.
process.windowsStore ReadonlyA Boolean. If the app is running as a Windows Store app (appx), this property is true,\nfor otherwise it is undefined.
process.contextId ReadonlyA String (optional) representing a globally unique ID of the current JavaScript context.\nEach frame has its own JavaScript context. When contextIsolation is enabled, the isolated\nworld also has a separate JavaScript context.\nThis property is only available in the renderer process.
The process object has the following methods:
process.crash()Causes the main thread of the current process crash.
\nprocess.getCreationTime()Returns Number | null - The number of milliseconds since epoch, or null if the information is unavailable
Indicates the creation time of the application.\nThe time is represented as number of milliseconds since epoch. It returns null if it is unable to get the process creation time.
\nprocess.getCPUUsage()Returns CPUUsage
process.getIOCounters() Windows LinuxReturns IOCounters
process.getHeapStatistics()Returns Object:
totalHeapSize IntegertotalHeapSizeExecutable IntegertotalPhysicalSize IntegertotalAvailableSize IntegerusedHeapSize IntegerheapSizeLimit IntegermallocedMemory IntegerpeakMallocedMemory IntegerdoesZapGarbage BooleanReturns an object with V8 heap statistics. Note that all statistics are reported in Kilobytes.
\nprocess.getBlinkMemoryInfo()Returns Object:
allocated Integer - Size of all allocated objects in Kilobytes.marked Integer - Size of all marked objects in Kilobytes.total Integer - Total allocated space in Kilobytes.Returns an object with Blink memory information.\nIt can be useful for debugging rendering / DOM related memory issues.\nNote that all values are reported in Kilobytes.
\nprocess.getProcessMemoryInfo()Returns Promise<ProcessMemoryInfo> - Resolves with a ProcessMemoryInfo
Returns an object giving memory usage statistics about the current process. Note\nthat all statistics are reported in Kilobytes.\nThis api should be called after app ready.
\nChromium does not provide residentSet value for macOS. This is because macOS\nperforms in-memory compression of pages that haven't been recently used. As a\nresult the resident set size value is not what one would expect. private memory\nis more representative of the actual pre-compression memory usage of the process\non macOS.
process.getSystemMemoryInfo()Returns Object:
total Integer - The total amount of physical memory in Kilobytes available to the\nsystem.free Integer - The total amount of memory not being used by applications or disk\ncache.swapTotal Integer Windows Linux - The total amount of swap memory in Kilobytes available to the\nsystem.swapFree Integer Windows Linux - The free amount of swap memory in Kilobytes available to the\nsystem.Returns an object giving memory usage statistics about the entire system. Note\nthat all statistics are reported in Kilobytes.
\nprocess.getSystemVersion()Returns String - The version of the host operating system.
Example:
\nconst version = process.getSystemVersion()\nconsole.log(version)\n// On macOS -> '10.13.6'\n// On Windows -> '10.0.17763'\n// On Linux -> '4.15.0-45-generic'\nNote: It returns the actual operating system version instead of kernel version on macOS unlike os.release().
process.takeHeapSnapshot(filePath)filePath String - Path to the output file.Returns Boolean - Indicates whether the snapshot has been created successfully.
Takes a V8 heap snapshot and saves it to filePath.
process.hang()Causes the main thread of the current process hang.
\nprocess.setFdLimit(maxDescriptors) macOS LinuxmaxDescriptors IntegerSets the file descriptor soft limit to maxDescriptors or the OS hard\nlimit, whichever is lower for the current process.
residentSet Integer Linux Windows - The amount of memory\ncurrently pinned to actual physical RAM in Kilobytes.private Integer - The amount of memory not shared by other processes, such as JS heap or HTML content in Kilobytes.shared Integer - The amount of memory shared between processes, typically\nmemory consumed by the Electron code itself in Kilobytes.pid Integer - Process id of the process.type String - Process type. One of the following values:BrowserTabUtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownserviceName String (optional) - The non-localized name of the process.name String (optional) - The name of the process.\nExamples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.cpu CPUUsage - CPU usage of the process.creationTime Number - Creation time for this process.\nThe time is represented as number of milliseconds since epoch.\nSince the pid can be reused after a process dies,\nit is useful to use both the pid and the creationTime to uniquely identify a process.memory MemoryInfo - Memory information for the process.sandboxed Boolean (optional) macOS Windows - Whether the process is sandboxed on OS level.integrityLevel String (optional) Windows - One of the following values:untrustedlowmediumhighunknownElectron inherits its multi-process architecture from Chromium, which makes the framework\narchitecturally very similar to a modern web browser. In this guide, we'll expound on\nthe conceptual knowledge of Electron that we applied in the minimal quick start app.
\nWeb browsers are incredibly complicated applications. Aside from their primary ability\nto display web content, they have many secondary responsibilities,\nsuch as managing multiple windows (or tabs) and loading third-party extensions.
\nIn the earlier days, browsers usually used a single process for all of this\nfunctionality. Although this pattern meant less overhead for each tab you had open,\nit also meant that one website crashing or hanging would affect the entire browser.
\nTo solve this problem, the Chrome team decided that each tab would render in its own\nprocess, limiting the harm that buggy or malicious code on a web page could cause to\nthe app as a whole. A single browser process then controls these processes, as well\nas the application lifecycle as a whole. This diagram below from the Chrome Comic\nvisualizes this model:
\n![\"Chrome's](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/chrome-processes.png\")
Electron applications are structured very similarly. As an app developer, you control\ntwo types of processes: main and renderer. These are analogous to Chrome's own browser\nand renderer processes outlined above.
\nEach Electron app has a single main process, which acts as the application's entry\npoint. The main process runs in a Node.js environment, meaning it has the ability\nto require modules and use all of Node.js APIs.
The main process' primary purpose is to create and manage application windows with the\nBrowserWindow module.
Each instance of the BrowserWindow class creates an application window that loads\na web page in a separate renderer process. You can interact with this web content\nfrom the main process using the window's webContents object.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\n\n\nNote: A renderer process is also created for web embeds such as the\n
\nBrowserViewmodule. ThewebContentsobject is also accessible for embedded\nweb content.
Because the BrowserWindow module is an EventEmitter, you can also\nadd handlers for various user events (for example, minimizing or maximizing your window).
When a BrowserWindow instance is destroyed, its corresponding renderer process gets\nterminated as well.
The main process also controls your application's lifecycle through Electron's\napp module. This module provides a large set of events and methods\nthat you can use to add custom application behaviour (for instance, programatically\nquitting your application, modifying the application dock, or showing an About panel).
As a practical example, the app shown in the quick start guide\nuses app APIs to create a more native application window experience.
// quitting the app when no windows are open on non-macOS platforms\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nTo extend Electron's features beyond being a Chromium wrapper for web contents, the\nmain process also adds custom APIs to interact with the user's operating system.\nElectron exposes various modules that control native desktop functionality, such\nas menus, dialogs, and tray icons.
\nFor a full list of Electron's main process modules, check out our API documentation.
\nEach Electron app spawns a separate renderer process for each open BrowserWindow\n(and each web embed). As its name implies, a renderer is responsible for\nrendering web content. For all intents and purposes, code ran in renderer processes\nshould behave according to web standards (insofar as Chromium does, at least).
Therefore, all user interfaces and app functionality within a single browser\nwindow should be written with the same tools and paradigms that you use on the\nweb.
\nAlthough explaining every web spec is out of scope for this guide, the bare minimum\nto understand is:
\n<script> elements.Moreover, this also means that the renderer has no direct access to require\nor other Node.js APIs. In order to directly include NPM modules in the renderer,\nyou must use the same bundler toolchains (for example, webpack or parcel) that you\nuse on the web.
\n\nNote: Renderer processes can be spawned with a full Node.js environment for ease of\ndevelopment. Historically, this used to be the default, but this feature was disabled\nfor security reasons.
\n
At this point, you might be wondering how your renderer process user interfaces\ncan interact with Node.js and Electron's native desktop functionality if these\nfeatures are only accessible from the main process. In fact, there is no direct\nway to import Electron's content scripts.
\nPreload scripts contain code that executes in a renderer process before its web content\nbegins loading. These scripts run within the renderer context, but are granted more\nprivileges by having access to Node.js APIs.
\nA preload script can be attached to the main process in the BrowserWindow constructor's\nwebPreferences option.
const { BrowserWindow } = require('electron')\n//...\nconst win = new BrowserWindow({\n webPreferences: {\n preload: 'path/to/preload.js'\n }\n})\n//...\nBecause the preload script shares a global Window interface with the\nrenderers and can access Node.js APIs, it serves to enhance your renderer by exposing\narbitrary APIs in the window global that your web contents can then consume.
Although preload scripts share a window global with the renderer they're attached to,\nyou cannot directly attach any variables from the preload script to window because of\nthe contextIsolation default.
window.myAPI = {\n desktop: true\n}\nconsole.log(window.myAPI)\n// => undefined\nContext Isolation means that preload scripts are isolated from the renderer's main world\nto avoid leaking any privileged APIs into your web content's code.
\nInstead, use the contextBridge module to accomplish this\nsecurely:
const { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n desktop: true\n})\nconsole.log(window.myAPI)\n// => { desktop: true }\nThis feature is incredibly useful for two main purposes:
\nipcRenderer helpers to the renderer, you can use\ninter-process communication (IPC) to trigger main process tasks from the\nrenderer (and vice-versa).window global that can\nbe used for desktop-only logic on the web client's side.productIdentifier String - The string that identifies the product to the Apple App Store.localizedDescription String - A description of the product.localizedTitle String - The name of the product.contentVersion String - A string that identifies the version of the content.contentLengths Number[] - The total size of the content, in bytes.price Number - The cost of the product in the local currency.formattedPrice String - The locale formatted price of the product.currencyCode String - 3 character code presenting a product's currency based on the ISO 4217 standard.isDownloadable Boolean - A Boolean value that indicates whether the App Store has downloadable content for this product. true if at least one file has been associated with the product.A progress bar enables a window to provide progress information to the user\nwithout the need of switching to the window itself.
\nOn Windows, you can use a taskbar button to display a progress bar.
\n![Windows Progress Bar][https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png]
\nOn macOS, the progress bar will be displayed as a part of the dock icon.
\n![\"macOS](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/macos-progress-bar.png\")
On Linux, the Unity graphical interface also has a similar feature that allows\nyou to specify the progress bar in the launcher.
\n![\"Linux](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/linux-progress-bar.png\")
\n\nNOTE: on Windows, each window can have its own progress bar, whereas on macOS\nand Linux (Unity) there can be only one progress bar for the application.
\n
All three cases are covered by the same API - the\nsetProgressBar() method available on an instance of\nBrowserWindow. To indicate your progress, call this method with a number\nbetween 0 and 1. For example, if you have a long-running task that is\ncurrently at 63% towards completion, you would call it as\nsetProgressBar(0.63).
Setting the parameter to negative values (e.g. -1) will remove the progress\nbar. Setting it to a value greater than 1 will indicate an indeterminate progress bar\nin Windows or clamp to 100% in other operating systems. An indeterminate progress bar\nremains active but does not show an actual percentage, and is used for situations when\nyou do not know how long an operation will take to complete.
See the API documentation for more options and modes.
\nIn this example, we add a progress bar to the main window that increments over time\nusing Node.js timers.
\nconst { app, BrowserWindow } = require('electron')\n\nlet progressInterval\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n\n const INCREMENT = 0.03\n const INTERVAL_DELAY = 100 // ms\n\n let c = 0\n progressInterval = setInterval(() => {\n // update progress bar to next value\n // values between 0 and 1 will show progress, >1 will show indeterminate or stick at 100%\n win.setProgressBar(c)\n\n // increment or reset progress bar\n if (c < 2) c += INCREMENT\n else c = 0\n }, INTERVAL_DELAY)\n}\n\napp.whenReady().then(createWindow)\n\n// before the app is terminated, clear both timers\napp.on('before-quit', () => {\n clearInterval(progressInterval)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nAfter launching the Electron application, the dock (macOS) or taskbar (Windows, Unity)\nshould show a progress bar that starts at zero and progresses through 100% to completion.\nIt should then show indeterminate (Windows) or pin to 100% (other operating systems)\nbriefly and then loop.
\n![\"macOS](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/dock-progress-bar.png\")
For macOS, the progress bar will also be indicated for your application\nwhen using Mission Control:
\n![\"Mission](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/mission-control-progress-bar.png\")
\n\nRegister a custom protocol and intercept existing protocol requests.
\n
Process: Main
\nAn example of implementing a protocol that has the same effect as the\nfile:// protocol:
const { app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n})\nNote: All methods unless specified can only be used after the ready event\nof the app module gets emitted.
protocol with a custom partition or sessionA protocol is registered to a specific Electron session\nobject. If you don't specify a session, then your protocol will be applied to\nthe default session that Electron uses. However, if you define a partition or\nsession on your browserWindow's webPreferences, then that window will use\na different session and your custom protocol will not work if you just use\nelectron.protocol.XXX.
To have your custom protocol work in combination with a custom session, you need\nto register it to that session explicitly.
\nconst { session, app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const partition = 'persist:example'\n const ses = session.fromPartition(partition)\n\n ses.protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n\n mainWindow = new BrowserWindow({ webPreferences: { partition } })\n})\nThe protocol module has the following methods:
protocol.registerSchemesAsPrivileged(customSchemes)customSchemes CustomScheme[]Note: This method can only be used before the ready event of the app\nmodule gets emitted and can be called only once.
Registers the scheme as standard, secure, bypasses content security policy for\nresources, allows registering ServiceWorker, supports fetch API, and streaming\nvideo/audio. Specify a privilege with the value of true to enable the capability.
An example of registering a privileged scheme, that bypasses Content Security\nPolicy:
\nconst { protocol } = require('electron')\nprotocol.registerSchemesAsPrivileged([\n { scheme: 'foo', privileges: { bypassCSP: true } }\n])\nA standard scheme adheres to what RFC 3986 calls generic URI\nsyntax. For example http and\nhttps are standard schemes, while file is not.
Registering a scheme as standard allows relative and absolute resources to\nbe resolved correctly when served. Otherwise the scheme will behave like the\nfile protocol, but without the ability to resolve relative URLs.
For example when you load following page with custom protocol without\nregistering it as standard scheme, the image will not be loaded because\nnon-standard schemes can not recognize relative URLs:
\n<body>\n <img src='test.png'>\n</body>\nRegistering a scheme as standard will allow access to files through the\nFileSystem API. Otherwise the renderer will throw a security\nerror for the scheme.
\nBy default web storage apis (localStorage, sessionStorage, webSQL, indexedDB,\ncookies) are disabled for non standard schemes. So in general if you want to\nregister a custom protocol to replace the http protocol, you have to register\nit as a standard scheme.
Protocols that use streams (http and stream protocols) should set stream: true.\nThe <video> and <audio> HTML elements expect protocols to buffer their\nresponses by default. The stream flag configures those elements to correctly\nexpect streaming responses.
protocol.registerFileProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a file as the response. The\nhandler will be called with request and callback where request is\nan incoming request for the scheme.
To handle the request, the callback should be called with either the file's\npath or an object that has a path property, e.g. callback(filePath) or\ncallback({ path: filePath }). The filePath must be an absolute path.
By default the scheme is treated like http:, which is parsed differently\nfrom protocols that follow the \"generic URI syntax\" like file:.
protocol.registerBufferProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a Buffer as a response.
The usage is the same with registerFileProtocol, except that the callback\nshould be called with either a Buffer object or an object that has the data\nproperty.
Example:
\nprotocol.registerBufferProtocol('atom', (request, callback) => {\n callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })\n})\nprotocol.registerStringProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a String as a response.
The usage is the same with registerFileProtocol, except that the callback\nshould be called with either a String or an object that has the data\nproperty.
protocol.registerHttpProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send an HTTP request as a response.
The usage is the same with registerFileProtocol, except that the callback\nshould be called with an object that has the url property.
protocol.registerStreamProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a stream as a response.
The usage is the same with registerFileProtocol, except that the\ncallback should be called with either a ReadableStream object or an object that\nhas the data property.
Example:
\nconst { protocol } = require('electron')\nconst { PassThrough } = require('stream')\n\nfunction createStream (text) {\n const rv = new PassThrough() // PassThrough is also a Readable stream\n rv.push(text)\n rv.push(null)\n return rv\n}\n\nprotocol.registerStreamProtocol('atom', (request, callback) => {\n callback({\n statusCode: 200,\n headers: {\n 'content-type': 'text/html'\n },\n data: createStream('<h5>Response</h5>')\n })\n})\nIt is possible to pass any object that implements the readable stream API (emits\ndata/end/error events). For example, here's how a file could be returned:
protocol.registerStreamProtocol('atom', (request, callback) => {\n callback(fs.createReadStream('index.html'))\n})\nprotocol.unregisterProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unregistered
Unregisters the custom protocol of scheme.
protocol.isProtocolRegistered(scheme)scheme StringReturns Boolean - Whether scheme is already registered.
protocol.interceptFileProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler\nwhich sends a file as a response.
protocol.interceptStringProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler\nwhich sends a String as a response.
protocol.interceptBufferProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler\nwhich sends a Buffer as a response.
protocol.interceptHttpProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler\nwhich sends a new HTTP request as a response.
protocol.interceptStreamProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Same as protocol.registerStreamProtocol, except that it replaces an existing\nprotocol handler.
protocol.uninterceptProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unintercepted
Remove the interceptor installed for scheme and restore its original handler.
protocol.isProtocolIntercepted(scheme)scheme StringReturns Boolean - Whether scheme is already intercepted.
url Stringreferrer Stringmethod StringuploadData UploadData[] (optional)headers Record<String, String>error Integer (optional) - When assigned, the request will fail with the\nerror number . For the available error numbers you can use, please see the\nnet error list.statusCode Number (optional) - The HTTP response code, default is 200.charset String (optional) - The charset of response body, default is\n\"utf-8\".mimeType String (optional) - The MIME type of response body, default is\n\"text/html\". Setting mimeType would implicitly set the content-type\nheader in response, but if content-type is already set in headers, the\nmimeType would be ignored.headers Record<string, string | string[]> (optional) - An object containing the response headers. The\nkeys must be String, and values must be either String or Array of String.data (Buffer | String | ReadableStream) (optional) - The response body. When\nreturning stream as response, this is a Node.js readable stream representing\nthe response body. When returning Buffer as response, this is a Buffer.\nWhen returning String as response, this is a String. This is ignored for\nother types of responses.path String (optional) - Path to the file which would be sent as response\nbody. This is only used for file responses.url String (optional) - Download the url and pipe the result as response\nbody. This is only used for URL responses.referrer String (optional) - The referrer URL. This is only used for file\nand URL responses.method String (optional) - The HTTP method. This is only used for file\nand URL responses.session Session (optional) - The session used for requesting URL, by default\nthe HTTP request will reuse the current session. Setting session to null\nwould use a random independent session. This is only used for URL responses.uploadData ProtocolResponseUploadData (optional) - The data used as upload data. This is only\nused for URL responses when method is \"POST\".contentType String - MIME type of the content.data String | Buffer - Content to be sent.Fork the project on GitHub and clone your fork\nlocally.
\n$ git clone git@github.com:username/electron.git\n$ cd electron\n$ git remote add upstream https://github.com/electron/electron.git\n$ git fetch upstream\nBuild steps and dependencies differ slightly depending on your operating system.\nSee these detailed guides on building Electron locally:
\n\nOnce you've built the project locally, you're ready to start making changes!
\nTo keep your development environment organized, create local branches to\nhold your work. These should be branched directly off of the main branch.
$ git checkout -b my-branch -t upstream/main\nMost pull requests opened against the electron/electron repository include\nchanges to either the C/C++ code in the shell/ folder,\nthe JavaScript code in the lib/ folder, the documentation in docs/api/\nor tests in the spec/ folder.
Please be sure to run npm run lint from time to time on any code changes\nto ensure that they follow the project's code style.
See coding style for\nmore information about best practice when modifying code in different parts of\nthe project.
\nIt is recommended to keep your changes grouped logically within individual\ncommits. Many contributors find it easier to review changes that are split\nacross multiple commits. There is no limit to the number of commits in a\npull request.
\n$ git add my/changed/files\n$ git commit\nNote that multiple commits often get squashed when they are landed.
\nA good commit message should describe what changed and why. The Electron project\nuses semantic commit messages to streamline\nthe release process.
\nBefore a pull request can be merged, it must have a pull request title with a semantic prefix.
\nExamples of commit messages with semantic prefixes:
\nfix: don't overwrite prevent_default if default wasn't preventedfeat: add app.isPackaged() methoddocs: app.isDefaultProtocolClient is now available on LinuxCommon prefixes:
\nOther things to keep in mind when writing a commit message:
\nA commit that has the text BREAKING CHANGE: at the beginning of its optional\nbody or footer section introduces a breaking API change (correlating with Major\nin semantic versioning). A breaking change can be part of commits of any type.\ne.g., a fix:, feat: & chore: types would all be valid, in addition to any\nother type.
See conventionalcommits.org for more details.
\nOnce you have committed your changes, it is a good idea to use git rebase\n(not git merge) to synchronize your work with the main repository.
$ git fetch upstream\n$ git rebase upstream/main\nThis ensures that your working branch has the latest changes from electron/electron\nmain.
Bug fixes and features should always come with tests. A\ntesting guide has been\nprovided to make the process easier. Looking at other tests to see how they\nshould be structured can also help.
\nBefore submitting your changes in a pull request, always run the full\ntest suite. To run the tests:
\n$ npm run test\nMake sure the linter does not report any issues and that all tests pass.\nPlease do not submit patches that fail either check.
\nIf you are updating tests and want to run a single spec to check it:
\n$ npm run test -match=menu\nThe above would only run spec modules matching menu, which is useful for\nanyone who's working on tests that would otherwise be at the very end of\nthe testing cycle.
Once your commits are ready to go -- with passing tests and linting --\nbegin the process of opening a pull request by pushing your working branch\nto your fork on GitHub.
\n$ git push origin my-branch\nFrom within GitHub, opening a new pull request will present you with a template\nthat should be filled out:
\n<!--\nThank you for your pull request. Please provide a description above and review\nthe requirements below.\n\nBug fixes and new features should include tests and possibly benchmarks.\n\nContributors guide: https://github.com/electron/electron/blob/main/CONTRIBUTING.md\n-->\nYou will probably get feedback or requests for changes to your pull request.\nThis is a big part of the submission process so don't be discouraged! Some\ncontributors may sign off on the pull request right away. Others may have\ndetailed comments or feedback. This is a necessary part of the process\nin order to evaluate whether the changes are correct and necessary.
\nTo make changes to an existing pull request, make the changes to your local\nbranch, add a new commit with those changes, and push those to your fork.\nGitHub will automatically update the pull request.
\n$ git add my/changed/files\n$ git commit\n$ git push origin my-branch\nThere are a number of more advanced mechanisms for managing commits using\ngit rebase that can be used, but are beyond the scope of this guide.
Feel free to post a comment in the pull request to ping reviewers if you are\nawaiting an answer on something. If you encounter words or acronyms that\nseem unfamiliar, refer to this\nglossary.
\nAll pull requests require approval from a\nCode Owner\nof the area you modified in order to land. Whenever a maintainer reviews a pull\nrequest they may request changes. These may be small, such as fixing a typo, or\nmay involve substantive changes. Such requests are intended to be helpful, but\nat times may come across as abrupt or unhelpful, especially if they do not include\nconcrete suggestions on how to change them.
\nTry not to be discouraged. If you feel that a review is unfair, say so or seek\nthe input of another project contributor. Often such comments are the result of\na reviewer having taken insufficient time to review and are not ill-intended.\nSuch difficulties can often be resolved with a bit of patience. That said,\nreviewers should be expected to provide helpful feedback.
\nIn order to land, a pull request needs to be reviewed and approved by\nat least one Electron Code Owner and pass CI. After that, if there are no\nobjections from other contributors, the pull request can be merged.
\nCongratulations and thanks for your contribution!
\nEvery pull request is tested on the Continuous Integration (CI) system to\nconfirm that it works on Electron's supported platforms.
\nIdeally, the pull request will pass (\"be green\") on all of CI's platforms.\nThis means that all tests pass and there are no linting errors. However,\nit is not uncommon for the CI infrastructure itself to fail on specific\nplatforms or for so-called \"flaky\" tests to fail (\"be red\"). Each CI\nfailure must be manually inspected to determine the cause.
\nCI starts automatically when you open a pull request, but only\ncore maintainers can restart a CI run. If you believe CI is giving a\nfalse negative, ask a maintainer to restart the tests.
", "title": "Pull Requests", "description": "" }, "/docs/tutorial/quick-start": { "locale": "en-US", "slug": "quick-start", "href": "/docs/tutorial/quick-start", "crowdinFileId": "256237", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/quick-start.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "This guide will step you through the process of creating a barebones Hello World app in\nElectron, similar to electron/electron-quick-start.
By the end of this tutorial, your app will open a browser window that displays a web page\nwith information about which Chromium, Node.js, and Electron versions are running.
\nTo use Electron, you need to install Node.js. We recommend that you\nuse the latest LTS version available.
\n\nPlease install Node.js using pre-built installers for your platform.\nYou may encounter incompatibility issues with different development tools otherwise.
\n
To check that Node.js was installed correctly, type the following commands in your\nterminal client:
\nnode -v\nnpm -v\nThe commands should print the versions of Node.js and npm accordingly.
\nNote: Since Electron embeds Node.js into its binary, the version of Node.js running\nyour code is unrelated to the version running on your system.
\nElectron apps follow the same general structure as other Node.js projects.\nStart by creating a folder and initializing an npm package.
\nmkdir my-electron-app && cd my-electron-app\nnpm init\nThe interactive init command will prompt you to set some fields in your config.\nThere are a few rules to follow for the purposes of this tutorial:
entry point should be main.js.author and description can be any value, but are necessary for\napp packaging.Your package.json file should look something like this:
{\n \"name\": \"my-electron-app\",\n \"version\": \"1.0.0\",\n \"description\": \"Hello World!\",\n \"main\": \"main.js\",\n \"author\": \"Jane Doe\",\n \"license\": \"MIT\"\n}\nThen, install the electron package into your app's devDependencies.
$ npm install --save-dev electron\n\n\nNote: If you're encountering any issues with installing Electron, please\nrefer to the Advanced Installation guide.
\n
Finally, you want to be able to execute Electron. In the scripts\nfield of your package.json config, add a start command like so:
{\n \"scripts\": {\n \"start\": \"electron .\"\n }\n}\nThis start command will let you open your app in development mode.
npm start\n\n\nNote: This script tells Electron to run on your project's root folder. At this stage,\nyour app will immediately throw an error telling you that it cannot find an app to run.
\n
The entry point of any Electron application is its main script. This script controls the\nmain process, which runs in a full Node.js environment and is responsible for\ncontrolling your app's lifecycle, displaying native interfaces, performing privileged\noperations, and managing renderer processes (more on that later).
During execution, Electron will look for this script in the main\nfield of the app's package.json config, which you should have configured during the\napp scaffolding step.
To initialize the main script, create an empty file named main.js in the root folder\nof your project.
\n\nNote: If you run the
\nstartscript again at this point, your app will no longer throw\nany errors! However, it won't do anything yet because we haven't added any code into\nmain.js.
Before we can create a window for our application, we need to create the content that\nwill be loaded into it. In Electron, each window displays web contents that can be loaded\nfrom either from a local HTML file or a remote URL.
\nFor this tutorial, you will be doing the former. Create an index.html file in the root\nfolder of your project:
\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n </body>\n</html>\n\n\nNote: Looking at this HTML document, you can observe that the version numbers are\nmissing from the body text. We'll manually insert them later using JavaScript.
\n
Now that you have a web page, load it into an application window. To do so, you'll\nneed two Electron modules:
\napp module, which controls your application's event lifecycle.BrowserWindow module, which creates and manages application\nwindows.Because the main process runs Node.js, you can import these as CommonJS\nmodules at the top of your file:
\nconst { app, BrowserWindow } = require('electron')\nThen, add a createWindow() function that loads index.html into a new BrowserWindow\ninstance.
function createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\nNext, call this createWindow() function to open your window.
In Electron, browser windows can only be created after the app module's\nready event is fired. You can wait for this event by using the\napp.whenReady() API. Call createWindow() after whenReady()\nresolves its Promise.
app.whenReady().then(() => {\n createWindow()\n})\n\n\nNote: At this point, your Electron application should successfully\nopen a window that displays your web page!
\n
Although you can now open a browser window, you'll need some additional boilerplate code\nto make it feel more native to each platform. Application windows behave differently on\neach OS, and Electron puts the responsibility on developers to implement these\nconventions in their app.
\nIn general, you can use the process global's platform attribute\nto run code specifically for certain operating systems.
On Windows and Linux, exiting all windows generally quits an application entirely.
\nTo implement this, listen for the app module's 'window-all-closed'\nevent, and call app.quit() if the user is not on macOS (darwin).
app.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nWhereas Linux and Windows apps quit when they have no windows open, macOS apps generally\ncontinue running even without any windows open, and activating the app when no windows\nare available should open a new one.
\nTo implement this feature, listen for the app module's activate\nevent, and call your existing createWindow() method if no browser windows are open.
Because windows cannot be created before the ready event, you should only listen for\nactivate events after your app is initialized. Do this by attaching your event listener\nfrom within your existing whenReady() callback.
app.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n\nNote: At this point, your window controls should be fully functional!
\n
Now, the last thing to do is print out the version numbers for Electron and its\ndependencies onto your web page.
\nAccessing this information is trivial to do in the main process through Node's\nglobal process object. However, you can't just edit the DOM from the main\nprocess because it has no access to the renderer's document context.\nThey're in entirely different processes!
\n\nNote: If you need a more in-depth look at Electron processes, see the\nProcess Model document.
\n
This is where attaching a preload script to your renderer comes in handy.\nA preload script runs before the renderer process is loaded, and has access to both\nrenderer globals (e.g. window and document) and a Node.js environment.
Create a new script named preload.js as such:
window.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\nThe above code accesses the Node.js process.versions object and runs a basic replaceText\nhelper function to insert the version numbers into the HTML document.
To attach this script to your renderer process, pass in the path to your preload script\nto the webPreferences.preload option in your existing BrowserWindow constructor.
// include the Node.js 'path' module at the top of your file\nconst path = require('path')\n\n// modify your existing createWindow() function\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n}\n// ...\nThere are two Node.js concepts that are used here:
\n__dirname string points to the path of the currently executing script\n(in this case, your project's root folder).path.join API joins multiple path segments together, creating a\ncombined path string that works across all platforms.We use a path relative to the currently executing JavaScript file so that your relative\npath will work in both development and packaged mode.
\nAt this point, you might be wondering how to add more functionality to your application.
\nFor any interactions with your web contents, you want to add scripts to your\nrenderer process. Because the renderer runs in a normal web environment, you can add a\n<script> tag right before your index.html file's closing </body> tag to include\nany arbitrary scripts you want:
<script src=\"./renderer.js\"></script>\nThe code contained in renderer.js can then use the same JavaScript APIs and tooling\nyou use for typical front-end development, such as using webpack to bundle\nand minify your code or React to manage your user interfaces.
After following the above steps, you should have a fully functional\nElectron application that looks like this:
\n![\"Simplest](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/simplest-electron-app.png\")
The full code is available below:
\n// main.js\n\n// Modules to control application life and create native browser window\nconst { app, BrowserWindow } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n // Create the browser window.\n const mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n // and load the index.html of the app.\n mainWindow.loadFile('index.html')\n\n // Open the DevTools.\n // mainWindow.webContents.openDevTools()\n}\n\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// Some APIs can only be used after this event occurs.\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n // On macOS it's common to re-create a window in the app when the\n // dock icon is clicked and there are no other windows open.\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\n\n// In this file you can include the rest of your app's specific main process\n// code. You can also put them in separate files and require them here.\n// preload.js\n\n// All of the Node.js APIs are available in the preload process.\n// It has the same sandbox as a Chrome extension.\nwindow.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\n<!--index.html-->\n\n\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n\n <!-- You can also require other files to run in this process -->\n <script src=\"./renderer.js\"></script>\n </body>\n</html>\nTo summarize all the steps we've done:
\nmain.js script that runs our main process, which controls our app\nand runs in a Node.js environment. In this script, we used Electron's app and\nBrowserWindow modules to create a browser window that displays web content\nin a separate process (the renderer).BrowserWindow constructor.The fastest way to distribute your newly created app is using\nElectron Forge.
\nAdd Electron Forge as a development dependency of your app, and use its import command to set up\nForge's scaffolding:
```sh npm2yarn\nnpm install --save-dev @electron-forge/cli\nnpx electron-forge import\n\n✔ Checking your system\n✔ Initializing Git Repository\n✔ Writing modified package.json file\n✔ Installing dependencies\n✔ Writing modified package.json file\n✔ Fixing .gitignore\n\nWe have ATTEMPTED to convert your app to be in a format that electron-forge understands.\n\nThanks for using \"electron-forge\"!!!\n```\nCreate a distributable using Forge's make command:
npm run make\n\n> my-electron-app@1.0.0 make /my-electron-app\n> electron-forge make\n\n✔ Checking your system\n✔ Resolving Forge Config\nWe need to package your application before we can make it\n✔ Preparing to Package Application for arch: x64\n✔ Preparing native dependencies\n✔ Packaging Application\nMaking for the following targets: zip\n✔ Making for target: zip - On platform: darwin - For arch: x64\nElectron Forge creates the out folder where your package will be located:
// Example for macOS\nout/\n├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip\n├── ...\n└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app\nPlease make sure that you use the documents that match your Electron version.\nThe version number should be a part of the page URL. If it's not, you are\nprobably using the documentation of a development branch which may contain API\nchanges that are not compatible with your Electron version. To view older\nversions of the documentation, you can\nbrowse by tag\non GitHub by opening the \"Switch branches/tags\" dropdown and selecting the tag\nthat matches your version.
\nThere are questions that are asked quite often. Check this out before creating\nan issue:
\nThese individual tutorials expand on topics discussed in the guide above.
\nThese guides are intended for people working on the Electron project itself.\nFor guides on Electron app development, see\n/docs/README.md.
\nWindows and macOS provide access to a list of recent documents opened by\nthe application via JumpList or dock menu, respectively.
\nJumpList:
\n![\"JumpList](\"https://cloud.githubusercontent.com/assets/2289/23446924/11a27b98-fdfc-11e6-8485-cc3b1e86b80a.png\")
Application dock menu:
\n![\"macOS](\"https://cloud.githubusercontent.com/assets/639601/5069610/2aa80758-6e97-11e4-8cfb-c1a414a10774.png\")
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\n\nconst fileName = 'recently-used.md'\nfs.writeFile(fileName, 'Lorem Ipsum', () => {\n app.addRecentDocument(path.join(__dirname, fileName))\n})\n\napp.whenReady().then(createWindow)\n\napp.on('window-all-closed', () => {\n app.clearRecentDocuments()\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nTo add a file to recent documents, use the\napp.addRecentDocument API.
\nAfter launching the Electron application, right click the application icon.\nIn this guide, the item is a Markdown file located in the root of the project.\nYou should see recently-used.md added to the list of recent files:
![\"Recent](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/recent-documents.png\")
To clear the list of recent documents, use the\napp.clearRecentDocuments API.\nIn this guide, the list of documents is cleared once all windows have been\nclosed.
\nTo use this feature on Windows, your application has to be registered as\na handler of the file type of the document, otherwise the file won't appear\nin JumpList even after you have added it. You can find everything\non registering your application in Application Registration.
\nWhen a user clicks a file from the JumpList, a new instance of your application\nwill be started with the path of the file added as a command line argument.
\nYou can add menu items to access and clear recent documents by adding the\nfollowing code snippet to your menu template:
\n{\n \"submenu\":[\n {\n \"label\":\"Open Recent\",\n \"role\":\"recentdocuments\",\n \"submenu\":[\n {\n \"label\":\"Clear Recent\",\n \"role\":\"clearrecentdocuments\"\n }\n ]\n }\n ]\n}\nMake sure the application menu is added after the 'ready'\nevent and not before, or the menu item will be disabled:
const { app, Menu } = require('electron')\n\nconst template = [\n // Menu template here\n]\nconst menu = Menu.buildFromTemplate(template)\n\napp.whenReady().then(() => {\n Menu.setApplicationMenu(menu)\n})\n![\"macOS](\"https://user-images.githubusercontent.com/3168941/33003655-ea601c3a-cd70-11e7-97fa-7c062149cfb1.png\")
When a file is requested from the recent documents menu, the open-file event\nof app module will be emitted for it.
x Number - The x coordinate of the origin of the rectangle (must be an integer).y Number - The y coordinate of the origin of the rectangle (must be an integer).width Number - The width of the rectangle (must be an integer).height Number - The height of the rectangle (must be an integer).url String - HTTP Referrer URL.policy String - Can be default, unsafe-url,\nno-referrer-when-downgrade, no-referrer, origin,\nstrict-origin-when-cross-origin, same-origin or strict-origin.\nSee the Referrer-Policy spec for more details on the\nmeaning of these values.Read-Eval-Print-Loop (REPL)\nis a simple, interactive computer programming environment that takes single user\ninputs (i.e. single expressions), evaluates them, and returns the result to the user.
\nElectron exposes the Node.js repl module\nthrough the --interactive CLI flag. Assuming you have electron installed as a local project\ndependency, you should be able to access the REPL with the following command:
./node_modules/.bin/electron --interactive\nNote: electron --interactive is not available on Windows\n(see electron/electron#5776 for more details).
You can use the DevTools Console tab to get a REPL for any renderer process.\nTo learn more, read the Chrome documentation.
", "title": "REPL", "description": "" }, "/docs/tutorial/represented-file": { "locale": "en-US", "slug": "represented-file", "href": "/docs/tutorial/represented-file", "crowdinFileId": "256243", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/represented-file.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "On macOS, you can set a represented file for any window in your application.\nThe represented file's icon will be shown in the title bar, and when users\nCommand-Click or Control-Click, a popup with a path to the file will be\nshown.
![\"Represented](\"https://cloud.githubusercontent.com/assets/639601/5082061/670a949a-6f14-11e4-987a-9aaa04b23c1d.png\")
\n\nNOTE: The screenshot above is an example where this feature is used to indicate the currently opened file in the Atom text editor.
\n
You can also set the edited state for a window so that the file icon can\nindicate whether the document in this window has been modified.
\nTo set the represented file of window, you can use the\nBrowserWindow.setRepresentedFilename and\nBrowserWindow.setDocumentEdited APIs.
\nconst { app, BrowserWindow } = require('electron')\nconst os = require('os');\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n}\n\napp.whenReady().then(() => {\n const win = new BrowserWindow()\n\n win.setRepresentedFilename(os.homedir())\n win.setDocumentEdited(true)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nAfter launching the Electron application, click on the title with Command or\nControl key pressed. You should see a popup with the represented file at the top.\nIn this guide, this is the current user's home directory:
![\"Represented](\"https://cdn.rawgit.com/electron/electron/v15.1.1//docs/images/represented-file.png\")
\n\nAllows access to simple encryption and decryption of strings for storage on the local machine.
\n
Process: Main
\nThis module protects data stored on disk from being accessed by other applications or users with full disk access.
\nNote that on Mac, access to the system Keychain is required and\nthese calls can block the current thread to collect user input.\nThe same is true for Linux, if a password management tool is available.
\nThe safeStorage module has the following methods:
safeStorage.isEncryptionAvailable()Returns Boolean - Whether encryption is available.
On Linux, returns true if the secret key is\navailable. On MacOS, returns true if Keychain is available.\nOn Windows, returns true with no other preconditions.
\nsafeStorage.encryptString(plainText)plainText StringReturns Buffer - An array of bytes representing the encrypted string.
This function will throw an error if encryption fails.
\nsafeStorage.decryptString(encrypted)encrypted BufferReturns String - the decrypted string. Decrypts the encrypted buffer\nobtained with safeStorage.encryptString back into a string.
This function will throw an error if decryption fails.
", "title": "safeStorage", "description": "Allows access to simple encryption and decryption of strings for storage on the local machine." }, "/docs/tutorial/sandbox": { "locale": "en-US", "slug": "sandbox", "href": "/docs/tutorial/sandbox", "crowdinFileId": "256245", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/sandbox.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "One key security feature in Chromium is that processes can be executed within a sandbox.\nThe sandbox limits the harm that malicious code can cause by limiting access to most\nsystem resources — sandboxed processes can only freely use CPU cycles and memory.\nIn order to perform operations requiring additional privilege, sandboxed processes\nuse dedicated communication channels to delegate tasks to more privileged processes.
\nIn Chromium, sandboxing is applied to most processes other than the main process.\nThis includes renderer processes, as well as utility processes such as the audio service,\nthe GPU service and the network service.
\nSee Chromium's Sandbox design document for more information.
\nElectron comes with a mixed sandbox environment, meaning sandboxed processes can run\nalongside privileged ones. By default, renderer processes are not sandboxed, but\nutility processes are. Note that as in Chromium, the main (browser) process is\nprivileged and cannot be sandboxed.
\nHistorically, this mixed sandbox approach was established because having Node.js available\nin the renderer is an extremely powerful tool for app developers. Unfortunately, this\nfeature is also an equally massive security vulnerability.
\nTheoretically, unsandboxed renderers are not a problem for desktop applications that\nonly display trusted code, but they make Electron less secure than Chromium for\ndisplaying untrusted web content. However, even purportedly trusted code may be\ndangerous — there are countless attack vectors that malicious actors can use, from\ncross-site scripting to content injection to man-in-the-middle attacks on remotely loaded\nwebsites, just to name a few. For this reason, we recommend enabling renderer sandboxing\nfor the vast majority of cases under an abundance of caution.
\n\nNote that there is an active discussion in the issue tracker to enable renderer sandboxing\nby default. See #28466) for details.
\nSandboxed processes in Electron behave mostly in the same way as Chromium's do, but\nElectron has a few additional concepts to consider because it interfaces with Node.js.
\nWhen renderer processes in Electron are sandboxed, they behave in the same way as a\nregular Chrome renderer would. A sandboxed renderer won't have a Node.js\nenvironment initialized.
\n\nTherefore, when the sandbox is enabled, renderer processes can only perform privileged\ntasks (such as interacting with the filesystem, making changes to the system, or spawning\nsubprocesses) by delegating these tasks to the main process via inter-process\ncommunication (IPC).
\nIn order to allow renderer processes to communicate with the main process, preload\nscripts attached to sandboxed renderers will still have a polyfilled subset of Node.js\nAPIs available. A require function similar to Node's require module is exposed,\nbut can only import a subset of Electron and Node's built-in modules:
In addition, the preload script also polyfills certain Node.js primitives as globals:
\nBufferprocessclearImmediatesetImmediateBecause the require function is a polyfill with limited functionality, you will not be\nable to use CommonJS modules to separate your preload script into multiple\nfiles. If you need to split your preload code, use a bundler such as webpack\nor Parcel.
Note that because the environment presented to the preload script is substantially\nmore privileged than that of a sandboxed renderer, it is still possible to leak\nprivileged APIs to untrusted code running in the renderer process unless\ncontextIsolation is enabled.
In Electron, renderer sandboxing can be enabled on a per-process basis with\nthe sandbox: true preference in the BrowserWindow constructor.
// main.js\napp.whenReady().then(() => {\n const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n })\n win.loadURL('https://google.com')\n})\nIf you want to force sandboxing for all renderers, you can also use the\napp.enableSandbox API. Note that this API has to be called before the\napp's ready event.
// main.js\napp.enableSandbox()\napp.whenReady().then(() => {\n // no need to pass `sandbox: true` since `app.enableSandbox()` was called.\n const win = new BrowserWindow()\n win.loadURL('https://google.com')\n})\nYou can also disable Chromium's sandbox entirely with the --no-sandbox\nCLI flag, which will disable the sandbox for all processes (including utility processes).\nWe highly recommend that you only use this flag for testing purposes, and never\nin production.
Note that the sandbox: true option will still disable the renderer's Node.js\nenvironment.
Rendering untrusted content in Electron is still somewhat uncharted territory,\nthough some apps are finding success (e.g. Beaker Browser).\nOur goal is to get as close to Chrome as we can in terms of the security of\nsandboxed content, but ultimately we will always be behind due to a few fundamental\nissues:
\nWhile we make our best effort to backport Chromium security fixes to older\nversions of Electron, we do not make a guarantee that every fix will be\nbackported. Your best chance at staying secure is to be on the latest stable\nversion of Electron.
", "title": "Process Sandboxing", "description": "" }, "/docs/api/screen": { "locale": "en-US", "slug": "screen", "href": "/docs/api/screen", "crowdinFileId": "256361", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/screen.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRetrieve information about screen size, displays, cursor position, etc.
\n
Process: Main
\nThis module cannot be used until the ready event of the app\nmodule is emitted.
screen is an EventEmitter.
Note: In the renderer / DevTools, window.screen is a reserved DOM\nproperty, so writing let { screen } = require('electron') will not work.
An example of creating a window that fills the whole screen:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\napp.whenReady().then(() => {\n const { width, height } = screen.getPrimaryDisplay().workAreaSize\n win = new BrowserWindow({ width, height })\n win.loadURL('https://github.com')\n})\nAnother example of creating a window in the external display:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n const displays = screen.getAllDisplays()\n const externalDisplay = displays.find((display) => {\n return display.bounds.x !== 0 || display.bounds.y !== 0\n })\n\n if (externalDisplay) {\n win = new BrowserWindow({\n x: externalDisplay.bounds.x + 50,\n y: externalDisplay.bounds.y + 50\n })\n win.loadURL('https://github.com')\n }\n})\nThe screen module emits the following events:
Returns:
\nevent EventnewDisplay DisplayEmitted when newDisplay has been added.
Returns:
\nevent EventoldDisplay DisplayEmitted when oldDisplay has been removed.
Returns:
\nevent Eventdisplay DisplaychangedMetrics String[]Emitted when one or more metrics change in a display. The changedMetrics is\nan array of strings that describe the changes. Possible changes are bounds,\nworkArea, scaleFactor and rotation.
The screen module has the following methods:
screen.getCursorScreenPoint()Returns Point
The current absolute position of the mouse pointer.
\nNote: The return value is a DIP point, not a screen physical point.
\nscreen.getPrimaryDisplay()Returns Display - The primary display.
screen.getAllDisplays()Returns Display[] - An array of displays that are currently available.
screen.getDisplayNearestPoint(point)point PointReturns Display - The display nearest the specified point.
screen.getDisplayMatching(rect)rect RectangleReturns Display - The display that most closely\nintersects the provided bounds.
screen.screenToDipPoint(point) Windowspoint PointReturns Point
Converts a screen physical point to a screen DIP point.\nThe DPI scale is performed relative to the display containing the physical point.
\nscreen.dipToScreenPoint(point) Windowspoint PointReturns Point
Converts a screen DIP point to a screen physical point.\nThe DPI scale is performed relative to the display containing the DIP point.
\nscreen.screenToDipRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleReturns Rectangle
Converts a screen physical rect to a screen DIP rect.\nThe DPI scale is performed relative to the display nearest to window.\nIf window is null, scaling will be performed to the display nearest to rect.
screen.dipToScreenRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleReturns Rectangle
Converts a screen DIP rect to a screen physical rect.\nThe DPI scale is performed relative to the display nearest to window.\nIf window is null, scaling will be performed to the display nearest to rect.
label String (optional) - The text to appear in this item.icon NativeImage (optional) - The image to appear in this item.As web developers, we usually enjoy the strong security net of the browser -\nthe risks associated with the code we write are relatively small. Our websites\nare granted limited powers in a sandbox, and we trust that our users enjoy a\nbrowser built by a large team of engineers that is able to quickly respond to\nnewly discovered security threats.
\nWhen working with Electron, it is important to understand that Electron is not\na web browser. It allows you to build feature-rich desktop applications with\nfamiliar web technologies, but your code wields much greater power. JavaScript\ncan access the filesystem, user shell, and more. This allows you to build\nhigh quality native applications, but the inherent security risks scale with\nthe additional powers granted to your code.
\nWith that in mind, be aware that displaying arbitrary content from untrusted\nsources poses a severe security risk that Electron is not intended to handle.\nIn fact, the most popular Electron apps (Atom, Slack, Visual Studio Code, etc)\ndisplay primarily local content (or trusted, secure remote content without Node\nintegration) – if your application executes code from an online source, it is\nyour responsibility to ensure that the code is not malicious.
\nFor information on how to properly disclose an Electron vulnerability,\nsee SECURITY.md
\nElectron keeps up to date with alternating Chromium releases. For more information,\nsee the Electron Release Cadence blog post.
\nIt is important to remember that the security of your Electron application is\nthe result of the overall security of the framework foundation\n(Chromium, Node.js), Electron itself, all NPM dependencies and\nyour code. As such, it is your responsibility to follow a few important best\npractices:
\nKeep your application up-to-date with the latest Electron framework release.\nWhen releasing your product, you’re also shipping a bundle composed of Electron,\nChromium shared library and Node.js. Vulnerabilities affecting these components\nmay impact the security of your application. By updating Electron to the latest\nversion, you ensure that critical vulnerabilities (such as nodeIntegration bypasses)\nare already patched and cannot be exploited in your application. For more information,\nsee \"Use a current version of Electron\".
\nEvaluate your dependencies. While NPM provides half a million reusable packages,\nit is your responsibility to choose trusted 3rd-party libraries. If you use outdated\nlibraries affected by known vulnerabilities or rely on poorly maintained code,\nyour application security could be in jeopardy.
\nAdopt secure coding practices. The first line of defense for your application\nis your own code. Common web vulnerabilities, such as Cross-Site Scripting (XSS),\nhave a higher security impact on Electron applications hence it is highly recommended\nto adopt secure software development best practices and perform security testing.
\nA security issue exists whenever you receive code from an untrusted source (e.g.\na remote server) and execute it locally. As an example, consider a remote\nwebsite being displayed inside a default BrowserWindow. If\nan attacker somehow manages to change said content (either by attacking the\nsource directly, or by sitting between your app and the actual destination), they\nwill be able to execute native code on the user's machine.
\n\n⚠️ Under no circumstances should you load and execute remote code with\nNode.js integration enabled. Instead, use only local files (packaged together\nwith your application) to execute Node.js code. To display remote content, use\nthe
\n<webview>tag orBrowserView, make sure\nto disable thenodeIntegrationand enablecontextIsolation.
From Electron 2.0 on, developers will see warnings and recommendations printed\nto the developer console. They only show up when the binary's name is Electron,\nindicating that a developer is currently looking at the console.
\nYou can force-enable or force-disable these warnings by setting\nELECTRON_ENABLE_SECURITY_WARNINGS or ELECTRON_DISABLE_SECURITY_WARNINGS on\neither process.env or the window object.
You should at least follow these steps to improve the security of your application:
\nses.setPermissionRequestHandler() in all sessions that load remote contentwebSecurityContent-Security-Policy and use restrictive rules (i.e. script-src 'self')allowRunningInsecureContent to trueenableBlinkFeatures<webview>: Do not use allowpopups<webview>: Verify options and paramsopenExternal with untrusted contentTo automate the detection of misconfigurations and insecure patterns, it is\npossible to use\nelectronegativity. For\nadditional details on potential weaknesses and implementation bugs when\ndeveloping applications using Electron, please refer to this guide for\ndevelopers and auditors
\nAny resources not included with your application should be loaded using a\nsecure protocol like HTTPS. In other words, do not use insecure protocols\nlike HTTP. Similarly, we recommend the use of WSS over WS, FTPS over\nFTP, and so on.
HTTPS has three main benefits:
1) It authenticates the remote server, ensuring your app connects to the correct\nhost instead of an impersonator.\n2) It ensures data integrity, asserting that the data was not modified while in\ntransit between your application and the host.\n3) It encrypts the traffic between your user and the destination host, making it\nmore difficult to eavesdrop on the information sent between your app and\nthe host.
\n// Bad\nbrowserWindow.loadURL('http://example.com')\n\n// Good\nbrowserWindow.loadURL('https://example.com')\n<!-- Bad -->\n<script crossorigin src=\"http://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"http://example.com/style.css\">\n\n<!-- Good -->\n<script crossorigin src=\"https://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"https://example.com/style.css\">\nThis recommendation is the default behavior in Electron since 5.0.0.
\nIt is paramount that you do not enable Node.js integration in any renderer\n(BrowserWindow, BrowserView, or\n<webview>) that loads remote content. The goal is to limit the\npowers you grant to remote content, thus making it dramatically more difficult\nfor an attacker to harm your users should they gain the ability to execute\nJavaScript on your website.
After this, you can grant additional permissions for specific hosts. For example,\nif you are opening a BrowserWindow pointed at https://example.com/, you can\ngive that website exactly the abilities it needs, but no more.
A cross-site-scripting (XSS) attack is more dangerous if an attacker can jump\nout of the renderer process and execute code on the user's computer.\nCross-site-scripting attacks are fairly common - and while an issue, their\npower is usually limited to messing with the website that they are executed on.\nDisabling Node.js integration helps prevent an XSS from being escalated into a\nso-called \"Remote Code Execution\" (RCE) attack.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n nodeIntegration: true,\n nodeIntegrationInWorker: true\n }\n})\n\nmainWindow.loadURL('https://example.com')\n// Good\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n preload: path.join(app.getAppPath(), 'preload.js')\n }\n})\n\nmainWindow.loadURL('https://example.com')\n<!-- Bad -->\n<webview nodeIntegration src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nWhen disabling Node.js integration, you can still expose APIs to your website that\ndo consume Node.js modules or features. Preload scripts continue to have access\nto require and other Node.js features, allowing developers to expose a custom\nAPI to remotely loaded content.
In the following example preload script, the later loaded website will have\naccess to a window.readConfig() method, but no Node.js features.
const { readFileSync } = require('fs')\n\nwindow.readConfig = function () {\n const data = readFileSync('./config.json')\n return data\n}\nContext isolation is an Electron feature that allows developers to run code\nin preload scripts and in Electron APIs in a dedicated JavaScript context. In\npractice, that means that global objects like Array.prototype.push or\nJSON.parse cannot be modified by scripts running in the renderer process.
Electron uses the same technology as Chromium's Content Scripts\nto enable this behavior.
\nEven when nodeIntegration: false is used, to truly enforce strong isolation\nand prevent the use of Node primitives contextIsolation must also be used.
For more information on what contextIsolation is and how to enable it please\nsee our dedicated Context Isolation document.
Sandboxing is a Chromium feature that uses the operating system to\nsignificantly limit what renderer processes have access to. You should enable\nthe sandbox in all renderers. Loading, reading or processing any untrusted\ncontent in an unsandboxed process, including the main process, is not advised.
\nWhen creating a window, pass the sandbox: true option in webPreferences:
const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n})\nYou may have seen permission requests while using Chrome: They pop up whenever\nthe website attempts to use a feature that the user has to manually approve (\nlike notifications).
\nThe API is based on the Chromium permissions API\nand implements the same types of permissions.
\nBy default, Electron will automatically approve all permission requests unless\nthe developer has manually configured a custom handler. While a solid default,\nsecurity-conscious developers might want to assume the very opposite.
\nconst { session } = require('electron')\n\nsession\n .fromPartition('some-partition')\n .setPermissionRequestHandler((webContents, permission, callback) => {\n const url = webContents.getURL()\n\n if (permission === 'notifications') {\n // Approves the permissions request\n callback(true)\n }\n\n // Verify URL\n if (!url.startsWith('https://example.com/')) {\n // Denies the permissions request\n return callback(false)\n }\n })\nRecommendation is Electron's default
\nYou may have already guessed that disabling the webSecurity property on a\nrenderer process (BrowserWindow,\nBrowserView, or <webview>) disables crucial\nsecurity features.
Do not disable webSecurity in production applications.
Disabling webSecurity will disable the same-origin policy and set\nallowRunningInsecureContent property to true. In other words, it allows\nthe execution of insecure code from different domains.
// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n webSecurity: false\n }\n})\n// Good\nconst mainWindow = new BrowserWindow()\n<!-- Bad -->\n<webview disablewebsecurity src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nA Content Security Policy (CSP) is an additional layer of protection against\ncross-site-scripting attacks and data injection attacks. We recommend that they\nbe enabled by any website you load inside Electron.
\nCSP allows the server serving content to restrict and control the resources\nElectron can load for that given web page. https://example.com should\nbe allowed to load scripts from the origins you defined while scripts from\nhttps://evil.attacker.com should not be allowed to run. Defining a CSP is an\neasy way to improve your application's security.
The following CSP will allow Electron to execute scripts from the current\nwebsite and from apis.example.com.
// Bad\nContent-Security-Policy: '*'\n\n// Good\nContent-Security-Policy: script-src 'self' https://apis.example.com\nElectron respects the Content-Security-Policy HTTP header\nwhich can be set using Electron's\nwebRequest.onHeadersReceived\nhandler:
const { session } = require('electron')\n\nsession.defaultSession.webRequest.onHeadersReceived((details, callback) => {\n callback({\n responseHeaders: {\n ...details.responseHeaders,\n 'Content-Security-Policy': ['default-src \\'none\\'']\n }\n })\n})\nCSP's preferred delivery mechanism is an HTTP header, however it is not possible\nto use this method when loading a resource using the file:// protocol. It can\nbe useful in some cases, such as using the file:// protocol, to set a policy\non a page directly in the markup using a <meta> tag:
<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'\">\nallowRunningInsecureContent to trueRecommendation is Electron's default
\nBy default, Electron will not allow websites loaded over HTTPS to load and\nexecute scripts, CSS, or plugins from insecure sources (HTTP). Setting the\nproperty allowRunningInsecureContent to true disables that protection.
Loading the initial HTML of a website over HTTPS and attempting to load\nsubsequent resources via HTTP is also known as \"mixed content\".
Loading content over HTTPS assures the authenticity and integrity\nof the loaded resources while encrypting the traffic itself. See the section on\nonly displaying secure content for more details.
// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n allowRunningInsecureContent: true\n }\n})\n// Good\nconst mainWindow = new BrowserWindow({})\nRecommendation is Electron's default
\nAdvanced users of Electron can enable experimental Chromium features using the\nexperimentalFeatures property.
Experimental features are, as the name suggests, experimental and have not been\nenabled for all Chromium users. Furthermore, their impact on Electron as a whole\nhas likely not been tested.
\nLegitimate use cases exist, but unless you know what you are doing, you should\nnot enable this property.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n experimentalFeatures: true\n }\n})\n// Good\nconst mainWindow = new BrowserWindow({})\nenableBlinkFeaturesRecommendation is Electron's default
\nBlink is the name of the rendering engine behind Chromium. As with\nexperimentalFeatures, the enableBlinkFeatures property allows developers to\nenable features that have been disabled by default.
Generally speaking, there are likely good reasons if a feature was not enabled\nby default. Legitimate use cases for enabling specific features exist. As a\ndeveloper, you should know exactly why you need to enable a feature, what the\nramifications are, and how it impacts the security of your application. Under\nno circumstances should you enable features speculatively.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n enableBlinkFeatures: 'ExecCommandInJavaScript'\n }\n})\n// Good\nconst mainWindow = new BrowserWindow()\nallowpopupsRecommendation is Electron's default
\nIf you are using <webview>, you might need the pages and scripts\nloaded in your <webview> tag to open new windows. The allowpopups attribute\nenables them to create new BrowserWindows using the\nwindow.open() method. <webview> tags are otherwise not allowed to create new\nwindows.
If you do not need popups, you are better off not allowing the creation of\nnew BrowserWindows by default. This follows the principle\nof minimally required access: Don't let a website create new popups unless\nyou know it needs that feature.
<!-- Bad -->\n<webview allowpopups src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nA WebView created in a renderer process that does not have Node.js integration\nenabled will not be able to enable integration itself. However, a WebView will\nalways create an independent renderer process with its own webPreferences.
It is a good idea to control the creation of new <webview> tags\nfrom the main process and to verify that their webPreferences do not disable\nsecurity features.
Since <webview> live in the DOM, they can be created by a script running on your\nwebsite even if Node.js integration is otherwise disabled.
Electron enables developers to disable various security features that control\na renderer process. In most cases, developers do not need to disable any of\nthose features - and you should therefore not allow different configurations\nfor newly created <webview> tags.
Before a <webview> tag is attached, Electron will fire the\nwill-attach-webview event on the hosting webContents. Use the event to\nprevent the creation of webViews with possibly insecure options.
app.on('web-contents-created', (event, contents) => {\n contents.on('will-attach-webview', (event, webPreferences, params) => {\n // Strip away preload scripts if unused or verify their location is legitimate\n delete webPreferences.preload\n delete webPreferences.preloadURL\n\n // Disable Node.js integration\n webPreferences.nodeIntegration = false\n\n // Verify URL being loaded\n if (!params.src.startsWith('https://example.com/')) {\n event.preventDefault()\n }\n })\n})\nAgain, this list merely minimizes the risk, it does not remove it. If your goal\nis to display a website, a browser will be a more secure option.
\nIf your app has no need to navigate or only needs to navigate to known pages,\nit is a good idea to limit navigation outright to that known scope, disallowing\nany other kinds of navigation.
\nNavigation is a common attack vector. If an attacker can convince your app to\nnavigate away from its current page, they can possibly force your app to open\nweb sites on the Internet. Even if your webContents are configured to be more\nsecure (like having nodeIntegration disabled or contextIsolation enabled),\ngetting your app to open a random web site will make the work of exploiting your\napp a lot easier.
A common attack pattern is that the attacker convinces your app's users to\ninteract with the app in such a way that it navigates to one of the attacker's\npages. This is usually done via links, plugins, or other user-generated content.
\nIf your app has no need for navigation, you can call event.preventDefault()\nin a will-navigate handler. If you know which pages your app\nmight navigate to, check the URL in the event handler and only let navigation\noccur if it matches the URLs you're expecting.
We recommend that you use Node's parser for URLs. Simple string comparisons can\nsometimes be fooled - a startsWith('https://example.com') test would let\nhttps://example.com.attacker.com through.
const URL = require('url').URL\n\napp.on('web-contents-created', (event, contents) => {\n contents.on('will-navigate', (event, navigationUrl) => {\n const parsedUrl = new URL(navigationUrl)\n\n if (parsedUrl.origin !== 'https://example.com') {\n event.preventDefault()\n }\n })\n})\nIf you have a known set of windows, it's a good idea to limit the creation of\nadditional windows in your app.
\nMuch like navigation, the creation of new webContents is a common attack\nvector. Attackers attempt to convince your app to create new windows, frames,\nor other renderer processes with more privileges than they had before; or\nwith pages opened that they couldn't open before.
If you have no need to create windows in addition to the ones you know you'll\nneed to create, disabling the creation buys you a little bit of extra\nsecurity at no cost. This is commonly the case for apps that open one\nBrowserWindow and do not need to open an arbitrary number of additional\nwindows at runtime.
webContents will delegate to its window open\nhandler before creating new windows. The handler will\nreceive, amongst other parameters, the url the window was requested to open\nand the options used to create it. We recommend that you register a handler to\nmonitor the creation of windows, and deny any unexpected window creation.
const { shell } = require('electron')\n\napp.on('web-contents-created', (event, contents) => {\n contents.setWindowOpenHandler(({ url }) => {\n // In this example, we'll ask the operating system\n // to open this event's url in the default browser.\n //\n // See the following item for considerations regarding what\n // URLs should be allowed through to shell.openExternal.\n if (isSafeForExternalOpen(url)) {\n setImmediate(() => {\n shell.openExternal(url)\n })\n }\n\n return { action: 'deny' }\n })\n})\nopenExternal with untrusted contentShell's openExternal allows opening a given protocol URI with\nthe desktop's native utilities. On macOS, for instance, this function is similar\nto the open terminal command utility and will open the specific application\nbased on the URI and filetype association.
Improper use of openExternal can be leveraged to compromise\nthe user's host. When openExternal is used with untrusted content, it can be\nleveraged to execute arbitrary commands.
// Bad\nconst { shell } = require('electron')\nshell.openExternal(USER_CONTROLLED_DATA_HERE)\n// Good\nconst { shell } = require('electron')\nshell.openExternal('https://example.com/index.html')\nYou should strive for always using the latest available version of Electron.\nWhenever a new major version is released, you should attempt to update your\napp as quickly as possible.
\nAn application built with an older version of Electron, Chromium, and Node.js\nis an easier target than an application that is using more recent versions of\nthose components. Generally speaking, security issues and exploits for older\nversions of Chromium and Node.js are more widely available.
\nBoth Chromium and Node.js are impressive feats of engineering built by\nthousands of talented developers. Given their popularity, their security is\ncarefully tested and analyzed by equally skilled security researchers. Many of\nthose researchers disclose vulnerabilities responsibly,\nwhich generally means that researchers will give Chromium and Node.js some time\nto fix issues before publishing them. Your application will be more secure if\nit is running a recent version of Electron (and thus, Chromium and Node.js) for\nwhich potential security issues are not as widely known.
", "title": "Security, Native Capabilities, and Your Responsibility", "description": "⚠️ Under no circumstances should you load and execute remote code with\nNode.js integration enabled. Instead, use only local files (packaged together\nwith your application) to execute Node.js code. To display remote content, use\nthelabel String (optional) - The text to appear in this segment.icon NativeImage (optional) - The image to appear in this segment.enabled Boolean (optional) - Whether this segment is selectable. Default: true.portId String - Unique identifier for the port.portName String - Name of the port.displayName String - A string suitable for display to the user for describing this device.vendorId String - Optional USB vendor ID.productId String - Optional USB product ID.serialNumber String - The USB device serial number.usbDriverName String (optional) - Represents a single serial port on macOS can be enumerated by multiple drivers.deviceInstanceId String (optional) - A stable identifier on Windows that can be used for device permissions.scriptUrl String - The full URL to the script that this service worker runsscope String - The base URL that this service worker is active for.renderProcessId Number - The virtual ID of the process that this service worker is running in. This is not an OS level PID. This aligns with the ID set used for webContents.getProcessId().\n\nQuery and receive events from a sessions active service workers.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Instances of the ServiceWorkers class are accessed by using serviceWorkers property of\na Session.
For example:
\nconst { session } = require('electron')\n\n// Get all service workers.\nconsole.log(session.defaultSession.serviceWorkers.getAllRunning())\n\n// Handle logs and get service worker info\nsession.defaultSession.serviceWorkers.on('console-message', (event, messageDetails) => {\n console.log(\n 'Got service worker message',\n messageDetails,\n 'from',\n session.defaultSession.serviceWorkers.getFromVersionID(messageDetails.versionId)\n )\n})\nThe following events are available on instances of ServiceWorkers:
Returns:
\nevent EventmessageDetails Object - Information about the console messagemessage String - The actual console messageversionId Number - The version ID of the service worker that sent the log messagesource String - The type of source for this message. Can be javascript, xml, network, console-api, storage, app-cache, rendering, security, deprecation, worker, violation, intervention, recommendation or other.level Number - The log level, from 0 to 3. In order it matches verbose, info, warning and error.sourceUrl String - The URL the message came fromlineNumber Number - The line number of the source that triggered this console messageEmitted when a service worker logs something to the console.
\nReturns:
\nevent Eventdetails Object - Information about the registered service workerscope String - The base URL that a service worker is registered forEmitted when a service worker has been registered. Can occur after a call to navigator.serviceWorker.register('/sw.js') successfully resolves or when a Chrome extension is loaded.
The following methods are available on instances of ServiceWorkers:
serviceWorkers.getAllRunning()Returns Record<Number, ServiceWorkerInfo> - A ServiceWorkerInfo object where the keys are the service worker version ID and the values are the information about that service worker.
serviceWorkers.getFromVersionID(versionId)versionId NumberReturns ServiceWorkerInfo - Information about this service worker
If the service worker does not exist or is not running this method will throw an exception.
", "title": "ServiceWorkers", "description": "Query and receive events from a sessions active service workers." }, "/docs/api/session": { "locale": "en-US", "slug": "session", "href": "/docs/api/session", "crowdinFileId": "256365", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/session.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nManage browser sessions, cookies, cache, proxy settings, etc.
\n
Process: Main
\nThe session module can be used to create new Session objects.
You can also access the session of existing pages by using the session\nproperty of WebContents, or from the session module.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nconst ses = win.webContents.session\nconsole.log(ses.getUserAgent())\nThe session module has the following methods:
session.fromPartition(partition[, options])partition Stringoptions Object (optional)cache Boolean - Whether to enable cache.Returns Session - A session instance from partition string. When there is an existing\nSession with the same partition, it will be returned; otherwise a new\nSession instance will be created with options.
If partition starts with persist:, the page will use a persistent session\navailable to all pages in the app with the same partition. if there is no\npersist: prefix, the page will use an in-memory session. If the partition is\nempty then default session of the app will be returned.
To create a Session with options, you have to ensure the Session with the\npartition has never been used before. There is no way to change the options\nof an existing Session object.
The session module has the following properties:
session.defaultSessionA Session object, the default session object of the app.
\n\nGet and set properties of a session.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
You can create a Session object in the session module:
const { session } = require('electron')\nconst ses = session.fromPartition('persist:name')\nconsole.log(ses.getUserAgent())\nThe following events are available on instances of Session:
Returns:
\nevent Eventitem DownloadItemwebContents WebContentsEmitted when Electron is about to download item in webContents.
Calling event.preventDefault() will cancel the download and item will not be\navailable from next tick of the process.
const { session } = require('electron')\nsession.defaultSession.on('will-download', (event, item, webContents) => {\n event.preventDefault()\n require('got')(item.getURL()).then((response) => {\n require('fs').writeFileSync('/somewhere', response.body)\n })\n})\nReturns:
\nevent Eventextension ExtensionEmitted after an extension is loaded. This occurs whenever an extension is\nadded to the \"enabled\" set of extensions. This includes:
\nSession.loadExtension.chrome.runtime.reload()).Returns:
\nevent Eventextension ExtensionEmitted after an extension is unloaded. This occurs when\nSession.removeExtension is called.
Returns:
\nevent Eventextension ExtensionEmitted after an extension is loaded and all necessary browser state is\ninitialized to support the start of the extension's background page.
\nReturns:
\nevent EventpreconnectUrl String - The URL being requested for preconnection by the\nrenderer.allowCredentials Boolean - True if the renderer is requesting that the\nconnection include credentials (see the\nspec for more details.)Emitted when a render process requests preconnection to a URL, generally due to\na resource hint.
\nReturns:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file has been successfully initialized. This\noccurs after the file has been downloaded.
\nReturns:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file starts downloading
\nReturns:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file has been successfully downloaded
\nReturns:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file download fails. For details\non the failure you should collect a netlog and inspect the download\nrequest.
\nReturns:
\nevent Eventdetails ObjectdeviceList HIDDevice[]frame WebFrameMaincallback FunctiondeviceId String | null (optional)Emitted when a HID device needs to be selected when a call to\nnavigator.hid.requestDevice is made. callback should be called with\ndeviceId to be selected; passing no arguments to callback will\ncancel the request. Additionally, permissioning on navigator.hid can\nbe further managed by using ses.setPermissionCheckHandler(handler)\nand ses.setDevicePermissionHandler(handler)`.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nReturns:
\nevent Eventdetails Objectdevice HIDDevice[]frame WebFrameMainEmitted when a new HID device becomes available. For example, when a new USB device is plugged in.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
Returns:
\nevent Eventdetails Objectdevice HIDDevice[]frame WebFrameMainEmitted when a HID device has been removed. For example, this event will fire when a USB device is unplugged.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
Returns:
\nevent EventportList SerialPort[]webContents WebContentscallback FunctionportId StringEmitted when a serial port needs to be selected when a call to\nnavigator.serial.requestPort is made. callback should be called with\nportId to be selected, passing an empty string to callback will\ncancel the request. Additionally, permissioning on navigator.serial can\nbe managed by using ses.setPermissionCheckHandler(handler)\nwith the serial permission.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({\n width: 800,\n height: 600\n })\n win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {\n event.preventDefault()\n const selectedPort = portList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n if (!selectedPort) {\n callback('')\n } else {\n callback(selectedPort.portId)\n }\n })\n})\nReturns:
\nevent Eventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a new serial port becomes available. For example, this event will fire when a new USB device is plugged in.
Returns:
\nevent Eventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a serial port has been removed. For example, this event will fire when a USB device is unplugged.
The following methods are available on instances of Session:
ses.getCacheSize()Returns Promise<Integer> - the session's current cache size, in bytes.
ses.clearCache()Returns Promise<void> - resolves when the cache clear operation is complete.
Clears the session’s HTTP cache.
\nses.clearStorageData([options])options Object (optional)origin String (optional) - Should follow window.location.origin’s representation\nscheme://host:port.storages String - The types of storages to clear, can contain:\nappcache, cookies, filesystem, indexdb, localstorage,\nshadercache, websql, serviceworkers, cachestorage. If not\nspecified, clear all storage types.quotas String - The types of quotas to clear, can contain:\ntemporary, persistent, syncable. If not specified, clear all quotas.Returns Promise<void> - resolves when the storage data has been cleared.
ses.flushStorageData()Writes any unwritten DOMStorage data to disk.
\nses.setProxy(config)config Objectmode String (optional) - The proxy mode. Should be one of direct,\nauto_detect, pac_script, fixed_servers or system. If it's\nunspecified, it will be automatically determined based on other specified\noptions.direct\nIn direct mode all connections are created directly, without any proxy involved.auto_detect\nIn auto_detect mode the proxy configuration is determined by a PAC script that can\nbe downloaded at http://wpad/wpad.dat.pac_script\nIn pac_script mode the proxy configuration is determined by a PAC script that is\nretrieved from the URL specified in the pacScript. This is the default mode\nif pacScript is specified.fixed_servers\nIn fixed_servers mode the proxy configuration is specified in proxyRules.\nThis is the default mode if proxyRules is specified.system\nIn system mode the proxy configuration is taken from the operating system.\nNote that the system mode is different from setting no proxy configuration.\nIn the latter case, Electron falls back to the system settings\nonly if no command-line options influence the proxy configuration.pacScript String (optional) - The URL associated with the PAC file.proxyRules String (optional) - Rules indicating which proxies to use.proxyBypassRules String (optional) - Rules indicating which URLs should\nbypass the proxy settings.Returns Promise<void> - Resolves when the proxy setting process is complete.
Sets the proxy settings.
\nWhen mode is unspecified, pacScript and proxyRules are provided together, the proxyRules\noption is ignored and pacScript configuration is applied.
You may need ses.closeAllConnections to close currently in flight connections to prevent\npooled sockets using previous proxy from being reused by future requests.
The proxyRules has to follow the rules below:
proxyRules = schemeProxies[\";\"<schemeProxies>]\nschemeProxies = [<urlScheme>\"=\"]<proxyURIList>\nurlScheme = \"http\" | \"https\" | \"ftp\" | \"socks\"\nproxyURIList = <proxyURL>[\",\"<proxyURIList>]\nproxyURL = [<proxyScheme>\"://\"]<proxyHost>[\":\"<proxyPort>]\nFor example:
\nhttp=foopy:80;ftp=foopy2 - Use HTTP proxy foopy:80 for http:// URLs, and\nHTTP proxy foopy2:80 for ftp:// URLs.foopy:80 - Use HTTP proxy foopy:80 for all URLs.foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing\nover to bar if foopy:80 is unavailable, and after that using no proxy.socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail\nover to the SOCKS5 proxy bar.com if foopy is unavailable.http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no\nproxy if foopy is unavailable.http=foopy;socks=foopy2 - Use HTTP proxy foopy for http URLs, and use\nsocks4://foopy2 for all other URLs.The proxyBypassRules is a comma separated list of rules described below:
[ URL_SCHEME \"://\" ] HOSTNAME_PATTERN [ \":\" <port> ]
Match all hostnames that match the pattern HOSTNAME_PATTERN.
\nExamples:\n\"foobar.com\", \"foobar.com\", \".foobar.com\", \"foobar.com:99\",\n\"https://x..y.com:99\"
\n\".\" HOSTNAME_SUFFIX_PATTERN [ \":\" PORT ]
Match a particular domain suffix.
\nExamples:\n\".google.com\", \".com\", \"http://.google.com\"
\n[ SCHEME \"://\" ] IP_LITERAL [ \":\" PORT ]
Match URLs which are IP address literals.
\nExamples:\n\"127.0.1\", \"[0:0::1]\", \"[::1]\", \"http://[::1]:99\"
\nIP_LITERAL \"/\" PREFIX_LENGTH_IN_BITS
Match any URL that is to an IP literal that falls between the\ngiven range. IP range is specified using CIDR notation.
\nExamples:\n\"192.168.1.1/16\", \"fefe:13::abc/33\".
\n<local>
Match local addresses. The meaning of <local> is whether the\nhost matches one of: \"127.0.0.1\", \"::1\", \"localhost\".
ses.resolveProxy(url)url URLReturns Promise<String> - Resolves with the proxy information for url.
ses.forceReloadProxyConfig()Returns Promise<void> - Resolves when the all internal states of proxy service is reset and the latest proxy configuration is reapplied if it's already available. The pac script will be fetched from pacScript again if the proxy mode is pac_script.
ses.setDownloadPath(path)path String - The download location.Sets download saving directory. By default, the download directory will be the\nDownloads under the respective app folder.
ses.enableNetworkEmulation(options)options Objectoffline Boolean (optional) - Whether to emulate network outage. Defaults\nto false.latency Double (optional) - RTT in ms. Defaults to 0 which will disable\nlatency throttling.downloadThroughput Double (optional) - Download rate in Bps. Defaults to 0\nwhich will disable download throttling.uploadThroughput Double (optional) - Upload rate in Bps. Defaults to 0\nwhich will disable upload throttling.Emulates network with the given configuration for the session.
// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.\nwindow.webContents.session.enableNetworkEmulation({\n latency: 500,\n downloadThroughput: 6400,\n uploadThroughput: 6400\n})\n\n// To emulate a network outage.\nwindow.webContents.session.enableNetworkEmulation({ offline: true })\nses.preconnect(options)options Objecturl String - URL for preconnect. Only the origin is relevant for opening the socket.numSockets Number (optional) - number of sockets to preconnect. Must be between 1 and 6. Defaults to 1.Preconnects the given number of sockets to an origin.
\nses.closeAllConnections()Returns Promise<void> - Resolves when all connections are closed.
Note: It will terminate / fail all requests currently in flight.
\nses.disableNetworkEmulation()Disables any network emulation already active for the session. Resets to\nthe original network configuration.
ses.setCertificateVerifyProc(proc)proc Function | nullrequest Objecthostname Stringcertificate CertificatevalidatedCertificate CertificateverificationResult String - Verification result from chromium.errorCode Integer - Error code.callback FunctionverificationResult Integer - Value can be one of certificate error codes\nfrom here.\nApart from the certificate error codes, the following special codes can be used.0 - Indicates success and disables Certificate Transparency verification.-2 - Indicates failure.-3 - Uses the verification result from chromium.Sets the certificate verify proc for session, the proc will be called with\nproc(request, callback) whenever a server certificate\nverification is requested. Calling callback(0) accepts the certificate,\ncalling callback(-2) rejects it.
Calling setCertificateVerifyProc(null) will revert back to default certificate\nverify proc.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.webContents.session.setCertificateVerifyProc((request, callback) => {\n const { hostname } = request\n if (hostname === 'github.com') {\n callback(0)\n } else {\n callback(-2)\n }\n})\n\n\nNOTE: The result of this procedure is cached by the network service.
\n
ses.setPermissionRequestHandler(handler)handler Function | nullwebContents WebContents - WebContents requesting the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.permission String - The type of requested permission.clipboard-read - Request access to read from the clipboard.media - Request access to media devices such as camera, microphone and speakers.display-capture - Request access to capture the screen.mediaKeySystem - Request access to DRM protected content.geolocation - Request access to user's current location.notifications - Request notification creation and the ability to display them in the user's system tray.midi - Request MIDI access in the webmidi API.midiSysex - Request the use of system exclusive messages in the webmidi API.pointerLock - Request to directly interpret mouse movements as an input method. Click here to know more.fullscreen - Request for the app to enter fullscreen mode.openExternal - Request to open links in external applications.unknown - An unrecognized permission requestcallback FunctionpermissionGranted Boolean - Allow or deny the permission.details Object - Some properties are only available on certain permission types.externalURL String (optional) - The url of the openExternal request.mediaTypes String - The types of media access being requested, elements can be video\nor audiorequestingUrl String - The last URL the requesting frame loadedisMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission requests for the session.\nCalling callback(true) will allow the permission and callback(false) will reject it.\nTo clear the handler, call setPermissionRequestHandler(null). Please note that\nyou must also implement setPermissionCheckHandler to get complete permission handling.\nMost web APIs do a permission check and then make a permission request if the check is denied.
const { session } = require('electron')\nsession.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {\n if (webContents.getURL() === 'some-host' && permission === 'notifications') {\n return callback(false) // denied.\n }\n\n callback(true)\n})\nses.setPermissionCheckHandler(handler)handler Function\\webContents (WebContents | null) - WebContents checking the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin. All cross origin sub frames making permission checks will pass a null webContents to this handler, while certain other permission checks such as notifications checks will always pass null. You should use embeddingOrigin and requestingOrigin to determine what origin the owning frame and the requesting frame are on respectively.permission String - Type of permission check. Valid values are midiSysex, notifications, geolocation, media,mediaKeySystem,midi, pointerLock, fullscreen, openExternal, hid, or serial.requestingOrigin String - The origin URL of the permission checkdetails Object - Some properties are only available on certain permission types.embeddingOrigin String (optional) - The origin of the frame embedding the frame that made the permission check. Only set for cross-origin sub frames making permission checks.securityOrigin String (optional) - The security origin of the media check.mediaType String (optional) - The type of media access being requested, can be video,\naudio or unknownrequestingUrl String (optional) - The last URL the requesting frame loaded. This is not provided for cross-origin sub frames making permission checks.isMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission checks for the session.\nReturning true will allow the permission and false will reject it. Please note that\nyou must also implement setPermissionRequestHandler to get complete permission handling.\nMost web APIs do a permission check and then make a permission request if the check is denied.\nTo clear the handler, call setPermissionCheckHandler(null).
const { session } = require('electron')\nconst url = require('url')\nsession.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {\n return true // granted\n }\n\n return false // denied\n})\nses.setDevicePermissionHandler(handler)handler Function\\details ObjectdeviceType String - The type of device that permission is being requested on, can be hid.origin String - The origin URL of the device permission check.device HIDDevice - the device that permission is being requested for.frame WebFrameMain - WebFrameMain checking the device permission.Sets the handler which can be used to respond to device permission checks for the session.\nReturning true will allow the device to be permitted and false will reject it.\nTo clear the handler, call setDevicePermissionHandler(null).\nThis handler can be used to provide default permissioning to devices without first calling for permission\nto devices (eg via navigator.hid.requestDevice). If this handler is not defined, the default device\npermissions as granted through device selection (eg via navigator.hid.requestDevice) will be used.\nAdditionally, the default behavior of Electron is to store granted device permision through the lifetime\nof the corresponding WebContents. If longer term storage is needed, a developer can store granted device\npermissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nses.clearHostResolverCache()Returns Promise<void> - Resolves when the operation is complete.
Clears the host resolver cache.
\nses.allowNTLMCredentialsForDomains(domains)domains String - A comma-separated list of servers for which\nintegrated authentication is enabled.Dynamically sets whether to always send credentials for HTTP NTLM or Negotiate\nauthentication.
\nconst { session } = require('electron')\n// consider any url ending with `example.com`, `foobar.com`, `baz`\n// for integrated authentication.\nsession.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')\n\n// consider all urls for integrated authentication.\nsession.defaultSession.allowNTLMCredentialsForDomains('*')\nses.setUserAgent(userAgent[, acceptLanguages])userAgent StringacceptLanguages String (optional)Overrides the userAgent and acceptLanguages for this session.
The acceptLanguages must a comma separated ordered list of language codes, for\nexample \"en-US,fr,de,ko,zh-CN,ja\".
This doesn't affect existing WebContents, and each WebContents can use\nwebContents.setUserAgent to override the session-wide user agent.
ses.isPersistent()Returns Boolean - Whether or not this session is a persistent one. The default\nwebContents session of a BrowserWindow is persistent. When creating a session\nfrom a partition, session prefixed with persist: will be persistent, while others\nwill be temporary.
ses.getUserAgent()Returns String - The user agent for this session.
ses.setSSLConfig(config)config ObjectminVersion String (optional) - Can be tls1, tls1.1, tls1.2 or tls1.3. The\nminimum SSL version to allow when connecting to remote servers. Defaults to\ntls1.maxVersion String (optional) - Can be tls1.2 or tls1.3. The maximum SSL version\nto allow when connecting to remote servers. Defaults to tls1.3.disabledCipherSuites Integer - List of cipher suites which\nshould be explicitly prevented from being used in addition to those\ndisabled by the net built-in policy.\nSupported literal forms: 0xAABB, where AA is cipher_suite[0] and BB is\ncipher_suite[1], as defined in RFC 2246, Section 7.4.1.2. Unrecognized but\nparsable cipher suites in this form will not return an error.\nEx: To disable TLS_RSA_WITH_RC4_128_MD5, specify 0x0004, while to\ndisable TLS_ECDH_ECDSA_WITH_RC4_128_SHA, specify 0xC002.\nNote that TLSv1.3 ciphers cannot be disabled using this mechanism.Sets the SSL configuration for the session. All subsequent network requests\nwill use the new configuration. Existing network connections (such as WebSocket\nconnections) will not be terminated, but old sockets in the pool will not be\nreused for new connections.
\nses.getBlobData(identifier)identifier String - Valid UUID.Returns Promise<Buffer> - resolves with blob data.
ses.downloadURL(url)url StringInitiates a download of the resource at url.\nThe API will generate a DownloadItem that can be accessed\nwith the will-download event.
Note: This does not perform any security checks that relate to a page's origin,\nunlike webContents.downloadURL.
ses.createInterruptedDownload(options)options Objectpath String - Absolute path of the download.urlChain String[] - Complete URL chain for the download.mimeType String (optional)offset Integer - Start range for the download.length Integer - Total length of the download.lastModified String (optional) - Last-Modified header value.eTag String (optional) - ETag header value.startTime Double (optional) - Time when download was started in\nnumber of seconds since UNIX epoch.Allows resuming cancelled or interrupted downloads from previous Session.\nThe API will generate a DownloadItem that can be accessed with the will-download\nevent. The DownloadItem will not have any WebContents associated with it and\nthe initial state will be interrupted. The download will start only when the\nresume API is called on the DownloadItem.
ses.clearAuthCache()Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.
ses.setPreloads(preloads)preloads String[] - An array of absolute path to preload scriptsAdds scripts that will be executed on ALL web contents that are associated with\nthis session just before normal preload scripts run.
ses.getPreloads()Returns String[] an array of paths to preload scripts that have been\nregistered.
ses.setSpellCheckerEnabled(enable)enable BooleanSets whether to enable the builtin spell checker.
\nses.isSpellCheckerEnabled()Returns Boolean - Whether the builtin spell checker is enabled.
ses.setSpellCheckerLanguages(languages)languages String[] - An array of language codes to enable the spellchecker for.The built in spellchecker does not automatically detect what language a user is typing in. In order for the\nspell checker to correctly check their words you must call this API with an array of language codes. You can\nget the list of supported language codes with the ses.availableSpellCheckerLanguages property.
Note: On macOS the OS spellchecker is used and will detect your language automatically. This API is a no-op on macOS.
\nses.getSpellCheckerLanguages()Returns String[] - An array of language codes the spellchecker is enabled for. If this list is empty the spellchecker\nwill fallback to using en-US. By default on launch if this setting is an empty list Electron will try to populate this\nsetting with the current OS locale. This setting is persisted across restarts.
Note: On macOS the OS spellchecker is used and has its own list of languages. This API is a no-op on macOS.
\nses.setSpellCheckerDictionaryDownloadURL(url)url String - A base URL for Electron to download hunspell dictionaries from.By default Electron will download hunspell dictionaries from the Chromium CDN. If you want to override this\nbehavior you can use this API to point the dictionary downloader at your own hosted version of the hunspell\ndictionaries. We publish a hunspell_dictionaries.zip file with each release which contains the files you need\nto host here, the file server must be case insensitive you must upload each file twice, once with the case it\nhas in the ZIP file and once with the filename as all lower case.
If the files present in hunspell_dictionaries.zip are available at https://example.com/dictionaries/language-code.bdic\nthen you should call this api with ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Please\nnote the trailing slash. The URL to the dictionaries is formed as ${url}${filename}.
Note: On macOS the OS spellchecker is used and therefore we do not download any dictionary files. This API is a no-op on macOS.
\nses.listWordsInSpellCheckerDictionary()Returns Promise<String[]> - An array of all words in app's custom dictionary.\nResolves when the full dictionary is loaded from disk.
ses.addWordToSpellCheckerDictionary(word)word String - The word you want to add to the dictionaryReturns Boolean - Whether the word was successfully written to the custom dictionary. This API\nwill not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be written to the OS custom dictionary as well
\nses.removeWordFromSpellCheckerDictionary(word)word String - The word you want to remove from the dictionaryReturns Boolean - Whether the word was successfully removed from the custom dictionary. This API\nwill not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be removed from the OS custom dictionary as well
\nses.loadExtension(path[, options])path String - Path to a directory containing an unpacked Chrome extensionoptions Object (optional)allowFileAccess Boolean - Whether to allow the extension to read local files over file://\nprotocol and inject content scripts into file:// pages. This is required e.g. for loading\ndevtools extensions on file:// URLs. Defaults to false.Returns Promise<Extension> - resolves when the extension is loaded.
This method will raise an exception if the extension could not be loaded. If\nthere are warnings when installing the extension (e.g. if the extension\nrequests an API that Electron does not support) then they will be logged to the\nconsole.
\nNote that Electron does not support the full range of Chrome extensions APIs.\nSee Supported Extensions APIs for\nmore details on what is supported.
\nNote that in previous versions of Electron, extensions that were loaded would\nbe remembered for future runs of the application. This is no longer the case:\nloadExtension must be called on every boot of your app if you want the\nextension to be loaded.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.on('ready', async () => {\n await session.defaultSession.loadExtension(\n path.join(__dirname, 'react-devtools'),\n // allowFileAccess is required to load the devtools extension on file:// URLs.\n { allowFileAccess: true }\n )\n // Note that in order to use the React DevTools extension, you'll need to\n // download and unzip a copy of the extension.\n})\nThis API does not support loading packed (.crx) extensions.
\nNote: This API cannot be called before the ready event of the app module\nis emitted.
Note: Loading extensions into in-memory (non-persistent) sessions is not\nsupported and will throw an error.
\nses.removeExtension(extensionId)extensionId String - ID of extension to removeUnloads an extension.
\nNote: This API cannot be called before the ready event of the app module\nis emitted.
ses.getExtension(extensionId)extensionId String - ID of extension to queryReturns Extension | null - The loaded extension with the given ID.
Note: This API cannot be called before the ready event of the app module\nis emitted.
ses.getAllExtensions()Returns Extension[] - A list of all loaded extensions.
Note: This API cannot be called before the ready event of the app module\nis emitted.
ses.getStoragePath()A String | null indicating the absolute file system path where data for this\nsession is persisted on disk. For in memory sessions this returns null.
The following properties are available on instances of Session:
ses.availableSpellCheckerLanguages ReadonlyA String[] array which consists of all the known available spell checker languages. Providing a language\ncode to the setSpellCheckerLanguages API that isn't in this array will result in an error.
ses.spellCheckerEnabledA Boolean indicating whether builtin spell checker is enabled.
ses.storagePath ReadonlyA String | null indicating the absolute file system path where data for this\nsession is persisted on disk. For in memory sessions this returns null.
ses.cookies ReadonlyA Cookies object for this session.
ses.serviceWorkers ReadonlyA ServiceWorkers object for this session.
ses.webRequest ReadonlyA WebRequest object for this session.
ses.protocol ReadonlyA Protocol object for this session.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const protocol = session.fromPartition('some-partition').protocol\n if (!protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })) {\n console.error('Failed to register protocol')\n }\n})\nses.netLog ReadonlyA NetLog object for this session.
const { app, session } = require('electron')\n\napp.whenReady().then(async () => {\n const netLog = session.fromPartition('some-partition').netLog\n netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nDebug symbols allow you to have better debugging sessions. They have information\nabout the functions contained in executables and dynamic libraries and provide\nyou with information to get clean call stacks. A Symbol Server allows the\ndebugger to load the correct symbols, binaries and sources automatically without\nforcing users to download large debugging files. The server functions like\nMicrosoft's symbol server so the\ndocumentation there can be useful.
\nNote that because released Electron builds are heavily optimized, debugging is\nnot always easy. The debugger will not be able to show you the content of all\nvariables and the execution path can seem strange because of inlining, tail\ncalls, and other compiler optimizations. The only workaround is to build an\nunoptimized local build.
\nThe official symbol server URL for Electron is\nhttps://symbols.electronjs.org.\nYou cannot visit this URL directly, you must add it to the symbol path of your\ndebugging tool. In the examples below, a local cache directory is used to avoid\nrepeatedly fetching the PDB from the server. Replace c:\\code\\symbols with an\nappropriate cache directory on your machine.
The Windbg symbol path is configured with a string value delimited with asterisk\ncharacters. To use only the Electron symbol server, add the following entry to\nyour symbol path (Note: you can replace c:\\code\\symbols with any writable\ndirectory on your computer, if you'd prefer a different location for downloaded\nsymbols):
SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\nSet this string as _NT_SYMBOL_PATH in the environment, using the Windbg menus,\nor by typing the .sympath command. If you would like to get symbols from\nMicrosoft's symbol server as well, you should list that first:
SRV*c:\\code\\symbols\\*https://msdl.microsoft.com/download/symbols;SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\n![\"Tools](\"https://mdn.mozillademos.org/files/733/symbol-server-vc8express-menu.jpg\")
Options\">\n![\"Symbols](\"https://mdn.mozillademos.org/files/2497/2005_options.gif\")
Type the following commands in Windbg to print why symbols are not loading:
\n> !sym noisy\n> .reload /f electron.exe\nThe ShareMenu class creates Share Menu on macOS, which can be\nused to share information from the current context to apps, social media\naccounts, and other services.
For including the share menu as a submenu of other menus, please use the\nshareMenu role of MenuItem.
\n\nCreate share menu on macOS.
\n
Process: Main
\nnew ShareMenu(sharingItem)sharingItem SharingItem - The item to share.Creates a new share menu.
\nThe shareMenu object has the following instance methods:
shareMenu.popup([options])options PopupOptions (optional)browserWindow BrowserWindow (optional) - Default is the focused window.x Number (optional) - Default is the current mouse cursor position.\nMust be declared if y is declared.y Number (optional) - Default is the current mouse cursor position.\nMust be declared if x is declared.positioningItem Number (optional) macOS - The index of the menu item to\nbe positioned under the mouse cursor at the specified coordinates. Default\nis -1.callback Function (optional) - Called when menu is closed.Pops up this menu as a context menu in the BrowserWindow.
shareMenu.closePopup([browserWindow])browserWindow BrowserWindow (optional) - Default is the focused window.Closes the context menu in the browserWindow.
id String - The unique id of the shared worker.url String - The url of the shared worker.texts String - An array of text to share.filePaths String - An array of files to share.urls String - An array of URLs to share.\n\nManage files and URLs using their default applications.
\n
Process: Main, Renderer (non-sandboxed only)
\nThe shell module provides functions related to desktop integration.
An example of opening a URL in the user's default browser:
\nconst { shell } = require('electron')\n\nshell.openExternal('https://github.com')\nNote: While the shell module can be used in the renderer process, it will not function in a sandboxed renderer.
The shell module has the following methods:
shell.showItemInFolder(fullPath)fullPath StringShow the given file in a file manager. If possible, select the file.
\nshell.openPath(path)path StringReturns Promise<String> - Resolves with a string containing the error message corresponding to the failure if a failure occurred, otherwise \"\".
Open the given file in the desktop's default manner.
\nshell.openExternal(url[, options])url String - Max 2081 characters on windows.options Object (optional)activate Boolean (optional) macOS - true to bring the opened application to the foreground. The default is true.workingDirectory String (optional) Windows - The working directory.Returns Promise<void>
Open the given external protocol URL in the desktop's default manner. (For example, mailto: URLs in the user's default mail agent).
\nshell.trashItem(path)path String - path to the item to be moved to the trash.Returns Promise<void> - Resolves when the operation has been completed.\nRejects if there was an error while deleting the requested item.
This moves a path to the OS-specific trash location (Trash on macOS, Recycle\nBin on Windows, and a desktop-environment-specific location on Linux).
\nshell.beep()Play the beep sound.
\nshell.writeShortcutLink(shortcutPath[, operation], options) WindowsshortcutPath Stringoperation String (optional) - Default is create, can be one of following:create - Creates a new shortcut, overwriting if necessary.update - Updates specified properties only on an existing shortcut.replace - Overwrites an existing shortcut, fails if the shortcut doesn't\nexist.options ShortcutDetailsReturns Boolean - Whether the shortcut was created successfully.
Creates or updates a shortcut link at shortcutPath.
shell.readShortcutLink(shortcutPath) WindowsshortcutPath StringReturns ShortcutDetails
Resolves the shortcut link at shortcutPath.
An exception will be thrown when any error happens.
", "title": "shell", "description": "Manage files and URLs using their default applications." }, "/docs/api/structures/shortcut-details": { "locale": "en-US", "slug": "shortcut-details", "href": "/docs/api/structures/shortcut-details", "crowdinFileId": "256509", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/shortcut-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "target String - The target to launch from this shortcut.cwd String (optional) - The working directory. Default is empty.args String (optional) - The arguments to be applied to target when\nlaunching from this shortcut. Default is empty.description String (optional) - The description of the shortcut. Default\nis empty.icon String (optional) - The path to the icon, can be a DLL or EXE. icon\nand iconIndex have to be set together. Default is empty, which uses the\ntarget's icon.iconIndex Number (optional) - The resource ID of icon when icon is a\nDLL or EXE. Default is 0.appUserModelId String (optional) - The Application User Model ID. Default\nis empty.toastActivatorClsid String (optional) - The Application Toast Activator CLSID. Needed\nfor participating in Action Center.width Numberheight NumberThis guide provides information on how to package your Electron application\nfor any Snapcraft environment, including the Ubuntu Software Center.
\nTogether with the broader Linux community, Canonical aims to fix many of the\ncommon software installation problems with the snapcraft\nproject. Snaps are containerized software packages that include required\ndependencies, auto-update, and work on all major Linux distributions without\nsystem modification.
There are three ways to create a .snap file:
1) Using electron-forge or\nelectron-builder, both tools that come with snap\nsupport out of the box. This is the easiest option.\n2) Using electron-installer-snap, which takes electron-packager's output.\n3) Using an already created .deb package.
In some cases, you will need to have the snapcraft tool installed.\nInstructions to install snapcraft for your particular distribution are\navailable here.
electron-installer-snapThe module works like electron-winstaller and similar\nmodules in that its scope is limited to building snap packages. You can install\nit with:
npm install --save-dev electron-installer-snap\nPackage the application using electron-packager (or a\nsimilar tool). Make sure to remove node_modules that you don't need in your\nfinal application, since any module you don't actually need will increase\nyour application's size.
The output should look roughly like this:
\n.\n└── dist\n └── app-linux-x64\n ├── LICENSE\n ├── LICENSES.chromium.html\n ├── content_shell.pak\n ├── app\n ├── icudtl.dat\n ├── libgcrypt.so.11\n ├── libnode.so\n ├── locales\n ├── resources\n ├── v8_context_snapshot.bin\n └── version\nelectron-installer-snapFrom a terminal that has snapcraft in its PATH, run electron-installer-snap\nwith the only required parameter --src, which is the location of your packaged\nElectron application created in the first step.
npx electron-installer-snap --src=out/myappname-linux-x64\nIf you have an existing build pipeline, you can use electron-installer-snap\nprogrammatically. For more information, see the Snapcraft API docs.
const snap = require('electron-installer-snap')\n\nsnap(options)\n .then(snapPath => console.log(`Created snap at ${snapPath}!`))\nsnapcraft with electron-packagerCreate your project directory and add the following to snap/snapcraft.yaml:
name: electron-packager-hello-world\nversion: '0.1'\nsummary: Hello World Electron app\ndescription: |\n Simple Hello World Electron app as an example\nbase: core18\nconfinement: strict\ngrade: stable\n\napps:\n electron-packager-hello-world:\n command: electron-quick-start/electron-quick-start --no-sandbox\n extensions: [gnome-3-34]\n plugs:\n - browser-support\n - network\n - network-bind\n environment:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n TMPDIR: $XDG_RUNTIME_DIR\n\nparts:\n electron-quick-start:\n plugin: nil\n source: https://github.com/electron/electron-quick-start.git\n override-build: |\n npm install electron electron-packager\n npx electron-packager . --overwrite --platform=linux --output=release-build --prune=true\n cp -rv ./electron-quick-start-linux-* $SNAPCRAFT_PART_INSTALL/electron-quick-start\n build-snaps:\n - node/14/stable\n build-packages:\n - unzip\n stage-packages:\n - libnss3\n - libnspr4\nIf you want to apply this example to an existing project:
\nsource: https://github.com/electron/electron-quick-start.git with source: ..electron-quick-start with your project's name.$ snapcraft\n\n<output snipped>\nSnapped electron-packager-hello-world_0.1_amd64.snap\nsudo snap install electron-packager-hello-world_0.1_amd64.snap --dangerous\nelectron-packager-hello-world\nSnapcraft is capable of taking an existing .deb file and turning it into\na .snap file. The creation of a snap is configured using a snapcraft.yaml\nfile that describes the sources, dependencies, description, and other core\nbuilding blocks.
If you do not already have a .deb package, using electron-installer-snap\nmight be an easier path to create snap packages. However, multiple solutions\nfor creating Debian packages exist, including electron-forge,\nelectron-builder or\nelectron-installer-debian.
For more information on the available configuration options, see the\ndocumentation on the snapcraft syntax.\nLet's look at an example:
\nname: myApp\nversion: '2.0.0'\nsummary: A little description for the app.\ndescription: |\n You know what? This app is amazing! It does all the things\n for you. Some say it keeps you young, maybe even happy.\n\ngrade: stable\nconfinement: classic\n\nparts:\n slack:\n plugin: dump\n source: my-deb.deb\n source-type: deb\n after:\n - desktop-gtk3\n stage-packages:\n - libasound2\n - libnotify4\n - libnspr4\n - libnss3\n - libpcre3\n - libpulse0\n - libxss1\n - libxtst6\n electron-launch:\n plugin: dump\n source: files/\n prepare: |\n chmod +x bin/electron-launch\n\napps:\n myApp:\n command: bin/electron-launch $SNAP/usr/lib/myApp/myApp\n desktop: usr/share/applications/myApp.desktop\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n environment:\n TMPDIR: $XDG_RUNTIME_DIR\nAs you can see, the snapcraft.yaml instructs the system to launch a file\ncalled electron-launch. In this example, it passes information on to the\napp's binary:
\nexec \"$@\" --executed-from=\"$(pwd)\" --pid=$$ > /dev/null 2>&1 &\nAlternatively, if you're building your snap with strict confinement, you\ncan use the desktop-launch command:
apps:\n myApp:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n command: env TMPDIR=$XDG_RUNTIME_DIR PATH=/usr/local/bin:${PATH} ${SNAP}/bin/desktop-launch $SNAP/myApp/desktop\n desktop: usr/share/applications/desktop.desktop\nThe source code of Electron is separated into a few parts, mostly\nfollowing Chromium on the separation conventions.
\nYou may need to become familiar with Chromium's multi-process\narchitecture\nto understand the source code better.
\nElectron\n├── build/ - Build configuration files needed to build with GN.\n├── buildflags/ - Determines the set of features that can be conditionally built.\n├── chromium_src/ - Source code copied from Chromium that isn't part of the content layer.\n├── default_app/ - A default app run when Electron is started without\n| providing a consumer app.\n├── docs/ - Electron's documentation.\n| ├── api/ - Documentation for Electron's externally-facing modules and APIs.\n| ├── development/ - Documentation to aid in developing for and with Electron.\n| ├── fiddles/ - A set of code snippets one can run in Electron Fiddle.\n| ├── images/ - Images used in documentation.\n| └── tutorial/ - Tutorial documents for various aspects of Electron.\n├── lib/ - JavaScript/TypeScript source code.\n| ├── browser/ - Main process initialization code.\n| | ├── api/ - API implementation for main process modules.\n| | └── remote/ - Code related to the remote module as it is\n| | used in the main process.\n| ├── common/ - Relating to logic needed by both main and renderer processes.\n| | └── api/ - API implementation for modules that can be used in\n| | both the main and renderer processes\n| ├── isolated_renderer/ - Handles creation of isolated renderer processes when\n| | contextIsolation is enabled.\n| ├── renderer/ - Renderer process initialization code.\n| | ├── api/ - API implementation for renderer process modules.\n| | ├── extension/ - Code related to use of Chrome Extensions\n| | | in Electron's renderer process.\n| | ├── remote/ - Logic that handles use of the remote module in\n| | | the main process.\n| | └── web-view/ - Logic that handles the use of webviews in the\n| | renderer process.\n| ├── sandboxed_renderer/ - Logic that handles creation of sandboxed renderer\n| | | processes.\n| | └── api/ - API implementation for sandboxed renderer processes.\n| └── worker/ - Logic that handles proper functionality of Node.js\n| environments in Web Workers.\n├── patches/ - Patches applied on top of Electron's core dependencies\n| | in order to handle differences between our use cases and\n| | default functionality.\n| ├── boringssl/ - Patches applied to Google's fork of OpenSSL, BoringSSL.\n| ├── chromium/ - Patches applied to Chromium.\n| ├── node/ - Patches applied on top of Node.js.\n| └── v8/ - Patches applied on top of Google's V8 engine.\n├── shell/ - C++ source code.\n| ├── app/ - System entry code.\n| ├── browser/ - The frontend including the main window, UI, and all of the\n| | | main process things. This talks to the renderer to manage web\n| | | pages.\n| | ├── ui/ - Implementation of UI stuff for different platforms.\n| | | ├── cocoa/ - Cocoa specific source code.\n| | | ├── win/ - Windows GUI specific source code.\n| | | └── x/ - X11 specific source code.\n| | ├── api/ - The implementation of the main process APIs.\n| | ├── net/ - Network related code.\n| | ├── mac/ - Mac specific Objective-C source code.\n| | └── resources/ - Icons, platform-dependent files, etc.\n| ├── renderer/ - Code that runs in renderer process.\n| | └── api/ - The implementation of renderer process APIs.\n| └── common/ - Code that used by both the main and renderer processes,\n| | including some utility functions and code to integrate node's\n| | message loop into Chromium's message loop.\n| └── api/ - The implementation of common APIs, and foundations of\n| Electron's built-in modules.\n├── spec/ - Components of Electron's test suite run in the renderer process.\n├── spec-main/ - Components of Electron's test suite run in the main process.\n└── BUILD.gn - Building rules of Electron.\nscript/create-dist.py script\nwhen creating a distribution.ninja.script/ - The set of all scripts Electron runs for a variety of purposes.\n├── codesign/ - Fakes codesigning for Electron apps; used for testing.\n├── lib/ - Miscellaneous python utility scripts.\n└── release/ - Scripts run during Electron's release process.\n ├── notes/ - Generates release notes for new Electron versions.\n └── uploaders/ - Uploads various release-related files during release.\nElectron has built-in support for Chromium's spellchecker since Electron 8. On Windows and Linux this is powered by Hunspell dictionaries, and on macOS it makes use of the native spellchecker APIs.
\nFor Electron 9 and higher the spellchecker is enabled by default. For Electron 8 you need to enable it in webPreferences.
const myWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: true\n }\n})\nOn macOS as we use the native APIs there is no way to set the language that the spellchecker uses. By default on macOS the native spellchecker will automatically detect the language being used for you.
\nFor Windows and Linux there are a few Electron APIs you should use to set the languages for the spellchecker.
\n// Sets the spellchecker to check English US and French\nmyWindow.session.setSpellCheckerLanguages(['en-US', 'fr'])\n\n// An array of all available language codes\nconst possibleLanguages = myWindow.session.availableSpellCheckerLanguages\nBy default the spellchecker will enable the language matching the current OS locale.
\nAll the required information to generate a context menu is provided in the context-menu event on each webContents instance. A small example\nof how to make a context menu with this information is provided below.
const { Menu, MenuItem } = require('electron')\n\nmyWindow.webContents.on('context-menu', (event, params) => {\n const menu = new Menu()\n\n // Add each spelling suggestion\n for (const suggestion of params.dictionarySuggestions) {\n menu.append(new MenuItem({\n label: suggestion,\n click: () => mainWindow.webContents.replaceMisspelling(suggestion)\n }))\n }\n\n // Allow users to add the misspelled word to the dictionary\n if (params.misspelledWord) {\n menu.append(\n new MenuItem({\n label: 'Add to dictionary',\n click: () => mainWindow.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord)\n })\n )\n }\n\n menu.popup()\n})\nAlthough the spellchecker itself does not send any typings, words or user input to Google services the hunspell dictionary files are downloaded from a Google CDN by default. If you want to avoid this you can provide an alternative URL to download the dictionaries from.
\nmyWindow.session.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/')\nCheck out the docs for session.setSpellCheckerDictionaryDownloadURL for more information on where to get the dictionary files from and how you need to host them.
These are the guidelines for writing Electron documentation.
\n#-level title at the top.##-level headings.# in the heading according to\ntheir nesting depth.Using Quick Start as example:
# Quick Start\n\n...\n\n## Main process\n\n...\n\n## Renderer process\n\n...\n\n## Run your app\n\n...\n\n### Run as a distribution\n\n...\n\n### Manually downloaded Electron binary\n\n...\nFor API references, there are exceptions to this rule.
\nThis repository uses the markdownlint package to enforce consistent\nMarkdown styling. For the exact rules, see the .markdownlint.json file in the root\nfolder.
There are a few style guidelines that aren't covered by the linter rules:
\n\nsh instead of cmd in code blocks (due to the syntax highlighter).js and javascript code blocks are linted with\nstandard-markdown.The following rules only apply to the documentation of APIs.
\nEach module's API doc must use the actual object name returned by require('electron')\nas its title (such as BrowserWindow, autoUpdater, and session).
Directly under the page title, add a one-line description of the module\nas a markdown quote (beginning with >).
Using the session module as an example:
# session\n\n> Manage browser sessions, cookies, cache, proxy settings, etc.\nFor modules that are not classes, their methods and events must be listed under\nthe ## Methods and ## Events chapters.
Using autoUpdater as an example:
# autoUpdater\n\n## Events\n\n### Event: 'error'\n\n## Methods\n\n### `autoUpdater.setFeedURL(url[, requestHeaders])`\n## Class: TheClassName chapter.###-level headings.### Static Methods chapter.### Instance Methods chapter.[TYPE] - [Return description]\"Object, its structure can be specified using a colon\nfollowed by a newline then an unordered list of properties in the same style as\nfunction parameters.### Instance Events chapter.### Instance Properties chapter.Using the Session and Cookies classes as an example:
# session\n\n## Methods\n\n### session.fromPartition(partition)\n\n## Static Properties\n\n### session.defaultSession\n\n## Class: Session\n\n### Instance Events\n\n#### Event: 'will-download'\n\n### Instance Methods\n\n#### `ses.getCacheSize()`\n\n### Instance Properties\n\n#### `ses.cookies`\n\n## Class: Cookies\n\n### Instance Methods\n\n#### `cookies.get(filter, callback)`\nThe methods chapter must be in the following form:
\n### `objectName.methodName(required[, optional]))`\n\n* `required` String - A parameter description.\n* `optional` Integer (optional) - Another parameter description.\n\n...\nThe heading can be ### or ####-levels depending on whether the method\nbelongs to a module or a class.
For modules, the objectName is the module's name. For classes, it must be the\nname of the instance of the class, and must not be the same as the module's\nname.
For example, the methods of the Session class under the session module must\nuse ses as the objectName.
Optional arguments are notated by square brackets [] surrounding the optional\nargument as well as the comma required if this optional argument follows another\nargument:
required[, optional]\nMore detailed information on each of the arguments is noted in an unordered list\nbelow the method. The type of argument is notated by either JavaScript primitives\n(e.g. String, Promise, or Object), a custom API structure like Electron's\nCookie, or the wildcard any.
If the argument is of type Array, use [] shorthand with the type of value\ninside the array (for example,any[] or String[]).
If the argument is of type Promise, parametrize the type with what the promise\nresolves to (for example, Promise<void> or Promise<String>).
If an argument can be of multiple types, separate the types with |.
The description for Function type arguments should make it clear how it may be\ncalled and list the types of the parameters that will be passed to it.
If an argument or a method is unique to certain platforms, those platforms are\ndenoted using a space-delimited italicized list following the datatype. Values\ncan be macOS, Windows or Linux.
* `animate` Boolean (optional) _macOS_ _Windows_ - Animate the thing.\nThe events chapter must be in following form:
\n### Event: 'wake-up'\n\nReturns:\n\n* `time` String\n\n...\nThe heading can be ### or ####-levels depending on whether the event\nbelongs to a module or a class.
The arguments of an event follow the same rules as methods.
\nThe properties chapter must be in following form:
\n### session.defaultSession\n\n...\nThe heading can be ### or ####-levels depending on whether the property\nbelongs to a module or a class.
See electron/i18n
", "title": "Electron Documentation Style Guide", "description": "" }, "/docs/tutorial/support": { "locale": "en-US", "slug": "support", "href": "/docs/tutorial/support", "crowdinFileId": "256253", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/support.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "If you have a security concern,\nplease see the security document.
\nIf you're looking for programming help,\nfor answers to questions,\nor to join in discussion with other developers who use Electron,\nyou can interact with the community in these locations:
\nElectron's Discord has channels for:electron category on the Atom forums#electron channel on Atom's Slackelectron-ru (Russian)electron-br (Brazilian Portuguese)electron-kr (Korean)electron-jp (Japanese)electron-tr (Turkish)electron-id (Indonesia)electron-pl (Poland)If you'd like to contribute to Electron,\nsee the contributing document.
\nIf you've found a bug in a supported version of Electron,\nplease report it with the issue tracker.
\nawesome-electron\nis a community-maintained list of useful example apps,\ntools and resources.
\nNote: Beginning in September 2021 with Electron 15, the Electron team\nwill temporarily support the latest four stable major versions. This\nextended support is intended to help Electron developers transition to\nthe new eight week release cadence, and will continue until May 2022, with\nthe release of Electron 19. At that time, the Electron team will drop support\nback to the latest three stable major versions.
\nThe latest three stable major versions are supported by the Electron team.\nFor example, if the latest release is 6.1.x, then the 5.0.x as well\nas the 4.2.x series are supported. We only support the latest minor release\nfor each stable release series. This means that in the case of a security fix\n6.1.x will receive the fix, but we will not release a new version of 6.0.x.
\nThe latest stable release unilaterally receives all fixes from main,\nand the version prior to that receives the vast majority of those fixes\nas time and bandwidth warrants. The oldest supported release line will receive\nonly security fixes directly.
All supported release lines will accept external pull requests to backport\nfixes previously merged to main, though this may be on a case-by-case\nbasis for some older supported lines. All contested decisions around release\nline backports will be resolved by the Releases Working Group as an agenda item at their weekly meeting the week the backport PR is raised.
When an API is changed or removed in a way that breaks existing functionality, the\nprevious functionality will be supported for a minimum of two major versions when\npossible before being removed. For example, if a function takes three arguments,\nand that number is reduced to two in major version 10, the three-argument version would\ncontinue to work until, at minimum, major version 12. Past the minimum two-version\nthreshold, we will attempt to support backwards compatibility beyond two versions\nuntil the maintainers feel the maintenance burden is too high to continue doing so.
\nWhen a release branch reaches the end of its support cycle, the series\nwill be deprecated in NPM and a final end-of-support release will be\nmade. This release will add a warning to inform that an unsupported\nversion of Electron is in use.
\nThese steps are to help app developers learn when a branch they're\nusing becomes unsupported, but without being excessively intrusive\nto end users.
\nIf an application has exceptional circumstances and needs to stay\non an unsupported series of Electron, developers can silence the\nend-of-support warning by omitting the final release from the app's\npackage.json devDependencies. For example, since the 1-6-x series\nended with an end-of-support 1.6.18 release, developers could choose\nto stay in the 1-6-x series without warnings with devDependency of\n\"electron\": 1.6.0 - 1.6.17.
Following platforms are supported by Electron:
\nOnly 64bit binaries are provided for macOS, and the minimum macOS version\nsupported is macOS 10.11 (El Capitan).
\nNative support for Apple Silicon (arm64) devices was added in Electron 11.0.0.
Windows 7 and later are supported, older operating systems are not supported\n(and do not work).
\nBoth ia32 (x86) and x64 (amd64) binaries are provided for Windows.\nNative support for Windows on Arm (arm64) devices was added in Electron 6.0.8..\nRunning apps packaged with previous versions is possible using the ia32 binary.
The prebuilt binaries of Electron are built on Ubuntu 18.04.
\nWhether the prebuilt binary can run on a distribution depends on whether the\ndistribution includes the libraries that Electron is linked to on the building\nplatform, so only Ubuntu 18.04 is guaranteed to work, but following platforms\nare also verified to be able to run the prebuilt binaries of Electron:
\n\n\nHow to use Node.js and Electron APIs.
\n
All of Node.js's built-in modules are available in\nElectron and third-party node modules also fully supported as well (including\nthe native modules).
\nElectron also provides some extra built-in modules for developing native\ndesktop applications. Some modules are only available in the main process, some\nare only available in the renderer process (web page), and some can be used in\neither process type.
\nThe basic rule is: if a module is GUI or low-level system related, then\nit should be only available in the main process. You need to be familiar with\nthe concept of main process vs. renderer process\nscripts to be able to use those modules.
\nThe main process script is like a normal Node.js script:
\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL('https://github.com')\n})\nThe renderer process is no different than a normal web page, except for the\nextra ability to use node modules if nodeIntegration is enabled:
\n<html>\n<body>\n<script>\n const fs = require('fs')\n console.log(fs.readFileSync(__filename, 'utf8'))\n</script>\n</body>\n</html>\nAs of 0.37, you can use\ndestructuring assignment to make it easier to use\nbuilt-in modules.
\nconst { app, BrowserWindow } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nIf you need the entire electron module, you can require it and then using\ndestructuring to access the individual modules from electron.
const electron = require('electron')\nconst { app, BrowserWindow } = electron\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nThis is equivalent to the following code:
\nconst electron = require('electron')\nconst app = electron.app\nconst BrowserWindow = electron.BrowserWindow\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\n\n\nGet system preferences.
\n
Process: Main
\nconst { systemPreferences } = require('electron')\nconsole.log(systemPreferences.isDarkMode())\nThe systemPreferences object emits the following events:
Returns:
\nevent EventnewColor String - The new RGBA color the user assigned to be their system\naccent color.Returns:
\nevent EventReturns:
\nevent EventinvertedColorScheme Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is being used, false otherwise.Deprecated: Should use the new updated event on the nativeTheme module.
Returns:
\nevent EventhighContrastColorScheme Boolean - true if a high contrast theme is being used, false otherwise.Deprecated: Should use the new updated event on the nativeTheme module.
systemPreferences.isDarkMode() macOS Windows DeprecatedReturns Boolean - Whether the system is in Dark Mode.
Deprecated: Should use the new nativeTheme.shouldUseDarkColors API.
systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOSReturns Boolean - Whether the Swipe between pages setting is on.
systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOSevent StringuserInfo Record<String, any>deliverImmediately Boolean (optional) - true to post notifications immediately even when the subscribing app is inactive.Posts event as native notifications of macOS. The userInfo is an Object\nthat contains the user information dictionary sent along with the notification.
systemPreferences.postLocalNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>Posts event as native notifications of macOS. The userInfo is an Object\nthat contains the user information dictionary sent along with the notification.
systemPreferences.postWorkspaceNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>Posts event as native notifications of macOS. The userInfo is an Object\nthat contains the user information dictionary sent along with the notification.
systemPreferences.subscribeNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object StringReturns Number - The ID of this subscription
Subscribes to native notifications of macOS, callback will be called with\ncallback(event, userInfo) when the corresponding event happens. The\nuserInfo is an Object that contains the user information dictionary sent\nalong with the notification. The object is the sender of the notification,\nand only supports NSString values for now.
The id of the subscriber is returned, which can be used to unsubscribe the\nevent.
Under the hood this API subscribes to NSDistributedNotificationCenter,\nexample values of event are:
AppleInterfaceThemeChangedNotificationAppleAquaColorVariantChangedAppleColorPreferencesChangedNotificationAppleShowScrollBarsSettingChangedsystemPreferences.subscribeLocalNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object StringReturns Number - The ID of this subscription
Same as subscribeNotification, but uses NSNotificationCenter for local defaults.\nThis is necessary for events such as NSUserDefaultsDidChangeNotification.
systemPreferences.subscribeWorkspaceNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object StringReturns Number - The ID of this subscription
Same as subscribeNotification, but uses NSWorkspace.sharedWorkspace.notificationCenter.\nThis is necessary for events such as NSWorkspaceDidActivateApplicationNotification.
systemPreferences.unsubscribeNotification(id) macOSid IntegerRemoves the subscriber with id.
systemPreferences.unsubscribeLocalNotification(id) macOSid IntegerSame as unsubscribeNotification, but removes the subscriber from NSNotificationCenter.
systemPreferences.unsubscribeWorkspaceNotification(id) macOSid IntegerSame as unsubscribeNotification, but removes the subscriber from NSWorkspace.sharedWorkspace.notificationCenter.
systemPreferences.registerDefaults(defaults) macOSdefaults Record<String, String | Boolean | Number> - a dictionary of (key: value) user defaultsAdd the specified defaults to your application's NSUserDefaults.
systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOSkey Stringtype Type - Can be string, boolean, integer, float, double,\nurl, array or dictionary.Returns UserDefaultTypes[Type] - The value of key in NSUserDefaults.
Some popular key and types are:
AppleInterfaceStyle: stringAppleAquaColorVariant: integerAppleHighlightColor: stringAppleShowScrollBars: stringNSNavRecentPlaces: arrayNSPreferredWebServices: dictionaryNSUserDictionaryReplacementItems: arraysystemPreferences.setUserDefault(key, type, value) macOSkey Stringtype String - Can be string, boolean, integer, float, double, url, array or dictionary.value StringSet the value of key in NSUserDefaults.
Note that type should match actual type of value. An exception is thrown\nif they don't.
Some popular key and types are:
ApplePressAndHoldEnabled: booleansystemPreferences.removeUserDefault(key) macOSkey StringRemoves the key in NSUserDefaults. This can be used to restore the default\nor global value of a key previously set with setUserDefault.
systemPreferences.isAeroGlassEnabled() WindowsReturns Boolean - true if DWM composition (Aero Glass) is\nenabled, and false otherwise.
An example of using it to determine if you should create a transparent window or\nnot (transparent windows won't work correctly when DWM composition is disabled):
\nconst { BrowserWindow, systemPreferences } = require('electron')\nconst browserOptions = { width: 1000, height: 800 }\n\n// Make the window transparent only if the platform supports it.\nif (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {\n browserOptions.transparent = true\n browserOptions.frame = false\n}\n\n// Create the window.\nconst win = new BrowserWindow(browserOptions)\n\n// Navigate.\nif (browserOptions.transparent) {\n win.loadURL(`file://${__dirname}/index.html`)\n} else {\n // No transparency, so we load a fallback that uses basic styles.\n win.loadURL(`file://${__dirname}/fallback.html`)\n}\nsystemPreferences.getAccentColor() Windows macOSReturns String - The users current system wide accent color preference in RGBA\nhexadecimal form.
const color = systemPreferences.getAccentColor() // `\"aabbccdd\"`\nconst red = color.substr(0, 2) // \"aa\"\nconst green = color.substr(2, 2) // \"bb\"\nconst blue = color.substr(4, 2) // \"cc\"\nconst alpha = color.substr(6, 2) // \"dd\"\nThis API is only available on macOS 10.14 Mojave or newer.
\nsystemPreferences.getColor(color) Windows macOScolor String - One of the following values:3d-dark-shadow - Dark shadow for three-dimensional display elements.3d-face - Face color for three-dimensional display elements and for dialog\nbox backgrounds.3d-highlight - Highlight color for three-dimensional display elements.3d-light - Light color for three-dimensional display elements.3d-shadow - Shadow color for three-dimensional display elements.active-border - Active window border.active-caption - Active window title bar. Specifies the left side color in\nthe color gradient of an active window's title bar if the gradient effect is\nenabled.active-caption-gradient - Right side color in the color gradient of an\nactive window's title bar.app-workspace - Background color of multiple document interface (MDI)\napplications.button-text - Text on push buttons.caption-text - Text in caption, size box, and scroll bar arrow box.desktop - Desktop background color.disabled-text - Grayed (disabled) text.highlight - Item(s) selected in a control.highlight-text - Text of item(s) selected in a control.hotlight - Color for a hyperlink or hot-tracked item.inactive-border - Inactive window border.inactive-caption - Inactive window caption. Specifies the left side color\nin the color gradient of an inactive window's title bar if the gradient\neffect is enabled.inactive-caption-gradient - Right side color in the color gradient of an\ninactive window's title bar.inactive-caption-text - Color of text in an inactive caption.info-background - Background color for tooltip controls.info-text - Text color for tooltip controls.menu - Menu background.menu-highlight - The color used to highlight menu items when the menu\nappears as a flat menu.menubar - The background color for the menu bar when menus appear as flat\nmenus.menu-text - Text in menus.scrollbar - Scroll bar gray area.window - Window background.window-frame - Window frame.window-text - Text in windows.alternate-selected-control-text - The text on a selected surface in a list or table. deprecatedcontrol-background - The background of a large interface element, such as a browser or table.control - The surface of a control.control-text -The text of a control that isn’t disabled.disabled-control-text - The text of a control that’s disabled.find-highlight - The color of a find indicator.grid - The gridlines of an interface element such as a table.header-text - The text of a header cell in a table.highlight - The virtual light source onscreen.keyboard-focus-indicator - The ring that appears around the currently focused control when using the keyboard for interface navigation.label - The text of a label containing primary content.link - A link to other content.placeholder-text - A placeholder string in a control or text view.quaternary-label - The text of a label of lesser importance than a tertiary label such as watermark text.scrubber-textured-background - The background of a scrubber in the Touch Bar.secondary-label - The text of a label of lesser importance than a normal label such as a label used to represent a subheading or additional information.selected-content-background - The background for selected content in a key window or view.selected-control - The surface of a selected control.selected-control-text - The text of a selected control.selected-menu-item-text - The text of a selected menu.selected-text-background - The background of selected text.selected-text - Selected text.separator - A separator between different sections of content.shadow - The virtual shadow cast by a raised object onscreen.tertiary-label - The text of a label of lesser importance than a secondary label such as a label used to represent disabled text.text-background - Text background.text - The text in a document.under-page-background - The background behind a document's content.unemphasized-selected-content-background - The selected content in a non-key window or view.unemphasized-selected-text-background - A background for selected text in a non-key window or view.unemphasized-selected-text - Selected text in a non-key window or view.window-background - The background of a window.window-frame-text - The text in the window's titlebar area.Returns String - The system color setting in RGB hexadecimal form (#ABCDEF).\nSee the Windows docs and the macOS docs for more details.
The following colors are only available on macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, and unemphasized-selected-text.
systemPreferences.getSystemColor(color) macOScolor String - One of the following values:bluebrowngraygreenorangepinkpurpleredyellowReturns String - The standard system color formatted as #RRGGBBAA.
Returns one of several standard system colors that automatically adapt to vibrancy and changes in accessibility settings like 'Increase contrast' and 'Reduce transparency'. See Apple Documentation for more details.
\nsystemPreferences.isInvertedColorScheme() Windows DeprecatedReturns Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is active, false otherwise.
Deprecated: Should use the new nativeTheme.shouldUseInvertedColorScheme API.
systemPreferences.isHighContrastColorScheme() macOS Windows DeprecatedReturns Boolean - true if a high contrast theme is active, false otherwise.
Deprecated: Should use the new nativeTheme.shouldUseHighContrastColors API.
systemPreferences.getEffectiveAppearance() macOSReturns String - Can be dark, light or unknown.
Gets the macOS appearance setting that is currently applied to your application,\nmaps to NSApplication.effectiveAppearance
\nsystemPreferences.getAppLevelAppearance() macOS DeprecatedReturns String | null - Can be dark, light or unknown.
Gets the macOS appearance setting that you have declared you want for\nyour application, maps to NSApplication.appearance.\nYou can use the setAppLevelAppearance API to set this value.
systemPreferences.setAppLevelAppearance(appearance) macOS Deprecatedappearance String | null - Can be dark or lightSets the appearance setting for your application, this should override the\nsystem default and override the value of getEffectiveAppearance.
systemPreferences.canPromptTouchID() macOSReturns Boolean - whether or not this device has the ability to use Touch ID.
NOTE: This API will return false on macOS systems older than Sierra 10.12.2.
systemPreferences.promptTouchID(reason) macOSreason String - The reason you are asking for Touch ID authenticationReturns Promise<void> - resolves if the user has successfully authenticated with Touch ID.
const { systemPreferences } = require('electron')\n\nsystemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {\n console.log('You have successfully authenticated with Touch ID!')\n}).catch(err => {\n console.log(err)\n})\nThis API itself will not protect your user data; rather, it is a mechanism to allow you to do so. Native apps will need to set Access Control Constants like kSecAccessControlUserPresence on their keychain entry so that reading it would auto-prompt for Touch ID biometric consent. This could be done with node-keytar, such that one would store an encryption key with node-keytar and only fetch it if promptTouchID() resolves.
NOTE: This API will return a rejected Promise on macOS systems older than Sierra 10.12.2.
\nsystemPreferences.isTrustedAccessibilityClient(prompt) macOSprompt Boolean - whether or not the user will be informed via prompt if the current process is untrusted.Returns Boolean - true if the current process is a trusted accessibility client and false if it is not.
systemPreferences.getMediaAccessStatus(mediaType) Windows macOSmediaType String - Can be microphone, camera or screen.Returns String - Can be not-determined, granted, denied, restricted or unknown.
This user consent was not required on macOS 10.13 High Sierra or lower so this method will always return granted.\nmacOS 10.14 Mojave or higher requires consent for microphone and camera access.\nmacOS 10.15 Catalina or higher requires consent for screen access.
Windows 10 has a global setting controlling microphone and camera access for all win32 applications.\nIt will always return granted for screen and for all media types on older versions of Windows.
systemPreferences.askForMediaAccess(mediaType) macOSmediaType String - the type of media being requested; can be microphone, camera.Returns Promise<Boolean> - A promise that resolves with true if consent was granted and false if it was denied. If an invalid mediaType is passed, the promise will be rejected. If an access request was denied and later is changed through the System Preferences pane, a restart of the app will be required for the new permissions to take effect. If access has already been requested and denied, it must be changed through the preference pane; an alert will not pop up and the promise will resolve with the existing access status.
Important: In order to properly leverage this API, you must set the NSMicrophoneUsageDescription and NSCameraUsageDescription strings in your app's Info.plist file. The values for these keys will be used to populate the permission dialogs so that the user will be properly informed as to the purpose of the permission request. See Electron Application Distribution for more information about how to set these in the context of Electron.
This user consent was not required until macOS 10.14 Mojave, so this method will always return true if your system is running 10.13 High Sierra or lower.
systemPreferences.getAnimationSettings()Returns Object:
shouldRenderRichAnimation Boolean - Returns true if rich animations should be rendered. Looks at session type (e.g. remote desktop) and accessibility settings to give guidance for heavy animations.scrollAnimationsEnabledBySystem Boolean - Determines on a per-platform basis whether scroll animations (e.g. produced by home/end key) should be enabled.prefersReducedMotion Boolean - Determines whether the user desires reduced motion based on platform APIs.Returns an object with system animation settings.
\nsystemPreferences.appLevelAppearance macOSA String property that can be dark, light or unknown. It determines the macOS appearance setting for\nyour application. This maps to values in: NSApplication.appearance. Setting this will override the\nsystem default as well as the value of getEffectiveAppearance.
Possible values that can be set are dark and light, and possible return values are dark, light, and unknown.
This property is only available on macOS 10.14 Mojave or newer.
\nsystemPreferences.effectiveAppearance macOS ReadonlyA String property that can be dark, light or unknown.
Returns the macOS appearance setting that is currently applied to your application,\nmaps to NSApplication.effectiveAppearance
", "title": "systemPreferences", "description": "Get system preferences." }, "/docs/api/structures/task": { "locale": "en-US", "slug": "task", "href": "/docs/api/structures/task", "crowdinFileId": "256513", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/task.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "program String - Path of the program to execute, usually you should\nspecify process.execPath which opens the current program.arguments String - The command line arguments when program is\nexecuted.title String - The string to be displayed in a JumpList.description String - Description of this task.iconPath String - The absolute path to an icon to be displayed in a\nJumpList, which can be an arbitrary resource file that contains an icon. You\ncan usually specify process.execPath to show the icon of the program.iconIndex Number - The icon index in the icon file. If an icon file\nconsists of two or more icons, set this value to identify the icon. If an\nicon file consists of one icon, this value is 0.workingDirectory String (optional) - The working directory. Default is empty.We aim to keep the code coverage of Electron high. We ask that all pull\nrequest not only pass all existing tests, but ideally also add new tests\nto cover changed code and new scenarios. Ensuring that we capture as\nmany code paths and use cases of Electron as possible ensures that we\nall ship apps with fewer bugs.
\nThis repository comes with linting rules for both JavaScript and C++ –\nas well as unit and integration tests. To learn more about Electron's\ncoding style, please see the coding-style document.
\nTo ensure that your JavaScript is in compliance with the Electron coding\nstyle, run npm run lint-js, which will run standard against both\nElectron itself as well as the unit tests. If you are using an editor\nwith a plugin/addon system, you might want to use one of the many\nStandardJS addons to be informed of coding style\nviolations before you ever commit them.
To run standard with parameters, run npm run lint-js -- followed by\narguments you want passed to standard.
To ensure that your C++ is in compliance with the Electron coding style,\nrun npm run lint-cpp, which runs a cpplint script. We recommend that\nyou use clang-format and prepared a short tutorial.
There is not a lot of Python in this repository, but it too is governed\nby coding style rules. npm run lint-py will check all Python, using\npylint to do so.
If you are not using build-tools,\nensure that that name you have configured for your\nlocal build of Electron is one of Testing, Release, Default, Debug, or\nyou have set process.env.ELECTRON_OUT_DIR. Without these set, Electron will fail\nto perform some pre-testing steps.
To run all unit tests, run npm run test. The unit tests are an Electron\napp (surprise!) that can be found in the spec folder. Note that it has\nits own package.json and that its dependencies are therefore not defined\nin the top-level package.json.
To run only specific tests matching a pattern, run npm run test -- -g=PATTERN, replacing the PATTERN with a regex that matches the tests\nyou would like to run. As an example: If you want to run only IPC tests, you\nwould run npm run test -- -g ipc.
Visual Studio 2019 must be installed.
\nNode headers have to be compiled for your configuration.
\nninja -C out\\Testing third_party\\electron_node:headers\nThe electron.lib has to be copied as node.lib.
\ncd out\\Testing\nmkdir gen\\node_headers\\Release\ncopy electron.lib gen\\node_headers\\Release\\node.lib\nSome Windows 10 devices do not ship with the Meiryo font installed, which may cause a font fallback test to fail. To install Meiryo:
\nSome tests which rely on precise pixel measurements may not work correctly on\ndevices with Hi-DPI screen settings due to floating point precision errors.\nTo run these tests correctly, make sure the device is set to 100% scaling.
\nTo configure display scaling:
\nBeing based on Chromium, Electron requires a display driver to function.\nIf Chromium can't find a display driver, Electron will fail to launch -\nand therefore not executing any of your tests, regardless of how you are running\nthem. Testing Electron-based apps on Travis, Circle, Jenkins or similar Systems\nrequires therefore a little bit of configuration. In essence, we need to use\na virtual display driver.
\nFirst, install Xvfb.\nIt's a virtual framebuffer, implementing the X11 display server protocol -\nit performs all graphical operations in memory without showing any screen output,\nwhich is exactly what we need.
\nThen, create a virtual Xvfb screen and export an environment variable\ncalled DISPLAY that points to it. Chromium in Electron will automatically look\nfor $DISPLAY, so no further configuration of your app is required.\nThis step can be automated with Anaïs Betts'\nxvfb-maybe: Prepend your test\ncommands with xvfb-maybe and the little tool will automatically configure\nXvfb, if required by the current system. On Windows or macOS, it will\ndo nothing.
## On Windows or macOS, this invokes electron-mocha\n## On Linux, if we are in a headless environment, this will be equivalent\n## to xvfb-run electron-mocha ./test/*.js\nxvfb-maybe electron-mocha ./test/*.js\nOn Travis, your .travis.yml should look roughly like this:
addons:\n apt:\n packages:\n - xvfb\n\ninstall:\n - export DISPLAY=':99.0'\n - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &\nFor Jenkins, a Xvfb plugin is available.
\nCircle CI is awesome and has Xvfb and $DISPLAY\nalready set up, so no further configuration is required.
AppVeyor runs on Windows, supporting Selenium, Chromium, Electron and similar\ntools out of the box - no configuration is required.
", "title": "Testing on Headless CI Systems (Travis CI, Jenkins)", "description": "" }, "/docs/tutorial/testing-widevine-cdm": { "locale": "en-US", "slug": "testing-widevine-cdm", "href": "/docs/tutorial/testing-widevine-cdm", "crowdinFileId": "256257", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/testing-widevine-cdm.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "In Electron you can use the Widevine CDM library shipped with Chrome browser.
\nWidevine Content Decryption Modules (CDMs) are how streaming services protect\ncontent using HTML5 video to web browsers without relying on an NPAPI plugin\nlike Flash or Silverlight. Widevine support is an alternative solution for\nstreaming services that currently rely on Silverlight for playback of\nDRM-protected video content. It will allow websites to show DRM-protected video\ncontent in Firefox without the use of NPAPI plugins. The Widevine CDM runs in an\nopen-source CDM sandbox providing better user security than NPAPI plugins.
\nAs of Electron v1.8.0 (Chrome v59),\nthe below steps are may only be some of the necessary steps to enable Widevine;\nany app on or after that version intending to use the Widevine CDM may need to\nbe signed using a license obtained from Widevine\nitself.
Per Widevine:
\n\n\nChrome 59 (and later) includes support for Verified Media Path (VMP). VMP\nprovides a method to verify the authenticity of a device platform. For browser\ndeployments, this will provide an additional signal to determine if a\nbrowser-based implementation is reliable and secure.
\nThe proxy integration guide has been updated with information about VMP and\nhow to issue licenses.
\nWidevine recommends our browser-based integrations (vendors and browser-based\napplications) add support for VMP.
\n
To enable video playback with this new restriction,\ncastLabs has created a\nfork that has implemented the\nnecessary changes to enable Widevine to be played in an Electron application if\none has obtained the necessary licenses from widevine.
\nOpen chrome://components/ in Chrome browser, find Widevine Content Decryption Module\nand make sure it is up to date, then you can find the library files from the\napplication directory.
The library file widevinecdm.dll will be under\nProgram Files(x86)/Google/Chrome/Application/CHROME_VERSION/WidevineCdm/_platform_specific/win_(x86|x64)/\ndirectory.
The library file libwidevinecdm.dylib will be under\n/Applications/Google Chrome.app/Contents/Versions/CHROME_VERSION/Google Chrome Framework.framework/Versions/A/Libraries/WidevineCdm/_platform_specific/mac_(x86|x64)/\ndirectory.
Note: Make sure that chrome version used by Electron is greater than or\nequal to the min_chrome_version value of Chrome's widevine cdm component.\nThe value can be found in manifest.json under WidevineCdm directory.
After getting the library files, you should pass the path to the file\nwith --widevine-cdm-path command line switch, and the library's version\nwith --widevine-cdm-version switch. The command line switches have to be\npassed before the ready event of app module gets emitted.
Example code:
\nconst { app, BrowserWindow } = require('electron')\n\n// You have to pass the directory that contains widevine library here, it is\n// * `libwidevinecdm.dylib` on macOS,\n// * `widevinecdm.dll` on Windows.\napp.commandLine.appendSwitch('widevine-cdm-path', '/path/to/widevine_library')\n// The version of plugin can be got from `chrome://components` page in Chrome.\napp.commandLine.appendSwitch('widevine-cdm-version', '1.4.8.866')\n\nlet win = null\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.show()\n})\nTo verify whether widevine works, you can use following ways:
\nWidevine.bitdash uses Widevine in your browser, then play the video.icon NativeImage - The icon showing in thumbnail\ntoolbar.click Functiontooltip String (optional) - The text of the button's tooltip.flags String - Control specific states and behaviors of the\nbutton. By default, it is ['enabled'].The flags is an array that can include following Strings:
enabled - The button is active and available to the user.disabled - The button is disabled. It is present, but has a visual state\nindicating it will not respond to user action.dismissonclick - When the button is clicked, the thumbnail window closes\nimmediately.nobackground - Do not draw a button border, use only the image.hidden - The button is not shown to the user.noninteractive - The button is enabled but not interactive; no pressed\nbutton state is drawn. This value is intended for instances where the button\nis used in a notification.\n\nCreate TouchBar layouts for native macOS applications
\n
Process: Main
\nnew TouchBar(options)options Objectitems (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer)escapeItem (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer | null) (optional)Creates a new touch bar with the specified items. Use\nBrowserWindow.setTouchBar to add the TouchBar to a window.
Note: The TouchBar API is currently experimental and may change or be\nremoved in future Electron releases.
\nTip: If you don't have a MacBook with Touch Bar, you can use\nTouch Bar Simulator\nto test Touch Bar usage in your app.
\nTouchBarButtonA typeof TouchBarButton reference to the TouchBarButton class.
TouchBarColorPickerA typeof TouchBarColorPicker reference to the TouchBarColorPicker class.
TouchBarGroupA typeof TouchBarGroup reference to the TouchBarGroup class.
TouchBarLabelA typeof TouchBarLabel reference to the TouchBarLabel class.
TouchBarPopoverA typeof TouchBarPopover reference to the TouchBarPopover class.
TouchBarScrubberA typeof TouchBarScrubber reference to the TouchBarScrubber class.
TouchBarSegmentedControlA typeof TouchBarSegmentedControl reference to the TouchBarSegmentedControl class.
TouchBarSliderA typeof TouchBarSlider reference to the TouchBarSlider class.
TouchBarSpacerA typeof TouchBarSpacer reference to the TouchBarSpacer class.
TouchBarOtherItemsProxyA typeof TouchBarOtherItemsProxy reference to the TouchBarOtherItemsProxy class.
The following properties are available on instances of TouchBar:
touchBar.escapeItemA TouchBarItem that will replace the \"esc\" button on the touch bar when set.\nSetting to null restores the default \"esc\" button. Changing this value\nimmediately updates the escape item in the touch bar.
Below is an example of a simple slot machine touch bar game with a button\nand some labels.
\nconst { app, BrowserWindow, TouchBar } = require('electron')\n\nconst { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar\n\nlet spinning = false\n\n// Reel labels\nconst reel1 = new TouchBarLabel()\nconst reel2 = new TouchBarLabel()\nconst reel3 = new TouchBarLabel()\n\n// Spin result label\nconst result = new TouchBarLabel()\n\n// Spin button\nconst spin = new TouchBarButton({\n label: '🎰 Spin',\n backgroundColor: '#7851A9',\n click: () => {\n // Ignore clicks if already spinning\n if (spinning) {\n return\n }\n\n spinning = true\n result.label = ''\n\n let timeout = 10\n const spinLength = 4 * 1000 // 4 seconds\n const startTime = Date.now()\n\n const spinReels = () => {\n updateReels()\n\n if ((Date.now() - startTime) >= spinLength) {\n finishSpin()\n } else {\n // Slow down a bit on each spin\n timeout *= 1.1\n setTimeout(spinReels, timeout)\n }\n }\n\n spinReels()\n }\n})\n\nconst getRandomValue = () => {\n const values = ['🍒', '💎', '7️⃣', '🍊', '🔔', '⭐', '🍇', '🍀']\n return values[Math.floor(Math.random() * values.length)]\n}\n\nconst updateReels = () => {\n reel1.label = getRandomValue()\n reel2.label = getRandomValue()\n reel3.label = getRandomValue()\n}\n\nconst finishSpin = () => {\n const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size\n if (uniqueValues === 1) {\n // All 3 values are the same\n result.label = '💰 Jackpot!'\n result.textColor = '#FDFF00'\n } else if (uniqueValues === 2) {\n // 2 values are the same\n result.label = '😍 Winner!'\n result.textColor = '#FDFF00'\n } else {\n // No values are the same\n result.label = '🙁 Spin Again'\n result.textColor = null\n }\n spinning = false\n}\n\nconst touchBar = new TouchBar({\n items: [\n spin,\n new TouchBarSpacer({ size: 'large' }),\n reel1,\n new TouchBarSpacer({ size: 'small' }),\n reel2,\n new TouchBarSpacer({ size: 'small' }),\n reel3,\n new TouchBarSpacer({ size: 'large' }),\n result\n ]\n})\n\nlet window\n\napp.whenReady().then(() => {\n window = new BrowserWindow({\n frame: false,\n titleBarStyle: 'hiddenInset',\n width: 200,\n height: 200,\n backgroundColor: '#000'\n })\n window.loadURL('about:blank')\n window.setTouchBar(touchBar)\n})\nTo run the example above, you'll need to (assuming you've got a terminal open in the directory you want to run the example):
\ntouchbar.jsnpm install electron./node_modules/.bin/electron touchbar.jsYou should then see a new Electron window and the app running in your touch bar (or touch bar emulator).
", "title": "TouchBar", "description": "Create TouchBar layouts for native macOS applications" }, "/docs/api/touch-bar-button": { "locale": "en-US", "slug": "touch-bar-button", "href": "/docs/api/touch-bar-button", "crowdinFileId": "256375", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/touch-bar-button.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCreate a button in the touch bar for native macOS applications
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarButton(options)options Objectlabel String (optional) - Button text.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.backgroundColor String (optional) - Button background color in hex format,\ni.e #ABCDEF.icon NativeImage | String (optional) - Button icon.iconPosition String (optional) - Can be left, right or overlay. Defaults to overlay.click Function (optional) - Function to call when the button is clicked.enabled Boolean (optional) - Whether the button is in an enabled state. Default is true.When defining accessibilityLabel, ensure you have considered macOS best practices.
The following properties are available on instances of TouchBarButton:
touchBarButton.accessibilityLabelA String representing the description of the button to be read by a screen reader. Will only be read by screen readers if no label is set.
touchBarButton.labelA String representing the button's current text. Changing this value immediately updates the button\nin the touch bar.
touchBarButton.backgroundColorA String hex code representing the button's current background color. Changing this value immediately updates\nthe button in the touch bar.
touchBarButton.iconA NativeImage representing the button's current icon. Changing this value immediately updates the button\nin the touch bar.
touchBarButton.iconPositionA String - Can be left, right or overlay. Defaults to overlay.
touchBarButton.enabledA Boolean representing whether the button is in an enabled state.
\n\nCreate a color picker in the touch bar for native macOS applications
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarColorPicker(options)options ObjectavailableColors String - Array of hex color strings to\nappear as possible colors to select.selectedColor String (optional) - The selected hex color in the picker,\ni.e #ABCDEF.change Function (optional) - Function to call when a color is selected.color String - The color that the user selected from the picker.The following properties are available on instances of TouchBarColorPicker:
touchBarColorPicker.availableColorsA String[] array representing the color picker's available colors to select. Changing this value immediately\nupdates the color picker in the touch bar.
touchBarColorPicker.selectedColorA String hex code representing the color picker's currently selected color. Changing this value immediately\nupdates the color picker in the touch bar.
\n\nCreate a group in the touch bar for native macOS applications
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarGroup(options)options Objectitems TouchBar - Items to display as a group.\n\nCreate a label in the touch bar for native macOS applications
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarLabel(options)options Objectlabel String (optional) - Text to display.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.textColor String (optional) - Hex color of text, i.e #ABCDEF.When defining accessibilityLabel, ensure you have considered macOS best practices.
The following properties are available on instances of TouchBarLabel:
touchBarLabel.labelA String representing the label's current text. Changing this value immediately updates the label in\nthe touch bar.
touchBarLabel.accessibilityLabelA String representing the description of the label to be read by a screen reader.
touchBarLabel.textColorA String hex code representing the label's current text color. Changing this value immediately updates the\nlabel in the touch bar.
\n\nInstantiates a special \"other items proxy\", which nests TouchBar elements inherited\nfrom Chromium at the space indicated by the proxy. By default, this proxy is added\nto each TouchBar at the end of the input. For more information, see the AppKit docs on\nNSTouchBarItemIdentifierOtherItemsProxy
\nNote: Only one instance of this class can be added per TouchBar.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarOtherItemsProxy()\n\nCreate a popover in the touch bar for native macOS applications
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarPopover(options)options Objectlabel String (optional) - Popover button text.icon NativeImage (optional) - Popover button icon.items TouchBar - Items to display in the popover.showCloseButton Boolean (optional) - true to display a close button\non the left of the popover, false to not show it. Default is true.The following properties are available on instances of TouchBarPopover:
touchBarPopover.labelA String representing the popover's current button text. Changing this value immediately updates the\npopover in the touch bar.
touchBarPopover.iconA NativeImage representing the popover's current button icon. Changing this value immediately updates the\npopover in the touch bar.
\n\nCreate a scrubber (a scrollable selector)
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarScrubber(options)options Objectitems ScrubberItem[] - An array of items to place in this scrubber.select Function (optional) - Called when the user taps an item that was not the last tapped item.selectedIndex Integer - The index of the item the user selected.highlight Function (optional) - Called when the user taps any item.highlightedIndex Integer - The index of the item the user touched.selectedStyle String (optional) - Selected item style. Can be background, outline or none. Defaults to none.overlayStyle String (optional) - Selected overlay item style. Can be background, outline or none. Defaults to none.showArrowButtons Boolean (optional) - Whether to show arrow buttons. Defaults to false and is only shown if items is non-empty.mode String (optional) - Can be fixed or free. The default is free.continuous Boolean (optional) - Defaults to true.The following properties are available on instances of TouchBarScrubber:
touchBarScrubber.itemsA ScrubberItem[] array representing the items in this scrubber. Updating this value immediately\nupdates the control in the touch bar. Updating deep properties inside this array does not update the touch bar.
touchBarScrubber.selectedStyleA String representing the style that selected items in the scrubber should have. Updating this value immediately\nupdates the control in the touch bar. Possible values:
background - Maps to [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Maps to [NSScrubberSelectionStyle outlineOverlayStyle].none - Removes all styles.touchBarScrubber.overlayStyleA String representing the style that selected items in the scrubber should have. This style is overlayed on top\nof the scrubber item instead of being placed behind it. Updating this value immediately updates the control in the\ntouch bar. Possible values:
background - Maps to [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Maps to [NSScrubberSelectionStyle outlineOverlayStyle].none - Removes all styles.touchBarScrubber.showArrowButtonsA Boolean representing whether to show the left / right selection arrows in this scrubber. Updating this value\nimmediately updates the control in the touch bar.
touchBarScrubber.modeA String representing the mode of this scrubber. Updating this value immediately\nupdates the control in the touch bar. Possible values:
fixed - Maps to NSScrubberModeFixed.free - Maps to NSScrubberModeFree.touchBarScrubber.continuousA Boolean representing whether this scrubber is continuous or not. Updating this value immediately\nupdates the control in the touch bar.
\n\nCreate a segmented control (a button group) where one button has a selected state
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSegmentedControl(options)options ObjectsegmentStyle String (optional) - Style of the segments:automatic - Default. The appearance of the segmented control is\nautomatically determined based on the type of window in which the control\nis displayed and the position within the window. Maps to NSSegmentStyleAutomatic.rounded - The control is displayed using the rounded style. Maps to NSSegmentStyleRounded.textured-rounded - The control is displayed using the textured rounded\nstyle. Maps to NSSegmentStyleTexturedRounded.round-rect - The control is displayed using the round rect style. Maps to NSSegmentStyleRoundRect.textured-square - The control is displayed using the textured square\nstyle. Maps to NSSegmentStyleTexturedSquare.capsule - The control is displayed using the capsule style. Maps to NSSegmentStyleCapsule.small-square - The control is displayed using the small square style. Maps to NSSegmentStyleSmallSquare.separated - The segments in the control are displayed very close to each\nother but not touching. Maps to NSSegmentStyleSeparated.mode String (optional) - The selection mode of the control:single - Default. One item selected at a time, selecting one deselects the previously selected item. Maps to NSSegmentSwitchTrackingSelectOne.multiple - Multiple items can be selected at a time. Maps to NSSegmentSwitchTrackingSelectAny.buttons - Make the segments act as buttons, each segment can be pressed and released but never marked as active. Maps to NSSegmentSwitchTrackingMomentary.segments SegmentedControlSegment[] - An array of segments to place in this control.selectedIndex Integer (optional) - The index of the currently selected segment, will update automatically with user interaction. When the mode is multiple it will be the last selected item.change Function (optional) - Called when the user selects a new segment.selectedIndex Integer - The index of the segment the user selected.isSelected Boolean - Whether as a result of user selection the segment is selected or not.The following properties are available on instances of TouchBarSegmentedControl:
touchBarSegmentedControl.segmentStyleA String representing the controls current segment style. Updating this value immediately updates the control\nin the touch bar.
touchBarSegmentedControl.segmentsA SegmentedControlSegment[] array representing the segments in this control. Updating this value immediately\nupdates the control in the touch bar. Updating deep properties inside this array does not update the touch bar.
touchBarSegmentedControl.selectedIndexAn Integer representing the currently selected segment. Changing this value immediately updates the control\nin the touch bar. User interaction with the touch bar will update this value automatically.
touchBarSegmentedControl.modeA String representing the current selection mode of the control. Can be single, multiple or buttons.
\n\nCreate a slider in the touch bar for native macOS applications
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSlider(options)options Objectlabel String (optional) - Label text.value Integer (optional) - Selected value.minValue Integer (optional) - Minimum value.maxValue Integer (optional) - Maximum value.change Function (optional) - Function to call when the slider is changed.newValue Number - The value that the user selected on the Slider.The following properties are available on instances of TouchBarSlider:
touchBarSlider.labelA String representing the slider's current text. Changing this value immediately updates the slider\nin the touch bar.
touchBarSlider.valueA Number representing the slider's current value. Changing this value immediately updates the slider\nin the touch bar.
touchBarSlider.minValueA Number representing the slider's current minimum value. Changing this value immediately updates the\nslider in the touch bar.
touchBarSlider.maxValueA Number representing the slider's current maximum value. Changing this value immediately updates the\nslider in the touch bar.
\n\nCreate a spacer between two items in the touch bar for native macOS applications
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSpacer(options)options Objectsize String (optional) - Size of spacer, possible values are:small - Small space between items. Maps to NSTouchBarItemIdentifierFixedSpaceSmall. This is the default.large - Large space between items. Maps to NSTouchBarItemIdentifierFixedSpaceLarge.flexible - Take up all available space. Maps to NSTouchBarItemIdentifierFlexibleSpace.The following properties are available on instances of TouchBarSpacer:
touchBarSpacer.sizeA String representing the size of the spacer. Can be small, large or flexible.
categoryFilter String - A filter to control what category groups\nshould be traced. A filter can have an optional '-' prefix to exclude\ncategory groups that contain a matching category. Having both included\nand excluded category patterns in the same list is not supported. Examples:\ntest_MyTest*, test_MyTest*,test_OtherStuff, -excluded_category1,-excluded_category2.traceOptions String - Controls what kind of tracing is enabled,\nit is a comma-delimited sequence of the following strings:\nrecord-until-full, record-continuously, trace-to-console, enable-sampling, enable-systrace,\ne.g. 'record-until-full,enable-sampling'.\nThe first 3 options are trace recording modes and hence mutually exclusive.\nIf more than one trace recording modes appear in the traceOptions string,\nthe last one takes precedence. If none of the trace recording modes are\nspecified, recording mode is record-until-full.\nThe trace option will first be reset to the default option (record_mode set\nto record-until-full, enable_sampling and enable_systrace\nset to false) before options parsed from traceOptions are applied on it.recording_mode String (optional) - Can be record-until-full, record-continuously, record-as-much-as-possible or trace-to-console. Defaults to record-until-full.trace_buffer_size_in_kb number (optional) - maximum size of the trace\nrecording buffer in kilobytes. Defaults to 100MB.trace_buffer_size_in_events number (optional) - maximum size of the trace\nrecording buffer in events.enable_argument_filter boolean (optional) - if true, filter event data\naccording to a specific list of events that have been manually vetted to not\ninclude any PII. See the implementation in\nChromium for specifics.included_categories String - a list of tracing categories to\ninclude. Can include glob-like patterns using * at the end of the category\nname. See tracing categories for the list of categories.excluded_categories String - a list of tracing categories to\nexclude. Can include glob-like patterns using * at the end of the category\nname. See tracing categories for the list of categories.included_process_ids number - a list of process IDs to\ninclude in the trace. If not specified, trace all processes.histogram_names String - a list of histogram names to report\nwith the trace.memory_dump_config Record<String, any> (optional) - if the\ndisabled-by-default-memory-infra category is enabled, this contains\noptional additional configuration for data collection. See the Chromium\nmemory-infra docs for more information.An example TraceConfig that roughly matches what Chrome DevTools records:
\n{\n recording_mode: 'record-until-full',\n included_categories: [\n 'devtools.timeline',\n 'disabled-by-default-devtools.timeline',\n 'disabled-by-default-devtools.timeline.frame',\n 'disabled-by-default-devtools.timeline.stack',\n 'v8.execute',\n 'blink.console',\n 'blink.user_timing',\n 'latencyInfo',\n 'disabled-by-default-v8.cpu_profiler',\n 'disabled-by-default-v8.cpu_profiler.hires'\n ],\n excluded_categories: ['*']\n}\ntransactionIdentifier String - A string that uniquely identifies a successful payment transaction.transactionDate String - The date the transaction was added to the App Store’s payment queue.originalTransactionIdentifier String - The identifier of the restored transaction by the App Store.transactionState String - The transaction state, can be purchasing, purchased, failed, restored or deferred.errorCode Integer - The error code if an error occurred while processing the transaction.errorMessage String - The error message if an error occurred while processing the transaction.payment ObjectproductIdentifier String - The identifier of the purchased product.quantity Integer - The quantity purchased.\n\nAdd icons and context menus to the system's notification area.
\n
Process: Main
\nTray is an EventEmitter.
const { app, Menu, Tray } = require('electron')\n\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n ])\n tray.setToolTip('This is my application.')\n tray.setContextMenu(contextMenu)\n})\nPlatform limitations:
\nGtkStatusIcon will be used instead.libappindicator1 to make the tray icon work.click event is ignored.MenuItems to take effect,\nyou have to call setContextMenu again. For example:const { app, Menu, Tray } = require('electron')\n\nlet appIcon = null\napp.whenReady().then(() => {\n appIcon = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' }\n ])\n\n // Make a change to the context menu\n contextMenu.items[1].checked = false\n\n // Call this again for Linux because we modified the context menu\n appIcon.setContextMenu(contextMenu)\n})\nICO icons to get best visual effects.If you want to keep exact same behaviors on all platforms, you should not\nrely on the click event and always attach a context menu to the tray icon.
new Tray(image, [guid])image (NativeImage | String)guid String (optional) Windows - Assigns a GUID to the tray icon. If the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. OS level settings like the position of the tray icon in the system tray will persist even if the path to the executable changes. If the executable is not code-signed then the GUID is permanently associated with the path to the executable. Changing the path to the executable will break the creation of the tray icon and a new GUID must be used. However, it is highly recommended to use the GUID parameter only in conjunction with code-signed executable. If an App defines multiple tray icons then each icon must use a separate GUID.Creates a new tray icon associated with the image.
The Tray module emits the following events:
Returns:
\nevent KeyboardEventbounds Rectangle - The bounds of tray icon.position Point - The position of the event.Emitted when the tray icon is clicked.
\nReturns:
\nevent KeyboardEventbounds Rectangle - The bounds of tray icon.Emitted when the tray icon is right clicked.
\nReturns:
\nevent KeyboardEventbounds Rectangle - The bounds of tray icon.Emitted when the tray icon is double clicked.
\nEmitted when the tray balloon shows.
\nEmitted when the tray balloon is clicked.
\nEmitted when the tray balloon is closed because of timeout or user manually\ncloses it.
\nEmitted when any dragged items are dropped on the tray icon.
\nReturns:
\nevent Eventfiles String[] - The paths of the dropped files.Emitted when dragged files are dropped in the tray icon.
\nReturns:
\nevent Eventtext String - the dropped text string.Emitted when dragged text is dropped in the tray icon.
\nEmitted when a drag operation enters the tray icon.
\nEmitted when a drag operation exits the tray icon.
\nEmitted when a drag operation ends on the tray or ends at another location.
\nReturns:
\nevent KeyboardEventposition Point - The position of the event.Emitted when the mouse is released from clicking the tray icon.
\nNote: This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.
Returns:
\nevent KeyboardEventposition Point - The position of the event.Emitted when the mouse clicks the tray icon.
\nReturns:
\nevent KeyboardEventposition Point - The position of the event.Emitted when the mouse enters the tray icon.
\nReturns:
\nevent KeyboardEventposition Point - The position of the event.Emitted when the mouse exits the tray icon.
\nReturns:
\nevent KeyboardEventposition Point - The position of the event.Emitted when the mouse moves in the tray icon.
\nThe Tray class has the following methods:
tray.destroy()Destroys the tray icon immediately.
\ntray.setImage(image)image (NativeImage | String)Sets the image associated with this tray icon.
tray.setPressedImage(image) macOSimage (NativeImage | String)Sets the image associated with this tray icon when pressed on macOS.
tray.setToolTip(toolTip)toolTip StringSets the hover text for this tray icon.
\ntray.setTitle(title[, options]) macOStitle Stringoptions Object (optional)fontType String (optional) - The font family variant to display, can be monospaced or monospacedDigit. monospaced is available in macOS 10.15+ and monospacedDigit is available in macOS 10.11+. When left blank, the title uses the default system font.Sets the title displayed next to the tray icon in the status bar (Support ANSI colors).
\ntray.getTitle() macOSReturns String - the title displayed next to the tray icon in the status bar
tray.setIgnoreDoubleClickEvents(ignore) macOSignore BooleanSets the option to ignore double click events. Ignoring these events allows you\nto detect every individual click of the tray icon.
\nThis value is set to false by default.
\ntray.getIgnoreDoubleClickEvents() macOSReturns Boolean - Whether double click events will be ignored.
tray.displayBalloon(options) Windowsoptions Objecticon (NativeImage | String) (optional) - Icon to use when iconType is custom.iconType String (optional) - Can be none, info, warning, error or custom. Default is custom.title Stringcontent StringlargeIcon Boolean (optional) - The large version of the icon should be used. Default is true. Maps to NIIF_LARGE_ICON.noSound Boolean (optional) - Do not play the associated sound. Default is false. Maps to NIIF_NOSOUND.respectQuietTime Boolean (optional) - Do not display the balloon notification if the current user is in \"quiet time\". Default is false. Maps to NIIF_RESPECT_QUIET_TIME.Displays a tray balloon.
\ntray.removeBalloon() WindowsRemoves a tray balloon.
\ntray.focus() WindowsReturns focus to the taskbar notification area.\nNotification area icons should use this message when they have completed their UI operation.\nFor example, if the icon displays a shortcut menu, but the user presses ESC to cancel it,\nuse tray.focus() to return focus to the notification area.
tray.popUpContextMenu([menu, position]) macOS Windowsmenu Menu (optional)position Point (optional) - The pop up position.Pops up the context menu of the tray icon. When menu is passed, the menu will\nbe shown instead of the tray icon's context menu.
The position is only available on Windows, and it is (0, 0) by default.
tray.closeContextMenu() macOS WindowsCloses an open context menu, as set by tray.setContextMenu().
tray.setContextMenu(menu)menu Menu | nullSets the context menu for this icon.
\ntray.getBounds() macOS WindowsReturns Rectangle
The bounds of this tray icon as Object.
tray.isDestroyed()Returns Boolean - Whether the tray icon is destroyed.
title: Tray\ndescription: This guide will take you through the process of creating\na Tray icon with its own context menu to the system's notification area.\nslug: tray
\nThis guide will take you through the process of creating a\nTray icon with\nits own context menu to the system's notification area.
\nOn MacOS and Ubuntu, the Tray will be located on the top\nright corner of your screen, adjacent to your battery and wifi icons.\nOn Windows, the Tray will usually be located in the bottom right corner.
\nFirst we must import app, Tray, Menu, nativeImage from electron.
const { app, Tray, Menu, nativeImage } = require('electron')\nNext we will create our Tray. To do this, we will use a\nNativeImage icon,\nwhich can be created through any one of these\nmethods.\nNote that we wrap our Tray creation code within an\napp.whenReady\nas we will need to wait for our electron app to finish initializing.
let tray\n\napp.whenReady().then(() => {\n const icon = nativeImage.createFromPath('path/to/asset.png')\n tray = new Tray(icon)\n\n // note: your contextMenu, Tooltip and Title code will go here!\n})\nGreat! Now we can start attaching a context menu to our Tray, like so:
\nconst contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n])\n\ntray.setContextMenu(contextMenu)\nThe code above will create 4 separate radio-type items in the context menu.\nTo read more about constructing native menus, click\nhere.
\nFinally, let's give our tray a tooltip and a title.
\ntray.setToolTip('This is my application')\ntray.setTitle('This is my title')\nAfter you start your electron app, you should see the Tray residing\nin either the top or bottom right of your screen, depending on your\noperating system.
", "title": "Tray", "description": "" }, "/docs/tutorial/updates": { "locale": "en-US", "slug": "updates", "href": "/docs/tutorial/updates", "crowdinFileId": "256261", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/updates.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "There are several ways to update an Electron application. The easiest and\nofficially supported one is taking advantage of the built-in\nSquirrel framework and\nElectron's autoUpdater module.
\nupdate.electronjs.orgThe Electron team maintains update.electronjs.org, a free and open-source\nwebservice that Electron apps can use to self-update. The service is designed\nfor Electron apps that meet the following criteria:
\nThe easiest way to use this service is by installing update-electron-app,\na Node.js module preconfigured for use with update.electronjs.org.
\nInstall the module:
\nnpm install update-electron-app\nInvoke the updater from your app's main process file:
\nrequire('update-electron-app')()\nBy default, this module will check for updates at app startup, then every ten\nminutes. When an update is found, it will automatically be downloaded in the background. When the download completes, a dialog is displayed allowing the user\nto restart the app.
\nIf you need to customize your configuration, you can\npass options to update-electron-app\nor\nuse the update service directly.
If you're developing a private Electron application, or if you're not\npublishing releases to GitHub Releases, it may be necessary to run your own\nupdate server.
\nDepending on your needs, you can choose from one of these:
\nOnce you've deployed your update server, continue with importing the required\nmodules in your code. The following code might vary for different server\nsoftware, but it works like described when using\nHazel.
\nImportant: Please ensure that the code below will only be executed in\nyour packaged app, and not in development. You can use\nelectron-is-dev to check for\nthe environment.
\nconst { app, autoUpdater, dialog } = require('electron')\nNext, construct the URL of the update server and tell\nautoUpdater about it:
\nconst server = 'https://your-deployment-url.com'\nconst url = `${server}/update/${process.platform}/${app.getVersion()}`\n\nautoUpdater.setFeedURL({ url })\nAs the final step, check for updates. The example below will check every minute:
\nsetInterval(() => {\n autoUpdater.checkForUpdates()\n}, 60000)\nOnce your application is packaged,\nit will receive an update for each new\nGitHub Release that you\npublish.
\nNow that you've configured the basic update mechanism for your application, you\nneed to ensure that the user will get notified when there's an update. This\ncan be achieved using the autoUpdater API\nevents:
\nautoUpdater.on('update-downloaded', (event, releaseNotes, releaseName) => {\n const dialogOpts = {\n type: 'info',\n buttons: ['Restart', 'Later'],\n title: 'Application Update',\n message: process.platform === 'win32' ? releaseNotes : releaseName,\n detail: 'A new version has been downloaded. Restart the application to apply the updates.'\n }\n\n dialog.showMessageBox(dialogOpts).then((returnValue) => {\n if (returnValue.response === 0) autoUpdater.quitAndInstall()\n })\n})\nAlso make sure that errors are\nbeing handled. Here's an example\nfor logging them to stderr:
autoUpdater.on('error', message => {\n console.error('There was a problem updating the application')\n console.error(message)\n})\nBecause the requests made by Auto Update aren't under your direct control, you may find situations that are difficult to handle (such as if the update server is behind authentication). The url field does support files, which means that with some effort, you can sidestep the server-communication aspect of the process. Here's an example of how this could work.
bytes Buffer - Content being sent.file String (optional) - Path of file being uploaded.blobUUID String (optional) - UUID of blob data. Use ses.getBlobData method\nto retrieve the data.type 'file' - file.filePath String - Path of file to be uploaded.offset Integer - Defaults to 0.length Integer - Number of bytes to read from offset.\nDefaults to 0.modificationTime Double - Last Modification time in\nnumber of seconds since the UNIX epoch.type 'rawData' - rawData.bytes Buffer - Data to be uploaded.string Stringboolean Booleaninteger Numberfloat Numberdouble Numberurl Stringarray Array\\dictionary Record\\<string, unknown>This type is a helper alias, no object will never exist of this type.
", "title": "UserDefaultTypes Object", "description": "" }, "/docs/tutorial/using-native-node-modules": { "locale": "en-US", "slug": "using-native-node-modules", "href": "/docs/tutorial/using-native-node-modules", "crowdinFileId": "256263", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-native-node-modules.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Native Node.js modules are supported by Electron, but since Electron has a different\napplication binary interface (ABI) from a given Node.js binary (due to\ndifferences such as using Chromium's BoringSSL instead of OpenSSL), the native\nmodules you use will need to be recompiled for Electron. Otherwise,\nyou will get the following class of error when you try to run your app:
\nError: The module '/path/to/native/module.node'\nwas compiled against a different Node.js version using\nNODE_MODULE_VERSION $XYZ. This version of Node.js requires\nNODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing\nthe module (for instance, using `npm rebuild` or `npm install`).\nThere are several different ways to install native modules:
\nYou can install modules like other Node projects, and then rebuild the modules\nfor Electron with the electron-rebuild package. This\nmodule can automatically determine the version of Electron and handle the\nmanual steps of downloading headers and rebuilding native modules for your app.\nIf you are using Electron Forge, this tool is used automatically\nin both development mode and when making distributables.
For example, to install the standalone electron-rebuild tool and then rebuild\nmodules with it via the command line:
npm install --save-dev electron-rebuild\n\n# Every time you run \"npm install\", run this:\n./node_modules/.bin/electron-rebuild\n\n# If you have trouble on Windows, try:\n.\\node_modules\\.bin\\electron-rebuild.cmd\nFor more information on usage and integration with other tools such as Electron\nPackager, consult the project's README.
\nnpmBy setting a few environment variables, you can use npm to install modules\ndirectly.
For example, to install all dependencies for Electron:
\n# Electron's version.\nexport npm_config_target=1.2.3\n# The architecture of Electron, see https://electronjs.org/docs/tutorial/support#supported-platforms\n# for supported architectures.\nexport npm_config_arch=x64\nexport npm_config_target_arch=x64\n# Download headers for Electron.\nexport npm_config_disturl=https://electronjs.org/headers\n# Tell node-pre-gyp that we are building for Electron.\nexport npm_config_runtime=electron\n# Tell node-pre-gyp to build module from source code.\nexport npm_config_build_from_source=true\n# Install all dependencies, and store cache to ~/.electron-gyp.\nHOME=~/.electron-gyp npm install\nIf you are a developer developing a native module and want to test it against\nElectron, you might want to rebuild the module for Electron manually. You can\nuse node-gyp directly to build for Electron:
cd /path-to-module/\nHOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://electronjs.org/headers\nHOME=~/.electron-gyp changes where to find development headers.--target=1.2.3 is the version of Electron.--dist-url=... specifies where to download the headers.--arch=x64 says the module is built for a 64-bit system.To compile native Node modules against a custom build of Electron that doesn't\nmatch a public release, instruct npm to use the version of Node you have bundled\nwith your custom build.
npm rebuild --nodedir=/path/to/src/out/Default/gen/node_headers\nIf you installed a native module and found it was not working, you need to check\nthe following things:
\nelectron-rebuild first.win_delay_load_hook is not set to false in the module's binding.gyp.win_delay_load_hookOn Windows, by default, node-gyp links native modules against node.dll.\nHowever, in Electron 4.x and higher, the symbols needed by native modules are\nexported by electron.exe, and there is no node.dll. In order to load native\nmodules on Windows, node-gyp installs a delay-load\nhook that triggers\nwhen the native module is loaded, and redirects the node.dll reference to use\nthe loading executable instead of looking for node.dll in the library search\npath (which would turn up nothing). As such, on Electron 4.x and higher,\n'win_delay_load_hook': 'true' is required to load native modules.
If you get an error like Module did not self-register, or The specified procedure could not be found, it may mean that the module you're trying to use\ndid not correctly include the delay-load hook. If the module is built with\nnode-gyp, ensure that the win_delay_load_hook variable is set to true in\nthe binding.gyp file, and isn't getting overridden anywhere. If the module\nis built with another system, you'll need to ensure that you build with a\ndelay-load hook installed in the main .node file. Your link.exe invocation\nshould look like this:
link.exe /OUT:\"foo.node\" \"...\\node.lib\" delayimp.lib /DELAYLOAD:node.exe /DLL\n \"my_addon.obj\" \"win_delay_load_hook.obj\"\nIn particular, it's important that:
\nnode.lib from Electron and not Node. If you link against\nthe wrong node.lib you will get load-time errors when you require the\nmodule in Electron./DELAYLOAD:node.exe. If the node.exe link is not\ndelayed, then the delay-load hook won't get a chance to fire and the node\nsymbols won't be correctly resolved.win_delay_load_hook.obj is linked directly into the final DLL. If the hook\nis set up in a dependent DLL, it won't fire at the right time.See node-gyp\nfor an example delay-load hook if you're implementing your own.
prebuildprebuild provides a way to publish\nnative Node modules with prebuilt binaries for multiple versions of Node\nand Electron.
If the prebuild-powered module provide binaries for the usage in Electron,\nmake sure to omit --build-from-source and the npm_config_build_from_source\nenvironment variable in order to take full advantage of the prebuilt binaries.
node-pre-gypThe node-pre-gyp tool provides a way to deploy native Node\nmodules with prebuilt binaries, and many popular modules are using it.
Sometimes those modules work fine under Electron, but when there are no\nElectron-specific binaries available, you'll need to build from source.\nBecause of this, it is recommended to use electron-rebuild for these modules.
If you are following the npm way of installing modules, you'll need to pass\n--build-from-source to npm, or set the npm_config_build_from_source\nenvironment variable.
Electron no longer supports the Pepper Flash plugin, as Chrome has removed support.
\nSee Chromium's Flash Roadmap for more\ndetails.
", "title": "Pepper Flash Plugin", "description": "" }, "/docs/tutorial/using-selenium-and-webdriver": { "locale": "en-US", "slug": "using-selenium-and-webdriver", "href": "/docs/tutorial/using-selenium-and-webdriver", "crowdinFileId": "256267", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-selenium-and-webdriver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "From ChromeDriver - WebDriver for Chrome:
\n\n\nWebDriver is an open source tool for automated testing of web apps across many\nbrowsers. It provides capabilities for navigating to web pages, user input,\nJavaScript execution, and more. ChromeDriver is a standalone server which\nimplements WebDriver's wire protocol for Chromium. It is being developed by\nmembers of the Chromium and WebDriver teams.
\n
Spectron is the officially supported ChromeDriver testing framework\nfor Electron. It is built on top of WebdriverIO and\nhas helpers to access Electron APIs in your tests and bundles ChromeDriver.
\n$ npm install --save-dev spectron\n// A simple test to verify a visible window is opened with a title\nconst Application = require('spectron').Application\nconst assert = require('assert')\n\nconst myApp = new Application({\n path: '/Applications/MyApp.app/Contents/MacOS/MyApp'\n})\n\nconst verifyWindowIsVisibleWithTitle = async (app) => {\n await app.start()\n try {\n // Check if the window is visible\n const isVisible = await app.browserWindow.isVisible()\n // Verify the window is visible\n assert.strictEqual(isVisible, true)\n // Get the window's title\n const title = await app.client.getTitle()\n // Verify the window's title\n assert.strictEqual(title, 'My App')\n } catch (error) {\n // Log any failures\n console.error('Test failed', error.message)\n }\n // Stop the application\n await app.stop()\n}\n\nverifyWindowIsVisibleWithTitle(myApp)\nWebDriverJs provides\na Node package for testing with web driver, we will use it as an example.
\nFirst you need to download the chromedriver binary, and run it:
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\nRemember the port number 9515, which will be used later
$ npm install selenium-webdriver\nThe usage of selenium-webdriver with Electron is the same with\nupstream, except that you have to manually specify how to connect\nchrome driver and where to find Electron's binary:
const webdriver = require('selenium-webdriver')\n\nconst driver = new webdriver.Builder()\n // The \"9515\" is the port opened by chrome driver.\n .usingServer('http://localhost:9515')\n .withCapabilities({\n 'goog:chromeOptions': {\n // Here is the path to your Electron binary.\n binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'\n }\n })\n .forBrowser('chrome') // note: use .forBrowser('electron') for selenium-webdriver <= 3.6.0\n .build()\n\ndriver.get('http://www.google.com')\ndriver.findElement(webdriver.By.name('q')).sendKeys('webdriver')\ndriver.findElement(webdriver.By.name('btnG')).click()\ndriver.wait(() => {\n return driver.getTitle().then((title) => {\n return title === 'webdriver - Google Search'\n })\n}, 1000)\n\ndriver.quit()\nWebdriverIO provides a Node package for testing with web\ndriver.
\nFirst you need to download the chromedriver binary, and run it:
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver --url-base=wd/hub --port=9515\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\nRemember the port number 9515, which will be used later
$ npm install webdriverio\nconst webdriverio = require('webdriverio')\nconst options = {\n host: 'localhost', // Use localhost as chrome driver server\n port: 9515, // \"9515\" is the port opened by chrome driver.\n desiredCapabilities: {\n browserName: 'chrome',\n 'goog:chromeOptions': {\n binary: '/Path-to-Your-App/electron', // Path to your Electron binary.\n args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/\n }\n }\n}\n\nconst client = webdriverio.remote(options)\n\nclient\n .init()\n .url('http://google.com')\n .setValue('#q', 'webdriverio')\n .click('#btnG')\n .getTitle().then((title) => {\n console.log('Title was: ' + title)\n })\n .end()\nTo test your application without rebuilding Electron,\nplace\nyour app source into Electron's resource directory.
\nAlternatively, pass an argument to run with your Electron binary that points to\nyour app's folder. This eliminates the need to copy-paste your app into\nElectron's resource directory.
", "title": "Selenium and WebDriver", "description": "WebDriver is an open source tool for automated testing of web apps across many\nbrowsers. It provides capabilities for navigating to web pages, user input,\nJavaScript execution, and more. ChromeDriver is a standalone server which\nimplements WebDriver's wire protocol for Chromium. It is being developed by\nmembers of the Chromium and WebDriver teams." }, "/docs/development/v8-development": { "locale": "en-US", "slug": "v8-development", "href": "/docs/development/v8-development", "crowdinFileId": "256171", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/v8-development.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "\n\nA collection of resources for learning and using V8
\n
--prof, --trace-ic, --trace-opt, --trace-deopt, --print-bytecode, --print-opt-codeSee also Chromium Development
", "title": "V8 Development", "description": "A collection of resources for learning and using V8" }, "/docs/api/web-contents": { "locale": "en-US", "slug": "web-contents", "href": "/docs/api/web-contents", "crowdinFileId": "256399", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-contents.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRender and control web pages.
\n
Process: Main
\nwebContents is an EventEmitter.\nIt is responsible for rendering and controlling a web page and is a property of\nthe BrowserWindow object. An example of accessing the\nwebContents object:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('http://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\nThese methods can be accessed from the webContents module:
const { webContents } = require('electron')\nconsole.log(webContents)\nwebContents.getAllWebContents()Returns WebContents[] - An array of all WebContents instances. This will contain web contents\nfor all windows, webviews, opened devtools, and devtools extension background pages.
webContents.getFocusedWebContents()Returns WebContents - The web contents that is focused in this application, otherwise\nreturns null.
webContents.fromId(id)id IntegerReturns WebContents | undefined - A WebContents instance with the given ID, or\nundefined if there is no WebContents associated with the given ID.
webContents.fromDevToolsTargetId(targetId)targetId String - The Chrome DevTools Protocol TargetID associated with the WebContents instance.Returns WebContents | undefined - A WebContents instance with the given TargetID, or\nundefined if there is no WebContents associated with the given TargetID.
When communicating with the Chrome DevTools Protocol,\nit can be useful to lookup a WebContents instance based on its assigned TargetID.
\nasync function lookupTargetId (browserWindow) {\n const wc = browserWindow.webContents\n await wc.debugger.attach('1.3')\n const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')\n const { targetId } = targetInfo\n const targetWebContents = await webContents.fromDevToolsTargetId(targetId)\n}\n\n\nRender and control the contents of a BrowserWindow instance.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emitted when the navigation is done, i.e. the spinner of the tab has stopped\nspinning, and the onload event was dispatched.
Returns:
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerThis event is like did-finish-load but emitted when the load failed.\nThe full list of error codes and their meaning is available here.
Returns:
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerThis event is like did-fail-load but emitted when the load was cancelled\n(e.g. window.stop() was invoked).
Returns:
\nevent EventisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when a frame has done navigation.
\nCorresponds to the points in time when the spinner of the tab started spinning.
\nCorresponds to the points in time when the spinner of the tab stopped spinning.
\nReturns:
\nevent EventEmitted when the document in the top-level frame is loaded.
\nReturns:
\nevent Eventtitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when\ntitle is synthesized from file url.
Returns:
\nevent Eventfavicons String[] - Array of URLs.Emitted when page receives favicon urls.
\nReturns:
\nevent NewWindowWebContentsEventurl StringframeName Stringdisposition String - Can be default, foreground-tab, background-tab,\nnew-window, save-to-disk and other.options BrowserWindowConstructorOptions - The options which will be used for creating the new\nBrowserWindow.additionalFeatures String[] - The non-standard features (features not handled\nby Chromium or Electron) given to window.open(). Deprecated, and will now\nalways be the empty array [].referrer Referrer - The referrer that will be\npassed to the new window. May or may not result in the Referer header being\nsent, depending on the referrer policy.postBody PostBody (optional) - The post data that\nwill be sent to the new window, along with the appropriate headers that will\nbe set. If no post data is to be sent, the value will be null. Only defined\nwhen the window is being created by a form that set target=_blank.Deprecated in favor of webContents.setWindowOpenHandler.
Emitted when the page requests to open a new window for a url. It could be\nrequested by window.open or an external link like <a target='_blank'>.
By default a new BrowserWindow will be created for the url.
Calling event.preventDefault() will prevent Electron from automatically creating a\nnew BrowserWindow. If you call event.preventDefault() and manually create a new\nBrowserWindow then you must set event.newGuest to reference the new BrowserWindow\ninstance, failing to do so may result in unexpected behavior. For example:
myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {\n event.preventDefault()\n const win = new BrowserWindow({\n webContents: options.webContents, // use existing webContents if provided\n show: false\n })\n win.once('ready-to-show', () => win.show())\n if (!options.webContents) {\n const loadOptions = {\n httpReferrer: referrer\n }\n if (postBody != null) {\n const { data, contentType, boundary } = postBody\n loadOptions.postData = postBody.data\n loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`\n }\n\n win.loadURL(url, loadOptions) // existing webContents will be navigated automatically\n }\n event.newGuest = win\n})\nReturns:
\nwindow BrowserWindowdetails Objecturl String - URL for the created window.frameName String - Name given to the created window in the\nwindow.open() call.options BrowserWindowConstructorOptions - The options used to create the\nBrowserWindow. They are merged in increasing precedence: parsed options\nfrom the features string from window.open(), security-related\nwebPreferences inherited from the parent, and options given by\nwebContents.setWindowOpenHandler.\nUnrecognized options are not filtered out.referrer Referrer - The referrer that will be\npassed to the new window. May or may not result in the Referer header\nbeing sent, depending on the referrer policy.postBody PostBody (optional) - The post data\nthat will be sent to the new window, along with the appropriate headers\nthat will be set. If no post data is to be sent, the value will be null.\nOnly defined when the window is being created by a form that set\ntarget=_blank.disposition String - Can be default, foreground-tab,\nbackground-tab, new-window, save-to-disk and other.Emitted after successful creation of a window via window.open in the renderer.\nNot emitted if the creation of the window is canceled from\nwebContents.setWindowOpenHandler.
See window.open() for more details and how to use this in conjunction with webContents.setWindowOpenHandler.
Returns:
\nevent Eventurl StringEmitted when a user or the page wants to start navigation. It can happen when\nthe window.location object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with\nAPIs like webContents.loadURL and webContents.back.
It is also not emitted for in-page navigations, such as clicking anchor links\nor updating the window.location.hash. Use did-navigate-in-page event for\nthis purpose.
Calling event.preventDefault() will prevent the navigation.
Returns:
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be\ntrue for in-page navigations.
Returns:
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted as a server side redirect occurs during navigation. For example a 302\nredirect.
\nThis event will be emitted after did-start-navigation and always before the\ndid-redirect-navigation event for the same navigation.
Calling event.preventDefault() will prevent the navigation (not just the\nredirect).
Returns:
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302\nredirect.
\nThis event cannot be prevented, if you want to prevent redirects you should\ncheckout out the will-redirect event above.
Returns:
\nevent Eventurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigationsEmitted when a main frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links\nor updating the window.location.hash. Use did-navigate-in-page event for\nthis purpose.
Returns:
\nevent Eventurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigations,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links\nor updating the window.location.hash. Use did-navigate-in-page event for\nthis purpose.
Returns:
\nevent Eventurl StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when an in-page navigation happened in any frame.
\nWhen in-page navigation happens, the page URL changes but does not cause\nnavigation outside of the page. Examples of this occurring are when anchor links\nare clicked or when the DOM hashchange event is triggered.
Returns:
\nevent EventEmitted when a beforeunload event handler is attempting to cancel a page unload.
Calling event.preventDefault() will ignore the beforeunload event handler\nand allow the page to be unloaded.
const { BrowserWindow, dialog } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.webContents.on('will-prevent-unload', (event) => {\n const choice = dialog.showMessageBoxSync(win, {\n type: 'question',\n buttons: ['Leave', 'Stay'],\n title: 'Do you want to leave this site?',\n message: 'Changes you made may not be saved.',\n defaultId: 0,\n cancelId: 1\n })\n const leave = (choice === 0)\n if (leave) {\n event.preventDefault()\n }\n})\nNote: This will be emitted for BrowserViews but will not be respected - this is because we have chosen not to tie the BrowserView lifecycle to its owning BrowserWindow should one exist per the specification.
Returns:
\nevent Eventkilled BooleanEmitted when the renderer process crashes or is killed.
\nDeprecated: This event is superceded by the render-process-gone event\nwhich contains more information about why the render process disappeared. It\nisn't always because it crashed. The killed boolean can be replaced by\nchecking reason === 'killed' when you switch to that event.
Returns:
\nevent Eventdetails Objectreason String - The reason the render process is gone. Possible values:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Integer - The exit code of the process, unless reason is\nlaunch-failed, in which case exitCode will be a platform-specific\nlaunch failure error code.Emitted when the renderer process unexpectedly disappears. This is normally\nbecause it was crashed or killed.
\nEmitted when the web page becomes unresponsive.
\nEmitted when the unresponsive web page becomes responsive again.
\nReturns:
\nevent Eventname Stringversion StringEmitted when a plugin process has crashed.
\nEmitted when webContents is destroyed.
Returns:
\nevent Eventinput Object - Input properties.type String - Either keyUp or keyDown.key String - Equivalent to KeyboardEvent.key.code String - Equivalent to KeyboardEvent.code.isAutoRepeat Boolean - Equivalent to KeyboardEvent.repeat.isComposing Boolean - Equivalent to KeyboardEvent.isComposing.shift Boolean - Equivalent to KeyboardEvent.shiftKey.control Boolean - Equivalent to KeyboardEvent.controlKey.alt Boolean - Equivalent to KeyboardEvent.altKey.meta Boolean - Equivalent to KeyboardEvent.metaKey.location Number - Equivalent to KeyboardEvent.location.modifiers String[] - See InputEvent.modifiers.Emitted before dispatching the keydown and keyup events in the page.\nCalling event.preventDefault will prevent the page keydown/keyup events\nand the menu shortcuts.
To only prevent the menu shortcuts, use\nsetIgnoreMenuShortcuts:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nwin.webContents.on('before-input-event', (event, input) => {\n // For example, only enable application menu keyboard shortcuts when\n // Ctrl/Cmd are down.\n win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)\n})\nEmitted when the window enters a full-screen state triggered by HTML API.
\nEmitted when the window leaves a full-screen state triggered by HTML API.
\nReturns:
\nevent EventzoomDirection String - Can be in or out.Emitted when the user is requesting to change the zoom level using the mouse wheel.
\nEmitted when DevTools is opened.
\nEmitted when DevTools is closed.
\nEmitted when DevTools is focused / opened.
\nReturns:
\nevent Eventurl Stringerror String - The error code.certificate Certificatecallback FunctionisTrusted Boolean - Indicates whether the certificate can be considered trusted.isMainFrame BooleanEmitted when failed to verify the certificate for url.
The usage is the same with the certificate-error event of\napp.
Returns:
\nevent Eventurl URLcertificateList Certificate[]callback Functioncertificate Certificate - Must be a certificate from the given list.Emitted when a client certificate is requested.
\nThe usage is the same with the select-client-certificate event of\napp.
Returns:
\nevent EventauthenticationResponseDetails Objecturl URLauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (optional)password String (optional)Emitted when webContents wants to do basic auth.
The usage is the same with the login event of app.
Returns:
\nevent Eventresult ObjectrequestId IntegeractiveMatchOrdinal Integer - Position of the active match.matches Integer - Number of Matches.selectionArea Rectangle - Coordinates of first match region.finalUpdate BooleanEmitted when a result is available for\n[webContents.findInPage] request.
Emitted when media starts playing.
\nEmitted when media is paused or done playing.
\nReturns:
\nevent Eventcolor (String | null) - Theme color is in format of '#rrggbb'. It is null when no theme color is set.Emitted when a page's theme color changes. This is usually due to encountering\na meta tag:
\n<meta name='theme-color' content='#ff0000'>\nReturns:
\nevent Eventurl StringEmitted when mouse moves over a link or the keyboard moves the focus to a link.
\nReturns:
\nevent Eventtype Stringimage NativeImage (optional)scale Float (optional) - scaling factor for the custom cursor.size Size (optional) - the size of the image.hotspot Point (optional) - coordinates of the custom cursor's hotspot.Emitted when the cursor's type changes. The type parameter can be default,\ncrosshair, pointer, text, wait, help, e-resize, n-resize,\nne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize,\nns-resize, ew-resize, nesw-resize, nwse-resize, col-resize,\nrow-resize, m-panning, e-panning, n-panning, ne-panning, nw-panning,\ns-panning, se-panning, sw-panning, w-panning, move, vertical-text,\ncell, context-menu, alias, progress, nodrop, copy, none,\nnot-allowed, zoom-in, zoom-out, grab, grabbing or custom.
If the type parameter is custom, the image parameter will hold the custom\ncursor image in a NativeImage, and scale, size and hotspot will hold\nadditional information about the custom cursor.
Returns:
\nevent Eventparams Objectx Integer - x coordinate.y Integer - y coordinate.frame WebFrameMain - Frame from which the context menu was invoked.linkURL String - URL of the link that encloses the node the context menu\nwas invoked on.linkText String - Text associated with the link. May be an empty\nstring if the contents of the link are an image.pageURL String - URL of the top level page that the context menu was\ninvoked on.frameURL String - URL of the subframe that the context menu was invoked\non.srcURL String - Source URL for the element that the context menu\nwas invoked on. Elements with source URLs are images, audio and video.mediaType String - Type of the node the context menu was invoked on. Can\nbe none, image, audio, video, canvas, file or plugin.hasImageContents Boolean - Whether the context menu was invoked on an image\nwhich has non-empty contents.isEditable Boolean - Whether the context is editable.selectionText String - Text of the selection that the context menu was\ninvoked on.titleText String - Title text of the selection that the context menu was\ninvoked on.altText String - Alt text of the selection that the context menu was\ninvoked on.suggestedFilename String - Suggested filename to be used when saving file through 'Save\nLink As' option of context menu.selectionRect Rectangle - Rect representing the coordinates in the document space of the selection.selectionStartOffset Number - Start position of the selection text.referrerPolicy Referrer - The referrer policy of the frame on which the menu is invoked.misspelledWord String - The misspelled word under the cursor, if any.dictionarySuggestions String[] - An array of suggested words to show the\nuser to replace the misspelledWord. Only available if there is a misspelled\nword and spellchecker is enabled.frameCharset String - The character encoding of the frame on which the\nmenu was invoked.inputFieldType String - If the context menu was invoked on an input\nfield, the type of that field. Possible values are none, plainText,\npassword, other.spellcheckEnabled Boolean - If the context is editable, whether or not spellchecking is enabled.menuSourceType String - Input source that invoked the context menu.\nCan be none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, or adjustSelectionReset.mediaFlags Object - The flags for the media element the context menu was\ninvoked on.inError Boolean - Whether the media element has crashed.isPaused Boolean - Whether the media element is paused.isMuted Boolean - Whether the media element is muted.hasAudio Boolean - Whether the media element has audio.isLooping Boolean - Whether the media element is looping.isControlsVisible Boolean - Whether the media element's controls are\nvisible.canToggleControls Boolean - Whether the media element's controls are\ntoggleable.canPrint Boolean - Whether the media element can be printed.canSave Boolean - Whether or not the media element can be downloaded.canShowPictureInPicture Boolean - Whether the media element can show picture-in-picture.isShowingPictureInPicture Boolean - Whether the media element is currently showing picture-in-picture.canRotate Boolean - Whether the media element can be rotated.canLoop Boolean - Whether the media element can be looped.editFlags Object - These flags indicate whether the renderer believes it\nis able to perform the corresponding action.canUndo Boolean - Whether the renderer believes it can undo.canRedo Boolean - Whether the renderer believes it can redo.canCut Boolean - Whether the renderer believes it can cut.canCopy Boolean - Whether the renderer believes it can copy.canPaste Boolean - Whether the renderer believes it can paste.canDelete Boolean - Whether the renderer believes it can delete.canSelectAll Boolean - Whether the renderer believes it can select all.canEditRichly Boolean - Whether the renderer believes it can edit text richly.Emitted when there is a new context menu that needs to be handled.
\nReturns:
\nevent Eventdevices BluetoothDevice[]callback FunctiondeviceId StringEmitted when bluetooth device needs to be selected on call to\nnavigator.bluetooth.requestDevice. To use navigator.bluetooth api\nwebBluetooth should be enabled. If event.preventDefault is not called,\nfirst available device will be selected. callback should be called with\ndeviceId to be selected, passing empty string to callback will\ncancel the request.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\napp.commandLine.appendSwitch('enable-experimental-web-platform-features')\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {\n event.preventDefault()\n const result = deviceList.find((device) => {\n return device.deviceName === 'test'\n })\n if (!result) {\n callback('')\n } else {\n callback(result.deviceId)\n }\n })\n})\nReturns:
\nevent EventdirtyRect Rectangleimage NativeImage - The image data of the whole frame.Emitted when a new frame is generated. Only the dirty area is passed in the\nbuffer.
\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ webPreferences: { offscreen: true } })\nwin.webContents.on('paint', (event, dirty, image) => {\n // updateBitmap(dirty, image.getBitmap())\n})\nwin.loadURL('http://github.com')\nEmitted when the devtools window instructs the webContents to reload
\nReturns:
\nevent EventwebPreferences WebPreferences - The web preferences that will be used by the guest\npage. This object can be modified to adjust the preferences for the guest\npage.params Record<string, string> - The other <webview> parameters such as the src URL.\nThis object can be modified to adjust the parameters of the guest page.Emitted when a <webview>'s web contents is being attached to this web\ncontents. Calling event.preventDefault() will destroy the guest page.
This event can be used to configure webPreferences for the webContents\nof a <webview> before it's loaded, and provides the ability to set settings\nthat can't be set via <webview> attributes.
Note: The specified preload script option will appear as preloadURL\n(not preload) in the webPreferences object emitted with this event.
Returns:
\nevent EventwebContents WebContents - The guest web contents that is used by the\n<webview>.Emitted when a <webview> has been attached to this web contents.
Returns:
\nevent Eventlevel Integer - The log level, from 0 to 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Integer - The line number of the source that triggered this console messagesourceId StringEmitted when the associated window logs a console message.
\nReturns:
\nevent EventpreloadPath Stringerror ErrorEmitted when the preload script preloadPath throws an unhandled exception error.
Returns:
\nevent Eventchannel String...args any[]Emitted when the renderer process sends an asynchronous message via ipcRenderer.send().
Returns:
\nevent Eventchannel String...args any[]Emitted when the renderer process sends a synchronous message via ipcRenderer.sendSync().
Returns:
\nevent EventEmitted when desktopCapturer.getSources() is called in the renderer process.\nCalling event.preventDefault() will make it return empty sources.
Returns:
\nevent EventpreferredSize Size - The minimum size needed to\ncontain the layout of the document—without requiring scrolling.Emitted when the WebContents preferred size has changed.
This event will only be emitted when enablePreferredSizeMode is set to true\nin webPreferences.
Returns:
\nevent Eventdetails Objectframe WebFrameMainEmitted when the mainFrame, an <iframe>, or a nested <iframe> is loaded within the page.
contents.loadURL(url[, options])url Stringoptions Object (optional)httpReferrer (String | Referrer) (optional) - An HTTP Referrer url.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\".postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url is a data url and needs to load other files.Returns Promise<void> - the promise will resolve when the page has finished loading\n(see did-finish-load), and rejects\nif the page fails to load (see\ndid-fail-load). A noop rejection handler is already attached, which avoids unhandled rejection errors.
Loads the url in the window. The url must contain the protocol prefix,\ne.g. the http:// or file://. If the load should bypass http cache then\nuse the pragma header to achieve it.
const { webContents } = require('electron')\nconst options = { extraHeaders: 'pragma: no-cache\\n' }\nwebContents.loadURL('https://github.com', options)\ncontents.loadFile(filePath[, options])filePath Stringoptions Object (optional)query Record<String, String> (optional) - Passed to url.format().search String (optional) - Passed to url.format().hash String (optional) - Passed to url.format().Returns Promise<void> - the promise will resolve when the page has finished loading\n(see did-finish-load), and rejects\nif the page fails to load (see did-fail-load).
Loads the given file in the window, filePath should be a path to\nan HTML file relative to the root of your application. For instance\nan app structure like this:
| root\n| - package.json\n| - src\n| - main.js\n| - index.html\nWould require code like this
\nwin.loadFile('src/index.html')\ncontents.downloadURL(url)url StringInitiates a download of the resource at url without navigating. The\nwill-download event of session will be triggered.
contents.getURL()Returns String - The URL of the current web page.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com').then(() => {\n const currentURL = win.webContents.getURL()\n console.log(currentURL)\n})\ncontents.getTitle()Returns String - The title of the current web page.
contents.isDestroyed()Returns Boolean - Whether the web page is destroyed.
contents.focus()Focuses the web page.
\ncontents.isFocused()Returns Boolean - Whether the web page is focused.
contents.isLoading()Returns Boolean - Whether web page is still loading resources.
contents.isLoadingMainFrame()Returns Boolean - Whether the main frame (and not just iframes or frames within it) is\nstill loading.
contents.isWaitingForResponse()Returns Boolean - Whether the web page is waiting for a first-response from the main\nresource of the page.
contents.stop()Stops any pending navigation.
\ncontents.reload()Reloads the current web page.
\ncontents.reloadIgnoringCache()Reloads current page and ignores cache.
\ncontents.canGoBack()Returns Boolean - Whether the browser can go back to previous web page.
contents.canGoForward()Returns Boolean - Whether the browser can go forward to next web page.
contents.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the web page can go to offset.
contents.clearHistory()Clears the navigation history.
\ncontents.goBack()Makes the browser go back a web page.
\ncontents.goForward()Makes the browser go forward a web page.
\ncontents.goToIndex(index)index IntegerNavigates browser to the specified absolute web page index.
\ncontents.goToOffset(offset)offset IntegerNavigates to the specified offset from the \"current entry\".
\ncontents.isCrashed()Returns Boolean - Whether the renderer process has crashed.
contents.forcefullyCrashRenderer()Forcefully terminates the renderer process that is currently hosting this\nwebContents. This will cause the render-process-gone event to be emitted\nwith the reason=killed || reason=crashed. Please note that some webContents share renderer\nprocesses and therefore calling this method may also crash the host process\nfor other webContents as well.
Calling reload() immediately after calling this\nmethod will force the reload to occur in a new process. This should be used\nwhen this process is unstable or unusable, for instance in order to recover\nfrom the unresponsive event.
contents.on('unresponsive', async () => {\n const { response } = await dialog.showMessageBox({\n message: 'App X has become unresponsive',\n title: 'Do you want to try forcefully reloading the app?',\n buttons: ['OK', 'Cancel'],\n cancelId: 1\n })\n if (response === 0) {\n contents.forcefullyCrashRenderer()\n contents.reload()\n }\n})\ncontents.setUserAgent(userAgent)userAgent StringOverrides the user agent for this web page.
\ncontents.getUserAgent()Returns String - The user agent for this web page.
contents.insertCSS(css[, options])css Stringoptions Object (optional)cssOrigin String (optional) - Can be either 'user' or 'author'; Specifying 'user' enables you to prevent websites from overriding the CSS you insert. Default is 'author'.Returns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via contents.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted\nstylesheet.
\ncontents.on('did-finish-load', () => {\n contents.insertCSS('html, body { background-color: #f00; }')\n})\ncontents.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified\nby its key, which is returned from contents.insertCSS(css).
contents.on('did-finish-load', async () => {\n const key = await contents.insertCSS('html, body { background-color: #f00; }')\n contents.removeInsertedCSS(key)\n})\ncontents.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (optional) - Default is false.Returns Promise<any> - A promise that resolves with the result of the executed code\nor is rejected if the result of the code is a rejected promise.
Evaluates code in page.
In the browser window some HTML APIs like requestFullScreen can only be\ninvoked by a gesture from the user. Setting userGesture to true will remove\nthis limitation.
Code execution will be suspended until web page stop loading.
\ncontents.executeJavaScript('fetch(\"https://jsonplaceholder.typicode.com/users/1\").then(resp => resp.json())', true)\n .then((result) => {\n console.log(result) // Will be the JSON object from the fetch call\n })\ncontents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electron's contextIsolation feature. You can provide any integer here.scripts WebSource[]userGesture Boolean (optional) - Default is false.Returns Promise<any> - A promise that resolves with the result of the executed code\nor is rejected if the result of the code is a rejected promise.
Works like executeJavaScript but evaluates scripts in an isolated context.
contents.setIgnoreMenuShortcuts(ignore)ignore BooleanIgnore application menu shortcuts while this web contents is focused.
\ncontents.setWindowOpenHandler(handler)handler Function<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>
details Objecturl String - The resolved version of the URL passed to window.open(). e.g. opening a window with window.open('foo') will yield something like https://the-origin/the/current/path/foo.frameName String - Name of the window provided in window.open()features String - Comma separated list of window features provided to window.open().disposition String - Can be default, foreground-tab, background-tab,\nnew-window, save-to-disk or other.referrer Referrer - The referrer that will be\npassed to the new window. May or may not result in the Referer header being\nsent, depending on the referrer policy.postBody PostBody (optional) - The post data that\nwill be sent to the new window, along with the appropriate headers that will\nbe set. If no post data is to be sent, the value will be null. Only defined\nwhen the window is being created by a form that set target=_blank.Returns {action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny cancels the creation of the new\nwindow. allow will allow the new window to be created. Specifying overrideBrowserWindowOptions allows customization of the created window.\nReturning an unrecognized value such as a null, undefined, or an object\nwithout a recognized 'action' value will result in a console error and have\nthe same effect as returning {action: 'deny'}.
Called before creating a window a new window is requested by the renderer, e.g.\nby window.open(), a link with target=\"_blank\", shift+clicking on a link, or\nsubmitting a form with <form target=\"_blank\">. See\nwindow.open() for more details and how to use this in\nconjunction with did-create-window.
contents.setAudioMuted(muted)muted BooleanMute the audio on the current web page.
\ncontents.isAudioMuted()Returns Boolean - Whether this page has been muted.
contents.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
contents.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Changes the zoom factor to the specified factor. Zoom factor is\nzoom percent divided by 100, so 300% = 3.0.
\nThe factor must be greater than 0.0.
\ncontents.getZoomFactor()Returns Number - the current zoom factor.
contents.setZoomLevel(level)level Number - Zoom level.Changes the zoom level to the specified level. The original size is 0 and each\nincrement above or below represents zooming 20% larger or smaller to default\nlimits of 300% and 50% of original size, respectively. The formula for this is\nscale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the\nzoom level for a specific domain propagates across all instances of windows with\nthe same domain. Differentiating the window URLs will make zoom work per-window.
\n
contents.getZoomLevel()Returns Number - the current zoom level.
contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberReturns Promise<void>
Sets the maximum and minimum pinch-to-zoom level.
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\ncontents.setVisualZoomLevelLimits(1, 3)\n
contents.undo()Executes the editing command undo in web page.
contents.redo()Executes the editing command redo in web page.
contents.cut()Executes the editing command cut in web page.
contents.copy()Executes the editing command copy in web page.
contents.copyImageAt(x, y)x Integery IntegerCopy the image at the given position to the clipboard.
\ncontents.paste()Executes the editing command paste in web page.
contents.pasteAndMatchStyle()Executes the editing command pasteAndMatchStyle in web page.
contents.delete()Executes the editing command delete in web page.
contents.selectAll()Executes the editing command selectAll in web page.
contents.unselect()Executes the editing command unselect in web page.
contents.replace(text)text StringExecutes the editing command replace in web page.
contents.replaceMisspelling(text)text StringExecutes the editing command replaceMisspelling in web page.
contents.insertText(text)text StringReturns Promise<void>
Inserts text to the focused element.
contents.findInPage(text[, options])text String - Content to be searched, must not be empty.options Object (optional)forward Boolean (optional) - Whether to search forward or backward, defaults to true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Defaults to false.matchCase Boolean (optional) - Whether search should be case-sensitive,\ndefaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. The result of the request\ncan be obtained by subscribing to found-in-page event.
contents.stopFindInPage(action)action String - Specifies the action to take place when ending\n[webContents.findInPage] request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webContents with the provided action.
const { webContents } = require('electron')\nwebContents.on('found-in-page', (event, result) => {\n if (result.finalUpdate) webContents.stopFindInPage('clearSelection')\n})\n\nconst requestId = webContents.findInPage('api')\nconsole.log(requestId)\ncontents.capturePage([rect])rect Rectangle (optional) - The area of the page to be captured.Returns Promise<NativeImage> - Resolves with a NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page.
contents.isBeingCaptured()Returns Boolean - Whether this page is being captured. It returns true when the capturer count\nis large then 0.
contents.incrementCapturerCount([size, stayHidden, stayAwake])size Size (optional) - The preferred size for the capturer.stayHidden Boolean (optional) - Keep the page hidden instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Increase the capturer count by one. The page is considered visible when its browser window is\nhidden and the capturer count is non-zero. If you would like the page to stay hidden, you should ensure that stayHidden is set to true.
This also affects the Page Visibility API.
\ncontents.decrementCapturerCount([stayHidden, stayAwake])stayHidden Boolean (optional) - Keep the page in hidden state instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Decrease the capturer count by one. The page will be set to hidden or occluded state when its\nbrowser window is hidden or occluded and the capturer count reaches zero. If you want to\ndecrease the hidden capturer count instead you should set stayHidden to true.
contents.getPrinters()Get the system printer list.
\nReturns PrinterInfo[]
contents.print([options], [callback])options Object (optional)silent Boolean (optional) - Don't ask user for print settings. Default is false.printBackground Boolean (optional) - Prints the background color and image of\nthe web page. Default is false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. Default is true.margins Object (optional)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. Default is false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print. On macOS, only one range is honored.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Can be simplex, shortEdge, or longEdge.dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3,\nA4, A5, Legal, Letter, Tabloid or an Object containing height.callback Function (optional)success Boolean - Indicates success of the print call.failureReason String - Error description called back if the print fails.When a custom pageSize is passed, Chromium attempts to validate platform specific minimum values for width_microns and height_microns. Width and height must both be minimum 353 microns but may be higher on some operating systems.
Prints window's web page. When silent is set to true, Electron will pick\nthe system's default printer if deviceName is empty and the default settings for printing.
Use page-break-before: always; CSS style to force to print to a new page.
Example usage:
\nconst options = {\n silent: true,\n deviceName: 'My-Printer',\n pageRanges: [{\n from: 0,\n to: 1\n }]\n}\nwin.webContents.print(options, (success, errorType) => {\n if (!success) console.log(errorType)\n})\ncontents.printToPDF(options)options ObjectheaderFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for\ndefault margin, 1 for no margin, and 2 for minimum margin.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3,\nA4, A5, Legal, Letter, Tabloid or an Object containing height and width in microns.printBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Buffer> - Resolves with the generated PDF data.
Prints window's web page as PDF with Chromium's preview printing custom\nsettings.
\nThe landscape will be ignored if @page CSS at-rule is used in the web page.
By default, an empty options will be regarded as:
{\n marginsType: 0,\n printBackground: false,\n printSelectionOnly: false,\n landscape: false,\n pageSize: 'A4',\n scaleFactor: 100\n}\nUse page-break-before: always; CSS style to force to print to a new page.
An example of webContents.printToPDF:
const { BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\nconst os = require('os')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nwin.webContents.on('did-finish-load', () => {\n // Use default printing options\n win.webContents.printToPDF({}).then(data => {\n const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')\n fs.writeFile(pdfPath, data, (error) => {\n if (error) throw error\n console.log(`Wrote PDF successfully to ${pdfPath}`)\n })\n }).catch(error => {\n console.log(`Failed to write PDF to ${pdfPath}: `, error)\n })\n})\ncontents.addWorkSpace(path)path StringAdds the specified path to DevTools workspace. Must be used after DevTools\ncreation:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.on('devtools-opened', () => {\n win.webContents.addWorkSpace(__dirname)\n})\ncontents.removeWorkSpace(path)path StringRemoves the specified path from DevTools workspace.
\ncontents.setDevToolsWebContents(devToolsWebContents)devToolsWebContents WebContentsUses the devToolsWebContents as the target WebContents to show devtools.
The devToolsWebContents must not have done any navigation, and it should not\nbe used for other purposes after the call.
By default Electron manages the devtools by creating an internal WebContents\nwith native view, which developers have very limited control of. With the\nsetDevToolsWebContents method, developers can use any WebContents to show\nthe devtools in it, including BrowserWindow, BrowserView and <webview>\ntag.
Note that closing the devtools does not destroy the devToolsWebContents, it\nis caller's responsibility to destroy devToolsWebContents.
An example of showing devtools in a <webview> tag:
<html>\n<head>\n <style type=\"text/css\">\n * { margin: 0; }\n #browser { height: 70%; }\n #devtools { height: 30%; }\n </style>\n</head>\n<body>\n <webview id=\"browser\" src=\"https://github.com\"></webview>\n <webview id=\"devtools\" src=\"about:blank\"></webview>\n <script>\n const { ipcRenderer } = require('electron')\n const emittedOnce = (element, eventName) => new Promise(resolve => {\n element.addEventListener(eventName, event => resolve(event), { once: true })\n })\n const browserView = document.getElementById('browser')\n const devtoolsView = document.getElementById('devtools')\n const browserReady = emittedOnce(browserView, 'dom-ready')\n const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')\n Promise.all([browserReady, devtoolsReady]).then(() => {\n const targetId = browserView.getWebContentsId()\n const devtoolsId = devtoolsView.getWebContentsId()\n ipcRenderer.send('open-devtools', targetId, devtoolsId)\n })\n </script>\n</body>\n</html>\n// Main process\nconst { ipcMain, webContents } = require('electron')\nipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {\n const target = webContents.fromId(targetContentsId)\n const devtools = webContents.fromId(devtoolsContentsId)\n target.setDevToolsWebContents(devtools)\n target.openDevTools()\n})\nAn example of showing devtools in a BrowserWindow:
const { app, BrowserWindow } = require('electron')\n\nlet win = null\nlet devtools = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n devtools = new BrowserWindow()\n win.loadURL('https://github.com')\n win.webContents.setDevToolsWebContents(devtools.webContents)\n win.webContents.openDevTools({ mode: 'detach' })\n})\ncontents.openDevTools([options])options Object (optional)mode String - Opens the devtools with specified dock state, can be\nright, bottom, undocked, detach. Defaults to last used dock state.\nIn undocked mode it's possible to dock back. In detach mode it's not.activate Boolean (optional) - Whether to bring the opened devtools window\nto the foreground. The default is true.Opens the devtools.
\nWhen contents is a <webview> tag, the mode would be detach by default,\nexplicitly passing an empty mode can force using last used dock state.
contents.closeDevTools()Closes the devtools.
\ncontents.isDevToolsOpened()Returns Boolean - Whether the devtools is opened.
contents.isDevToolsFocused()Returns Boolean - Whether the devtools view is focused .
contents.toggleDevTools()Toggles the developer tools.
\ncontents.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y).
contents.inspectSharedWorker()Opens the developer tools for the shared worker context.
\ncontents.inspectSharedWorkerById(workerId)workerId StringInspects the shared worker based on its ID.
\ncontents.getAllSharedWorkers()Returns SharedWorkerInfo[] - Information about all Shared Workers.
contents.inspectServiceWorker()Opens the developer tools for the service worker context.
\ncontents.send(channel, ...args)channel String...args any[]Send an asynchronous message to the renderer process via channel, along with\narguments. Arguments will be serialized with the Structured Clone\nAlgorithm, just like postMessage, so prototype chains will not be\nincluded. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will\nthrow an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or\nspecial Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the\nipcRenderer module.
An example of sending messages from the main process to the renderer process:
\n// In the main process.\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL(`file://${__dirname}/index.html`)\n win.webContents.on('did-finish-load', () => {\n win.webContents.send('ping', 'whoooooooh!')\n })\n})\n<!-- index.html -->\n<html>\n<body>\n <script>\n require('electron').ipcRenderer.on('ping', (event, message) => {\n console.log(message) // Prints 'whoooooooh!'\n })\n </script>\n</body>\n</html>\ncontents.sendToFrame(frameId, channel, ...args)frameId Integer | [number, number] - the ID of the frame to send to, or a\npair of [processId, frameId] if the frame is in a different process to the\nmain frame.channel String...args any[]Send an asynchronous message to a specific frame in a renderer process via\nchannel, along with arguments. Arguments will be serialized with the\nStructured Clone Algorithm, just like postMessage, so prototype\nchains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or\nWeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or\nspecial Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the\nipcRenderer module.
If you want to get the frameId of a given renderer context you should use\nthe webFrame.routingId value. E.g.
// In a renderer process\nconsole.log('My frameId is:', require('electron').webFrame.routingId)\nYou can also read frameId from all incoming IPC messages in the main process.
// In the main process\nipcMain.on('ping', (event) => {\n console.info('Message came from frameId:', event.frameId)\n})\ncontents.postMessage(channel, message, [transfer])Send a message to the renderer process, optionally transferring ownership of\nzero or more [MessagePortMain][] objects.
The transferred MessagePortMain objects will be available in the renderer\nprocess by accessing the ports property of the emitted event. When they\narrive in the renderer, they will be native DOM MessagePort objects.
For example:
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\ncontents.enableDeviceEmulation(parameters)parameters ObjectscreenPosition String - Specify the screen type to emulate\n(default: desktop):desktop - Desktop screen type.mobile - Mobile screen type.screenSize Size - Set the emulated screen size (screenPosition == mobile).viewPosition Point - Position the view on the screen\n(screenPosition == mobile) (default: { x: 0, y: 0 }).deviceScaleFactor Integer - Set the device scale factor (if zero defaults to\noriginal device scale factor) (default: 0).viewSize Size - Set the emulated view size (empty means no override)scale Float - Scale of emulated view inside available space (not in fit to\nview mode) (default: 1).Enable device emulation with the given parameters.
\ncontents.disableDeviceEmulation()Disable device emulation enabled by webContents.enableDeviceEmulation.
contents.sendInputEvent(inputEvent)inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventSends an input event to the page.\nNote: The BrowserWindow containing the contents needs to be focused for\nsendInputEvent() to work.
contents.beginFrameSubscription([onlyDirty ,]callback)onlyDirty Boolean (optional) - Defaults to false.callback Functionimage NativeImagedirtyRect RectangleBegin subscribing for presentation events and captured frames, the callback\nwill be called with callback(image, dirtyRect) when there is a presentation\nevent.
The image is an instance of NativeImage that stores the\ncaptured frame.
The dirtyRect is an object with x, y, width, height properties that\ndescribes which part of the page was repainted. If onlyDirty is set to\ntrue, image will only contain the repainted area. onlyDirty defaults to\nfalse.
contents.endFrameSubscription()End subscribing for frame presentation events.
\ncontents.startDrag(item)item Objectfile String - The path to the file being dragged.files String - The paths to the files being dragged. (files will override file field)icon NativeImage | String - The image must be\nnon-empty on macOS.Sets the item as dragging item for current drag-drop operation, file is the\nabsolute path of the file to be dragged, and icon is the image showing under\nthe cursor when dragging.
contents.savePage(fullPath, saveType)fullPath String - The full file path.saveType String - Specify the save type.HTMLOnly - Save only the HTML of the page.HTMLComplete - Save complete-html page.MHTML - Save complete-html page as MHTML.Returns Promise<void> - resolves if the page is saved.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.loadURL('https://github.com')\n\nwin.webContents.on('did-finish-load', async () => {\n win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {\n console.log('Page was saved successfully.')\n }).catch(err => {\n console.log(err)\n })\n})\ncontents.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\ncontents.isOffscreen()Returns Boolean - Indicates whether offscreen rendering is enabled.
contents.startPainting()If offscreen rendering is enabled and not painting, start painting.
\ncontents.stopPainting()If offscreen rendering is enabled and painting, stop painting.
\ncontents.isPainting()Returns Boolean - If offscreen rendering is enabled returns whether it is currently painting.
contents.setFrameRate(fps)fps IntegerIf offscreen rendering is enabled sets the frame rate to the specified number.\nOnly values between 1 and 240 are accepted.
\ncontents.getFrameRate()Returns Integer - If offscreen rendering is enabled returns the current frame rate.
contents.invalidate()Schedules a full repaint of the window this web contents is in.
\nIf offscreen rendering is enabled invalidates the frame and generates a new\none through the 'paint' event.
contents.getWebRTCIPHandlingPolicy()Returns String - Returns the WebRTC IP Handling Policy.
contents.setWebRTCIPHandlingPolicy(policy)policy String - Specify the WebRTC IP Handling Policy.default - Exposes user's public and local IPs. This is the default\nbehavior. When this policy is used, WebRTC has the right to enumerate all\ninterfaces and bind them to discover public interfaces.default_public_interface_only - Exposes user's public IP, but does not\nexpose user's local IP. When this policy is used, WebRTC should only use the\ndefault route used by http. This doesn't expose any local addresses.default_public_and_private_interfaces - Exposes user's public and local\nIPs. When this policy is used, WebRTC should only use the default route used\nby http. This also exposes the associated default private address. Default\nroute is the route chosen by the OS on a multi-homed endpoint.disable_non_proxied_udp - Does not expose public or local IPs. When this\npolicy is used, WebRTC should only use TCP to contact peers or servers unless\nthe proxy server supports UDP.Setting the WebRTC IP handling policy allows you to control which IPs are\nexposed via WebRTC. See BrowserLeaks for\nmore details.
\ncontents.getOSProcessId()Returns Integer - The operating system pid of the associated renderer\nprocess.
contents.getProcessId()Returns Integer - The Chromium internal pid of the associated renderer. Can\nbe compared to the frameProcessId passed by frame specific navigation events\n(e.g. did-frame-navigate)
contents.takeHeapSnapshot(filePath)filePath String - Path to the output file.Returns Promise<void> - Indicates whether the snapshot has been created successfully.
Takes a V8 heap snapshot and saves it to filePath.
contents.getBackgroundThrottling()Returns Boolean - whether or not this WebContents will throttle animations and timers\nwhen the page becomes backgrounded. This also affects the Page Visibility API.
contents.setBackgroundThrottling(allowed)allowed BooleanControls whether or not this WebContents will throttle animations and timers\nwhen the page becomes backgrounded. This also affects the Page Visibility API.
\ncontents.getType()Returns String - the type of the webContent. Can be backgroundPage, window, browserView, remote, webview or offscreen.
contents.setImageAnimationPolicy(policy)policy String - Can be animate, animateOnce or noAnimation.Sets the image animation policy for this webContents. The policy only affects\nnew images, existing images that are currently being animated are unaffected.\nThis is a known limitation in Chromium, you can force image animation to be\nrecalculated with img.src = img.src which will result in no network traffic\nbut will update the animation policy.
This corresponds to the animationPolicy accessibility feature in Chromium.
\ncontents.audioMutedA Boolean property that determines whether this page is muted.
contents.userAgentA String property that determines the user agent for this web page.
contents.zoomLevelA Number property that determines the zoom level for this web contents.
The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
contents.zoomFactorA Number property that determines the zoom factor for this web contents.
The zoom factor is the zoom percent divided by 100, so 300% = 3.0.
\ncontents.frameRateAn Integer property that sets the frame rate of the web contents to the specified number.\nOnly values between 1 and 240 are accepted.
Only applicable if offscreen rendering is enabled.
\ncontents.id ReadonlyA Integer representing the unique ID of this WebContents. Each ID is unique among all WebContents instances of the entire Electron application.
contents.session ReadonlyA Session used by this webContents.
contents.hostWebContents ReadonlyA WebContents instance that might own this WebContents.
contents.devToolsWebContents ReadonlyA WebContents | null property that represents the of DevTools WebContents associated with a given WebContents.
Note: Users should never store this object because it may become null\nwhen the DevTools has been closed.
contents.debugger ReadonlyA Debugger instance for this webContents.
contents.backgroundThrottlingA Boolean property that determines whether or not this WebContents will throttle animations and timers\nwhen the page becomes backgrounded. This also affects the Page Visibility API.
contents.mainFrame ReadonlyA WebFrameMain property that represents the top frame of the page's frame hierarchy.
If you want to embed (third-party) web content in an Electron BrowserWindow,\nthere are three options available to you: <iframe> tags, <webview> tags,\nand BrowserViews. Each one offers slightly different functionality and is\nuseful in different situations. To help you choose between these, this guide\nexplains the differences and capabilities of each option.
Iframes in Electron behave like iframes in regular browsers. An <iframe>\nelement in your page can show external web pages, provided that their\nContent Security Policy\nallows it. To limit the number of capabilities of a site in an <iframe> tag,\nit is recommended to use the sandbox attribute\nand only allow the capabilities you want to support.
\n\nImportant Note:\nwe do not recommend you to use WebViews,\nas this tag undergoes dramatic architectural changes that may affect stability\nof your application. Consider switching to alternatives, like
\niframeand\nElectron'sBrowserView, or an architecture that avoids embedded content\nby design.
WebViews are based on Chromium's WebViews and are not\nexplicitly supported by Electron. We do not guarantee that the WebView API will\nremain available in future versions of Electron. To use <webview> tags, you\nwill need to set webviewTag to true in the webPreferences of your\nBrowserWindow.
WebView is a custom element (<webview>) that will only work inside Electron.\nThey are implemented as an \"out-of-process iframe\". This means that all\ncommunication with the <webview> is done asynchronously using IPC. The\n<webview> element has many custom methods and events, similar to\nwebContents, that provide you with greater control over the content.
Compared to an <iframe>, <webview> tends to be slightly slower but offers\nmuch greater control in loading and communicating with the third-party content\nand handling various events.
BrowserViews are not a part of the DOM - instead,\nthey are created in and controlled by your Main process. They are simply\nanother layer of web content on top of your existing window. This means\nthat they are completely separate from your own BrowserWindow content and\ntheir position is not controlled by the DOM or CSS. Instead, it is controlled\nby setting the bounds in the Main process.
BrowserViews offer the greatest control over their contents, since they\nimplement the webContents similarly to how the BrowserWindow does it.\nHowever, as BrowserViews are not a part of your DOM, but are rather overlaid\non top of them, you will have to manage their position manually.
\n\nCustomize the rendering of the current web page.
\n
Process: Renderer
\nwebFrame export of the Electron module is an instance of the WebFrame\nclass representing the top frame of the current BrowserWindow. Sub-frames can\nbe retrieved by certain properties and methods (e.g. webFrame.firstChild).
An example of zooming current page to 200%.
\nconst { webFrame } = require('electron')\n\nwebFrame.setZoomFactor(2)\nThe WebFrame class has the following instance methods:
webFrame.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Changes the zoom factor to the specified factor. Zoom factor is\nzoom percent divided by 100, so 300% = 3.0.
\nThe factor must be greater than 0.0.
\nwebFrame.getZoomFactor()Returns Number - The current zoom factor.
webFrame.setZoomLevel(level)level Number - Zoom level.Changes the zoom level to the specified level. The original size is 0 and each\nincrement above or below represents zooming 20% larger or smaller to default\nlimits of 300% and 50% of original size, respectively.
\n\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the\nzoom level for a specific domain propagates across all instances of windows with\nthe same domain. Differentiating the window URLs will make zoom work per-window.
\n
webFrame.getZoomLevel()Returns Number - The current zoom level.
webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberSets the maximum and minimum pinch-to-zoom level.
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\nwebFrame.setVisualZoomLevelLimits(1, 3)\n
\n\nNOTE: Visual zoom only applies to pinch-to-zoom behavior. Cmd+/-/0 zoom shortcuts are\ncontrolled by the 'zoomIn', 'zoomOut', and 'resetZoom' MenuItem roles in the application\nMenu. To disable shortcuts, manually define the Menu and omit zoom roles\nfrom the definition.
\n
webFrame.setSpellCheckProvider(language, provider)language Stringprovider ObjectspellCheck Functionwords String[]callback FunctionmisspeltWords String[]Sets a provider for spell checking in input fields and text areas.
\nIf you want to use this method you must disable the builtin spellchecker when you\nconstruct the window.
\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: false\n }\n})\nThe provider must be an object that has a spellCheck method that accepts\nan array of individual words for spellchecking.\nThe spellCheck function runs asynchronously and calls the callback function\nwith an array of misspelt words when complete.
An example of using node-spellchecker as provider:
\nconst { webFrame } = require('electron')\nconst spellChecker = require('spellchecker')\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck (words, callback) {\n setTimeout(() => {\n const spellchecker = require('spellchecker')\n const misspelled = words.filter(x => spellchecker.isMisspelled(x))\n callback(misspelled)\n }, 0)\n }\n})\nwebFrame.insertCSS(css)css String - CSS source code.Returns String - A key for the inserted CSS that can later be used to remove\nthe CSS via webFrame.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted\nstylesheet.
\nwebFrame.removeInsertedCSS(key)key StringRemoves the inserted CSS from the current web page. The stylesheet is identified\nby its key, which is returned from webFrame.insertCSS(css).
webFrame.insertText(text)text StringInserts text to the focused element.
webFrame.executeJavaScript(code[, userGesture, callback])code StringuserGesture Boolean (optional) - Default is false.callback Function (optional) - Called after script has been executed. Unless\nthe frame is suspended (e.g. showing a modal alert), execution will be\nsynchronous and the callback will be invoked before the method returns. For\ncompatibility with an older version of this method, the error parameter is\nsecond.result Anyerror ErrorReturns Promise<any> - A promise that resolves with the result of the executed\ncode or is rejected if execution throws or results in a rejected promise.
Evaluates code in page.
In the browser window some HTML APIs like requestFullScreen can only be\ninvoked by a gesture from the user. Setting userGesture to true will remove\nthis limitation.
webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])worldId Integer - The ID of the world to run the javascript\nin, 0 is the default main world (where content runs), 999 is the\nworld used by Electron's contextIsolation feature. Accepts values\nin the range 1..536870911.scripts WebSource[]userGesture Boolean (optional) - Default is false.callback Function (optional) - Called after script has been executed. Unless\nthe frame is suspended (e.g. showing a modal alert), execution will be\nsynchronous and the callback will be invoked before the method returns. For\ncompatibility with an older version of this method, the error parameter is\nsecond.result Anyerror ErrorReturns Promise<any> - A promise that resolves with the result of the executed\ncode or is rejected if execution could not start.
Works like executeJavaScript but evaluates scripts in an isolated context.
Note that when the execution of script fails, the returned promise will not\nreject and the result would be undefined. This is because Chromium does not\ndispatch errors of isolated worlds to foreign worlds.
webFrame.setIsolatedWorldInfo(worldId, info)worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electrons contextIsolation feature. Chrome extensions reserve the range of IDs in [1 << 20, 1 << 29). You can provide any integer here.info ObjectsecurityOrigin String (optional) - Security origin for the isolated world.csp String (optional) - Content Security Policy for the isolated world.name String (optional) - Name for isolated world. Useful in devtools.Set the security origin, content security policy and name of the isolated world.\nNote: If the csp is specified, then the securityOrigin also has to be specified.
webFrame.getResourceUsage()Returns Object:
images MemoryUsageDetailsscripts MemoryUsageDetailscssStyleSheets MemoryUsageDetailsxslStyleSheets MemoryUsageDetailsfonts MemoryUsageDetailsother MemoryUsageDetailsReturns an object describing usage information of Blink's internal memory\ncaches.
\nconst { webFrame } = require('electron')\nconsole.log(webFrame.getResourceUsage())\nThis will generate:
\n{\n images: {\n count: 22,\n size: 2549,\n liveSize: 2542\n },\n cssStyleSheets: { /* same with \"images\" */ },\n xslStyleSheets: { /* same with \"images\" */ },\n fonts: { /* same with \"images\" */ },\n other: { /* same with \"images\" */ }\n}\nwebFrame.clearCache()Attempts to free memory that is no longer being used (like images from a\nprevious navigation).
\nNote that blindly calling this method probably makes Electron slower since it\nwill have to refill these emptied caches, you should only call it if an event\nin your app has occurred that makes you think your page is actually using less\nmemory (i.e. you have navigated from a super heavy page to a mostly empty one,\nand intend to stay there).
\nwebFrame.getFrameForSelector(selector)selector String - CSS selector for a frame element.Returns WebFrame - The frame element in webFrame's document selected by\nselector, null would be returned if selector does not select a frame or\nif the frame is not in the current renderer process.
webFrame.findFrameByName(name)name StringReturns WebFrame - A child of webFrame with the supplied name, null\nwould be returned if there's no such frame or if the frame is not in the current\nrenderer process.
webFrame.findFrameByRoutingId(routingId)routingId Integer - An Integer representing the unique frame id in the\ncurrent renderer process. Routing IDs can be retrieved from WebFrame\ninstances (webFrame.routingId) and are also passed by frame\nspecific WebContents navigation events (e.g. did-frame-navigate)Returns WebFrame - that has the supplied routingId, null if not found.
webFrame.isWordMisspelled(word)word String - The word to be spellchecked.Returns Boolean - True if the word is misspelled according to the built in\nspellchecker, false otherwise. If no dictionary is loaded, always return false.
webFrame.getWordSuggestions(word)word String - The misspelled word.Returns String[] - A list of suggested words for a given word. If the word\nis spelled correctly, the result will be empty.
webFrame.top ReadonlyA WebFrame | null representing top frame in frame hierarchy to which webFrame\nbelongs, the property would be null if top frame is not in the current\nrenderer process.
webFrame.opener ReadonlyA WebFrame | null representing the frame which opened webFrame, the property would\nbe null if there's no opener or opener is not in the current renderer process.
webFrame.parent ReadonlyA WebFrame | null representing parent frame of webFrame, the property would be\nnull if webFrame is top or parent is not in the current renderer process.
webFrame.firstChild ReadonlyA WebFrame | null representing the first child frame of webFrame, the property\nwould be null if webFrame has no children or if first child is not in the\ncurrent renderer process.
webFrame.nextSibling ReadonlyA WebFrame | null representing next sibling frame, the property would be null if\nwebFrame is the last frame in its parent or if the next sibling is not in the\ncurrent renderer process.
webFrame.routingId ReadonlyAn Integer representing the unique frame id in the current renderer process.\nDistinct WebFrame instances that refer to the same underlying frame will have\nthe same routingId.
\n\nControl web pages and iframes.
\n
Process: Main
\nThe webFrameMain module can be used to lookup frames across existing\nWebContents instances. Navigation events are the common\nuse case.
const { BrowserWindow, webFrameMain } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://twitter.com')\n\nwin.webContents.on(\n 'did-frame-navigate',\n (event, url, isMainFrame, frameProcessId, frameRoutingId) => {\n const frame = webFrameMain.fromId(frameProcessId, frameRoutingId)\n if (frame) {\n const code = 'document.body.innerHTML = document.body.innerHTML.replaceAll(\"heck\", \"h*ck\")'\n frame.executeJavaScript(code)\n }\n }\n)\nYou can also access frames of existing pages by using the mainFrame property\nof WebContents.
const { BrowserWindow } = require('electron')\n\nasync function main () {\n const win = new BrowserWindow({ width: 800, height: 600 })\n await win.loadURL('https://reddit.com')\n\n const youtubeEmbeds = win.webContents.mainFrame.frames.filter((frame) => {\n try {\n const url = new URL(frame.url)\n return url.host === 'www.youtube.com'\n } catch {\n return false\n }\n })\n\n console.log(youtubeEmbeds)\n}\n\nmain()\nThese methods can be accessed from the webFrameMain module:
webFrameMain.fromId(processId, routingId)processId Integer - An Integer representing the internal ID of the process which owns the frame.routingId Integer - An Integer representing the unique frame ID in the\ncurrent renderer process. Routing IDs can be retrieved from WebFrameMain\ninstances (frame.routingId) and are also passed by frame\nspecific WebContents navigation events (e.g. did-frame-navigate).Returns WebFrameMain | undefined - A frame with the given process and routing IDs,\nor undefined if there is no WebFrameMain associated with the given IDs.
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emitted when the document is loaded.
\nframe.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (optional) - Default is false.Returns Promise<unknown> - A promise that resolves with the result of the executed\ncode or is rejected if execution throws or results in a rejected promise.
Evaluates code in page.
In the browser window some HTML APIs like requestFullScreen can only be\ninvoked by a gesture from the user. Setting userGesture to true will remove\nthis limitation.
frame.reload()Returns boolean - Whether the reload was initiated successfully. Only results in false when the frame has no history.
frame.send(channel, ...args)channel String...args any[]Send an asynchronous message to the renderer process via channel, along with\narguments. Arguments will be serialized with the [Structured Clone\nAlgorithm][SCA], just like [postMessage][], so prototype chains will not be\nincluded. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will\nthrow an exception.
The renderer process can handle the message by listening to channel with the\nipcRenderer module.
frame.postMessage(channel, message, [transfer])Send a message to the renderer process, optionally transferring ownership of\nzero or more [MessagePortMain][] objects.
The transferred MessagePortMain objects will be available in the renderer\nprocess by accessing the ports property of the emitted event. When they\narrive in the renderer, they will be native DOM MessagePort objects.
For example:
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nframe.url ReadonlyA string representing the current URL of the frame.
frame.top ReadonlyA WebFrameMain | null representing top frame in the frame hierarchy to which frame\nbelongs.
frame.parent ReadonlyA WebFrameMain | null representing parent frame of frame, the property would be\nnull if frame is the top frame in the frame hierarchy.
frame.frames ReadonlyA WebFrameMain[] collection containing the direct descendents of frame.
frame.framesInSubtree ReadonlyA WebFrameMain[] collection containing every frame in the subtree of frame,\nincluding itself. This can be useful when traversing through all frames.
frame.frameTreeNodeId ReadonlyAn Integer representing the id of the frame's internal FrameTreeNode\ninstance. This id is browser-global and uniquely identifies a frame that hosts\ncontent. The identifier is fixed at the creation of the frame and stays\nconstant for the lifetime of the frame. When the frame is removed, the id is\nnot used again.
frame.name ReadonlyA String representing the frame name.
frame.osProcessId ReadonlyAn Integer representing the operating system pid of the process which owns this frame.
frame.processId ReadonlyAn Integer representing the Chromium internal pid of the process which owns this frame.\nThis is not the same as the OS process ID; to read that use frame.osProcessId.
frame.routingId ReadonlyAn Integer representing the unique frame id in the current renderer process.\nDistinct WebFrameMain instances that refer to the same underlying frame will\nhave the same routingId.
frame.visibilityState ReadonlyA string representing the visibility state of the frame.
See also how the Page Visibility API is affected by other Electron APIs.
", "title": "webFrameMain", "description": "Control web pages and iframes." }, "/docs/api/web-request": { "locale": "en-US", "slug": "web-request", "href": "/docs/api/web-request", "crowdinFileId": "256405", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-request.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nIntercept and modify the contents of a request at various stages of its lifetime.
\n
Process: Main
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Instances of the WebRequest class are accessed by using the webRequest\nproperty of a Session.
The methods of WebRequest accept an optional filter and a listener. The\nlistener will be called with listener(details) when the API's event has\nhappened. The details object describes the request.
⚠️ Only the last attached listener will be used. Passing null as listener will unsubscribe from the event.
The filter object has a urls property which is an Array of URL\npatterns that will be used to filter out the requests that do not match the URL\npatterns. If the filter is omitted then all requests will be matched.
For certain events the listener is passed with a callback, which should be\ncalled with a response object when listener has done its work.
An example of adding User-Agent header for requests:
const { session } = require('electron')\n\n// Modify the user agent for all requests to the following urls.\nconst filter = {\n urls: ['https://*.github.com/*', '*://electron.github.io']\n}\n\nsession.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {\n details.requestHeaders['User-Agent'] = 'MyAgent'\n callback({ requestHeaders: details.requestHeaders })\n})\nThe following methods are available on instances of WebRequest:
webRequest.onBeforeRequest([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleuploadData UploadData[]callback Functionresponse Objectcancel Boolean (optional)redirectURL String (optional) - The original request is prevented from\nbeing sent or completed and is instead redirected to the given URL.The listener will be called with listener(details, callback) when a request\nis about to occur.
The uploadData is an array of UploadData objects.
The callback has to be called with an response object.
Some examples of valid urls:
'http://foo:1234/'\n'http://foo.com/'\n'http://foo:1234/bar'\n'*://*/*'\n'*://example.com/*'\n'*://example.com/foo/*'\n'http://*.foo:1234/'\n'file://foo:1234/bar'\n'http://foo:*/'\n'*://www.foo.com/'\nwebRequest.onBeforeSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders Record<string, string>callback FunctionbeforeSendResponse Object\n cancel Boolean (optional)\n requestHeaders Record<string, string | string[]> (optional) - When provided, request will be made\nwith these headers.The listener will be called with listener(details, callback) before sending\nan HTTP request, once the request headers are available. This may occur after a\nTCP connection is made to the server, but before any http data is sent.
The callback has to be called with a response object.
webRequest.onSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders Record<string, string>The listener will be called with listener(details) just before a request is\ngoing to be sent to the server, modifications of previous onBeforeSendHeaders\nresponse are visible by the time this listener is fired.
webRequest.onHeadersReceived([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublestatusLine StringstatusCode IntegerresponseHeaders Record<string, string[]> (optional)callback FunctionheadersReceivedResponse Objectcancel Boolean (optional)responseHeaders Record<string, string | string[]> (optional) - When provided, the server is assumed\nto have responded with these headers.statusLine String (optional) - Should be provided when overriding\nresponseHeaders to change header status otherwise original response\nheader's status will be used.The listener will be called with listener(details, callback) when HTTP\nresponse headers of a request have been received.
The callback has to be called with a response object.
webRequest.onResponseStarted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache Boolean - Indicates whether the response was fetched from disk\ncache.statusCode IntegerstatusLine StringThe listener will be called with listener(details) when first byte of the\nresponse body is received. For HTTP requests, this means that the status line\nand response headers are available.
webRequest.onBeforeRedirect([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleredirectURL StringstatusCode IntegerstatusLine Stringip String (optional) - The server IP address that the request was\nactually sent to.fromCache BooleanresponseHeaders Record<string, string[]> (optional)The listener will be called with listener(details) when a server initiated\nredirect is about to occur.
webRequest.onCompleted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache BooleanstatusCode IntegerstatusLine Stringerror StringThe listener will be called with listener(details) when a request is\ncompleted.
webRequest.onErrorOccurred([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublefromCache Booleanerror String - The error description.The listener will be called with listener(details) when an error occurs.
urls String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.code Stringurl String (optional)startLine Integer (optional) - Default is 1.<webview> TagElectron's webview tag is based on Chromium's webview, which\nis undergoing dramatic architectural changes. This impacts the stability of webviews,\nincluding rendering, navigation, and event routing. We currently recommend to not\nuse the webview tag and to consider alternatives, like iframe, Electron's BrowserView,\nor an architecture that avoids embedded content altogether.
By default the webview tag is disabled in Electron >= 5. You need to enable the tag by\nsetting the webviewTag webPreferences option when constructing your BrowserWindow. For\nmore information see the BrowserWindow constructor docs.
\n\nDisplay external web content in an isolated frame and process.
\n
Process: Renderer
\nThis class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Use the webview tag to embed 'guest' content (such as web pages) in your\nElectron app. The guest content is contained within the webview container.\nAn embedded page within your app controls how the guest content is laid out and\nrendered.
Unlike an iframe, the webview runs in a separate process than your\napp. It doesn't have the same permissions as your web page and all interactions\nbetween your app and embedded content will be asynchronous. This keeps your app\nsafe from the embedded content. Note: Most methods called on the\nwebview from the host page require a synchronous call to the main process.
To embed a web page in your app, add the webview tag to your app's embedder\npage (this is the app page that will display the guest content). In its simplest\nform, the webview tag includes the src of the web page and css styles that\ncontrol the appearance of the webview container:
<webview id=\"foo\" src=\"https://www.github.com/\" style=\"display:inline-flex; width:640px; height:480px\"></webview>\nIf you want to control the guest content in any way, you can write JavaScript\nthat listens for webview events and responds to those events using the\nwebview methods. Here's sample code with two event listeners: one that listens\nfor the web page to start loading, the other for the web page to stop loading,\nand displays a \"loading...\" message during the load time:
<script>\n onload = () => {\n const webview = document.querySelector('webview')\n const indicator = document.querySelector('.indicator')\n\n const loadstart = () => {\n indicator.innerText = 'loading...'\n }\n\n const loadstop = () => {\n indicator.innerText = ''\n }\n\n webview.addEventListener('did-start-loading', loadstart)\n webview.addEventListener('did-stop-loading', loadstop)\n }\n</script>\nUnder the hood webview is implemented with Out-of-Process iframes (OOPIFs).\nThe webview tag is essentially a custom element using shadow DOM to wrap an\niframe element inside it.
So the behavior of webview is very similar to a cross-domain iframe, as\nexamples:
webview, the page focus will move from the embedder\nframe to webview.webview.webview are asynchronous.Please note that the webview tag's style uses display:flex; internally to\nensure the child iframe element fills the full height and width of its webview\ncontainer when used with traditional and flexbox layouts. Please do not\noverwrite the default display:flex; CSS property, unless specifying\ndisplay:inline-flex; for inline layout.
The webview tag has the following attributes:
src<webview src=\"https://www.github.com/\"></webview>\nA String representing the visible URL. Writing to this attribute initiates top-level\nnavigation.
Assigning src its own value will reload the current page.
The src attribute can also accept data URLs, such as\ndata:text/plain,Hello, world!.
nodeintegration<webview src=\"http://www.google.com/\" nodeintegration></webview>\nA Boolean. When this attribute is present the guest page in webview will have node\nintegration and can use node APIs like require and process to access low\nlevel system resources. Node integration is disabled by default in the guest\npage.
nodeintegrationinsubframes<webview src=\"http://www.google.com/\" nodeintegrationinsubframes></webview>\nA Boolean for the experimental option for enabling NodeJS support in sub-frames such as iframes\ninside the webview. All your preloads will load for every iframe, you can\nuse process.isMainFrame to determine if you are in the main frame or not.\nThis option is disabled by default in the guest page.
plugins<webview src=\"https://www.github.com/\" plugins></webview>\nA Boolean. When this attribute is present the guest page in webview will be able to use\nbrowser plugins. Plugins are disabled by default.
preload<!-- from a file -->\n<webview src=\"https://www.github.com/\" preload=\"./test.js\"></webview>\n<!-- or if you want to load from an asar archive -->\n<webview src=\"https://www.github.com/\" preload=\"./app.asar/test.js\"></webview>\nA String that specifies a script that will be loaded before other scripts run in the guest\npage. The protocol of script's URL must be file: (even when using asar: archives) because\nit will be loaded by Node's require under the hood, which treats asar: archives as virtual\ndirectories.
When the guest page doesn't have node integration this script will still have\naccess to all Node APIs, but global objects injected by Node will be deleted\nafter this script has finished executing.
\nNote: This option will appear as preloadURL (not preload) in\nthe webPreferences specified to the will-attach-webview event.
httpreferrer<webview src=\"https://www.github.com/\" httpreferrer=\"http://cheng.guru\"></webview>\nA String that sets the referrer URL for the guest page.
useragent<webview src=\"https://www.github.com/\" useragent=\"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko\"></webview>\nA String that sets the user agent for the guest page before the page is navigated to. Once the\npage is loaded, use the setUserAgent method to change the user agent.
disablewebsecurity<webview src=\"https://www.github.com/\" disablewebsecurity></webview>\nA Boolean. When this attribute is present the guest page will have web security disabled.\nWeb security is enabled by default.
partition<webview src=\"https://github.com\" partition=\"persist:github\"></webview>\n<webview src=\"https://electronjs.org\" partition=\"electron\"></webview>\nA String that sets the session used by the page. If partition starts with persist:, the\npage will use a persistent session available to all pages in the app with the\nsame partition. if there is no persist: prefix, the page will use an\nin-memory session. By assigning the same partition, multiple pages can share\nthe same session. If the partition is unset then default session of the app\nwill be used.
This value can only be modified before the first navigation, since the session\nof an active renderer process cannot change. Subsequent attempts to modify the\nvalue will fail with a DOM exception.
\nallowpopups<webview src=\"https://www.github.com/\" allowpopups></webview>\nA Boolean. When this attribute is present the guest page will be allowed to open new\nwindows. Popups are disabled by default.
webpreferences<webview src=\"https://github.com\" webpreferences=\"allowRunningInsecureContent, javascript=no\"></webview>\nA String which is a comma separated list of strings which specifies the web preferences to be set on the webview.\nThe full list of supported preference strings can be found in BrowserWindow.
The string follows the same format as the features string in window.open.\nA name by itself is given a true boolean value.\nA preference can be set to another value by including an =, followed by the value.\nSpecial values yes and 1 are interpreted as true, while no and 0 are interpreted as false.
enableblinkfeatures<webview src=\"https://www.github.com/\" enableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be enabled separated by ,.\nThe full list of supported feature strings can be found in the\nRuntimeEnabledFeatures.json5 file.
disableblinkfeatures<webview src=\"https://www.github.com/\" disableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be disabled separated by ,.\nThe full list of supported feature strings can be found in the\nRuntimeEnabledFeatures.json5 file.
The webview tag has the following methods:
Note: The webview element must be loaded before using the methods.
\nExample
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('dom-ready', () => {\n webview.openDevTools()\n})\n<webview>.loadURL(url[, options])url URLoptions Object (optional)httpReferrer (String | Referrer) (optional) - An HTTP Referrer url.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url is a data url and needs to load other files.Returns Promise<void> - The promise will resolve when the page has finished loading\n(see did-finish-load), and rejects\nif the page fails to load (see\ndid-fail-load).
Loads the url in the webview, the url must contain the protocol prefix,\ne.g. the http:// or file://.
<webview>.downloadURL(url)url StringInitiates a download of the resource at url without navigating.
<webview>.getURL()Returns String - The URL of guest page.
<webview>.getTitle()Returns String - The title of guest page.
<webview>.isLoading()Returns Boolean - Whether guest page is still loading resources.
<webview>.isLoadingMainFrame()Returns Boolean - Whether the main frame (and not just iframes or frames within it) is\nstill loading.
<webview>.isWaitingForResponse()Returns Boolean - Whether the guest page is waiting for a first-response for the\nmain resource of the page.
<webview>.stop()Stops any pending navigation.
\n<webview>.reload()Reloads the guest page.
\n<webview>.reloadIgnoringCache()Reloads the guest page and ignores cache.
\n<webview>.canGoBack()Returns Boolean - Whether the guest page can go back.
<webview>.canGoForward()Returns Boolean - Whether the guest page can go forward.
<webview>.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the guest page can go to offset.
<webview>.clearHistory()Clears the navigation history.
\n<webview>.goBack()Makes the guest page go back.
\n<webview>.goForward()Makes the guest page go forward.
\n<webview>.goToIndex(index)index IntegerNavigates to the specified absolute index.
\n<webview>.goToOffset(offset)offset IntegerNavigates to the specified offset from the \"current entry\".
\n<webview>.isCrashed()Returns Boolean - Whether the renderer process has crashed.
<webview>.setUserAgent(userAgent)userAgent StringOverrides the user agent for the guest page.
\n<webview>.getUserAgent()Returns String - The user agent for guest page.
<webview>.insertCSS(css)css StringReturns Promise<String> - A promise that resolves with a key for the inserted\nCSS that can later be used to remove the CSS via\n<webview>.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted\nstylesheet.
\n<webview>.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified\nby its key, which is returned from <webview>.insertCSS(css).
<webview>.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (optional) - Default false.Returns Promise<any> - A promise that resolves with the result of the executed code\nor is rejected if the result of the code is a rejected promise.
Evaluates code in page. If userGesture is set, it will create the user\ngesture context in the page. HTML APIs like requestFullScreen, which require\nuser action, can take advantage of this option for automation.
<webview>.openDevTools()Opens a DevTools window for guest page.
\n<webview>.closeDevTools()Closes the DevTools window of guest page.
\n<webview>.isDevToolsOpened()Returns Boolean - Whether guest page has a DevTools window attached.
<webview>.isDevToolsFocused()Returns Boolean - Whether DevTools window of guest page is focused.
<webview>.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y) of guest page.
<webview>.inspectSharedWorker()Opens the DevTools for the shared worker context present in the guest page.
\n<webview>.inspectServiceWorker()Opens the DevTools for the service worker context present in the guest page.
\n<webview>.setAudioMuted(muted)muted BooleanSet guest page muted.
\n<webview>.isAudioMuted()Returns Boolean - Whether guest page has been muted.
<webview>.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
<webview>.undo()Executes editing command undo in page.
<webview>.redo()Executes editing command redo in page.
<webview>.cut()Executes editing command cut in page.
<webview>.copy()Executes editing command copy in page.
<webview>.paste()Executes editing command paste in page.
<webview>.pasteAndMatchStyle()Executes editing command pasteAndMatchStyle in page.
<webview>.delete()Executes editing command delete in page.
<webview>.selectAll()Executes editing command selectAll in page.
<webview>.unselect()Executes editing command unselect in page.
<webview>.replace(text)text StringExecutes editing command replace in page.
<webview>.replaceMisspelling(text)text StringExecutes editing command replaceMisspelling in page.
<webview>.insertText(text)text StringReturns Promise<void>
Inserts text to the focused element.
<webview>.findInPage(text[, options])text String - Content to be searched, must not be empty.options Object (optional)forward Boolean (optional) - Whether to search forward or backward, defaults to true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Defaults to false.matchCase Boolean (optional) - Whether search should be case-sensitive,\ndefaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. The result of the request\ncan be obtained by subscribing to found-in-page event.
<webview>.stopFindInPage(action)action String - Specifies the action to take place when ending\n<webview>.findInPage request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webview with the provided action.
<webview>.print([options])options Object (optional)silent Boolean (optional) - Don't ask user for print settings. Default is false.printBackground Boolean (optional) - Prints the background color and image of\nthe web page. Default is false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. Default is true.margins Object (optional)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. Default is false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Can be simplex, shortEdge, or longEdge.dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3,\nA4, A5, Legal, Letter, Tabloid or an Object containing height.Returns Promise<void>
Prints webview's web page. Same as webContents.print([options]).
<webview>.printToPDF(options)options ObjectheaderFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for\ndefault margin, 1 for no margin, and 2 for minimum margin.\nand width in microns.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print. On macOS, only the first range is honored.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3,\nA4, A5, Legal, Letter, Tabloid or an Object containing heightprintBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Uint8Array> - Resolves with the generated PDF data.
Prints webview's web page as PDF, Same as webContents.printToPDF(options).
<webview>.capturePage([rect])rect Rectangle (optional) - The area of the page to be captured.Returns Promise<NativeImage> - Resolves with a NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page.
<webview>.send(channel, ...args)channel String...args any[]Returns Promise<void>
Send an asynchronous message to renderer process via channel, you can also\nsend arbitrary arguments. The renderer process can handle the message by\nlistening to the channel event with the ipcRenderer module.
See webContents.send for\nexamples.
\n<webview>.sendToFrame(frameId, channel, ...args)frameId [number, number] - [processId, frameId]channel String...args any[]Returns Promise<void>
Send an asynchronous message to renderer process via channel, you can also\nsend arbitrary arguments. The renderer process can handle the message by\nlistening to the channel event with the ipcRenderer module.
See webContents.sendToFrame for\nexamples.
\n<webview>.sendInputEvent(event)event MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventReturns Promise<void>
Sends an input event to the page.
See webContents.sendInputEvent\nfor detailed description of event object.
<webview>.setZoomFactor(factor)factor Number - Zoom factor.Changes the zoom factor to the specified factor. Zoom factor is\nzoom percent divided by 100, so 300% = 3.0.
\n<webview>.setZoomLevel(level)level Number - Zoom level.Changes the zoom level to the specified level. The original size is 0 and each\nincrement above or below represents zooming 20% larger or smaller to default\nlimits of 300% and 50% of original size, respectively. The formula for this is\nscale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the\nzoom level for a specific domain propagates across all instances of windows with\nthe same domain. Differentiating the window URLs will make zoom work per-window.
\n
<webview>.getZoomFactor()Returns Number - the current zoom factor.
<webview>.getZoomLevel()Returns Number - the current zoom level.
<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberReturns Promise<void>
Sets the maximum and minimum pinch-to-zoom level.
\n<webview>.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\n<webview>.getWebContentsId()Returns Number - The WebContents ID of this webview.
The following DOM events are available to the webview tag:
Returns:
\nurl StringisMainFrame BooleanFired when a load has committed. This includes navigation within the current\ndocument as well as subframe document-level loads, but does not include\nasynchronous resource loads.
\nFired when the navigation is done, i.e. the spinner of the tab will stop\nspinning, and the onload event is dispatched.
Returns:
\nerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanThis event is like did-finish-load, but fired when the load failed or was\ncancelled, e.g. window.stop() is invoked.
Returns:
\nisMainFrame BooleanFired when a frame has done navigation.
\nCorresponds to the points in time when the spinner of the tab starts spinning.
\nCorresponds to the points in time when the spinner of the tab stops spinning.
\nFired when attached to the embedder web contents.
\nFired when document in the given frame is loaded.
\nReturns:
\ntitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when\ntitle is synthesized from file url.
Returns:
\nfavicons String[] - Array of URLs.Fired when page receives favicon urls.
\nFired when page enters fullscreen triggered by HTML API.
\nFired when page leaves fullscreen triggered by HTML API.
\nReturns:
\nlevel Integer - The log level, from 0 to 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Integer - The line number of the source that triggered this console messagesourceId StringFired when the guest window logs a console message.
\nThe following example code forwards all log messages to the embedder's console\nwithout regard for log level or other properties.
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('console-message', (e) => {\n console.log('Guest page logged a message:', e.message)\n})\nReturns:
\nresult ObjectrequestId IntegeractiveMatchOrdinal Integer - Position of the active match.matches Integer - Number of Matches.selectionArea Rectangle - Coordinates of first match region.finalUpdate BooleanFired when a result is available for\nwebview.findInPage request.
const webview = document.querySelector('webview')\nwebview.addEventListener('found-in-page', (e) => {\n webview.stopFindInPage('keepSelection')\n})\n\nconst requestId = webview.findInPage('test')\nconsole.log(requestId)\nReturns:
\nurl StringframeName Stringdisposition String - Can be default, foreground-tab, background-tab,\nnew-window, save-to-disk and other.options BrowserWindowConstructorOptions - The options which should be used for creating the new\nBrowserWindow.Fired when the guest page attempts to open a new browser window.
\nThe following example code opens the new url in system's default browser.
\nconst { shell } = require('electron')\nconst webview = document.querySelector('webview')\n\nwebview.addEventListener('new-window', async (e) => {\n const protocol = (new URL(e.url)).protocol\n if (protocol === 'http:' || protocol === 'https:') {\n await shell.openExternal(e.url)\n }\n})\nReturns:
\nurl StringEmitted when a user or the page wants to start navigation. It can happen when\nthe window.location object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with\nAPIs like <webview>.loadURL and <webview>.back.
It is also not emitted during in-page navigation, such as clicking anchor links\nor updating the window.location.hash. Use did-navigate-in-page event for\nthis purpose.
Calling event.preventDefault() does NOT have any effect.
Returns:
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be\ntrue for in-page navigations.
Returns:
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302\nredirect.
\nReturns:
\nurl StringEmitted when a navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links\nor updating the window.location.hash. Use did-navigate-in-page event for\nthis purpose.
Returns:
\nurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigations,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links\nor updating the window.location.hash. Use did-navigate-in-page event for\nthis purpose.
Returns:
\nisMainFrame Booleanurl StringEmitted when an in-page navigation happened.
\nWhen in-page navigation happens, the page URL changes but does not cause\nnavigation outside of the page. Examples of this occurring are when anchor links\nare clicked or when the DOM hashchange event is triggered.
Fired when the guest page attempts to close itself.
\nThe following example code navigates the webview to about:blank when the\nguest attempts to close itself.
const webview = document.querySelector('webview')\nwebview.addEventListener('close', () => {\n webview.src = 'about:blank'\n})\nReturns:
\nframeId [number, number] - pair of [processId, frameId].channel Stringargs any[]Fired when the guest page has sent an asynchronous message to embedder page.
\nWith sendToHost method and ipc-message event you can communicate\nbetween guest page and embedder page:
// In embedder page.\nconst webview = document.querySelector('webview')\nwebview.addEventListener('ipc-message', (event) => {\n console.log(event.channel)\n // Prints \"pong\"\n})\nwebview.send('ping')\n// In guest page.\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('ping', () => {\n ipcRenderer.sendToHost('pong')\n})\nFired when the renderer process is crashed.
\nReturns:
\nname Stringversion StringFired when a plugin process is crashed.
\nFired when the WebContents is destroyed.
\nEmitted when media starts playing.
\nEmitted when media is paused or done playing.
\nReturns:
\nthemeColor StringEmitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nReturns:
\nurl StringEmitted when mouse moves over a link or the keyboard moves the focus to a link.
\nEmitted when DevTools is opened.
\nEmitted when DevTools is closed.
\nEmitted when DevTools is focused / opened.
", "title": "There are several ways to control how windows are created from trusted or\nuntrusted content within a renderer. Windows can be created from the renderer in two ways:
\ntarget=_blankwindow.open()For same-origin content, the new window is created within the same process,\nenabling the parent to access the child window directly. This can be very\nuseful for app sub-windows that act as preference panels, or similar, as the\nparent can render to the sub-window directly, as if it were a div in the\nparent. This is the same behavior as in the browser.
When nativeWindowOpen is set to false, window.open instead results in the\ncreation of a BrowserWindowProxy, a light wrapper\naround BrowserWindow.
Electron pairs this native Chrome Window with a BrowserWindow under the hood.\nYou can take advantage of all the customization available when creating a\nBrowserWindow in the main process by using webContents.setWindowOpenHandler()\nfor renderer-created windows.
BrowserWindow constructor options are set by, in increasing precedence\norder: parsed options from the features string from window.open(),\nsecurity-related webPreferences inherited from the parent, and options given by\nwebContents.setWindowOpenHandler.\nNote that webContents.setWindowOpenHandler has final say and full privilege\nbecause it is invoked in the main process.
window.open(url[, frameName][, features])url StringframeName String (optional)features String (optional)Returns BrowserWindowProxy | Window
features is a comma-separated key-value list, following the standard format of\nthe browser. Electron will parse BrowserWindowConstructorOptions out of this\nlist where possible, for convenience. For full control and better ergonomics,\nconsider using webContents.setWindowOpenHandler to customize the\nBrowserWindow creation.
A subset of WebPreferences can be set directly,\nunnested, from the features string: zoomFactor, nodeIntegration, preload,\njavascript, contextIsolation, and webviewTag.
For example:
\nwindow.open('https://github.com', '_blank', 'top=500,left=200,frame=false,nodeIntegration=no')\nNotes:
\nwindow if it is\ndisabled on the parent window.window if it is\nenabled on the parent window.window if it is disabled on\nthe parent window.features will be passed to any registered webContents's\ndid-create-window event handler in the options argument.frameName follows the specification of windowName located in the native documentation.To customize or cancel the creation of the window, you can optionally set an\noverride handler with webContents.setWindowOpenHandler() from the main\nprocess. Returning { action: 'deny' } cancels the window. Returning { action: 'allow', overrideBrowserWindowOptions: { ... } } will allow opening\nthe window and setting the BrowserWindowConstructorOptions to be used when\ncreating the window. Note that this is more powerful than passing options\nthrough the feature string, as the renderer has more limited privileges in\ndeciding security preferences than the main process.
Window example// main.js\nconst mainWindow = new BrowserWindow()\n\n// In this example, only windows with the `about:blank` url will be created.\n// All other urls will be blocked.\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url === 'about:blank') {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n frame: false,\n fullscreenable: false,\n backgroundColor: 'black',\n webPreferences: {\n preload: 'my-child-window-preload-script.js'\n }\n }\n }\n }\n return { action: 'deny' }\n})\n// renderer process (mainWindow)\nconst childWindow = window.open('', 'modal')\nchildWindow.document.write('<h1>Hello</h1>')\nBrowserWindowProxy example\n// main.js\nconst mainWindow = new BrowserWindow({\n webPreferences: { nativeWindowOpen: false }\n})\n\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url.startsWith('https://github.com/')) {\n return { action: 'allow' }\n }\n return { action: 'deny' }\n})\n\nmainWindow.webContents.on('did-create-window', (childWindow) => {\n // For example...\n childWindow.webContents.on('will-navigate', (e) => {\n e.preventDefault()\n })\n})\n// renderer.js\nconst windowProxy = window.open('https://github.com/', null, 'minimizable=false')\nwindowProxy.postMessage('hi', '*')\nIf your app runs with Electron 6.0.8 or later, you can now build it for Windows 10 on Arm. This considerably improves performance, but requires recompilation of any native modules used in your app. It may also require small fixups to your build and packaging scripts.
\nIf your app doesn't use any native modules, then it's really easy to create an Arm version of your app.
\nnode_modules directory is empty.set npm_config_arch=arm64 before running npm install/yarn install as usual.Lots of Windows-specific code contains if... else logic that selects between either the x64 or x86 architectures.
\nif (process.arch === 'x64') {\n // Do 64-bit thing...\n} else {\n // Do 32-bit thing...\n}\nIf you want to target arm64, logic like this will typically select the wrong architecture, so carefully check your application and build scripts for conditions like this. In custom build and packaging scripts, you should always check the value of npm_config_arch in the environment, rather than relying on the current process arch.
If you use native modules, you must make sure that they compile against v142 of the MSVC compiler (provided in Visual Studio 2017). You must also check that any pre-built .dll or .lib files provided or referenced by the native module are available for Windows on Arm.
To test your app, use a Windows on Arm device running Windows 10 (version 1903 or later). Make sure that you copy your application over to the target device - Chromium's sandbox will not work correctly when loading your application assets from a network location.
\nNode.js v12.9.0 or later is recommended. If updating to a new version of Node is undesirable, you can instead update npm's copy of node-gyp manually to version 5.0.2 or later, which contains the required changes to compile native modules for Arm.
\nVisual Studio 2017 (any edition) is required for cross-compiling native modules. You can download Visual Studio Community 2017 via Microsoft's Visual Studio Dev Essentials program. After installation, you can add the Arm-specific components by running the following from a Command Prompt:
\nvs_installer.exe ^\n--add Microsoft.VisualStudio.Workload.NativeDesktop ^\n--add Microsoft.VisualStudio.Component.VC.ATLMFC ^\n--add Microsoft.VisualStudio.Component.VC.Tools.ARM64 ^\n--add Microsoft.VisualStudio.Component.VC.MFC.ARM64 ^\n--includeRecommended\nSetting npm_config_arch=arm64 in the environment creates the correct arm64 .obj files, but the standard Developer Command Prompt for VS 2017 will use the x64 linker. To fix this:
vcvarsamd64_arm64.bat at the end instead of vcvarsamd64_x86.bat.If done successfully, the command prompt should print something similar to this on startup:
\n**********************************************************************\n** Visual Studio 2017 Developer Command Prompt v15.9.15\n** Copyright (c) 2017 Microsoft Corporation\n**********************************************************************\n[vcvarsall.bat] Environment initialized for: 'x64_arm64'\nIf you want to develop your application directly on a Windows on Arm device, substitute vcvarsx86_arm64.bat in Target so that cross-compilation can happen with the device's x86 emulation.
node.libBy default, node-gyp unpacks Electron's node headers and downloads the x86 and x64 versions of node.lib into %APPDATA%\\..\\Local\\node-gyp\\Cache, but it does not download the arm64 version (a fix for this is in development.) To fix this:
node.lib from https://electronjs.org/headers/v6.0.9/win-arm64/node.lib%APPDATA%\\..\\Local\\node-gyp\\Cache\\6.0.9\\arm64\\node.libSubstitute 6.0.9 for the version you're using.
After completing all of the above, open your cross-compilation command prompt and run set npm_config_arch=arm64. Then use npm install to build your project as normal. As with cross-compiling x86 modules, you may need to remove node_modules to force recompilation of native modules if they were previously compiled for another architecture.
Debugging native modules can be done with Visual Studio 2017 (running on your development machine) and corresponding Visual Studio Remote Debugger running on the target device. To debug:
\n.exe on the target device via the Command Prompt (passing --inspect-brk to pause it before any native modules are loaded)..pdb symbols under Debugging > Symbols.If you encounter a problem with this documentation, or if your app works when compiled for x86 but not for arm64, please file an issue with \"Windows on Arm\" in the title.
", "title": "Windows on ARM", "description": "" }, "/docs/tutorial/windows-store-guide": { "locale": "en-US", "slug": "windows-store-guide", "href": "/docs/tutorial/windows-store-guide", "crowdinFileId": "256273", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-store-guide.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "With Windows 10, the good old win32 executable got a new sibling: The Universal\nWindows Platform. The new .appx format does not only enable a number of new\npowerful APIs like Cortana or Push Notifications, but through the Windows Store,\nalso simplifies installation and updating.
Microsoft developed a tool that compiles Electron apps as .appx packages,\nenabling developers to use some of the goodies found in the new application\nmodel. This guide explains how to use it - and what the capabilities and\nlimitations of an Electron AppX package are.
Windows 10 \"Anniversary Update\" is able to run win32 .exe binaries by\nlaunching them together with a virtualized filesystem and registry. Both are\ncreated during compilation by running app and installer inside a Windows\nContainer, allowing Windows to identify exactly which modifications to the\noperating system are done during installation. Pairing the executable with a\nvirtual filesystem and a virtual registry allows Windows to enable one-click\ninstallation and uninstallation.
In addition, the exe is launched inside the appx model - meaning that it can use\nmany of the APIs available to the Universal Windows Platform. To gain even more\ncapabilities, an Electron app can pair up with an invisible UWP background task\nlaunched together with the exe - sort of launched as a sidekick to run tasks\nin the background, receive push notifications, or to communicate with other UWP\napplications.
To compile any existing Electron app, ensure that you have the following\nrequirements:
\nnode -v)Then, go and install the electron-windows-store CLI:
npm install -g electron-windows-store\nPackage the application using electron-packager (or a similar tool).\nMake sure to remove node_modules that you don't need in your final application, since\nany module you don't actually need will increase your application's size.
The output should look roughly like this:
\n├── Ghost.exe\n├── LICENSE\n├── content_resources_200_percent.pak\n├── content_shell.pak\n├── d3dcompiler_47.dll\n├── ffmpeg.dll\n├── icudtl.dat\n├── libEGL.dll\n├── libGLESv2.dll\n├── locales\n│ ├── am.pak\n│ ├── ar.pak\n│ ├── [...]\n├── node.dll\n├── resources\n│ └── app.asar\n├── v8_context_snapshot.bin\n├── squirrel.exe\n└── ui_resources_200_percent.pak\nFrom an elevated PowerShell (run it \"as Administrator\"), run\nelectron-windows-store with the required parameters, passing both the input\nand output directories, the app's name and version, and confirmation that\nnode_modules should be flattened.
electron-windows-store `\n --input-directory C:\\myelectronapp `\n --output-directory C:\\output\\myelectronapp `\n --package-version 1.0.0.0 `\n --package-name myelectronapp\nOnce executed, the tool goes to work: It accepts your Electron app as an input,\nflattening the node_modules. Then, it archives your application as app.zip.\nUsing an installer and a Windows Container, the tool creates an \"expanded\" AppX\npackage - including the Windows Application Manifest (AppXManifest.xml) as\nwell as the virtual file system and the virtual registry inside your output\nfolder.
Once the expanded AppX files are created, the tool uses the Windows App Packager\n(MakeAppx.exe) to create a single-file AppX package from those files on disk.\nFinally, the tool can be used to create a trusted certificate on your computer\nto sign the new AppX package. With the signed AppX package, the CLI can also\nautomatically install the package on your machine.
In order to run your package, your users will need Windows 10 with the so-called\n\"Anniversary Update\" - details on how to update Windows can be found here.
\nIn opposition to traditional UWP apps, packaged apps currently need to undergo a\nmanual verification process, for which you can apply here.\nIn the meantime, all users will be able to install your package by double-clicking it,\nso a submission to the store might not be necessary if you're looking for an\neasier installation method. In managed environments (usually enterprises), the\nAdd-AppxPackage PowerShell Cmdlet can be used to install it in an automated fashion.
Another important limitation is that the compiled AppX package still contains a\nwin32 executable - and will therefore not run on Xbox, HoloLens, or Phones.
\nYou can pair your Electron app up with an invisible UWP background task that\ngets to make full use of Windows 10 features - like push notifications,\nCortana integration, or live tiles.
\nTo check out how an Electron app that uses a background task to send toast\nnotifications and live tiles, check out the Microsoft-provided sample.
\nTo generate the AppX package, the electron-windows-store CLI uses a template\nthat should work for most Electron apps. However, if you are using a custom\ninstaller, or should you experience any trouble with the generated package, you\ncan attempt to create a package using compilation with a Windows Container - in\nthat mode, the CLI will install and run your application in blank Windows Container\nto determine what modifications your application is exactly doing to the operating\nsystem.
Before running the CLI for the first time, you will have to setup the \"Windows Desktop App\nConverter\". This will take a few minutes, but don't worry - you only have to do\nthis once. Download and Desktop App Converter from here.\nYou will receive two files: DesktopAppConverter.zip and BaseImage-14316.wim.
DesktopAppConverter.zip. From an elevated PowerShell (opened with\n\"run as Administrator\", ensure that your systems execution policy allows us to\nrun everything we intend to run by calling Set-ExecutionPolicy bypass.BaseImage-14316.wim), by\ncalling .\\DesktopAppConverter.ps1 -Setup -BaseImage .\\BaseImage-14316.wim.Once installation succeeded, you can move on to compiling your Electron app.
", "title": "Windows Store Guide", "description": "" }, "/docs/tutorial/windows-taskbar": { "locale": "en-US", "slug": "windows-taskbar", "href": "/docs/tutorial/windows-taskbar", "crowdinFileId": "256275", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-taskbar.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron has APIs to configure the app's icon in the Windows taskbar. This API\nsupports both Windows-only features like creation of a JumpList,\ncustom thumbnails and toolbars,\nicon overlays, and the so-called\n\"Flash Frame\" effect, and cross-platform features\nlike recent documents and\napplication progress.
Windows allows apps to define a custom context menu that shows up when users\nright-click the app's icon in the taskbar. That context menu is called\nJumpList. You specify custom actions in the Tasks category of JumpList,\nas quoted from MSDN:
\n\nApplications define tasks based on both the program's features and the key\nthings a user is expected to do with them. Tasks should be context-free, in\nthat the application does not need to be running for them to work. They\nshould also be the statistically most common actions that a normal user would\nperform in an application, such as compose an email message or open the\ncalendar in a mail program, create a new document in a word processor, launch\nan application in a certain mode, or launch one of its subcommands. An\napplication should not clutter the menu with advanced features that standard\nusers won't need or one-time actions such as registration. Do not use tasks\nfor promotional items such as upgrades or special offers.
\nIt is strongly recommended that the task list be static. It should remain the\nsame regardless of the state or status of the application. While it is\npossible to vary the list dynamically, you should consider that this could\nconfuse the user who does not expect that portion of the destination list to\nchange.
\n
![\"IE\"](\"https://i-msdn.sec.s-msft.com/dynimg/IC420539.png\")
\n\nNOTE: The screenshot above is an example of general tasks of\nInternet Explorer
\n
Unlike the dock menu in macOS which is a real menu, user tasks in Windows work\nlike application shortcuts. For example, when a user clicks a task, the program\nwill be executed with specified arguments.
\nTo set user tasks for your application, you can use\napp.setUserTasks API.
\nStarting with a working application from the\nQuick Start Guide, update the main.js file with the\nfollowing lines:
const { app } = require('electron')\n\napp.setUserTasks([\n {\n program: process.execPath,\n arguments: '--new-window',\n iconPath: process.execPath,\n iconIndex: 0,\n title: 'New Window',\n description: 'Create a new window'\n }\n])\nTo clear your tasks list, you need to call app.setUserTasks with an empty\narray in the main.js file.
const { app } = require('electron')\n\napp.setUserTasks([])\n\n\nNOTE: The user tasks will still be displayed even after closing your\napplication, so the icon and program path specified for a task should exist until your application is uninstalled.
\n
On Windows, you can add a thumbnail toolbar with specified buttons to a taskbar\nlayout of an application window. It provides users with a way to access a\nparticular window's command without restoring or activating the window.
\nAs quoted from MSDN:
\n\n\nThis toolbar is the familiar standard toolbar common control. It has a\nmaximum of seven buttons. Each button's ID, image, tooltip, and state are defined\nin a structure, which is then passed to the taskbar. The application can show,\nenable, disable, or hide buttons from the thumbnail toolbar as required by its\ncurrent state.
\nFor example, Windows Media Player might offer standard media transport controls\nsuch as play, pause, mute, and stop.
\n
![\"player\"](\"https://i-msdn.sec.s-msft.com/dynimg/IC420540.png\")
\n\nNOTE: The screenshot above is an example of thumbnail toolbar of Windows\nMedia Player
\n
To set thumbnail toolbar in your application, you need to use\nBrowserWindow.setThumbarButtons
\nStarting with a working application from the\nQuick Start Guide, update the main.js file with the\nfollowing lines:
const { BrowserWindow } = require('electron')\nconst path = require('path')\n\nconst win = new BrowserWindow()\n\nwin.setThumbarButtons([\n {\n tooltip: 'button1',\n icon: path.join(__dirname, 'button1.png'),\n click () { console.log('button1 clicked') }\n }, {\n tooltip: 'button2',\n icon: path.join(__dirname, 'button2.png'),\n flags: ['enabled', 'dismissonclick'],\n click () { console.log('button2 clicked.') }\n }\n])\nTo clear thumbnail toolbar buttons, you need to call\nBrowserWindow.setThumbarButtons with an empty array in the main.js file.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.setThumbarButtons([])\nOn Windows, a taskbar button can use a small overlay to display application\nstatus.
\nAs quoted from MSDN:
\n\n\nIcon overlays serve as a contextual notification of status, and are intended\nto negate the need for a separate notification area status icon to communicate\nthat information to the user. For instance, the new mail status in Microsoft\nOutlook, currently shown in the notification area, can now be indicated\nthrough an overlay on the taskbar button. Again, you must decide during your\ndevelopment cycle which method is best for your application. Overlay icons are\nintended to supply important, long-standing status or notifications such as\nnetwork status, messenger status, or new mail. The user should not be\npresented with constantly changing overlays or animations.
\n
![\"Overlay](\"https://i-msdn.sec.s-msft.com/dynimg/IC420441.png\")
\n\nNOTE: The screenshot above is an example of overlay on a taskbar button
\n
To set the overlay icon for a window, you need to use the\nBrowserWindow.setOverlayIcon API.
\nStarting with a working application from the\nQuick Start Guide, update the main.js file with the\nfollowing lines:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.setOverlayIcon('path/to/overlay.png', 'Description for overlay')\nOn Windows, you can highlight the taskbar button to get the user's attention.\nThis is similar to bouncing the dock icon in macOS.
\nAs quoted from MSDN:
\n\n\nTypically, a window is flashed to inform the user that the window requires\nattention but that it does not currently have the keyboard focus.
\n
To flash the BrowserWindow taskbar button, you need to use the\nBrowserWindow.flashFrame API.
\nStarting with a working application from the\nQuick Start Guide, update the main.js file with the\nfollowing lines:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.once('focus', () => win.flashFrame(false))\nwin.flashFrame(true)\n\n", "title": "Taskbar Customization (Windows)", "description": "Applications define tasks based on both the program's features and the key\nthings a user is expected to do with them. Tasks should be context-free, in\nthat the application does not need to be running for them to work. They\nshould also be the statistically most common actions that a normal user would\nperform in an application, such as compose an email message or open the\ncalendar in a mail program, create a new document in a word processor, launch\nan application in a certain mode, or launch one of its subcommands. An\napplication should not clutter the menu with advanced features that standard\nusers won't need or one-time actions such as registration. Do not use tasks\nfor promotional items such as upgrades or special offers.\nIt is strongly recommended that the task list be static. It should remain the\nsame regardless of the state or status of the application. While it is\npossible to vary the list dynamically, you should consider that this could\nconfuse the user who does not expect that portion of the destination list to\nchange." } }, "ja-JP": { "/docs/api/accelerator": { "locale": "ja-JP", "slug": "accelerator", "href": "/docs/api/accelerator", "crowdinFileId": "256277", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/accelerator.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "NOTE: Don't forget to call
\nwin.flashFrame(false)to turn off the flash.\nIn the above example, it is called when the window comes into focus,\nbut you might use a timeout or some other event to disable it.
\n\nキーボードショートカットを定義します。
\n
Accelerator は、+ によって結合された複数の修飾キーと単一のキーコードを含む文字列で、アプリケーション全体でキーボードショートカットを定義するために使われます。
例:
\nCommandOrControl+ACommandOrControl+Shift+Z以下のようにショートカットは register メソッドを使って globalShortcut モジュールに登録されます。
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+Y' shortcut listener.\n globalShortcut.register('CommandOrControl+Y', () => {\n // Y と Command/Control が押下されたときに処理を行います。\n })\n})\nLinux と Windows の場合、Command キーは効果がありません。Accelerator を定義するのに、macOS では Command、Linux と Windows では Control を表す、CommandOrControl を使うようにしてください。
Option ではなく Alt を使用してください。 Option キーは macOS にしか存在しませんが、Alt キーは全てのプラットフォームで利用可能です。
Super (または Meta) キーは、WindowsとLinuxの場合は Windows キー、macOSの場合は Cmd にマッピングされます。
Command (または略して Cmd)Control (または略して Ctrl)CommandOrControl (または略して CmdOrCtrl)AltOptionAltGrShiftSuperメタ情報0 から 9A から ZF1 から F24~、!、@、#、$ などの記号PlusSpaceTabCapslockNumlockスクロールロックBackspace削除InsertReturn (またはエイリアスとして Enter)Up と Down、 Left、 RightHome と EndPageUp と PageDownEscape (または略して Esc)VolumeUp と VolumeDown、 VolumeMuteMediaNextTrack と MediaPreviousTrack、 MediaStop、 MediaPlayPausePrintScreennum0 から num9numdec - 数字キーnumadd - テンキーの + キーnumsub - テンキーの - キーnummult - テンキーの * キーnumdiv - テンキーの ÷ キーアクセシビリティの高いアプリケーションを作ることは重要です。私たちは、開発者がすべてのユーザとってより良いアプリケーションを開発することを手助けする機能として Devtron と Spectron を提供してます。
\nElectron アプリケーションのアクセシビリティに関する懸念は、どちらも最終的に HTML であるため、ウェブサイトと同様です。 しかし、Electron アプリケーションでは、アプリケーションに監査機を指す URL がないため、アクセシビリティ監査にオンラインリソースを使用することはできません。
\nこれらの機能は、監査ツールを Electron アプリに提供します。 Spectron でテストに監査を追加するか、開発者向けツール内で Devtron で監査を使用するかを選択できます。 ツールの概要については、以下を参照してください。
\nSpectron テストフレームワークで、アプリケーション内の各ウィンドウと <webview> タグを監視できます。 以下がその例です。
app.client.auditAccessibility().then(function (audit) {\n if (audit.failed) {\n console.error(audit.message)\n }\n})\nこの機能の詳細は Spectron のドキュメント にて閲覧できます。
\nDevtron にはアクセシビリティタブがあり、アプリ内のページを監査し、結果を並べ替えてフィルタリングすることができます。
\n
これらのツールはいずれも、Google for Chrome で作成された Accessibility Developer Tools ライブラリを使用しています。 このライブラリが使用しているアクセシビリティ監査のルールに関する詳細は、リポジトリの wiki に記載されています。
\nElectron 向けの他の優れたアクセシビリティツールについて知っている場合は、アクセシビリティドキュメントにプルリクエストを加えてください。
\nElectron アプリケーションは、支援技術 (Windows の JAWS や macOS の VoiceOverなど) が動いている場合にアクセシビリティ機能を自動で有効にします。 詳細については、Chrome の アクセシビリティドキュメント を参照してください。
\nこれらの機能は、Electron アプリケーション内からか、サードパーティのネイティブソフトウェアでフラグを設定することで手動切り替えできます。
\napp.setAccessibilitySupportEnabled(enabled) API を使うことで、アプリケーション設定で Chrome のアクセシビリティを有効にする機能を手動設置できます。 注意として、ユーザーのシステム支援ユーティリティはこの設定よりも優先され、これを上書きします。
macOS では、サードパーティの支援技術により AXManualAccessibility 属性をプログラムで設定することで、Electron アプリケーション内のアクセシビリティ機能を切り替えられます。
CFStringRef kAXManualAccessibility = CFSTR(\"AXManualAccessibility\");\n\n+ (void)enableAccessibility:(BOOL)enable inElectronApplication:(NSRunningApplication *)app\n{\n AXUIElementRef appRef = AXUIElementCreateApplication(app.processIdentifier);\n if (appRef == nil)\n return;\n\n CFBooleanRef value = enable ? kCFBooleanTrue : kCFBooleanFalse;\n AXUIElementSetAttributeValue(appRef, kAXManualAccessibility, value);\n CFRelease(appRef);\n}\n\n\nアプリケーションのイベントライフサイクルを制御します。
\n
プロセス: Main
\n以下の例では最後のウインドウが閉じられたときにアプリケーションを終了する方法を示します。
\nconst { app } = require('electron')\napp.on('window-all-closed', () => {\n app.quit()\n})\napp オブジェクトでは以下のイベントが発生します。
アプリケーションが基本的な起動処理を完了したときに発生します。 Windows と Linux上では、will-finish-launching イベントは ready イベントと同じです。macOS上では、このイベントはNSApplication の applicationWillFinishLaunching 通知を表しています。 通常、ここでは、open-file や open-url イベントのリスナーを設定したり、クラッシュレポーターや自動アップデーターを開始したりします。
ほとんどの場合、ready イベントハンドラーですべてのことを行うようにするべきです。
戻り値：
\nevent EventlaunchInfo Record<string, any> | NotificationResponse macOSElectron が一度、初期化処理を完了したときに発生します。 macOS で通知センターから起動された場合、launchInfo は、NSUserNotification の userInfo、またはアプリケーションを開く際に使用された UNNotificationResponse からの情報を保持しています。 また、app.isReady() を呼び出してこのイベントが発生したことがあるかどうかを確認したり、app.whenReady() を呼び出して Electron 初期化時に解決される Promise を取得したりできます。
すべてのウィンドウが閉じられたときに発生します。
\nこのイベントを購読せずに全てのウインドウを閉じた場合、既定の動作としてアプリは終了します。しかし、このイベントを購読している場合は、アプリを終了するかどうかを制御することができます。 ユーザが Cmd + Q を押下したり、開発者が app.quit() を呼び出したりした場合では、Electron はまず全てのウインドウを閉じようとして、その後に will-quit イベントを発生させます。しかし、この場合は window-all-closed イベントは発生しません。
戻り値：
\nevent Eventアプリケーションがウィンドウを閉じ始める前に発生します。 event.preventDefault() を呼び出すことで、アプリケーションが終了する既定の動作を阻害できます。
注: アプリケーションの終了が autoUpdater.quitAndInstall() によって開始された場合、全てのウインドウで close イベントを発生させ、それらが閉じた後 に before-quit が発生します。
注釈: Windows では、このイベントはシステムのシャットダウン/再起動やユーザーのログアウトでアプリケーションが閉じられようとしている場合には発生しません。
\n戻り値：
\nevent Eventすべてのウィンドウが閉じられ、アプリが終了しようとしているときに発生します。 event.preventDefault() を呼び出すことで、アプリケーションが終了する既定の動作を阻害できます。
will-quit と window-all-closed イベントの差異を確認するためには、window-all-closed イベントの説明もお読みください。
注釈: Windows では、このイベントはシステムのシャットダウン/再起動やユーザーのログアウトでアプリケーションが閉じられようとしている場合には発生しません。
\n戻り値：
\nevent EventexitCode Integerアプリケーションが終了するときに発生します。
\n注釈: Windows では、このイベントはシステムのシャットダウン/再起動やユーザーのログアウトでアプリケーションが閉じられようとしている場合には発生しません。
\n戻り値：
\nevent Eventpath Stringユーザがアプリケーションでファイルを開こうとしたときに発生します。 open-file イベントは、大抵の場合ファイルをアプリケーションが既に開いていて、OS が開くために再利用しようとしたときに発生します。 open-file は、Dock にファイルがドロップされて、アプリケーションがまだ起動していないときにも発生します。 このようなケースに対処するために、アプリケーション起動時の非常に早い段階 ( ready イベントが発生するよりも前) で open-file イベントを監視するようにしてください。
このイベントを処理する場合、event.preventDefault() を呼び出す必要があります。
Windows では、ファイルパスを取得するために (メインプロセスの) process.argv をパースしなければなりません。
戻り値：
\nevent Eventurl Stringユーザがこのアプリケーションで URL を開こうとしたときに発生します。 アプリケーションの Info.plist ファイルで CFBundleURLTypes キーの中に URL スキームを定義し、NSPrincipalClass に AtomApplication を設定しなければなりません。
このイベントを処理する場合、event.preventDefault() を呼び出す必要があります。
戻り値：
\nevent EventhasVisibleWindows Booleanアプリケーションがアクティブになったときに発生します。 アプリケーションが最初に起動される、既に実行中のときにアプリケーションを再起動しようとする、アプリケーションの Dock やタスクバーのアイコンをクリックするなど、いろいろなアクションがこのイベントの引き金となり得ます。
\n戻り値：
\nevent EventmacOS のアプリケーションがアクティブになったときに発生します。 activateイベントとの違い: did-become-active が発生するのはアプリがアクティブになる度に発生します。Dock アイコンがクリックしたり、アプリが再起動したときだけではありません。
戻り値：
\nevent Eventtype String - アクティビティを識別する文字列。 NSUserActivity.activityType と対応しています。userInfo unknown - 別のデバイスのアクティビティによって保存されたアプリ固有の情報が含まれています。details ObjectwebpageURL String (任意) - 利用可能な場合、別デバイス上の操作でアクセスしたウェブページの URL を特定する文字列になります。ハンドオフ 中に別のデバイスからのアクティビティを継続しようとしたときに発生します。 このイベントを処理する場合、event.preventDefault() を呼び出す必要があります。
ユーザのアクティビティはアクティビティ元のアプリと同一の開発者チームIDを持ち、アクティビティタイプをサポートするアプリでしか継続させることができません。 サポートされるアクティビティタイプは、アプリの Info.plist の NSUserActivityTypes キーで指定されています。
戻り値：
\nevent Eventtype String - アクティビティを識別する文字列。 NSUserActivity.activityType と対応しています。ハンドオフ 中に別のデバイスからのアクティビティを継続しようとする前に発生します。 このイベントを処理する場合、event.preventDefault() を呼び出す必要があります。
戻り値：
\nevent Eventtype String - アクティビティを識別する文字列。 NSUserActivity.activityType と対応しています。error String - エラーのローカライズされた説明としての文字列。ハンドオフ 中に別のデバイスからのアクティビティを継続できなかったときに発生します。
\n戻り値：
\nevent Eventtype String - アクティビティを識別する文字列。 NSUserActivity.activityType と対応しています。userInfo unknown - アクティビティによって保存されたアプリ固有の情報が含まれています。ハンドオフ 中にこのデバイスからのアクティビティを他のデバイスで継続させることに成功した後で発生します。
\n戻り値：
\nevent Eventtype String - アクティビティを識別する文字列。 NSUserActivity.activityType と対応しています。userInfo unknown - アクティビティによって保存されたアプリ固有の情報が含まれています。ハンドオフ が別のデバイスでまさに継続されようとしているときに発生します。 送信される情報を更新する必要がある場合、event.preventDefault() をすぐに呼び出してください。そして、新しい userInfo ディクショナリを組み立てて、app.updateCurrentActivity() をタイミングよく呼び出してください。 さもなくば操作は失敗し、continue-activity-error が呼び出されます。
戻り値：
\nevent Eventユーザーが macOS ネイティブの新規タブボタンをクリックすると発生します。 新規タブボタンは現在の BrowserWindow に tabbingIdentifier が設定されている場合にだけ表示されます。
戻り値：
\nevent Eventwindow BrowserWindowbrowserWindow のフォーカスが外れたときに発生します。
\n戻り値：
\nevent Eventwindow BrowserWindowbrowserWindow がフォーカスを得たときに発生します。
\n戻り値：
\nevent Eventwindow BrowserWindow新しい browserWindow が生成されたときに発生します。
\n戻り値：
\nevent EventwebContents WebContents新しい webContents が生成されたときに発生します。
\n戻り値：
\nevent EventwebContents WebContentsurl Stringerror String - エラーコードcertificate Certificatecallback FunctionisTrusted Boolean - 証明書を信頼できるものと見なすかどうかisMainFrame Booleanurl に対する certificate の検証に失敗したときに発生します。証明書を信頼するためには、event.preventDefault() で既定の動作をキャンセルして、callback(true) を呼び出すようにしてください。
const { app } = require('electron')\n\napp.on('certificate-error', (event, webContents, url, error, certificate, callback) => {\n if (url === 'https://github.com') {\n // 検証ロジック。\n event.preventDefault()\n callback(true)\n } else {\n callback(false)\n }\n})\n戻り値：
\nevent EventwebContents WebContentsurl URLcertificateList Certificate[]callback Functioncertificate Certificate (optional)クライアント証明書が要求されたときに発生します。
\nurl がクライアント証明書を要求しているナビゲーションエントリーに対応していれば、リストからフィルターされたエントリーで callback を呼び出すことができます。 event.preventDefault() を使うことで、アプリケーションがストアから最初の証明書を使うのをキャンセルできます。
const { app } = require('electron')\n\napp.on('select-client-certificate', (event, webContents, url, list, callback) => {\n event.preventDefault()\n callback(list[0])\n})\n戻り値：
\nevent EventwebContents WebContentsauthenticationResponseDetails Objecturl URLauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (任意)password String (任意)webContents がBasic認証を要求すると発生します。
既定の動作では、全てに認証をキャンセルします。 これを変更するには、event.preventDefault() で既定の動作をキャンセルして、資格情報と共に callback(username, password) を呼び出すようにしてください。
const { app } = require('electron')\n\napp.on('login', (event, webContents, details, authInfo, callback) => {\n event.preventDefault()\n callback('username', 'secret')\n})\nユーザー名またはパスワードを渡さずに callback を呼び出すと、認証リクエストはキャンセルされ、認証エラーがページに返されます。
GPU 情報の更新がある場合に発生します。
\n戻り値：
\nevent Eventkilled BooleanGPU プロセスがクラッシュしたり、強制終了されたりしたときに発生します。
\n非推奨: このイベントは child-process-gone イベント によって引き継がれます。このイベントには、子プロセスが失われた理由についての詳細情報が含まれています。 これはクラッシュした場合に限りません。 移植する場合は、Boolean 型の killed だと reason === 'killed' をチェックするように置き換えればできます。
戻り値：
\nevent EventwebContents WebContentskilled BooleanwebContents のレンダラープロセスがクラッシュ、または強制終了されたときに発行されます。
非推奨: このイベントは render-process-gone イベント によって引き継がれます。このイベントには、子プロセスが失われた理由についての詳細情報が含まれています。 これはクラッシュした場合に限りません。 移植する場合は、Boolean 型の killed だと reason === 'killed' をチェックするように置き換えればできます。
戻り値：
\nevent EventwebContents WebContentsdetails Objectreason String - レンダープロセスがなくなった理由。 取りうる値:clean-exit - 終了コードが0でプロセスが終了したabnormal-exit - ゼロでない終了コードでプロセスを終了しました。killed - プロセスへSIGTERMシグナルが送信されたか、その他の方法で殺されました。crashed - プロセスがクラッシュしたoom - プロセスがメモリ不足になったlaunch-failed - プロセスが正常に起動されなかったintegrity-failure - Windows コードの整合性チェックに失敗しましたexitCode Integer - プロセスの終了コードです。reason が launch-failed でなければ、exitCode はプラットフォーム固有の起動失敗のエラーコードになります。renderer processが予期せず消えたときに発生します。 プロセスがクラッシュした場合やまたは殺された場合、これは正常です。
\n戻り値：
\nevent Eventdetails Objecttype String - プロセスの種別。 以下の値のいずれかです。UtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownreason String - 子プロセスがなくなった理由。 取りうる値:clean-exit - 終了コードが0でプロセスが終了したabnormal-exit - ゼロでない終了コードでプロセスを終了しました。killed - プロセスへSIGTERMシグナルが送信されたか、その他の方法で殺されました。crashed - プロセスがクラッシュしたoom - プロセスがメモリ不足になったlaunch-failed - プロセスが正常に起動されなかったintegrity-failure - Windows コードの整合性チェックに失敗しましたexitCode Number - プロセスの終了コード (例: posix の場合は waitpid からのステータス、Windowsの場合は GetExitCodeProcess) 。serviceName String (任意) - そのプロセスのローカライズされていない名前。name String (任意) - そのプロセスの名前。 ユーティリティの例: Audio Service, Content Decryption Module Service, Network Service, Video Captureなど子 processが予期せず消えたときに発生します。 プロセスがクラッシュした場合やまたは殺された場合、これは正常です。 レンダラープロセスを含みません。
\n戻り値：
\nevent EventaccessibilitySupportEnabled Boolean - Chromeのユーザ補助機能が有効な場合は true、そうでない場合は false。Chromeのユーザ補助機能が変更されると発生します。 このイベントはスクリーンリーダーのような支援技術が有効にされたり、無効にされたりしたときに発火します。 詳細については、https://www.chromium.org/developers/design-documents/accessibility を参照してください。
\n戻り値：
\nsession SessionElectron が新しい session を作成したときに発生します。
const { app } = require('electron')\n\napp.on('session-created', (session) => {\n console.log(session)\n})\n戻り値：
\nevent Eventargv String[] - 2番目のインスタンスのコマンドライン引数の配列workingDirectory String - 2番目のインスタンスの作業ディレクトリこのイベントは、2 つ目のインスタンスが実行され app.requestSingleInstanceLock() が実行されたとき、アプリケーションの1つ目のインスタンス内で発火されます。
argv は2番目のインスタンスのコマンドライン引数の配列で、workingDirectory はその現在の作業ディレクトリです。 通常、アプリケーションはこれに対して1番目のウインドウにフォーカスを当て、最小化しないように対応します。
注意: 2 番目のインスタンスが最初のインスタンスとは別のユーザーによって起動された場合、 argv 配列には引数が含まれません。
このイベントは app の ready イベントが発生した後で実行されることが保証されます。
注意: Chromiumがコマンドライン引数を追加することがあります。例えば、--original-process-start-timeがあります。
戻り値：
\nevent EventwebContents WebContentswebContents のレンダラープロセス内で desktopCapture.getSources() が呼ばれたときに発生します。 event.preventDefault() を呼び出すと、空のソースを返します。
app オブジェクトには以下のメソッドがあります。
注: いくつかのメソッドは特定のオペレーティングシステムでのみ利用可能で、そのように注記がつけられています。
\napp.quit()すべてのウインドウを閉じようとします。 before-quit イベントが最初に発生します。 すべてのウインドウを閉じることに成功した場合、will-quit イベントが発生し、既定ではアプリケーションは終了します。
このメソッドは、すべての beforeunload および unload イベントハンドラーが正しく実行されることを保証します。 beforeunload イベントハンドラーで false を返すことによって、ウインドウが終了処理をキャンセルすることができます。
app.exit([exitCode])exitCode Integer (任意)exitCode ですぐに終了します。 exitCode の省略値は 0 です。
ユーザに確認することなくすべてのウインドウがすぐに閉じられ、before-quit および will-quit イベントは発生しません。
app.relaunch([options])現在のインスタンスが終了したときに、アプリを再起動します。
\n既定では新しいインスタンスは現在のインスタンスと同じ作業ディレクトリおよびコマンドライン引数を使用します。 args が指定された場合、args がコマンドライン引数として代わりに引き渡されます。 execPath が指定された場合、execPath が再起動のため現在のアプリに代わって実行されます。
このメソッドは実行されているアプリを終了しないことに注意してください。アプリを再起動するには、app.relaunch を呼び出した後、app.quit または app.exit を呼び出さなければなりません。
app.relaunch を複数回呼び出した場合、現在のインスタンスが終了した後、複数のインスタンスが開始されます。
現在のインスタンスをすぐに再起動し、新しいコマンドライン引数を新しいインスタンスに追加する例:
\nconst { app } = require('electron')\n\napp.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) })\napp.exit(0)\napp.isReady()戻り値 Boolean - Electronの初期化が完了している場合、true、そうでない場合、false。 app.whenReady() も参照してください。
app.whenReady()Returns Promise<void> - Electron が初期化されるときに実行される Promise。 app.isReady() を確認してアプリの準備がまだできていないときに ready イベントに登録するための、便利な代替手段として使用できます。
app.focus([options])options Object (任意)steal Boolean macOS - 他のアプリが現在アクティブな場合でも、受信者をアクティブなアプリにします。Linux では、最初の表示ウィンドウにフォーカスします。 macOS では、アプリケーションがアクティブになります。 Windows では、アプリケーションの最初のウィンドウにフォーカスします。
\nできるだけ慎重に steal オプションを使用してください。
app.hide() macOS最小化することなくアプリケーションのすべてのウインドウを非表示にします。
\napp.show() macOS非表示にされたアプリケーションのウインドウを表示します。 自動的にフォーカスしません。
\napp.setAppLogsPath([path])path String (任意) - ログのカスタムパス。 絶対パスでなければなりません。アプリがロギングするディレクトリを設定または作成します。これは app.getPath() や app.setPath(pathName, newPath) で操作できます。
path 引数なしで app.setAppLogsPath() を呼び出すと、このディレクトリは、macOS では ~/Library/Logs/アプリ名 に、Linux と Windows では userData ディレクトリ内に設定されます。
app.getAppPath()戻り値 String - 現在のアプリケーションのディレクトリ。
app.getPath(name)name String - 以下のパスを名前で要求することができます。home ユーザのホームディレクトリ。appData - 既定のユーザ毎のアプリケーションデータディレクトリ。%APPDATA%$XDG_CONFIG_HOME もしくは ~/.config~/Library/Application SupportuserData アプリの設定ファイルが保存されるディレクトリで、既定ではアプリの名前で追加された appData のディレクトリ。キャッシュtemp 一時ディレクトリ。exe 現在の実行ファイル。module libchromiumcontent ライブラリ。desktop 現在のユーザのデスクトップディレクトリ。documents ユーザの\"マイドキュメント\"のディレクトリ。downloads ユーザのダウンロードのディレクトリ。music ユーザのミュージックのディレクトリ。pictures ユーザのピクチャのディレクトリ。videos ユーザのビデオのディレクトリ。recent ユーザーの最近のファイルのめのディレクトリ(Windows のみ)。logs アプリのログフォルダのディレクトリ。crashDumps クラッシュダンプが格納されているディレクトリ。戻り値 String - name に関連付けられた特別なディレクトリもしくはファイルのパス。 失敗した場合、Error が送出されます。
app.setAppLogsPath() を呼び出すよりも先に app.getPath('logs') が呼び出された場合、path 引数なしで app.setAppLogsPath() を呼び出すのに等しい、デフォルトのログディレクトリが作成されます。
app.getFileIcon(path[, options])path Stringoptions Object (任意)size Stringsmall - 16x16normal - 32x32large - Linux の場合は 48x48、Windowsの場合は 32x32、macOS の場合はサポートされていません。Promise<NativeImage>を返す - NativeImageでアプリのアイコンを埋めます。
パスに関連付けられているアイコンを取得します。
\nWindows の場合、2種類のアイコンがあります。
\n.mp3、.png など、特定のファイル拡張子に関連付けられたアイコン。.exe、.dll、.ico のような、ファイル自体に含まれるアイコン。Linux と macOS の場合、アイコンはファイルのMIMEタイプに関連付けられたアプリケーションによって決まります。
\napp.setPath(name, path)name Stringpath Stringname に関連付けられた特別なディレクトリもしくはファイルの path を上書きします。 パスとして存在しないディレクトリが指定された場合、Error が投げられます。 その場合、そのディレクトリを fs.mkdirSync や類似のもので作成するべきです。
app.getPath で定義されている name のパスだけを上書きすることができます。
既定では、WebページのCookieとキャッシュは userData ディレクトリに保存されます。 この場所を変更するには、app モジュールの ready イベントが発生する前に userData を上書きする必要があります。
app.getVersion()戻り値 String - ロードされたアプリケーションのバージョン。 アプリケーションの package.json ファイルにバージョンが見つからない場合、現在のバンドルもしくは実行可能ファイルのバージョンが返却されます。
app.getName()戻り値 String - アプリケーションの package.json ファイルで名前として設定された現在のアプリケーション名。
通常、package.json の name フィールドは、npm のモジュール仕様に基づいて小文字だけの短い名前が設定されます。 通常、すべて大文字で始まるアプリケーションの名前となる productName フィールドも指定してください。Electronによって、name よりも優先されます。
app.setName(name)name String現在のアプリケーションの名前を上書きします。
\n注釈: この関数は、Electron 内で使用する名前を上書きします。OS が使用する名前には影響しません。
\napp.getLocale()戻り値 String - 現在のアプリケーションのロケールで、Chromium の l10n_util ライブラリを用いて取得されます。 取りうる戻り値については こちら にドキュメントがあります。
ロケールを設定するには、アプリケーションの起動時にコマンドラインスイッチを使用する必要があります。これについては、こちら を参照してください。
\n注: アプリをパッケージ化して配布する場合、locales フォルダを同梱する必要があります。
Note:Windows の 準備ができて のイベントが出力される後を呼び出すことがあります。
app.getLocaleCountryCode()戻り値 String - 2 文字の ISO 3166 国名コードで、ユーザーの OS のロケールを示します。 この値はネイティブの OS API から取得します。
注意: ロケールの国コードを取得できなかった場合、これは空文字列を返します。
\napp.addRecentDocument(path) macOS Windowspath Stringpath を最近使ったドキュメントのリストに追加します。
このリストは OS が管理します。 Windows の場合はタスクバーからリストにアクセスでき、macOS の場合は Dock メニューからリストにアクセスできます。
\napp.clearRecentDocuments() macOS Windows最近使ったドキュメントのリストをクリアします。
\napp.setAsDefaultProtocolClient(protocol[, path, args])protocol String - :// を除くプロトコルの名前。 例えば、アプリで electron:// リンクを処理したい場合、引数を electron にしてこのメソッドを呼び出してください。path String (任意) Windows - Electron 実行形式へのパス。 省略値は process.execPath です。args String Windows - 実行形式に渡す引数。 省略値は空の配列です。戻り値 Boolean - 呼び出しが成功したかどうか。
このメソッドは現在の実行形式をプロトコル (または URI スキーム) の既定のハンドラーとして設定します。 これにより、アプリをオペレーティングシステムと密接に統合できます。 登録すると、プロトコル:// によるすべてのリンクは現在の実行形式で開かれるようになります。 プロトコルを含むリンク全体が、アプリケーションに引数として渡されます。
注: macOS の場合はアプリの info.plist に追加されているプロトコルしか登録できず、実行時に変更できません。 しかし、Electron Forge や Electron Packager を介するかテキストエディタで info.plist を編集することで、ビルド時にファイルを変更できます。 詳細は Apple社のドキュメント を参照するようにしてください。
注釈: Windows ストア 環境 (appx としてパッケージされている) 場合、この API はすべての呼び出しに true を返しますが、それにセットされたレジストリキーは他のアプリケーションからアクセスできません。 Windows ストア アプリケーションをデフォルトのプロトコルハンドラとして登録するには、マニフェストでプロトコルを宣言する 必要があります。
この API は内部的に Windows レジストリ や LSSetDefaultHandlerForURLScheme を使用します。
app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windowsprotocol String - :// を除くプロトコルの名前。path String (任意) Windows - 省略値は process.execPathargs String Windows - 省略値は空の配列戻り値 Boolean - 呼び出しが成功したかどうか。
このメソッドは、現在の実行ファイルがプロトコル (または URI スキーム) のデフォルトハンドラであるかどうかをチェックします。 その場合、既定のハンドラーからアプリを削除します。
\napp.isDefaultProtocolClient(protocol[, path, args])protocol String - :// を除くプロトコルの名前。path String (任意) Windows - 省略値は process.execPathargs String Windows - 省略値は空の配列戻り値 Boolean - 現在の実行形式がプロトコル (または URI スキーム) の既定のハンドラーかどうか。
注: macOSの場合、このメソッドは、アプリがプロトコルの既定のハンドラーとして登録されていたかをチェックするのに使えます。 macOSのマシン上の ~/Library/Preferences/com.apple.LaunchServices.plist を確認することでもこれを検証することができます。 詳細は Apple社のドキュメント を参照するようにしてください。
この API は内部的に Windows レジストリ や LSCopyDefaultHandlerForURLScheme を使用します。
app.getApplicationNameForProtocol(url)url String - 確認するプロトコル名が付いた URL。 類似の他メソッドとは異なり、少なくとも :// までを含む URL 全体を受け付けます (例: https://)。戻り値 String - そのプロトコルを処理するアプリケーションの名前。ハンドラーがない場合は空の文字列です。 たとえば、Electron がその URL のデフォルトハンドラーである場合、Windows と Mac では Electron になります。 ただし、厳密な形式に依存しないでください。変更されている可能性があります。 Linux では、.desktop 接尾子を付けた別の形式が必要でしょう。
このメソッドは、URL のプロトコル (別名 URI スキーム) のデフォルトハンドラーであるアプリケーション名を返します。
\napp.getApplicationInfoForProtocol(url) macOS Windowsurl String - 確認するプロトコル名が付いた URL。 類似の他メソッドとは異なり、少なくとも :// までを含む URL 全体を受け付けます (例: https://)。戻り値 Promise<Object> - 以下を含むオブジェクトで実行されます。
icon NativeImage - プロトコルを処理するアプリの表示アイコン。path String - プロトコルを扱うアプリのインストールパス。name String - プロトコルを扱うアプリの表示名。このメソッドは、URL のプロトコル (別名 URI スキーム) のデフォルトハンドラーであるアプリケーション名、アイコン、パスを含むPromiseを返します。
\napp.setUserTasks(tasks) Windowstasks Task[] - Task オブジェクトの配列tasks を Windows でのジャンプリストの タスク カテゴリに追加します。
tasks は Task オブジェクトの配列です。
戻り値 Boolean - 呼び出しが成功したかどうか。
注: ジャンプリストをもっとカスタマイズしたい場合は、app.setJumpList(categories) を代わりに使用してください。
app.getJumpListSettings() Windows戻り値 Object:
minItems Integer - ジャンプリストに表示されるアイテムの最小の数 (この値の詳細な説明は MSDN ドキュメント を参照してください) 。removedItems JumpListItem[] - ユーザが、ジャンプリストのカスタムカテゴリから明示的に削除したアイテムに対応した、JumpListItem オブジェクトの配列。 これらのアイテムを直後の app.setJumpList() の呼び出しでジャンプリストに再度追加してはいけません。Windowsは削除されたアイテムを含むいかなるカスタムカテゴリも表示することはできません。app.setJumpList(categories) Windowscategories JumpListCategory[] | null - JumpListCategory オブジェクトの配列。アプリケーションのカスタムジャンプリストを設定もしくは削除し、以下の文字列のいずれかを返します。
\nok - 正常。error - 1つ以上のエラーが発生しました。何が原因かを把握するためには、実行時ログを有効にします。invalidSeparatorError - ジャンプリストのカスタムカテゴリに区切りを追加しようとしました。 区切りは標準の タスク カテゴリでしか使用できません。fileTypeRegistrationError - アプリが処理できると登録されていないファイルタイプのファイルリンクをジャンプリストに追加しようとしました。customCategoryAccessDeniedError - ユーザープライバシーもしくはグループポリシー設定のため、ジャンプリストにカスタムカテゴリを追加できません。categories が null の場合、その前に設定されていたカスタムジャンプリスト (あれば) は、(Windowsによって管理される) アプリ標準のジャンプリストに置換されます。
注: JumpListCategory オブジェクトに type プロパティも name プロパティも設定されなかった場合、type は tasks と見做されます。 name プロパティは設定されている一方で type プロパティが省略された場合、type は custom と見做されます。
注: ユーザはカスタムカテゴリからアイテムを削除できますが、Windows では次の app.setJumpList(categories) の呼び出しが成功した 後 でないと、削除されたアイテムをカスタムカテゴリに追加し直すことができません。 それより早くカスタムカテゴリに削除されたアイテムを再度追加しようとすると、ジャンプリストからカスタムカテゴリ全体が外れてしまいます。 削除されたアイテムのリストは、app.getJumpListSettings() を使って取得できます。
注: ジャンプリストのアイテムの description プロパティは最大長は 260 文字です。 この制限を超えると、アイテムはジャンプリストに追加されず、表示されません。
カスタムジャンプリストを作成する非常に簡単な例は以下の通りです。
\nconst { app } = require('electron')\n\napp.setJumpList([\n {\n type: 'custom',\n name: '最近開いたプロジェクト',\n items: [\n { type: 'file', path: 'C:\\\\Projects\\\\project1.proj' },\n { type: 'file', path: 'C:\\\\Projects\\\\project2.proj' }\n ]\n },\n { // 名前があるため `type` は \"custom\" になります\n name: 'ツール',\n items: [\n {\n type: 'task',\n title: 'ツール A',\n program: process.execPath,\n args: '--run-tool-a',\n icon: process.execPath,\n iconIndex: 0,\n description: 'ツール A を実行する'\n },\n {\n type: 'task',\n title: 'ツール B',\n program: process.execPath,\n args: '--run-tool-b',\n icon: process.execPath,\n iconIndex: 0,\n description: 'ツール B を実行する'\n }\n ]\n },\n { type: 'frequent' },\n { // 名前がないため `type` は \"tasks\" になります\n items: [\n {\n type: 'task',\n title: '新規プロジェクト',\n program: process.execPath,\n args: '--new-project',\n description: '新規プロジェクトを作成します。'\n },\n { type: 'separator' },\n {\n type: 'task',\n title: 'プロジェクトの復元',\n program: process.execPath,\n args: '--recover-project',\n description: 'プロジェクトを復元します。'\n }\n ]\n }\n])\napp.requestSingleInstanceLock()戻り値 Boolean
このメソッドの戻り値は、アプリケーションのこのインスタンスのロックが成功したかどうかを表します。 ロック状態にできなかった場合、アプリケーションの他のインスタンスが既にロックされており、ただちに終了すると想定できます。
\nつまり、 このメソッドは、プロセスがアプリケーションの 1 つ目のインスタンスで、アプリがロード処理を続行する必要がある場合に true を返します。 既にロック状態にしたものとは別のインスタンスにパラメータを送信したためプロセスが直ちに終了する必要がある場合は、false を返します。
macOSの場合、ユーザがFinderでアプリの2番目のインスタンスを開こうとしたとき、システムは自動的にシングルインスタンスになるようにし、open-file と open-url イベントが発生します。 ただし、ユーザがアプリをコマンドラインで開始する場合、シングルインスタンスを強制するシステムの仕組みが迂回されるため、シングルインスタンスであることを保証するには、このメソッドを使う必要があります。
2番目のインスタンスが開始されたとき、1番目のインスタンスのウインドウをアクティブにする例:
\nconst { app } = require('electron')\nlet myWindow = null\n\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // 誰かが2つ目のインスタンスを実行したとき、このウィンドウにフォーカスします。\n if (myWindow) {\n if (myWindow.isMinimized()) myWindow.restore()\n myWindow.focus()\n }\n })\n\n // myWindow を作成したり、アプリの残りをロードしたり、...\n app.whenReady().then(() => {\n myWindow = createWindow()\n })\n}\napp.hasSingleInstanceLock()戻り値 Boolean
このメソッドはアプリのこのインスタンスが現在シングルインスタンスロックをされているかどうかを返します。 app.requestSingleInstanceLock() でロックを要求し、app.releaseSingleInstanceLock() で解放できます。
app.releaseSingleInstanceLock()requestSingleInstanceLock によって作成されたすべてのロックを解放します。 これにより、並列実行するための複数インスタンスのアプリケーションが再び許可されます。
app.setUserActivity(type, userInfo[, webpageURL]) macOStype String - アクティビティを一意に識別します。 NSUserActivity.activityType と対応しています。userInfo any - 別のデバイスで使用するために保存されたアプリ固有の情報。webpageURL String (任意) - 継続されたデバイスに適切なアプリがインストールされていない場合にブラウザで読み込もうとしたウェブページ。 スキームは http もしくは https でなければなりません。NSUserActivity を作成し、現在のアクティビティとして設定します。 そのアクティビティは後に別のデバイスでの ハンドオフ に適用されます。
app.getCurrentActivityType() macOS戻り値 String - 現在実行されているアクティビティのタイプ。
app.invalidateCurrentActivity() macOS現在の ハンドオフ ユーザアクティビティを無効にします。
\napp.resignCurrentActivity() macOS現在の ハンドオフ ユーザーアクティビティを、無効にせずに不活性化します。
\napp.updateCurrentActivity(type, userInfo) macOStype String - アクティビティを一意に識別します。 NSUserActivity.activityType と対応しています。userInfo any - 別のデバイスで使用するために保存されたアプリ固有の情報。タイプが type と一致した場合、現在のアクティビティを更新し、現在の userInfo ディスクショナリに userInfo のエントリを統合します。
app.setAppUserModelId(id) Windowsid Stringアプリケーションユーザモデル ID を id に変更します。
app.setActivationPolicy(policy) macOSpolicy String - 'regular', 'accessory', 'formited' のいずれか。アプリのアクティベーションポリシーを設定します。
\nアクティベーションポリシーの種類:
\napp.importCertificate(options, callback) Linuxoptions Objectcertificate String - PACS#12ファイルのパス。password String - 証明書のパスフレーズ。callback Functionresult Integer - インポート結果。プラットフォームの証明書ストアにPACS#12形式で証明書をインポートします。 インポート操作の result で callback が呼び出されます。0 という値は成功を意味しますが、その他の値はChromium の net_error_list の通り、失敗を意味します。
app.configureHostResolver(options)options ObjectenableBuiltInResolver Boolean (任意) - getaddrinfo ではなく組み込みのホストリゾルバを使用するかどうか。 有効にすると、組み込みリゾルバはシステムの DNS 設定を使用し、単体で DNS ルックアップを実行しようとします。 macOS ではデフォルトで有効、Windows と Linux ではデフォルトで無効になっています。secureDnsMode String (任意) - \"off\"、\"automatic\"、\"secure\" のいずれかにできます。 DNS-over-HTTP モードを設定します。 \"off\" の場合、DoH ルックアップは行われません。 \"automatic\" の場合、DoH が利用可能であれば DoH ルックアップが最初に実行され、安全でない DNS 検索がフォールバックとして実行されます。 \"secure\" の場合、DoH ルックアップのみが行われます。 既定値は \"automatic\" です。secureDnsServers String[] (任意) - DNS-over-HTTP サーバのテンプレートのリスト。 テンプレートのフォーマットについては、RFC8484 § 3 をご参照ください。 ほとんどのサーバーは POST メソッドをサポートしており、そういったサーバーのテンプレートは単なる URI です。 なお、一部のDNSプロバイダ では、このリストに DoH サーバーが提供されていなくても、DoH が明示的に無効化されていない限りリゾルバを自動的に DoH へアップグレードします。enableAdditionalDnsQueryTypes Boolean (任意) - 安全でない DNS 経由でリクエストが行われた場合に、従来の A および AAAA のクエリに加えて HTTPS (DNS タイプ 65) などの追加の DNS クエリタイプを許可するかどうかを制御します。 追加タイプを常に許可するセキュア DNS には影響しません。 省略値は true です。ホスト解決 (DNS と DNS-over-HTTPS) を設定します。 デフォルトでは、以下のリゾルバがこの順番で使用されます。
\ngetaddrinfo など)これは、暗号化されていない DNS の使用を制限する (secureDnsMode: \"secure\") か、DNS-over-HTTPS を無効にする (secureDnsMode: \"off\") ように設定できます。 また、組み込みリゾルバの有効化または無効化もできます。
安全でない DNS を無効にするには、 secureDnsMode に \"secure\" を指定します。 その場合、ユーザーの DNS 設定に DoH をサポートするプロバイダが無い場合に備えて、使用する DNS-over-HTTPS サーバのリストを提供しなければなりません。
app.configureHostResolver({\n secureDnsMode: 'secure',\n secureDnsServers: [\n 'https://cloudflare-dns.com/dns-query'\n ]\n})\nこの API は ready イベントが発生した後で呼ばなければいけません。
app.disableHardwareAcceleration()現在のアプリのハードウェアアクセラレーションを無効にします。
\nこのメソッドはアプリが ready になる前だけでしか呼び出すことができません。
\napp.disableDomainBlockingFor3DAPIs()既定では、GPU プロセスがあまりに頻繁にクラッシュする場合、ドメイン単位の原則に基づき、再起動するまで Chromium は 3D API (例えばWebGL) を無効にします。 この関数はこの振る舞いを無効にします。
\nこのメソッドはアプリが ready になる前だけでしか呼び出すことができません。
\napp.getAppMetrics()戻り値 ProcessMetric[]: ProcessMetric オブジェクトの配列で、アプリに関連付けられたすべてのプロセスのメモリや CPU 使用率の統計情報に対応しています。
app.getGPUFeatureStatus()戻り値 GPUFeatureStatus - chrome://gpu/ から取得したグラフィックス機能のステータス。
注: この情報は gpu-info-update イベントが発行された後にのみ利用できます。
app.getGPUInfo(infoType)infoType String - basic か complete にできます。戻り値 Promise<unknown>
infoType が complete に等しい場合、Promise は Chromium の GPUInfo オブジェクト 内におけるすべてのGPU情報を含んだ Object で解決されます。 これには chrome://gpu ページ上で表示されるバージョンとドライバ情報が含まれます。
infoType が basic に等しい場合、Promise は complete でのGPU情報より少ない属性を含んだ Object で解決されます。 basic の応答の例はこちらです。
{\n auxAttributes:\n {\n amdSwitchable: true,\n canSupportThreadedTextureMailbox: false,\n directComposition: false,\n directRendering: true,\n glResetNotificationStrategy: 0,\n inProcessGpu: true,\n initializationTime: 0,\n jpegDecodeAcceleratorSupported: false,\n optimus: false,\n passthroughCmdDecoder: false,\n sandboxed: false,\n softwareRendering: false,\n supportsOverlays: false,\n videoDecodeAcceleratorFlags: 0\n },\n gpuDevice:\n [{ active: true, deviceId: 26657, vendorId: 4098 },\n { active: false, deviceId: 3366, vendorId: 32902 }],\n machineModelName: 'MacBookPro',\n machineModelVersion: '11.5'\n}\nvendorId や driverId のような基本的な情報だけ必要であれば、basic を用いることが好ましいです。
app.setBadgeCount([count]) Linux macOScount Integer (任意) - 値が指定されている場合は、指定された値のバッジを設定します。そうでない場合、macOS では無地の白点 (通知数不明などの意味) を表示します。 Linux で値を指定しない場合、バッジは表示されません。戻り値 Boolean - 呼び出しが成功したかどうか。
現在のアプリのカウンターバッジを設定します。 カウントを 0 に設定すると、バッジを非表示にします。
macOS では Dock アイコンに表示されます。 Linux では Unity ランチャーでのみ動作します。
\n注意: Unity ランチャーは動作にあたって .desktop ファイルを必要とします。 詳しい情報は、Unity 統合ドキュメント をご覧ください。
app.getBadgeCount() Linux macOS戻り値 Integer - カウンターバッジに表示されている現在の値。
app.isUnityRunning() Linux戻り値 Boolean - 現在のデスクトップ環境がUnityランチャーであるかどうか。
app.getLoginItemSettings([options]) macOS Windowsoptions Object (任意)app.setLoginItemSettings に path と args オプションを指定した場合、openAtLogin が正しく設定されるように、ここで同じ引数を引き渡す必要があります。
戻り値 Object:
openAtLogin Boolean - アプリがログイン時に開くように設定されている場合、true。openAsHidden Boolean macOS - アプリがログイン時に隠して開くように設定されている場合 true です。 この設定は MAS ビルド では利用できません。wasOpenedAtLogin Boolean macOS - アプリがログイン時に自動的に開かれた場合 true です。 この設定は MAS ビルド では利用できません。wasOpenedAsHidden Boolean macOS - アプリが非表示のログイン項目として開かれていた場合 true です。 これは、アプリが起動時に何もウインドウを開いてはいけないことを示します。 この設定は MAS ビルド では利用できません。restoreState Boolean macOS - 以前のセッションから状態を復元する必要があるログイン項目としてアプリを開いた場合 true です。 アプリが最後に閉じたとき開いていたウインドウをアプリが復元する必要があることを示します。 この設定は MAS ビルド では利用できません。executableWillLaunchAtLogin Boolean Windows - true アプリはログイン時に開くように設定されており、その実行キーが無効化されていない場合。 openAtLoginはargs オプションを無視する点が異なっています。与えられた実行ファイルがログイン時なんらかの引数が与えれた場合にこのプロパティは 真 になります。launchItems Object[] Windowsname String Windows - レジストリエントリの名前の値。path String Windows - レジストリエントリに対応するアプリの実行可能ファイル。args String Windows - 実行ファイルに渡すコマンドライン引数。scope String Windows - user または machine のどちらか。 レジストリエントリが HKEY_CURRENT USER または HKEY_LOCAL_MACHINE の下にあるかどうかを示します。enabled Boolean Windows - 次の場合trueになります。アプリレジストリキーが承認されているため、タスクマネージャと Windows 設定で enabled として表示されている場合。app.setLoginItemSettings(settings) macOS Windowssettings ObjectopenAtLogin Boolean (任意) - アプリをログイン時に開く場合は true、ログイン項目からアプリを外す場合は false にします。 省略値は false 。openAsHidden Boolean (任意) macOS - アプリを非表示で開く場合 true にします。 省略値は false です。 ユーザはこの設定をシステム環境設定から変更することができるので、現在の値を取得するために app.getLoginItemSettings().wasOpenedAsHidden をアプリが開かれたときに確認するようにしてください。 この設定は MAS ビルド では利用できません。path String (任意) Windows - ログイン時に起動する実行形式。 省略値は process.execPath です。args String Windows - 実行ファイルに渡すコマンドライン引数。 省略値は空の配列です。 パスはテンプレート文字列にするようにしましょう。enabled Boolean (任意) Windows - true の場合、スタートアップが承認したレジストリキーを変更し、 タスクマネージャと Windows 設定で アプリを有効/無効にします。 省略値は true です。name String (任意) Windows - レジストリに書きこむ値の名前。 デフォルトはアプリの AppUserModelId() です。 アプリのログイン項目設定を設定します。Windows 上で Electron の autoUpdater を Squirrel を使って動かす場合、起動パスを Update.exe に設定し、渡す引数にアプリケーション名を指定してください。 以下がその例です。
const appFolder = path.dirname(process.execPath)\nconst updateExe = path.resolve(appFolder, '..', 'Update.exe')\nconst exeName = path.basename(process.execPath)\n\napp.setLoginItemSettings({\n openAtLogin: true,\n path: updateExe,\n args: [\n '--processStart', `\"${exeName}\"`,\n '--process-start-args', `\"--hidden\"`\n ]\n})\napp.isAccessibilitySupportEnabled() macOS Windows戻り値 Boolean - Chromeのユーザ補助機能が有効な場合、true、そうでない場合、false。 このAPIは、スクリーンリーダーなどの支援技術を使っていることが検出された場合、true を返します。 詳細については、https://www.chromium.org/developers/design-documents/accessibility を参照してください。
app.setAccessibilitySupportEnabled(enabled) macOS Windowsenabled Boolean - アクセシビリティツリーレンダリングを有効もしくは無効にします。手動でChromeのユーザ補助機能を有効にすると、アプリケーションの設定でユーザにアクセシビリティスイッチを出すことができます。 詳細については Chromium のアクセシビリティドキュメント を参照してください。 既定では無効です。
\nこの API は ready イベントが発生した後で呼ばなければいけません。
注: アクセシビリティツリーをレンダリングすると、アプリのパフォーマンスに顕著な影響を与える可能性があります。 既定で有効にすべきではありません。
\napp.showAboutPanel()アプリの About パネルを表示します。 このオプションは app.setAboutPanelOptions(options)で上書きできます。
app.setAboutPanelOptions(options)options ObjectapplicationName String (任意) - アプリの名前。applicationVersion String (任意) - アプリのバージョン。copyright String (任意) - 著作権情報。version String (任意) macOS - アプリのビルドバージョン番号。credits String (任意) macOS Windows - クレジット情報。authors String Linux - アプリの作者のリスト。website String (任意) Linux - アプリのウェブサイト。iconPath String (任意) Linux Windows - JPEGまたはPNGフォーッマットの、アプリのアイコンへのパス。 Linux で、アスペクト比を保ったまま 64×64 ピクセルで表示されます。Aboutパネルのオプションを設定します。 macOS の場合、これはアプリの .plist ファイルで定義された値を上書きします。 詳細は Apple のドキュメント を参照してください。 Linuxの場合、表示するために値をセットしなければなりません。デフォルトの値はありません。
credits を設定していなくてもアプリに表示したい場合、AppKit は NSBundle の main クラスメソッドから返されたバンドル内で、\"Credits.html\"、\"Credits.rtf\"、\"Credits.rtfd\" の順番でファイルを探します。 最初に見つかったファイルが使用されます。見つからない場合、その情報の部分は空白のままです。 詳細は Apple の ドキュメント を参照してください。
app.isEmojiPanelSupported()戻り値 Boolean - 現在の OS バージョンがネイティブの絵文字ピッカーを許可しているかどうか。
app.showEmojiPanel() macOS Windowsプラットフォームのネイティブの絵文字ピッカーを表示します。
\napp.startAccessingSecurityScopedResource(bookmarkData) masbookmarkData String - dialog.showOpenDialog または dialog.showSaveDialog メソッドによって返された、base64 でエンコードされたセキュリティスコープのブックマークデータ。戻り値 Function - セキュリティスコープ付きファイルへのアクセスが終了すれば、この関数の呼び出しを しなければなりません。 ブックマークへのアクセスを忘れた場合は、カーネルリソースがリークします。アプリが再起動されるまで、サンドボックスの外部にアクセスする権限は失われます。
// ファイルアクセス開始\nconst stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)\n// サンドボックス外のファイルにアクセスできるようになりました 🎉\n\n// ファイルへのアクセスが終わったらアクセス停止を忘れずに。\nstopAccessingSecurityScopedResource()\nセキュリティスコープ付きリソースへのアクセスを開始します。 このメソッドでは、Mac App Store 用にパッケージ化された Electron アプリケーションが、ユーザーが選択したファイルにアクセスするためにサンドボックスの外部にアクセスすることがあります。 このシステムの動作の詳細は、Apple のドキュメント を参照してください。
\napp.enableSandbox()アプリで完全サンドボックスモードを有効にします。 これは、WebPreferences の sandbox フラグの値に関係なく、すべてのレンダラーがサンドボックスで起動されることを意味します。
このメソッドはアプリが ready になる前だけでしか呼び出すことができません。
\napp.isInApplicationsFolder() macOS戻り値 Boolean - アプリケーションが現在、システムのアプリケーションフォルダから実行されているかどうか。 app.moveToApplicationsFolder() と組み合わせて使ってください。
app.moveToApplicationsFolder([options]) macOSoptions Object (任意)conflictHandler Function\\conflictType String - ハンドラーが遭遇した移動で起こった競合の種類。exists か existsAndRunning になります。exists は同じ名前のアプリがアプリケーションディレクトリに存在し、existsAndRunning は存在し且つ現在実行されていることを意味します。戻り値 Boolean - 移動が成功したかどうか。 移動が成功した場合、アプリケーションは終了し、再起動されることに注意してください。
デフォルトでは確認ダイアログは表示されません。 ユーザに操作の確認をさせたい場合は、dialog API で実現できます。
注意: このメソッドはユーザ以外が移動の失敗を引き起こした場合にもエラーを送出します。 例えば、ユーザが承認ダイアログをキャンセルした場合、このメソッドは false を返します。 コピーの実行に失敗した場合、このメソッドはエラーをスローします。 エラーのメッセージは意味の分かるものにする必要があり、何が間違っているのかを正確に知らせるようにしてください。
\n既定では、移動するアプリと同じ名前のアプリがアプリケーションディレクトリに存在し実行されて いない 場合、既存のアプリはゴミ箱に移動され、新たなアプリがその場所に移動します。 実行されている 場合、既存の実行中のアプリはフォーカスを引き継ぎ、新たなアプリは自動的に終了します。 この挙動は、オプションの競合ハンドラを提供することで変更できます。この場合、ハンドラによって返されるブール値によって、移動の競合がデフォルトの動作で解決されるかどうかを決定します。 つまり、false を返すとそれ以上のアクションは行われなくなります。true を返すとデフォルトの動作になり、メソッドが続行されます。
以下がその例です。
\napp.moveToApplicationsFolder({\n conflictHandler: (conflictType) => {\n if (conflictType === 'exists') {\n return dialog.showMessageBoxSync({\n type: 'question',\n buttons: ['移動を中止', '移動を続行'],\n defaultId: 0,\n message: 'この名前のアプリはすでに存在します'\n }) === 1\n }\n }\n})\nそのユーザーディレクトリにアプリが既に存在する場合、ユーザーが '移動を続行' を選択すると、関数は既定の動作を続行し、既存のアプリは破棄され、新たなアプリはその場所に移動します。
\napp.isSecureKeyboardEntryEnabled() macOS戻り値 Boolean - キーボード入力のセキュリティを保護 が有効になっているかどうか。
この API は既定で false を返します。
app.setSecureKeyboardEntryEnabled(enabled) macOSenabled Boolean - キーボード入力のセキュリティを保護 を有効にするかどうかアプリケーションの キーボード入力のセキュリティを保護 の有効化を設定します。
この API を利用すると、パスワードなどの重要な情報や機密情報を他のプロセスの傍受から防げます。
\n詳しくは Apple のドキュメント を参照してください。
\n注意: キーボード入力のセキュリティを保護 は必要なときにのみ有効にし、不要なときには無効にしてください。
app.accessibilitySupportEnabled macOS Windowsこの Boolean プロパティは、Chrome のアクセシビリティサポートが有効になっている場合は true、それ以外の場合は false になります。 このプロパティは、テキスト読み上げなどのアシスト技術を使っていることが検出された場合、true を返します。 手動でこのプロパティを true にセットして Chrome のアクセシビリティサポートを有効にすると、開発者はアプリケーション設定内でユーザにアクセシビリティスイッチを出すことができます。
詳細については Chromium のアクセシビリティドキュメント を参照してください。 既定では無効です。
\nこの API は ready イベントが発生した後で呼ばなければいけません。
注: アクセシビリティツリーをレンダリングすると、アプリのパフォーマンスに顕著な影響を与える可能性があります。 既定で有効にすべきではありません。
\napp.applicationMenuMenu | null 型のプロパティです。セットされている場合は Menu を、それ以外は null を返します。 ユーザはこのプロパティに Menu を渡すことができます。
app.badgeCount Linux macOSInteger 型のプロパティです。現在のアプリのバッジカウントを返します。 カウントを 0 に設定するとバッジを非表示にします。
macOS では、ゼロ以外の整数を設定すると、ドックアイコンに表示されます。 Linux では Unity ランチャーでのみ動作します。
\n注意: Unity ランチャーは動作にあたって .desktop ファイルを必要とします。 詳しい情報は、Unity 統合ドキュメント をご覧ください。
注意: macOS でこのプロパティを有効にするには、アプリケーションに通知を表示する権限があるかどうか確認する必要があります。
\napp.commandLine 読み出し専用CommandLine オブジェクトです。Chromium が使用するコマンドライン引数の読み取りと操作ができます。
app.dock macOS ReadonlyDock | undefined 型のオブジェクトです。macOS のユーザーの Dock 内のアプリアイコンにおけるアクションを実行できます。
app.isPackaged 読み出し専用アプリがパッケージされている場合はtrue、それ以外は false を返す Boolean プロパティ。 多くのアプリケーションでは、このプロパティを用いて開発版の環境と製品版の環境を区別できます。
app.nameString 型のプロパティです。現在のアプリケーション名を示します。アプリケーションの package.json ファイル内にある名前になります。
通常、package.json の name フィールドは、npm のモジュール仕様に基づいて小文字だけの短い名前が設定されます。 通常、すべて大文字で始まるアプリケーションの名前となる productName フィールドも指定してください。Electronによって、name よりも優先されます。
app.userAgentFallbackこの String は Electron がグローバルフォールバックとして使用するユーザーエージェント文字列です。
これは、webContents または session レベルでユーザーエージェントが設定されていない場合に使用されるユーザーエージェントです。 アプリ全体が同じユーザーエージェントを持っていることを確認するのに役立ちます。 オーバーライドされた値が確実に使用されるように、アプリの初期化のできるだけ早い段階でカスタム値に設定してください。
app.runningUnderRosettaTranslation macOS Readonly DeprecatedBoolean 型で、true の場合アプリが Rosetta 変換環境 下で動作していることを示します。
このプロパティを使用すれば、x64 版を Rosetta で誤って実行している場合に、arm64 版のアプリケーションをダウンロードするようにユーザーに促すことができます。
\n非推奨: このプロパティは runningUnderARM64Translation プロパティに置き換えられます。こちらは macOS と Windows の両方でアプリを ARM64 に変換したかどうかを検出します。
app.runningUnderARM64Translation Readonly macOS WindowsBoolean 型で、trueの場合はアプリが現在 ARM64 変換機 (macOS の Rosetta 変換環境 や Windows の WOW など) で動作していることを示します。
このプロパティを使用すれば、x64 版を Rosetta で誤って実行している場合に、arm64 版のアプリケーションをダウンロードするようにユーザーに促すことができます。
", "title": "app", "description": "アプリケーションのイベントライフサイクルを制御します。" }, "/docs/tutorial/application-debugging": { "locale": "ja-JP", "slug": "application-debugging", "href": "/docs/tutorial/application-debugging", "crowdinFileId": "256175", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/application-debugging.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron アプリケーションが望むように動作しないときは、デバッグツール一式がコーディングエラー、パフォーマンスのボトルネック、最適化の機会を見つけるのに役立つかもしれません。
\n個々のレンダラープロセスをデバッグするための最も包括的なツールは、Chromium Developer Toolset です。 BrowserWindow、BrowserView、WebView のインスタンスを含むすべてのレンダラープロセスに対して利用可能です。 インスタンスの webContents 上で openDevTools() APIを呼ぶことで、プログラムで開くことができます。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.webContents.openDevTools()\nGoogle は 開発者向けツールの優れたドキュメント を提供しています。 通常、Electron 開発者のツールベルトの中で最も強力なユーティリティの1つです。自分自身に慣れさせることを推奨します。
\nメインプロセスのデバッグは少し難解です。なぜなら、開発者向けツールで開くことができないからです。 Google / Chrome と Node.js の緊密なコラボレーションのおかげで、Chromium デベロッパーツールを使用して Electron のメインプロセスをデバッグする ことができます。しかし、コンソールにrequire が存在しないなどの奇妙な問題が発生する可能性があります。
より詳しい情報は、メインプロセスのデバッグのドキュメント を参照してください。
\nV8 コンテキストがクラッシュした場合、デベロッパー ツールにこのメッセージが表示されます。
\nデベロッパー ツールはページから切断されました。 ページをリロードすれば、デベロッパー ツールは自動で再接続します。
Chromium のログは ELECTRON_ENABLE_LOGGING 環境変数を介して有効にできます。 詳しい情報は 環境変数ドキュメント を参照してください。
代替として、--enable-logging コマンドライン引数を渡すことでもできます。 詳しい情報は コマンドラインスイッチドキュメント を参照してください。
Electron アプリを配布するには、パッケージ化してアイコンを変更する必要があります。 アイコンの変更にあたっては、専用ツールか手動で行うかを選べます。
\nアプリケーションの配布には以下のツールを使用できます。
\n\nこれらのツールは、あなたの Electron アプリケーションを配布可能にするにあたって必要な全手順を網羅しています。この手順には、アプリケーションのパッケージング、実行ファイルのリブランド、正しいアイコンの設定が含まれます。
\nクイックスタートガイド にて electron-forge でアプリのパッケージ方法のサンプルを確認できます。
手動でアプリを配布する際は、Electron の ビルド済みバイナリ をダウンロードする必要があります。 次に、アプリケーションが含まれたフォルダの名前を app に変更し、Electron のリソースディレクトリに以下に示すように配置します。
\n\n注意: 以下の例では、Electron のビルド済みバイナリの場所を
\nelectron/としています。
macOS:
\nelectron/Electron.app/Contents/Resources/app/\n├── package.json\n├── main.js\n└── index.html\nWindows および Linux:
\nelectron/resources/app\n├── package.json\n├── main.js\n└── index.html\nその後、macOS では Electron.app、Linux では electron、Windows では electron.exe を実行すると、Electron がアプリとして起動します。 そして、その electron ディレクトリがユーザーに頒布する頒布物となります。
Parcel や Webpack などのバンドラを使用していない場合、ソースファイルをすべてコピーしてアプリを頒布するのではなく asar アーカイブにアプリをパッケージすることで、Windows のようなプラットフォーム上でファイルの読み出しパフォーマンスを改善できます。
\napp フォルダの代わりに asar アーカイブを使用するためには、アーカイブファイルを app.asar という名前に変更し、Electron のリソースディレクトリに以下のように配置する必要があります。そうすれば、Electron はアーカイブを読み込みを試み、そこから起動します。
macOS:
\nelectron/Electron.app/Contents/Resources/\n└── app.asar\nWindows および Linux:
\nelectron/resources/\n└── app.asar\nelectron/asar リポジトリ に asar の使い方の詳細を掲載してあります。
アプリを Electron にバンドルした後、ユーザーに配布する前に、 Electron の名称変更をしたいでしょう。
\nElectron.app のファイル名は、好きな任意の名前に変更することが出来ます。その場合、以下のファイル内の CFBundleDisplayName、CFBundleIdentifier、CFBundleName も変更する必要があります。
Electron.app/Contents/Info.plistElectron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plistアクティビティモニタ上で Electron Helper と表示されるのを避けるために、ヘルパーアプリの名前を変更することも出来ます。ただし、ヘルパーアプリの実行ファイル名が変更されていることを確認してください。
名前を変更したアプリケーションの構造は以下のようになります。
\nMyApp.app/Contents\n├── Info.plist\n├── MacOS/\n│ └── MyApp\n└── Frameworks/\n └── MyApp Helper.app\n ├── Info.plist\n └── MacOS/\n └── MyApp Helper\nelectron.exe のファイル名は、任意の名前に変更することが出来ます。また、アイコンやその他の情報を rcedit のようなツールで編集出来ます。
electron 実行形式の名前は好きな任意の名前に変更できます。
ソースからプロダクト名を変更してビルドすることで、Electron を名称変更することも可能です。 これを行うには、製品名に対応するビルド引数 (electron_product_name = \"YourProductName\" ) を args.gn ファイルに設定して再ビルドする必要があります。
\n\nアプリを自動的に更新することができます。
\n
プロセス: Main
\nこちらも参照: アプリケーションを更新する
\nautoUpdater は EventEmitter を継承しています。
現在、macOS と Windows にのみ対応しています。 Linux では、自動更新の組み込みサポートがないので、アプリ更新にはディストリビューションのパッケージマネージャーの使用を推奨しています。
\nさらに、各プラットフォームではいくつかの微妙な違いがあります。
\nmacOSでは、autoUpdater モジュールは Squirrel.Mac で構築されているので、動作させるのに特別なセットアップ作業をする必要はありません。 サーバー側の要件については、サーバーサポート をお読みください。 アプリケーショントランスポートセキュリティ (ATS) が、更新処理の一部としてなされるすべてのリクエストに適用されることに注意してください。 アプリのplistに NSAllowsArbitraryLoads キーを追加することで、ATSを無効にすることができます。
注: macOS で自動更新を有効にするには、アプリ署名が必要です。 これは Squirrel.Mac の動作要件です。
Windows で autoUpdater を使用するには、アプリをユーザのマシンにインストールする必要があります。electron-winstaller、electron-forge、grunt-electron-installer のいずれかのパッケージで Windows インストーラを生成することを推奨します。
electron-winstaller または electron-forge を使用する場合、初回実行時に アプリを更新しようとしないようにしてください (この issue の詳細情報 も参照)。 アプリのデスクトップショートカットを作成する electron-squirrel-startup も使用することを推奨します。
\nSquirrel で作成されたインストーラは、例えば、com.squirrel.slack.Slack や com.squirrel.code.Code といったcom.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE という形式の アプリケーションユーザ ID を持つショートカットアイコンを作成します。 app.setAppUserModelId APIでアプリに対して同じIDを使うようにしてください。そうでないと、Windowsはタスクバーにアプリを正しくピン留めすることができません。
Squirrel.Mac と同様に、Windows でも S3 やその他の静的ファイルホストで更新プログラムをホストできます。 Squirrel.Windows の仕組みの詳細については、Squirrel.Windows のドキュメントをお読みください。
\nautoUpdater オブジェクトは以下のイベントを発生させます。
戻り値：
\nerror Error更新中にエラーがあるときに出力されます。
\n更新が始まったかどうかをチェックするときに放出されます。
\n利用可能な更新がある場合に発生します。 更新は自動ダウンロードされます。
\n利用可能な更新がない場合に出力されます。
\n戻り値：
\nevent EventreleaseNotes StringreleaseName StringreleaseDate DateupdateURL String更新プログラムがダウンロードされたときに発生します。
\nWindowsでは releaseName のみ利用可能です。
注: 必ずこのイベントを処理する必要はありません。 ダウンロードに成功した更新は、次回のアプリケーション起動時でも適用されます。
\nこのイベントは、ユーザが呼び出した quitAndInstall() の後に発火されます。
この API が呼ばれた時、すべてのウィンドウが閉じられる前に before-quit イベントは発火されません。 結果として、プロセス終了時にウィンドウが閉じられる前にアクションを実行するために、before-quit をリッスンする場合は、このイベントも同様にリッスンする必要があります。
autoUpdater オブジェクトには以下のメソッドがあります
autoUpdater.setFeedURL(options)options Objecturl Stringheaders Record<String, String> (任意) macOS - HTTP リクエストのヘッダ。serverType String (任意) macOS - json、default のいずれかです。詳細は Squirrel.Mac README を参照してください。url を設定して自動更新を初期化します。
autoUpdater.getFeedURL()戻り値 String - 現在の更新フィードURL。
autoUpdater.checkForUpdates()更新があるかどうかサーバーに問い合わせます。 この API を使用する前に setFeedURL を呼び出す必要があります。
注意: アップデート可能であれは、自動でダウンロードされます。 autoUpdater.checkForUpdates() を 2 回呼び出すと、更新データを 2 回ダウンロードすることになります。
autoUpdater.quitAndInstall()ダウンロード後にアプリを再起動し、更新をインストールします。 update-downloaded が発生した後でしか呼び出さないでください。
autoUpdater.quitAndInstall() を呼ぶと、この中では最初にすべてのアプリケーションウィンドウを閉じ、すべてのウィンドウが閉じられた後に自動的に app.quit() を呼び出します。
注意: アップデートを適用するために必ずこの関数を呼ぶ必要はなく、ダウンロードに成功したアップデートは次回のアプリケーション起動時に必ず適用されます。
", "title": "autoUpdater", "description": "アプリを自動的に更新することができます。" }, "/docs/tutorial/automated-testing-with-a-custom-driver": { "locale": "ja-JP", "slug": "automated-testing-with-a-custom-driver", "href": "/docs/tutorial/automated-testing-with-a-custom-driver", "crowdinFileId": "256179", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/automated-testing-with-a-custom-driver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron アプリの自動テストを作成するには、アプリケーションを「ドライブ」する方法が必要になります。 Spectron は、WebDriver を介してユーザの操作をエミュレートする、一般的な解決方法です。 ただし、Node に組み込まれている IPC 越し標準入出力を使用して独自のカスタムドライバを書くことも可能です。 カスタムドライバの利点は、Spectron よりもオーバーヘッドが少なくて済むことです。また、カスタムメソッドをあなたのテストスイートに公開できます。
\nカスタムドライバを作成するには、Node.js の child_process API を使用します。 テストスイートは、以下のように Electron プロセスを spawn してから、簡単なメッセージングプロトコルを確立します。
\nconst childProcess = require('child_process')\nconst electronPath = require('electron')\n\n// プロセスの生成\nconst env = { /* ... */ }\nconst stdio = ['inherit', 'inherit', 'inherit', 'ipc']\nconst appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })\n\n// アプリからの IPC メッセージをリッスン\nappProcess.on('message', (msg) => {\n // ...\n})\n\n// アプリへ IPC メッセージを送る\nappProcess.send({ my: 'message' })\nElectron アプリケーション内からは、Node.js の process API を使用して、メッセージをリッスンして返信を送信できます。
\n// テストスイートからの IPC メッセージをリッスンする\nprocess.on('message', (msg) => {\n // ...\n})\n\n// テストスイートへ IPC メッセージを送る\nprocess.send({ my: 'message' })\nこれで、appProcess オブジェクトを使用してテストスイートから Electron アプリケーションに通信できます。
利便性のために、より高度な機能を提供するドライバオブジェクトで appProcess をラップすることをお勧めします。 以下は、これをどのようにするかの例です。
class TestDriver {\n constructor ({ path, args, env }) {\n this.rpcCalls = []\n\n // 子プロセスの開始\n env.APP_TEST_DRIVER = 1 // メッセージをリッスンする必要性をアプリに知らせる\n this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })\n\n // RPC レスポンスのハンドリング\n this.process.on('message', (message) => {\n // ハンドラを除去\n const rpcCall = this.rpcCalls[message.msgId]\n if (!rpcCall) return\n this.rpcCalls[message.msgId] = null\n // 拒否/解決\n if (message.reject) rpcCall.reject(message.reject)\n else rpcCall.resolve(message.resolve)\n })\n\n // ready を待つ\n this.isReady = this.rpc('isReady').catch((err) => {\n console.error('Application failed to start', err)\n this.stop()\n process.exit(1)\n })\n }\n\n // 簡単な RPC 呼び出し\n // to use: driver.rpc('method', 1, 2, 3).then(...)\n async rpc (cmd, ...args) {\n // rpc リクエストを送信する\n const msgId = this.rpcCalls.length\n this.process.send({ msgId, cmd, args })\n return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))\n }\n\n stop () {\n this.process.kill()\n }\n}\nこのアプリでは、RPC 呼び出しのために簡単なハンドラを作成する必要があります。
\nif (process.env.APP_TEST_DRIVER) {\n process.on('message', onMessage)\n}\n\nasync function onMessage ({ msgId, cmd, args }) {\n let method = METHODS[cmd]\n if (!method) method = () => new Error('Invalid method: ' + cmd)\n try {\n const resolve = await method(...args)\n process.send({ msgId, resolve })\n } catch (err) {\n const reject = {\n message: err.message,\n stack: err.stack,\n name: err.name\n }\n process.send({ msgId, reject })\n }\n}\n\nconst METHODS = {\n isReady () {\n // ここで必要なセットアップをします\n return true\n }\n // ここで RPC 可能なメソッドを定義します\n}\nすると、テストスイート内では、以下のようにテストドライバを使用できます。
\nconst test = require('ava')\nconst electronPath = require('electron')\n\nconst app = new TestDriver({\n path: electronPath,\n args: ['./app'],\n env: {\n NODE_ENV: 'test'\n }\n})\ntest.before(async t => {\n await app.isReady\n})\ntest.after.always('cleanup', async t => {\n await app.stop()\n})\nWindows 上の Electron CI は AppVeyor を使用し、AppVeyor は Azure VM イメージを実行に使用します。 場合によっては、Chromium の要件が変更されたため、これらの VM イメージを更新する必要があります。 更新するには、PowerShell と Azure PowerShell モジュール が必要です。
\n時折、Chromium の変更やその他のビルド要件の変更により、これらのイメージを更新する必要があります。
\nユースケースの例:\n* VS15.9 が必要なのに VS15.7 がインストールされているので、Azure イメージを更新する必要がある。
修正したいイメージを指定します。
\nAzure ストレージアカウントキーを取得します
\nappveyorlibccbuilds という ディスクストレージアカウント名 の場合、ストレージアカウントのリスト @ ホーム < ストレージアカウントで appveyorlibccbuilds を探します。アクセスキー を見つけます。そして、リストにあるキーのうちどれでも使うことができます。Azure からフルの仮想マシンイメージ URI を取得します
\n$ACCT_NAME < Blobs < イメージ に移動します。マスターイメージ PowerShell スクリプトをコピー を用いてイメージをコピーします。
\n(images) を使用しますlibcc-20core-vs2017-15.9-2019-04-15.vhdVHD PowerShell からマスター VM を作成 を用いて新しい VM を起動します。
\n./create_master_vm_from_vhd.ps1 のような ps1 ファイルを実行します。Standard_F32s_v2 を使用しますEast US を使用しますAzure にログインし直して先ほど作成した VM を探します。ホーム < 仮想マシン < $YOUR_NEW_VM を見てください。
Microsoft リモート デスクトップを使用して、接続 をクリックして VM に接続します。
AppVeyor Enterprise マスター VM 認証情報下にあります。必要に応じて VM を変更してください。
\nAzure で VM をシャットダウンして削除します。
\nAppveyor クラウドの設定に新しいイメージを追加するか、新しい VHD を指すように既存のイメージを変更します。
\ndeviceName StringdeviceId StringElectron での開発は特定のやり方に固執しておらず、開発、ビルド、パッケージ、リリースに「一つの正しいやり方」はありません。 Electron への追加機能は、ビルドと実行時の両方において、大抵の場合 npm 上で独立したパッケージとして見つけられます。開発者は必要なアプリとビルドパイプラインの両方を構築できます。
\nこのレベルのモジュール性と拡張性のために、チーム規模の大小を問わず、Electron を使用しているすべての開発者が、開発ライフサイクル中のいかなる可能なことも不可能なことも決して制限されません。 しかし、多くの開発者にとっては、コミュニティ主導のボイラープレートやコマンドラインツールを使用すると、アプリのコンパイル、パッケージ、リリースが劇的に簡単になるかもしれません。
\nボイラープレートはアプリケーションを構築するためのスタート地点、いわばカンバスです。 通常、ボイラープレートはクローン可能なレポジトリとして提供され、自分の要求に応じたカスタマイズができます。
\n一方で、コマンドラインツールは開発からリリースまでをサポートしてくれます。 より多くの点で開発を手助けしてくれますが、コードの構成やビルド方法についての制約を強制します。 特に初心者はコマンドラインツールを使うのが良いでしょう。
\n\"モダンなElectronアプリケーションを作成する完璧なツール\"。 Electron Forge は、既存の (よく保守されている) Electron 開発用のビルドツール群をまとまったパッケージに統合しており、誰でもすぐに Electron 開発に着手できるようにします。
\nForge には Webpack をバンドラーとして利用するための 即席テンプレート があります。 Typescript の構成例が含まれており、簡単にカスタマイズできる構成ファイル 2 つが提供されています。 これは、大規模な Electron コミュニティで使用されているものと同じコアモジュールを使用しています (electron-packager など)。(Slack のような) Electron メンテナによる変更は、Forge のユーザにも有益です。
詳細とドキュメントは electronforge.io で見ることができます。
\nこの \"Electron アプリをパッケージしてビルドして即配布できる完璧ソリューション\" は総合的な経験に焦点を当てています。 electron-builder は、単純さに重点を置いた単一の依存関係を1つ追加し、他の要件は内部で管理します。
electron-builder は、Electron メンテナー (自動更新プログラムなど) が使用する機能やモジュールをカスタムのものに置き換えます。 これらは一般的に緊密に統合されていますが、Atom、Visual Studio Code や、Slack のような人気のある Electron アプリケーションとの共通点は少なくなります。
より詳しい情報やドキュメントは レポジトリ にあります。
\nツールを使わずにしっかりしたボイラープレートのみを作成する場合、CT Lin の electron-react-boilerplate は一見の価値があるかもしれません。 これはコミュニティで非常に人気があり、electron-builder は内部で使用しています。
\"Awesome Electron\" リスト ではより多くのツールやボイラープレートを紹介しています。 リストの長さのあまり探すことに足がすくんでしまう場合は、ツールを追加することも有効な方法であることを忘れないでください。
", "title": "ボイラープレートとCLI", "description": "" }, "/docs/breaking-changes": { "locale": "ja-JP", "slug": "breaking-changes", "href": "/docs/breaking-changes", "crowdinFileId": "256117", "githubUrl": "https://github.com/electron/electron/tree/main/docs/breaking-changes.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "破壊的な変更は変更の 一つ前のメジャーバージョン についてここに文書化され、可能であれば非推奨の警告を JS コードに加えます。
\nこのドキュメントでは、以下の規約によって破壊的な変更を分類しています。
\nremote モジュールremote モジュールは Electron 12 で非推奨となりました。Electron 14 で削除される予定です。 これは @electron/remote モジュールに置き換えられます。
// Electron 12では非推奨:\nconst { BrowserWindow } = require('electron').remote\n// こちらに置換:\nconst { BrowserWindow } = require('@electron/remote')\n\n// メインプロセスでは:\nrequire('@electron/remote/main').initialize()\napp.allowRendererProcessReuseapp.allowRendererProcessReuse プロパティは、セキュリティ、パフォーマンス、保守性のために Chromium のプロセスモデルとより密接に連携する計画の一環として削除されます。
詳細は #18397 を参照してください。
\nBrowserWindow を新規構築する際の affinity オプションは、セキュリティ、パフォーマンス、保守性のために Chromium のプロセスモデルとの共同連携計画の一環として削除されます。
詳細は #18397 を参照してください。
\nwindow.open()任意引数 frameName は、ウィンドウのタイトルに設定されなくなります。 これにより、ネイティブの document に対応するパラメータ windowName で説明されている仕様に従うことになりました。
この引数でウィンドウのタイトルを設定していた場合は、代わりに win.setTitle(title) を利用できます。
\nworldSafeExecuteJavaScriptElectron 14 では、 worldSafeExecuteJavaScript が削除されます。 代替手段はありませんので、このプロパティが有効になった上でのコードの動作を確認してください。 これは Electron 12 からデフォルトで有効になっています。\n12.
webFrame.executeJavaScript か webFrame.executeJavaScriptInIsolatedWorld のいずれかを使用している場合、この変更の影響を受けます。 これらのメソッドは同じ値渡しセマンティクスを使用しているため、Context Bridge API がサポートしている戻り値かどうかを確認する必要があります。
nativeWindowOpen の省略値を true にElectron 14 より前の window.open は既定で BrowserWindowProxy を使用していました。 このため、window.open('about:blank') では同期的にスクリプトで操作可能な子ウィンドウを開くことができないなどといった、非互換性がありました。 nativeWindowOpen は実験的でなくなり、既定値になります。
詳細については Electron での window.open をご参照ください
\nElectron 14 より前は、window.open で開いたウインドウは、親ウインドウから transparent や resizable などの BrowserWindow コンストラクタのオプションを継承していました。 Electron 14 以降ではこの動作は削除され、ウインドウは親から BrowserWindow コンストラクタのオプションを継承しません。
代わりに、setWindowOpenHandler で以下のように新しいウインドウのオプションを明示的に設定してください。
webContents.setWindowOpenHandler((details) => {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n // ...\n }\n }\n})\nadditionalFeaturesWebContents の new-window イベントと did-create-window イベントの、非推奨となっていた additionalFeatures プロパティは削除されました。 new-window は引数の順番があるのでこの引数はまだ残りますが、常に空の配列 [] になります。 (ただし注意として、new-window イベント自体は非推奨であり setWindowOpenHandler に置き換えられます。) ウインドウ機能のキーに値が無い場合は、オプションオブジェクトで true の値を持つキーとして表示されるようになりました。
// Electron 14 で削除\n// window.open('...', '', 'my-key') で動く\nwebContents.on('did-create-window', (window, details) => {\n if (details.additionalFeatures.includes('my-key')) {\n // ...\n }\n})\n\n// こちらに置換\nwebContents.on('did-create-window', (window, details) => {\n if (details.options['my-key']) {\n // ...\n }\n})\nsession.setPermissionCheckHandler(handler)handler メソッドの第 1 引数は、前までは必ず webContents でしたが、これからは null になることもあります。 requestingOrigin、embeddingOrigin、securityOrigin プロパティを使用して、権限の確認へ正しく対応する必要があります。 webContents が null になることがあるので、これに依存しないようにしてください。
// 古いコード\nsession.setPermissionCheckHandler((webContents, permission) => {\n if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {\n return true\n }\n return false\n})\n\n// こちらに置換\nsession.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {\n return true\n }\n return false\n})\nshell.moveItemToTrash()非推奨となっていた同期型の shell.moveItemToTrash() API が削除されました。 代わりに非同期の shell.trashItem() を使用してください。
// Electron 13 では削除されます。\nshell.moveItemToTrash(path)\n// 以下と置き換えてください\nshell.trashItem(path).then(/* ... */)\nBrowserWindow 拡張機能 API以下の非推奨の API が削除されました。
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()代わりに以下の session API を使用してください。
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Electron 13 で削除\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// こちらに置換\nsession.defaultSession.loadExtension(path)\n// Electron 13 で削除\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// こちらに置換\nsession.defaultSession.removeExtension(extension_id)\n// Electron 13 で削除\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// こちらに置換\nsession.defaultSession.getAllExtensions()\nsystemPreferences のメソッド以下の systemPreferences のメソッドは非推奨になりました。
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()代わりに、次の nativeTheme プロパティを使用します。
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Electron 13 で削除\nsystemPreferences.isDarkMode()\n// こちらに置換\nnativeTheme.shouldUseDarkColors\n\n// Electron 13 で削除\nsystemPreferences.isInvertedColorScheme()\n// こちらに置換\nnativeTheme.shouldUseInvertedColorScheme\n\n// Electron 13 で削除\nsystemPreferences.isHighContrastColorScheme()\n// こちらに置換\nnativeTheme.shouldUseHighContrastColors\nnew-window イベントWebContents の new-window イベントは非推奨となりました。 これは webContents.setWindowOpenHandler() に置き換えられます。
// Electron 13 で非推奨\nwebContents.on('new-window', (event) => {\n event.preventDefault()\n})\n\n// こちらに置換\nwebContents.setWindowOpenHandler((details) => {\n return { action: 'deny' }\n})\nChromium が Flash のサポートを削除したため、私たちもこれに従わなければなりません。 詳細については、Chromium の Flash Roadmap を参照してください。
\nworldSafeExecuteJavaScript の省略値を true にElectron 12 からは worldSafeExecuteJavaScript が既定で有効です。 以前の動作に戻すには、WebPreferences で worldSafeExecuteJavaScript: false を指定する必要があります。 このオプションを false に設定すると 安全ではなくなる ことに注意してください。
このオプションは Electron 14 で削除予定なので、デフォルト値をサポートするようにコードを移行してください。
\ncontextIsolation の省略値を true にElectron 12 からは contextIsolation が既定で有効です。 以前の動作に戻すには、WebPreferences で contextIsolation: false を指定する必要があります。
アプリケーションのセキュリティのために、contextIsolation の有効化を推奨します。
\nこれは、nodeIntegration が true かつ contextIsolation が false でない限り、require() がレンダラープロセスで使用できなくなるということでもあります。
詳細はこちら: https://github.com/electron/electron/issues/23506
\ncrashReporter.getCrashesDirectory()crashReporter.getCrashesDirectory メソッドは削除されました。 app.getPath('crashDumps)に置き換える必要があります。
// Electron 12 で削除\ncrashReporter.getCrashesDirectory()\n// こちらに置換\napp.getPath('crashDumps')\ncrashReporter メソッド以下の crashReporter メソッドはレンダラープロセスで利用できなくなります。
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryこれらは、メインプロセスから呼び出ことしかできません。
\n詳しくは #23265 を参照してください。
\ncrashReporter.start({ compress: true })crashReporter.start の compress オプションの既定値が false から true へ変更されました。 つまり、クラッシュのダンプは Content-Encoding: gzip ヘッダで、本文が圧縮されてクラッシュ収集サーバーにアップロードされます。
クラッシュ収集サーバーが圧縮形式のペイロードをサポートしていない場合、クラッシュレポーターのオプションで { compress: false } を指定すれば圧縮をオフにできます。
remote モジュールremote モジュールは Electron 12 で非推奨となり、Electron 14 で削除される予定です。 これは @electron/remote モジュールに置き換えられます。
// Electron 12では非推奨:\nconst { BrowserWindow } = require('electron').remote\n// こちらに置換:\nconst { BrowserWindow } = require('@electron/remote')\n\n// メインプロセスでは:\nrequire('@electron/remote/main').initialize()\nshell.moveItemToTrash()同期的な shell.moveItemToTrash() は、新しく非同期的な shell.trashItem() に置き換えられました。
// Electron 12 では非推奨\nshell.moveItemToTrash(path)\n// 以下と置き換えてください。\nshell.trashItem(path).then(/* ... */)\nBrowserView.{destroy, fromId, fromWebContents, getAllViews} と BrowserView の id プロパティ実験的 API BrowserView.{destroy, fromId, fromWebContents, getAllViews} が削除されました。 加えて、BrowserView の id プロパティも削除されました。
詳細な情報は、#23578 を参照してください。
\ncrashReporter.start() 関数のcompanyName 引数crashReporter.start()の引数のcompanyName は以前は必須でしたが、省略可能になり、今後廃止することになりました。 非推奨ではない方法で以前と同じ動作を実現するには、 globalExtra にcompanyName の値を渡します。
// Electron 10 で非推奨\ncrashReporter.start({ companyName: 'Umbrella Corporation' })\n// 置き換え\ncrashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })\ncrashReporter.getCrashesDirectory()crashReporter.getCrashesDirectory メソッドは非推奨となりました。 app.getPath('crashDumps)に置き換える必要があります。
// Electron 10 では非推奨\ncrashReporter.getCrashesDirectory()\n// 置き換え\napp.getPath('crashDumps')\ncrashReporter メソッドレンダラープロセスから以下の crashReporter メソッドを呼び出すことは非推奨になります。:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryレンダラーの crashReporter モジュールに残っている非推奨ではないメソッドは、 extraParameterと removeExtraParameter とgetParametersだけです。
上記のすべてのメソッドは、メインプロセスから呼び出されたときに非推奨のままです。
\n詳しくは #23265 を参照してください。
\ncrashReporter.start({ compress: false })crashReporter.start に { compress: false } を指定することは非推奨です。 ほぼすべてのクラッシュ収集サーバーは gzip 圧縮をサポートしているためです。 このオプションは将来バージョンの Electron で削除されます。
enableRemoteModule の省略値を false にElectron 9 では、enableRemoteModule WebPreferences オプションによって明示的に有効にせずに remote モジュールを使用すると、警告を出すようになりました。 Electron 10 では、remote モジュールはデフォルトで利用できなくなります。 remote モジュールを使用するには、以下のように WebPreferences で enableRemoteModule: true を指定する必要があります。
const w = new BrowserWindow({\n webPreferences: {\n enableRemoteModule: true\n }\n})\n私たちは remote モジュールから離れるように推奨しています。
\nprotocol.unregisterProtocolprotocol.uninterceptProtocolAPI は同期になり、任意のコールバックは不要になりました。
\n// 非推奨\nprotocol.unregisterProtocol(scheme, () => { /* ... */ })\n// こちらに置換\nprotocol.unregisterProtocol(scheme)\nprotocol.registerFileProtocolprotocol.registerBufferProtocolprotocol.registerStringProtocolprotocol.registerHttpProtocolprotocol.registerStreamProtocolprotocol.interceptFileProtocolprotocol.interceptStringProtocolprotocol.interceptBufferProtocolprotocol.interceptHttpProtocolprotocol.interceptStreamProtocolAPI は同期になり、任意のコールバックは不要になりました。
\n// 非推奨\nprotocol.registerFileProtocol(scheme, handler, () => { /* ... */ })\n// こちらに置換\nprotocol.registerFileProtocol(scheme, handler)\n登録または干渉されたプロトコルは、ナビゲーションが発生するまで現在のページに影響しません。
\nprotocol.isProtocolHandledこの API は非推奨です。ユーザーは、代わりに protocol.isProtocolRegistered および protocol.isProtocolIntercepted を使用する必要があります。
// 非推奨\nprotocol.isProtocolHandled(scheme).then(() => { /* ... */ })\n// こちらに置換\nconst isRegistered = protocol.isProtocolRegistered(scheme)\nconst isIntercepted = protocol.isProtocolIntercepted(scheme)\nElectron 9 では、レンダラープロセスでコンテキスト未対応のネイティブモジュールをロードすることはできなくなります。 これは Electron のプロジェクトとしてのセキュリティ、パフォーマンス、保守性を向上させるためです。
\nこれが影響する場合、app.allowRendererProcessReuse を false に設定して一時的に以前の動作に戻すことができます。 このフラグは Electron 11 までの設定となっており、ネイティブモジュールを更新してコンテキストに対応する必要があります。
詳細は #18397 を参照してください。
\nBrowserWindow 拡張機能 APIこれらの拡張機能 API は非推奨になりました。
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()代わりに以下の session API を使用してください。
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Electron 9 で非推奨化\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// こちらに置換\nsession.defaultSession.loadExtension(path)\n// Electron 9 で非推奨化\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// こちらに置換\nsession.defaultSession.removeExtension(extension_id)\n// Electron 9 で非推奨化\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// こちらに置換\nsession.defaultSession.getAllExtensions()\n<webview>.getWebContents()Electron 8.0 で非推奨となっていた、この API は削除されました。
\n// Electron 9.0 で削除\nwebview.getWebContents()\n// こちらに置換\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium は、レイアウトのズームレベル制限を変更するサポートを削除しました。そのうえ、これは Elcetron でメンテナンスできるものではありません。 この関数は Electron 8.x で非推奨となり、Electron 9.x で削除されました。 レイアウトのズームレベル制限は、こちら で定義されているように最小 0.25 から最大 5.0 に固定されました。
\nElectron 8.0 では、構造化複製アルゴリズムを使用するように IPC が変更され、パフォーマンスが大幅に改善されました。 移行を容易にするため、旧 IPC シリアライズアルゴリズムは、構造化複製でシリアライズできない一部のオブジェクトにそのまま使用されます。 特に、DOM オブジェクト (Element、Location、DOMMatrix など)、内部に C++ のクラスがある Node.js オブジェクト (process.env、Stream のいくつかのメンバーなど)、内部に C++ のクラスがある Electron オブジェクト (WebContents、BrowserWindow、WebFrame など) は、構造化複製ではシリアライズできません。 旧アルゴリズムが呼び出されるたびに、非推奨の警告が出力されます。
Electron 9.0 では、旧シリアライズアルゴリズムが削除されました。先ほどのシリアライズ不可能なオブジェクトを送信すると、\"object could not be cloned\" (オブジェクトを複製できませんでした) というエラーが送出されます。
\nshell.openItem は shell.openPath にshell.openItem API は非同期の shell.openPath API に置き換えられました。 元の API の提案と理由は こちら で確認できます。
IPC を介して (ipcRenderer.send、ipcRenderer.sendSync、WebContents.send 及び関連メソッドから) オブジェクトを送信できます。このオブジェクトのシリアライズに使用されるアルゴリズムが、カスタムアルゴリズムから V8 組み込みの 構造化複製アルゴリズム に切り替わります。これは postMessage のメッセージのシリアライズに使用されるものと同じアルゴリズムです。 これにより、大きなメッセージに対するパフォーマンスが 2 倍向上しますが、動作に重大な変更が加えられます。
undefined に変換していましたが、代わりに例外が送出されるようになります。// 以前:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => メインプロセスに { value: 3 } が着く\n\n// Electron 8 から:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => Error(\"() => {} could not be cloned.\") を投げる\nNaN、Infinity、-Infinity は、null に変換するのではなく、正しくシリアライズします。null に変換するのではなく、正しくシリアライズします。Set、Map、Error、RegExp の値は、{} に変換するのではなく、正しくシリアライズします。BigInt の値は、null に変換するのではなく、正しくシリアライズします。null の密配列に変換するのではなく、そのままシリアライズします。Date オブジェクトは、ISO 文字列表現に変換するのではなく、Date オブジェクトとして転送します。Uint8Array、Uint16Array、Uint32Array など) は、Node.js の Buffer に変換するのではなく、そのまま転送します。Buffer オブジェクトは、Uint8Array として転送します。 基底となる ArrayBuffer をラップすることで、Uint8Array を Node.js の Buffer に変換できます。Buffer.from(value.buffer, value.byteOffset, value.byteLength)\nネイティブな JS 型ではないオブジェクト、すなわち DOM オブジェクト (Element、Location、DOMMatrix など)、Node.js オブジェクト (process.env、Stream のいくつかのメンバーなど)、Electron オブジェクト (WebContents、BrowserWindow、WebFrame など) のようなものは非推奨です。 Electron 8 では、これらのオブジェクトは DeprecationWarning メッセージで以前と同様にシリアライズされます。しかし、Electron 9 以降でこういった類のオブジェクトを送信すると \"could not be cloned\" エラーが送出されます。
<webview>.getWebContents()この API は、パフォーマンスとセキュリティの両方に影響する remote モジュールを使用して実装されます。 したがって、その用途がはっきりとしている必要があります。
// 非推奨\nwebview.getWebContents()\n// こちらに置換\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nただし、remote モジュールをできる限り使用しないことを推奨します。
// メイン\nconst { ipcMain, webContents } = require('electron')\n\nconst getGuestForWebContents = (webContentsId, contents) => {\n const guest = webContents.fromId(webContentsId)\n if (!guest) {\n throw new Error(`Invalid webContentsId: ${webContentsId}`)\n }\n if (guest.hostWebContents !== contents) {\n throw new Error('Access denied to webContents')\n }\n return guest\n}\n\nipcMain.handle('openDevTools', (event, webContentsId) => {\n const guest = getGuestForWebContents(webContentsId, event.sender)\n guest.openDevTools()\n})\n\n// レンダラー\nconst { ipcRenderer } = require('electron')\n\nipcRenderer.invoke('openDevTools', webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium は、レイアウトのズームレベル制限を変更するサポートを削除しました。そのうえ、これは Elcetron でメンテナンスできるものではありません。 この関数は Electron 8.x に警告を出力し、Electron 9.x に存在しなくなります。 レイアウトのズームレベル制限は、こちら で定義されているように最小 0.25 から最大 5.0 に固定されました。
\nsystemPreferences のイベント以下の systemPreferences のイベントは非推奨になりました。
inverted-color-scheme-changedhigh-contrast-color-scheme-changed代わりに nativeTheme の新しいイベントである updated を使用してください。
// 非推奨\nsystemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })\nsystemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })\n\n// こちらに置換\nnativeTheme.on('updated', () => { /* ... */ })\nsystemPreferences のメソッド以下の systemPreferences のメソッドは非推奨になりました。
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()代わりに、次の nativeTheme プロパティを使用します。
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Deprecated\nsystemPreferences.isDarkMode()\n// Replace with\nnativeTheme.shouldUseDarkColors\n\n// Deprecated\nsystemPreferences.isInvertedColorScheme()\n// Replace with\nnativeTheme.shouldUseInvertedColorScheme\n\n// Deprecated\nsystemPreferences.isHighContrastColorScheme()\n// Replace with\nnativeTheme.shouldUseHighContrastC\nこれは .npmrc ファイル内の disturl か、ネイティブ Node モジュールをビルドするときの --dist-url コマンドライン引数で指定する URL です。 両方とも近い将来サポートされますが、切り替えることを推奨します。
非推奨: https://atom.io/download/electron
\nこちらに置換: https://electronjs.org/headers
\nsession.clearAuthCache() が引数を受け取らないようにsession.clearAuthCache API は、消去対象のオプションを受け入れなくなり、代わりにキャッシュ全体を無条件に消去します。
// 非推奨\nsession.clearAuthCache({ type: 'password' })\n// こちらに置換\nsession.clearAuthCache()\npowerMonitor.querySystemIdleState は powerMonitor.getSystemIdleState に// Electron 7.0 で削除\npowerMonitor.querySystemIdleState(threshold, callback)\n// こちらの非同期 API に置換\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime は powerMonitor.getSystemIdleTime に// Electron 7.0 で削除\npowerMonitor.querySystemIdleTime(callback)\n// こちらの非同期 API に置換\nconst idleTime = powerMonitor.getSystemIdleTime()\nwebFrame.setIsolatedWorldInfo で分散したメソッドを置換// Electron 7.0 で削除\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// こちらに置換\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\ngetBlinkMemoryInfo の marked プロパティこのプロパティは Chromium 77 で削除されたため、利用できなくなりました。
\n<input type=\"file\"/> の webkitdirectory 属性でディレクトリの内容を取るようにwebkitdirectory プロパティは、HTML ファイル上の input でフォルダーを選択できるようにします。 以前の Electron のバージョンでは、input の event.target.files において、選択したフォルダーに対応する 1 つの File が入った FileList を返すという誤った実装がありました。
Electron 7 では、Chrome、Firefox、Edge と同様 (MDNドキュメントへのリンク) に、FileList はフォルダー内に含まれるすべてのファイルのリストになりました。
例として、以下の構造のフォルダーを使用します。
\nfolder\n├── file1\n├── file2\n└── file3\nElectron <= 6 では、以下のような File オブジェクトが 1 つ入った FileList を返します。
path/to/folder\nElectron 7 では、以下のような File オブジェクトが入った FileList を返します。
/path/to/folder/file3\n/path/to/folder/file2\n/path/to/folder/file1\nwebkitdirectory は、選択したフォルダーへのパスを公開しないことに注意してください。 フォルダーの内容ではなく選択したフォルダーへのパスが必要な場合は、dialog.showOpenDialog API (リンク) を参照してください。
Electron 5 とElectron 6 では、既存の非同期 API の Promise ベース版を導入し、対応する古いコールバックベースのものは非推奨にしました。 Electron 7 では、非推奨のコールバックベースの API がすべて削除されます。
\nこれらの関数は Promise を返すようになりました。
\napp.getFileIcon() #15742app.dock.show() #16904contentTracing.getCategories() #16583contentTracing.getTraceBufferUsage() #16600contentTracing.startRecording() #16584contentTracing.stopRecording() #16584contents.executeJavaScript() #17312cookies.flushStore() #16464cookies.get() #16464cookies.remove() #16464cookies.set() #16464debugger.sendCommand() #16861dialog.showCertificateTrustDialog() #17181inAppPurchase.getProducts() #17355inAppPurchase.purchaseProduct()#17355netLog.stopLogging() #16862session.clearAuthCache() #17259session.clearCache() #17185session.clearHostResolverCache() #17229session.clearStorageData() #17249session.getBlobData() #17303session.getCacheSize() #17185session.resolveProxy() #17222session.setProxy() #17222shell.openExternal() #16176webContents.loadFile() #15855webContents.loadURL() #15855webContents.hasServiceWorker() #16535webContents.printToPDF() #16795webContents.savePage() #16742webFrame.executeJavaScript() #17312webFrame.executeJavaScriptInIsolatedWorld() #17312webviewTag.executeJavaScript() #17312win.capturePage() #15743これらの関数には、同期と Promise ベースの非同期、2 つの形式があります。
\ndialog.showMessageBox()/dialog.showMessageBoxSync() #17298dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054win.setMenu(null) は win.removeMenu() に// 非推奨\nwin.setMenu(null)\n// こちらに置換\nwin.removeMenu()\nelectron.screen が remote を介してアクセスするように// 非推奨\nrequire('electron').screen\n// こちらに置換\nrequire('electron').remote.screen\nrequire() で remote のものを読み込まないように// 非推奨\nrequire('child_process')\n// こちらに置換\nrequire('electron').remote.require('child_process')\n\n// 非推奨\nrequire('fs')\n// こちらに置換\nrequire('electron').remote.require('fs')\n\n// 非推奨\nrequire('os')\n// こちらに置換\nrequire('electron').remote.require('os')\n\n// 非推奨\nrequire('path')\n// こちらに置換\nrequire('electron').remote.require('path')\npowerMonitor.querySystemIdleState を powerMonitor.getSystemIdleState で置換// 非推奨\npowerMonitor.querySystemIdleState(threshold, callback)\n// こちらの非同期 API に置換\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime を powerMonitor.getSystemIdleTime で置換// 非推奨\npowerMonitor.querySystemIdleTime(callback)\n// こちらの非同期 API に置換\nconst idleTime = powerMonitor.getSystemIdleTime()\napp.enableMixedSandbox() が不要に// 非推奨\napp.enableMixedSandbox()\n混合サンドボックスモードはデフォルトで有効になりました。
\nTray.setHighlightModemacOS Catalina 下では、以前の Tray 実装は破壊されています。 Apple のネイティブの代替実装は、強調表示動作の変更をサポートしていません。
\n// 非推奨\ntray.setHighlightMode(mode)\n// API は v7.0 で削除され、置換はできません\nnodeIntegration と webviewTag の省略値は false に、contextIsolation の省略値は true に以下の webPreferences オプションの初期値は、以下の記載された新しい初期値のために非推奨になっています。
| 属性 | 非推奨の初期値 | 新しい初期値 |
|---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration を設定しなければ true | false |
以下は例です。 webviewTag を再有効化しています。
\nconst w = new BrowserWindow({\n webPreferences: {\n webviewTag: true\n }\n})\nnodeIntegration は nativeWindowOpen を介して開かれるようにnativeWindowOpen オプションで開かれる子ウインドウは、nodeIntegrationInSubFrames が true でなければ Node.js インテグレーションが無効化されます。
レンダラプロセス API webFrame.registerURLSchemeAsPrivileged と webFrame.registerURLSchemeAsBypassingCSP、ならびにブラウザプロセス API protocol.registerStandardSchemes を削除しました。 新しい API protocol.registerSchemesAsPrivileged が追加されました。これらは、必要な権限でカスタムスキームを登録するために使用する必要があります。 カスタムスキームは、アプリの準備が整う前に登録する必要があります。
webFrame.setIsolatedWorld* を webFrame.setIsolatedWorldInfo で置換// 非推奨\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// こちらに置換\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nwebFrame.setSpellCheckProvider が非同期コールバックを取るようにspellCheck コールバックは非同期になり、autoCorrectWord パラメーターは削除されました。
// 非推奨\nwebFrame.setSpellCheckProvider('en-US', true, {\n spellCheck: (text) => {\n return !spellchecker.isMisspelled(text)\n }\n})\n// こちらに置換\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck: (words, callback) => {\n callback(words.filter(text => spellchecker.isMisspelled(text)))\n }\n})\nwebContents.getZoomLevel と webContents.getZoomFactor が同期実行にwebContents.getZoomLevel と webContents.getZoomFactor はコールバック引数を受け取らなくなり、代わりに数値を直接返すようになります。
// 非推奨\nwebContents.getZoomLevel((level) => {\n console.log(level)\n})\n// こちらに置換\nconst level = webContents.getZoomLevel()\nconsole.log(level)\n// 非推奨\nwebContents.getZoomFactor((factor) => {\n console.log(factor)\n})\n// こちらに置換\nconst factor = webContents.getZoomFactor()\nconsole.log(factor)\n以下のリストには Electron 4.0 でなされた破壊的な API の変更が含まれています。
\napp.makeSingleInstance// 非推奨\napp.makeSingleInstance((argv, cwd) => {\n /* ... */\n})\n// こちらに置換\napp.requestSingleInstanceLock()\napp.on('second-instance', (event, argv, cwd) => {\n /* ... */\n})\napp.releaseSingleInstance// 非推奨\napp.releaseSingleInstance()\n// こちらに置換\napp.releaseSingleInstanceLock()\napp.getGPUInfoapp.getGPUInfo('complete')\n// macOS 上では `basic` と同様に振る舞う\napp.getGPUInfo('basic')\nwin_delay_load_hookWindows でネイティブモジュールをビルドするとき、モジュールの binding.gyp 内の win_delay_load_hook 変数は true (これが初期値) にならなければいけません。 このフックが存在しない場合ネイティブモジュールは Windows 上でロードできず、モジュールが見つかりません のようなエラーメッセージが表示されます。 より詳しくは ネイティブモジュールガイド を参照してください。
以下のリストには Electron 3.0 での破壊的な API の変更が含まれています。
\napp// 非推奨\napp.getAppMemoryInfo()\n// こちらに置換\napp.getAppMetrics()\n\n// 非推奨\nconst metrics = app.getAppMetrics()\nconst { memory } = metrics[0] // 非推奨なプロパティ\nBrowserWindow// 非推奨\nconst optionsA = { webPreferences: { blinkFeatures: '' } }\nconst windowA = new BrowserWindow(optionsA)\n// こちらに置き換えてください\nconst optionsB = { webPreferences: { enableBlinkFeatures: '' } }\nconst windowB = new BrowserWindow(optionsB)\n\n// 非推奨\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play_pause') {\n // do something\n }\n})\n// こちらに置き換えてください\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play-pause') {\n // do something\n }\n})\n`
\n// 非推奨\nclipboard.readRtf()\n// こちらに置換\nclipboard.readRTF()\n\n// 非推奨\nclipboard.writeRtf()\n// こちらに置換\nclipboard.writeRTF()\n\n// 非推奨\nclipboard.readHtml()\n// こちらに置換\nclipboard.readHTML()\n\n// 非推奨\nclipboard.writeHtml()\n// こちらに置換\nclipboard.writeHTML()\ncrashReporter// 非推奨\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n autoSubmit: true\n})\n// こちらに置換\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n uploadToServer: true\n})\nnativeImage// 非推奨\nnativeImage.createFromBuffer(buffer, 1.0)\n// こちらに置換\nnativeImage.createFromBuffer(buffer, {\n scaleFactor: 1.0\n})\nプロセス// 非推奨\nconst info = process.getProcessMemoryInfo()\nscreen// 非推奨\nscreen.getMenuBarHeight()\n// こちらに置換\nscreen.getPrimaryDisplay().workArea\nsession// 非推奨\nses.setCertificateVerifyProc((hostname, certificate, callback) => {\n callback(true)\n})\n// こちらに置換\nses.setCertificateVerifyProc((request, callback) => {\n callback(0)\n})\nTray// 非推奨\ntray.setHighlightMode(true)\n// こちらに置換\ntray.setHighlightMode('on')\n\n// 非推奨\ntray.setHighlightMode(false)\n// こちらに置換\ntray.setHighlightMode('off')\nwebContents// 非推奨\nwebContents.openDevTools({ detach: true })\n// こちらに置換\nwebContents.openDevTools({ mode: 'detach' })\n\n// 削除されました\nwebContents.setSize(options)\n// この API は置換できません\nwebFrame// 非推奨\nwebFrame.registerURLSchemeAsSecure('app')\n// こちらに置換\nprotocol.registerStandardSchemes(['app'], { secure: true })\n\n// 非推奨\nwebFrame.registerURLSchemeAsPrivileged('app', { secure: true })\n// こちらに置換\nprotocol.registerStandardSchemes(['app'], { secure: true })\n<webview>// 削除されました\nwebview.setAttribute('disableguestresize', '')\n// この API は置換できません\n\n// 削除されました\nwebview.setAttribute('guestinstance', instanceId)\n// この API は置換できません\n\n// webview タグ上ではキーボードリスナは動作しなくなります\nwebview.onkeydown = () => { /* handler */ }\nwebview.onkeyup = () => { /* handler */ }\nこれは .npmrc ファイル内の disturl か、ネイティブ Node モジュールをビルドするときの --dist-url コマンドライン引数で指定する URL です。
非推奨: https://atom.io/download/atom-shell
\nこちらに置換: https://atom.io/download/electron
\n以下のリストには Electron 2.0 でなされた破壊的な API の変更が含まれています。
\nBrowserWindow// 非推奨\nconst optionsA = { titleBarStyle: 'hidden-inset' }\nconst windowA = new BrowserWindow(optionsA)\n// こちらに置換\nconst optionsB = { titleBarStyle: 'hiddenInset' }\nconst windowB = new BrowserWindow(optionsB)\nmenu// 削除されました\nmenu.popup(browserWindow, 100, 200, 2)\n// こちらに置換\nmenu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })\nnativeImage// 削除されました\nnativeImage.toPng()\n// こちらに置換\nnativeImage.toPNG()\n\n// 削除されました\nnativeImage.toJpeg()\n// こちらに置換\nnativeImage.toJPEG()\nプロセスprocess.versions.electron と process.version.chrome は、Node によって定められた他の process.versions プロパティと一貫性を持つために読み取り専用プロパティになりました。webContents// 削除されました\nwebContents.setZoomLevelLimits(1, 2)\n// こちらに置換\nwebContents.setVisualZoomLevelLimits(1, 2)\nwebFrame// 削除されました\nwebFrame.setZoomLevelLimits(1, 2)\n// こちらに置換\nwebFrame.setVisualZoomLevelLimits(1, 2)\n<webview>// 削除されました\nwebview.setZoomLevelLimits(1, 2)\n// こちらに置換\nwebview.setVisualZoomLevelLimits(1, 2)\nどの Electron リリースにも、electron-v1.7.3-linux-arm.zip や electron-v1.7.3-linux-armv7l.zip のような少しファイル名が異なる2つの同一な ARM ビルドが含まれます。 サポートされている ARM バージョンをユーザに明確にし、将来作成される armv6l および arm64 アセットらと明確にするために、v7l という接頭子を持つアセットが追加されました。
接頭子が付いていない ファイルは、まだそれを使用している可能性がある設定を破壊しないために公開しています。 2.0 からは、接頭子のないファイルは公開されなくなりました。
\n", "title": "破壊的変更", "description": "" }, "/docs/api/browser-view": { "locale": "ja-JP", "slug": "browser-view", "href": "/docs/api/browser-view", "crowdinFileId": "256283", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-view.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "BrowserView は、BrowserWindow に追加のウェブコンテンツを埋め込むのに使用することができます。 外側のウインドウを基準にして配置される点を除いて、子ウインドウのようなものです。 webview タグの代替となるものです。
\n\nビューを作成したり、制御したりします。
\n
プロセス: Main
\n// メインプロセス\nconst { BrowserView, BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nconst view = new BrowserView()\nwin.setBrowserView(view)\nview.setBounds({ x: 0, y: 0, width: 300, height: 300 })\nview.webContents.loadURL('https://electronjs.org')\nnew BrowserView([options]) 実験的options Object (任意)webPreferences Object (任意) - BrowserWindow を参照してください。new BrowserView で作成されたオブジェクトは、以下のプロパティを持っています。
view.webContents 実験的このビューによって保持されている WebContents オブジェクト。
new BrowserView で作成されたオブジェクトは、次のインスタンスメソッドを持っています。
view.setAutoResize(options) 実験的options Objectwidth Boolean (任意) - true の場合、ビューの横幅はウインドウと一緒に伸び縮みします。 省略値は false です。height Boolean (任意) - true の場合、ビューの高さはウインドウと一緒に伸び縮みします。 省略値は false です。horizontal Boolean (任意) - true の場合、ビューの x 位置と幅はウィンドウに比例して増減します。 省略値は false です。vertical Boolean (任意) - true の場合、ビューの y 位置と高さはウィンドウに比例して増減します。 省略値は false です。view.setBounds(bounds) 実験的bounds Rectangleウインドウを基準に指定された境界までビューをリサイズしたり、移動させたりします。
\nview.getBounds() 実験的戻り値 Rectangle
Object としてのこの BrowserView インスタンスの bounds。
view.setBackgroundColor(color) 実験的color String - #aarrggbb や #argb といった形式の色。 アルファチャンネルは任意です。\n\nブラウザウィンドウを作成したり、制御したりします。
\n
プロセス: Main
\n// メインプロセス\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\n// 外部 URL を読み込む\nwin.loadURL('https://github.com')\n\n// またはローカルの HTML ファイルを読み込む\nwin.loadURL('index.html')\nFrameless Window APIを使うと、枠がないウインドウや任意の形状の透明なウインドウを作成することができます。
\nウインドウにページを直接ロードすると、ユーザにはページが徐々にロードされるように見えるかもしれません。これはネイティブアプリとしては良い挙動ではありません。 ちらつかせることなくウインドウを表示するには、さまざまな状況に応じた 2 つの解決策があります。
\nready-to-show イベントを使用するページのロード中、ウインドウがまだ表示されていない場合、レンダラープロセスが初めてページをレンダリングし終わったとき、ready-to-show イベントが発生します。 このイベントの後にウインドウを表示させれば、チラつくことはありません。
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ show: false })\nwin.once('ready-to-show', () => {\n win.show()\n})\nこのイベントは、通常、did-finish-load イベントの後に発生しますが、大量のリモートリソースがあるページでは、did-finish-load イベントの前に発生する可能性があります。
このイベントを使用すると、show が false でもレンダラーが \"見えている\" と見なされ、描画されることに注意してください。 paintWhenInitiallyHidden: false を使用すると、このイベントは発生しません。
backgroundColor プロパティを設定する複雑なアプリでは、ready-to-show イベントが発生するのに時間がかかり過ぎて、アプリが遅いと感じさせる可能性があります。 このような場合、ウインドウをすぐに表示し、アプリの背景に近い backgroundColor を使うことを推奨します。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ backgroundColor: '#2e2c29' })\nwin.loadURL('https://github.com')\nready-to-show イベントを使用しているアプリに対しても、アプリがよりネイティブに感じられるように backgroundColor を設定することが推奨されます。
parent オプションを使用することで、子ウインドウを作成することができます。
const { BrowserWindow } = require('electron')\n\nconst top = new BrowserWindow()\nconst child = new BrowserWindow({ parent: top })\nchild.show()\ntop.show()\nchild ウインドウは、常に top ウインドウの前面に表示されます。
モーダルウインドウは親ウインドウを無効化する子ウインドウです。モーダルウインドウを作成するには、parent と modal オプションの両方を設定しなければなりません。
const { BrowserWindow } = require('electron')\n\nconst child = new BrowserWindow({ parent: top, modal: true, show: false })\nchild.loadURL('https://github.com')\nchild.once('ready-to-show', () => {\n child.show()\n})\nPage Visibility API は、以下のように動作します。
\nhidden になります。 他のプラットフォーム上では、ウインドウが最小化されるか、明示的に win.hide() で非表示にされた場合のみ、表示状態は hidden になります。BrowserWindow が show: false で作成された場合、ウインドウが実際には非表示であるにも関わらず、初期の表示状態は visible になります。backgroundThrottling が無効の場合、ウインドウを最小化したり、重ねたり、非表示にしたりしても、表示状態は visible のままになります。消費電力を最小にするために、表示状態が hidden のとき、高負荷な操作を一時停止することを推奨します。
dialog に変更されます。\n\nブラウザウィンドウを作成したり、制御したりします。
\n
プロセス: Main
\nBrowserWindow は EventEmitter を継承しています。
options によって設定されたネイティブプロパティで新しい BrowserWindow を生成します。
new BrowserWindow([options])options Object (任意)width Integer (任意) - ピクセル単位でのウインドウの幅。 省略値は 800 です。height Integer (任意) - ピクセル単位でのウインドウの高さ。 省略値は 600 です。x Integer (任意) - (y が使われている場合は 必須) ウインドウの画面左のオフセット。 省略すると、ウインドウは中央に配置されます。y Integer (任意) - (x が使われている場合は 必須) ウインドウの画面上のオフセット。 省略すると、ウインドウは中央に配置されます。useContentSize Boolean (任意) - width と height が、Webページのサイズとして使用されます。この場合、実際のウインドウのサイズは、ウインドウ枠のサイズが含まれ、若干大きくなることを意味します。 省略値は false です。center Boolean (任意) - ウインドウを画面中央に表示します。minWidth Integer (任意) - ウインドウの最小の幅。 省略値は 0 です。minHeight Integer (任意) - ウィンドウの最小の高さ。 省略値は 0 です。maxWidth Integer (任意) - ウインドウの最大の幅。 省略すると無制限です。maxHeight Integer (任意) - ウインドウの最大の高さ。 省略すると無制限です。resizable Boolean (任意) - ウインドウがリサイズ可能かどうか。 省略値は true です。movable Boolean (任意) - ウインドウが移動可能かどうか。 これは Linux では実装されていません。 省略値は true です。minimizable Boolean (任意) - ウインドウが最小化可能かどうか。 これは Linux では実装されていません。 省略値は true です。maximizable Boolean (任意) - ウインドウが最大化可能かどうか。 これは Linux では実装されていません。 省略値は true です。closable Boolean (任意) - ウインドウを閉じることができるかどうか。 これは Linux では実装されていません。 省略値は true です。focusable Boolean (任意) - ウインドウにフォーカスを当てることができるかどうか。 省略値は true です。 Windowsでは、focusable: false と設定することは、skipTaskbar: true と設定することにもなります。 Linuxでは、focusable: false と設定することは、ウインドウがwmとのやり取りを停止することになるため、ウインドウがすべてのワークスペースで常に前面に表示されます。alwaysOnTop Boolean (任意) - ウインドウを常に他のウインドウの前面に表示させるかどうか。 省略値は false です。fullscreen Boolean (任意) - ウインドウをフルスクリーンで表示させるかどうか。 明示的に false と設定された場合、macOSでは、フルスクリーンボタンが非表示または無効になります。 省略値は false です。fullscreenable Boolean (任意) - ウインドウをフルスクリーンモードにすることができるかどうか。 macOSでは、さらに、最大化/ズームボタンが、フルスクリーンモードまたはウインドウ最大化に切り替わるかどうか。 省略値は true です。simpleFullscreen Boolean (任意) - macOS で Lion より前のフルスクリーンを使用します。 省略値は false です。skipTaskbar Boolean (任意) - ウインドウをタスクバーに表示するかどうか。 省略値は false です。kiosk Boolean (任意) - ウインドウがキオスクモードかどうか。 省略値は false です。title String (任意) - デフォルトのウインドウタイトル。 省略値は \"Electron\" です。 HTML タグの <title> が loadURL() でロードされた HTML ファイル内で定義されている場合、このプロパティは無視されます。icon (NativeImage | String) (任意) - ウインドウのアイコン。 Windowsでは、最高の視覚効果を得るためには、ICO アイコンを使うことを推奨します。未定義のままにすることもできますが、その場合、実行可能ファイルのアイコンが使われます。show Boolean (任意) - 生成時にウインドウを表示するかどうか。 省略値は true です。paintWhenInitiallyHidden Boolean (任意) - show が false で作成されたばかりのときに、レンダラーをアクティブにするかどうか。 show: false での document.visibilityState が最初のロードで正しく機能するには、これを false に設定する必要があります。 これを false に設定すると、ready-to-show イベントが発生しなくなります。 省略値は true です。frame Boolean (任意) - false を指定すると フレームレスウインドウ を生成します。 省略値は true です。parent BrowserWindow (任意) - 親ウインドウを指定します。 省略値は null です。modal Boolean (任意) - これをモーダルウインドウにするかどうか。 これは、このウインドウが子ウインドウの場合にのみ機能します。 省略値は false です。acceptFirstMouse Boolean (任意) - 非アクティブのウインドウをクリックしたとき、ウェブコンテンツにもクリックを渡すかどうか。 macOS での既定値は false です。 このオプションは他プラットフォームでは設定できません。disableAutoHideCursor Boolean (任意) - タイプ中にカーソルを非表示にするかどうか。 省略値は false です。autoHideMenuBar Boolean (任意) - Alt キーが押されていなければ、メニューバーを自動で非表示にします。 省略値は false です。enableLargerThanScreen Boolean (任意) - ウインドウを画面よりも大きいサイズに変更できるようにします。 他の OS はデフォルトで画面よりも大きなウィンドウを許可するため、macOS にのみ関係します。 省略値は false です。backgroundColor String (任意) - #66CD00 や #FFF や #80FFFFFF (transparent を true にセットすれば #AARRGGBB 形式のアルファ値をサポートします) のような16進数の値でのウインドウの背景色。 省略値は #FFF (白) です。hasShadow Boolean (任意) - ウインドウに影を付けるかどうか。 省略値は true です。opacity Number (任意) - ウインドウの初期透明度を 0.0 (完全に透明) から 1.0 (完全に不透明) の間で設定します。 これは Windows と macOS でのみ実装されています。darkTheme Boolean (任意) - ウインドウに対してダークテーマの使用を強制します。いくつかの GTK+3 デスクトップ環境でしか動作しません。 省略値は false です。transparent Boolean (任意) - ウインドウを 透明 にします。 省略値は false です。 Windows では、ウィンドウがフレームレスでない限り機能しません。type String (任意) - ウインドウのタイプで、省略すると通常のウインドウになります。 詳しくは後述します。visualEffectState String (任意) - macOS 上のウィンドウのアクティビティ状態をマテリアルの外観に反映させる方法を指定します。 vibrancyプロパティと一緒に使用する必要があります。 以下は取りうる値です。followWindow - ウィンドウがアクティブなときにはアクティブに、そうでないときには非アクティブになるよう背景が自動的に表示されます。 これが既定値です。active - 背景が常にアクティブに表示されます。inactive - 背景が常に非アクティブに表示されます。titleBarStyle String (任意) macOS Windows - ウインドウのタイトルバーのスタイル。 省略値は default です。 以下は取りうる値です。default - macOS や Windows ごとの標準的なタイトルバーになります。hidden - タイトルバーが隠れ、フルサイズのコンテンツウインドウになります。 macOS では、ウインドウの左上に標準ウインドウコントロール (\"信号機ボタン\") が付きます。 Windows では、titleBarOverlay: true と合わせることでウインドウコントロールオーバーレイ (詳細は titleBarOverlay を参照) が有効になり、さもなくばウインドウコントロールは表示されません。hiddenInset - macOS 限定で、タイトルバーが非表示になり、信号機ボタンがウインドウ端から少し離れたところに表示されるようになります。customButtonsOnHover - macOS 限定で、タイトルバーが非表示になり、フルサイズコンテンツのウインドウが表示されます。ウィンドウの左上にカーソルを置くと信号機ボタンが表示されるようになります。 注: 現在、これは実験的な機能です。trafficLightPosition Point (任意) - フレームレスウインドウにおける信号機ボタンのカスタム位置を設定します。roundedCorners Boolean (任意) - macOS でのフレームレスウインドウが丸角であるべきかどうか。 省略値は true です。fullscreenWindowTitle Boolean (任意) 非推奨 - macOSで titleBarStyle が hiddenInset のフルスクリーンモードでタイトルバーにタイトルを表示するかどうか。 省略値は false です。thickFrame Boolean (任意) - Windowsのフレームレスウインドウに対して、標準のウインドウ枠を追加する WS_THICKFRAME スタイルを使用します。 false に設定すると、ウインドウの影とウインドウアニメーションがなくなります。 省略値は true です。vibrancy String (任意) - macOSでのみ、ウインドウに曇りガラス効果の種類を追加します。 appearance-based、light、dark、titlebar、selection、menu、popover、sidebar、medium-light、ultra-dark、header、sheet、window、hud、fullscreen-ui、tooltip、content、under-window または under-page にすることができます。 appearance-based、light、dark、medium-light、ultra-dark は非推奨になっており、macOS Catalina (10.15) で削除されたことにご注意ください。zoomToPageWidth Boolean (任意) - macOS で、option キーを押しながら緑の信号ボタンをクリックしたり、ウインドウ > ズーム のメニュー項目をクリックしたりしたときの動作を制御します。 true の場合、ズームしたとき、ウインドウはWebページの最適な幅に拡大されます。false だと、画面の幅にズームされます。 これは、maximize() を直接呼び出したときの動作にも影響を与えます。 省略値は false です。tabbingIdentifier String (任意) - タブのグループ名で、macOS 10.12以上の場合、ネイティブのタブとしてウインドウを開くことができます。 同一のタブ識別子を持つウインドウは、一緒にグループ化されます。 これはネイティブのタブボタンをウインドウのタブバーに追加し、app とウインドウが new-window-for-tab イベントを受け取ることができるようになります。webPreferences Object (任意) - ウェブページの機能の設定です。devTools Boolean (任意) - デベロッパーツールを有効にするかどうか。 false に設定すると、BrowserWindow.webContents.openDevTools() を使ってデベロッパーツールを開くことはできません。 省略値は true です。nodeIntegration Boolean (任意) - Node インテグレーションを有効にするかどうか。 省略値は false です。nodeIntegrationInWorker Boolean (任意) - WebワーカーでNode統合を有効にするかどうか。 省略値は false です。 これについての詳細は、マルチスレッド を参照してください。nodeIntegrationInSubFrames Boolean (任意) - iframe や子ウインドウのようなサブフレーム内で Node.js サポートを有効にする実験的な機能です。 すべてのプリロードは iframe 毎にロードされます。メインフレーム内かそうでないか判断するには process.isMainFrame が使用できます。preload String (任意) - 他のスクリプトがページで実行される前にロードされるスクリプトを指定します。 このスクリプトは、Node統合がオンまたはオフであるかに関係なく常にNode APIにアクセスできます。 値は、スクリプトへの絶対ファイルパスにする必要があります。 Node統合がオフのときでも、プレロードされたスクリプトは、Nodeのグローバルシンボルをグローバルスコープに再導入できます。 ここ の例を参照してください。sandbox Boolean (任意) - 設定された場合、ウインドウと関連付けられているレンダラーをサンドボックス化します。これは、ChromiumのOSレベルのサンドボックスと互換性を持ち、Node.jsエンジンを無効化します。 これは nodeIntegration オプションと同じではなく、プレロードスクリプトで利用可能なAPIよりもさらに制限がかかります。 このオプションの詳細については、ここ をお読みください。session Session (任意) - ページで使用されるセッションを設定します。 Session オブジェクトを直接引き渡す代わりに、パーティション文字列を受け付ける partition オプションを使用することを選択することもできます。 session と partition の両方が指定されたときは、session が優先されます。 省略値は、既定のセッションです。partition String (任意) - セッションのパーティション文字列に従って、ページで使用されるセッションを設定します。 partition が persist: 始まりの場合、ページはアプリの全ページで利用可能な永続的なセッションを同じ partition で使用します。 persist: プレフィックスがない場合、ページは、インメモリセッションを使用します。 同じ partition を割り当てることによって、複数のページが同じセッションを共有できます。 省略値は、既定のセッションです。zoomFactor Number (任意) - ページの既定のズーム倍率で、3.0 は 300% を表します。 省略値は 1.0 です。javascript Boolean (任意) - JavaScript サポートを有効にします。 省略値は true です。webSecurity Boolean (任意) - false のとき、同一オリジンポリシー (通常、テスト用Webサイトを使用します) が無効になり、ユーザによって設定されない場合、allowRunningInsecureContent が true に設定されます。 省略値は true です。allowRunningInsecureContent Boolean (任意) - https のページで http の URL からの JavaScript、CSS やプラグインを実行することを許可します。 省略値は false です。images Boolean (任意) - 画像のサポートを有効にします。 省略値は true です。imageAnimationPolicy String (任意) - 画像アニメーションの実行方法を指定します。(例: GIF)。 animate、animateOnce、noAnimation のいずれかにできます。 省略値は animate です。textAreasAreResizable Boolean (任意) - TextArea 要素のサイズを変更可能にします。 省略値は true です。webgl Boolean (任意) - WebGL のサポートを有効にします。 省略値は true です。plugins Boolean (任意) - プラグインを有効にするかどうか。 省略値は false です。experimentalFeatures Boolean (任意) - Chromium の実験的な機能を有効にします。 省略値は false です。scrollBounce Boolean (任意) - macOS でスクロールバウンス (ラバーバンディング) 効果を有効にします。 省略値は false です。enableBlinkFeatures String (任意) - CSSVariables,KeyboardEventKey のように , で区切られた有効にする機能の文字列のリスト。 サポートされている機能の文字列の完全なリストは、RuntimeEnabledFeatures.json5 ファイルで確認することができます。disableBlinkFeatures String (任意) - CSSVariables,KeyboardEventKey のように , で区切られた無効にする機能の文字列のリスト。 サポートされている機能の文字列の完全なリストは、RuntimeEnabledFeatures.json5 ファイルで確認することができます。defaultFontFamily Object (任意) - 各フォントファミリーの既定フォントを設定します。standard String (任意) - 省略値は、Times New Roman です。serif String (任意) - 省略値は、Times New Roman です。sansSerif String (任意) - 省略値は、Arial です。monospace String (任意) - 省略値は、Courier New です。cursive String (任意) - 省略値は、Script です。fantasy String (任意) - 省略値は、Impact です。defaultFontSize Integer (任意) - 省略値は、16 です。defaultMonospaceFontSize Integer (任意) - 省略値は、13 です。minimumFontSize Integer (任意) - 省略値は、0 です。defaultEncoding String (任意) - 省略値は、ISO-8859-1 です。backgroundThrottling Boolean (任意) - ページがバックグラウンドになったとき、アニメーションやタイマーを抑制するかどうか。 これは Page Visibility API にも影響を与えます。 省略値は true です。offscreen Boolean (任意) - ブラウザウィンドウでオフスクリーンレンダリングを有効にするかどうか。 省略値は false 。 詳細については、オフスクリーンレンダリングのチュートリアル を参照してください。contextIsolation Boolean (任意) - Electron APIと指定された preload スクリプトを別々のJavaScriptコンテキストで実行するかどうか。 省略値は true です。 preload スクリプトが実行されるコンテキストでは、専用の document および window グローバルと、独自の JavaScript ビルドインのセット (Array, Object, JSON など) にのみアクセスできます。これらすべてはロードされたコンテンツからは見えません。 Electron API は preload スクリプトでのみ利用可能で、読み込まれたページでは利用できません。 このオプションは、信頼できない可能性のあるリモートコンテンツをロードする際に使用します。ロードされたコンテンツが preload スクリプトや使用する Electron API を改ざんできないようにするためです。 このオプションは、Chrome のコンテンツスクリプト のものと同じ技術を使用しています。 Console タブの一番上のコンボボックスの中にある 'Electron Isolated Context' という項目を選択することによって、開発者ツールでこのコンテキストにアクセスできます。nativeWindowOpen Boolean (任意) - ネイティブの window.open() を使用するかどうか。 省略値は true です。 子ウインドウは、nodeIntegrationInSubFrames が true でなければ node integration は無効化されます。webviewTag Boolean (任意) - <webview> タグ を有効にするかどうか。 省略値は false 。 注: <webview> に設定された preload スクリプトは、実行時にNode統合が有効になるので、潜在的に悪意のある preload スクリプトを含む <webview> タグをリモート/信頼できないコンテンツに作成させないようにする必要があります。 preload スクリプトを除去したり、検証したり、<webview> の初期設定を変更したりするために、webContents の will-attach-webview イベントを使うことができます。additionalArguments String - このアプリケーションのレンダラープロセスで process.argv に追加される文字列のリスト。 小規模なデータをレンダラープロセスのプリロードスクリプトに渡すのに便利です。safeDialogs Boolean (任意) - ブラウザによる連続ダイアログ保護を有効にするかどうか。 省略値は false です。safeDialogsMessage String (任意) - 連続したダイアログからの保護が機能したときに表示されるメッセージ。 定義されていなければデフォルトメッセージが使われますが、現在のデフォルトメッセージは英語であり、ローカライズされていないことに注意してください。disableDialogs Boolean (任意) - ダイアログを完全に無効化するかどうか。 safeDialogs を上書きします。 省略値は false です。navigateOnDragDrop Boolean (任意) - ファイルやリンクをページにドラッグ & ドロップした際にナビゲーションするかどうか。 省略値は false です。autoplayPolicy String (任意) - ウインドウ内のコンテンツに適用される自動再生ポリシーで、no-user-gesture-required、user-gesture-required、document-user-activation-required にできます。 省略値は no-user-gesture-required です。disableHtmlFullscreenWindowResize Boolean (任意) - HTML フルスクリーンになった時にウィンドウのサイズ変更を禁止するかどうか。 省略値は false です。accessibleTitle String (任意) - スクリーンリーダーなどのアクセシビリティツールにのみ提供される代替タイトル文字列。 この文字列はユーザに直接表示されません。spellcheck Boolean (任意) - 組み込みスペルチェックを有効にするかどうか。 省略値は true です。enableWebSQL Boolean (任意) - WebSQL API を有効にするかどうか。 省略値は true です。v8CacheOptions String (任意) - blink が使用する v8 コードキャッシュポリシーを強制します。 以下は取りうる値です。none - コードキャッシュ無効化code - ヒューリスティックベースのコードキャッシュbypassHeatCheck - ヒューリスティックのコードキャッシュをバイパスしつつ遅延コンパイルbypassHeatCheckAndEagerCompile - 上と同じにしつつ先行コンパイルします。 既定のポリシーは code です。enablePreferredSizeMode Boolean (任意) - 優先サイズモードを有効にするかどうか。 優先サイズとは、document のレイアウトをスクロール無しで格納するにあたって必要な最小サイズのことです。 これを有効にすると、優先サイズが変更されたときに WebContentsでpreferred-size-changedイベントが発生します。 省略値は false です。titleBarOverlay Object | Boolean (任意) - フレームレスウインドウを macOS の win.setWindowButtonVisibility(true) と組み合わせて使用している場合や、titleBarStyle を使用して標準ウインドウコントロール (macOS では \"信号機ボタン\") が表示されている場合、このプロパティはウインドウコントロールオーバーレイで JavaScript API と CSS 環境変数 を有効にします。 true を指定すると、オーバーレイはデフォルトのシステムカラーになります。 省略値は false です。color String (任意) Windows - 有効化されたウインドウコントロールオーバーレイの CSS の色。 既定値はシステムカラーです。symbolColor String (任意) Windows - 有効化されたウインドウコントロールオーバーレイ内の記号の CSS の色。 既定値はシステムカラーです。minWidth/maxWidth/minHeight/maxHeight で最小もしくは最大のウインドウサイズを設定するのは、ユーザを束縛するだけです。 サイズ制約に関係しないサイズを setBounds/setSize や BrowserWindow のコンストラクタに渡すことは差し支えありません。
type オプションに設定できる値と動作は、プラットフォーム依存です。 以下は取りうる値です。
desktop、dock、toolbar、splash、notification です。desktop、textured です。textured タイプは、メタルのグラデーションの外観 (NSTexturedBackgroundWindowMask) を追加します。desktop タイプは、ウインドウをデスクトップのバックグラウンドウインドウのレベル (kCGDesktopWindowLevel - 1) に配置します。 デスクトップウインドウはフォーカス、キーボードやマウスイベントを受け付けようとしないことに注意してください。しかしながら、globalShortcut を使って、かろうじて入力を受け付けることはできます。toolbar です。new BrowserWindow で作成されたオブジェクトでは以下のイベントが発生します。
注: いくつかのイベントは特定のオペレーティングシステムでのみ利用可能で、そのように注記がつけられています。
\n戻り値：
\nevent Eventtitle StringexplicitSet Booleanドキュメントのタイトルが変更されたときに発生します。event.preventDefault() を呼び出すことで、ネイティブウインドウのタイトルが変更されるのをキャンセルできます。 タイトルがファイルの URL から合成された場合、explicitSet は false です。
戻り値：
\nevent Eventウインドウがクローズされようとするときに発生します。 これは、DOMの beforeunload と unload イベントの前に発生します。 event.preventDefault() を呼び出すことで、クローズがキャンセルされます。
通常、ウインドウをクローズさせる必要があるかどうかを判断するために、beforeunload ハンドラーを使用したいと思うでしょうが、これは、ウインドウがリロードされるときにも呼び出されます。 Electronでは、undefined 以外の値を返却すれば、クローズをキャンセルします。 以下がその例です。
window.onbeforeunload = (e) => {\n console.log('I do not want to be closed')\n\n // メッセージボックスがユーザに表示される通常のブラウザーとは違って、\n // 無効でない値を返却すれば、何も表示せずにクローズをキャンセルします。\n // アプリケーションがクローズするのをユーザに確認させるには、\n // ダイアログAPIを使用することを推奨します。\n e.returnValue = false // `return false` と同じですが、非推奨\n}\n注: window.onbeforeunload = handler と window.addEventListener('beforeunload', handler) の動作には、微妙な違いがあります。 値のみを返すのではなく、常に明示的に event.returnValue を設定するようにすることを推奨します。後者の方がElectron内でより一貫性のある動作をします。
ウインドウが閉じられたときに発生します。 このイベントを受け取った後は、ウインドウへの参照を削除し、以降そのウインドウを使用しないようにしてください。
\n強制的なシャットダウン、マシン再起動またはセッションのログオフによってウインドウセッションが終了されようとしたときに発生します。
\nWebページが応答しなくなるときに発生します。
\n応答しないWebページが再び応答するようになるときに発生します。
\nウインドウがフォーカスを失うときに発生します。
\nウインドウがフォーカスを得るときに発生します。
\nウインドウが表示されるときに発生します。
\nウインドウが非表示になるときに発生します。
\nWebページが (まだ表示されていないが) レンダリングされ、チラつくことなくウインドウが表示できるときに発生します。
\nこのイベントを使用すると、show が false でもレンダラーが \"見えている\" と見なされ、描画されることに注意してください。 paintWhenInitiallyHidden: false を使用すると、このイベントは発生しません。
ウィンドウが最大化されるときに発生します。
\nウインドウが最大化状態から抜けるときに発生します。
\nウィンドウが最小化されるときに発生します。
\nウインドウが最小化状態から復元されたときに発生します。
\n戻り値：
\nevent EventnewBounds Rectangle - ウインドウがリサイズされようとしているサイズ。details Objectedge (String) - サイズ変更のためにドラッグされているウインドウの縁。 bottom、left、right、top-left、top-right、bottom-left、bottom-right のいずれかになります。ウィンドウがリサイズされる前に発生します。 event.preventDefault()を呼び出すことで、ウィンドウがリサイズされるのを阻止できます。
このイベントは、ウィンドウが手動でリサイズされようとしているときにしか発生しません。 ウィンドウを、setBoundsやsetSize でリサイズする時には、このイベントは発生しません。
edge オプションに設定できる値と動作は、プラットフォーム依存です。 以下は取りうる値です。
bottom、top、left、right、top-left、top-right、bottom-left、bottom-right です。bottom、right です。bottom は垂直方向のサイズ変更の表現に使用されます。right は水平方向のサイズ変更の表現に使用されます。ウインドウがリサイズされた後に発生します。
\nウインドウがリサイズされるときに一度発生します。
\nこれは、通常、ウィンドウが手動でリサイズされようとしているときにしか発生しません。 macOS の場合 setBounds/setSize でウィンドウのサイズを変更し、 animate パラメーターを true に設定すると、サイズ変更が完了したときにも、このイベントが発生します。
戻り値：
\nevent EventnewBounds Rectangle - ウインドウが移動されようとしている位置。ウィンドウが移動される前に発生します。 Windows では、 event.preventDefault() を呼び出すことで、ウィンドウが移動されるのを阻止できます。
このイベントは、ウィンドウが手動でリサイズされようとしているときにしか発生しません。 ウィンドウを、setBoundsやsetSize でリサイズする時には、このイベントは発生しません。
ウインドウが新しい位置に移動されているときに発生します。
\nウインドウが新しい位置に移動されるときに一回だけ、発生します。
\n注: macOSでは、このイベントは move のエイリアスです。
ウインドウがフルスクリーン状態に入るときに発生します。
\nウインドウがフルスクリーン状態を抜けるときに発生します。
\nウインドウがHTML APIによってフルスクリーン状態に入るときに発生します。
\nウインドウがHTML APIによってフルスクリーン状態を抜けるときに発生します。
\n戻り値：
\nevent EventisAlwaysOnTop Booleanウインドウが常に他のウインドウの手前に表示されるように設定またはそれが解除されたときに発生します。
\n戻り値：
\nevent Eventcommand Stringアプリコマンド が呼び出されるときに発生します。 これらは、Windowsで幾つかのマウスに組み込まれている \"Back\" ボタンだけでなく、一般的にキーボードのメディアキーやブラウザコマンドとも関連付けられています。
\nコマンドは小文字にされ、アンダースコアはハイフンに置き換えられ、APPCOMMAND_プレフィックスは外されます。 例えば、APPCOMMAND_BROWSER_BACKWARD は、browser-backward として送信されます。
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.on('app-command', (e, cmd) => {\n // ユーザーがマウスで戻るボタンを押下したときにナビゲートする\n if (cmd === 'browser-backward' && win.webContents.canGoBack()) {\n win.webContents.goBack()\n }\n})\nLinux 上では以下のアプリコマンドが明示的にサポートされます。
\nbrowser-backwardbrowser-forwardスクロールホイールイベントフェーズが開始されたときに発生します。
\nスクロールホイールイベントフェーズが終了したときに発生します。
\nスクロールイベントフェーズが要素の端に達したことを検出したときに発生します。
\n戻り値：
\nevent Eventdirection String3 本指でのスワイプ時に発火されます。 方向は up、right、down、left のいずれかになります。
このイベントは、スワイプで画面の内容が移動しない、古い macOS スタイルのトラックパッドスワイプを元にしています。 ほとんどの macOS トラックパッドはもうこの類のスワイプを許可していないため、正常にイベントを発生させるためには システム環境設定 > トラックパッド > その他のジェスチャ の 'ページ間をスワイプ' 設定を '2本指または3本指でスワイプ' にする必要があります。
戻り値：
\nevent Eventrotation Floatトラックパッドの回転ジェスチャで発生します。 回転ジェスチャーが終了するまで継続的に発生します。 各イベントの rotation 値は、最後の発生から回転した角度です。 回転ジェスチャで最後に発行されたイベントは、常に 0 の値になります。 反時計回りの回転値は正であり、時計回りの回転値は負です。
ウインドウがシートを開くときに発生します。
\nウインドウがシートを閉じたときに発生します。
\nネイティブの新規タブボタンがクリックされるときに発生します。
\n戻り値：
\nevent Eventpoint Point - コンテキストメニューがトリガーされた画面の座標。システムコンテキストメニューがウィンドウ上でトリガーされたときに発生します。 通常ユーザーがウィンドウのクライアントエリア以外を右クリックしたときにトリガーされます。 これは、フレームレスウィンドウで-webkit-app-region: dragと宣言したウィンドウタイトルバーまたは任意の領域です。
event.preventDefault() を呼ぶと、そのメニューは表示されなくなります。
BrowserWindow クラスには、次の静的メソッドがあります。
BrowserWindow.getAllWindows()戻り値 BrowserWindow[] - 開かれたすべてのブラウザウィンドウの配列。
BrowserWindow.getFocusedWindow()戻り値 BrowserWindow | null - このアプリケーションでフォーカスされたウインドウ。それ以外は、null を返します。
BrowserWindow.fromWebContents(webContents)webContents WebContents戻り値 BrowserWindow | null - 指定された webContents を保持しているウインドウ。ウインドウが保持していないコンテンツの場合は null です。
BrowserWindow.fromBrowserView(browserView)browserView BrowserView戻り値 BrowserWindow - 指定された browserView を所有するウインドウ。 指定されたビューがどのウィンドウにもアタッチされていない場合は、 nullを返します。
BrowserWindow.fromId(id)id Integer戻り値 BrowserWindow | null - 指定された id のウインドウ。
new BrowserWindow で作成されたオブジェクトは、以下のプロパティを持っています。
const { BrowserWindow } = require('electron')\n// この例では、 `win` がインスタンス\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('https://github.com')\nwin.webContents 読み出し専用このウィンドウが所有する WebContents オブジェクト。 すべての Web ページ関連のイベントおよび操作は、これを介して行われます。
webContents ドキュメント でメソッドやイベントについて参照してください。
win.id 読み出し専用Integer 型のプロパティです。そのウインドウの一意な ID を表します。 各 ID は、この Electron アプリケーション全体のすべての BrowserWindow インスタンス間で一意です。
win.autoHideMenuBarウインドウがユーザーによって手動で最小化できるかどうかを決定する Boolean 型のプロパティ。 一度設定されると、メニューバーはユーザが単独で Alt キーを押したときのみに表示されます。
メニューバーが既に表示されている場合、このプロパティを true にセットしてもすぐに非表示にはなりません。
win.simpleFullScreenBoolean 型のプロパティです。これは、ウィンドウがシンプルな (Lion 以前の) フルスクリーンモードかどうかを決定します。
win.fullScreenBoolean 型のプロパティです。これは、ウィンドウがフルスクリーンモードかどうかを決定します。
win.focusable Windows macOSBoolean 型のプロパティです。ウィンドウにフォーカスできるどうかを決定します。
win.visibleOnAllWorkspacesBoolean 型のプロパティです。これは、ウィンドウがすべてのワークスペースで表示されるどうかを決定します。
注: Windows の場合、常に false を返します。
\nwin.shadowBoolean 型のプロパティです。ウィンドウに影があるかどうかを決定します。
win.menuBarVisible Windows LinuxBoolean 型のプロパティです。メニューバーが表示されるかどうかを決定します。
注: メニューバーが自動的に非表示にされている場合でも、ユーザが単に Alt キーを押下すれば、依然としてメニューバーを表示させることができます。
win.kioskBoolean 型のプロパティです。これは、ウィンドウがキオスクモードかどうかを決定します。
win.documentEdited macOSBoolean 型のプロパティです。ウィンドウのドキュメントが編集されたかどうかを決定します。
true にすると、タイトルバーのアイコンが灰色になります。
win.representedFilename macOSString 型のプロパティです。ウィンドウが表すファイルのパス名を決定し、そのファイルのアイコンがウィンドウのタイトルバーに表示されます。
win.titleString 型のプロパティです。ネイティブウインドウのタイトルを決定します。
注: ウェブページのタイトルとネイティブウインドウのタイトルは異なる可能性があります。
\nwin.minimizableBoolean 型のプロパティです。ウインドウがユーザーによって手動で最小化できるかどうかを決定します。
Linux ではセッターは何もしませんが、ゲッターは true を返します。
win.maximizableBoolean 型のプロパティです。ウインドウがユーザーによって手動で最大化できるかどうかを決定します。
Linux ではセッターは何もしませんが、ゲッターは true を返します。
win.fullScreenableBoolean 型のプロパティです。ウインドウを最大化/ズームするウインドウボタンでフルスクリーンモードや最大化をトグル切り替えできるかどうかを決定します。
win.resizableBoolean 型のプロパティです。ウインドウがユーザーによって手動でサイズ変更できるかどうかを決定します。
win.closableBoolean 型のプロパティです。ウインドウがユーザーによって手動で閉じることができるかどうかを決定します。
Linux ではセッターは何もしませんが、ゲッターは true を返します。
win.movableBoolean 型のプロパティです。ウインドウがユーザーによって移動できるかどうかを決定します。
Linux ではセッターは何もしませんが、ゲッターは true を返します。
win.excludedFromShownWindowsMenu macOSウィンドウがアプリケーションの Windows メニューから除外されるかどうかを決定する Boolean プロパティ。 省略値は false です。
const win = new BrowserWindow({ height: 600, width: 600 })\n\nconst template = [\n {\n role: 'windowmenu'\n }\n]\n\nwin.excludedFromShownWindowsMenu = true\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nwin.accessibleTitleスクリーンリーダーなどのアクセシビリティツールにのみ提供される代替タイトルを定義する String 型のプロパティ。 この文字列はユーザに直接表示されません。
new BrowserWindow で作成されたオブジェクトは、次のインスタンスメソッドを持っています。
注: いくつかのメソッドは特定のオペレーティングシステムでのみ利用可能で、そのように注記がつけられています。
\nwin.destroy()強制的にウインドウを閉じます。unload と beforeunload イベントはWebページで発生しません。また、close イベントもこのウインドウで発生しません。しかし、closed イベントが発生することは保証されます。
win.close()ウインドウを閉じようとします。 これは、ユーザーが手動でウィンドウの閉じるボタンをクリックした場合と同じ効果があります。 ただし、 Web ページはウィンドウが閉じようとするのををキャンセルすることができます。 close イベント を参照してください。
\nwin.focus()ウインドウにフォーカスを当てます。
\nwin.blur()ウインドウからフォーカスを外します。
\nwin.isFocused()戻り値 Boolean - ウインドウがフォーカスされているかどうか。
win.isDestroyed()戻り値 Boolean - ウインドウが破棄されているかどうか。
win.show()表示し、ウインドウにフォーカスを当てます。
\nwin.showInactive()ウインドウを表示しますが、フォーカスを当てません。
\nwin.hide()ウインドウを非表示にします。
\nwin.isVisible()戻り値 Boolean - ウインドウがユーザーに表示されているかどうか。
win.isModal()戻り値 Boolean - 現在のウインドウがモーダルウインドウかどうか。
win.maximize()ウィンドウを最大化します。 ウインドウがまだ表示されていない場合、併せてウインドウを表示 (ただし、フォーカスは当たりません) します。
\nwin.unmaximize()ウインドウの最大化を解除します。
\nwin.isMaximized()戻り値 Boolean - ウインドウが最大化されているかどうか。
win.minimize()ウィンドウを最小化します。 一部のプラットフォームでは、最小化されたウィンドウが Dock に表示されます。
\nwin.restore()ウインドウを最小化された状態からその前の状態に戻します。
\nwin.isMinimized()戻り値 Boolean - ウインドウが最小化されているかどうか。
win.setFullScreen(flag)flag Booleanウインドウをフルスクリーンモードにするかどうかを設定します。
\nwin.isFullScreen()戻り値 Boolean - ウインドウがフルスクリーンモードであるかどうか。
win.setSimpleFullScreen(flag) macOSflag Boolean簡易フルスクリーンモードに設定したり、解除したりします。
\nmacOS Lion (10.7) より前のバージョンで見られる簡易フルスクリーンモードはネイティブのフルスクリーン動作をエミュレートします。
\nwin.isSimpleFullScreen() macOS戻り値 Boolean - ウインドウが簡易 (Lionより前) フルスクリーンモードであるかどうか。
win.isNormal()Returns Boolean - ウィンドウが通常の状態 (最大化されていない、最小化されていない、フルスクリーンモードではない) かどうか。
win.setAspectRatio(aspectRatio[, extraSize])aspectRatio Float - コンテンツビューの一部を維持するためのアスペクト比。extraSize Size (任意) macOS - アスペクト比を維持している間は含まれない余分のサイズ。これはウインドウのアスペクト比を維持します。 ピクセルで指定した追加のサイズによって、開発者は、アスペクト比の計算に含まれないスペースを確保することができます。 このAPIはウインドウのサイズとそのコンテンツのサイズの差異も考慮しています。
\nHDビデオプレーヤーと関連したコントロールを持つ通常のウインドウを考えてみましょう。 ひょっとすると、左端に15ピクセルのコントロール、右端に25ピクセルのコントロール、プレーヤーの下部に50ピクセルのコントロールがあるかもしれません。 プレーヤー内で 16:9 アスペクト比 (HD @1920x1280 の標準的なアスペクト比) を維持するためには、この関数を 16/9 と { width: 40, height: 50 } の引数で呼び出します。 2番目の引数は、追加の幅と高さがコンテンツビューの中に収まるかを気にしません。それらはただ存在しているだけです。 全体のコンテンツビュー内にある余分な幅と高さの領域を単純に足し合わせます。
\nwin.setSize などの API でプログラム上からウインドウをサイズ変更した場合、アスペクト比は維持されません。
win.setBackgroundColor(backgroundColor)backgroundColor String - #66CD00 や #FFF や #80FFFFFF (transparent を true にすればアルファ値をサポートします) のような16進数の値でのウインドウの背景色。 省略値は #FFF (白) です。ウィンドウの背景色を設定します。 backgroundColor 設定 を参照してください。
win.previewFile(path[, displayName]) macOSpath String - Quick Lookでプレビューするファイルへの絶対パス。 ここで、Quick Lookはパスのファイル名とファイル拡張子をファイルを開くためのコンテンツタイプを決定するのに使用する点が重要です。displayName String (任意) - Quick Lookのモーダルビューに表示するファイルの名前。 これは純粋に見た目だけのもので、ファイルのコンテンツタイプには影響しません。 省略値は、path です。指定したパスでファイルをプレビューするために、Quick Look を使用します。
\nwin.closeFilePreview() macOS現在開いている Quick Look のパネルを閉じます。
\nwin.setBounds(bounds[, animate])bounds Partial<Rectangle>animate Boolean (任意) macOS指定した境界までウインドウのサイズを変更して移動します。 指定されていないプロパティは、既定で現在の値になります。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\n// bounds のプロパティをすべて設定\nwin.setBounds({ x: 440, y: 225, width: 800, height: 600 })\n\n// bounds のプロパティをひとつ設定\nwin.setBounds({ width: 100 })\n\n// { x: 440, y: 225, width: 100, height: 600 }\nconsole.log(win.getBounds())\nwin.getBounds()戻り値 Rectangle - ウインドウの bounds が Object になったもの。
win.getBackgroundColor()戻り値 String - ウインドウの背景色を取得します。 backgroundColor 設定 を参照してください。
win.setContentBounds(bounds[, animate])bounds Rectangleanimate Boolean (任意) macOS指定した境界までウインドウのクライアント領域 (例えば、Webページ) のサイズを変更して移動します。
\nwin.getContentBounds()戻り値 Rectangle - ウインドウの内部領域の bounds が Object になったもの。
win.getNormalBounds()Returns Rectangle - 通常状態におけるウィンドウ境界を含む領域。
注意: ウインドウの現在の状態: 最大化、最小化、または全画面表示に関係なく、この関数は常に通常状態のウインドウの位置とサイズを返します。 通常状態においては、getBounds と getNormalBounds は同じ Rectangle を返します。
win.setEnabled(enable)enable Booleanウインドウを無効にするか有効にします。
\nwin.isEnabled()戻り値 Boolean - そのウインドウが有効かどうか。
win.setSize(width, height[, animate])width Integerheight Integeranimate Boolean (任意) macOSウインドウのサイズを width と height に変更します。 width または height が最小サイズ制約の設定値より低い場合、ウィンドウはその最小サイズにスナップします。
win.getSize()戻り値 Integer[] - ウインドウの幅と高さを含みます。
win.setContentSize(width, height[, animate])width Integerheight Integeranimate Boolean (任意) macOSウインドウのクライアント領域 (例えば、Webページ) のサイズを width と height に変更します。
win.getContentSize()戻り値 Integer[] - ウインドウのクライアント領域の幅と高さを含みます。
win.setMinimumSize(width, height)width Integerheight Integerウインドウの最小サイズを width と height に設定します。
win.getMinimumSize()戻り値 Integer[] - ウインドウの最小の幅と高さを含みます。
win.setMaximumSize(width, height)width Integerheight Integerウインドウの最大サイズを width と height に設定します。
win.getMaximumSize()戻り値 Integer[] - ウインドウの最大の幅と高さを含みます。
win.setResizable(resizable)resizable Booleanウインドウがユーザによって手動でサイズ変更できるかどうかを設定します。
\nwin.isResizable()戻り値 Boolean - ウインドウがユーザによって手動でサイズ変更できるかどうか。
win.setMovable(movable) macOS Windowsmovable Booleanウインドウがユーザーによって手動で移動できるかどうかを設定します。 Linux では何もしません。
\nwin.isMovable() macOS Windows戻り値 Boolean - ウインドウがユーザーによって移動できるかどうか。
Linuxでは常に true を返します。
win.setMinimizable(minimizable) macOS Windowsminimizable Booleanウインドウがユーザーによって手動で最小化できるかどうかを設定します。 Linux では何もしません。
\nwin.isMinimizable() macOS Windows戻り値 Boolean - ウインドウがユーザによって手動で最小化できるかどうか。
Linuxでは常に true を返します。
win.setMaximizable(maximizable) macOS Windowsmaximizable Booleanウインドウがユーザーによって手動で最大化できるかどうかを設定します。 Linux では何もしません。
\nwin.isMaximizable() macOS Windows戻り値 Boolean - ウインドウがユーザーによって手動で最大化できるかどうか。
Linuxでは常に true を返します。
win.setFullScreenable(fullscreenable)fullscreenable Booleanウインドウの最大化/ズームボタンでフルスクリーンモードに切り替えるか、ウインドウを最大化するかを設定します。
\nwin.isFullScreenable()戻り値 Boolean - ウインドウの最大化/ズームボタンでフルスクリーンモードに切り替えるのか、それともウインドウを最大化するのか。
win.setClosable(closable) macOS Windowsclosable Booleanウインドウがユーザーによって手動で閉じられるかどうかを設定します。 Linux では何もしません。
\nwin.isClosable() macOS Windows戻り値 Boolean - ウインドウをユーザーが手動で閉じられるかどうか。
Linuxでは常に true を返します。
win.setAlwaysOnTop(flag[, level][, relativeLevel])flag Booleanlevel String (任意) macOS Windows - 値は、normal、floating、torn-off-menu、modal-panel、main-menu、status、pop-up-menu、screen-saver と dockflag が true の場合、省略値は floating です。 flag が false の場合、level は normal にリセットされます。 floating から status までに含まれているものにおいて、ウィンドウは macOS では Dock の下に、Windows ではタスクバーの下に配置されることをことに注意してください。 pop-up-menu 以降は、macOS では Dock の上に、Windows ではタスクバーの上に表示されます。 詳細については、macOS のドキュメント を参照してください。relativeLevel Integer (任意) macOS - このウインドウに設定する指定した level より上のレイヤーの数。 省略値は、0 です。 Apple社は、screen-saver より上に1以上のレベルを設定することを推奨していないことに注意してください。ウィンドウを常に他のウィンドウの上に表示するかどうかを設定します。 この設定を行った後でも、ウィンドウはまだ通常のものであり、フォーカスが当てられないツールボックスウィンドウではありません。
\nwin.isAlwaysOnTop()戻り値 Boolean - ウインドウが常に他のウインドウの上に表示されるかどうか。
win.moveAbove(mediaSourceId)mediaSourceId String - DesktopCapturerSource の ID の形式のウィンドウ ID。 例えば \"window:1869:0\" 。Z オーダーの意味で、ウィンドウをソースウィンドウの上に移動します。 mediaSourceId がウィンドウの ID でないか、ウィンドウが存在しない場合、このメソッドはエラーをスローします。
win.moveTop()フォーカスに関係なく上 (Z順序) にウィンドウを移動します。
\nwin.center()ウインドウを画面の中央に移動します。
\nwin.setPosition(x, y[, animate])x Integery Integeranimate Boolean (任意) macOSウインドウを x と y に移動します。
win.getPosition()戻り値 Integer[] - ウインドウの現在の位置を含みます。
win.setTitle(title)title Stringネイティブのウインドウのタイトルを title に変更します。
win.getTitle()戻り値 String - ネイティブのウインドウのタイトル。
注: Web ページのタイトルはネイティブのウインドウのタイトルとは異なる可能性があります。
\nwin.setSheetOffset(offsetY[, offsetX]) macOSoffsetY FloatoffsetX Float (optional)macOS においてシートを設置する位置を変更します。 既定では、シートはウィンドウフレームのすぐ下に設置されますが、 HTML で表示されたツールバーの下に表示することもできます。 以下がその例です。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nconst toolbarRect = document.getElementById('toolbar').getBoundingClientRect()\nwin.setSheetOffset(toolbarRect.height)\nwin.flashFrame(flag)flag Booleanユーザの注意を引きつけるためにウインドウの点滅を開始または停止します。
\nwin.setSkipTaskbar(skip)skip Booleanウインドウがタスクバーに表示されなくなります。
\nwin.setKiosk(flag)flag Booleanキオスクモードに入ったり出たりします。
\nwin.isKiosk()戻り値 Boolean - ウインドウがキオスクモードであるかどうか。
win.isTabletMode() Windows戻り値 Boolean - ウインドウが Windows 10 タブレットモードであるかどうか。
Windows 10 ユーザーは PC をタブレットとして使用できる ので、アプリはこのモードの際にタイトルバーを大きくしたり、タイトルバーのボタンを非表示にしたりと、タブレット用に UI を最適化できます。
\nこの API は、ウインドウがタブレットモードかどうかを返します。resize イベントでタブレットモードへの変更をリッスンすることもできます。
win.getMediaSourceId()戻り値 String - DesktopCapturerSource の ID の形式のウィンドウ ID。 例えば \"window:1324:0\" 。
より正確には、フォーマットは window:id:other_id です。ここでの id は、Windows では HWND、macOS では CGWindowID (uint64_t)、Linux では Window (unsigned long) です。 other_id は、同じトップレベルウィンドウ内のウェブコンテンツ (タブ) を識別するために使用されます。
win.getNativeWindowHandle()戻り値 Buffer - ウインドウのプラットフォーム固有のハンドル。
ハンドルのネイティブな型は、Windowsでは HWND、macOSでは NSView*、Linuxでは Window (unsigned long) です。
win.hookWindowMessage(message, callback) Windowsmessage Integercallback FunctionwParam any - WndProc に指定された wParamlParam any - WndProc に指定された lParamウィンドウメッセージをフックします。 メッセージが WndProc で受信されると、 callback が呼び出されます。
win.isWindowMessageHooked(message) Windowsmessage Integer戻り値 Boolean - メッセージがフックされているかどうかによって、true または false 。
win.unhookWindowMessage(message) Windowsmessage Integerウインドウメッセージのフックを解除します。
\nwin.unhookAllWindowMessages() Windowsすべてのウインドウメッセージのフックを解除します。
\nwin.setRepresentedFilename(filename) macOSfilename Stringウインドウが表すファイルのパス名を設定します。ファイルのアイコンがウインドウのタイトルバーに表示されます。
\nwin.getRepresentedFilename() macOS戻り値 String - ウインドウが表すファイルのパス名。
win.setDocumentEdited(edited) macOSedited Booleanウインドウのドキュメントが編集されたかどうかを指定します。true に設定すると、タイトルバーのアイコンがグレーになります。
win.isDocumentEdited() macOS戻り値 Boolean - ウインドウのドキュメントが編集されたかどうか。
win.focusOnWebView()win.blurWebView()win.capturePage([rect])rect Rectangle (任意) - キャプチャする範囲戻り値 Promise<NativeImage> - NativeImage を解決します
rect 内のページのスナップショットをキャプチャします。 rect を省略すると、表示されているページ全体をキャプチャします。 ページが表示されない場合、 rect が空である可能性があります。
win.loadURL(url[, options])url Stringoptions Object (任意)httpReferrer (String | Referrer) (任意) - HTTP リファラの URL。userAgent String (任意) - リクエスト元のユーザーエージェント。extraHeaders String (任意) - \"\\n\" で区切られた追加のヘッダーpostData (UploadRawData | UploadFile)baseURLForDataURL String (任意) - データ URL によってロードされたファイルの (最後のパス区切り文字を含む) ベース URL。 これは指定された url がデータ URL で、他のファイルをロードする必要がある場合のみ必要です。戻り値 Promise<void> - ページ読み込みが完了した時 (did-finish-load を参照) に解決され、ページの読み込みに失敗した時 (did-fail-load を参照) に拒否される Promise。
webContents.loadURL(url[, options]) と同じです。
url は、リモートアドレス (例えば、http://) または file:// プロトコルを使ってローカルのHTMLファイルのパスにすることができます。
ファイルのURLが正しく構成されているようにするため、Nodeの url.format メソッドを使用することを推奨します。
const url = require('url').format({\n protocol: 'file',\n slashes: true,\n pathname: require('path').join(__dirname, 'index.html')\n})\n\nwin.loadURL(url)\n次のようにすることによって、URLエンコードされたデータで POST リクエストを使用してURLをロードすることができます。
win.loadURL('http://localhost:8000/post', {\n postData: [{\n type: 'rawData',\n bytes: Buffer.from('hello=world')\n }],\n extraHeaders: 'Content-Type: application/x-www-form-urlencoded'\n})\nwin.loadFile(filePath[, options])filePath Stringoptions Object (任意)search Record<String, String> (任意) - url.format() に渡されます。search String (任意) - url.format() に渡されます。hash String (任意) - url.format() に渡されます。戻り値 Promise<void> - ページ読み込みが完了した時 (did-finish-load を参照) に解決され、ページの読み込みに失敗した時 (did-fail-load を参照) に拒否される Promise。
webContents.loadFile と同じく、 filePath はアプリケーションのルートからの HTML ファイルへの相対パスである必要があります。 詳しくは、 webContents ドキュメントを参照してください。
win.reload()webContents.reload と同じです。
win.setMenu(menu) Linux Windowsmenu Menu | nullmenu をウインドウのメニューバーとして設定します。
win.removeMenu() Linux Windowsウインドウのメニューバーを消去します。
\nwin.setProgressBar(progress[, options])progress Doubleoptions Object (任意)mode String Windows - プログレスバーのモード。 none 、 normal 、 indeterminate 、 error 、 paused のいずれかが使用できます。プログレスバーの進捗を設定します。 有効な範囲は [0, 1.0] です。
\n進捗 < 0 の場合、プログレスバーは削除されます。進捗 > 1 の場合、不確定モードに変更します。
\nLinuxプラットフォームでは、Unityデスクトップ環境のみがサポートされ、package.json の desktopName フィールドに *.desktop ファイル名を指定する必要があります。 既定では、{app.name}.desktop であるとみなされます。
Windowsでは、モードを渡すことができます。 有効な値は、none、normal、indeterminate、error と paused です。 モードを設定せずに (ただし、有効範囲内の値で) setProgressBar を呼び出した場合、normal とみなされます。
win.setOverlayIcon(overlay, description) Windowsoverlay NativeImage | null - タスクバーアイコンの右下隅に表示されるアイコン。 この引数が null の場合、オーバーレイは消去されます。description String - アクセシビリティスクリーンリーダーに提供される説明現在のタスクバーアイコンの上に、通常、何らかのアプリケーションステータスを伝えたり、ユーザーに控えめに通知したりするのに使われる16 x 16ピクセルのオーバレイを設定します。
\nwin.setHasShadow(hasShadow)hasShadow Booleanウインドウに影を付けるべきかどうかを設定します。
\nwin.hasShadow()戻り値 Boolean - ウインドウに影を表示させているかどうか。
win.setOpacity(opacity) Windows macOSopacity Number - 0.0 (完全に透明) と 1.0 (完全に不透明) の間ウィンドウの不透明度を設定します。 Linux では何もしません。 範囲外の値は [0, 1] に収められます。
\nwin.getOpacity()戻り値 Number - 0.0 (完全に透明) と 1.0 (完全に不透明) の間。 Linuxでは常に 1 を返します。
win.setShape(rects) Windows Linux 実験的rects Rectangle[] - ウィンドウの形。 空のリストを渡すと、ウィンドウが四角形に戻ります。ウィンドウの形を設定すると、システム内で描画とユーザ操作が許可されているウィンドウ内の領域が決まります。 与えられた領域の外側のピクセルでは描画されず、マウスイベントも登録されません。 領域外のマウスイベントはそのウィンドウでは受信されませんが、ウィンドウの後ろにあるものにそのイベントがフォールスルーします。
\nwin.setThumbarButtons(buttons) Windowsbuttons ThumbarButton[]戻り値 Boolean - ボタンを追加するのに成功したかどうか
タスクバーボタンレイアウトのウインドウのサムネイルイメージに指定されたボタンのセットと一緒にサムネイルツールバーを追加します。 返却される Boolean オブジェクトは、サムネイルを追加するのに成功したかどうかを示します。
限られた空間のため、サムネイルツールバーのボタン数は、7以下にしてください。 一度、サムネイルツールバーをセットアップすると、プラットフォームの制約のため、ツールバーを削除することはできません。 しかしながら、ボタンを取り除くためにAPIを空の配列で呼び出すことはできます。
\nbuttons は、Button オブジェクトの配列です。
Button Objecticon NativeImage - サムネイルツールバーで表示されるアイコン。click Functiontooltip String (任意) - ボタンのツールチップのテキスト。flags String - ボタンの特定の状態や動作を制御します。 省略値は、['enabled'] です。flags は、以下の String を含めることができる配列です。
enabled - ボタンはアクティブで、ユーザーが使用できます。disabled - そのボタンは無効化されます。 存在しますが、ユーザ操作に応答しないことを示す視覚的な状態です。dismissonclick - そのボタンをクリックすると、サムネイルウインドウがすぐに閉じます。nobackground - そのボタンの縁を描画しません。画像にのみ使用してください。hidden - そのボタンはユーザに表示されません。noninteractive - そのボタンは有効ですが、反応せず、押されたボタンの状態も描画されません。 この値は、例えば通知内で使用するボタンに使用されます。win.setThumbnailClip(region) Windowsregion Rectangle - ウインドウの領域タスクバーのウインドウの上でホバリングするときに表示されるサムネイルイメージとして表示するウインドウの領域を設定します。 空の領域: { x: 0, y: 0, width: 0, height: 0 } を指定することで、サムネイルをウインドウ全体にリセットすることができます。
win.setThumbnailToolTip(toolTip) WindowstoolTip Stringタスクバーのウインドウサムネイルでホバリングするときに表示されるツールチップを設定します。
\nwin.setAppDetails(options) Windowsoptions ObjectappId String (任意) - ウインドウのアプリユーザーモデルID。 設定されないと、他のオプションは無効です。appIconPath String (任意) - ウインドウの再起動アイコン。appIconIndex Integer (任意) - appIconPath でのアイコンのインデックス。 appIconPath が設定されていない場合は無視されます。 省略値は 0 です。relaunchCommand String (任意) - ウインドウの再起動コマンド。relaunchDisplayName String (任意) - ウインドウの再起動表示名。ウインドウのタスクバーボタンのプロパティを設定します。
\n注: relaunchCommand と relaunchDisplayName は一緒に設定する必要があります。 いずれかが設定されていない場合、どちらも使用されません。
win.showDefinitionForSelection() macOSwebContents.showDefinitionForSelection() と同じです。
win.setIcon(icon) Windows Linuxicon NativeImage | Stringウインドウのアイコンを変更します。
\nwin.setWindowButtonVisibility(visible) macOSvisible Booleanウインドウの信号ボタンを表示するかどうかを設定します。
\nwin.setAutoHideMenuBar(hide)hide Booleanウィンドウのメニューバーを自動的に非表示にするかどうかを設定します。 一度設定されると、メニューバーはユーザが単独で Alt キーを押したときのみに表示されます。
メニューバーが既に表示されている場合、setAutoHideMenuBar(true) を呼び出してもすぐに非表示にはなりません。
win.isMenuBarAutoHide()戻り値 Boolean - メニューバーを自動的に非表示にするかどうか。
win.setMenuBarVisibility(visible) Windows Linuxvisible Booleanメニューバーを表示するかどうかを設定します。 メニューバーが自動的に非表示にされている場合でも、ユーザが単に Alt キーを押下すれば、依然としてメニューバーを表示させることができます。
win.isMenuBarVisible()戻り値 Boolean - メニューバーを表示しているかどうか。
win.setVisibleOnAllWorkspaces(visible[, options])visible Booleanoptions Object (任意)visibleOnFullScreen Boolean (任意) macOS - ウインドウをフルスクリーンウィンドウの上で表示するかどうかを設定します。skipTransformProcessType Boolean (任意) macOS - setVisibleOnAllWorkspaces を呼ぶと、デフォルトでは UIElementApplication と ForegroundApplication の間でプロセスタイプが変換され、正しい動作を保証します。 しかし、これでは呼び出されるたびに短時間だけウインドウが非表示になり、Dock も非表示になってしまいます。 ウインドウが既に UIElementApplication 型である場合、skipTransformProcessType に true を渡すことでこの変換をバイパスできます。ウインドウをすべてのワークスペースで表示させるかどうかを設定します。
\n注: このAPIはWindowsでは何もしません。
\nwin.isVisibleOnAllWorkspaces()戻り値 Boolean - ウインドウがすべてのワークスペースで表示されているかどうか。
注: このAPIはWindowsの場合、常にfalseを返します。
\nwin.setIgnoreMouseEvents(ignore[, options])ignore Booleanoptions Object (任意)forward Boolean (任意) macOS Windows - true の場合、マウスの移動メッセージが Chromium に転送され、mouseleave のようなマウス関連のイベントが有効になります。 ignore がtrueのときだけ使用されます。 ignore がfalseの場合、この値に関わらず、転送は常に無効です。ウインドウがすべてのマウスイベントを無視するようにします。
\nこのウインドウで発生するすべてのマウスイベントは、このウインドウの下にあるウインドウに渡されますが、このウインドウにフォーカスがある場合、依然としてキーボードイベントは受信されます。
\nwin.setContentProtection(enable) macOS Windowsenable Boolean他のアプリによってウインドウのコンテンツがキャプチャされるのを防止します。
\nmacOS では、NSWindow の共有タイプを NSWindowSharingNone に設定します。 Windows では、 SetWindowDisplayAffinity を WDA_EXCLUDEFROMCAPTURE で呼び出します。 Windows 10 バージョン 2004 以降からウインドウのキャプチャが完全に削除されましたが、古い Windows バージョンで WDA_MONITOR が適用された場合は黒いウィンドウをキャプチャするように動作します。
win.setFocusable(focusable) macOS Windowsfocusable Booleanウインドウにフォーカスできるかどうかを変更します。
\nmacOS ではウィンドウからフォーカスは除去されません。
\nwin.isFocusable() macOS Windowsウインドウにフォーカスできるかどうかを返します。
\nwin.setParentWindow(parent)parent BrowserWindow | null現在のウインドウの親ウインドウとして parent を設定します。null を渡すと、現在のウインドウをトップレベルウインドウにします。
win.getParentWindow()戻り値 BrowserWindow - 親ウインドウ。
win.getChildWindows()戻り値 BrowserWindow[] - すべての子ウインドウ。
win.setAutoHideCursor(autoHide) macOSautoHide Booleanタイプしているときにカーソルを非表示にするかどうかを制御します。
\nwin.selectPreviousTab() macOSネイティブのタブが有効で、ウインドウに他のタブがあるとき、一つ前のタブを選択します。
\nwin.selectNextTab() macOSネイティブのタブが有効で、ウインドウに他のタブがあるとき、次のタブを選択します。
\nwin.mergeAllWindows() macOSネイティブのタブが有効で複数の開いているウインドウがあるとき、すべてのウインドウを複数のタブで1つのウインドウにマージします。
\nwin.moveTabToNewWindow() macOSネイティブのタブが有効で現在のウインドウに複数のタブがあるとき、現在のタブを新しいウインドウに移動します。
\nwin.toggleTabBar() macOSネイティブのタブが有効で現在のウインドウにタブが1つだけしかないとき、タブバーを表示するかどうかを切り替えます。
\nwin.addTabbedWindow(browserWindow) macOSbrowserWindow BrowserWindowウインドウインスタンスのタブの後ろに、このウインドウのタブとしてウインドウを追加します。
\nwin.setVibrancy(type) macOStype String | null - appearance-based、light、dark、titlebar、selection、menu、popover、sidebar、medium-light、ultra-dark、header、sheet、window、hud、fullscreen-ui、tooltip、content、under-window または under-page にすることができます。 詳細については、macOSのドキュメント を参照してください。ブラウザウィンドウにバイブレンシーエフェクトを追加します。 null または空の文字列を渡すと、ウィンドウのバイブレンシーエフェクトを削除します。
注意として、appearance-based、light、dark、medium-light と ultra-dark は非推奨であり、macOS の今後のバージョンで削除されます。
win.setTrafficLightPosition(position) macOSposition Pointフレームレスウインドウにおける信号機ボタンのカスタム位置を設定します。
\nwin.getTrafficLightPosition() macOS戻り値 Point - フレームレスウインドウにおける現在の信号機ボタンの位置。
win.setTouchBar(touchBar) macOStouchBar TouchBar | null現在のウインドウのTouchBarレイアウトを設定します。 null または undefined を指定すると、TouchBarがクリアされます。 このメソッドはTouchBarがあって、macOS 10.12.1以上を実行しているマシンでのみ、有効です。
Note: TouchBar API は現在実験的な機能です。そのため、将来的には変更されたり削除されたりする可能性があります。
\nwin.setBrowserView(browserView) ExperimentalbrowserView BrowserView | null - browserView を win へアタッチします。 他の BrowserView がアタッチされている場合、それはこのウィンドウから削除されます。win.getBrowserView() 実験的戻り値 BrowserView | null - win にアタッチされた BrowserView。 アタッチされていない場合は null を返します。 複数の BrowserView がアタッチされている場合、エラーを送出します。
win.addBrowserView(browserView) 実験的browserView BrowserView複数の BrowserView をサポートする setBrowserView の置換 API。
\nwin.removeBrowserView(browserView) 実験的browserView BrowserViewwin.setTopBrowserView(browserView) 実験的browserView BrowserViewbrowserView を win にアタッチされた他の BrowserView の上へと持ち上げます。 browserView が win にアタッチされていない場合, エラーを送出します。
win.getBrowserViews() 実験的戻り値 BrowserView[] - addBrowserView または setBrowserView でアタッチされたすべての BrowserView の配列。
注: 現在のところ、BrowserView APIは実験的な機能であり、将来のElectronのリリースで変更されたり、削除されたりする可能性があります。
", "title": "BrowserWindow", "description": "ブラウザウィンドウを作成したり、制御したりします。" }, "/docs/api/browser-window-proxy": { "locale": "ja-JP", "slug": "browser-window-proxy", "href": "/docs/api/browser-window-proxy", "crowdinFileId": "256285", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-window-proxy.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n子ブラウザウィンドウを操作します。
\n
プロセス: レンダラー
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
BrowserWindowProxy オブジェクトは、window.open から返却され、子ウインドウの限定的な機能を提供します。
BrowserWindowProxy オブジェクトには、次のインスタンスメソッドがあります。
win.blur()子ウインドウからフォーカスを外します。
\nwin.close()unloadイベントを呼び出すことなく、子ウインドウを強制的に閉じます。
\nwin.eval(code)code String子ウインドウでコードを評価します。
\nwin.focus()子ウインドウにフォーカスします (ウインドウを前面に移動します)。
\nwin.print()子ウインドウで印刷ダイアログを呼び出します。
\nwin.postMessage(message, targetOrigin)message anytargetOrigin String特定のオリジンまたはオリジン未設定を意味する * で子ウインドウにメッセージを送信します。
これらのメソッドに加えて、子ウインドウには、プロパティがなく、1つのメソッドを持つ window.opener オブジェクトが実装されています。
BrowserWindowProxy オブジェクトには、次のインスタンスプロパティがあります。
win.closed子ウインドウが閉じた後にtrueが設定される Boolean 型のプロパティ。
カスタム Electron バイナリの作成にあたって Electron そのもの をビルドするには、以下のガイドラインに従ってください。 アプリのコードをビルド済み Electron バイナリにバンドルして頒布する場合は、アプリケーション頒布 のガイドを参照してください。
\n続行する前に、以下から各プラットフォームのビルド要件を確認してください。
\n\nElectron ビルドツール は、さまざまな設定やビルドターゲットを使ってソースから Electron をコンパイルするためのセットアップの多くを自動化します。 手動で環境構築する場合の手順は以下の通りです。
\ndepot_tools をインストールする必要があります。このツールセットは Chromium とその依存関係のダウンロードに使用されます。
更に Windows では、DEPOT_TOOLS_WIN_TOOLCHAIN=0 と環境変数を設定する必要があります。 これを行うには、コントロール パネル → システムとセキュリティ → システム → システムの詳細設定 を開き、DEPOT_TOOLS_WIN_TOOLCHAIN 環境変数を追加して値を 0 にします。 これはローカルにインストールされているバージョンの Visual Studio を使用するように depot_tools に知らせます (デフォルトで depot_tools は Google 社員のみがアクセスできる Google 内部のバージョンをダウンロードしようとします) 。
Electron を複数回チェックアウトする予定がある場合 (例えば複数の並列ディレクトリを異なるブランチにチェックアウトさせるなど)、git キャッシュを使用することでその後の gclient 呼び出しを高速化できます。 これをするには GIT_CACHE_PATH 環境変数を以下のように設定する必要があります。
$ export GIT_CACHE_PATH=\"${HOME}/.git_cache\"\n$ mkdir -p \"${GIT_CACHE_PATH}\"\n# 16G ほどあります。\n$ mkdir electron-gn && cd electron-gn\n$ gclient config --name \"src/electron\" --unmanaged https://github.com/electron/electron\n$ gclient sync --with_branch_heads --with_tags\n# これはしばらくかかります。コーヒーでも飲みに行きましょう。\n\n\n\n
https://github.com/electron/electronの代わりに、https://github.com/<username>/electronのような自分のフォークを使うこともできます。
もし将来公式の electron レポジトリから git pull や git push をする予定であれば、現在はそれぞれのフォルダの origin URL を更新する必要があります。
$ cd src/electron\n$ git remote remove origin\n$ git remote add origin https://github.com/electron/electron\n$ git checkout main\n$ git branch --set-upstream-to=origin/main\n$ cd -\n📝 gclient は、Chromium や Node.js のような依存の解決のために src/electron フォルダ内の DEPS と呼ばれるファイルを確認します。 gclient sync -f を実行することで Electron のビルドに必要な依存関係をすべて取得します。
なので、プルするには、以下のコマンドを実行するとよいでしょう。
\n$ cd src/electron\n$ git pull\n$ gclient sync -f\n$ cd src\n$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nWindows 上(任意の引数はなし):
\n$ cd src\n$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\\buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\")\"\nこれはデバッグビルドの設定とともに src/ 下の out/Testing ビルドディレクトリに生成されます。 Testing は他の名前に置換できますが、out のサブディレクトリである必要があります。 更に gn gen を再び実行してはいけません。ビルド引数を変更したい場合、 gn args out/Testing を実行してエディタを呼び出します。
利用可能なビルド設定を一覧するには、gn args out/Testing --list を実行してください。
Electron の Testing ビルド設定は以下のとおりです。
\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nElectron の Release (別名 \"non-component\" または \"static\") ビルド設定は以下のとおりです。
\n$ gn gen out/Release --args=\"import(\\\"//electron/build/args/release.gn\\\") $GN_EXTRA_ARGS\"\nビルドするには、ninja を electron ターゲットで実行します。 注意: これはさらなる時間を要し、パソコンも熱くなります。
テスト構成は以下のとおりです。
\n$ ninja -C out/Testing electron\nリリース構成は以下のとおりです。
\n$ ninja -C out/Release electron\nこれは、先に \"libchromiumcontent\" ( chromium の content/ ディレクトリと WebKit や V8 を含む依存関係) のすべてをビルドします。そのため時間がかかります。
実行形式は ./out/Testing 下に置かれます。
$ ./out/Testing/Electron.app/Contents/MacOS/Electron\n# Windowsの場合\n$ ./out/Testing/electron.exe\n# Linuxの場合\n$ ./out/Testing/electron\nLinuxの場合、デバッグ情報やシンボル情報を削除します。
\nelectron/script/strip-binaries.py -d out/Release\n配布可能なzipファイルとしてこのエレクトロンビルドをパッケージするには、次のようにする。
\nninja -C out/Release electron:electron_dist_zip\n構築しているプラットフォームと同じでないプラットフォーム用にコンパイルするには、target_cpu 及び target_os GN 引数を設定します。 例えば、x64 ホストから x86 ターゲットをコンパイルするには、gn args で target_cpu = \"x86\" と指定します。
$ gn gen out/Testing-x86 --args='... target_cpu = \"x86\"'\nソースコードとターゲット CPU/OS のすべての組み合わせが Chromium でサポートされているわけではありません。
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Host | ターゲット | 状況 |
|---|---|---|
| Windows x64 | Windows arm64 | 実験中 |
| Windows x64 | Windows x86 | 自動テスト済み |
| Linux x64 | Linux x86 | 自動テスト済み |
他の組み合わせをテストしてうまく動作することがわかれば、このドキュメントを更新してください :)
\ntarget_os と target_cpu の許可されている値については、 GN リファレンスを参照してください。
Arm 上の Windows 用にクロスコンパイルするには、Chromium のガイドに従って 必要な依存関係、SDK およびライブラリを取得し、gclient sync を実行する前に環境内で ELECTRON_BUILDING_WOA=1 でビルドします。
set ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nもしくは (PowerShell を用いる場合) こうします。
\n$env:ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nそれから、上記のように target_cpu=\"arm64\" で gn gen を実行します。
このテストを実行するために、あなたは最初に、このビルドプロセスの一部としてビルドする Node.js と同じバージョンに対してテストモジュールをビルドする必要があります。 再びコンパイルするモジュールのためのビルドヘッダを生成するために、src/ディレクトリの下で以下のように実行します。
$ ninja -C out/Testing third_party/electron_node:headers\nこれで テストを実行 できます。
\nもし何かをデバッグ中であれば、以下のフラグを Electron バイナリに渡すと役に立つかもしれません。
\n$ npm run test -- \\\n --enable-logging -g 'BrowserWindow module'\ngclient git キャッシュを Linux 上で SMB 共有としてエクスポートすることで、他のマシンと共有することは可能ですが、一度に一つのプロセス/マシンだけがキャッシュを使用できます。 git-cache スクリプトによって作成されたロックはこれを防止しようとしますが、ネットワーク内で完璧には動作しない可能性があります。
\nWindows では、SMBv2 にはディレクトリキャッシュがあり、git キャッシュスクリプトに問題が発生するため、レジストリキー
\nHKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\\DirectoryCacheLifetime\nを0に設定して無効にする必要があります。 詳細: https://stackoverflow.com/a/9935126
\nこれは PowerShell 内ですぐに設定できます (管理者権限で実行します)。
\nNew-ItemProperty -Path \"HKLM:\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force\ngclient sync が中断されると、git ツリーが不正な状態のままになってしまい、将来 gclient sync を実行したときに不可解なメッセージが表示されます。
2> Conflict while rebasing this branch.\n2> Fix the conflict and run gclient again.\n2> See man git-rebase for details.\nsrc/electron に git のコンフリクトやリベースがない場合は、src の git am を abort する必要があります。
$ cd ../\n$ git am --abort\n$ cd electron\n$ gclient sync -f\nWindows 上で gclient sync を実行しているときに Username for 'https://chrome-internal.googlesource.com': のプロンプトが表示された場合、おそらく DEPOT_TOOLS_WIN_TOOLCHAIN 環境変数が 0 に設定されていないからです。 コントロール パネル → システムとセキュリティ → システム → システムの詳細設定 を開き、DEPOT_TOOLS_WIN_TOOLCHAIN 環境変数を追加して値を 0 にします。 これはローカルにインストールされているバージョンの Visual Studio を使用するように depot_tools に知らせます (デフォルトで depot_tools は Google 社員のみがアクセスできる Google 内部のバージョンをダウンロードしようとします) 。
Follow the guidelines below for building Electron itself on Linux, for the purposes of creating custom Electron binaries. アプリのコードをビルド済み Electron バイナリにバンドルして頒布する場合は、アプリケーション頒布 のガイドを参照してください。
\nAt least 25GB disk space and 8GB RAM.
\nPython 2.7.x. Some distributions like CentOS 6.x still use Python 2.6.x so you may need to check your Python version with python -V.
Please also ensure that your system and Python version support at least TLS 1.2. For a quick test, run the following script:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, use your system's package manager to update Python to the latest version in the 2.7.x branch. Alternatively, visit https://www.python.org/downloads/ for detailed instructions.
\nNode.js. There are various ways to install Node. You can download source code from nodejs.org and compile it. Doing so permits installing Node on your own home directory as a standard user. Or try repositories such as NodeSource.
\nclang 3.4 or later.
\nDevelopment headers of GTK 3 and libnotify.
\nOn Ubuntu, install the following libraries:
\n$ sudo apt-get install build-essential clang libdbus-1-dev libgtk-3-dev \\\n libnotify-dev libgnome-keyring-dev \\\n libasound2-dev libcap-dev libcups2-dev libxtst-dev \\\n libxss1 libnss3-dev gcc-multilib g++-multilib curl \\\n gperf bison python-dbusmock openjdk-8-jre\nOn RHEL / CentOS, install the following libraries:
\n$ sudo yum install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Fedora, install the following libraries:
\n$ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Arch Linux / Manjaro, install the following libraries:
\n$ sudo pacman -Syu base-devel clang libdbus gtk2 libnotify \\\n libgnome-keyring alsa-lib libcap libcups libxtst \\\n libxss nss gcc-multilib curl gperf bison \\\n python2 python-dbusmock jdk8-openjdk\nOther distributions may offer similar packages for installation via package managers such as pacman. Or one can compile from source code.
\nIf you want to build for an arm target you should also install the following dependencies:
$ sudo apt-get install libc6-dev-armhf-cross linux-libc-dev-armhf-cross \\\n g++-arm-linux-gnueabihf\nSimilarly for arm64, install the following:
$ sudo apt-get install libc6-dev-arm64-cross linux-libc-dev-arm64-cross \\\n g++-aarch64-linux-gnu\nAnd to cross-compile for arm or ia32 targets, you should pass the target_cpu parameter to gn gen:
$ gn gen out/Testing --args='import(...) target_cpu=\"arm\"'\nPrebuilt clang will try to link to libtinfo.so.5. Depending on the host architecture, symlink to appropriate libncurses:
$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5\nThe default building configuration is targeted for major desktop Linux distributions. To build for a specific distribution or device, the following information may help you.
\nclang instead of downloaded clang binariesBy default Electron is built with prebuilt clang binaries provided by the Chromium project. If for some reason you want to build with the clang installed in your system, you can specify the clang_base_path argument in the GN args.
For example if you installed clang under /usr/local/bin/clang:
$ gn gen out/Testing --args='import(\"//electron/build/args/testing.gn\") clang_base_path = \"/usr/local/bin\"'\nclangBuilding Electron with compilers other than clang is not supported.
カスタム Electron バイナリの作成にあたって macOS で Electron そのもの をビルドするには、以下のガイドラインに従ってください。 アプリのコードをビルド済み Electron バイナリにバンドルして頒布する場合は、アプリケーション頒布 のガイドを参照してください。
\nPlease also ensure that your system and Python version support at least TLS 1.2. これは、macOS と Python 両方のバージョンに依存します。 クイックテストをするには以下を実行します。
\n$ npx @electron/check-python-tls\nスクリプトが古い構成のセキュリティプロトコルを使用していると応答した場合、macOS を High Sierra に更新するか、新しいバージョンの Python 2.7.x をインストールすることができます。 Python をアップグレードするために、以下では Homebrew を使用します。
\n$ brew install python@2 && brew link python@2 --force\nHomebrew で提供される Python を使用している場合、以下の Python モジュールのインストールも必要です。
\n以下のように pip を使ってインストールできます。
$ pip install pyobjc\nElectron を開発していて独自の Electron ビルドを再配布する予定がない場合は、このセクションを飛ばして構いません。
\n公式の Electron ビルドは、Xcode 12.2 と macOS 11.0 SDK でビルドされています。 より新しい SDK でビルドして同様に動いても、現在のリリースは 11.0 SDK を使用します。
\nビルド指示: GNを参照してください。
", "title": "ビルド手順 (macOS)", "description": "" }, "/docs/development/build-instructions-windows": { "locale": "ja-JP", "slug": "build-instructions-windows", "href": "/docs/development/build-instructions-windows", "crowdinFileId": "256137", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/build-instructions-windows.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "カスタム Electron バイナリの作成にあたって Windows で Electron そのもの をビルドするには、以下のガイドラインに従ってください。 アプリのコードをビルド済み Electron バイナリにバンドルして頒布する場合は、アプリケーション頒布 のガイドを参照してください。
\nvs2019_install = DRIVE:\\path\\to\\Microsoft Visual Studio\\2019\\Community、このうち 2019 と Community をインストールしたバージョンのものに、DRIVE: をVisual Studio があるドライブに置き換えます。 大抵、このドライブは C: です。WINDOWSSDKDIR = DRIVE:\\path\\to\\Windows Kits\\10、このうち DRIVE: を Windows Kits があるドライブに置き換えます。 大抵、このドライブは C: です。.pdb ファイルからシンボルストアを作成するために symstore.exe を使用します。変更 → 個別のコンポーネント を選択し、スクロールしてインストールする適切な Windows SDK を選択します。 他に、Windows SDK とエミュレータのアーカイブ を見て、SDK のスタンドアロン版をそれぞれダウンロードすることでもできます。コントロールパネル → プログラム → プログラムと機能 → \"Windows Software Development Kit\" を選択 → 変更 → 変更 → \"Debugging Tools For Windows\" にチェック → 変更。 または、スタンドアロンの SDK インストーラをダウンロードして、それを使ってデバッグツールをインストールすることができます。現在 Windows インストールを持っていない場合、dev.microsoftedge.com に Electron をビルドするために使用できる Windows のバージョンがあります。
\nElectron のビルドは完全にコマンドラインスクリプトで行われ、Visual Studio では実行できません。 任意のエディタで Electron を開発できますが、将来 Visual Studio を使用したビルドがサポートされます。
\n注釈: Visual Studio はビルドに使用されていませんが、それが提供するビルドツールチェーンが必要なため、まだ 必要 です。
\nWindows Security は Chromium ソースコード内のファイルを良く思わないようで (https://crbug.com/441184 を参照)、常にある特定のファイルを削除してしまい、gclient sync の問題を引き起こします。 こちらの手順に従う ことで、ソースのツリーを Windows Security の監視から除外できます。
ビルド手順: GN を参照してください。
\n32ビットターゲット用にビルドするには、引数としてtarget_cpu = \"x86\" をGNに渡す必要があります。 32ビットターゲットと共に64ビットターゲットをビルドできます。それには別の引数を使って、out/Release-x86のような別のディレクトリに出力させられます。
$ gn gen out/Release-x86 --args=\"import(\\\"//electron/build/args/release.gn\\\") target_cpu=\\\"x86\\\"\"\n他のビルド手順は全く同じです。
\nVisual Studio プロジェクトを生成するには、--ide=vs2017 引数をgn genに渡します。
$ gn gen out/Testing --ide=vs2017\nCommand xxxx not found のようなエラーに遭遇した場合、開発者コマンド プロンプト for VS2015 コンソールを使用してビルドスクリプトを実行してみましょう。
最新の Visual Studio アップデートがインストールされていることを確認してください。
\n32ビット Node.js を再インストールしてください。
\n以下のようにディレクトリを作成すると 問題 は解決するはずです。
\n$ mkdir ~\\AppData\\Roaming\\npm\nビルドに Git Bash を使用している場合は、代わりに PowerShell または 開発者コマンド プロンプト for VS2015 を使用する必要があります。
\nnode.jsに長すぎるパス名があるようです。標準では、Windows版のgitは、長いファイル名をきちんと処理できません。 この問題を解決するには以下のようにします：
\n$ git config --system core.longpaths true\nこれは、Windows 用のデバッグツールが Windows Driver Kit とともにインストールされている場合においてビルド中に発生する可能性があります。 Windows Driver Kit をアンインストールし、上記の手順で Debugging Tools をインストールします。
\npywin32がインストールされているか確認してください。これは次のコマンドでインストールします。:pip install pywin32.
このバグは Windows コマンドプロンプトの「機能」によるものです。 簡易編集モード を有効にしたプロンプトウィンドウ内をクリックすると発生し、出力テキストを簡単に選択してコピーできるようにすることを目的としています。 誤ってクリックするたびにビルドプロセスが一時停止するため、この機能はコマンドプロンプトのプロパティで無効にできます。
Electronは、プロジェクト生成にGNを用い、ビルドには ninjaを使用します。 プロジェクト設定は.gn と .gni ファイルを見てください。
以下のgnファイルにはElectronのビルトのメインルールを含んでいます：
BUILD.gn は、Electron 自身をどのようにビルドするかを定義し、Chromium とリンクするデフォルト設定を含んでいます。build/args/{debug,release,all}.gn には、Electronをビルドするためのデフォルトのビルド引数が含まれています。Chromiumはとても巨大なプロジェクトですので、最終的なリンクの段階でかなりの時間を要し、それが開発を難しくしてしまいます。 これを解決するために、Chromiumはそれぞれのコンポーネントを別々の共有ライブラリとしてビルドを行う、「コンポーネントビルド」を採用しており、これによりファイルサイズとパフォーマンスを犠牲にすることでビルドを高速で行っています。
\nElectronはChromiumビルドオプションを継承します。 Debug ビルドでは、ライブラリはリンク時間を節約するために、Chromium のコンポーネントの共有ライブラリにバイナリがリンクされます。Release ビルドではバイナリは静的ライブラリにリンクされるので、適したファイルサイズとパフォーマンスを得ることができます。
注意 この章は古い内容であり、この情報は GN でビルドされた Electron には該当しません。
\nプロジェクトのコーディングスタイルは以下で確認できます。
\n$ npm run lint\n以下で機能テストをします。
\n$ npm test\nElectron のソースコードを変更したため再ビルドとテストを行う場合は以下を実行します。
\n$ npm run build && npm test\nMocha の排他テスト (exclusive tests) 機能を使用することで、特定のテストやブロックが切り離され、連続したテストを早く実行できます。 以下のような .only を describe か it 関数呼び出しに加えます。
describe.only('some feature', () => {\n // ... このブロックのテストのみ実行されます\n})\n他に、Mocha の grep オプションで指定した正規表現に一致したテストのみを実行できます。
$ npm test -- --grep child_process\nネイティブモジュール (runas など) を含むテストは、デバッグビルドでは実行できません (詳細は #2558 を参照)。リリースビルドでは動作します。
リリースビルドでテストを行うには、以下のようにします。
\n$ npm test -- -R\ndata String - PEM encoded dataissuer CertificatePrincipal - Issuer principalissuerName String - Issuer's Common NameissuerCert Certificate - Issuer certificate (if not self-signed)subject CertificatePrincipal - Subject principalsubjectName String - Subject's Common NameserialNumber String - Hex value represented stringvalidStart Number - Start date of the certificate being valid in secondsvalidExpiry Number - End date of the certificate being valid in secondsfingerprint String - Fingerprint of the certificatecommonName String - Common Name.organizations String[] - Organization names.organizationUnits String[] - Organization Unit names.locality String - Locality.state String - State or province.country String - Country or region.\n\nChromium の学習や Chromium の開発状況を追跡する際に参考になるリソース集です
\n
V8 Development も参照
", "title": "Chromium開発", "description": "Chromium の学習や Chromium の開発状況を追跡する際に参考になるリソース集です" }, "/docs/development/clang-format": { "locale": "ja-JP", "slug": "clang-format", "href": "/docs/development/clang-format", "crowdinFileId": "256143", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/clang-format.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "clang-format は C/C++/Objective-C のコードを自動的にフォーマットするツールです。開発者がコードレビュー中にスタイルの問題を心配する必要はありません。
プルリクエストを開く前に、変更された C++ コードをフォーマットすることを強くお勧めします。これにより、あなたとレビュアーの時間が節約されます。
\nnpm install -g clang-format を介して clang-format と git-clang-format をインストールできます。
Electron C++ コードスタイルに従ってファイルを自動的にフォーマットするには、 clang-format -i electron/への/パス/ファイル.cc を実行します。 これは macOS/Linux/Windows で動作します。
以下は変更したコードをフォーマットするワークフローです。
\ngit add your_changed_file.cc を実行します。git-clang-format を実行すると、clang-format によって生成された修正が 変更したファイル名.cc 内に見えるはずです。git add your_changed_file.cc を実行して、変更をコミットします。もし最新の git コミット (HEAD) 上の変更コードをフォーマットしたい場合は、git-clang-format HEAD~1 でできます。 より詳しくは git-clang-format -h を参照してください。
あなたの好きなエディタに直接 clang-format を統合することもできます。 エディタ統合の設定に関する詳細は、以下のページを参照してください。
clang-tidy は C/C++/Objective-C コードのスタイル違反、プログラミングエラー、ベストプラクティスを自動でチェックするツールです。
Electron の clang-tidy インテグレーションは、npm run lint:clang-tidy で実行できるリンタースクリプトとして提供しています。 clang-tidy でディスク上のファイルをチェックするには、使用するコンパイラーフラグが分かるように Electron をビルドしておく必要があります。 このスクリプトには、コンパイル情報を取得するビルドディレクトリを指定するオプション --output-dir があります。 典型的な使用方法としては npm run lint:clang-tidy --out-dir ../out/Testing のようになります。
ファイル名を指定しない場合、すべての C/C++/Objective-C ファイルがチェックされます。 チェックするファイルのリストを指定するには、npm run lint:clang-tidy --out-dir ../out/testing shell/browser/api/electron_api_app.cc のようにオプションの後にそのファイル名を渡すとできます。
clang-tidy では こちらの長いリスト がチェック可能な項目ですが、Electron のデフォルトではこのうちいくつかのチェックしか有効になっていません。 現時点の Electron には .clang-tidy の設定が無いので、clang-tidy は Chromium 内の src/.clang-tidy にあるものを見つけ、Chromium が有効にしているチェックを使用します。 実行するチェックは --checks= オプションで変更できます。 これはそのまま clang-tidy に渡されるので、この詳細は clang-tidy のドキュメントを参照してください。 ワイルドカードが使用でき、- を頭に付けるとそのチェックを無効にできます。 デフォルトでは、リストしたチェックはすべて .clang-tidy のチェックに追加されます。そのため、特定のチェックを制限したい場合は、最初にすべてのチェックを除外してから --checks=-*,performance* のように必要なものを追加してください。
clang-tidy の実行はかなり遅いです。内部的には各ファイルをコンパイルしてからチェックするので、何らかの要因でコンパイルよりも常に遅くなります。 --jobs|-j オプションで並列実行して高速化できますが、clang-tidy もチェック中に多くのメモリを使用するので、メモリ不足エラーに陥りやすくなります。 このため、デフォルトのジョブ数は 1 です。
\n\nHTTP/HTTPリクエストを行います。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
ClientRequest は Writable Stream インターフェースを実装しているため、 EventEmitter です。
new ClientRequest(options)options (Object | String) - もし options が String なら、リクエスト URL として処理されます。 オブジェクトの場合は、次のプロパティによる HTTP リクエストの完全な指定と予期されます。method String (任意) - HTTP リクエストのメソッド。 既定では GET メソッドです。url String (任意) - リクエスト URL 。 http または https のプロトコルスキームを含む絶対形式である必要があります。session Session (任意) - リクエストが関連付けられている Session のインスタンス。partition String (任意) - リクエストが関連付けられている partition の名前。 省略値は、空の文字列です。 session オプションは partition を上書きします。 そのため、session が明示的に指定されている場合、partition は無視されます。credentials String (任意) - include か omit にできます。 このリクエストと一緒に 資格情報 を送信するかどうか。 include に設定した場合、リクエストに関連付けられたセッションからの資格情報が使用されます。 omit に設定した場合、資格情報はリクエストと一緒に送信されません (そして 401 の場合に 'login' イベントが発生しません)。 これは、同名の fetch オプションの動作と同じです。 このオプションを指定しない場合、セッションからの認証データは送信され、(useSessionCookies を設定しない限り) Cookie は送信されません。useSessionCookies Boolean (任意) - 指定のセッションからこのリクエストで Cookie を送るかどうか。 credentials を指定した場合、このオプションの効果はありません。 省略値は false です。protocol String (任意) - http: か https: にできます。 これは 'scheme:' という形式のプロトコルスキームです。 既定値は 'http:' です。host String (任意) - ホスト名とポート番号を連結した 'hostname:port' として指定されたサーバーホスト。hostname String (任意) - サーバーホスト名。port Integer (任意) - サーバーのリスニングポート番号。path String (任意) - リクエストURLのパスの部分。redirect String (任意) - follow、error、manual のいずれかにできます。 これはこのリクエストのリダイレクトモードです。 モードが error のとき、リダイレクトは中止されます。 モードが manual のときは、request.followRedirect が呼び出されるまで redirect イベントは同期的に中止されます。 省略値は、follow です。origin String (任意) - リクエストのオリジン URL。protocol、host、hostname、port や path といった options プロパティは、URL モジュールで説明されている Node.js モデルに厳密に従うようにしてください。
例えば、以下のようにすると、'github.com' に対してリクエストをしているのと同じです。
\nconst request = net.request({\n method: 'GET',\n protocol: 'https:',\n hostname: 'github.com',\n port: 443,\n path: '/'\n})\n戻り値：
\nresponse IncomingMessage - HTTP レスポンスメッセージを表すオブジェクト。戻り値：
\nauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (任意)password String (任意)認証プロキシがユーザの資格情報を要求しているときに発生します。
\ncallback ファンクションは、ユーザの資格情報と共にコールバックされます。
username Stringpassword Stringrequest.on('login', (authInfo, callback) => {\n callback('username', 'password')\n})\n空の資格情報を指定すると、リクエストがキャンセルされ、レスポンスオブジェクトで認証エラーが返ります。
\nrequest.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`);\n response.on('error', (error) => {\n console.log(`ERROR: ${JSON.stringify(error)}`)\n })\n})\nrequest.on('login', (authInfo, callback) => {\n callback()\n})\nrequest のデータの最後のチャンクが request オブジェクトに書き込まれた直後に発生します。
request が中止されたときに発生します。 request が既に閉じられている場合、 abort イベントは発生しません。
戻り値：
\nerror Error - 失敗に関するいくつかの情報を提供するエラーオブジェクト。net モジュールがネットワークリクエストを行うのに失敗するときに発生します。 通常、request オブジェクトが error イベントを発生させるとき、続いて close イベントが発生し、レスポンスオブジェクトが返ることはありません。
HTTPのリクエストからレスポンスまでのやり取りの最後のイベントして発生します。 close イベントは、request または response オブジェクトのいずれでもこれ以上のイベントが発生しないことを示します。
戻り値：
\nstatusCode Integermethod StringredirectUrl StringresponseHeaders Record<String, String[]>サーバーがリダイレクトのレスポンス (301 Moved Permanently など) を返すときに生成されます。 request.followRedirect を呼び出すと、リダイレクトが続行されます。 このイベントを処理する場合、request.followRedirect を 同期的に で呼び出す必要があります。でなければ、リクエストはキャンセルされます。
request.chunkedEncodingリクエストがHTTPのチャンク形式転送エンコーディングを使用するかどうかを指定する Boolean 型。 省略値は、false です。 プロパティは読み書き可能ですが、HTTPヘッダーがまだ送信されていない最初の書き込み操作の前でしか設定できません。 最初の書き込みの後、chunkedEncoding プロパティを設定しようとすると、エラーがスローされます。
Electronのプロセスメモリの中で内部的にバッファする代わりにデータが細切れにストリーミングされるため、大きなリクエストボディを送信する必要がある場合、チャンク形式のエンコーディングを使用することを強く推奨します。
\nrequest.setHeader(name, value)name String - 追加する HTTP ヘッダーの名前。value String - 追加する HTTP ヘッダーの値。別の HTTP ヘッダーを追加します。 ヘッダー名は小文字にされることなく、そのまま出力されます。 最初の書き込み前のみ呼び出すことができます。 最初の書き込み後にこのメソッドを呼び出すとエラーがスローされます。 渡された値が String 型でない場合、最終的な値を得るために toString() メソッドが呼び出されます。
特定のヘッダーはアプリによって設定されないように制限されています。 これらのヘッダは以下にリストアップしています。 制限付きヘッダーの詳細は、Chromium のヘッダー ユーティリティ を参照してください。
\nContent-LengthHostTrailer または TeUpgradeCookie2Keep-AliveTransfer-Encodingさらに、Connection ヘッダを upgrade の値に設定することも禁止されています。
request.getHeader(name)name String - 追加したヘッダーの名前を指定します。戻り値 String - 先に設定した追加したヘッダーの名前の値。
request.removeHeader(name)name String - 追加したヘッダーの名前を指定します。以前に設定した追加ヘッダーの名前を削除します。 このメソッドは、最初の書き込み前のみ呼び出すことができます。 最初の書き込み後にこのメソッドを呼び出すとエラーがスローされます。
\nrequest.write(chunk[, encoding][, callback])chunk (String | Buffer) - リクエストボディのデータのチャンク。 文字列の場合、指定されたエンコーディングで Buffer に変換されます。encoding String (任意) - 文字列のチャンクを Buffer オブジェクトへ変換する際に使用されます。 既定値は 'utf-8' です。callback Function (任意) - 書き込み操作の終了後に呼び出されます。callback は、Node.jsのAPIとの類似性を維持する目的で導入された本質的にはダミーのファンクションです。 chunk コンテンツがChromiumのネットワークレイヤーに到達した後、すぐに非同期で呼び出されます。 Node.jsの実装とは違って、callback が呼び出される前に chunk コンテンツが書き込まれていることは保証されません。
リクエストボディにデータのチャンクを追加します。 最初の書き込み操作では、リクエストヘッダーも出力される可能性があります。 最初の書き込み操作の後、カスタムヘッダーを追加したり、削除したりすることはできません。
\nrequest.end([chunk][, encoding][, callback])chunk (String | Buffer) (任意)encoding String (任意)callback Function (任意)リクエストデータの最終チャンクを送信します。 後続の書き込みまたは終了の操作は許可されません。 終了操作の直後に finish イベントが発生します。
request.abort()現在進行中のHTTPトランザクションをキャンセルします。 リクエストで既に close イベントが発生していた場合、中止操作は無効になります。 そうでない場合、進行中のイベントでは、abort と close イベントが発生します。 さらに、処理中のレスポンスオブジェクトがある場合、aborted イベントが発生します。
request.followRedirect()保留中のリダイレクトを続行します。 'redirect' イベントの間のみ呼び出せます。
request.getUploadProgress()戻り値 Object:
active Boolean - リクエストが現在アクティブかどうか。 これが false の場合、他のプロパティは設定されません。started Boolean - アップロードが開始されたかどうか。 これが false の場合、 current と total は 0 になります。current Integer - どのくらいアップロードしたかのバイト数。total Integer - このリクエストでアップロードされるバイト数。このメソッドを POST リクエストと組み合わせて使用すると、ファイルのアップロードや他のデータ転送の進行状況を取得できます。
\n\n\nシステムのクリップボードでコピーやペーストの操作を行います。
\n
Linux には、 selection クリップボードも存在します。 これを操作するには、各メソッドに selection を渡す必要があります。
const { clipboard } = require('electron')\n\nclipboard.writeText('Example String', 'selection')\nconsole.log(clipboard.readText('selection'))\nclipboard モジュールには以下のメソッドがあります。
注: 実験的なAPIにはそのように注記があり、将来的に削除される可能性があります。
\nclipboard.readText([type])type String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。戻り値 String - プレーンテキストでのクリップボード内のコンテンツ。
const { clipboard } = require('electron')\n\nclipboard.writeText('hello i am a bit of text!')\n\nconst text = clipboard.readText()\nconsole.log(text)\n// hello i am a bit of text!'\nclipboard.writeText(text[, type])text Stringtype String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。プレーンテキストとしてクリップボードに text を書き込みます。
const { clipboard } = require('electron')\n\nconst text = 'hello i am a bit of text!'\nclipboard.writeText(text)\nclipboard.readHTML([type])type String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。戻り値 String - マークアップでのクリップボード内のコンテンツ。
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b>')\nconst html = clipboard.readHTML()\n\nconsole.log(html)\n// <meta charset='utf-8'><b>Hi</b>\nclipboard.writeHTML(markup[, type])markup Stringtype String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。クリップボードに markup を書き込みます。
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b')\nclipboard.readImage([type])type String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。戻り値 NativeImage - クリップボード内の画像コンテンツ。
clipboard.writeImage(image[, type])image NativeImagetype String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。クリップボードに image を書き込みます。
clipboard.readRTF([type])type String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。戻り値 String - RTFでのクリップボード内のコンテンツ。
const { clipboard } = require('electron')\n\nclipboard.writeRTF('{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}')\n\nconst rtf = clipboard.readRTF()\nconsole.log(rtf)\n// {\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}\nclipboard.writeRTF(text[, type])text Stringtype String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。RTFでクリップボードに text を書き込みます。
const { clipboard } = require('electron')\n\nconst rtf = '{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}'\nclipboard.writeRTF(rtf)\nclipboard.readBookmark() macOS Windows戻り値 Object:
title Stringurl Stringクリップボード内のブックマークを表す title と url のキーを含む Object を返します。 ブックマークが無効なとき、title と url の値は空文字です。
clipboard.writeBookmark(title, url[, type]) macOS Windowstitle Stringurl Stringtype String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。ブックマークとしてクリップボードに title と url を書き込みます。
注: Windowsの大抵のアプリは、ブックマークのペーストをサポートしていないため、ブックマークと縮退したテキストの両方をクリップボードに書き込むため、clipboard.write を使うようにしてください。
const { clipboard } = require('electron')\n\nclipboard.writeBookmark({\n text: 'https://electronjs.org',\n bookmark: 'Electron Homepage'\n})\nclipboard.readFindText() macOS戻り値 String - 検索ペーストボード上のテキストです。これは、アクティブなアプリケーションの検索パネルの現在の状態に関する情報を保持するペーストボードです。
このメソッドは、レンダラープロセスから呼び出されたとき同期 IPC を使います。 アプリケーションがアクティブにされるたびに、キャッシュされた値は、検索ペーストボードから再読込されます。
\nclipboard.writeFindText(text) macOStext Stringtext をプレーンテキストとして検索ペーストボード (アクティブなアプリケーションの検索パネルの現在の状態に関する情報を保持するペーストボード) に書き込みます。 このメソッドは、レンダラープロセスから呼び出されたとき同期 IPC を使います。
clipboard.clear([type])type String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。クリップボードの内容を消去します。
\nclipboard.availableFormats([type])type String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。戻り値 String[] - クリップボードがサポートしている形式の type の配列。
const { clipboard } = require('electron')\n\nconst formats = clipboard.availableFormats()\nconsole.log(formats)\n// [ 'text/plain', 'text/html' ]\nclipboard.has(format[, type]) 実験的format Stringtype String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。戻り値 Boolean - クリップボードが指定した format をサポートしているかどうか。
const { clipboard } = require('electron')\n\nconst hasFormat = clipboard.has('<p>selection</p>')\nconsole.log(hasFormat)\n// 'true' か 'false'\nclipboard.read(format) 実験的format String戻り値 String - クリップボードから format 形式で読み出します。
format は有効な ASCII 文字を含み、/ で区切られている必要があります。 a/c, a/bc は有効ですが、/abc, abc/, a/, /a, a は無効です。
clipboard.readBuffer(format) 実験的format String戻り値 Buffer - クリップボードから format 形式で読み出します。
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('this is binary', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\n\nconst ret = clipboard.readBuffer('public/utf8-plain-text')\n\nconsole.log(buffer.equals(out))\n// true\nclipboard.writeBuffer(format, buffer[, type]) 実験的format Stringbuffer Buffertype String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。format でクリップボードに buffer を書き込みます。
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('writeBuffer', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\nclipboard.write(data[, type])data Objecttext String (任意)html String (任意)image NativeImage (任意)rtf String (任意)bookmark String (任意) - URL のタイトルの text。type String (任意) - selection または clipboard 。既定値は 'clipboard' です。 selection は Linux のみで有効です。クリップボードに data を書き込みます。
const { clipboard } = require('electron')\n\nclipboard.write({\n text: 'test',\n html: '<b>Hi</b>',\n rtf: '{\\\\rtf1\\\\utf8 text}',\n bookmark: 'a title'\n})\n\nconsole.log(clipboard.readText())\n// 'test'\n\nconsole.log(clipboard.readHTML())\n// <meta charset='utf-8'><b>Hi</b>\n\nconsole.log(clipboard.readRTF())\n// '{\\\\rtf1\\\\utf8 text}'\n\nconsole.log(clipboard.readBookmark())\n// { title: 'a title', url: 'test' }\nコード署名はセキュリティ技術のひとつで、アプリを作成したのがあなたであることを確実にするために使用します。
\nmacOS システムでは、その変更が誤りか悪意のあるコードによって導入されたのかにかかわらず、アプリに対する変更を検出できます。
\nWindows では、コード署名証明書に信頼レベルが割り当てられています。そうでない場合や、信頼レベルが低いと、ユーザがアプリケーションを使用しようとしたときにセキュリティダイアログが表示されます。 信頼レベルは時間とともに上昇するので、できるだけ早くコード署名し始めることを推奨します。
\n未署名のアプリを配布することは可能ですが、非推奨です。 Windows と macOS の両方は、デフォルトで未署名のアプリケーションのダウンロードや実行を阻害します。 macOS Catalina (バージョン 10.15) 以降では、ユーザーが署名されていないアプリケーションを開くには、複数ある手動の手順を実行する必要があります。
\n
見かけ上、ユーザーには 2 つの選択肢があります。アプリをゴミ箱に直接移動するか、実行をキャンセルするかです。 ユーザーにそのダイアログを表示させたくはないでしょう。
\nパッケージ化して配布する予定の Electron アプリケーションを作成している場合は、コード署名されている必要があります。
\nmacOS アプリをリリースに向けて適切に準備するには、2 つのステップが必要です。まず、アプリをコード署名する必要があります。 そして、\"公証\" と呼ばれるプロセスのためにアプリを Apple にアップロードする必要があります。自動化されたシステムによって、アプリがユーザーを危険にさらすようなことをしていないかどうか、さらに確認します。
\nこのプロセスを開始するには、以下に示すアプリへの署名と公証の要件を満たしていることを確認してください。
\nElectron のエコシステムでは構成とその自由度を重視しているため、アプリケーションの署名と公証の取得には複数の方法が用意されています。
\nelectron-forge好きな Electron のビルドツールを使用している場合、アプリケーションの署名と公証を行うにあたって、設定にいくつか追加する必要があります。 forge は、内部で electron-packager、electron-osx-sign、electron-notarize を使っている、Electron 公式のツールの集合体です。
ここでは、すべての必須フィールドを設定した例を見てみましょう。 すべてが必須というわけでは無いのです。お使いのツールは適切な identity を自動的に見つけられるでしょう。それでも明示的に指定することを推奨します。
{\n \"name\": \"my-app\",\n \"version\": \"0.0.1\",\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"osxSign\": {\n \"identity\": \"Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)\",\n \"hardened-runtime\": true,\n \"entitlements\": \"entitlements.plist\",\n \"entitlements-inherit\": \"entitlements.plist\",\n \"signature-flags\": \"library\"\n },\n \"osxNotarize\": {\n \"appleId\": \"felix@felix.fun\",\n \"appleIdPassword\": \"my-apple-id-password\",\n }\n }\n }\n }\n}\nApple のセキュリティメカニズムを保証するため、ここで参照されている plist ファイルには以下のような macOS 固有の資格情報が入っている必要があります。
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nなお、Electron 12 までは com.apple.security.cs.allow-unsigned-executable-memory の資格情報も必要でした。 しかし、現在はできる限り使用を避けてください。
この実例をすべて見たいのであれば、Electron Fiddle のソースコード、特に electron-forge の設定ファイル を確認してください。
Electron の API を使ってアプリ内からマイクやカメラにアクセスする場合は、以下の資格情報も追加する必要があります。
\n<key>com.apple.security.device.audio-input</key>\n<true/>\n<key>com.apple.security.device.camera</key>\n<true/>\n起動時にこれらがアプリの資格情報に存在しない場合に、以下のようにしてみます。
\nconst { systemPreferences } = require('electron')\n\nconst microphone = systemPreferences.askForMediaAccess('microphone')\nアプリがクラッシュするでしょう。 詳しい情報や必要な資格情報については、Hardened Runtime の Resource Access のセクションをご覧ください。
\nelectron-builderElectron Builder にはアプリケーションに署名するためのカスタムソリューションが付属しています。 そのドキュメントはこちら にあります。
\nelectron-packagerForge や Builder のような統合されたビルドパイプラインを使用しない場合、electron-packager を使用することが多く、これは electron-osx-sign や electron-notarize を同梱しています。
Packager の API を使用している場合、アプリケーションに署名と公証の両方を行う設定 を渡すことができます。
\nconst packager = require('electron-packager')\n\npackager({\n dir: '/path/to/my/app',\n osxSign: {\n identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',\n 'hardened-runtime': true,\n entitlements: 'entitlements.plist',\n 'entitlements-inherit': 'entitlements.plist',\n 'signature-flags': 'library'\n },\n osxNotarize: {\n appleId: 'felix@felix.fun',\n appleIdPassword: 'my-apple-id-password'\n }\n})\nApple のセキュリティメカニズムを保証するため、ここで参照されている plist ファイルには以下のような macOS 固有の資格情報が入っている必要があります。
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nElectron 12 までは、com.apple.security.cs.allow-unsigned-executable-memory の資格情報も必要でした。 しかし、現在はできる限り使用を避けてください。
Mac App Store Guide を参照してください。
\nWindows ビルドに署名する前に、以下のことをしなければなりません。
\n多くの再販業者からコード署名証明書を入手できます。 価格はさまざまですので、選ぶのに迷うでしょう。 人気のある再販業者は次のとおりです。
\n\nパッケージアプリケーションに署名するためのツールは以下のようにたくさんあります。
\nelectron-winstaller は Windows 用インストーラを生成し、それに署名します。electron-forge は Squirrel.Windows または MSI ターゲットを通して生成されたインストーラに署名できます。electron-builder ではその Windows ターゲットのいくつかに署名することができますWindows Store Guide を参照してください。
", "title": "コード署名", "description": "" }, "/docs/development/coding-style": { "locale": "ja-JP", "slug": "coding-style", "href": "/docs/development/coding-style", "crowdinFileId": "256147", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/coding-style.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "これらは Electron のコーディングスタイルのガイドラインです。
\nnpm run lint を実行すると、cpplint と eslint で検出されたスタイルの問題を表示できます。
path など)ipc、app など)@ で始まるメソッド)path.join() を使用してファイル名を連結します。/tmp ではなく os.tmpdir() を使用してください。return を使用します。return null、return undefined、null や undefined ではありませんC++ と Python の場合、Chromium の コーディングスタイル に従います。 C++ のコードを自動的にフォーマットするのに、clang-format が使用できます。 また、script/cpplint.py というスクリプトがあり、すべてのファイルが適しているかどうかを確認します。
我たちの使用している現在の Python のバージョンは、Python 2.7 です。
\nC++ コードは多くの Chromium の抽象クラスと型を使用しているため、それらを知ることを推奨します。 始めるには、Chromiumの 重要な抽象クラスとデータ構造 ドキュメントが良いです。 このドキュメントでは、いくつかの特別な型、スコープ付きの型 (スコープ外に出たときに自動的にメモリを解放する) 、ロギングのメカニズムなどについて記述しています。
\nnpm run lint-docs を実行して、ドキュメントの変更が正しくフォーマットされていることを確認できます。
_ の代わりに - で連結する必要があります。github/atom モジュール名は通常は module-name の形式になるので、file_name.js ではなく、file-name.js としてください。 このルールは、.js ファイルにのみ適用されます。Electron API では、Node.js と同じ大文字表記が使用されます。
\nBrowserWindow のようなクラスである場合は、PascalCase を使用します。globalShortcut のような API のセットである場合は、camelCase を使用します。win.webContents のような別の章に分けられるほど複雑な場合は、mixedCase を使用します。<webview>タグ や プロセスオブジェクト などの自然なタイトルを使用します。新しい API を作成する場合は、jQuery の one 関数スタイルの代わりに getter と setter を使用することを推奨します。 例えば、.text([text]) より、.getText() と .setText(text) を優先します。 こちらに、これついての ディスカッション があります。
\n\nChromium が読み取るアプリのコマンドライン引数を操作します
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
以下の例は、-disable-gpu フラグが設定されているかどうかを確認する方法を示しています。
const { app } = require('electron')\napp.commandLine.hasSwitch('disable-gpu')\n使用できるフラグとスイッチの種類の詳細については、コマンドラインスイッチ ドキュメントを参照してください。
\ncommandLine.appendSwitch(switch[, value])switch String - 主要なものを除くコマンドラインスイッチ --value String (任意) - 与えられたスイッチの値Chromiumのコマンドラインに (オプションの value と一緒に) スイッチを追加します。
注: これはprocess.argv に影響を与えません。 この関数は主に Chromium の振る舞いを制御するために使われます。
commandLine.appendArgument(value)value String - コマンドラインに追加された引数Chromiumのコマンドラインに引数を追加します。 引数は正しく引用符で囲ってください。 スイッチは、追加順序に関係なく引数に先行します。
\n--switch=value のような引数を追加している場合は、代わりに appendSwitch('switch', 'value') を使用することを検討してください。
注: これはprocess.argv に影響を与えません。 この関数は主に Chromium の振る舞いを制御するために使われます。
commandLine.hasSwitch(switch)switch String - コマンドラインスイッチ戻り値 Boolean - コマンドラインスイッチがあるかどうか。
commandLine.getSwitchValue(switch)switch String - コマンドラインスイッチ戻り値 String - コマンドラインスイッチの値
注意: スイッチが存在しないか値がない場合、これは空文字列を返します。
", "title": "クラス: CommandLine", "description": "Chromium が読み取るアプリのコマンドライン引数を操作します" }, "/docs/api/command-line-switches": { "locale": "ja-JP", "slug": "command-line-switches", "href": "/docs/api/command-line-switches", "crowdinFileId": "256293", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/command-line-switches.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nElectronによってサポートされているコマンドラインスイッチ。
\n
app モジュールで ready イベントが発生する前に、アプリのメインスクリプトで app.commandLine.appendSwitch を使って、コマンドラインスイッチを追加することができます。
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('remote-debugging-port', '8315')\napp.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')\n\napp.whenReady().then(() => {\n // コードをここに\n})\nurl統合認証が有効であるサーバーのコンマ区切りのリスト。
\n以下がその例です。
\n--auth-server-whitelist='*example.com, *foobar.com, *baz'\n末尾が example.com、foobar.com、baz である url は、統合認証の対象になります。 * のプリフィックスがない場合は、URL は厳密に一致する必要があります。
urlユーザー資格情報の委任が必要なサーバのコンマ区切りリスト。 * のプリフィックスがない場合は、URL は厳密に一致する必要があります。
POSIX プラットフォーム向けに NTLM v2 を無効化します。他プラットフォームでの効果はありません。
\nHTTPリクエストに対するディスクキャッシュを無効にします。
\nHTTP/2 および SPDY/3.1 プロトコルを無効にします。
\nChromiumが隠れたページのレンダラープロセスの優先順位を下げるのを防止します。
\nこのフラグはすべてのレンダラープロセスに影響を及ぼすので、1つのウインドウの制限を無効にしたいだけの場合、無音のオーディオを再生するというテクニックを使うことができます。
\nsizeディスクキャッシュによって使用されるバイト単位での最大のディスク容量を強制的に設定します。
\n以下の API の呼び出し元スタックログを有効にします (イベントのフィルタリング)。
\ndesktopCapturer.getSources() / desktop-capturer-get-sources標準エラー出力 (またはログファイル) に Chromium のログを出力します。
\nELECTRON_ENABLE_LOGGING 環境変数への設定は --enable-logging を渡すのと同じ効果です。
--enable-logging を渡すと、標準エラー出力にログを出力すます。 --enable-logging=file を渡すと、ログは --log-file=... で指定したファイルに、--log-file が未指定の場合はユーザデータディレクトリの electron_debug.log に保存されます。
\n\n注意: Windows では、子プロセスからのログを標準エラー出力に送信できません。 Windows でのログ収集は、ファイルへのログ出力が最も信頼できる方法です。
\n
--log-file, --log-level, --v, --vmodule もご参照ください。
trialsフィールド トライアルを強制的に有効または無効にします。
\n例: WebRTC-Audio-Red-For-Opus/Enabled/
rulesホスト名をどのようにマッピングするかを制御する rules のコンマ区切りのリスト。
以下がその例です。
\nMAP * 127.0.0.1 は、すべてのホスト名を強制的に127.0.0.1にマッピングします。MAP *.google.com proxy は、すべてのgoogle.comのサブドメインを強制的に \"proxy\" で解決されるようにします。MAP test.com [::1]:77 は \"test.com\" を強制的に IPv6 ループバックへ解決されるようにします。 また、ソケットアドレスのポートを 77 に強制します。MAP * baz, EXCLUDE www.google.com は、\"www.google.com\" 以外のすべてを \"baz\" に再マッピングします。これらのマッピングは、ネットワークリクエストのエンドポイントのホスト (直接接続でのTCP接続とホストリゾルバー、HTTPプロキシ接続での CONNECT、SOCKS プロキシ接続でのエンドポイントホスト) に対して適用されます。
rules--host-rules と似ていますが、これらの rules は、ホストリゾルバーにしか適用されません。
証明書関連のエラーを無視します。
\ndomains, で区切られた domains リストに対する接続数の制限を無視します。
flagsNode.js エンジンへ渡されるフラグを指定します。 flags をメインプロセスで有効化したい場合は、 Electron の開始時に与えられる必要があります。
$ electron --js-flags=\"--harmony_proxies --harmony_collections\" your-app\n利用できるフラグの一覧については、Node.js のドキュメントを参照するか、ターミナルで node --help を実行してください。 さらに、Node.js の V8 JavaScript エンジンに関するフラグの一覧を具体的に見るには、node --v8-options を実行してください。
カスタムロケールを設定します。
\npath--enable-logging が指定された場合、ログを指定のパスに書き込みます。 その親ディレクトリは存在していなければなりません。
環境変数 ELECTRON_LOG_FILE への設定は、このフラグを渡すことと等価です。 両方とも存在する場合はコマンドラインスイッチを優先します。
path保存されるネットワークログイベントを有効にし、path にそれらを書き込みます。
N--enable-logging と一緒に使用することで、ログの詳細度を設定します。 N は ChromeのLogSeverities のいずれかでなければなりません。
注意として、Chromium の 2 つの相補的なログメカニズムである LOG() と VLOG() は、それぞれ別のスイッチで制御しています。 --log-level は LOG() のメッセージを制御しますが、--v と --vmodule は VLOG() のメッセージを制御します。 そのため、必要な詳細度やウォッチしようとしているコードで行われているロギング呼び出しに応じて、これら 3 つのスイッチを組み合わせて使用するとよいでしょう。
LOG() と VLOG() の相互作用の詳細については、Chromium ロギングのソース をご参照ください。 大まかに言えば、VLOG() は大量の LOG(INFO) データを制御する LOG(INFO) 内部のサブレベル / モジュールごとのレベルと考えられます。
--enable-logging, --log-level, --v, --vmodule もご参照ください。
プロキシサーバを使わず、常に直接接続を行います。 他に与えられたプロキシサーバのフラグをすべて上書きします。
\nChromium の サンドボックス を無効化します。 レンダラープロセスと Chromium ヘルパープロセスにサンドボックスなしの実行を強制します。 テスト時のみ使用すべきです。
\nhostsセミコロン区切りで与えられたホストに対してプロキシサーバを回避するように Electron へ指示します。 このフラグは —proxy-server と共に使用される場合のみ有効です。
以下がその例です。
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')\nローカルアドレス (localhost、127.0.0.1 など)、google.com のサブドメイン、foo.com で終わるホストと 1.2.3.4:5678 を除く、すべてのホストに対してプロキシサーバーが使用されます。
url指定した url のPACスクリプトを使用します。
address:portシステム設定よりも優先して、指定したプロキシサーバーを使用します。 このスイッチは、HTTPSとWebSocketリクエストを含むHTTPプロトコルでのリクエストにしか影響しません。 また、すべてのプロキシサーバーがHTTPSとWebSocketリクエストに対応している訳ではないことにも注意してください。 プロキシ URL は 各 Chromium issue でのユーザー名とパスワードによる認証をサポートしていません。
\nport指定された port でHTTP越しのリモートデバッグを有効にします。
log_level既定で有効な最高の V ロギングレベルを設定します。既定値は 0 です。 通常、正の値は V ロギングレベルに使用されます。
\nこのスイッチは、--enable-logging が一緒に渡されたときのみ機能します。
--enable-logging, --log-level, --vmodule もご参照ください。
pattern--v で指定された値を上書きするモジュール単位の最大のVログレベルを指定します。 以下は例です。 my_module=2,foo*=3 は、my_module.* と foo*.* のソースファイルにあるすべてのコードのログレベルを変更します。
スラッシュまたはバックスラッシュを含むパターンは、モジュールだけでなく全体のパス名に対してテストされます。 以下は例です。 */foo/bar/*=2 は、foo/bar ディレクトリの下にあるソースファイルのすべてのコードのログレベルを変更します。
このスイッチは、--enable-logging が一緒に渡されたときのみ機能します。
--enable-logging, --log-level, --v もご参照ください。
複数のGPUが利用可能な場合、離散GPUを強制的に使用します。
\n複数のGPUが利用可能な場合、統合GPUを強制的に使用します。
\nElectron は Node.js でサポートされている CLI フラグ の一部をサポートしています。
\n注: ELECTRON_RUN_AS_NODE で実行していないときに未サポートのコマンドラインスイッチを Electron に渡しても、効果はありません。
host:port でインスペクタを起動し、ユーザスクリプトの開始時にブレークします。 host:port の省略値は 127.0.0.1:9229 です。
\n--debug-brk=[host:]port のエイリアスです。
インスペクタが起動したときに使用する host:port を設定します。 SIGUSR1 シグナルを送信してインスペクタを起動するときに便利です。 host の省略値は 127.0.0.1 です。
--debug-port=[host:]port のエイリアスです。
host:port でインスペクタを有効にします。 省略値は 127.0.0.1:9229 です。
V8 インスペクタの統合により、Chrome デベロッパー ツールや IDE などのツールで Electron インスタンスのデバッグやプロファイルが可能になりました。 ツールは TCP ポートを介して Electron インスタンスにアタッチし、Chrome デベロッパー ツールプロトコル を使用して通信します。
\n詳細は メインプロセスのデバッグ ガイドを参照してください。
\n--debug[=[host:]port] のエイリアスです。
インスペクタの WebSocket URL の公開方法を指定します。
\nデフォルトでは、インスペクタの WebSocket URL は標準エラーで、http://host:port/json/list の /json/list エンドポイント下にあります。
", "title": "サポートしているコマンドラインスイッチ", "description": "Electronによってサポートされているコマンドラインスイッチ。" }, "/docs/api/content-tracing": { "locale": "ja-JP", "slug": "content-tracing", "href": "/docs/api/content-tracing", "crowdinFileId": "256297", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/content-tracing.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nChromium からトレースデータを収集して、パフォーマンスのボトルネックや遅い操作を見つけます。
\n
プロセス: Main
\nこのモジュールにはウェブインターフェイスが付属していません。 記録したトレースを見るには、トレースビュアー を使用します。Chrome では chrome://tracing で利用できます。
注: アプリモジュールの ready イベントが発生するまではこのモジュールを使用してはいけません。
const { app, contentTracing } = require('electron')\n\napp.whenReady().then(() => {\n (async () => {\n await contentTracing.startRecording({\n included_categories: ['*']\n })\n console.log('Tracing started')\n await new Promise(resolve => setTimeout(resolve, 5000))\n const path = await contentTracing.stopRecording()\n console.log('Tracing data recorded to ' + path)\n })()\n})\ncontentTracing モジュールには以下のメソッドがあります。
contentTracing.getCategories()戻り値 Promise<String[]> - すべての子プロセスが getCategories リクエストを受諾したとき、そのカテゴリグループの配列で解決されます。
カテゴリグループの集合を取得します。 新しいコードパスに到達したら、カテゴリグループは変更できます。 詳しくは 組み込みトレースカテゴリのリスト を参照してください。
\n\n\n注意: Electron は
\n\"electron\"という非デフォルトのトレースカテゴリを追加します。 このカテゴリは、Electron 固有のトレースイベントのキャプチャに使用できます。
contentTracing.startRecording(options)options (TraceConfig | TraceCategoriesAndOptions)戻り値 Promise<void> - すべての子プロセスが startRecording リクエストを受諾したときに解決されます。
すべてのプロセスで記録を開始します。
\nEnableRecordingリクエストを受信するとすぐにローカルでは即時、子プロセスでは非同期的に記録が開始されます。
\n記録を実行中の場合、promise はすぐに解決されます。一度に一つまでしかトレース操作は処理されません。
\ncontentTracing.stopRecording([resultFilePath])resultFilePath String (任意)戻り値 Promise<String> - すべての子プロセスが stopRecording リクエストを確認すると、トレースデータを格納したファイルへのパスで解決します
すべてのプロセスで記録を停止します。
\n子プロセスは、大抵、トレースデータをキャッシュし、滅多に書き出さず、メインプロセスにトレースデータを送り返すだけです。 トレースデータをIPC越しに送信するのは高負荷な操作であるため、これはトレースのランタイムオーバーヘッドを最小化するのに役立ちます。 そのため、トレースを終了するために、Chromium はすべての子プロセスに保留中のトレースデータをフラッシュするよう非同期に要求します。
\nトレースデータは resultFilePath へと書き込まれます。 resultFilePath が空であるか提供されていない場合、トレースデータは一時ファイルに書き込まれ、そのパスは promise で返されます。
contentTracing.getTraceBufferUsage()戻り値 Promise<Object> - トレースバッファの最大使用率の value と percentage を含むオブジェクトで実行されます。
value Numberpercentage Number完全な形式のパーセンテージとして、トレースバッファのプロセス間の最大使用率を取得します。
", "title": "contentTracing", "description": "Chromium からトレースデータを収集して、パフォーマンスのボトルネックや遅い操作を見つけます。" }, "/docs/api/context-bridge": { "locale": "ja-JP", "slug": "context-bridge", "href": "/docs/api/context-bridge", "crowdinFileId": "256299", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/context-bridge.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n分離されたコンテキスト間に、安全、双方向で同期されたブリッジを作成します
\n
プロセス: Renderer
\n分離されたプリロードスクリプトから API をレンダラーに公開する例を以下に示します。
\n// プリロード (隔離ワールド)\nconst { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing')\n }\n)\n// レンダラー (メインワールド)\n\nwindow.electron.doThing()\n\"メインワールド\" は、メインレンダラーコードが実行される JavaScript コンテキストです。 デフォルトでは、レンダラーでロードしたページはこのワールドでコードを実行します。
\nwebPreferences で contextIsolation が有効 (これは Electron 12.0.0 からの既定の動作) になっている場合、preload スクリプトは \"隔離ワールド\" で実行されます。 コンテキスト分離とその影響の詳細については、BrowserWindow のドキュメントを参照してください。
contextBridge モジュールには以下のメソッドがあります。
contextBridge.exposeInMainWorld(apiKey, api)apiKey String - window に API を注入するキー。 その API には window[apiKey] でアクセスできます。api Record - あなたの API です。この詳細と動作については下記を参照してください。exposeInMainWorld に指定する api は、Function、String、Number、Array、Boolean、または文字列のキーで Function、String、Number、Array、Boolean、同じ条件を満たすオブジェクトのいずれかの値の、入れ子でなければなりません。
Function 値は他のコンテキストへプロキシされ、他のすべての値は コピー か 凍結 されます。 API で送信されるデータ/プリミティブはイミュータブルであり、ブリッジの一方で更新しても他方のものは更新されません。
複雑な API の例を以下に示します。
\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing'),\n myPromises: [Promise.resolve(), Promise.reject(new Error('whoops'))],\n anAsyncFunction: async () => 123,\n data: {\n myFlags: ['a', 'b', 'c'],\n bootTime: 1234\n },\n nestedAPI: {\n evenDeeper: {\n youCanDoThisAsMuchAsYouWant: {\n fn: () => ({\n returnData: 123\n })\n }\n }\n }\n }\n)\ncontextBridge を介してバインドした Function 値は、コンテキストが分離されたままになるように Electron を介してプロキシされます。 これにより、以下に概説するいくつかの重要な制限が生じます。
引数、エラー、戻り値は、ブリッジを介して送信されるときに コピー されるため、使用できるのは特定の型のみです。 高水準なものは、使用したい型をシリアライズおよびデシリアライズして、同じように動作するオブジェクトにできます。 以下の型サポートの表に全てが載っています。
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| 種類 | 複雑さ | 引数サポート | 戻り値サポート | 制限事項 |
|---|---|---|---|---|
String | 単純 | ✅ | ✅ | なし |
Number | 単純 | ✅ | ✅ | なし |
Boolean | 単純 | ✅ | ✅ | なし |
Object | 複雑 | ✅ | ✅ | キーにはこの表の \"単純\" な型のみの使用をサポートしています。 値にはこの表のものをサポートしています。 プロトタイプの変更は削除されます。 カスタムクラスを送信すると、値はコピーされますが、プロトタイプはコピーされません。 |
Array | 複雑 | ✅ | ✅ | 制限は Object 型と同じです |
エラー | 複雑 | ✅ | ✅ | スローされるエラーもコピーされます。これにより、異なるコンテキストでスローされるためにエラーのメッセージとスタックトレースがわずかに変化する可能性があります。 |
Promise | 複雑 | ✅ | ✅ | Promise は、戻り値や実引数である場合にのみプロキシされます。 配列やオブジェクトにネストされた Promise は削除されます。 |
Function | 複雑 | ✅ | ✅ | プロトタイプの変更は削除されます。 クラスまたはコンストラクターを送信しても動作しません。 |
| 複製可能型 | 単純 | ✅ | ✅ | 複製可能型に関してはリンクのドキュメントを参照してください |
Element | 複雑 | ✅ | ✅ | プロトタイプの変更は削除されます。 カスタム要素の送信は動作しません。 |
Blob | 複雑 | ✅ | ✅ | なし |
Symbol | なし | ❌ | ❌ | Symbol はコンテキスト間でコピーできないため、削除されます |
関心のある型が上記の表にない場合、それはおそらくサポートされていません。
\ncontextBridge はプリロードスクリプトで使用でき、レンダラーが Node API へアクセスできるようにします。 上記のサポート型の表は、 contextBridge を介して公開する Node API にも適用されます。 注意として、Node API の多くはローカルシステムのリソースへのアクセスを許してしまいます。 信頼できない外部コンテンツにおいては、公開するグローバルや API について注意が必要です。
const { contextBridge } = require('electron')\nconst crypto = require('crypto')\ncontextBridge.exposeInMainWorld('nodeCrypto', {\n sha256sum (data) {\n const hash = crypto.createHash('sha256')\n hash.update(data)\n return hash.digest('hex')\n }\n})\nコンテキスト分離は、あなたのプレロード スクリプトと Electron の内部ロジックの両方が、 webContents でロードしたウェブサイトに対して別のコンテキストで実行されることを保証する機能です。 これは、ウェブサイトが Electron の内部にアクセスできないようにするためのセキュリティを向上させ、プリロードスクリプトがアクセスできる強力な API を防ぐために重要です。
つまり、プリロードスクリプトがアクセスできる window オブジェクトは、ウェブサイトがアクセスできるオブジェクトとは実際には 異なる オブジェクトであることを意味します。 例えば、コンテキストの分離が有効の場合、プリロードスクリプトで window.hello = 'wave' を設定してウェブサイトがこれにアクセスしようとしても、window.hello は undefined になります。
コンテキストの分離は Electron 12 からデフォルトで有効になっており、すべてのアプリケーション で推奨されているセキュリティ設定です。
\n\n\nコンテキストが分離されていない状態で、
\nwindow.X = apiObjectを使ってプリロードスクリプトから API を提供していました。 どうすればよいですか？
プリロードスクリプトからレンダラープロセスで読み込まれたウェブサイトに API を公開することは、ごく一般的な使用例です。 コンテキストの分離を無効にすると、プリロードスクリプトは、共通のグローバルな window オブジェクトをレンダラーと共有することになります。 そして、任意のプロパティをプリロードスクリプトに添付できます。
// コンテキストの分離が無効のプリロード\nwindow.myAPI = {\n doAThing: () => {}\n}\ndoAThing() 関数は、レンダラープロセスで直接使用できます。
// レンダラー内から公開された API を使用\nwindow.myAPI.doAThing()\nElectron には、これを楽に行うための専用モジュールがあります。 contextBridge モジュールは、プリロードスクリプトの分離したコンテキストから、ウェブサイトが実行されているコンテキストに API を 安全に 公開するために使用できます。 このAPIは以前と同様に window.myAPI のウェブサイトからもアクセスできます。
// コンテキストの分離が有効のプリロード\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n doAThing: () => {}\n})\n// レンダラー内から公開された API を使用\nwindow.myAPI.doAThing()\n上記の contextBridge ドキュメントを読んで、その制限を完全に理解してください。 例えば、カスタムプロトタイプやシンボルはブリッジで送信できません。
contextIsolation を有効にして、 contextBridge を使用するだけでは、すべてが安全であることにはなりません。 例えば、以下のコードは 危険です。
// ❌ 悪いコード\ncontextBridge.exposeInMainWorld('myAPI, {\n send: ipcRenderer.send\n})\nこれは、引数のフィルタリングなどを行うことなく、強力なAPIを直接公開します。 これにより、任意のウェブサイトが、設計者の望んでいない任意の IPC メッセージを送信できるようになります。 IPC ベースの API を公開する正しい方法は、IPCメッセージごとに1つのメソッドを提供することです。
\n// ✅ 良いコード\ncontextBridge.exposeInMainWorld('myAPI, {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nTypeScript で Electron アプリを構築している場合、コンテキストブリッジを介して公開される API に型を追加する必要があります。 型宣言ファイル で型を拡張しないと、レンダラーの window オブジェクトは正しい型になりません。
例えば、以下の preload.ts スクリプトについて考えましょう。
contextBridge.exposeInMainWorld('electronAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nrenderer.d.ts 型宣言ファイルを作成し、Window インターフェースをこのようにグローバルに拡張できます。
export interface IElectronAPI {\n loadPreferences: () => Promise<void>,\n}\n\ndeclare global {\n interface Window {\n electronAPI: IElectronAPI\n }\n}\nそうすることで、レンダラープロセスでスクリプトを書く際に、TypeScript コンパイラがグローバルな window オブジェクトの electronAPI プロパティを知ることができます。
window.electronAPI.loadPreferences()\nname String - The name of the cookie.value String - The value of the cookie.domain String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains.hostOnly Boolean (optional) - Whether the cookie is a host-only cookie; this will only be true if no domain was passed.path String (optional) - The path of the cookie.secure Boolean (optional) - Whether the cookie is marked as secure.httpOnly Boolean (optional) - Whether the cookie is marked as HTTP only.session Boolean (optional) - Whether the cookie is a session cookie or a persistent cookie with an expiration date.expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.sameSite String - The Same Site policy applied to this cookie. Can be unspecified, no_restriction, lax or strict.\n\nセッションのクッキーをクエリーしたり、変更したりします。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
Cookies クラスのインスタンスには、Session の cookies プロパティを使用してアクセスします。
以下がその例です。
\nconst { session } = require('electron')\n\n// すべてのクッキーをクエリーします。\nsession.defaultSession.cookies.get({})\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// 特定のurlに関連した全てのクッキーを問い合わせ\nsession.defaultSession.cookies.get({ url: 'http://www.github.com' })\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// 与えられたクッキーデータでクッキーをセット\n// 同等なクッキーが存在していた場合、それを上書きすることあり\nconst cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }\nsession.defaultSession.cookies.set(cookie)\n .then(() => {\n // 成功\n }, (error) => {\n console.error(error)\n })\nCookies のインスタンスでは、以下のイベントが利用できます。
戻り値：
\nevent Eventcookie Cookie - 変更された cookie。cause String - 以下のいずれかの値となる変更の原因。explicit - ユーザーのアクションによってクッキーが直接変更されました。overwrite - 上書きする挿入操作のため、クッキーが自動的に削除されました。expired - 有効期限切れのため、クッキーが自動的に削除されました。evicted - ガベージコレクション中にクッキーが自動的に破棄されました。expired-overwrite - クッキーが既に期限切れの有効期限で上書きされました。removed Boolean - クッキーが削除された場合、true、それ以外は、false。追加されたり、編集されたり、削除されたり、有効期限が切れたりすることによってクッキーが変更されたときに発生します。
\nCookies のインスタンスでは、以下のメソッドが利用できます。
cookies.get(filter)filter Objecturl String (任意) - url に関連付けられた Cookie を取得します。 空の場合は全ての URL の Cookie を取得します。name String (任意) - 名前でクッキーをフィルタリングします。domain String (任意) - クッキーのドメインと一致するか、ドメインが domains のサブドメインであるクッキーを取得します。path String (任意) - クッキーのパスが path と一致するクッキーを取得します。secure Boolean (任意) - Secureプロパティでクッキーをフィルタリングします。session Boolean (任意) - セッションまたは永続的クッキーでフィルタリングします。戻り値 Promise<Cookie[]> - cookie オブジェクトの配列で解決される Promise。
filter に一致するすべての cookie を取得するリクエストを送り、そのレスポンスで Promise を解決します。
cookies.set(details)details Objecturl String - クッキーに関連付けられるURL。 URL が不正な場合、 Promise は reject されます。name String (任意) - Cookie の名前。 省略された場合は既定で空になります。value String (任意) - Cookie の値。 省略された場合は既定で空になります。domain String (任意) - Cookie のドメインです。これはサブドメインでも有効になるように最初のドットで正規化されます。 省略された場合は既定で空になります。path String (optional) - Cookie のパス。 省略された場合は既定で空になります。secure Boolean (任意) - Cookie に Secure フラグがついているか。 Same Site=None 属性が使用されていない限り、デフォルトでは false となります。httpOnly Boolean (任意) - Cookie に HttpOnly フラグがついているか。 省略値は、false です。expirationDate Double (任意) - UNIX時間の秒数によるCookieの有効期限。 省略した場合、クッキーはセッションクッキーになり、セッション間では保持されなくなります。sameSite String (任意) - この Cookie に適用する SameSite ポリシー。 unspecified、no_restriction、lax、strict のいずれかにできます。 省略値は no_restriction です。戻り値 Promise<void> - cookie が設定されたときに解決される Promise。
cookie を details で設定します。
cookies.remove(url, name)url String - クッキーに関連付けられたURL。name String - 削除するクッキーの名前。戻り値 Promise<void> - cookie が削除されたときに解決される Promise。
url と name が一致する cookie を削除します。
cookies.flushStore()戻り値 Promise<void> - cookie ストアがフラッシュされたときに解決される Promise。
未書き込みのクッキーのデータをディスクに書き込みます。
", "title": "クラス: Cookies", "description": "セッションのクッキーをクエリーしたり、変更したりします。" }, "/docs/api/structures/cpu-usage": { "locale": "ja-JP", "slug": "cpu-usage", "href": "/docs/api/structures/cpu-usage", "crowdinFileId": "256419", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/cpu-usage.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "percentCPUUsage Number - Percentage of CPU used since the last call to getCPUUsage. First call returns 0.idleWakeupsPerSecond Number - The number of average idle CPU wakeups per second since the last call to getCPUUsage. First call returns 0. Will always return 0 on Windows.date Dateid String\n\n\nクラッシュレポートをリモートサーバーに送信します。
\n
以下は、Electron が外部サーバーにクラッシュレポートを自動送信するように設定する例です。
\nconst { crashReporter } = require('electron')\n\ncrashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })\nクラッシュレポートを受信して処理するサーバーをセットアップするには、以下のプロジェクトを使用することができます。
\n\nまた、サードパーティによる解決方法も使用できます。
\n\nクラッシュレポートは、アップロードされる前にアプリのユーザーデータディレクトリ下にあるディレクトリに一時保存されます (Windows と Mac では 'Crashpad'、Linux では 'Crash Reports' と呼びます)。 クラッシュし始める前に app.setPath('crashDumps', '/path/to/crashes') を呼び出すことで、このディレクトリをオーバーライドできます。
Windows と macOS において、Electron は crashpad を使用してクラッシュを監視し報告します。 Linux では、Electron は breakpad を使用します。 これは Chromium が動かす内部実装によるもので、将来的に変更される可能性があります。 特に crashpad は新しく、最終的には全プラットフォームで breakpad を置き換える可能性が高いです。
\nNode.js の child_process モジュールを使用していて、Linux 上でそれらのプロセスからクラッシュを報告したい場合、子プロセスのクラッシュレポーターを適切に初期化するために追加の手順が必要になります。 Mac や Windows のプラットフォームでは、子プロセスを自動的に監視する Crashpad を使用しているため不要です。
require('electron') は Node の子プロセスでは利用できないので、Node の子プロセスでは process オブジェクトの以下の API を利用することができます。 注意として、Linux では、Node の子プロセスはそれぞれ別々の breeakpad クラッシュレポーターのインスタンスを保持します。 これはレンダラーの子プロセスとは異なり、情報をメインプロセスに返してレポートする \"スタブ\" breakpad レポーターです。
process.crashReporter.start(options)crashReporter.start() をご参照ください。
process.crashReporter.getParameters()crashReporter.getParameters() をご参照ください。
process.crashReporter.addExtraParameter(key, value)crashReporter.addExtraParameter(key, value) をご参照ください。
process.crashReporter.removeExtraParameter(key)crashReporter.removeExtraParameter(key) をご参照ください。
crashReporter モジュールには以下のメソッドがあります。
crashReporter.start(options)options ObjectsubmitURL String (optional) - URL that crash reports will be sent to as POST. Required unless uploadToServer is false.productName String (任意) - 省略値は、app.name です。companyName String (任意) 非推奨 - { globalExtra: { _companyName: ... } } の非推奨な別名です。uploadToServer Boolean (任意) - クラッシュレポートをサーバーに送信するかどうか。 false の場合、クラッシュレポートは収集されてクラッシュのディレクトリに保存されますが、アップロードされません。 省略値は true です。ignoreSystemCrashHandler Boolean (任意) - true の場合、メインプロセスで発生したクラッシュをシステムクラッシュハンドラに転送しません。 省略値は false です。rateLimit Boolean (任意) macOS Windows - true の場合、アップロードされるクラッシュの数を 1 時間につき 1 つに制限します。 省略値は false です。compress Boolean (任意) - true の場合、クラッシュレポートは圧縮され Content-Encoding: gzip でアップロードされます。 省略値は true です。extra Record<String, String> (任意) - メインプロセスが生成するクラッシュレポートと一緒に送信される追加のキー/バリューアノテーションの文字列。 文字列のみをサポートしています。 子プロセスから生成されたクラッシュレポートはこれらの追加パラメータを含みません。子プロセスが生成したクラッシュにこれらを含める場合は、子プロセスから addExtraParameter を呼び出してください。globalExtra Record<String, String> (任意) - 任意のプロセスが生成したクラッシュレポートと一緒に送信される、追加のキー/バリューアノテーションの文字列。 これらのアノテーションは、クラッシュレポーターを起動すると変更できません。 グローバル追加パラメータとプロセス固有の追加パラメータの両方に同じキーが存在する場合、グローバルのものが優先されます。 デフォルトでは、 productName と、Electron のバージョンと同様のアプリのバージョンが含まれています。このメソッドは、他の crashReporter API を使用する前に呼ばれなければなりません。 このように初期化すると、crashpad ハンドラは、以降作成されたすべてのプロセスからクラッシュを収集します。 一度起動したクラッシュレポーターは無効にできません。
このメソッドは、アプリの起動時にできるだけ早く、できれば app.on('ready') の前に呼び出す必要があります。 レンダラープロセスの作成時にクラッシュレポーターが初期化されていない場合、そのレンダラープロセスはクラッシュレポーターに監視されません。
注: process.crash() でクラッシュを生成することで、クラッシュレポーターをテストできます。
注意: 最初の start 呼び出しの後に追加/更新された extra パラメータを送信する必要がある場合は、addExtraParameter を呼び出すことでできます。
注: extra、globalExtra で渡すパラメータや addExtraParameter で設定するパラメータは、キーと値の長さに制限があります。 キー名の長さは最大 39 バイト、値の長さは 127 バイト以下でなければなりません。 最大値より長い名前を持つキーは警告を出さずに無視されます。 キーの値が最大長より長ければ切り捨てられます。
注意: このメソッドはメインプロセスからのみ利用できます。
\ncrashReporter.getLastCrashReport()戻り値 CrashReport - 最後のクラッシュレポートの日付と ID。 アップロードされたクラッシュレポートだけを返します。例えば、クラッシュレポートがディスク上に存在したとしても、アップロードしていなければそれを返しません。 アップロードされたレポートがない場合これは、null を返します。
注意: このメソッドはメインプロセスからのみ利用できます。
\ncrashReporter.getUploadedReports()戻り値 CrashReport[]:
アップロードされたすべてのクラッシュレポートを返します。 各レポートには、日付とアップロードされた ID が含まれています。
\n注意: このメソッドはメインプロセスからのみ利用できます。
\ncrashReporter.getUploadToServer()戻り値 Boolean - レポートがサーバに送信されるべきかどうか。 start メソッドまたは setUploadToServer を通して設定されます。
注意: このメソッドはメインプロセスからのみ利用できます。
\ncrashReporter.setUploadToServer(uploadToServer)uploadToServer Boolean - レポートがサーバーに送信されるかどうか.これは通常、ユーザーの設定によって制御されます。 start が呼ばれるまでは何もしません。
注意: このメソッドはメインプロセスからのみ利用できます。
\ncrashReporter.addExtraParameter(key, value)key String - パラメータキー。39 バイト未満でなければなりません。value String - パラメータの値。127 バイト未満でなければなりません。クラッシュレポートで送信される追加のパラメータを設定します。 ここで指定された値は、start が呼ばれたときに extra オプションで設定された値に加えて送信されます。
この方法 (または crashReporter.start のextra パラメータ) で追加されたパラメータは、呼び出すプロセスに固有のものです。 メインプロセスに追加パラメータを追加しても、それらのパラメータはレンダラーや他の子プロセスからのクラッシュとは一緒に送信されません。 同様に、レンダラープロセスでパラメータを追加しても、他のレンダラープロセスやメインプロセスで発生するクラッシュでそれらのパラメータは送信されません。
注: パラメータはキーと値の長さに制限があります。 キー名の長さは 39 バイト未満、値の長さは 20320 バイト未満でなければなりません。 最大値より長い名前を持つキーは警告を出さずに無視されます。 キーの値が最大長より長ければ切り捨てられます。
\n注: Linux では、127 バイトより長い値は複数のキーに分割され、それぞれの長さが 127 バイトになります。 以下は例です。 addExtraParameter('foo', 'a'.repeat(130)) の場合、2 つにチャンク化されたキー foo__1 と foo__2 が生成され、1 つ目のキーには最初の 127 バイトが、2 つ目のキーには残りの 3 バイトが含まれます。 クラッシュレポートのバックエンドでは、この形式のキーをつなぎ合わせる必要があります。
crashReporter.removeExtraParameter(key)key String - パラメータキー。39 バイト未満でなければなりません。現在のパラメータセットから追加パラメータを削除します。 今後のクラッシュにこのパラメータは含まれなくなります。
\ncrashReporter.getParameters()戻り値 Record<String, String> - クラッシュレポーターの現在の '追加' パラメータ。
クラッシュレポーターは、以下のデータを submitURL に multipart/form-data の POST で送信します。
ver String - Electronのバージョン。platform String - 例えば、'win32'。process_type String - 例えば、'renderer'。guid String - 例えば、'5e1286fc-da97-479e-918b-6bfb0c3d1c72'。_version String - package.json内のバージョン。_productName String - crashReporterのoptions内のproductName。prod String - 基底にあるプロダクトの名前。 この場合は Electron です。_companyName String - crashReporterのoptions内のcompanyName。upload_file_minidump File - minidumpフォーマットのクラッシュレポート。crashReporterのoptions内のextraオブジェクトの全ての最上位プロパティ。scheme String - Custom schemes to be registered with options.privileges Object (optional)standard Boolean (optional) - Default false.secure Boolean (optional) - Default false.bypassCSP Boolean (optional) - Default false.allowServiceWorkers Boolean (optional) - Default false.supportFetchAPI Boolean (optional) - Default false.corsEnabled Boolean (optional) - Default false.stream Boolean (optional) - Default false.\"Native interfaces\" include the file picker, window border, dialogs, context menus, and more - anything where the UI comes from your operating system and not from your app. The default behavior is to opt into this automatic theming from the OS.
\nIf your app has its own dark mode, you should toggle it on and off in sync with the system's dark mode setting. これは、[prefer-color-scheme] CSS メディアクエリを使用することで可能です。
\nIf you want to manually switch between light/dark modes, you can do this by setting the desired mode in the themeSource property of the nativeTheme module. This property's value will be propagated to your Renderer process. Any CSS rules related to prefers-color-scheme will be updated accordingly.
macOS 10.14 Mojave にて、Apple は新しい システム全体のダークモード を全ての macOS コンピュータに導入しました。 あなたの Electron アプリにダークモードがある場合、nativeTheme API を使用してシステム全体のダークモード設定に従うようにできます。
macOS 10.15 Catalina にて、Apple は新しい \"自動\" ダークモードオプションを全ての macOS コンピュータに導入しました。 Catalina 上のこのモードで nativeTheme.shouldUseDarkColors と Tray API を正しく動作させるには、Electron >=7.0.0 を使用するか、古いバージョンの場合は Info.plist ファイルの NSRequiresAquaSystemAppearance を false に設定する必要があります。 Electron Packager と Electron Forge の両方には darwinDarkModeSupport オプション があり、アプリビルド時の Info.plist の変更を自動化します。
Electron > 8.0.0 を使用中でオプトアウトしたい場合は、Info.plist ファイルの NSRequiresAquaSystemAppearance キーを true に設定する必要があります。 Electron 8.0.0 以降では macOS 10.14 SDK を使用するため、このテーマ設定をオプトアウトすることはできません。ご注意ください。
ここでは、nativeTheme から派生したテーマカラーになる Electron アプリケーションの例を示します。 加えて、IPC チャンネルを利用したテーマの切り替えとリセットの制御もできます。
index.html ファイルから見ていきましょう。
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n <link rel=\"stylesheet\" type=\"text/css\" href=\"./styles.css\">\n</head>\n<body>\n <h1>Hello World!</h1>\n <p>Current theme source: <strong id=\"theme-source\">System</strong></p>\n\n <button id=\"toggle-dark-mode\">Toggle Dark Mode</button>\n <button id=\"reset-to-system\">Reset to System Theme</button>\n\n <script src=\"renderer.js\"></script>\n </body>\n</body>\n</html>\nそして styles.css ファイルです。
@media (prefers-color-scheme: dark) {\n body { background: #333; color: white; }\n}\n\n@media (prefers-color-scheme: light) {\n body { background: #ddd; color: black; }\n}\nこの例では、一対の要素を持つ HTML ページを描画しています。 <strong id=\"theme-source\"> 要素は現在選択されているテーマを示すもので、2 つの <button> 要素は制御用です。 CSS ファイルでは、prefers-color-scheme のメディアクエリを使用して <body> 要素の背景色とテキスト色を設定しています。
preload.js スクリプトで、window オブジェクトに darkMode という新しい API を追加します。 この API は、'dark-mode:toggle' と 'dark-mode:system' の 2 つの IPC チャンネルをレンダラープロセスへ公開します。 また、レンダラープロセスからのメッセージをメインプロセスに渡すため、toggle と system の 2 つのメソッドも代入しています。
const { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld('darkMode', {\n toggle: () => ipcRenderer.invoke('dark-mode:toggle'),\n system: () => ipcRenderer.invoke('dark-mode:system')\n})\nこれで、レンダラープロセスはメインプロセスと安全に通信し、nativeTheme オブジェクトに必要な変更操作ができます。
renderer.js ファイルは、<button> の機能を制御する役割を担います。
document.getElementById('toggle-dark-mode').addEventListener('click', async () => {\n const isDarkMode = await window.darkMode.toggle()\n document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'\n})\n\ndocument.getElementById('reset-to-system').addEventListener('click', async () => {\n await window.darkMode.system()\n document.getElementById('theme-source').innerHTML = 'System'\n})\naddEventListener を使って、renderer.js ファイルで 'click' イベントリスナー を各ボタン要素に追加します。 各イベントリスナーハンドラーには、それぞれの window.darkMode API メソッドの呼び出しをさせます。
最後に、main.js ファイルでメインプロセスを記述し、実際の nativeTheme の API を入れます。
const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n\n ipcMain.handle('dark-mode:toggle', () => {\n if (nativeTheme.shouldUseDarkColors) {\n nativeTheme.themeSource = 'light'\n } else {\n nativeTheme.themeSource = 'dark'\n }\n return nativeTheme.shouldUseDarkColors\n })\n\n ipcMain.handle('dark-mode:system', () => {\n nativeTheme.themeSource = 'system'\n })\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nipcMain.handle メソッドは、HTML ページ上のボタンからのクリックイベントに対して、メインプロセスが応答する手段となります。
'dark-mode:toggle' IPC チャンネルハンドラーのメソッドは、shouldUseDarkColors 真偽値型プロパティを確認して対応する themeSource を設定し、現在の shouldUseDarkColors プロパティを返します。 この IPC チャンネルに対応するレンダラープロセスのイベントリスナーへと戻って見てみると、このハンドラーの戻り値を利用して <strong id='theme-source'> 要素に正しいテキストを代入しています。
'dark-mode:system' IPC チャンネルハンドラーのメソッドは、文字列'system' を themeSource に割り当てるだけで何も返しません。 これは対応するレンダラープロセスのイベントリスナーにも言えることで、このメソッドは戻り値が期待できない状態で待機しています。
Electron Fiddle を使ってサンプルを実行してみましょう。\"Toggle Dark Mode\" ボタンをクリックすると、アプリの背景色が明るくなったり暗くなったりするでしょう。
\n
JavaScript アプリケーションに起因しないと思われるクラッシュや問題が Electron 上で起こった場合、特にネイティブ/ C++ デバッグの経験がない開発者にとって少しトリッキーなデバッグになります。 しかし、Visual Studio、Electron がホストするシンボルサーバーと Electron のソースコードを使用することで、Electron のソースコード内のブレークポイントを使ったステップスルーデバッグができます。
\nこちらも参照: Chromium のデバッグに関する豊富な情報があります。その多くは Chromium 開発者サイト (Debugging Chromium on Windows) の Electron にも適しています。
\nElectronのデバッグビルド: 最も簡単な方法は、ビルド手順 (Windows) にリストされているツールと必要な環境を使って、自分でビルドをする方法です。 Electron を直接ダウンロードしてアタッチしデバッグできますが、Electron は高度に最適化されているためデバッグが困難であることに気付くでしょう。デバッガはすべての変数の内容は表示できませんし、インラインに展開されたり、末尾再帰やその他のコンパイラによる最適化により実行経路は奇妙に見えるはずです。
\nVisual Studio with C++ Tools: Visual Studio 2013 と Visual Studio 2015 の無料コミュニティ版両方が動きます。 インストール後、Electron のシンボルサーバーを使うための設定を行います。 これによりVisual StudioがElectron内で起こっていることをより理解できるようになり、人が読める形式で現在の変数を表示することができます。
\nProcMon: 無料の SysInternals ツールを使うことでプロセスパラメーター、ファイル操作、レジストリ操作を検査することができます。
\nデバッグセッションを始めるには、PowerShell/CMD を開いて Electron のデバッグビルドを実行し、引数として開くアプリケーションを渡して使用します。
\n$ ./out/Testing/electron.exe ~/my-electron-app/\nそして、Visual Studio を開きます。 Electron は Visual Studio でビルドされていないため、プロジェクトファイルは含まれていません。しかし、ソースコードファイルを \"ファイルとして\" 開くことができます。つまり、Visual Studio がそれ単独で開きます。 ブレークポイントを設定することもできます。 Visual Studio は、ソースコードがアタッチされたプロセスで実行されているコードと一致することを自動的に認識し、それに応じてブレークします。
\n関連コードファイルは ./shell/ にあります。
ローカルまたはリモートコンピュータ上で実行中のプロセスに Visual Studio デバッガをアタッチできます。 プロセスを実行中にしてから、\"プロセスにアタッチ\" ダイアログを開くためにプロセスにデバッグ/アタッチをクリック (または CTRL+ALT+P を押下) します。 この機能を使用してローカルまたはリモートコンピュータ上で実行されているアプリをデバッグし、複数のプロセスを同時にデバッグすることができます。
Electron が異なるユーザアカウントで実行されている場合、すべてのユーザからのプロセスを表示する チェックボックスを選択してください。 開かれているアプリの BrowserWindow の数に応じて、複数のプロセスが表示されることに注意してください。 典型的な1ウインドウアプリは、Visual Studio に2つの Electron.exe エントリ - メインプロセス用とレンダラプロセス用を表示します。 リストは名前だけを表示するので、どちらがどちらであるかを把握する信頼できる方法は現在ありません。
メインプロセス内から実行するコード (すなわちメイン JavaScript ファイル内から見られるコードまたは最終的に実行するコード) はメインプロセスで実行され、その他のコードはそれぞれのレンダラープロセスで実行されます。
\nデバッグ中は複数のプログラムにアタッチすることができますが、随時1つのプログラムだけがデバッガでアクティブになります。 デバッグの場所 ツールバーか プロセスウインドウ 内でアクティブなプログラムをセットできます。
Visual Studio は特定のコードパスを検査するのには優れていますが、ProcMon の強みは、アプリケーションのオペレーティングシステムで行われているすべてのことを実際に監視していることです。プロセスのファイル、レジストリ、ネットワーク、プロセス、プロファイリングの詳細をキャプチャします。 すべてのイベントをログに記録しようするので非常に巨大になる可能性がありますが、アプリケーションがオペレーティングシステムに対して何をどのようにして行っているのかを理解しようとするには価値のあるリソースになるかもしれません。
\nProcMon の基本及び高度なデバッグ機能については、Microsoft が提供する このビデオチュートリアル を参照してください。
", "title": "Windows におけるデバッグ", "description": "" }, "/docs/api/debugger": { "locale": "ja-JP", "slug": "debugger", "href": "/docs/api/debugger", "crowdinFileId": "256305", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/debugger.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nChromeのリモートデバッグプロトコルに対する選択肢の1つ。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
Chromeの開発者ツールは、ページと相互にやり取りをしたり、ページを調整したりすることのできるJavaScriptランタイムに特別なバインディングを持っています。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\ntry {\n win.webContents.debugger.attach('1.1')\n} catch (err) {\n console.log('Debugger attach failed : ', err)\n}\n\nwin.webContents.debugger.on('detach', (event, reason) => {\n console.log('Debugger detached due to : ', reason)\n})\n\nwin.webContents.debugger.on('message', (event, method, params) => {\n if (method === 'Network.requestWillBeSent') {\n if (params.request.url === 'https://www.github.com') {\n win.webContents.debugger.detach()\n }\n }\n})\n\nwin.webContents.debugger.sendCommand('Network.enable')\n戻り値：
\nevent Eventreason String - デバッガーがデタッチする理由。デバッグセッションが終了したときに発生します。 これは、webContents がクローズされるか、アタッチしていた webContents に対して開発者ツールが呼び出されるときに発生します。
戻り値：
\nevent Eventmethod String - メソッド名。params any - リモートデバッグプロトコルの 'parameters' 属性で定義されたイベントパラメータ。sessionId String - アタッチされたデバッグセッションの一意な識別子で、debugger.sendCommand から送られる値と同じです。デバッグ対象で計測イベントが生じる毎に発生します。
\ndebugger.attach([protocolVersion])protocolVersion String (任意) - リクエストしたデバッグプロトコルのバージョン。webContents にデバッガーをアタッチします。
debugger.isAttached()戻り値 Boolean - webContents にデバッガーがアタッチされているかどうか。
debugger.detach()webContents からデバッガーをデタッチします。
debugger.sendCommand(method[, commandParams, sessionId])method String - メソッド名。リモートデバッグプロトコル で定義されているメソッドのいずれかである必要があります。commandParams any (任意) - リクエストパラメータの JSON オブジェクト。sessionId String (任意) - デバッグセッション ID に関連付けられたターゲットにコマンドを送信します。 初期値は Target.attachToTarget メッセージを送信することで取得できます。戻り値 Promise<any> - リモートデバッグプロトコル内のコマンドの説明の 'returns' 属性で定義されたレスポンスで解決されるか、またはコマンドの失敗を示すために拒否されるプロミス。
指定したコマンドをデバッグ対象に送信します。
", "title": "クラス: Debugger", "description": "Chromeのリモートデバッグプロトコルに対する選択肢の1つ。" }, "/docs/development/debugging-instructions-macos": { "locale": "ja-JP", "slug": "debugging-instructions-macos", "href": "/docs/development/debugging-instructions-macos", "crowdinFileId": "256153", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "JavaScript アプリケーションに起因しないと思われるクラッシュや問題が Electron 上で起こった場合、特にネイティブ/ C++ デバッグの経験がない開発者にとって少しトリッキーなデバッグになります。 しかし、lldb と Electron のソースコードを使用することで、Electron のソースコード内でブレークポイントを使用したステップ実行デバッグを有効にできます。 グラフィカルインタフェースを希望する場合は、Xcode におけるデバッグ を使用することもできます。
\nElectronのデバッグビルド: 最も簡単な方法は、ビルド手順 (macOS) にリストされているツールと必要な環境を使って、自分でビルドをする方法です。 Electron を直接ダウンロードしてアタッチしデバッグできますが、Electron は高度に最適化されているためデバッグが困難であることに気付くでしょう。デバッガはすべての変数の内容は表示できませんし、インラインに展開されたり、末尾再帰やその他のコンパイラによる最適化により実行経路は奇妙に見えるはずです。
\nXcode: Xcode では、加えて Xcode コマンドラインツールもインストールします。 macOS の XCode には、デフォルトのデバッガの LLDB が入っています。 C、Objective-C、C++ のデバッグを、デスクトップ、iOS デバイス、シミュレータ上でサポートします。
\n.lldbinit: ~/.lldbinit を以下のように作成及び編集し、Chromium コードを適切にソースマップできるようにします。
# 例: ['~/electron/src/tools/lldb']\nscript sys.path[:0] = ['<...path/to/electron/src/tools/lldb>']\nscript import lldbinit\nデバッグセッションを始めるには、ターミナルを開いて Electron のリリースでないビルドを引数として渡して lldb を実行します。
$ lldb ./out/Testing/Electron.app\n(lldb) target create \"./out/Testing/Electron.app\"\nCurrent executable set to './out/Testing/Electron.app' (x86_64).\nLLDBは強力なツールであり、コード検査のための複数の計画をサポートします。 この基本的な導入では、正しく動作していないコマンドを JavaScript から呼び出していると仮定しましょう。Electron ソース内に対応するコマンドの C++をブレークしたいとします。
\n関連コードファイルは ./shell/ にあります。
browser.cc 内に Browser::SetName() として定義されている app.setName() をデバッグしたいと仮定しましょう。 breakpoint コマンドを用いて、以下のようにブレークするファイルと行を指定してブレークポイントを設定します。
(lldb) breakpoint set --file browser.cc --line 117\nBreakpoint 1: where = Electron Framework`atom::Browser::SetName(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) + 20 at browser.cc:118, address = 0x000000000015fdb4\nそして、 Electron を実行します。
\n(lldb) run\nElectron は起動時にアプリの名前を設定するため、アプリはすぐに一時停止されます。
\n(lldb) run\nProcess 25244 launched: '/Users/fr/Code/electron/out/Testing/Electron.app/Contents/MacOS/Electron' (x86_64)\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1\n frame #0: 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118\n 115 }\n 116\n 117 void Browser::SetName(const std::string& name) {\n-> 118 name_override_ = name;\n 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n(lldb)\n現在のフレームの引数とローカル変数を表示するには、frame variable (または fr v) を実行します。アプリの名前が現在は \"Electron\" にセットされているのが表示されるでしょう。
(lldb) frame variable\n(atom::Browser *) this = 0x0000000108b14f20\n(const string &) name = \"Electron\": {\n [...]\n}\n現在のスレッド内でソースレベルステップ実行するには、step (または s) を実行します。 これにより、name_override_.empty() に飛びます。 処理してステップオーバーするには、next (または n) を実行します。
(lldb) step\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119, queue = 'com.apple.main-thread', stop reason = step in\n frame #0: 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119\n 116\n 117 void Browser::SetName(const std::string& name) {\n 118 name_override_ = name;\n-> 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n 122 return badge_count_;\n注意: 表示しようとしてもソースコードが表示されない場合は、上記の ~/.lldbinit ファイルを追加していない可能性があります。
このポイントでのデバッグが完了したら、process continue を実行します。 このスレッドで特定の行がヒットするまで (thread until 100) 続行することもできます。 このコマンドは、このフレームの100行目に達するまで、現在のフレーム内のスレッドを実行し、現在のフレームを終了すると停止します。
今、Electron の開発者ツールを開いて setName を呼び出すと、もう一度ブレークポイントにヒットします。
LLDB は素晴らしいドキュメントを備えた強力なツールです。 詳細については、LLDB コマンド構造リファレンス や LLDB をスタンドアロンデバッガとして使用する方法 などの Apple のデバッグドキュメントを参照してください。
\nLLDB の素晴らしい マニュアルとチュートリアル もご参考ください。さらに複雑なデバッグシナリオについて説明されています。
", "title": "macOS におけるデバッグ", "description": "" }, "/docs/development/debugging-instructions-macos-xcode": { "locale": "ja-JP", "slug": "debugging-instructions-macos-xcode", "href": "/docs/development/debugging-instructions-macos-xcode", "crowdinFileId": "256151", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos-xcode.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "gn gen に --ide=xcode 引数を加えて実行します。
$ gn gen out/Testing --ide=xcode\nこれで、electron.ninja.xcworkspace を生成します。 このワークスペースを開いて、ブレークポイントをセットしてインスペクトしなければなりません。
\nGNでIDEプロジェクトの生成についての情報を見るには、gn help genを見てください。
ビルド後にElectronアプリを起動します。 上記で作成した Xcode ワークスペースを開いて、デバッグ > プロセスにアタッチ > Electron デバッグメニューから Electron プロセスにアタッチすることができます。 [注意: レンダラープロセスをデバッグする場合は、Electron Helper にもアタッチする必要があります。]
\nインデックスファイル内のどこにでもブレークポイントを設定することができます。 ただし、Chromium ソース内でブレークポイントを直接設定することはできません。 Chromium ソース内でブレークポイントを設定するには、デバッグ > ブレークポイント > シンボリックブレークポイントの作成 を選択し、関数名をシンボルとして設定します。 これは、一つ以上クラスがある場合は、そのうちのすべてのクラスから、その名前を持つすべての関数のブレークポイントを設定します。 デバッガをアタッチする前にブレークポイントを設定する手順を実行することもできますが、シンボリックブレークポイント関数の実際のブレークポイントは、デバッガがアプリにアタッチされるまで表示されないことがあります。
", "title": "Xcodeでのデバッグ", "description": "" }, "/docs/tutorial/debugging-main-process": { "locale": "ja-JP", "slug": "debugging-main-process", "href": "/docs/tutorial/debugging-main-process", "crowdinFileId": "256189", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/debugging-main-process.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron ブラウザウィンドウのデベロッパー ツールは、そのウィンドウで実行されている JavaScript (例えばウェブページ) のみをデバッグできます。 メインプロセスの JavaScript をデバッグしたい場合は、Electron を --inspect や --inspect-brk フラグで起動し、外部デバッガを使用する必要があります。
Electron のメインプロセスをデバッグするためには、以下のコマンドラインスイッチを使用します。
\n--inspect=[port]Electron は、指定された port で V8 インスペクタープロトコルのメッセージを受け取ります。外部デバッガはこのポートに接続する必要があります。 デフォルトの port は 5858 です。
electron --inspect=5858 your/app\n--inspect-brk=[port]--inspect と同様ですが、最初の行でスクリプトを中断します。
V8 インスペクタープロトコルをサポートするデバッガを使用する必要があります。
\nchrome://inspect を開いて Chrome に接続し、起動した Electron アプリのインスペクトをそこから選択します。このガイドでは、自作の Electron プロジェクトとネイティブの Electron コードベース両方の VSCode デバッグを設定する方法について説明します。
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json ファイルを追加する{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"Debug Main Process\",\n \"type\": \"node\",\n \"request\": \"launch\",\n \"cwd\": \"${workspaceFolder}\",\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron\",\n \"windows\": {\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron.cmd\"\n },\n \"args\" : [\".\"],\n \"outputCapture\": \"std\"\n }\n ]\n}\nmain.js にいくつかブレークポイントを設定し 、デバッグ ビュー からデバッグを開始します。 このとき設定したブレークポイントにヒットするはずです。
ここではダウンロードして直接 VSCode 内でデバッグできる構成済みのプロジェクトを用意しています: https://github.com/octref/vscode-electron-debug/tree/master/electron-quick-start
\nソースから Electron をビルドしてネイティブの Electron コードベースを変更したい場合は、このセクションを参照してください。
\nこのコードの入手方法やビルド方法がわからない方のために、Electron のビルドツール がこのプロセスのほとんどを自動化して説明します。 手動で環境を設定したい場合は、代わりに以下の ビルド手順 も使用できます。
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json ファイルを追加する{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"(Windows) Launch\",\n \"type\": \"cppvsdbg\",\n \"request\": \"launch\",\n \"program\": \"${workspaceFolder}\\\\out\\\\your-executable-location\\\\electron.exe\",\n \"args\": [\"your-electron-project-path\"],\n \"stopAtEntry\": false,\n \"cwd\": \"${workspaceFolder}\",\n \"environment\": [\n {\"name\": \"ELECTRON_ENABLE_LOGGING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_ENABLE_STACK_DUMPING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_RUN_AS_NODE\", \"value\": \"\"},\n ],\n \"externalConsole\": false,\n \"sourceFileMap\": {\n \"o:\\\\\": \"${workspaceFolder}\",\n },\n },\n ]\n}\n設定メモ
\ncppvsdbg は 組み込み C/C++ 拡張 が有効である必要があります。${workspaceFolder} Chromium の src ディレクトリのフルパスです。your-executable-location はいくつかの項目に応じて以下のいずれかになります。Testing: Electron のビルドツール のデフォルト設定や、ソースからビルド でのデフォルト指定を使用している場合。Release: Testing ビルドではなく Release ビルドで構築した場合。your-directory-name: ビルド処理中にこれをデフォルトから変更した場合は、指定したものがそのまま適用されます。args 配列文字列内の \"your-electron-project-path\" は、テストに用する Electron プロジェクトのディレクトリまたは main.js ファイルへの絶対パスでなければなりません。 このサンプルでは、 electron-quick-start へのパスである必要があります。ネイティブの Electron C++ コード内の任意の .cc ファイルにブレークポイントを設定し、デバッグビュー でデバッグを開始しましょう。
", "title": "VS Code でデバッグする", "description": "" }, "/docs/api/desktop-capturer": { "locale": "ja-JP", "slug": "desktop-capturer", "href": "/docs/api/desktop-capturer", "crowdinFileId": "256307", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/desktop-capturer.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n\n\n
navigator.mediaDevices.getUserMediaAPIを使用して、デスクトップからの音声と映像のキャプチャに利用できるメディアソース関連の情報にアクセスします。
以下の例では、タイトルが Electron であるデスクトップウインドウからビデオをキャプチャする方法を示します。
// レンダラープロセス\nconst { desktopCapturer } = require('electron')\n\ndesktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources => {\n for (const source of sources) {\n if (source.name === 'Electron') {\n try {\n const stream = await navigator.mediaDevices.getUserMedia({\n audio: false,\n video: {\n mandatory: {\n chromeMediaSource: 'desktop',\n chromeMediaSourceId: source.id,\n minWidth: 1280,\n maxWidth: 1280,\n minHeight: 720,\n maxHeight: 720\n }\n }\n })\n handleStream(stream)\n } catch (e) {\n handleError(e)\n }\n return\n }\n }\n})\n\nfunction handleStream (stream) {\n const video = document.querySelector('video')\n video.srcObject = stream\n video.onloadedmetadata = (e) => video.play()\n}\n\nfunction handleError (e) {\n console.log(e)\n}\ndesktopCapturer が提供するソースから映像をキャプチャするには、navigator.mediaDevices.getUserMedia に渡す制約に、chromeMediaSource: 'desktop' と audio: false を含める必要があります。
デスクトップ全体から音声と映像の両方をキャプチャするには、navigator.mediaDevices.getUserMedia に渡す制約に、audio と video の両方に対して chromeMediaSource: 'desktop' を含める必要がありますが、chromeMediaSourceId 制約は不要です。
const constraints = {\n audio: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n },\n video: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n }\n}\ndesktopCapturer モジュールには以下のメソッドがあります。
desktopCapturer.getSources(options)options Objecttypes String[] - キャプチャされるデスクトップソースの種別を列挙した文字列の配列。指定できる種別は、screen と window です。thumbnailSize Size (任意) - メディアソースのサムネイルを拡大縮小するサイズ。 省略値は 150 x 150 です。 サムネイルが不要な場合は、幅または高さを 0 に設定してください。 これにより、各ウィンドウおよび画面のコンテンツをキャプチャするために必要な処理時間が節約されます。fetchWindowIcons Boolean (任意) - ウィンドウアイコンの取得を有効にするには true に設定します。 デフォルト値は false です。 false の場合、ソースの appIcon プロパティは null を返します。 ソースが screen 型の場合も同様です。戻り値 Promise<DesktopCapturerSource[]> - DesktopCapturerSource オブジェクトの配列を使用して解決します。各 DesktopCapturerSource は、キャプチャできる画面または個々のウィンドウを表します。
注釈 画面コンテンツをキャプチャするには、macOS 10.15 Catalina 以降でのユーザーの同意が必要です。同意しているかどうかは systemPreferences.getMediaAccessStatusで検知できます。
navigator.mediaDevices.getUserMedia はシステムのオーディオにアクセスしたいアプリが署名付きカーネル拡張を必要とするという基本的な制限のため、macOS ではオーディオキャプチャが動作しません。 Chrome、ひいては Electron はこれを提供していません。
Soundflower のような他の macOS アプリでシステムオーディオをキャプチャし、それを仮想オーディオ入力デバイスに渡すことでこの制限を回避することが可能です。 この仮想デバイスは、 navigator.mediaDevices.getUserMedia.を使用して照会できます。
id String - The identifier of a window or screen that can be used as a chromeMediaSourceId constraint when calling [navigator.webkitGetUserMedia]. The format of the identifier will be window:XX:YY or screen:ZZ:0. XX is the windowID/handle. YY is 1 for the current process, and 0 for all others. ZZ is a sequential number that represents the screen, and it does not equal to the index in the source's name.name String - A screen source will be named either Entire Screen or Screen <index>, while the name of a window source will match the window title.thumbnail NativeImage - A thumbnail image. Note: There is no guarantee that the size of the thumbnail is the same as the thumbnailSize specified in the options passed to desktopCapturer.getSources. The actual size depends on the scale of the screen or window.display_id String - A unique identifier that will correspond to the id of the matching Display returned by the Screen API. On some platforms, this is equivalent to the XX portion of the id field above and on others it will differ. It will be an empty string if not available.appIcon NativeImage - An icon image of the application that owns the window or null if the source has a type screen. The size of the icon is not known in advance and depends on what the application provides.Chromium ベースのブラウザのように、Electron はウェブ API を介してデバイスハードウェアへのアクセスを提供します。 ほとんどの場合これらの API はブラウザと同じように動作しますが、いくつかの違いを考慮しなければなりません。 Electronとブラウザの主な違いは、デバイスアクセスが要求されたときに起きることです。 ブラウザでは、ユーザーにポップアップが表示され、ユーザーは個々のデバイスにアクセスを許可できます。 Electron API では、デバイスを自動選択したり開発者が作成したインターフェースを介してユーザーにデバイス選択を促したりするために、開発者が利用できる API を提供しています。
\nウェブ Bluetooth API は、Bluetooth デバイスとの通信に利用できます。 この API を Electron で使用するには、開発者がデバイスリクエストに関連するwebContents の select-bluetooth-device イベント をハンドリングする必要があります。
この例では、Test Bluetooth ボタンがクリックされたときに最初に利用可能な Bluetooth デバイスを自動的に選択する、Electron のアプリケーションを示しています。
WebHID API は、キーボードやゲームパッドなどの HID デバイスのアクセスに利用できます。 Electron は、WebHID API と連携するためにいくつかの API を提供しています。
\nselect-hid-device イベント は、navigator.hid.requestDevice が呼び出された時に HID デバイスを選択するために利用できます。 さらに、Session の hid-device-added および hid-device-removed イベントは、navigator.hid.requestDevice の処理中におけるデバイスの接続や除去の処理に利用できます。ses.setDevicePermissionHandler(handler) は、先に navigator.hid.requestDevice を介して許可の呼び出しをせずとも、デバイスへのデフォルトの権限を提供するために利用できます。 また、Electron のデフォルトの動作では、付与されたデバイスの権限を対応する WebContents が有効の間だけ保存します。 より長期間の保存が必要な場合、開発者は付与されたデバイスのパーミッションを保存し (select-hid-device イベントを処理するときなど)、setDevicePermissionHandler でそのストレージから読み出しできます。ses.setPermissionCheckHandler(handler) を使うと、特定オリジンの HID アクセスを無効にできます。デフォルトでは、Electron は Chromium が使用する ブロックリスト と同じものを採用しています。 この動作を無効にしたい場合は、以下のように disable-hid-blocklist フラグで設定できます。
app.commandLine.appendSwitch('disable-hid-blocklist')\nこの例では、ses.setDevicePermissionHandler(handler) を通じて HID デバイスを自動選択する Electron アプリケーションを示しています。Test WebHID ボタンがクリックされると、Session の select-hid-device イベントを通じて HID デバイスを自動選択します。
Web シリアル API を使用すると、シリアルポートや USB、Bluetooth で接続されたシリアルデバイスにアクセスできます。 この API を Electron で使用には、開発者がシリアルポートのリクエストに関する Session の select-serial-port イベント をハンドリングする必要があります。
Web シリアル API の利用にあたって更にいくつかの API があります。
\nserial-port-added と serial-port-removed イベントは、navigator.serial.requestPort の処理中におけるデバイスの接続や除去のハンドリングに使用できます。ses.setPermissionCheckHandler(handler) を使うと、特定オリジンのシリアルアクセスを無効にできます。この例で示している Electron アプリケーションは、Test Web Serial ボタンがクリックされたときに、Session の select-serial-port イベント を通して最初に利用可能な Arduino Uno シリアルデバイスを (接続されている場合は) 自動選択します。
Electron は Chrome デベロッパー ツール拡張 をサポートしています。これは人気ウェブフレームワークのデバッグ向けに Chrome デベロッパー ツールを拡張できます。
\nデベロッパー ツール拡張を読み込む最も簡単な方法は、サードパーティ製ツールで手順を自動化することです。 electron-devtools-installer はこれを行うにあたって人気の NPM パッケージです。
\nツールを使う手段をお望みでない場合は、必要な作業すべてを手で行うこともできます。 Electron で拡張機能を読み込むには、Chrome でそれをダウンロードして、そのファイルシステムのパスを探し、[ses.loadExtension] API を呼び出して Session にロードします。
以下は React Developer Tools を使用する例です。
\nGoogle Chrome で拡張機能をインストールします。
\nchrome://extensions に移動し、fmkadmapgofadopljbjfkapdkoienihi のようなハッシュ文字列であるそれの拡張 ID を探します。
Chrome が拡張機能の保存に使用している、ファイルシステムの場所を調べます。
\n%LOCALAPPDATA%\\Google\\Chrome\\User Data\\Default\\Extensions です。~/.config/google-chrome/Default/Extensions/~/.config/google-chrome-beta/Default/Extensions/~/.config/google-chrome-canary/Default/Extensions/~/.config/chromium/Default/Extensions/~/Library/Application Support/Google/Chrome/Default/Extensions になります。拡張機能の場所をses.loadExtension API に渡します。 React Developer Tools v4.9.0 の場合、以下のようになります。
const { app, session } = require('electron')\n const path = require('path')\n const os = require('os')\n\n // macOS の場合\n const reactDevToolsPath = path.join(\n os.homedir(),\n '/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.9.0_0'\n )\n\n app.whenReady().then(async () => {\n await session.defaultSession.loadExtension(reactDevToolsPath)\n })\n注釈:
\nloadExtension は Extension オブジェクト の Promise を返します。これには、読み込まれた拡張機能についてのメタデータが含まれます。 この Promise はページ読み込み前に (await 式などで) 解決する必要があります。 さもなくば、拡張の読み込みは保証されません。loadExtension は、app モジュールの readyイベントが発生する前には呼び出せず、インメモリ (非永続) セッションでも呼び出せません。loadExtension を呼び出す必要があります。拡張の ID を ses.removeExtension API に渡すことで、Session から拡張を削除できます。 これにより、読み込んだ拡張がアプリの次回起動時にも保持されることはなくなります。
Electron は chrome.* API のうち限られたいくつか のみをサポートしています。未サポートの chrome.* API を使用した拡張機能は動作しない可能性があります。
以下のデベロッパー ツール拡張は Electron での動作がテストされています。
\nまず、拡張がメンテナンスされていて、最新の Google Chrome と互換性があるかどうかを確認してください。 未サポートの拡張については、さらなるサポートを提供できません。
\n拡張機能が Chrome で動作しているのに Electron で動作しない場合は、Electron の Issue トラッカー にバグ報告し、拡張機能のどの部分が期待通りに動作しないかをご説明ください。
", "title": "DevTools エクステンション", "description": "" }, "/docs/api/dialog": { "locale": "ja-JP", "slug": "dialog", "href": "/docs/api/dialog", "crowdinFileId": "256309", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/dialog.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nファイルを開いたり、保存したり、アラートを出したりするために、ネイティブのシステムダイアログを表示します。
\n
プロセス: Main
\n以下は複数のファイルを選択する dialog を表示する例です。
\nconst { dialog } = require('electron')\nconsole.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))\ndialog モジュールには以下のメソッドがあります。
dialog.showOpenDialogSync([browserWindow, ]options)browserWindow BrowserWindow (任意)options Objecttitle String (任意)defaultPath String (任意)buttonLabel String (任意) - 確認ボタンのカスタムラベル。空のままにすると、既定のラベルが使用されます。filters FileFilter[] (任意)properties String[] (任意) - ダイアログが使うべきでない機能が入ります。 以下の値がサポートされています:openFile - ファイルを選択するのを許可します。openDirectory - ディレクトリを選択するのを許可します。multiSelections - 複数のパスを選択するのを許可します。showHiddenFiles - ダイアログで隠しファイルを表示します。createDirectory macOS - ダイアログでディレクトリを作成するのを許可します。promptToCreate Windows - ダイアログで存在しないファイルパスを入力した場合に、作成を促します。 これは実際にパスにファイルを作成しませんが、アプリケーションによって作成される必要がある存在しないパスが返されることを許可します。noResolveAliases macOS - 自動的なエイリアス (シンボリックリンク) によるパス解決を無効にします。 選択されたエイリアスは、ターゲットパスの代わりにエイリアスパスを返します。treatPackageAsDirectory macOS - .app フォルダのようなパッケージを、ファイルの代わりにディレクトリとして扱います。dontAddToRecent Windows - 開いているアイテムを最近開いたドキュメントリストに追加しないようにします。message String (任意) macOS - 入力ボックスの上に表示するメッセージ。securityScopedBookmarks Boolean (任意) macOS mas - Mac App Store 向けにパッケージしたときに セキュリティスコープ付きブックマーク を作成します。戻り値 String[] | undefined - ユーザが選択したファイルパス。dialog がキャンセルされた場合は undefined を返します。
browserWindow の引数で、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。
特定の種類だけにユーザーを制限したいとき、filters には、表示または選択できるファイルの種類の配列を指定します。 以下がその例です。
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nextensions の配列には、ワイルドカードやドットを含む拡張子 (例えば、'png' は問題ありませんが、'.png' や '*.png' はいけません) を入れないで下さい。 すべてのファイルを表示するには、'*' ワイルドカードを使用して下さい (その他のワイルドカードはサポートされていません)。
注: WindowsとLinuxのオープンダイアログでは、ファイルとディレクトリの両方を選択することはできません。そのため、これらのプラットフォームで properties に ['openFile', 'openDirectory'] を設定すると、ディレクトリの選択が表示されます。
dialog.showOpenDialogSync(mainWindow, {\n properties: ['openFile', 'openDirectory']\n})\ndialog.showOpenDialog([browserWindow, ]options)browserWindow BrowserWindow (任意)options Objecttitle String (任意)defaultPath String (任意)buttonLabel String (任意) - 確認ボタンのカスタムラベル。空のままにすると、既定のラベルが使用されます。filters FileFilter[] (任意)properties String[] (任意) - ダイアログが使うべきでない機能が入ります。 以下の値がサポートされています:openFile - ファイルを選択するのを許可します。openDirectory - ディレクトリを選択するのを許可します。multiSelections - 複数のパスを選択するのを許可します。showHiddenFiles - ダイアログで隠しファイルを表示します。createDirectory macOS - ダイアログでディレクトリを作成するのを許可します。promptToCreate Windows - ダイアログで存在しないファイルパスを入力した場合に、作成を促します。 これは実際にパスにファイルを作成しませんが、アプリケーションによって作成される必要がある存在しないパスが返されることを許可します。noResolveAliases macOS - 自動的なエイリアス (シンボリックリンク) によるパス解決を無効にします。 選択されたエイリアスは、ターゲットパスの代わりにエイリアスパスを返します。treatPackageAsDirectory macOS - .app フォルダのようなパッケージを、ファイルの代わりにディレクトリとして扱います。dontAddToRecent Windows - 開いているアイテムを最近開いたドキュメントリストに追加しないようにします。message String (任意) macOS - 入力ボックスの上に表示するメッセージ。securityScopedBookmarks Boolean (任意) macOS mas - Mac App Store 向けにパッケージしたときに セキュリティスコープ付きブックマーク を作成します。戻り値 Promise<Object> - 以下を含むオブジェクトで実行されます。
canceled Boolean - dialog がキャンセルされたかそうでないか。filePaths String[] - ユーザーによって選択されたファイルパスの配列. ダイアログがキャンセルされた場合、これは空の配列になります。bookmarks String[] (任意)macOS mas - セキュリティスコープ付きブックマークを含む base64 エンコードされた filePaths 配列にマッチする配列。 データを取り込むために securityScopedBookmarks を有効にする必要があります。 (戻り値については、この表 を参照してください。)browserWindow の引数で、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。
特定の種類だけにユーザーを制限したいとき、filters には、表示または選択できるファイルの種類の配列を指定します。 以下がその例です。
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nextensions の配列には、ワイルドカードやドットを含む拡張子 (例えば、'png' は問題ありませんが、'.png' や '*.png' はいけません) を入れないで下さい。 すべてのファイルを表示するには、'*' ワイルドカードを使用して下さい (その他のワイルドカードはサポートされていません)。
注: WindowsとLinuxのオープンダイアログでは、ファイルとディレクトリの両方を選択することはできません。そのため、これらのプラットフォームで properties に ['openFile', 'openDirectory'] を設定すると、ディレクトリの選択が表示されます。
dialog.showOpenDialog(mainWindow, {\n properties: ['openFile', 'openDirectory']\n}).then(result => {\n console.log(result.canceled)\n console.log(result.filePaths)\n}).catch(err => {\n console.log(err)\n})\ndialog.showSaveDialogSync([browserWindow, ]options)browserWindow BrowserWindow (任意)options Objecttitle String (任意) - ダイアログのタイトル。 一部の Linux デスクトップ環境では表示できないことがあります。defaultPath String (任意) - 既定で使用される絶対ディレクトリパス、絶対ファイルパスもしくはファイル名。buttonLabel String (任意) - 確認ボタンのカスタムラベル。空のままにすると、既定のラベルが使用されます。filters FileFilter[] (任意)message String (任意) macOS - テキストフィールドの上に表示するメッセージ。nameFieldLabel String (任意) macOS - ファイル名のテキストフィールドの前に表示されるテキストのカスタムラベル。showsTagField Boolean (任意) macOS - タグの入力ボックスを表示します。省略値は、true です。properties String[] (任意)showHiddenFiles - ダイアログで隠しファイルを表示します。createDirectory macOS - ダイアログでディレクトリを作成するのを許可します。treatPackageAsDirectory macOS - .app フォルダのようなパッケージを、ファイルの代わりにディレクトリとして扱います。showOverwriteConfirmation Linux - ユーザが既に存在するファイル名を入力した場合に、ユーザに確認ダイアログを表示するかどうかを設定します。dontAddToRecent Windows - 開いているアイテムを最近開いたドキュメントリストに追加しないようにします。securityScopedBookmarks Boolean (任意) macOS mas - Mac App Store 向けにパッケージしたときに セキュリティスコープ付きブックマーク を作成します。 このオプションが有効でファイルが存在しない場合は、選択したパスに空のファイルが作成されます。戻り値 String | undefined - ユーザが選択したファイルパス。dialog がキャンセルされた場合は undefined を返します。
browserWindow の引数で、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。
filters には、表示することのできるファイルの種類の配列を指定します。例については、dialog.showOpenDialog を参照して下さい。
dialog.showSaveDialog([browserWindow, ]options)browserWindow BrowserWindow (任意)options Objecttitle String (任意) - ダイアログのタイトル。 一部の Linux デスクトップ環境では表示できないことがあります。defaultPath String (任意) - 既定で使用される絶対ディレクトリパス、絶対ファイルパスもしくはファイル名。buttonLabel String (任意) - 確認ボタンのカスタムラベル。空のままにすると、既定のラベルが使用されます。filters FileFilter[] (任意)message String (任意) macOS - テキストフィールドの上に表示するメッセージ。nameFieldLabel String (任意) macOS - ファイル名のテキストフィールドの前に表示されるテキストのカスタムラベル。showsTagField Boolean (任意) macOS - タグの入力ボックスを表示します。省略値は、true です。properties String[] (任意)showHiddenFiles - ダイアログで隠しファイルを表示します。createDirectory macOS - ダイアログでディレクトリを作成するのを許可します。treatPackageAsDirectory macOS - .app フォルダのようなパッケージを、ファイルの代わりにディレクトリとして扱います。showOverwriteConfirmation Linux - ユーザが既に存在するファイル名を入力した場合に、ユーザに確認ダイアログを表示するかどうかを設定します。dontAddToRecent Windows - 開いているアイテムを最近開いたドキュメントリストに追加しないようにします。securityScopedBookmarks Boolean (任意) macOS mas - Mac App Store 向けにパッケージしたときに セキュリティスコープ付きブックマーク を作成します。 このオプションが有効でファイルが存在しない場合は、選択したパスに空のファイルが作成されます。戻り値 Promise<Object> - 以下を含むオブジェクトで実行されます。
canceled Boolean - dialog がキャンセルされたかそうでないか。filePath String (任意) - ダイアログがキャンセルされると、これは undefined になります。bookmark String (任意)macOS mas - 保存されたファイルのセキュリティスコープのブックマークデータを含む Base64 エンコードされた文字列。 出力するために securityScopedBookmarks を有効にする必要があります。 (戻り値については、この表 を参照してください。)browserWindow の引数で、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。
filters には、表示することのできるファイルの種類の配列を指定します。例については、dialog.showOpenDialog を参照して下さい。
注意: macOS では、ダイアログを展開したり折りたたんだりする際の問題を避けるために、非同期バージョンを使用することを推奨します。
\ndialog.showMessageBoxSync([browserWindow, ]options)browserWindow BrowserWindow (任意)options Objectmessage String - メッセージボックスの内容。type String (任意) - \"none\"、\"info\"、\"error\"、\"question\"、\"warning\" にすることができます。 Windowsでは、\"icon\" のオプションを使用してアイコンを設定しない場合、\"question\" は、\"info\" と同じアイコンを表示します。 macOSでは、\"warning\" と \"error\" の両方で同じ警告アイコンを表示します。buttons String[] (任意) - ボタン用テキストの配列。 Windows では、空の配列は 1 つの \"OK\" ボタンになります。defaultId Integer (任意) - メッセージボックスを開いたとき、既定で選択されるボタンの配列の中のボタンのインデックス。title String (任意) - メッセージボックスのタイトル。いくつかのプラットフォームでは表示されません。detail String (任意) - メッセージの追加情報。icon (NativeImage | String) (任意)textWidth Integer (任意) macOS - メッセージボックス内のテキストのカスタムな幅。cancelId Integer (任意) - Esc キー経由でダイアログをキャンセルするのに使用されるボタンのインデックス。 既定では、これはラベルとして \"cancel\" または \"no\" の付いた最初のボタンに割り当てられます。 そのようにラベル付けされたボタンがなく、このオプションが設定されていない場合、0 が戻り値として使用されます。noLink Boolean (任意) - WindowsでElectronはどの buttons が (\"Cancel\" や \"Yes\" のような) 一般的なボタンかを把握し、その他をダイアログでコマンドリンクとして表示しようとします。 これにより、モダンなWindowsアプリのスタイルでダイアログを表示させることができます。 この動作が気に入らない場合、noLink を true に設定することができます。normalizeAccessKeys Boolean (任意) - プラットフォーム間でキーボードのアクセスキーを正規化します。 省略値は false です。 これを有効にすると、& が、ボタンのラベルでキーボードショートカットアクセスキーの位置として使用されているとみなされ、各プラットフォームで正常に動作するようにラベルが変換されます。macOSでは、& の文字は削除され、Linuxでは、_ に変換され、Windowsでは、そのままにされます。 例えば、Vie&w というボタンラベルは、Linuxでは、Vie_w、macOSでは、View に変換され、WindowsとLinuxでは、Alt-W 経由で選択できます。戻り値 Integer - クリックされたボタンのインデックス。
メッセージボックスを表示し、メッセージボックスが閉じられるまでプロセスをブロックします。 クリックされたボタンのインデックスを返します。
\nbrowserWindow の引数で、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。 browserWindow が表示されていない場合、dialog はアタッチされません。 この場合は独立したウインドウとして表示されます。
dialog.showMessageBox([browserWindow, ]options)browserWindow BrowserWindow (任意)options Objectmessage String - メッセージボックスの内容。type String (任意) - \"none\"、\"info\"、\"error\"、\"question\"、\"warning\" にすることができます。 Windowsでは、\"icon\" のオプションを使用してアイコンを設定しない場合、\"question\" は、\"info\" と同じアイコンを表示します。 macOSでは、\"warning\" と \"error\" の両方で同じ警告アイコンを表示します。buttons String[] (任意) - ボタン用テキストの配列。 Windows では、空の配列は 1 つの \"OK\" ボタンになります。defaultId Integer (任意) - メッセージボックスを開いたとき、既定で選択されるボタンの配列の中のボタンのインデックス。signal AbortSignal (任意) - 任意でメッセージボックスを閉じるために AbortSignal のインスタンスを渡すことができます。メッセージボックスはあたかもユーザーによってキャンセルされたかのように動作します。 macOS では、signal は親ウインドウのないメッセージボックスで動作しません。これらのメッセージボックスは、プラットフォーム上の制約により同期的に動作するからです。title String (任意) - メッセージボックスのタイトル。いくつかのプラットフォームでは表示されません。detail String (任意) - メッセージの追加情報。checkboxLabel String (任意) - 指定した場合、メッセージボックスには、指定したラベルを持つチェックボックスが含まれます。checkboxChecked Boolean (任意) - チェックボックスの初期のチェック状態。 省略値は false です。icon NativeImage (任意)textWidth Integer (任意) macOS - メッセージボックス内のテキストのカスタムな幅。cancelId Integer (任意) - Esc キー経由でダイアログをキャンセルするのに使用されるボタンのインデックス。 既定では、これはラベルとして \"cancel\" または \"no\" の付いた最初のボタンに割り当てられます。 そのようにラベル付けされたボタンがなく、このオプションが設定されていない場合、0 が戻り値として使用されます。noLink Boolean (任意) - WindowsでElectronはどの buttons が (\"Cancel\" や \"Yes\" のような) 一般的なボタンかを把握し、その他をダイアログでコマンドリンクとして表示しようとします。 これにより、モダンなWindowsアプリのスタイルでダイアログを表示させることができます。 この動作が気に入らない場合、noLink を true に設定することができます。normalizeAccessKeys Boolean (任意) - プラットフォーム間でキーボードのアクセスキーを正規化します。 省略値は false です。 これを有効にすると、& が、ボタンのラベルでキーボードショートカットアクセスキーの位置として使用されているとみなされ、各プラットフォームで正常に動作するようにラベルが変換されます。macOSでは、& の文字は削除され、Linuxでは、_ に変換され、Windowsでは、そのままにされます。 例えば、Vie&w というボタンラベルは、Linuxでは、Vie_w、macOSでは、View に変換され、WindowsとLinuxでは、Alt-W 経由で選択できます。戻り値 Promise<Object> - 以下のプロパティを含む Promise で解決されます。
response Number - クリックされたボタンのインデックス。checkboxChecked Boolean - checkboxLabel が設定された場合、チェックボックスのチェック状態。 そうでない場合は false になります。メッセージボックスを表示します。
\nbrowserWindow の引数で、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。
dialog.showErrorBox(title, content)title String - エラーボックスに表示するタイトル.content String - エラーボックスに表示するテキストの内容.エラーメッセージを表示するモーダルダイアログを表示します。
\napp モジュールで ready イベントが発生する前でも、このAPIは安全に呼び出すことができます。これは、起動の初期段階でのエラーを報告するのによく使用されます。 Linuxで、appの ready イベントの前に呼び出すと、メッセージは標準エラーに出力され、GUIのダイアログは表示されません。
dialog.showCertificateTrustDialog([browserWindow, ]options) macOS WindowsbrowserWindow BrowserWindow (任意)options Objectcertificate Certificate - 信頼/インポートする証明書。message String - ユーザーに表示するメッセージ。戻り値 Promise<void> - 証明書信頼ダイアログが表示されると実行されます。
macOSでは、これはメッセージと証明書情報を表示するモーダルダイアログを表示し、ユーザーに証明書を信頼/インポートする選択肢を提供します。 browserWindow の引数を指定すると、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。
Windowsでは、使用されているWin32 APIのため、オプションはより限定的です。
\nmessage の引数は使用されません。browserWindow の引数は無視されます。showOpenDialog、showOpenDialogSync、showSaveDialog、 showSaveDialogSync は bookmarks と言う配列を返します。
| ビルド種別 | securityScopedBookmarks 真偽値 | 戻り値の型 | 返り値 |
|---|---|---|---|
| macOS mas | True | Success | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | エラー | [''] (空文字列の配列) |
| macOS mas | False | なし | [] (空の配列) |
| non mas | any | なし | [] (空の配列) |
macOS では、browserWindow パラメータに BrowserWindow の参照を指定した場合、ダイアログは、ウインドウにアタッチされたシートとして表示されます。ウインドウを指定しない場合、モーダルで表示されます。
BrowserWindow.getCurrentWindow().setSheetOffset(offset) を呼び出すことで、シートがアタッチされるウインドウフレームからのオフセットを変更することができます。
id Number - Unique identifier associated with the display.rotation Number - Can be 0, 90, 180, 270, represents screen rotation in clock-wise degrees.scaleFactor Number - Output device's pixel scale factor.touchSupport String - Can be available, unavailable, unknown.monochrome Boolean - Whether or not the display is a monochrome display.accelerometerSupport String - Can be available, unavailable, unknown.colorSpace String - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversionscolorDepth Number - The number of bits per pixel.depthPerComponent Number - The number of bits per color component.displayFrequency Number - The display refresh rate.bounds Rectangle - the bounds of the display in DIP points.size SizeworkArea Rectangle - the work area of the display in DIP points.workAreaSize Sizeinternal Boolean - true for an internal display and false for an external displayThe Display object represents a physical display connected to the system. A fake Display may exist on a headless system, or a Display may correspond to a remote, virtual display.
\n\nmacOS Dock 内のアプリを制御する
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
以下の例は、Dock でアイコンをバウンスさせる方法を示しています。
\nconst { app } = require('electron')\napp.dock.bounce()\ndock.bounce([type]) macOStype String (任意) - critical か informational にできます。 省略値は、informational です。戻り値 Integer - このリクエストを表すID。
critical が渡された場合、ドックのアイコンはアプリケーションがアクティブになるか、リクエストがキャンセルされるまでバウンスします。
informational が渡されると、ドックアイコンが 1 秒間バウンスします。 ただし、アプリケーションがアクティブになるかリクエストがキャンセルされるまで、そのリクエストはアクティブのままです。
注釈: このメソッドは、アプリがフォーカスされていないときにのみ使用できます。アプリがフォーカスされていると -1 を返します。
\ndock.cancelBounce(id) macOSid Integerid のバウンスをキャンセルします。
dock.downloadFinished(filePath) macOSfilePath StringfilePath がダウンロードフォルダの中の場合、ダウンロードのスタックをバウンスさせます。
\ndock.setBadge(text) macOStext Stringドックのバッジ領域に表示される文字列を設定します。
\ndock.getBadge() macOS戻り値 String - ドックのバッジ文字列。
dock.hide() macOSドックのアイコンを非表示にする
\ndock.show() macOS戻り値 Promise<void> - Dock のアイコンが表示されたときに実行されます。
dock.isVisible() macOSReturns Boolean - Dock のアイコンが表示されているかどうか。
dock.setMenu(menu) macOSmenu Menuアプリケーションの [Dock メニュー][dock-menu] を設定します。
\ndock.getMenu() macOS戻り値 Menu | null - アプリケーションの [Dock メニュー][dock-menu]。
dock.setIcon(image) macOSimage (NativeImage | String)このドックアイコンに関連付けられた image を設定します。
\n\nリモートソースからのファイルのダウンロードを制御します。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
DownloadItem は EventEmitter を継承しており、Electron でのダウンロードアイテムを表します。 これは Session クラスの will-download イベントで使用されており、ユーザーがダウンロードアイテムを制御できるようにします。
// メインプロセス\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.session.on('will-download', (event, item, webContents) => {\n // 保存パスを設定して、Electronに保存ダイアログを出さないようにします。\n item.setSavePath('/tmp/save.pdf')\n\n item.on('updated', (event, state) => {\n if (state === 'interrupted') {\n console.log('Download is interrupted but can be resumed')\n } else if (state === 'progressing') {\n if (item.isPaused()) {\n console.log('Download is paused')\n } else {\n console.log(`Received bytes: ${item.getReceivedBytes()}`)\n }\n }\n })\n item.once('done', (event, state) => {\n if (state === 'completed') {\n console.log('Download successfully')\n } else {\n console.log(`Download failed: ${state}`)\n }\n })\n})\n戻り値：
\nevent Eventstate String - progressing か interrupted にできます。ダウンロードが更新され、まだ未完了であるときに発生します。
\nstate は、次のいずれかになります。
progressing - ダウンロードが進行中です。interrupted - ダウンロードが中断されましたが、再開することができます。戻り値：
\nevent Eventstate String - completed、cancelled か interrupted にできます。ダウンロードが終了状態となったときに発生します。 これは完了したダウンロード、キャンセルされたダウンロード (downloadItem.cancel() によって) 、再開できる中断されたダウンロードを含みます。
state は、次のいずれかになります。
completed - ダウンロードが正常に完了しました。cancelled - ダウンロードがキャンセルされました。interrupted - ダウンロードが中断され、再開することができません。downloadItem オブジェクトには以下のメソッドがあります
downloadItem.setSavePath(path)path String - ダウロードアイテムを保存するファイルパスを設定します。このAPIは、セッションの will-download コールバック関数でのみ利用可能です。 path が存在しない場合、Electron はディレクトリを再帰的に作成しようとします。 ユーザがこのAPIを経由して保存先のパスを設定しない場合、Electron は、保存先のパスを決定するために独自のルーチンを使用します。通常は保存ダイアログを表示します。
downloadItem.getSavePath()戻り値 String - ダウンロードアイテムの保存先パス。 これは downloadItem.setSavePath(path) で設定されたものか、保存ダイアログで選択されたものになります。
downloadItem.setSaveDialogOptions(options)options SaveDialogOptions - ファイル保存ダイアログのオプションを設定します。 このオブジェクトは options パラメータ(dialog.showSaveDialog()の)と同じプロパティを持ちます。この API によって、ダウンロードアイテムに対して既定で開かれる保存ダイアログのカスタムオプションをユーザが設定できます。 このAPIは、セッションの will-download コールバック関数でのみ利用可能です。
downloadItem.getSaveDialogOptions()戻り値 SaveDialogOptions - downloadItem.setSaveDialogOptions(options)によってその前に設定されたオブジェクトを返す。
downloadItem.pause()ダウンロードを一時停止します。
\ndownloadItem.isPaused()戻り値 Boolean - ダウンロードが一時停止しているかどうか。
downloadItem.resume()一時停止されたダウンロードを再開します。
\n注: 再開可能なダウンロードを有効にするには、ダウンロードしているサーバーがRangeリクエストをサポートしており、Last-Modified と ETag の両方のヘッダーの値を提供していなければなりません。 そうでなければ、resume() は、前回受信したバイト数を無視して、最初からダウンロードを再開します。
downloadItem.canResume()戻り値 Boolean - ダウンロードを再開できるかどうか。
downloadItem.cancel()ダウンロード操作をキャンセルします。
\ndownloadItem.getURL()戻り値 String - アイテムがダウンロードされた元の URL。
downloadItem.getMimeType()戻り値 String - ファイルのMIMEタイプ。
downloadItem.hasUserGesture()戻り値 Boolean - ダウンロードにユーザージェスチャがあるかどうか。
downloadItem.getFilename()戻り値 String - ダウンロードアイテムのファイル名。
注: ファイル名は常にローカルディスクに保存したものと同じではありません。 ユーザーが表示されたダウンロード保存ダイアログでファイル名を変更した場合、保存されたファイルの実際の名前は異なります。
\ndownloadItem.getTotalBytes()戻り値 Integer - ダウンロードアイテムのバイト単位での合計サイズ。
サイズが不明な場合、0を返します。
\ndownloadItem.getReceivedBytes()戻り値 Integer - ダウンロードアイテムの受信したバイト数。
downloadItem.getContentDisposition()戻り値 String - レスポンスヘッダーのContent-Dispositionフィールド。
downloadItem.getState()戻り値 String - 現在の状態。 progressing 、 completed 、 cancelled 、 interrupted のいずれか。
注: 以下のメソッドは、セッションが再開されたときに cancelled アイテムを再開するのに特に有用です。
downloadItem.getURLChain()戻り値 String[] - すべてのリダイレクトを含むアイテムの完全な URL チェーン。
downloadItem.getLastModifiedTime()戻り値 String - Last-Modifiedのヘッダーの値。
downloadItem.getETag()戻り値 String - ETagのヘッダーの値。
downloadItem.getStartTime()戻り値 Double - ダウンロードが開始されたUNIXエポックからの秒数。
downloadItem.savePathString 型のプロパティです。ダウンロードアイテムを保存するファイルパスを決定します。
このプロパティは、セッションの will-download コールバック関数内でのみ利用可能です。 ユーザがこのプロパティを経由して保存先のパスを設定しない場合、Electron は、保存先のパスを決定するために独自のルーチンを使用します。通常は保存ダイアログを表示します。
特筆事項:
\n-beta.1 および stable の日付は、具体的なリリース日です。| Electron | アルファ | ベータ | 安定版 | Chrome | ノード |
|---|---|---|---|---|---|
| 2.0.0 | -- | 2018-Feb-21 | 2018-May-01 | M61 | v8.9 |
| 3.0.0 | -- | 2018-Jun-21 | 2018-Sep-18 | M66 | v10.2 |
| 4.0.0 | -- | 2018-Oct-11 | 2018-Dec-20 | M69 | v10.11 |
| 5.0.0 | -- | 2019-Jan-22 | 2019-Apr-24 | M73 | v12.0 |
| 6.0.0 | -- | 2019-May-01 | 2019-Jul-30 | M76 | v12.4 |
| 7.0.0 | -- | 2019-Aug-01 | 2019-Oct-22 | M78 | v12.8 |
| 8.0.0 | -- | 2019-Oct-24 | 2020-Feb-04 | M80 | v12.13 |
| 9.0.0 | -- | 2020-Feb-06 | 2020-May-19 | M83 | v12.14 |
| 10.0.0 | -- | 2020-May-21 | 2020-May-21 | M85 | v12.16 |
| 11.0.0 | -- | 2020-Aug-27 | 2020-Nov-17 | M87 | v12.18 |
| 12.0.0 | -- | 2020-Nov-19 | 2021-Mar-02 | M89 | v14.16 |
| 13.0.0 | -- | 2021-Mar-04 | 2021-May-25 | M91 | v14.16 |
| 14.0.0 | -- | 2021-May-27 | 2021-Aug-31 | M93 | v14.17 |
| 15.0.0 | 2021-Jul-20 | 2021-Sep-01 | 2021-Sep-21 | M94 | v16.5 |
| 16.0.0 | -- | 2021-Sep-23 | 2021-Nov-16 | M96 | 未定 |
\n\nバージョン管理ポリシーと実装の詳細をご覧ください。
\n
バージョン 2.0.0 から、Electron は SemVer に準拠しています。 以下のコマンドで、最新の安定版 Electron のビルドをインストールできます。
\nnpm install --save-dev electron\n既存のプロジェクトを最新の安定版を使用するように更新するには、以下のようにします。
\nnpm install --save-dev electron@latest\nElectron 2.0 より前のバージョンでは SemVer の仕様に準拠していませんでした。メジャーバージョンはエンドユーザ API の変更に、マイナーバージョンは Chromium のメジャーリリースに、パッチバージョンは新機能やバグ修正に対応していました。 機能を統合する開発者にとっては便利ですが、クライアント向けアプリケーションの開発者には問題が生じます。 Slack、Stride、Teams、Skype、VS Code、Atom、Desktop などのメジャーなアプリの QA テストサイクルは時間がかかることがあり、安定性においては非常に望ましい結果を出します。 これは、バグ修正を吸収しようとする一方で、新しい機能を採用することに高いリスクがあります。
\n1.x の方針の例を以下に示します。
\n
1.8.1 を使用して開発されたアプリケーションは、1.8.2 の機能を取り入れるか、修正をバックポートし、新しいリリースラインをメンテナンスすることなしに、1.8.3 のバグ修正をとることもできません。
上に概説されている 1.x の方針から、いくつかの大きな変更があります。 各変更は、開発者/管理者とアプリ開発者のニーズと優先順位を満たすためのものです。
\n-beta タグの導入master ブランチにはバージョンがなく、安定ブランチのみがバージョン情報を含みます。git のブランチ動作の仕組み、npm のタグ付けの仕組み、開発者が期待するべきこと、変更をバックポートする方法について詳しく説明します。
\n2.0 以降から、Electron は SemVer に従います。
\n以下は、変更の種別をそれに対応する SemVer のカテゴリ (メジャー、マイナー、パッチなど) へ明示的に割り当てた表です。
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| メジャーバージョンの単位 | マイナーバージョンの単位 | パッチバージョンの単位 |
|---|---|---|
| 互換性を破る Electron API の変更 | 互換性を破らない Electron API の変更 | Electron のバグ修正 |
| Node.js のメジャーバージョン更新 | Node.js のマイナーバージョン更新 | Node.js のパッチバージョン更新 |
| Chromium のバージョン更新 | Chromium パッチの修正関連 |
注意として、ほとんどの Chromium のアップデートは破壊的とみなされます。 バックポート可能な修正は、パッチとしてチェリーピックされます。
\n安定ブランチは、セキュリティまたは安定性に関連する cherry-pick されたコミットのみを取り入れて、master と並行して実行されるブランチです。 これらのブランチはマスターに戻されることはありません。
\n
Electron 8 以降、安定化ブランチは常に major のバージョンラインであり、テンプレート $MAJOR-x-y に沿って 8-x-y のように名前を付けます。 以前は minor のバージョンラインを使用しており、$MAJOR-$MINOR-x に沿って 2-0-x のような名前にしていました。
複数の安定化ブランチを同時に存在させることができます。また、必要に応じてセキュリティ修正を後方移植しながら、少なくとも2つのサポートを常に並行してサポートする予定です。
それより古いものは GitHub ではサポートされませんが、他のグループは所有権を持って、自分自身で安定性とセキュリティの修正をバックポートできます。 これはお勧めできませんが、多くのアプリ開発者にとってライフが楽になると認識しています。
\n開発者はどのリリースが 安全 に使用できるかを知りたいものです。 一見無害な機能でさえ、複雑なアプリケーションに後退をもたらすことがあります。 同時に、あなたのバージョンから出るセキュリティパッチとバグ修正の可能性を無視しているので、固定バージョンへのロックは危険です。 私たちの目標は、package.json で以下のように標準的な semver 範囲を許可することです。
~2.0.0 を使用すると、2.0.0 リリースに対する安定性またはセキュリティ関連の修正のみを認めます。^2.0.0 を使用すると、セキュリティやバグ修正だけでなく、破壊的でない 合理的で安定した 機能も認めます。2つ目の点に関して重要なことは、^ を使用しているアプリはまだ妥当なレベルの安定性を期待できることです。 これを実現するために、SemVer では特定のバージョンがまだ 安全 または 安定 ではないことを示す プレリリース識別子 を指定できるようになっています。
どれを選択しても、破壊的な変更は Chromium が寿命である事実であるため、定期的に package.json 内のバージョンを更新する必要があります。
プロセスは以下の通りです。
\n2.0.0-beta.1 のような beta.N の SemVer プレリリースタグで示されたベータ系列で始めます。 最初のベータ版の後、その後のベータ版リリースは以下のすべての条件を満たす必要があります。2.0.0-beta.2 のようにプレリリースタグが増分されます。2.0.0 のようになります。 最初の安定版以降は、すべての変更は後方互換性のあるバグまたはセキュリティ修正でなければなりません。2.0.1 のように、patch のバージョンを増やします。具体的に言うと、以下が上記の意味です。
\nメジャーとマイナーのバージョン上げのそれぞれにおいて、以下のようなものが見えるはずです。
\n2.0.0-beta.1\n2.0.0-beta.2\n2.0.0-beta.3\n2.0.0\n2.0.1\n2.0.2\n以下は絵に描いたライフサイクルの例です。
\n2.0.0-beta.1 として公開されます。 2.0.0-beta.2 として公開されます。 2.0.0 の下に非ベータ版として再度公開されます。 2-0-x のラインにバックポートし、2.0.1 をリリースします。 以下に、さまざまな SemVer 範囲で新リリースを取得する例をいくつか示します。
\n
私たちの戦略にはいくつかのトレードオフがありますが、今のところそれは適切だと感じています。 最も重要なことは、master の新機能が安定したリリースラインに到達するまでにはしばらく時間がかかることです。 すぐに新しい機能を試したい場合は、自分で Electron をビルドする必要があります。
\n今後の検討事項として、以下のうちの一方または両方を紹介する可能性があります。
\n機能フラグは Chromium で一般的な方法であり、Web 開発エコシステムではよく確立されています。 Electron のコンテキストでは、機能フラグまたは ソフトブランチ には次のプロパティが必要です。
\n私達は更新およびリリースプロセスのすべてのレベルで明快さを増すよう努めます。 2.0.0 以降、プルリクエストは 従来のコミット の仕様に準拠する必要があります。これは以下のようにまとめることができます。
major バージョンを上げるコミットの本文は BREAKING CHANGE: で始まる必要があります。
minor バージョンを上げるコミットは feat: で始まる必要があります。
patch バージョンを上げるコミットは fix: で始まる必要があります。
squash したメッセージも上記のメッセージフォーマットを遵守するという条件下で、コミットの squash を許可します。
\nプルリクエストのタイトルが意味のある包括的なセマンティックメッセージを含むのであれば、プルリクエストにおけるいくつかのコミットがセマンティックプレフィックスを含まないことは許容できます。
\nmastermaster ブランチは、常に package.json に次のメジャーバージョンの X.0.0-nightly.DATE を含みます。package.json 内に正しいバージョンを含んで いますmaster は常に理論上次のリリースブランチとしてバージョン管理されますNW.js のように、Electron はウェブ技術を使ったデスクトップアプリケーションを書くプラットフォームを提供します。 どちらのプラットフォームも、開発者は HTML、JavaScript、Node.js が利用できます。 表面上は、とても似ています。
\nしかし、この 2 つのプロジェクトには根本的な違いがあり、Electron と NW.js は完全に別物です。
\nNW.js では、アプリケーションのメインエントリポイントを HTML ウェブページにできます。 その場合、NW.js は指定のエントリポイントをブラウザウインドウで開きます。
\nElectron では、エントリポイントは常に JavaScript スクリプトです。 URL を直接指定するのではなく、手動でブラウザウィンドウを作成し、API で HTML ファイルをロードします。 アプリケーションを終了するタイミングを決めるため、ウインドウイベントを監視する必要もあります。
\nElectron は Node.js ランタイムのように動作します。 Electron の API はローレベルなので、PhantomJS 代わりのブラウザテストに使うことができます。
\nNW.js では、ウェブページで Node インテグレーションをするには Chromium にパッチを当てる必要があります。Electron では Chromium のハッキングを避けるために各プラットフォームのメッセージループに libuv ループを統合する、別の選択をしました。 これがどのように行われているかについては node_bindings コードを参照してください。
NW.js の経験者であれば、Node コンテキストやウェブコンテキストの概念をご存知でしょう。 これらの概念は、NW.js の実装手段から考案されたものです。
\nNode の マルチコンテキスト 機能を使用すると、Electron はウェブページ内に新しい JavaScript コンテキストを導入しません。
\n注釈: NW.js は 0.13 からマルチコンテキストを任意でサポートしています。
\nNW.js では、Windows XP 対応の \"レガシーリリース\" がまだ提供されています。 これはセキュリティアップデートを受けません。
\nハードウェアメーカー、Microsoft、Chromium、Node.js がシステムの重大セキュリティアップデートすらリリースしていないことを鑑みると、Windows XP の使用は危険であり、完全に自己責任であることを警告しなければなりません。
\nしかし、私たちの想像を超える要件が存在する可能性があることは理解しています。Windows XP で動作する Electron のようなものをお探しであれば、NW.js のレガシーリリースをお勧めします。
\nサポートする機能の量は多くの差異があります。 Electron にはより大きなコミュニティがあり、これを使用するアプリ製品の数も多く、npm で利用できる大量のユーザー製モジュールがあります。
\n例えば、Electron には自動更新サポートが組み込まれており、インストーラ作成を容易にする無数のツールも用意されています。 NW.js の良いところを挙げると、NW.js は Chrome アプリ開発向けに Chrome.* API を数多くサポートしています。
もちろん、ウェブ技術で構築された、洗練されたアプリケーション製品 (Visual Studio Code、Slack、Facebook Messenger など) のプラットフォームとしては Electron の方が優れていると考えます。しかし、ウェブ技術の仲間たるもの公平でありたいです。 Electron にはない機能が必要であれば、NW.js を試すのもいいかもしれません。
", "title": "Electron と NW.js との技術的差異", "description": "" }, "/docs/api/environment-variables": { "locale": "ja-JP", "slug": "environment-variables", "href": "/docs/api/environment-variables", "crowdinFileId": "256315", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/environment-variables.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nコードを変更することなくアプリケーションの設定と動作を制御します。
\n
いくつかのElectronの動作は、コマンドラインのフラグやアプリのコードよりも早く初期化されるため、環境変数によって制御されます。
\nPOSIXシェルの例:
\n$ export ELECTRON_ENABLE_LOGGING=true\n$ electron\nWindowsコンソールの例:
\n> set ELECTRON_ENABLE_LOGGING=true\n> electron\n以下の環境変数は、主にパッケージ化されたElectronアプリケーションで実行時に使用するためのものです。
\nNODE_OPTIONSElectron は Node の NODE_OPTIONS の一部をサポートに含んでいます。 Chromium の BoringSSL の使用と衝突するものを除き、大多数はサポートされています。
サンプル:
\nexport NODE_OPTIONS=\"--no-warnings --max-old-space-size=2048\"\n以下はサポートされていないオプションです。
\n--use-bundled-ca\n--force-fips\n--enable-fips\n--openssl-config\n--use-openssl-ca\nNODE_OPTIONS は、以下のようにしない限りパッケージされたアプリ内では明示的に許可されません。
--max-http-header-size\n--http-parser\nGOOGLE_API_KEYElectron での地理位置情報サポートには、Google Cloud Platform の地理位置情報ウェブサービスの利用が必要です。 この機能を有効にするには、Google API キー を取得し、ジオロケーション要求を行うブラウザウィンドウを開く前に、以下のコードをメインプロセスファイルに配置してください。
\nprocess.env.GOOGLE_API_KEY = 'YOUR_KEY_HERE'\nデフォルトでは、新しく生成された Google API キーではジオロケーションリクエストを行えない場合があります。 プロジェクトで地理位置情報ウェブサービスを有効にするには、API ライブラリ から有効にしてください。
\n注: 地理位置情報ウェブサービスが動作するには、API キーに関連付けられたプロジェクトに 請求先アカウント を追加する必要があります。
\nELECTRON_NO_ASARASAR サポートを無効にします。 この変数は、ELECTRON_RUN_AS_NODE を設定したフォークされた子プロセスと生成された子プロセスでのみサポートされます。
ELECTRON_RUN_AS_NODE通常のNode.jsプロセスとしてプロセスを開始します。
\nこのモードでは、以下のフラグを除いて、通常の Node.js 実行ファイルを実行しているときと同じように CLI 引数 を Node.js に渡せます。
\nこれらのフラグは、Electron が Node.js の crypto モジュール構築に OpenSSL ではなく BoringSSL を使用しているため、設計通りに動作せず無効になっています。
ELECTRON_NO_ATTACH_CONSOLE Windows現在のコンソールセッションにアタッチしません。
\nELECTRON_FORCE_WINDOW_MENU_BAR LinuxLinuxのグローバルメニューバーを使用しません。
\nELECTRON_TRASH LinuxLinux でゴミの実装を設定します。 既定値は gio です。
オプション:
\ngvfs-trashtrash-clikioclient5kioclient以下の環境変数は、主に開発とデバッグを目的としています。
\nELECTRON_ENABLE_LOGGINGコンソールに Chromium の内部ログを出力します。
\nこの変数への設定は、コマンドラインで --enable-logging を渡すのと同じです。 詳しくは、コマンドラインスイッチ の --enable-logging をご覧ください。
ELECTRON_LOG_FILEChromium の内部ログの保存先ファイルを設定します。
\nこの変数への設定は、コマンドラインで --log-file を渡すのと同じです。 詳細は、 コマンドラインスイッチ の --log-file をご参照ください。
ELECTRON_DEBUG_DRAG_REGIONSmacOS での BrowserView のドラッグ可能な領域に色を付けます。ドラッグ可能な領域は緑、ドラッグ不可能な領域は赤で表示され、デバッグを支援します。
ELECTRON_DEBUG_NOTIFICATIONSmacOS での Notification ライフサイクルにさらなるログを追加し、デバッグを支援します。 新しい通知の作成や有効化のタイミングで、そのさらなるログが表示されます。 これは、通知が表示されたり、解除されたり、そのボタンがクリックされたり、返信されたりといった一般的なアクションが実行されたときにも表示されます。
以下は出力例です。
\nNotification created (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification displayed (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification activated (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification replied to (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nELECTRON_LOG_ASAR_READSElectron が ASAR ファイルから読み込むときに、読み取りオフセットとファイルパスをシステムの tmpdir へログとして出力します。 ファイルの順番を最適化するために、結果のファイルを ASAR モジュールへ与えられます。
ELECTRON_ENABLE_STACK_DUMPINGElectronがクラッシュすると、コンソールにスタックトレースを出力します。
\ncrashReporter が開始されている場合、この環境変数は機能しません。
ELECTRON_DEFAULT_ERROR_MODE WindowsElectronがクラッシュすると、Windowsのクラッシュダイアログを表示します。
\ncrashReporter が開始されている場合、この環境変数は機能しません。
ELECTRON_OVERRIDE_DIST_PATHelectron パッケージを実行しているとき、この変数は npm install によってダウンロードされた代わりの Electron の指定ビルドを使用するための electron コマンドを知らせます。 使い方:
export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing\nElectron は実行時に環境変数をいくつか設定します。
\nORIGINAL_XDG_CURRENT_DESKTOPこの変数には、アプリケーション が起動した XDG_CURRENT_DESKTOP の値が設定されます。 Electron は XDG_CURRENT_DESKTOP の値を変更して Chromium 内の他のロジックに影響を与えることがあるので、元々 の値にアクセスしたい場合は、代わりにこの環境変数を見る必要があります。
GlobalEventpreventDefault VoidFunctionいくつかの Electrons API のドキュメントには、_Experimental_ というタグが付けられています。 このタグは、その API が不安定であろうと考えられており、他の API に比べて警告をあまりせずに API の削除や変更が頻繁に行われるかもしれないということです。
新機能の PR では、誰でも API を実験的なものとしてタグ付けるよう要求できます。新機能が実験的かどうかに関する意見の相違が PR で解決できない場合、API WG で議論にかけることができます。
\nその API が安定しており、2 つ以上のメジャー安定版のリリースラインにある場合は、API の実験的なタグ付けの削除指名ができます。 この議論は API WG ミーティングで執り行われます。 議論/指名の際に考慮すべきこと:
\nid Stringmanifest any - Copy of the extension's manifest data.name Stringpath String - The extension's file path.version Stringurl String - The extension's chrome-extension:// URL.name Stringversion StringElectron は Chrome 拡張機能 API のサブセットをサポートしており、主にデベロッパー ツール拡張機能と Chromium 内部拡張機能をサポートしていますが、他の拡張機能もサポートしています。
\n\n\n注意: Electron はストアのすべての Chrome 拡張機能はサポートしていません。Chrome の拡張機能の実装と完全に互換性を持たせることは Electron プロジェクトの 目標ではありません。
\n
Electron は解凍された拡張機能のみの読み込みをサポートしています (例えば .crx ファイルは動作しません)。 拡張機能は session ごとにインストールされます。 拡張機能を読み込むには、以下のように ses.loadExtension を呼び出します。
const { session } = require('electron')\n\nsession.loadExtension('path/to/unpacked/extension').then(({ id }) => {\n // ...\n})\n読み込まれた拡張機能は終了時に自動で記憶されません。アプリを実行する度にloadExtension を呼び出さないと、拡張子は読み込まれません。
注意として、拡張機能の読み込みは持続する session でのみサポートされます。 拡張機能をメモリで一時的な session に読み込もうとすると、エラーが送出されます。
\n有効な拡張機能の読み込み、解除、クエリについての詳細は session のドキュメントを参照してください。
いくつかの注意点はありますが、以下の拡張機能 API をサポートしています。 他の API も追加でサポートされる可能性がありますが、ここに記載されていない API のサポートは暫定であり、削除される可能性があります。
\nchrome.devtools.inspectedWindowこの API はすべての機能がサポートされています。
\nchrome.devtools.networkこの API はすべての機能がサポートされています。
\nchrome.devtools.panelsこの API はすべての機能がサポートされています。
\nchrome.extensionchrome.extension のうち以下のプロパティがサポートされています。
chrome.extension.lastErrorchrome.extension のうち以下のメソッドがサポートされています。
chrome.extension.getURLchrome.extension.getBackgroundPagechrome.runtimechrome.runtime のうち以下のプロパティがサポートされています。
chrome.runtime.lastErrorchrome.runtime.idchrome.runtime のうち以下のメソッドがサポートされています。
chrome.runtime.getBackgroundPagechrome.runtime.getManifestchrome.runtime.getPlatformInfochrome.runtime.getURLchrome.runtime.connectchrome.runtime.sendMessagechrome.runtime.reloadchrome.runtime のうち以下のイベントがサポートされています。
chrome.runtime.onStartupchrome.runtime.onInstalledchrome.runtime.onSuspendchrome.runtime.onSuspendCanceledchrome.runtime.onConnectchrome.runtime.onMessagechrome.storagechrome.storage.local のみがサポートされており、chrome.storage.sync と chrome.storage.managed はサポートされていません。
chrome.tabschrome.tabs のうち以下のメソッドがサポートされています。
chrome.tabs.sendMessagechrome.tabs.executeScript\n\n注: Chrome では、タブ ID に
\n-1を渡すと \"現在アクティブなタブ\" を意味します。 Electron にはそのような概念がないため、タブ ID として-1を渡すことはサポートされておらず、エラーとなります。
chrome.managementchrome.management のうち以下のメソッドがサポートされています。
chrome.management.getAllchrome.management.getchrome.management.getSelfchrome.management.getPermissionWarningsByIdchrome.management.getPermissionWarningsByManifestchrome.management.onEnabledchrome.management.onDisabledchrome.webRequestこの API はすべての機能がサポートされています。
\n\n", "title": "Chrome 拡張機能サポート", "description": "注意: Electron はストアのすべての Chrome 拡張機能はサポートしていません。Chrome の拡張機能の実装と完全に互換性を持たせることは Electron プロジェクトの 目標ではありません。" }, "/docs/faq": { "locale": "ja-JP", "slug": "faq", "href": "/docs/faq", "crowdinFileId": "256121", "githubUrl": "https://github.com/electron/electron/tree/main/docs/faq.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "注意: ハンドラが競合する場合は、
\nchrome.webRequestより Electron のwebRequestモジュールのものが優先されます。
npm install electron を実行するとき、インストール時エラーが発生する場合があります。
ほとんどの場合、このエラーはネットワークによるもので、electron の npm パッケージに問題はありません。 ELIFECYCLE、EAI_AGAIN、ECONNRESET、ETIMEDOUT といったエラーは、ネットワーク上の問題を示しています。 最善の解決策は、ネットワークを切り替えるか、少し待ってからもう一度インストールしてることです。
npm でのインストールに失敗する場合、Electron を electron/electron/releases から直接ダウンロードすることもできます。
Electron 内の Chrome のバージョンは、通常であれば新しい Chrome の安定バージョンがリリースされてから 1 ~ 2 週間以内に更新します。 この期間というのは保証されておらず、バージョンアップの作業量にも依存します。
\nChrome の安定版のみを使用します。 重要な修正が beta や dev 版にある場合、それをバックポートします。
\nより詳しい情報は、セキュリティについて を参照してください。
\n新しいバージョンの Node.js がリリースされた後、通常であれば Electron 内の Node.js のアップグレードまで約 1 ヶ月待ちます。 これにより、新しい Node.js のリリースでよく発生するバグの影響を避けることができます。
\n通常、Node.js の新しい機能は V8 のアップグレードによってもたらされますが、Electron は Chrome ブラウザーに搭載されている V8 を使用しているので、新しい Node.js に入ったばかりのピカピカに新しい JavaScript 機能は Electron ではたいてい既に導入されています。
\nウェブページ (レンダラープロセス) 間でデータを共有する最も単純な方法は、ブラウザで既に提供されている HTML5 API を使用することです。 Storage API, localStorage, sessionStorage, IndexedDB といった良い選択肢があります。
Alternatively, you can use the IPC primitives that are provided by Electron. To share data between the main and renderer processes, you can use the ipcMain and ipcRenderer modules. ウェブページ間で直接通信するには、ipcRenderer.postMessage() でメインプロセスを経由して一方から他方に MessagePort を送ることによってできます。 Subsequent communication over message ports is direct and does not detour through the main process.
これは、tray を格納している変数がガベージコレクトされると発生します。
\n以下のドキュメントが参考になるはずです。
\n\nもし簡単に修正したい場合は、コードを以下のように修正して変数をグローバルにすると良いでしょう。以下の部分を
\nconst { app, Tray } = require('electron')\napp.whenReady().then(() => {\n const tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\n以下のように変更します。
\nconst { app, Tray } = require('electron')\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\nElectron の Node.js 組み込みの影響で、module、exports、require のような余分なシンボルが DOM に追加されています。 このため、いくつかのライブラリでは同名のシンボルを追加しようとして問題が発生することがあります。
これを解決するために、Electron の node integration を無効にできます。
\n// メインプロセス\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n webPreferences: {\n nodeIntegration: false\n }\n})\nwin.show()\nそれでも Node.js と Electron API を使用した機能を維持したい場合は、他ライブラリを読み込む前に、ページ内のそのシンボル名を変更する必要があります。
\n<head>\n<script>\nwindow.nodeRequire = require;\ndelete window.require;\ndelete window.exports;\ndelete window.module;\n</script>\n<script type=\"text/javascript\" src=\"jquery.js\"></script>\n</head>\nrequire('electron').xxx が未定義です。Electron の組み込みモジュールを使うと、以下のエラーに遭遇するかもしれません。
\n> require('electron').webFrame.setZoomFactor(1.0)\nUncaught TypeError: Cannot read property 'setZoomLevel' of undefined\nこれは、間違ったプロセスでモジュールを使用している可能性が高いです。 たとえば、electron.app はメインプロセスのみ、electron.webFrame はレンダラープロセスのみで利用できます。
サブピクセルアンチエイリアス が無効だと、液晶画面上のフォントはぼやけて見えます。 サンプル:
\n
サブピクセルアンチエイリアスは不透明なレイヤーの背景が必要で、そのレイヤーはフォントグリフを含みます。 (詳しくは この issue を参照してください)。
\nこの目的を達成するには、BrowserWindow のコンストラクタで背景を設定しましょう。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n backgroundColor: '#fff'\n})\nこの効果は (一部の?) 液晶画面でしか見られません。 違いが見えなくても、ユーザーの中には違って見える人がいるかもしれません。 こうしてはいけない理由がなければ、背景は基本的にこのように設定するのが良いでしょう。
\nCSS で背景を設定するだけでは期待する効果はないことに注意してください。
", "title": "Electron FAQ", "description": "" }, "/docs/api/structures/file-filter": { "locale": "ja-JP", "slug": "file-filter", "href": "/docs/api/structures/file-filter", "crowdinFileId": "256435", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/file-filter.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "name Stringextensions String[]Fileオブジェクト\n\nファイルシステム上のファイルでネイティブに機能するHTML5
\nFileAPIを使用します。
DOMのファイルインターフェースは、ユーザーがHTML5ファイルAPIで直接ネイティブファイルを扱えるように、ネイティブファイルを抽象化します。 Electronは、File インターフェースにファイルシステム上のファイルの実際のパスを公開する path 属性を追加しています。
アプリの上にドラッグされたファイルから実際のパスを取得する例:
\n<div id=\"holder\">\n ファイルをここにドラッグ\n</div>\n\n<script>\n document.addEventListener('drop', (e) => {\n e.preventDefault();\n e.stopPropagation();\n\n for (const f of e.dataTransfer.files) {\n console.log('File(s) you dragged here: ', f.path)\n }\n });\n document.addEventListener('dragover', (e) => {\n e.preventDefault();\n e.stopPropagation();\n });\n</script>\npath String - The path to the file to send.headers Record<string, string> (optional) - Additional headers to be sent.\n\nツールバー、境界やその他のグラフィカルな\"枠\"のないウインドウを開きます。
\n
フレームレスウインドウは、Webページの一部ではないツールバーのようなウインドウの部品である chrome を持たないウインドウです。 これらは、BrowserWindow クラスのオプションです。
フレームレスウインドウを作成するには、BrowserWindow の options で frame を false に設定する必要があります。
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600, frame: false })\nwin.show()\nmacOS と Windows ではフレームレスウインドウを指定する方法が他にあります。 タイトルバーとウインドウコントロールの両方が無効になる frame を false に設定する方法の代わりに、タイトルバーを非表示にし、コンテンツをフルウインドウサイズに拡大しつつ、標準のウインドウアクションのためにウインドウコントロール (macOS での \"信号ボタン\") を保持し続けることもできます。 titleBarStyle オプションを指定すると、そのようにすることができます。
hiddenタイトルバーが隠れ、フルサイズのコンテンツウインドウになります。 macOS では、タイトルバーの左上に標準ウインドウコントロール (\"信号機ボタン\") が付きます。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hidden' })\nwin.show()\nhiddenInsetウインドウの端から信号ボタンが少し埋め込まれた別の見た目でタイトルバーが非表示になります。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })\nwin.show()\ncustomButtonsOnHoverウインドウの左上にカーソルを合わせたときに表示されるカスタム描画の閉じる、最小化ボタンを使用します。 フルスクリーンボタンは、フレームレスウインドウの制約のために利用できません。Apple の macOS ウインドウマスクと被るからです。 これらのボタンは標準のウインドウツールバーボタンで発生するマウスイベントの問題を防止します。 このオプションは、フレームレスウインドウにのみ適用されます。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover', frame: false })\nwin.show()\nフレームレスウインドウを macOS の win.setWindowButtonVisibility(true) と組み合わせて使用したり、信号機ボタンが見えるように上述の titleBarStyle のいずれかを使用したり、Windows の titleBarStyle: hidden を使用したりしているとき、titleBarOverlay のオプションを true に設定するとウィンドウコントロールオーバーレイ [JavaScript API][overlay-javascript-apis] と CSS 環境変数 にアクセスできます。 true を指定すると、オーバーレイはデフォルトのシステムカラーになります。
Windows では、color と symbolColor のオプションで作った titleBarOverlay オブジェクトを設定することで、オーバーレイとそのシンボルの色指定もできます。 以下のようにオプションを指定しない場合、ウインドウコントロールボタンの色はデフォルトでシステムカラーになります。
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: true\n})\nwin.show()\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: {\n color: '#2f3241',\n symbolColor: '#74b1be'\n }\n})\nwin.show()\ntransparent オプションを true に設定することで、フレームレスウインドウを透明にすることもできます。
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ transparent: true, frame: false })\nwin.show()\nresizable を true に設定すると、いくつかのプラットフォームでは透明なウインドウが機能しなくなることがあります。blur フィルターはWebページにしか適用されないため、ウインドウの下にあるコンテンツ (すなわち、ユーザーのシステムで開かれた他のアプリケーション) にぼかし効果を適用する方法はありません。--enable-transparent-visuals --disable-gpu を指定しなければなりません。これは、Linux における いくつかの NVidia ドライバーでアルファチャンネルが機能しない という上流のバグによるものです。クリックスルーウインドウを作成する、すなわち、ウインドウにすべてのマウスイベントを無視させるには、win.setIgnoreMouseEvents(ignore) APIを呼び出して下さい。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.setIgnoreMouseEvents(true)\nマウスのメッセージを無視すると、Webページでマウスの移動が検出されなくなり、マウスの移動イベントが発生しません。 Windowsオペレーティングシステムでは、mouseleave のようなイベントを発生させられるよう、マウスの移動メッセージをWebページに転送するのに、オプションパラメーターが使用されます。
const { ipcRenderer } = require('electron')\nconst el = document.getElementById('clickThroughElement')\nel.addEventListener('mouseenter', () => {\n ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })\n})\nel.addEventListener('mouseleave', () => {\n ipcRenderer.send('set-ignore-mouse-events', false)\n})\n\n// メインプロセス\nconst { ipcMain } = require('electron')\nipcMain.on('set-ignore-mouse-events', (event, ...args) => {\n BrowserWindow.fromWebContents(event.sender).setIgnoreMouseEvents(...args)\n})\nこれにより、el の上のとき、Webページはクリックスルーになり、その外側では、通常に戻ります。
既定では、フレームレスウインドウはドラッグできません。 アプリは、どの領域が (OSの標準のタイトルバーのように) ドラッグ可能であるかをElectronに伝えるため、CSSで -webkit-app-region: drag を指定することが必要です。また、アプリは、ドラッグ可能な領域からドラッグ不可能な領域を除外するため、-webkit-app-region: no-drag を使用することもできます。 現在のところ、長方形の形状しかサポートされていないことに注意して下さい。
注: -webkit-app-region: drag は、開発者ツールが開かれている間、問題があることが知られています。 回避策を含む詳細については、この GitHub Issue を参照して下さい。
ウインドウ全体をドラッグ可能にするには、body のスタイルとして -webkit-app-region: drag を追加して下さい。
<body style=\"-webkit-app-region: drag\">\n</body>\nそして、ウインドウ全体をドラッグ可能にした場合、ボタンをドラッグ不可として同時にマークしなければなりません。そうでなければ、ユーザーがボタンをクリックすることができなくなります。
\nbutton {\n -webkit-app-region: no-drag;\n}\nカスタムのタイトルバーをドラッグ可能に設定するだけの場合、同時にタイトルバーのすべてのボタンもドラッグ不可にする必要があります。
\nフレームレスウインドウでは、ドラッグの挙動がテキストの選択と競合する可能性があります。 例えば、タイトルバーをドラッグするとき、誤ってタイトルバーのテキストを選択する可能性があります。 これを防止するには、このようにドラッグ可能な領域内のテキスト選択を無効にする必要があります。
\n.titlebar {\n -webkit-user-select: none;\n -webkit-app-region: drag;\n}\nいくつかのプラットフォームでは、ドラッグ可能な領域は非クライアントのフレームとして扱われます。そのため、ドラッグ可能な領域を右クリックすると、システムメニューが現れます。 すべてのプラットフォームでコンテキストメニューが正しく動作するようにするには、絶対にカスタムのコンテキストメニューをドラッグ可能な領域で使用しないようにしてください。
\n[overlay-javascript-apis]: https://github. com/WICG/window-controls-overlay/blob/main/explainer.md#javascript-apis
", "title": "フレームレスウインドウ", "description": "ツールバー、境界やその他のグラフィカルな\"枠\"のないウインドウを開きます。" }, "/docs/tutorial/fuses": { "locale": "ja-JP", "slug": "fuses", "href": "/docs/tutorial/fuses", "crowdinFileId": "256201", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/fuses.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nパッケージ時機能切り替え
\n
Electron は機能の集合体なので、アプリケーション全体に渡って特定の機能を無効化しても合理的です。 例えば、99% のアプリは ELECTRON_RUN_AS_NODE を利用しないので、そういったアプリでその機能が利用できないバイナリを頒布できるようにしたいのです。 Electron の消費者がソースから Electron を構築することは技術的に大きな障害であり時間とお金両方のコストがかかるため、それも避けたいと考えています。
Fuse はこの問題の解決策です。高水準としては Electron バイナリ内の \"マジックビット\" であり、Electron アプリをパッケージングする際にそれらを反転させることで、特定の機能や制限を有効化/無効化できます。 アプリのコード署名前のパッケージ時に反転するので、OS は OS レベルのコード署名検証(Gatekeeper / App Locker) の時に反転しないようにする責任があります。
\nこれら Fuse を簡単に反転させるために、便利なモジュール @electron/fuses を作成しました。 使用方法や潜在的なエラーケースといった詳細は、このモジュールの README を確認してください。
require('@electron/fuses').flipFuses(\n // electron のパス\n require('electron'),\n // 反転する Fuse\n {\n runAsNode: false\n }\n)\n手動で Fuse を反転させるには、Electron バイナリを編集し必要な Fuse の状態を表すバイト列になるように Fuse Wire を修正する必要があります。
\nElectron バイナリのどこかに、以下のようなバイト列があります。
\n| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |\nsentinel_bytes は厳密にこのような文字列 dL7pKGdnNz796PbbjQWNKmHXBZaB9tsX ですfuse_version は単一バイトで、その符号無し整数の値が Fuse Schema のバージョンを表します。fuse_wire_length は単一バイトで、その符号無し整数の値は後続の Fuse Wire にある Fuse の数を表します。fuse_wire は N バイトのシーケンスで、各バイトは 1 つの Fuse とその状態を表します。Fuse を反転させるには、Fuse Wire の位置を見つけ、状態に応じて \"0\" または \"1\" に変更します。
\n現在のスキーマは こちら で閲覧できます。
", "title": "Electron Fuse", "description": "パッケージ時機能切り替え" }, "/docs/api/global-shortcut": { "locale": "ja-JP", "slug": "global-shortcut", "href": "/docs/api/global-shortcut", "crowdinFileId": "256323", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/global-shortcut.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nアプリケーションにキーボードフォーカスがないときにキーボードイベントを検出します。
\n
プロセス: Main
\nglobalShortcut モジュールは、オペレーティングシステムに対してグローバルショートカットを登録/登録解除することができます。そのため、様々なショートカットに対する操作をカスタマイズすることができます。
注: ショートカットはグローバルです。そのため、アプリにキーボードフォーカスがない場合でも機能します。 app モジュールの ready イベントが発生するよりも前では、このモジュールは使用できません。
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // 'CommandOrControl+X' ショートカットのリスナーを登録します。\n const ret = globalShortcut.register('CommandOrControl+X', () => {\n console.log('CommandOrControl+X is pressed')\n })\n\n if (!ret) {\n console.log('registration failed')\n }\n\n // ショートカットが登録されているかどうかをチェックします。\n console.log(globalShortcut.isRegistered('CommandOrControl+X'))\n})\n\napp.on('will-quit', () => {\n // ショートカットを登録解除します。\n globalShortcut.unregister('CommandOrControl+X')\n\n // すべてのショートカットを登録解除します。\n globalShortcut.unregisterAll()\n})\nglobalShortcut モジュールには以下のメソッドがあります。
globalShortcut.register(accelerator, callback)accelerator Acceleratorcallback Function戻り値 Boolean - ショートカットが正常に登録されたかどうか.
accelerator のグローバルショートカットを登録します。 callback は登録したショートカットがユーザに押下されたときに呼び出されます。
アクセラレータが他のアプリケーションによってすでに使用されている場合、この呼び出しは何も通知することなく失敗します。 この動作は、アプリケーションにグローバルショートカットの取り合いをさせたくないため、オペレーティングシステムによって意図されたものです。
\n以下のアクセラレータは、アプリが 信頼できるアクセシビリティクライアント として認識されていない限り macOS 10.14 Mojave に正常に登録されません。
\nglobalShortcut.registerAll(accelerators, callback)accelerators String[] - Acceleratorの配列callback Functionaccelerators 内の全ての accelerator のグローバルショートカットを登録します。 callback は登録したいずれかのショートカットがユーザに押下されたときに呼び出されます。
与えられたアクセラレータが他のアプリケーションによってすでに使用されている場合、この呼び出しは何も通知することなく失敗します。 この動作は、アプリケーションにグローバルショートカットの取り合いをさせたくないため、オペレーティングシステムによって意図されたものです。
\n以下のアクセラレータは、アプリが 信頼できるアクセシビリティクライアント として認識されていない限り macOS 10.14 Mojave に正常に登録されません。
\nglobalShortcut.isRegistered(accelerator)accelerator Accelerator戻り値 Boolean - このアプリケーションが accelerator を登録したかどうか。
アクセラレータが他のアプリケーションによってすでに使用されている場合、この呼び出しは false を返すはずです。 この動作は、アプリケーションにグローバルショートカットの取り合いをさせたくないため、オペレーティングシステムによって意図されたものです。
globalShortcut.unregister(accelerator)accelerator Acceleratoraccelerator のグローバルショートカットを登録解除します。
globalShortcut.unregisterAll()すべてのグローバルショートカットを登録解除します。
", "title": "globalShortcut", "description": "アプリケーションにキーボードフォーカスがないときにキーボードイベントを検出します。" }, "/docs/glossary": { "locale": "ja-JP", "slug": "glossary", "href": "/docs/glossary", "crowdinFileId": "256123", "githubUrl": "https://github.com/electron/electron/tree/main/docs/glossary.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "このページでは、Electron の開発で一般的に使用される用語を示します。
\nASARはAtom Shell Archive Formatの略語です。 asarアーカイブは、複数のファイルを1つにまとめるtarライクでシンプルなアーカイブ形式です。 Electron はASARファイルから全体を解凍せずに任意のファイルを読み出すことができます。
ASAR フォーマットは、主に Windows で大量の小さなファイルを読み込むとき (例: アプリケーションの JavaScript 依存関係ツリーを node_modules から読み込む場合など) のパフォーマンス向上のために作成されました。
コード署名とは、アプリ開発者によるパッケージ作成後のコード改ざんを検出するために、コードにデジタル署名を行う処理です。 Windows と macOS はどちらも独自のコード署名を実装しています。 デスクトップアプリケーションの開発者としてコードを一般公衆に頒布する予定の方は、コード署名が重要です。
\n詳しい情報については、コード署名 のチュートリアルをご参照ください。
\nコンテキストの分離は Electron によるセキュリティ施策で、プリロードスクリプトが特権的な Electron や Node.js の API をレンダラープロセスのウェブコンテンツに漏らさないようにします。 コンテキストの分離を有効にすると、プリロードスクリプトから API を公開するには contextBridge API を使用するしかありません。
詳しい情報については、コンテキストの分離 のチュートリアルをご参照ください。
\n関連項目: プリロードスクリプト、レンダラープロセス
\nC ランタイム ライブラリ (CRT, C Run-time Library) は ISO C99 標準ライブラリが組み込まれている C++ 標準ライブラリの一部です。 ネイティブコード開発、ネイティブコードと管理コードの混在した開発、.Netの純粋な管理コードをサポートするCRTを実装するVisual C++ライブラリ
\nApple Disk Image (DMG) はmacOSで使用されるパッケージング形式です。 DMGファイルはインストーラーアプリケーションを配布するために使用されます。
\nInput Method Editorの略で、日本では「かな漢字変換システム」を指します。 日本のユーザにとっては何を今更という説明になりますが、漢字などキーボード上に存在しない文字や記号を入力するためのツールです。 日本語、中国語、韓国語に限らず、インドの言語などもIMEを使用することでアルファベット（ローマ字）から入力することができます。
\nInterface description language、インターフェイス記述言語のことです。 Java、C++、JavaScript などのインターフェース生成に使用できるフォーマットで、関数のシグネチャやデータ型を記述します。
\nIPC は Inter-Process Communication、プロセス間通信の略です。 Electron では IPC を、メインプロセスとレンダラープロセスの間でのシリアライズした JSON メッセージの送信に使用します。
\nメインプロセス、レンダラープロセスについても参照してください。
\nメインプロセスは通常 main.js というファイル名で配置され、Electron アプリのエントリポイントになります。 これはアプリが開始してから終了するまでを制御します。 また、メニュー、メニューバー、ドック、タスクトレイなどのネイティブ要素の管理も担当します。 メインプロセスは、アプリ内のレンダラプロセスの作成も担います。 完全な Node API を使用できます。
各アプリのメインプロセスファイルは、package.json の main プロパティに指定します。 electron . はここから起動時に実行するファイルを取得します。
Chromium では、このプロセスを \"ブラウザプロセス\" と呼びます。 レンダラープロセスとの混同を避けるため、Electron では名前を変更しています。
\n\nApple の Mac App Store の頭文字をつなげたものです。 MAS へのアプリ登録の詳細は、Mac App Store 登録ガイド を参照してください。
\nプロセス内またはプロセス間で通信するための IPC システムです。これが重要なのは、Chrome がメモリの圧迫などに応じて作業を別プロセスに分割できるかどうかを判断しているためです。
\n（参照： https://chromium.googlesource.com/chromium/src/+/master/mojo/README.md ）
\n関連項目: IPC
\nWindows では、アプリケーションのインストールと設定のために Windows Installer (別称 Microsoft Installer) サービスが MSI パッケージを使用します。
\n詳しい情報は Microsoft のドキュメント に記載されています。
\nネイティブ モジュールはNode.js ではアドオン とも呼ばれ、requireによってNode.jsやElectronへ読み込むことの出来る、C またはC++で書かれたモジュールです。通常のNode.jsモジュールと同様に使用することが出来ます。 主に、Node.jsで実行されているJavaScript と C/C++ のライブラリ間のインタフェースを提供するために使用されます。
\nElectronは、ネイティブのNodeモジュールをサポートしていますが、システム上にインストールされたNodeとは異なるV8バージョンを使用しているので、ネイティブモジュールでビルドする時、Electronのヘッダーの場所を手動で指定する必要があります。
\n詳しい情報については、[ネイティブ Node モジュール] のチュートリアルをご参照ください。
\n公証とは、macOS 特有のプロセスで、開発者がコード署名したアプリをアップルのサーバーに送り、自動サービスによって悪意あるコンポーネントの有無を検証してもらうものです。
\n関連項目: コード署名
\nOSR (offscreen rendering、オフスクリーンレンダリング) を使用すると、重いページをバックグラウンドで読み込みんだ後で表示することができます (かなりの高速化が期待されます)。 画面に表示することなくページをレンダリングできます。
\n詳しい情報については、オフスクリーンレンダリング[osr] のチュートリアルをご参照ください。
\nプリロードスクリプトは、ウェブコンテンツの読み込み開始前にレンダラープロセス内で実行されるコードです。 これらのスクリプトはレンダラーのコンテキスト内で実行されますが、Node.js の API にアクセスできるようにより多くの権限が与えられています。
\n\nプロセスは、実行されているプログラムのインスタンスです。 Electronでは、メインプロセスと 1つ以上のレンダラープロセスが動作しており、実際には同時に複数のプログラムが実行されていることになります。
\nNode.jsとElectronでは、実行中のプロセスは、processオブジェクトをもっています。 このオブジェクトは現在のプロセスに関する情報を提供し、また制御を行う広域変数です。 広域変数であるため、require() を使用せずにいつでもアクセスできます。
メインプロセス、レンダラープロセスについても参照してください。
\nレンダラープロセスは、アプリ内のブラウザウインドウです。 メインプロセスと違って複数存在でき、それぞれ別のプロセスとして動作します。 また、非表示にもできます。
\n\nサンドボックスとは、Chromium から受け継いだセキュリティ機能で、レンダラープロセスを限られた権限に制限するものです。
\n詳しい情報については、プロセスのサンドボックス化 のチュートリアルをご参照ください。
\n関連項目: プロセス
\nSquirrelは、Electronアプリケーションの新しいバージョンに対する自動更新を可能にするオープンソースフレームワークです。 Squirrelについては autoUpdater APIを参照してください。
\nUnixコミュニティーに由来する言葉ですが、\"ユーザーランド\"や\"ユーザースペース\"は、Osカーネルの外側で動作するプログラムを意味します。 より最近では、この用語はNodeやnpmコミュニティでは、\"Node core\"で使用できる機能を、大きな\"ユーザー\"コミュニティ npmに登録して公開されたパッケージを区別されるために使用されます。
\nNode.jsのように、Electronはマルチプラットフォームなデスクトップアプリケーション開発に必要なすべての原始的機能を提供するスモールセットAPIを提供することに焦点を当てています。 この設計思想により、Electronは過度にルールに則りすぎたものになることなく、柔軟性を持つツールであり続けることが可能になっています。 ユーザーランドは、\"core\"で使用できる物の上に追加機能を提供するツールを作成したり共有したりすることを可能にします。
\nV8 は Google のオープンソース JavaScript エンジンです。 C++ で書かれており、Google Chrome で使用されています。 V8 はスタンドアローンで実行することも、任意の C++ アプリケーションに組み込むこともできます。
\nElectron は V8 を Chromium の一部としてビルドし、それからNodeをビルドする際に NodeがV8を指すようにします。
\nV8 のバージョンは必ず Google Chrome のバージョンに対応しています。 例えば Chrome 59 には V8 5.9 が入っており、Chrome 58 には V8 5.8 が入っています。
\n\nwebview タグは、Electron アプリに 'ゲスト' コンテンツ (外部のウェブページなど) を埋め込むために使用します。 これらは iframe に似ていますが、それぞれの webview が別のプロセスで実行されるという点が異なります。 あなたのウェブページとは同じ権限はもっておらず、アプリと埋め込まれたコンテンツのやりとりは非同期的な物になります。 アプリはこれにより埋め込みコンテンツから安全を保たれます。
\n\nGoma は Chromium や Android などのオープンソースプロジェクト向けに公開されたコンパイラサービスです。
\n
Electron はカスタム Goma バックエンドのデプロイがあり、これはすべての Electron メンテナーが利用できます。 認証詳細情報については以下にある アクセス の章を参照してください。 資格情報がない場合にデフォルトで使用される cache-only Goma エンドポイントもあります。 cache-only Goma へのリクエストはクラスターにヒットしませんが、キャッシュから読み取るためビルド時間が大幅に短縮されます。
現在、Goma の使用をサポートしている方法は、ビルドツール の使用のみです。 build-tools をセットアップすると、Goma の設定が自動的にインクルードされます。
あなたがメンテナーかつクラスターにアクセスできる場合は、Goma クラスターを使用する build-tools を構成するために e init を --goma=cluster 付きで実行するようにしてください。 既存のコンフィグがある場合は、\"goma\": \"cluster\" をコンフィグファイルにセットするだけです。
Goma を使用している場合、マシンで通常サポートされている値よりも大幅に大きい値の j で ninja を実行できます。
Windows や Linux では 200、macOS では 50 より大きい値を設定しないでください。 Goma システムの使用状況は監視されており、不合理な並列実行で Goma システムを悪用していることが判明したユーザーは無効になります。
\nninja -C out/Testing electron -j 200\nbuild-tools を使用している場合、適切な -j の値が自動的に使用されます。
ローカルマシンで http://localhost:8088 にアクセスすると、Goma システムを通過するコンパイルジョブを監視できます。
\n現在、セキュリティとコストの理由により Electron Goma へのアクセスは Electron メンテナーに制限されています。 アクセスしたい場合は、Slack の #access-requests にアクセスし、@goma-squad に連絡してアクセスを要求してください。 メンテナーであることはアクセスを 自動的に 許可するものではなく、アクセスはその場に応じて許可されることに留意してください。
https://status.notgoma.com で Goma クラスターとキャッシュの監視を自動化しています
\nGoma の使用に対するサポートは提供していません。ヘルプを求める Issue は ほぼ全て 理由なくクローズします。そういったサポートは取り扱いません。
", "title": "Goma", "description": "Goma は Chromium や Android などのオープンソースプロジェクト向けに公開されたコンパイラサービスです。" }, "/docs/api/structures/gpu-feature-status": { "locale": "ja-JP", "slug": "gpu-feature-status", "href": "/docs/api/structures/gpu-feature-status", "crowdinFileId": "256439", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/gpu-feature-status.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "2d_canvas String - Canvas.flash_3d String - Flash.flash_stage3d String - Flash Stage3D.flash_stage3d_baseline String - Flash Stage3D Baseline profile.gpu_compositing String - Compositing.multiple_raster_threads String - Multiple Raster Threads.native_gpu_memory_buffers String - Native GpuMemoryBuffers.rasterization String - Rasterization.video_decode String - Video Decode.video_encode String - Video Encode.vpx_decode String - VPx Video Decode.webgl String - WebGL.webgl2 String - WebGL2.取りうる値:
\ndisabled_software - Software only. Hardware acceleration disabled (yellow)disabled_off - Disabled (red)disabled_off_ok - Disabled (yellow)unavailable_software - Software only, hardware acceleration unavailable (yellow)unavailable_off - Unavailable (red)unavailable_off_ok - Unavailable (yellow)enabled_readback - Hardware accelerated but at reduced performance (yellow)enabled_force - Hardware accelerated on all pages (green)enabled - Hardware accelerated (green)enabled_on - Enabled (green)enabled_force_on - Force enabled (green)deviceId String - デバイスの一意な識別子。name String - デバイス名。vendorId Integer - USB 製造元 ID。productId Integer - USB 製品 ID。serialNumber String (任意) - USB デバイスのシリアル番号。guid String (任意) - HID インターフェイスの一意な識別子。 デバイスによっては複数の HID インターフェースを保持することがあります。\n\nMac App Store のアプリ内購入。
\n
プロセス: Main
\ninAppPurchase モジュールは以下のイベントが発生します。
1つ以上のトランザクションが更新されたときに発生します。
\n戻り値：
\nevent Eventtransactions Transaction[] - Transaction オブジェクトの配列。inAppPurchase モジュールには以下のメソッドがあります。
inAppPurchase.purchaseProduct(productID[, quantity])productID String - 購入する製品の識別子。 (com.example.app.product1 の識別子は product1)。quantity Integer (任意) - ユーザーが購入しようとしている商品数。戻り値 Promise<Boolean> - プロダクトが有効で支払いキューに追加されている場合は、true を返します。
purchaseProduct を呼び出す前に、できるだけ早く transactions-updated イベントをリッスンする必要があります。
inAppPurchase.getProducts(productIDs)productIDs String[] - 取得する製品の識別子。戻り値 Promise<Product[]> - Product オブジェクトの配列で実行されます。
製品説明を探します。
\ninAppPurchase.canMakePayments()戻り値 Boolean - ユーザが支払いできるかどうか。
inAppPurchase.restoreCompletedTransactions()購入済みの支払いを復元します。 このメソッドは、更なるデバイスに購入品をインストールしたり、ユーザーが削除して再インストールしたアプリケーションの購入品を復元したりするために呼び出すことができます。
\n支払いキュー では、以前に完了した取引ごとに新しい取引情報を提供し復元できるようにします。 各取引は元の取引情報のコピーを含みます。
\ninAppPurchase.getReceiptURL()戻り値 String - 領収書へのパス。
inAppPurchase.finishAllTransactions()すべての保留中の取引を完了させます。
\ninAppPurchase.finishTransactionByDate(date)date String - 取引を終える ISO 形式の日付。日付に対応するすべての保留中の取引を完了させます。
", "title": "inAppPurchase", "description": "Mac App Store のアプリ内購入。" }, "/docs/tutorial/in-app-purchases": { "locale": "ja-JP", "slug": "in-app-purchases", "href": "/docs/tutorial/in-app-purchases", "crowdinFileId": "256203", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/in-app-purchases.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "まだしていないのであれば、iTunes Connect 内で有料アプリケーション契約に署名し、銀行口座情報と納税フォームをセットアップする必要があります。
\niTunes Connect デベロッパーヘルプ: 契約／税金／口座情報の概要
\n次に、iTunes Connect でアプリ内購入を設定し、名前、価格、説明、アプリ内購入の特徴と機能の説明などの詳細を含める必要があります。
\niTunes Connect デベロッパーヘルプ: App 内課金の作成
\nElectron での開発で App 内課金をテストするには、node_modules/electron/dist/Electron.app/Contents/Info.plist 内の CFBundleIdentifier を変更する必要があります。 iTunes Connect で作成したアプリケーションのバンドル ID で、com.github.electron を置き換える必要があります。
<key>CFBundleIdentifier</key>\n<string>com.example.app</string>\n以下は、Electron でアプリ内課金を使用する方法を示した例です。 製品 ID を iTunes Connect で作成された製品の識別子で置き換える必要があります (com.example.app.product1 の識別子は product1 です)。 アプリ内で transactions-updated イベントをできる限り早くリッスンする必要があることに注意してください。
// メインプロセス\nconst { inAppPurchase } = require('electron')\nconst PRODUCT_IDS = ['id1', 'id2']\n\n// できるだけ早くトランザクションをリッスンします。\ninAppPurchase.on('transactions-updated', (event, transactions) => {\n if (!Array.isArray(transactions)) {\n return\n }\n\n // それぞれのトランザクションを確認します。\n transactions.forEach(function (transaction) {\n const payment = transaction.payment\n\n switch (transaction.transactionState) {\n case 'purchasing':\n console.log(`Purchasing ${payment.productIdentifier}...`)\n break\n\n case 'purchased': {\n console.log(`${payment.productIdentifier} purchased.`)\n\n // 領収書の URL を取得します。\n const receiptURL = inAppPurchase.getReceiptURL()\n\n console.log(`Receipt URL: ${receiptURL}`)\n\n // 領収書ファイルをサーバーに送信して、それが有効かどうかを確認します。\n // こちらを参照 https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html\n // ...\n // 領収書が有効であれば、プロダクトは購入されます\n // ...\n\n // トランザクションを終了します。\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n }\n\n case 'failed':\n\n console.log(`Failed to purchase ${payment.productIdentifier}.`)\n\n // トランザクションを終了します。\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n case 'restored':\n\n console.log(`The purchase of ${payment.productIdentifier} has been restored.`)\n\n break\n case 'deferred':\n\n console.log(`The purchase of ${payment.productIdentifier} has been deferred.`)\n\n break\n default:\n break\n }\n })\n})\n\n// ユーザに App 内課金が許可されているかどうか確認します。\nif (!inAppPurchase.canMakePayments()) {\n console.log('The user is not allowed to make in-app purchase.')\n}\n\n// 製品の説明を探して表示します。\ninAppPurchase.getProducts(PRODUCT_IDS).then(products => {\n // 引数を確認します。\n if (!Array.isArray(products) || products.length <= 0) {\n console.log('Unable to retrieve the product informations.')\n return\n }\n\n // 各製品の名前と価格を表示します。\n products.forEach(product => {\n console.log(`The price of ${product.localizedTitle} is ${product.formattedPrice}.`)\n })\n\n // どの製品を購入したいかをユーザーに尋ねます。\n const selectedProduct = products[0]\n const selectedQuantity = 1\n\n // 選択した製品を購入します。\n inAppPurchase.purchaseProduct(selectedProduct.productIdentifier, selectedQuantity).then(isProductValid => {\n if (!isProductValid) {\n console.log('The product is not valid.')\n return\n }\n\n console.log('The payment has been added to the payment queue.')\n })\n})\n\n\nHTTP/HTTPSリクエストに対するレスポンスを処理します。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
IncomingMessage は Readable Stream インターフェースを実装しているため、EventEmitter です。
戻り値：
\nchunk Buffer - レスポンスボディのデータのチャンク。data イベントはレスポンスデータを実用的なコードに移す常套手段です。
レスポンスボディが終了したことを示します。 'data' イベントの前に配置する必要があります。
\n現在進行しているHTTPのやり取り中にリクエストがキャンセルされたときに発生します。
\n戻り値：
\nerror Error - 通常は、根本的な原因を識別するエラー文字列を保持します。
レスポンスデータのイベントをストリーミングしている最中にエラーが発生したときに発生します。 例えば、レスポンスのストリーミング中にサーバーがその基をクローズした場合、error イベントがレスポンスオブジェクトで発生し、続いて close イベントがリクエストオブジェクトで発生します。
IncomingMessage のインスタンスには、以下の読み取り可能なプロパティがあります。
response.statusCodeHTTPレスポンスステータスコードを表す Integer。
response.statusMessageHTTPステータスメッセージを表す String。
response.headersRecord<string, string | string[]> 型。HTTP レスポンスヘッダを表します。 headers オブジェクトは以下のようにフォーマットされます:
age、authorization、content-length、content-type、etag、expires、from、host、if-modified-since、if-unmodified-since、last-modified、location、max-forwards、proxy-authorization、referer、retry-after、server、user-agent の重複は破棄されます。set-cookie は常に配列です。 重複は配列へと追加されます。cookie ヘッダは、値を '; ' で結合します。response.httpVersionHTTPプロトコルのバージョン番号を示す String。 典型的な値は、'1.0'や'1.1'です。 さらに、httpVersionMajor と httpVersionMinor は、2つともIntegerの値を返す読み取り専用プロパティで、それぞれHTTPのメジャーとマイナーのバージョン番号を返します。
response.httpVersionMajorHTTPプロトコルのメジャーバージョン番号を示す Integer。
response.httpVersionMinorHTTPプロトコルのマイナーバージョン番号を示す Integer。
modifiers String - An array of modifiers of the event, can be shift, control, ctrl, alt, meta, command, cmd, isKeypad, isAutoRepeat, leftButtonDown, middleButtonDown, rightButtonDown, capsLock, numLock, left, right.Electron のビルド済みバイナリをインストールするには、npm を使用します。 アプリの開発用依存関係として Electron をインストールする方法を推奨します。
npm install electron --save-dev\nアプリ内で Electron のバージョンを管理する方法については、Electron のバージョン管理 を参照して下さい。
\nもし急用かつローカルプロジェクト内で npm install を使用すべきでない場合は、以下のように npm にバンドルされている npx コマンドランナー を使った Electron の臨時実行もできます。
npx electron .\n上記のコマンドは、Electron で現在のワーキングディレクトリを実行します。 注意としてアプリ内の依存関係がインストールされることはありません。
\nダウンロードするアーキテクチャを変更したい (例えば ia32 を x64 マシン上にインストールする) 場合、以下のように npm install に --arch フラグを指定するか、npm_config_arch 環境変数を指定してください。
npm install --arch=ia32 electron\nアーキテクチャに加えてプラットフォーム (win32、linuxなど) も変更する場合は、更に --platformフラグを指定できます。
npm install --platform=win32 electron\nHTTP プロキシを使用する必要がある場合は、ELECTRON_GET_USE_PROXY 変数を任意の値に設定する必要があります。さらに、ホストシステムの Node のバージョンに応じて追加の環境変数を設定する必要があります。
インストール中、electron モジュールは @electron/get を呼び出して、プラットフォーム用のビルド済み Electron バイナリをダウンロードします。 これは Github のリリースダウンロードページ (https://github.com/electron/electron/releases/tag/v$VERSION、 $VERSION は Electron の正確なバージョン) からダウンロードします。
もし Github にアクセス出来ないかカスタムビルドを提供する必要がある場合、他に提供されているミラーや既存のキャッシュからダウンロードできます。
\n基底URL、Electron のバイナリを見つけるためのパス、バイナリのファイル名は、環境変数を用いて上書きできます。 @electron/get で使われる URL は以下の組み合わせです。
url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME\n例として、中国の CDN ミラーを使うにはこうします。
\nELECTRON_MIRROR=\"https://cdn.npm.taobao.org/dist/electron/\"\n既定の ELECTRON_CUSTOM_DIR は v$VERSION です。 この形式を変更するには、{{ version }} プレースホルダーを使用します。 例えば、version-{{ version }} は version-5.0.0 に解決され、{{ version }} は 5.0.0 に解決されます。v{{ version }} は既定と等価です。 より具体的な例として、中国の非 CDN ミラーを使用してみます。
ELECTRON_MIRROR=\"https://npm.taobao.org/mirrors/electron/\"\nELECTRON_CUSTOM_DIR=\"{{ version }}\"\n上記の構成では、https://npm.taobao.org/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip の URL からダウンロードされます。
ミラーが公式の Electron リリースと異なるチェックサムのアーティファクトを提供している場合、Electron が組み込みチェックサムの代わりに外部の SHASUMS256.txt ファイルをチェックサム検証に使うように ELECTRON_USE_REMOTE_CHECKSUMS=1 と設定する必要があるでしょう。
代わりに、ローカルキャッシュを上書きできます。 @electron/get はあなたのネットワークに負荷がかからないように、ダウンロードしたバイナリをローカルディレクトリにキャッシュします。 そのキャッシュフォルダは、Electron のカスタムビルドの提供やネットワークとの接続を回避するために使用できます。
$XDG_CACHE_HOME または ~/.cache/electron/~/Library/Caches/electron/$LOCALAPPDATA/electron/Cache または ~/AppData/Local/electron/Cache/古いバージョンの Electron を使用していた環境の場合は、~/.electron 内にもキャッシュがあるかもしれません。
また、electron_config_cache 環境変数を設けることでローカルキャッシュの場所を上書きできます。
キャッシュには、バージョンの公式の zip ファイルと共に、テキストファイルとして格納されているチェックサムが含まれています。 典型的なキャッシュは、次のようになっています。
\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9electron-v1.7.9-darwin-x64.zip\n│ └── electron-v1.7.9-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1electron-v1.8.1-darwin-x64.zip\n│ └── electron-v1.8.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1electron-v1.8.2-beta.1-darwin-x64.zip\n│ └── electron-v1.8.2-beta.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2electron-v1.8.2-beta.2-darwin-x64.zip\n│ └── electron-v1.8.2-beta.2-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3electron-v1.8.2-beta.3-darwin-x64.zip\n│ └── electron-v1.8.2-beta.3-darwin-x64.zip\n└── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3SHASUMS256.txt\n └── SHASUMS256.txt\n実際には、Electron の JavaScript API はその実装を格納するバイナリにバインドされています。 このバイナリは Electron アプリの動作に不可欠であるため、npm レジストリから electron をインストールするたびに postinstall ステップにおいて既定でダウンロードされます。
しかし、プロジェクトの依存関係をインストールしたいものの Electron の機能を使う必要がない場合は、ELECTRON_SKIP_BINARY_DOWNLOAD 環境変数を設定してバイナリのダウンロードを抑止できます。 例えば、継続的インテグレーション環境において electron モジュールをモックアウトした単体テストを実行する際に、この機能が役立ちます。
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install\nnpm install electron を実行するとき、インストール時エラーが発生する場合があります。
ほとんどの場合、このエラーはネットワークによるもので、electron の npm パッケージに問題はありません。 ELIFECYCLE、EAI_AGAIN、ECONNRESET、ETIMEDOUT といったエラーは、ネットワーク上の問題を示しています。 最善の解決策は、ネットワークを切り替えるか、少し待ってからもう一度インストールしてることです。
npm を介したインストールに失敗する場合、Electron の electron/electron/releases からの直接ダウンロードを試みることもできます。
インストールが EACCESS エラーで失敗する場合は、npm の権限の修正 が必要かもしれません。
上記のエラーが続く場合は、unsafe-perm フラグを true にする必要があるでしょう。
\nsudo npm install electron --unsafe-perm=true\n速度の遅いネットワークでは、--verboseを指定してダウンロード進捗を表示することでなにか役に立つ情報が得られるかもしれません。
npm install --verbose electron\n強制的に再ダウンロードする必要がある場合は、force_no_cache環境変数をtrueに設定してください。
Electron ドキュメントへようこそ！ 初めて Electron アプリを開発する方は、このはじめにを読んで基本的な知識を身につけてください。 そうでない方は、ガイドや API ドキュメントもご利用ください！
\nElectron は、JavaScript、HTML、CSS によるデスクトップアプリケーションを構築するフレームワークです。 Electron は Chromium と Node.js をバイナリに組み込むことで、単一の JavaScript コードベースを維持しつつ、ネイテイブ開発経験無しでも Windows、macOS、Linux で動作するクロスプラットフォームアプリを作成できます。
\nこのドキュメントは、読者が Node.js と一般的なウェブ開発の両方に精通していることを前提にしています。 これらの分野のいずれかに精通しておきたい方は、以下のリソースをお勧めします。
\n\nまた、Chromium のプロセスモデルを知っていると Electron の仕組みをより理解しやすくなります。 2008 年の Chrome 発表と同時に公開された Chrome 漫画 には、Chrome のアーキテクチャの概要が載っています。 その公開から 10 年以上経っていますが、この漫画で紹介された基本原理は Electron の理解に役立ちます。
\nElectron Fiddle は Electron で書かれたサンドボックスアプリで、Electron のメンテナがサポートしています。 Electron の API を試したり開発中の機能を試作するための学習ツールとして、インストールを強く推奨します。
\nまた、Fiddle はドキュメントとうまく統合してあります。 チュートリアルのサンプルを見ていると、コードブロックの下に \"Electron Fiddle で開く\" ボタンが表示されていることがよくあります。 Fiddle がインストールされている場合、このボタンを押すと fiddle.electronjs.org のリンクが開き、コピーペーストせずとも自動的に Fiddle にサンプルがロードされます。
どこかで行き詰まってしまいましたか? こちらに、ご覧いただきたいリンクがいくつかあります。
\nelectron パッケージのバグが疑われる場合は、GitHub Issue トラッカー で既存の Issue とあなたの Issue に合致するものがないかご確認ください。 もし無ければ、バグレポートのテンプレートに記入し、新しい Issue をご提出ください。readOperationCount Number - The number of I/O read operations.writeOperationCount Number - The number of I/O write operations.otherOperationCount Number - Then number of I/O other operations.readTransferCount Number - The number of I/O read transfers.writeTransferCount Number - The number of I/O write transfers.otherTransferCount Number - Then number of I/O other transfers.\n\nメインプロセスからレンダラープロセスへ非同期で通信を行います。
\n
プロセス: Main
\nipcMain モジュールは Event Emitter を継承しています。 メインプロセスで使用される場合、レンダラープロセス (ウェブページ) から送られる非同期及び同期メッセージを処理します。 レンダラーから送信されたメッセージは、このモジュールに送られます。
また、メインプロセスからレンダラープロセスにメッセージを送ることもできます。より詳しくは webContents.send を参照して下さい。
\nchannel です。event.returnValue を設定する必要があります。event.reply(...) を使用できます。 このヘルパーメソッドはメインフレームではないフレーム (例: iframe) から来るメッセージを自動的に処理します。一方、event.sender.send(...) は常にメインフレームに送信されます。レンダラー/メインプロセス間のメッセージの送信と処理の例:
\n// メインプロセス\nconst { ipcMain } = require('electron')\nipcMain.on('asynchronous-message', (event, arg) => {\n console.log(arg) // \"ping\"を表示\n event.reply('asynchronous-reply', 'pong')\n})\n\nipcMain.on('synchronous-message', (event, arg) => {\n console.log(arg) // \"ping\"を表示\n event.returnValue = 'pong'\n})\n// レンダラープロセス（ウェブページ）\n// 備考: Electron の API は、contextIsolation が無効でない限りプリロードからのみアクセスできます。\n// 詳細は https://www.electronjs.org/docs/tutorial/process-model#preload-scripts をご参照ください。\nconst { ipcRenderer } = require('electron')\nconsole.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // \"pong\"を表示\n\nipcRenderer.on('asynchronous-reply', (event, arg) => {\n console.log(arg) // \"pong\"を表示\n})\nipcRenderer.send('asynchronous-message', 'ping')\nipcMain オブジェクトは、イベントを受け取るために以下のメソッドがあります。
ipcMain.on(channel, listener)channel Stringlistener Functionevent IpcMainEvent...args any[]channel に新しいメッセージが来たときに listener が listener(event, args...) として呼ばれます、
ipcMain.once(channel, listener)channel Stringlistener Functionevent IpcMainEvent...args any[]イベントに対する一回限りの listener 関数を追加します。 この listener は、次にメッセージが channel へ送信されたときに、削除されてから呼び出されます。
ipcMain.removeListener(channel, listener)channel Stringlistener Function...args any[]指定した channel の listener 配列から、指定した listener を削除します。
ipcMain.removeAllListeners([channel])channel String (任意)指定した channel の listener を全て削除します。
ipcMain.handle(channel, listener)channel Stringlistener Function<Promise\\event IpcMainInvokeEvent...args any[]invoke 可能な IPC のハンドラを追加します。 このハンドラは、レンダラが ipcRenderer.invoke(channel, ...args) を呼び出したとき常に呼び出されます。
listener が Promise を返す場合、Promise の最終的な結果は、リモート呼び出し元への応答として返されます。 それ以外は、リスナーの戻り値が応答の値として使用されます。
// メインプロセス\nipcMain.handle('my-invokable-ipc', async (event, ...args) => {\n const result = await somePromise(...args)\n return result\n})\n\n// レンダラープロセス\nasync () => {\n const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)\n // ...\n}\nハンドラーの最初の引数として渡される event は、通常のイベントリスナーに渡されるものと同じです。 どの WebContents が呼び出しリクエスト元であるかに関する情報が含まれています。
メインプロセスの handle から投げられたエラーはシリアライズされ、元のエラーからの message プロパティのみがレンダラープロセスに提供されるため、非透過的です。 詳細は #24427 をご参照ください。
ipcMain.handleOnce(channel, listener)channel Stringlistener Function<Promise\\event IpcMainInvokeEvent...args any[]1 つの invoke 可能な IPC メッセージを処理し、リスナーを削除します。 ipcMain.handle(channel, listener) を参照してください。
ipcMain.removeHandler(channel)channel Stringchannel にハンドラがあれば削除します。
callback に渡された event オブジェクトに関するドキュメントは、ipc-main-event 構造体ドキュメントにあります。
handle コールバックに渡される event オブジェクトのドキュメントは、ipc-main-invoke-event 構造体ドキュメントにあります。
EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagereturnValue any - Set this to the value to be returned in a synchronous messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this messageports MessagePortMain[] - A list of MessagePorts that were transferred with this messagereply Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to \"reply\" to the sent message in order to guarantee the reply will go to the correct process and frame.channel String...args any[]EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this message\n\nレンダラープロセスからメインプロセスに非同期通信をします。
\n
プロセス: Renderer
\nipcRenderer モジュールは Event Emitter を継承しています。 レンダラープロセス (ウェブページ) からメインプロセスに同期及び非同期メッセージを送れるように、いくつかのメソッドを提供します。 メインプロセスからの返信を受け取ることもできます。
サンプルコードについては ipcMain を参照して下さい。
\nipcRenderer オブジェクトは、イベントを受け取り、送るために以下のメソッドがあります。
ipcRenderer.on(channel, listener)channel Stringlistener Functionevent IpcRendererEvent...args any[]channel に新しいメッセージが来たときに listener が listener(event, args...) として呼ばれます、
ipcRenderer.once(channel, listener)channel Stringlistener Functionevent IpcRendererEvent...args any[]イベントに対する一回限りの listener 関数を追加します。 この listener は、次にメッセージが channel へ送信されたときに、削除されてから呼び出されます。
ipcRenderer.removeListener(channel, listener)channel Stringlistener Function...args any[]指定した channel の listener 配列から、指定した listener を削除します。
ipcRenderer.removeAllListeners(channel)channel String指定した channel の listener を全て削除します。
ipcRenderer.send(channel, ...args)channel String...args any[]引数と共に、channel を介してメインプロセスに非同期メッセージを送信します。 引数は window.postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。
\n\n注意: DOM オブジェクトや特殊な Electron オブジェクトなど、非標準の JavaScript 型を送信すると例外が発生します。
\nメインプロセスでは
\nImageBitmap、File、DOMMatrixなどの DOM オブジェクトをサポートしていません。そのため、これらのオブジェクトをメインプロセスでデコードする方法がなく、Electron の IPC を介してメインプロセスに送信することはできません。 IPC 経由でこのようなオブジェクトを送信するとエラーになります。
メインプロセスは ipcMain モジュールで channel を聴いてそれを処理します。
MessagePort をメインプロセスに転送する必要がある場合は、ipcRenderer.postMessage を使用してください。
メソッド呼び出しの結果のようにメインプロセスから応答を一つだけ受け取りたい場合は、ipcRenderer.invoke の使用を検討してください。
ipcRenderer.invoke(channel, ...args)channel String...args any[]戻り値 Promise<any> - メインプロセスからの応答で解決します。
channel を介して非同期でメインプロセスにメッセージを送信し、結果を待ちます。 引数は window.postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。
\n\n注意: DOM オブジェクトや特殊な Electron オブジェクトなど、非標準の JavaScript 型を送信すると例外が発生します。
\nメインプロセスでは
\nImageBitmap、File、DOMMatrixなどの DOM オブジェクトをサポートしていません。そのため、これらのオブジェクトをメインプロセスでデコードする方法がなく、Electron の IPC を介してメインプロセスに送信することはできません。 IPC 経由でこのようなオブジェクトを送信するとエラーになります。
メインプロセスは、ipcMain.handle() で channel をリッスンする必要があります。
以下がその例です。
\n// レンダラープロセス\nipcRenderer.invoke('some-name', someArgument).then((result) => {\n // ...\n})\n\n// メインプロセス\nipcMain.handle('some-name', async (event, someArgument) => {\n const result = await doSomeWork(someArgument)\n return result\n})\nMessagePort をメインプロセスに転送する必要がある場合は、ipcRenderer.postMessage を使用してください。
メッセージの応答が必要ない場合は、ipcRenderer.send の使用を検討してください。
ipcRenderer.sendSync(channel, ...args)channel String...args any[]戻り値 any - ipcMain ハンドラから返された値。
channel を介して同期でメインプロセスにメッセージを送信し、結果を待ちます。 引数は window.postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。
\n\n注意: DOM オブジェクトや特殊な Electron オブジェクトなど、非標準の JavaScript 型を送信すると例外が発生します。
\nメインプロセスでは
\nImageBitmap、File、DOMMatrixなどの DOM オブジェクトをサポートしていません。そのため、これらのオブジェクトをメインプロセスでデコードする方法がなく、Electron の IPC を介してメインプロセスに送信することはできません。 IPC 経由でこのようなオブジェクトを送信するとエラーになります。
メインプロセスは ipcMain オブジェクトで channel を聴いてそれを処理します。そして event.returnValue をセットすることで応答します。
\n\n⚠️ 警告: 同期メッセージを送信すると、応答を受信するまでレンダラープロセス全体がブロックされます。そのため、このメソッドは最終手段として使用してください。 非同期バージョンの、
\ninvoke()を使用することを推奨します。
ipcRenderer.postMessage(channel, message, [transfer])メッセージをメインプロセスに送信し、任意でゼロ個以上の MessagePort オブジェクトの所有権を転送します。
転送した MessagePort オブジェクトは、発生したイベントの ports プロパティにアクセスすることで、MessagePortMain オブジェクトとしてメインプロセスで利用可能になります。
以下がその例です。
\n// レンダラープロセス\nconst { port1, port2 } = new MessageChannel()\nipcRenderer.postMessage('port', { message: 'hello' }, [port1])\n\n// メインプロセス\nipcMain.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nMessagePort と MessageChannel の使用方法の詳細については MDN ドキュメント を参照してください。
ipcRenderer.sendTo(webContentsId, channel, ...args)webContentsId Numberchannel String...args any[]channel を介して webContentsId のウインドウにメッセージを送ります。
ipcRenderer.sendToHost(channel, ...args)channel String...args any[]ipcRenderer.send に似ていますが、イベントはメインプロセスの代わりにホストページの <webview> に送信されます。
callback に渡された event オブジェクトに関するドキュメントは、ipc-renderer-event 構造体ドキュメントにあります。
Eventsender IpcRenderer - The IpcRenderer instance that emitted the event originallysenderId Integer - The webContents.id that sent the message, you can call event.sender.sendTo(event.senderId, ...) to reply to the message, see ipcRenderer.sendTo for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set event.senderId to 0.ports MessagePort[] - A list of MessagePorts that were transferred with this message問題に対してコントリビュートする方法が3つあります：
\nelectron/electronの issue トラッカー に新しい issue を作って報告することを推奨します。electron/electronのソースコードに変更を加えるプルリクエストを送ることによって解決されます。\"Finding Support\" にはプログラミングヘルプ、セキュリティ Issue の報告、貢献などのリソースのリストがあります。 Issue トラッカーはバグにのみ使用してください！
\nバグレポートを送信するには:
\nelectron/electron Issue トラッカー 内で新しい Issue を開くとき、ユーザには記入するべきテンプレートが表示されます。
Electron のバグを発見したと思われる方は、できるだけテンプレートの記入にご協力ください。
\nレポートを評価するために必要な、2つの最も重要な情報は、バグの説明とそれを再現するための簡単なテストケースです。 再現できる場合は、バグを修正することがより簡単になります。
\n簡潔、完璧、検証可能な例の作り方 を参照してください。
\n未解決の Issue には議論が伴うのが一般的です。 コントリビュータらは、その振る舞いがバグか機能かなどで意見が異なるでしょう。 この議論はプロセスの一部であり、集中し、有用で、専門的になるべきです。
\n補足の文脈も裏付けとなる詳細も示さない簡潔な回答は、役に立たず専門的ではありません。 多くの人にとって、そのようなレスポンスは面倒で不親切です。
\nコントリビュータは、問題を共同で解決し互いに進歩するのを手助けすることが奨励されます。 無効、または誤った情報が含まれていると思われる Issue に遭遇した場合は、その 理由 をあなたが間違っている可能性も考えて説明してください。 そうすることで、大抵の場合正しい結論に早く到達することができます。
\nほとんどの Issue はプルリクエストを開くことで解決されます。 プルリクエストを開いてレビューするプロセスは、問題をオープンして優先順位付けするプロセスと似ています。しかし、提案された変更が Electron プロジェクトの最低限の品質と機能のガイドラインを満たすことを確実にするために必要な、レビューと承認のワークフローを伴います。
", "title": "Electron の Issue", "description": "" }, "/docs/api/structures/jump-list-category": { "locale": "ja-JP", "slug": "jump-list-category", "href": "/docs/api/structures/jump-list-category", "crowdinFileId": "256451", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/jump-list-category.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "type String (optional) - One of the following:tasks - Items in this category will be placed into the standard Tasks category. There can be only one such category, and it will always be displayed at the bottom of the Jump List.frequent - Displays a list of files frequently opened by the app, the name of the category and its items are set by Windows.recent - Displays a list of files recently opened by the app, the name of the category and its items are set by Windows. Items may be added to this category indirectly using app.addRecentDocument(path).custom - Displays tasks or file links, name must be set by the app.name String (optional) - Must be set if type is custom, otherwise it should be omitted.items JumpListItem - Array of JumpListItem objects if type is tasks or custom, otherwise it should be omitted.Note: If a JumpListCategory object has neither the type nor the name property set then its type is assumed to be tasks. If the name property is set but the type property is omitted then the type is assumed to be custom.
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
type String (optional) - One of the following:task - A task will launch an app with specific arguments.separator - Can be used to separate items in the standard Tasks category.file - A file link will open a file using the app that created the Jump List, for this to work the app must be registered as a handler for the file type (though it doesn't have to be the default handler).path String (optional) - Path of the file to open, should only be set if type is file.program String (optional) - Path of the program to execute, usually you should specify process.execPath which opens the current program. Should only be set if type is task.args String (optional) - The command line arguments when program is executed. Should only be set if type is task.title String (optional) - The text to be displayed for the item in the Jump List. Should only be set if type is task.description String (optional) - Description of the task (displayed in a tooltip). Should only be set if type is task. Maximum length 260 characters.iconPath String (optional) - The absolute path to an icon to be displayed in a Jump List, which can be an arbitrary resource file that contains an icon (e.g. .ico, .exe, .dll). You can usually specify process.execPath to show the program icon.iconIndex Number (optional) - The index of the icon in the resource file. If a resource file contains multiple icons this value can be used to specify the zero-based index of the icon that should be displayed for this task. If a resource file contains only one icon, this property should be set to zero.workingDirectory String (optional) - The working directory. Default is empty.ctrlKey Boolean (optional) - whether the Control key was used in an accelerator to trigger the EventmetaKey Boolean (optional) - whether a meta key was used in an accelerator to trigger the EventshiftKey Boolean (optional) - whether a Shift key was used in an accelerator to trigger the EventaltKey Boolean (optional) - whether an Alt key was used in an accelerator to trigger the EventtriggeredByAccelerator Boolean (optional) - whether an accelerator was used to trigger the event as opposed to another user gesture like mouse clickInputEventtype String - The type of the event, can be keyDown, keyUp or char.keyCode String - The character that will be sent as the keyboard event. Should only use the valid key codes in Accelerator.この機能により、Electron アプリケーションのローカルとグローバルのキーボードショートカットを設定できます。
\nローカルキーボードショートカットは、アプリケーションにフォーカスしているときのみトリガーされます。 ローカルキーボードショートカットを設定するには、Menu モジュール内の MenuItem 作成時に accelerator プロパティを指定する必要があります。
クイックスタートガイド の作業用アプリケーションから始めることにして、 main.js ファイルを以下の行の通りに更新します。
const { Menu, MenuItem } = require('electron')\n\nconst menu = new Menu()\nmenu.append(new MenuItem({\n label: 'Electron',\n submenu: [{\n role: 'help',\n accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Alt+Shift+I',\n click: () => { console.log('Electron rocks!') }\n }]\n}))\n\nMenu.setApplicationMenu(menu)\n\n\n注意: 上記のコードでは、ユーザーのオペレーティングシステムによってアクセラレーターを変えていることがわかります。 macOS では
\nAlt+Cmd+Iで、Linux と Windows ではAlt+Shift+Iです。
Electron アプリケーションを起動すると、アプリケーションメニューが先ほど定義したローカルショートカットとともに表示されます。
\n
ヘルプ をクリックする又は定義したアクセラレータを押してから、Electron アプリケーションを実行したターミナルを開くと、click イベントがトリガーされたことで生成されたメッセージ \"Electron rocks!\" が表示されます。
グローバルキーボードショートカットを設定するには、globalShortcut モジュールを使用して、アプリケーションにキーボードフォーカスがない場合のキーボードイベントを検出する必要があります。
\nクイックスタートガイド の作業用アプリケーションから始めることにして、 main.js ファイルを以下の行の通りに更新します。
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n globalShortcut.register('Alt+CommandOrControl+I', () => {\n console.log('Electron loves global shortcuts!')\n })\n}).then(createWindow)\n\n\n注意: 上記コードの
\nCommandOrControlの組み合わせは、macOS ではCommandを、Windows/Linux ではControlを使用します。
Electron アプリケーションを起動した後、定義されたキーの組み合わせを押して、Electron アプリケーションを起動したターミナルを開くと、Electron はグローバルショートカット大好きだとわかりますね!
\nBrowserWindow 内でキーボードショートカットを扱いたい場合は、addEventListener() API を使用して keyup と keydown の DOM イベント をレンダラープロセス内でリッスンすることでできます。
function handleKeyPress(event) {\n // キー押下のハンドリングはここにコードを書くとできます。\n document.getElementById(\"last-keypress\").innerText = event.key;\n console.log(`You pressed ${event.key}`);\n}\n\nwindow.addEventListener('keyup', handleKeyPress, true);\n\n\n注意: 第 3 引数の
\ntrueは、このリスナーが他のリスナーよりも必ず優先してキー押下を受け取ることを示しています。そのため、このリスナー内でstopPropagation()を呼び出さないでください。
before-input-event イベントは keydown イベントと keyup イベントをディスパッチするより前に発生します。 メニューに表示されないカスタムショートカットをキャッチして処理するため使用することができます。
クイックスタートガイド の作業用アプリケーションから始めることにして、 main.js ファイルを以下の行の通りに更新します。
const { app, BrowserWindow } = require('electron')\n\napp.whenReady().then(() => {\n const win = new BrowserWindow({ width: 800, height: 600 })\n\n win.loadFile('index.html')\n win.webContents.on('before-input-event', (event, input) => {\n if (input.control && input.key.toLowerCase() === 'i') {\n console.log('Pressed Control+I')\n event.preventDefault()\n }\n })\n})\nElectron アプリケーションを起動した後、Electron アプリケーションを実行したターミナルを開き、Ctrl+I キーの組み合わせを押すと、このキーの組み合わせが正常に受け取られたとわかります。
ショートカットの解析を手動で行いたくない場合は、mousetrap のような高度なキー検出を行うライブラリがあります。 レンダラープロセスで mousetrap を実行する使用例を以下に示します。
Mousetrap.bind('4', () => { console.log('4') })\nMousetrap.bind('?', () => { console.log('show shortcuts!') })\nMousetrap.bind('esc', () => { console.log('escape') }, 'keyup')\n\n// 組み合わせ\nMousetrap.bind('command+shift+k', () => { console.log('command shift k') })\n\n// 複数の組み合わせを同じコールバックに割り当て\nMousetrap.bind(['command+k', 'ctrl+k'], () => {\n console.log('command k or control k')\n\n // false を返すと規定の動作を抑制してイベントの伝播を止める\n return false\n})\n\n// Gmail 式シーケンス\nMousetrap.bind('g i', () => { console.log('go to inbox') })\nMousetrap.bind('* a', () => { console.log('select all') })\n\n// コナミコマンド!\nMousetrap.bind('up up down down left right left right b a enter', () => {\n console.log('コナミコマンド')\n})\ntitle: 他アプリ内の URL から自分の Electron アプリを起動する\ndescription: このガイドでは、Electron アプリを特定のプロトコルのデフォルトハンドラとして設定する手順を説明します。\nslug: launch-app-from-url-in-another-app
\nこのガイドでは、Electron アプリを特定の protocol のデフォルトハンドラとして設定する手順を説明します。
\nこのチュートリアルを終える頃には、特定のプロトコルで始まる URL がクリックされた場合、アプリがそれに干渉してハンドリングするように設定できます。 このガイドでは、使用するプロトコルを \"electron-fiddle://\" とします。
最初に、electron から必要なモジュールをインポートします。 これらのモジュールは、アプリケーションのライフサイクルの制御と、ネイティブなブラウザウインドウの作成を助けます。
const { app, BrowserWindow, shell } = require('electron')\nconst path = require('path')\n次に、\"electron-fiddle://\" プロトコルをすべて処理するために、アプリケーションを登録します。
if (process.defaultApp) {\n if (process.argv.length >= 2) {\n app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])\n }\n} else {\n app.setAsDefaultProtocolClient('electron-fiddle')\n}\nここで、ブラウザのウインドウを作成し、アプリケーションの index.html ファイルを読み込む関数を定義します。
const createWindow = () => {\n // ブラウザウインドウを作成します。\n mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n mainWindow.loadFile('index.html')\n}\nこの次のステップで、BrowserWindow を作成し、外部プロトコルがクリックされたイベントの処理方法をアプリケーションに伝えます。
Windows でのこのコードは、MacOS や Linux と異なります。 これは、Windows で同じ Electron インスタンス内のプロトコルリンクのコンテンツを開くには、さらなるコードが必要だからです。 この詳細については、こちら をお読みください。
\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // 誰かが 2 つ目のインスタンスを実行しようとしたので、ウインドウにフォーカスさせなければなりません。\n if (mainWindow) {\n if (mainWindow.isMinimized()) mainWindow.restore()\n mainWindow.focus()\n }\n })\n\n // mainWindow を作成する、アプリの残りを読み込む、等\n app.whenReady().then(() => {\n createWindow()\n })\n\n // プロトコルのハンドリング。 今回は、エラーボックスを表示することにします。\n app.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n })\n}\n// このメソッドは、Electron の初期化が完了し、\n// ブラウザウインドウの作成準備ができると呼び出されます。\n// 一部のAPIはこのイベントが発生した後にのみ利用できます。\napp.whenReady().then(() => {\n createWindow()\n})\n\n// プロトコルのハンドリング。 今回は、エラーボックスを表示することにします。\napp.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n})\n最後に、誰かがアプリケーションを閉じたときの処理コードを追加します。
\n// macOS 以外では、すべてのウインドウを閉じたときに終了します。 // ユーザが Cmd + Q で明示的に終了するまで、アプリケーションと\n// そのメニューバーがアクティブになっているのが一般的です。\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') app.quit()\n})\nmacOS と Linux では、この機能はアプリがパッケージ化されているときのみ動作します。 開発中でコマンドラインから起動した場合は動作しません。 アプリをパッケージ化する際には、アプリの macOS の Info.plist と Linux の .desktop が更新され、その新しいプロトコルハンドラが含まれていることを確認するようにしてください。 Electron のアプリのバンドル及び頒布ツールには、この処理を行ってくれるものもあります。
Electron Forge を使用している場合は、Forge の設定 において macOS サポート用に packagerConfig を、Linux サポート用に適切な Linux makers の設定を調整してください (以下の例は、設定変更を加えるために必要な最低限のことしか示していないことに注意してください)。
{\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"protocols\": [\n {\n \"name\": \"Electron Fiddle\",\n \"schemes\": [\"electron-fiddle\"]\n }\n ]\n },\n \"makers\": [\n {\n \"name\": \"@electron-forge/maker-deb\",\n \"config\": {\n \"mimeType\": [\"x-scheme-handler/electron-fiddle\"]\n }\n }\n ]\n }\n }\n}\nmacOS サポートの場合:
\nElectron Packager の API を使用している場合、プロトコルハンドラ対応の追加は Electron Forge と似た処理方法ですが、protocols が packager 関数に渡される Packager オプションの一部である点が異なります。
const packager = require('electron-packager')\n\npackager({\n // ...他のオプション...\n protocols: [\n {\n name: 'Electron Fiddle',\n schemes: ['electron-fiddle']\n }\n ]\n\n}).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))\n .catch(err => console.error(`ERROR: ${err.message}`))\nElectron Packager の CLI を使用している場合、--protocol と --protocol-name のフラグを使用してください。 以下は例です。
npx electron-packager . --protocol=electron-fiddle --protocol-name=\"Electron Fiddle\"\nElectron アプリを起動した後、ブラウザにカスタムプロトコルを含む URL、例えば\"electron-fiddle://open\" を入力すると、アプリが応答してエラーダイアログボックスを表示することを確認できます。
多くの Linux 環境では、.desktop ファイルを変更することでシステムランチャーにカスタムエントリを追加できます。 Canonical の Unity ドキュメントについては、ランチャーにショートカットを追加する を参照してください。 より一般的な実装については、freedesktop.org 仕様 を参照してください。
\n\n注意: 上のスクリーンショットは Audacious オーディオプレーヤーのランチャーショートカットの例です。
\n
ショートカットを作成するには、ショートカットメニューに追加したいエントリごとに Name と Exec プロパティを指定する必要があります。 Unity は、ユーザーがショートカットのメニューアイテムをクリックした後に Exec フィールドで定義されたコマンドを実行します。 .desktop ファイルの例を以下に示します。
Actions=PlayPause;Next;Previous\n\n[Desktop Action PlayPause]\nName=Play-Pause\nExec=audacious -t\nOnlyShowIn=Unity;\n\n[Desktop Action Next]\nName=Next\nExec=audacious -f\nOnlyShowIn=Unity;\n\n[Desktop Action Previous]\nName=Previous\nExec=audacious -r\nOnlyShowIn=Unity;\nUnity がアプリケーションにやることを指定する好ましい方法は、引数の利用です。 これはアプリケーション内からグローバル変数 process.argv で参照できます。
このガイドでは以下の情報を提供しています。
\nElectron アプリを署名するには、まず以下のツールをインストールする必要があります。
\nまた、Apple Developer アカウントを登録し Apple Developer Program に参加する必要があります。
\nElectron アプリは Mac App Store や外部サイトで頒布できます。 それぞれの方法ごとに、署名やテストの方法が異なります。 このガイドでは Mac App Store での頒布を中心に説明しますが、その他の方法についても言及します。
\n以下の手順で、Apple から証明書を取得する方法、Electron アプリに署名する方法、テストする方法を説明します。
\n最も簡単に署名証明書を取得するには、Xcode を使用して以下のようします。
\n\"Apple Development\" 証明書は、Apple Developer ウェブサイトで登録したマシン上で、開発およびテスト用のアプリに署名するために使用します。 登録方法については、プロビジョニングプロファイルの準備 で説明します。
\n\"Apple Development\" 証明書で署名したアプリは Mac App Store に提出できません。 このためには、代わりに \"Apple Distribution\" 証明書でアプリに署名する必要があります。 ただし注意として、\"Apple Distribution\" 証明書で署名したアプリはそのまま実行できません。実行できるようにするには Apple が再署名する必要がありますが、これは Mac App Store からダウンロードした後でのみ可能になります。
\n証明書の種類が他にもあることにお気づきでしょう。
\n\"Developer ID Application\" 証明書は、アプリを Mac App Store 以外で頒布する前の署名に使用します。
\n\"Developer ID Installer\" および \"Mac Installer Distribution\" の証明書は、アプリ自体ではなく \"Mac Installer Package\" の署名に使用します。 ほとんどの Electron アプリは Mac Installer Package を使用しないので、通常は必要ありません。
\n証明書の種類の完全なリストは こちら で見られます。
\n\"Apple Development\" および \"Apple Distribution\" 証明書で署名されたアプリは App Sandbox 下でしか実行できないため、Electron の MAS ビルドを使用する必要があります。 しかし、\"Developer ID Application\" 証明書にはこの制限がないため、この証明書で署名されたアプリは Electron の通常ビルドと MAS ビルドのどちらでも使用できます。
\nApple は過去数年の間に証明書の名称を変更しており、古いドキュメントを読んでいると古い名称が出てくるかもしれません。一部のユーティリティも未だに古い名称を使用していることがあります。
\nMac App Store へアプリを提出する前にローカルマシンでアプリをテストしたい場合は、アプリバンドルに埋め込まれたプロビジョニングプロファイル付きの \"Apple Development\" 証明書でアプリを署名する必要があります。
\nプロビジョニングプロファイルの作成 は、以下の手順を踏むとできます。
\n/path/to/yourapp.provisionprofile へダウンロードします。Mac App Store に提出したアプリは Apple の App Sandbox 下で実行する必要があり、Electron の MAS ビルドだけが App Sandbox で実行できます。 Electron の標準の darwin ビルドでは、App Sandbox で実行すると起動に失敗します。
\nelectron-osx-sign でアプリを署名すると、必要なエンタイトルメントが自動追加されます。しかしカスタムエンタイトルメントを使用している場合は、App Sandbox の資格が追加されていることを確認する必要があります。
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n </dict>\n</plist>\nelectron-osx-sign を使わない場合のさらなる手順electron-osx-sign を使わずにアプリを署名する場合、アプリバンドルのエンタイトルメントが少なくとも以下のキーを持っていることを確認する必要があります。
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.application-groups</key>\n <array>\n <string>TEAM_ID.your.bundle.id</string>\n </array>\n </dict>\n</plist>\nTEAM_ID は Apple Developer アカウントの Team ID に、your.bundle.id はアプリの App ID に置き換えてください。
また、アプリのバンドル内のバイナリやヘルパーに以下のエンタイトルメントを追加する必要があります。
\n\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.inherit</key>\n <true/>\n </dict>\n</plist>\nそしてアプリバンドルの Info.plist には、ElectronTeamID キーに Apple Developer アカウントの Team ID を値として含める必要があります。
<plist version=\"1.0\">\n<dict>\n ...\n <key>ElectronTeamID</key>\n <string>TEAM_ID</string>\n</dict>\n</plist>\nelectron-osx-sign を使用する場合は、証明書の名前から Team ID を抽出することで ElectronTeamID キーが自動追加されます。 electron-osx-sign が正しい Team ID を見つけられなかった場合は、このキーを手動で追加する必要があるでしょう。
開発マシン上で実行できるようにアプリを署名するには、\"Apple Development\" 証明書で署名し、そのプロビジョニングプロファイルを electron-osx-sign に渡す必要があります。
electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile\nelectron-osx-sign を使わずに署名する場合は、プロビジョニングプロファイルを YourApp.app/Contents/embedded.provisionprofile に配置する必要があります。
署名したアプリはプロビジョニングプロファイルによって登録されたマシン上でのみ実行可能です。これが Mac App Store に提出する前に署名したアプリをテストする唯一の方法です。
\nMac App Store へ提出するアプリを署名するには、\"Apple Distribution\" 証明書で署名する必要があります。 注意として、この証明書で署名されたアプリは、Mac App Store からダウンロードしない限りどのマシンでも実行できません。
\nelectron-osx-sign YourApp.app --identity='Apple Distribution'\nMac App Store への申請の予定がない場合は、\"Developer ID Application\" 証明書で署名できます。 この方法では App Sandbox 上の要件はありません。App Sandbox を使用しない場合は、Electron の通常の darwin ビルドを使用してください。
\nelectron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess\n--no-gatekeeper-assess を指定すると、electron-osx-sign は macOS の GateKeeper の確認を飛ばします。通常この段階ではアプリはまだ公証されていません。
このガイドでは、App Notarization については説明しません。しかし App Notarization を行っておかないと、ユーザーが Mac App Store 以外からのアプリを使用できないように Apple が阻害する可能性があるので、行っておいた方がよいでしょう。
\n\"Apple Distribution\" 証明書でアプリを署名すれば、Mac App Store に提出できます。
\nこのガイドは、Apple がアプリを承認することを保証していません。Mac App Store の登録要件を満たすには、Apple の アプリの提出 のガイドも読んでおくべきでしょう。
\n手続きのために、Application Loader を使用して署名したアプリを iTunes Connect にアップロードする必要があります。アップロードする前に レコードを作成した ことを確認するようにしてください。
\n非公開 API の利用といったエラーが出る場合は、アプリが Electron の MAS ビルドを使用しているかどうかを確認するとよいでしょう。
\nアップロードした後は、アプリを審査に提出 しましょう。
\nアプリのサンドボックスですべての要件を満たすために、MASビルドで次のモジュールを無効にしてください。
\ncrashReporterautoUpdater次の挙動を変更してください。
\nサンドボックス化の利用により、アプリがアクセスできるリソースは厳密に制限されます。詳細は アプリのサンドボックス化 をご参照ください。
\nアプリが使用する Electron API に応じて、アプリの entitlements ファイルに追加のエンタイトルメントが必要です。 さもなくば、App Sandbox がその使用を阻害することがあります。
\nアプリがサーバーに接続できるように、以下のように発信ネットワーク接続を有効にします。
\n<key>com.apple.security.network.client</key>\n<true/>\nアプリがネットワーク待機ソケットを開くことを許可するために、以下のように着信ネットワーク接続を有効にします。
\n<key>com.apple.security.network.server</key>\n<true/>\n詳細は Enabling Network Access ドキュメント を参照してください。
\n<key>com.apple.security.files.user-selected.read-only</key>\n<true/>\n詳細は Enabling User-Selected File Access ドキュメント を参照してください。
\n<key>com.apple.security.files.user-selected.read-write</key>\n<true/>\n詳細は Enabling User-Selected File Access ドキュメント を参照してください。
\nアプリをリリースする国によっては、ソフトウェアで使用されている暗号化アルゴリズムに関する情報を提供する必要があります。 詳細は 暗号輸出コンプライアンスドキュメント を参照してください。
\nElectron は次の暗号アルゴリズムを使用しています:
\nElectron には macOS Dock 内のアプリアイコンを設定する API があります。 カスタム Dock メニューを作成するための macOS 専用 API は存在しますが、Electron は 最近使った書類 や アプリケーションのプログレス などのクロスプラットフォーム機能のエントリポイントにアプリの Dock アイコンを使用します。
\nカスタム Dock は、ユーザーが全てのアプリウインドウを開きたくないであろう作業のショートカット追加によく使われます。
\nターミナルアプリのDockメニュー
\n
カスタム Dock メニューを設定するには、macOS でのみ利用可能な app.dock.setMenu API を使用する必要があります。
クイックスタートガイド の作業用アプリケーションから始めることにして、 main.js ファイルを以下の行の通りに更新します。
const { app, BrowserWindow, Menu } = require('electron')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n })\n\n win.loadFile('index.html')\n}\n\nconst dockMenu = Menu.buildFromTemplate([\n {\n label: 'New Window',\n click () { console.log('New Window') }\n }, {\n label: 'New Window with Settings',\n submenu: [\n { label: 'Basic' },\n { label: 'Pro' }\n ]\n },\n { label: 'New Command...' }\n])\n\napp.whenReady().then(() => {\n if (process.platform === 'darwin') {\n app.dock.setMenu(dockMenu)\n }\n}).then(createWindow)\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n\nElectron アプリケーションの起動後、アプリケーションのアイコンを右クリックしてみましょう。 先ほど定義したカスタムメニューが表示されるはずです。
\n
workingSetSize Integer - The amount of memory currently pinned to actual physical RAM.peakWorkingSetSize Integer - The maximum amount of memory that has ever been pinned to actual physical RAM.privateBytes Integer (optional) Windows - The amount of memory not shared by other processes, such as JS heap or HTML content.Note that all statistics are reported in Kilobytes.
", "title": "MemoryInfo Object", "description": "" }, "/docs/api/structures/memory-usage-details": { "locale": "ja-JP", "slug": "memory-usage-details", "href": "/docs/api/structures/memory-usage-details", "crowdinFileId": "256461", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/memory-usage-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "count Numbersize NumberliveSize Number\n\nネイティブアプリケーションのメニューとコンテキストメニューを作成します。
\n
プロセス: Main
\nnew Menu()新しいメニューを作成します
\nMenu クラスは以下の静的メソッドを持ちます。
Menu.setApplicationMenu(menu)menu Menu | nullmacOS では、 menu をアプリケーションメニューとして設定します。 Windows と Linux では、 menu は各ウィンドウのトップメニューとして設定されます。
更に Windows と Linux では、最上位のアイテム名に & を使用して、アクセラレータを生成させるときに取得する文字を指定できます。 たとえば、ファイルメニューに &File を使用すると、その関連付けされたメニューを開く Alt-F アクセラレータが生成されます。 ボタンラベルでその指定をした文字には下線が引かれ、& 文字はボタンラベルに表示されません。
メニューアイテム名の & 文字をエスケープするには、& を続けて書きます。 例えば、&&File とするとボタンラベルに &File が表示されます。
null を渡すと、既定のメニューが表示されなくなります。 Windows と Linux では、さらにウィンドウからメニューバーを削除します。
注: アプリが何も設定しない場合は自動でデフォルトメニューが作成されます。 これは ファイル、編集、表示、ウィンドウ、ヘルプ のような標準のアイテムを含みます。
Menu.getApplicationMenu()戻り値 Menu | null - セットされていれば menu を、そうでなければ null を返します。
注: 返される Menu のインスタンスは、メニューアイテムの動的な追加または削除をサポートしていません。 インスタンス プロパティ は動的に変更ができます。
Menu.sendActionToFirstResponder(action) macOSaction Stringaction をアプリケーションの最初のレスポンダーに送信します。 macOS メニューの既定の動作をエミュレートするために使用されます。 通常は MenuItem の role プロパティを使用します。
macOSネイティブなアクションに関してはmacOS Cocoa Event Handling Guideを参照してください。
\nMenu.buildFromTemplate(template)template (MenuItemConstructorOptions | MenuItem)[]戻り値 Menu
一般的に、template は MenuItem を構築するための options の配列です。 使用方法は上記を参照できます。
template の要素に他のフィールドを付けることもでき、それらは構築されたメニューアイテムのプロパティになります。
menu オブジェクトには以下のメソッドがあります。
menu.popup([options])options Object (任意)window BrowserWindow (任意) - 省略値はフォーカスされたウインドウです。x Number (任意) - 既定ではマウスカーソルの現在位置です。 y が宣言されている場合は宣言する必要があります。y Number (任意) - 既定ではマウスカーソルの現在位置です。 x が宣言されている場合は宣言する必要があります。positioningItem Number (任意) macOS - マウスカーソルの位置に配置するメニューアイテムのインデックス。 既定値は -1 です。callback Function (任意) - メニューが閉じたしたときに呼ばれます。この menu を BrowserWindow 内のコンテキストメニューとしてポップアップします。
menu.closePopup([browserWindow])browserWindow BrowserWindow (任意) - 省略値はフォーカスされたウインドウです。browserWindow 内のこのコンテキストメニューを閉じます。
menu.append(menuItem)menuItem MenuItemmenu に menuItem を追加します。
menu.getMenuItemById(id)id String戻り値 MenuItem | null - 指定した id のアイテム。
menu.insert(pos, menuItem)pos IntegermenuItem MenuItemmenu の pos の位置に menuItem を挿入します。
new Menu で作成されたオブジェクトまたは Menu.buildFromTemplate によって返されたオブジェクトは、以下のイベントが発生します。
注: いくつかのイベントは特定のオペレーティングシステムでのみ利用可能で、そのように注記がつけられています。
\n戻り値：
\nevent Eventmenu.popup() が呼ばれたときに発生します。
戻り値：
\nevent Event手動か menu.closePopup() でポップアップが閉じられたときに発生します。
menu オブジェクトには更に以下のプロパティがあります。
menu.itemsmenu のアイテムが入った配列 MenuItem[]。
それぞれの Menu は複数の MenuItem で構成され、それぞれの MenuItem はサブメニューを持つことができます。
以下は簡易テンプレート API でアプリケーションメニューを作成した例です。
\nconst { app, Menu } = require('electron')\n\nconst isMac = process.platform === 'darwin'\n\nconst template = [\n // { role: 'appMenu' }\n ...(isMac ? [{\n label: app.name,\n submenu: [\n { role: 'about' },\n { type: 'separator' },\n { role: 'services' },\n { type: 'separator' },\n { role: 'hide' },\n { role: 'hideOthers' },\n { role: 'unhide' },\n { type: 'separator' },\n { role: 'quit' }\n ]\n }] : []),\n // { role: 'fileMenu' }\n {\n label: 'ファイル',\n submenu: [\n isMac ? { role: 'close' } : { role: 'quit' }\n ]\n },\n // { role: 'editMenu' }\n {\n label: 'Edit',\n submenu: [\n { role: 'undo' },\n { role: 'redo' },\n { type: 'separator' },\n { role: 'cut' },\n { role: 'copy' },\n { role: 'paste' },\n ...(isMac ? [\n { role: 'pasteAndMatchStyle' },\n { role: 'delete' },\n { role: 'selectAll' },\n { type: 'separator' },\n {\n label: 'Speech',\n submenu: [\n { role: 'startSpeaking' },\n { role: 'stopSpeaking' }\n ]\n }\n ] : [\n { role: 'delete' },\n { type: 'separator' },\n { role: 'selectAll' }\n ])\n ]\n },\n // { role: 'viewMenu' }\n {\n label: 'View',\n submenu: [\n { role: 'reload' },\n { role: 'forceReload' },\n { role: 'toggleDevTools' },\n { type: 'separator' },\n { role: 'resetZoom' },\n { role: 'zoomIn' },\n { role: 'zoomOut' },\n { type: 'separator' },\n { role: 'togglefullscreen' }\n ]\n },\n // { role: 'windowMenu' }\n {\n label: 'Window',\n submenu: [\n { role: 'minimize' },\n { role: 'zoom' },\n ...(isMac ? [\n { type: 'separator' },\n { role: 'front' },\n { type: 'separator' },\n { role: 'window' }\n ] : [\n { role: 'close' }\n ])\n ]\n },\n {\n role: 'help',\n submenu: [\n {\n label: 'Learn More',\n click: async () => {\n const { shell } = require('electron')\n await shell.openExternal('https://electronjs.org')\n }\n }\n ]\n }\n]\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nレンダラープロセスが起点となってメニューを作成するには、IPC を使用して必要な情報をメインプロセスに送信し、メインプロセスがレンダラーに代わってメニューを表示するようにします。
\n以下は、ユーザーがページを右クリックしたときにメニューを表示する例です。
\n// レンダラー\nwindow.addEventListener('contextmenu', (e) => {\n e.preventDefault()\n ipcRenderer.send('show-context-menu')\n})\n\nipcRenderer.on('context-menu-command', (e, command) => {\n // ...\n})\n\n// メイン\nipcMain.on('show-context-menu', (event) => {\n const template = [\n {\n label: 'Menu Item 1',\n click: () => { event.sender.send('context-menu-command', 'menu-item-1') }\n },\n { type: 'separator' },\n { label: 'Menu Item 2', type: 'checkbox', checked: true }\n ]\n const menu = Menu.buildFromTemplate(template)\n menu.popup(BrowserWindow.fromWebContents(event.sender))\n})\nmacOS は、Windows 及び Linux とは全く異なるスタイルのアプリケーションメニューを持ちます。 ここでは、アプリのメニューをよりネイティブのようにする方法について、いくつかの注意点を示します。
\nmacOS ではシステムが定義する標準メニューがいくつかある。例えば、サービス やウインドウ メニューが該当する。 メニューを標準メニューにするには、メニューの role を次のいずれかに設定する必要があります。Electron はそれらを認識して標準メニューにします。
windowhelpservicesmacOS はいくつかのメニューアイテムに、About xxx や Hide xxx、Hide Others といった標準アクションを提供しています。 メニューアイテムのアクションを標準アクションに設定するには、メニューアイテムの role 属性を設定する必要があります。
macOS のアプリケーションメニューの最初のアイテムのラベルは、設定した名前に関係なく、アプリ名になります。 これを変えるには、アプリのバンドルの Info.plist ファイルを変更します。 より詳しくは、Information Property List ファイルについて をご参照ください。
ブラウザウインドウの setMenu メソッド は、特定のブラウザウインドウのメニューを設定できます。
Menu.buildFromTemplate でメニューを構築するとき、アイテムをどのように配置するかを制御するのに、before, after, beforeGroupContaining, afterGroupContaining, id が使用できます。
before - 指定したラベルの前にこのアイテムを挿入します。 参照された項目が存在しない場合、アイテムはメニューの最後に挿入されます。 また、与えられたメニューアイテムをそのアイテムと同じ「グループ」に配置する必要があることを意味します。after - 指定したラベルの後にこのアイテムを挿入します。 参照された項目が存在しない場合、アイテムはメニューの最後に挿入されます。 また、与えられたメニューアイテムをそのアイテムと同じ「グループ」に配置する必要があることを意味します。beforeGroupContaining - 単一のコンテキストメニューで、指定されたラベルのアイテムを含むグループの前に、そのグループの配置を宣言する手段を提供します。afterGroupContaining - 単一のコンテキストメニューで、指定されたラベルのアイテムを含むグループの後に、そのグループの配置を宣言する手段を提供します。デフォルトでは、指定された位置指定キーワードのうち1つも使用されていない限り、アイテムはテンプレートに存在する順序で挿入されます。
\nテンプレート:
\n[\n { id: '1', label: 'one' },\n { id: '2', label: 'two' },\n { id: '3', label: 'three' },\n { id: '4', label: 'four' }\n]\nメニュー:
\n- 1\n- 2\n- 3\n- 4\nテンプレート:
\n[\n { id: '1', label: 'one' },\n { type: 'separator' },\n { id: '3', label: 'three', beforeGroupContaining: ['1'] },\n { id: '4', label: 'four', afterGroupContaining: ['2'] },\n { type: 'separator' },\n { id: '2', label: 'two' }\n]\nメニュー:
\n- 3\n- 4\n- ---\n- 1\n- ---\n- 2\nテンプレート:
\n[\n { id: '1', label: 'one', after: ['3'] },\n { id: '2', label: 'two', before: ['1'] },\n { id: '3', label: 'three' }\n]\nメニュー:
\n- ---\n- 3\n- 2\n- 1\n\n\nネイティブアプリケーションメニューとコンテキストメニューに項目を追加します。
\n
プロセス: Main
\nサンプルについては Menu を参照して下さい。
new MenuItem(options)options Objectclick Function (任意) - メニューアイテムがクリックされたとき、 click(menuItem, browserWindow, event) で呼び出されます。menuItem MenuItembrowserWindow BrowserWindow | undefined - ウインドウが開かれていないときは undefined になります。event KeyboardEventrole String (任意) - undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow, windowMenu のいずれかにできます。メニューアイテムのアクションを定義します。指定すると click プロパティは無視されます。 役割 (roles) を参照してください。type String (任意) - normal、separator、submenu、checkbox、radio にできる。label String (任意)sublabel String (任意)toolTip String (任意) macOS - このメニューアイテムに浮かび上がるテキスト。accelerator Accelerator (任意)icon (NativeImage | String) (任意)enabled Boolean (任意) - もし false なら、メニューアイテムはグレーっぽくなってクリックできない。acceleratorWorksWhenHidden Boolean (任意) macOS - 省略値は true です。false のときは、アイテムが表示されていない場合にアクセラレータがアイテムをトリガーするのを防ぎます。visible Boolean (任意) - もし false なら、メニューアイテムは全く見えなくなる。checked Boolean (任意) - checkbox または radio の type のメニューアイテムに対してのみ指定する必要がある。registerAccelerator Boolean (任意) Linux Windows - false の場合、アクセラレータはシステムに登録されませんが、それでも表示はされます。 省略値は true です。sharingItem SharingItem (任意) macOS - role が shareMenu の場合に共有するアイテムです。submenu (MenuItemConstructorOptions[] | Menu) (任意) - submenu 型メニューアイテムを指定する必要があります。 もし submenu を指定した場合、type: 'submenu' は省略できます。 値が Menu でない場合は、Menu.buildFromTemplate を用いて自動的に変換されます。id String (任意) - 単一のメニューの中でユニーク。 宣言されている場合は、位置属性によってこのアイテムへの参照として使用できます。before String - 指定したラベルの前にこのアイテムを挿入します。 参照された項目が存在しない場合、アイテムはメニューの最後に挿入されます。 また、与えられたメニューアイテムをそのアイテムと同じ「グループ」に配置する必要があることを意味します。after String - 指定したラベルの後にこのアイテムを挿入します。 参照された項目が存在しない場合、アイテムはメニューの最後に挿入されます。beforeGroupContaining String - 単一のコンテキストメニューで、指定されたラベルのアイテムを含むグループの前に、そのグループの配置を宣言する手段を提供します。afterGroupContaining String - 単一のコンテキストメニューで、指定されたラベルのアイテムを含むグループの後に、そのグループの配置を宣言する手段を提供します。注釈: Windows と Linux でアイテムが非表示になっている場合のアクセラレータは常に機能するため、acceleratorWorksWhenHidden は macOS 専用として指定されています。 これはネイティブの macOS 開発では可能なので、オプションを無効にするオプションをユーザーに提供するためにユーザーに公開されます。 このプロパティは macOS High Sierra 10.13 以降でのみ利用可能です。
Roles を使用すると、メニューアイテムに定義済みの動作を持たせることができます。
\nclick 関数で手動で動作を実装しようとするのではなく、標準の role に一致するメニューアイテムに対して role を指定することが最善です。 組み込み role の動作は最適なネイティブの操作感を得られます。
roleを使用する場合、label と accelerator の値は任意で、各プラットフォームに最適な値がデフォルトになっています。
すべてのメニューアイテムは、role、label、セパレータの場合は type のいずれかを保持する必要があります。
role プロパティは、以下の値を持つことができます。
undoabout - ネイティブのこの App についてのパネル (専用のパネルを提供しない、Window 上のカスタムメッセージボックス) をトリガーします。redocutcopypastepasteAndMatchStyleselectAlldeleteminimize - 現在のウィンドウを最小化する。close - 現在のウィンドウを閉じる。quit - アプリケーションを終了する。reload - 現在のウィンドウをリロードする。forceReload - キャッシュを無視して現在のウィンドウをリロードする。toggleDevTools - 現在のウィンドウの開発者向けツールのトグル切り替えをする。togglefullscreen - 現在のウインドウの全画面モードのトグル切り替え.resetZoom - フォーカス中のページのズームレベルを元のサイズにリセットする。zoomIn - フォーカス中のページを 10% 拡大する。zoomOut - フォーカス中のページを 10% 縮小する。toggleSpellChecker - 組み込みスペルチェッカーを有効/無効にします。fileMenu - デフォルト\"ファイル\" メニュー全体 (Close / Quit)editMenu - デフォルトの\"編集\"メニュー全体 (元に戻す、コピー、等)。viewMenu - デフォルトの\"表示\"メニュー全体 (リロード、開発ツールON/OFF等)windowMenu - デフォルトの\"ウインドウ\"メニュー全体 (最小化、ズーム等)。以下は macOS で有効な追加の role です。
\nappMenu - デフォルトの\"App\"メニュー全体 (Electronについて、サービス等)hide - hide アクションに割り当てる。hideOthers - hideOtherApplications アクションに割り当てる。unhide - unhideAllApplications アクションに割り当てる。startSpeaking - startSpeaking アクションに割り当てる。stopSpeaking - stopSpeaking アクションに割り当てる。front - arrangeInFront アクションに割り当てる。zoom - performZoom アクションに割り当てる。toggleTabBar - toggleTabBar アクションに割り当てる。selectNextTab - selectNextTab アクションに割り当てる。selectPreviousTab - selectPreviousTab アクションに割り当てる。mergeAllWindows - mergeAllWindows アクションに割り当てる。moveTabToNewWindow - moveTabToNewWindow アクションに割り当てる。window - \"ウインドウ\"サブメニュー。help - \"ヘルプ\"サブメニュー。services - \"サービス\" メニューのサブメニュー。 これはこのアプリケーションのメニューにのみ使うことを意図しており、macOSアプリのコンテキストメニューで使用される \"サービス\"サブメニューと同じではありません。この\"サービス\"サブメニューはElectronでは実装しません。recentDocuments - \"最近使った項目を開く\"サブメニュー。clearRecentDocuments - clearRecentDocuments アクションに割り当てる。shareMenu - このサブメニューは 共有メニュー です。 sharingItem プロパティは、共有アイテムを示すためにも設定する必要があります。macOS の role を指定するとき、label と accelerator がメニューアイテムに影響を与える唯一のオプションです。 ほかのすべてのオプションは無視されます。 小文字の role、toggledevtools などもまだサポートしています。
注意: macOS 上の tray 内の最も上にあるメニューアイテムでは、enabled と visibility プロパティは利用できません。
MenuItem のインスタンスには以下のプロパティがあります。
menuItem.idアイテムの一意な id を示す String。このプロパティは動的に変更できます。
menuItem.labelそのアイテムに表示されるラベルを示す String。
menuItem.clickMenuItem がクリックイベントを受け取った時に発火される Function。 これは menuItem.click(event, focusedWindow, focusedWebContents) で呼び出されます。
event KeyboardEventfocusedWindow BrowserWindowfocusedWebContents WebContentsmenuItem.submenu存在する場合、メニューアイテムのサブメニューを格納する Menu (任意)。
menuItem.typeそのアイテムの種類を示す String。 normal 、 separator 、 submenu 、 checkbox 、 radio のいずれか。
menuItem.roleセットされている場合、アイテムの役割を示す String (任意)。 undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow, windowMenu のいずれかにできます。
menuItem.acceleratorAccelerator (任意) 型で、セットされているならばそのアイテムのアクセラレータになります。
menuItem.userAccelerator Readonly macOSAccelerator | null 型で、メニューアイテムの ユーザーが割り当てたアクセラレータ を表します。
注意: このプロパティは MenuItem が Menu に追加された後にのみ初期化されます。 Menu.buildFromTemplate または Menu.append()/insert() を介してください。 初期化前にアクセスすると null を返します。
menuItem.iconセットされている場合、アイテムのアイコンを示す NativeImage | String (任意)。
menuItem.sublabelそのアイテムのサブラベルを示す String。
menuItem.toolTip macOSそのアイテムに浮かび上がるテキストを示す String。
menuItem.enabledアイテムが有効かどうかを示す Boolean。このプロパティは動的に変更できます。
menuItem.visibleアイテムが見えるかどうかを示す Boolean。このプロパティは動的に変更できます。
menuItem.checkedアイテムがチェックされたかどうかを示す Boolean。このプロパティは動的に変更できます。
checkbox メニューアイテムは、選択された時に checked プロパティをオンかオフにトグル切り替えします。
radio メニューアイテムは、クリックされると checked がオンになり、同じメニュー内の隣接するアイテムすべてのこのプロパティをオフにします。
更なる動作は、click 関数の追加で可能です。
menuItem.registerAcceleratorアクセラレータをシステムに登録する必要があるのか、ただ表示するだけなのかを示す Boolean。
このプロパティは動的に変更できます。
\nmenuItem.sharingItem macOSSharingItem 型で、role が shareMenu の場合に共有するアイテムを示します。
このプロパティは動的に変更できます。
\nmenuItem.commandIdアイテムの連続する一意な id を示す Number。
menuItem.menuそのアイテムが属する Menu。
MessageChannelMain はメインプロセス側における DOM の MessageChannel オブジェクトです。 .
チャンネルメッセージングの使用方法の詳細については、チャンネルメッセージング API のドキュメントを参照してください。
\n\n\nメインプロセス内でチャンネルメッセージングをするためのチャンネルインターフェイスです。
\n
プロセス: Main
\nサンプル:
\n// メインプロセス\nconst { MessageChannelMain } = require('electron')\nconst { port1, port2 } = new MessageChannelMain()\nw.webContents.postMessage('port', null, [port2])\nport1.postMessage({ some: 'message' })\n\n// レンダラープロセス\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('port', (e) => {\n // e.ports はこのメッセージに付加されるポートのリストです\n e.ports[0].on('message', (messageEvent) => {\n console.log(messageEvent.data)\n })\n})\nchannel.port1MessagePortMain 型のプロパティ。
channel.port2MessagePortMain 型のプロパティ。
MessagePortMain は、メインプロセス側における DOM の MessagePort オブジェクトです。 DOM の EventTarget イベントシステムの代わりに Node.js の EventEmitter システムを使用していることを除けば、DOM のものと同様の動作をします。 これは、イベントをリッスンする際には port.onmessage = ... や port.addEventListener('message', ...) の代わりに port.on('message', ...) を使うべきであるということです。
チャンネルメッセージングの使用方法の詳細については、チャンネルメッセージング API のドキュメントを参照してください。
\nMessagePortMain は [EventEmitter][event-emitter] を継承しています。
\n\nメインプロセス内でチャンネルメッセージングをするためのポートインターフェイスです。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
port.postMessage(message, [transfer])ポートからメッセージを送信し、任意でオブジェクトの所有権を他のブラウジングコンテキストに転送します。
\nport.start()ポートのキューに入れられたメッセージを送信し始めます。 このメソッドが呼び出されるまで、メッセージはキューに溜められます。
\nport.close()ポートを切断し、これを無効にします。
\n戻り値：
\nmessageEvent Objectdata anyports MessagePortMain[]MessagePortMain オブジェクトがメッセージを受信したときに発生します。
\nMessagePortMain オブジェクトの外部のもう一方が切断されたときに発生します。
", "title": "MessagePortMain", "description": "メインプロセス内でチャンネルメッセージングをするためのポートインターフェイスです。" }, "/docs/tutorial/message-ports": { "locale": "ja-JP", "slug": "message-ports", "href": "/docs/tutorial/message-ports", "crowdinFileId": "256219", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/message-ports.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "MessagePort は、異なるコンテキスト間でメッセージを受け渡すことができるウェブ機能です。 window.postMessage に似ていますが、こちらはチャンネルが別々になります。 このドキュメントの目的は、Electron で拡張した Channel Messaging モデルの説明と、アプリ内での MessagePort の使用方法の例示です。
MessagePort がどのようなものでどのように動作するのかを、以下で簡単に説明します。
\n// renderer.js ///////////////////////////////////////////////////////////////\n// MessagePort のペアを作成します。 接続されたメッセージポートのペアを\n// チャンネルといいます。\nconst channel = new MessageChannel()\n\n// port1 と port2 の違いは、その使い方だけです。 port1 に\n// 送信されたメッセージは port2 で受信され、逆も同様です。\nconst port1 = channel.port1\nconst port2 = channel.port2\n\n// 受信側がリスナーを登録する前にそのチャンネルへメッセージを送信しても\n// 大丈夫です。 リスナーが登録されるまでメッセージはキューに溜められます。\nport2.postMessage({ answer: 42 })\n\n// ここでチャネルの他方である port1 をメインプロセスに送信します。 MessagePort を\n// 他のフレームや Web Worker などに送信することも可能です。\nipcRenderer.postMessage('port', null, [port1])\n// main.js ///////////////////////////////////////////////////////////////////\n// メインプロセスでは、ポートを受け取ります。\nipcMain.on('port', (event) => {\n // メインプロセスで MessagePort を受信すると、それは\n // MessagePortMain に変化します。\n const port = event.ports[0]\n\n // MessagePortMain はウェブ方式のイベント API ではなく\n // Node.js 方式のイベント API を使用しています。 そのため .onmessage = ... ではなく .on('message', ...) とします。\n port.on('message', (event) => {\n // data は { answer: 42 }\n const data = event.data\n })\n\n // MessagePortMain は .start() メソッドが呼ばれるまでメッセージをキューに溜めます。\n port.start()\n})\nChannel Messaging API のドキュメントは、MessagePort の動作原理をより詳しく知るのによいでしょう。
\nレンダラーでの MessagePort クラスは、ウェブ上とまったく同じように動作します。 メインプロセスはウェブページではありませんが、Blink と統合していないので MessagePort や MessageChannel のクラスがありません。 メインプロセスで MessagePort をハンドルしてやり取りするために、Electron は 2 つの新しいクラス MessagePortMain と MessageChannelMain を追加しています。 これらはレンダラーの類似クラスと同様に動作します。
MessagePort オブジェクトは、レンダラープロセスかメインプロセスのいずれかで作成し、ipcRenderer.postMessage や WebContents.postMessage メソッドを使用して反対側へ送ります。 注意として、send や invoke のような通常の IPC メソッドは MessagePort の転送に使用できず、postMessage メソッドだけが MessagePort を転送できます。
メインプロセス経由で MessagePort を渡すと、他の方法では (同一オリジン制限などのため) 通信できないかもしれない 2 つのページを接続できます。
close イベントElectron は MessagePort をより便利にするため、ウェブにない機能を追加しました。 それは、チャンネルの反対側が閉じられたときに発火する close イベントです。 ポートはガベージコレクションによって暗黙的に閉じることもあります。
レンダラーでは、port.onclose に代入するか port.addEventListener('close', ...) を呼ぶことで closeイベントをリッスンできます。 メインプロセスでは、port.on('close', ...) を呼ぶことで close イベントをリッスンできます。
この例では、アプリに隠しウインドウとして実装されたワーカープロセスがあります。 メインプロセスを介して中継する際のパフォーマンスオーバーヘッドをなくして、アプリのページとワーカープロセスが直接通信できるようにしたいとします。
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, ipcMain, MessageChannelMain } = require('electron')\n\napp.whenReady().then(async () => {\n // ワーカープロセスは隠し BrowserWindow であるため、Blink のすべての\n // コンテキスト (<canvas>, audio, fetch() などを含む) にアクセスできます。\n const worker = new BrowserWindow({\n show: false,\n webPreferences: { nodeIntegration: true }\n })\n await worker.loadFile('worker.html')\n\n // メインウインドウはワーカープロセスへ仕事を送り、\n // MessagePort を介して結果を受信します。\n const mainWindow = new BrowserWindow({\n webPreferences: { nodeIntegration: true }\n })\n mainWindow.loadFile('app.html')\n\n // 返信で MessagePort を転送する必要があるので、\n // ここで ipcMain.handle() は使えません。\n ipcMain.on('request-worker-channel', (event) => {\n // セキュリティ上の理由から、期待するフレームだけが\n // ワーカーにアクセスできるようにしておきましょう。\n if (event.senderFrame === mainWindow.webContents.mainFrame) {\n // 新しいチャンネルを作成し...\n const { port1, port2 } = new MessageChannelMain()\n // ...その一方をワーカーへ送り...\n worker.webContents.postMessage('new-client', null, [port1])\n // ...そしてもう一方をメインウインドウへ送ります。\n event.senderFrame.postMessage('provide-worker-channel', null, [port2])\n // これでメインウインドウとワーカーがメインプロセスを介さずに\n // 通信できるようになりました!\n }\n })\n})\n<!-- worker.html ------------------------------------------------------------>\n<script>\nconst { ipcRenderer } = require('electron')\n\nfunction doWork(input) {\n // CPU の力が必要な処理。\n return input * 2\n}\n\n// 複数のウィンドウがある、メインウインドウがリロードされた、\n// などの場合に複数クライアントを取得することがあります。\nipcRenderer.on('new-client', (event) => {\n const [ port ] = event.ports\n port.onmessage = (event) => {\n // イベントデータは任意のシリアライズ可能なオブジェクトにできます\n // (イベントに他の MessagePort を載せることもできます!)\n const result = doWork(event.data)\n port.postMessage(result)\n }\n})\n</script>\n<!-- app.html --------------------------------------------------------------->\n<script>\nconst { ipcRenderer } = require('electron')\n\n// ワーカーとの通信に使用できるチャンネルを送るように\n// メインプロセスへ要求します。\nipcRenderer.send('request-worker-channel')\n\nipcRenderer.once('provide-worker-channel', (event) => {\n // 返信を受け取ったら、ポートを取り出し...\n const [ port ] = event.ports\n // ...結果を受信するハンドラを登録したら...\n port.onmessage = (event) => {\n console.log('received result:', event.data)\n }\n // ...メッセージを送信して動かしましょう!\n port.postMessage(21)\n})\n</script>\nElectron の組み込み IPC メソッドは、一方向通信 (send など) と送信に対する返信 (invoke など) の 2 つのモードしかサポートしていません。 MessageChannel を使用すれば、一つのリクエストに対してデータのストリームで応答する \"応答ストリーム\" を実装できます。
// renderer.js ///////////////////////////////////////////////////////////////\n\nfunction makeStreamingRequest (element, callback) {\n // MessageChannel は軽量なので、リクエストごとに新規作成してもコストが\n // かかりません。\n const { port1, port2 } = new MessageChannel()\n\n // 一方のポートをメインプロセスへ送り...\n ipcRenderer.postMessage(\n 'give-me-a-stream',\n { element, count: 10 },\n [port2]\n )\n\n // ...もう一方は持っておきます。 メインプロセスはその一方のポートに\n // メッセージを送り、終了すればこれを閉じます。\n port1.onmessage = (event) => {\n callback(event.data)\n }\n port1.onclose = () => {\n console.log('stream ended')\n }\n}\n\nmakeStreamingRequest(42, (data) => {\n console.log('got response data:', event.data)\n})\n// \"got response data: 42\" が 10 回見えるでしょう。\n// main.js ///////////////////////////////////////////////////////////////////\n\nipcMain.on('give-me-a-stream', (event, msg) => {\n // レンダラーから応答を送信するための MessagePort が\n // 送られてきます。\n const [replyPort] = event.ports\n\n // ここではメッセージを同期的に送信していますが、ポートを保存しておけば\n // 非同期的なメッセージ送信も同じくらい簡単にできます。\n for (let i = 0; i < msg.count; i++) {\n replyPort.postMessage(msg.element)\n }\n\n // 終わったらポートを閉じて、もうメッセージを送信しないことを\n // 相手に示します。 これは厳密には必要ではありません。\n // 明示的にポートを閉じなければ最終的にガベージコレクションされ、\n // レンダラーの 'close' イベントも発生するでしょう。\n replyPort.close()\n})\nコンテキスト分離 が有効になっている場合、メインプロセスからレンダラーへの IPC メッセージは、メインワールドではなく分離されたワールドへ送られます。 分離したワールドを介さずに、メインワールドへ直接メッセージを送りたいこともあるでしょう。
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, MessageChannelMain } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(async () => {\n // contextIsolation が有効な BrowserWindow を作成します。\n const bw = new BrowserWindow({\n webPreferences: {\n contextIsolation: true,\n preload: path.join(__dirname, 'preload.js')\n }\n })\n bw.loadURL('index.html')\n\n // この一方のチャンネルを、コンテキスト分離ページの\n // メインワールドへ送ります。\n const { port1, port2 } = new MessageChannelMain()\n\n // 相手側がリスナーを登録する前にそのチャンネルで\n // メッセージを送信しても大丈夫です。 リスナーが登録されるまでメッセージはキューに\n // 溜められます。\n port2.postMessage({ test: 21 })\n\n // レンダラーのメインワールドからのメッセージを受信することもできます。\n port2.on('message', (event) => {\n console.log('from renderer main world:', event.data)\n })\n port2.start()\n\n // プリロードスクリプトはこの IPC メッセージを受信し、ポートを\n // メインワールドへ転送します。\n bw.webContents.postMessage('main-world-port', null, [port1])\n})\n// preload.js ////////////////////////////////////////////////////////////////\nconst { ipcRenderer } = require('electron')\n\n// メインワールドがメッセージを受信できるようになるまで待ってから\n// ポートを送信する必要があります。 この Promise をプリロードで作成することで、load イベント\n// が発生する前に onload リスナーを登録できることが保証されます。\nconst windowLoaded = new Promise(resolve => {\n window.onload = resolve\n})\n\nipcRenderer.on('main-world-port', async (event) => {\n await windowLoaded\n // 分離ワールドからメインワールドへポートを転送するために、通常の\n // window.postMessage を使用します。\n window.postMessage('main-world-port', '*', event.ports)\n})\n<!-- index.html ------------------------------------------------------------->\n<script>\nwindow.onmessage = (event) => {\n // event.source === window は、メッセージが <iframe> や他のソースから\n // ではなくプリロードスクリプト由来だということです。\n if (event.source === window && event.data === 'main-world-port') {\n const [ port ] = event.ports\n // ポートを確保すれば、メインプロセスと直接通信できるように\n // なります。\n port.onmessage = (event) => {\n console.log('from main process:', event.data)\n port.postMessage(event.data * 2)\n }\n }\n}\n</script>\nmimeType String (optional) - MIME type of the buffer.charset String (optional) - Charset of the buffer.data Buffer - The actual Buffer content.InputEventtype String - The type of the event, can be mouseDown, mouseUp, mouseEnter, mouseLeave, contextMenu, mouseWheel or mouseMove.x Integery Integerbutton String (optional) - The button pressed, can be left, middle, right.globalX Integer (optional)globalY Integer (optional)movementX Integer (optional)movementY Integer (optional)clickCount Integer (optional)MouseInputEventtype String - The type of the event, can be mouseWheel.deltaX Integer (optional)deltaY Integer (optional)wheelTicksX Integer (optional)wheelTicksY Integer (optional)accelerationRatioX Integer (optional)accelerationRatioY Integer (optional)hasPreciseScrollingDeltas Boolean (optional)canScroll Boolean (optional)Web Workers により、JavaScript を OS レベルのスレッドで実行することが可能になります。
\nElectron の Web Workers 内で Node.js の機能を使用するには、webPreferences の nodeIntegrationInWorker オプションを true に設定する必要があります。
const win = new BrowserWindow({\n webPreferences: {\n nodeIntegrationInWorker: true\n }\n})\nnodeIntegrationInWorker は nodeIntegration とは独立して使用できますが、サンドボックス は true に設定してはなりません。
Node.js の組み込みモジュールはすべて Web Workers でサポートされており、asar アーカイブは Node.js API で読み取ることができます。 しかし、Electron の組み込みモジュールは、マルチスレッド環境では使用できません。
任意のネイティブ Node.js モジュールを Web Workers に直接ロードできますが、そのようにしないことを強く推奨します。 既存のネイティブモジュールのほとんどはシングルスレッド環境を想定して作成されており、Web Workers でそれらを使用するとクラッシュやメモリ破壊につながります。
\nネイティブ Node.js モジュールがスレッドセーフであっても、process.dlopen 関数はスレッドセーフではないため、Web Worker でロードするのは安全ではありません。
ネイティブモジュールを安全にロードする唯一の方法は、Web Workers の起動後にアプリがネイティブモジュールをロードしないようにすることです。
\nprocess.dlopen = () => {\n throw new Error('Load native module is not safe')\n}\nconst worker = new Worker('script.js')\nファイルを操作する特定の種類のアプリケーションは、オペレーティングシステムのネイティブなファイルのドラッグ&ドロップの機能をサポートしたいでしょう。 ファイルをウェブコンテンツにドラッグすることは一般的であり、多くのウェブサイトでサポートされています。 Electron はさらに、ファイルやコンテンツをウェブコンテンツからオペレーティングシステム側へドラッグすることをサポートしています。
\nこの機能をアプリに実装するには、ondragstart イベントへの応答として ``webContents.startDrag(item) API を呼ぶ必要があります。
この例では、実行時にファイルを作成し、ウィンドウ外へとドラッグできるようにする方法を示します。
\npreload.js では、contextBridge を使用してメインプロセスに IPC メッセージを送信するメソッド window.electron.startDrag(...) を注入します。
const { contextBridge, ipcRenderer } = require('electron')\nconst path = require('path')\n\ncontextBridge.exposeInMainWorld('electron', {\n startDrag: (fileName) => {\n ipcRenderer.send('ondragstart', path.join(process.cwd(), fileName))\n }\n})\nindex.html にドラッグ可能な要素を追加し、レンダラースクリプトを読むようにします。
<div style=\"border:2px solid black;border-radius:3px;padding:5px;display:inline-block\" draggable=\"true\" id=\"drag\">Drag me</div>\n<script src=\"renderer.js\"></script>\nrenderer.js ではレンダラープロセスを設定します。上記の contextBridge で追加したメソッドを呼び出す形で、ドラッグイベントを処理します。
document.getElementById('drag').ondragstart = (event) => {\n event.preventDefault()\n window.electron.startDrag('drag-and-drop.md')\n}\nメインプロセス (main.jsファイル) で受信したイベントを、以下のようにドラッグされたファイルのパスとアイコンへと展開します。
const { ipcMain } = require('electron')\n\nipcMain.on('ondragstart', (event, filePath) => {\n event.sender.startDrag({\n file: filePath,\n icon: '/path/to/icon.png'\n })\n})\nElectron アプリケーションを起動したら、BrowserWindow 上の アイテムをデスクトップへドラッグ & ドロップしてみてください。 このガイドでは、そのアイテムはプロジェクトのルートにある Markdown ファイルとなっています。
\n
\n\n\ntray や Dock やアプリケーションのアイコンを PNG や JPG ファイルで作成します。
\n
Electron では、 API が画像を取る場合、ファイルパスまたは NativeImage インスタンスを渡すことができます。 null が渡されたときは空の画像が使用されます。
例として、tray を作ったりウインドウのアイコンを設定したりするとき、String で画像ファイルパスを渡せます。
const { BrowserWindow, Tray } = require('electron')\n\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconst win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })\nconsole.log(appIcon, win)\nclipboard から画像を読む場合は、NativeImage が返されます。
const { clipboard, Tray } = require('electron')\nconst image = clipboard.readImage()\nconst appIcon = new Tray(image)\nconsole.log(appIcon)\n現在 PNG と JPEG の画像形式に対応しています。 透明度とか可逆圧縮に対応した PNG をおすすめします。
Windows では、ファイルパスから ICO アイコンを読み込むこともできます。 最高の表示品質を得るため、少なくとも以下のサイズを含めることをおすすめします:
この記事 内の サイズ要件 の章を確認して下さい。
\nApple Retina ディスプレイのような高解像度をサポートしているプラットフォームにおいて、画像のファイルネームの後ろに @2x を加えることで、高解像度の画像としてマークすることができます。
例えば、icon.png が通常の標準解像度の画像であれば、icon@2x.png が2倍のピクセル密度を持つ高解像度の画像として扱われます。
同時に異なるピクセル密度のディスプレイをサポートしたい場合、同じフォルダ内に異なるサイズの画像を置き、DPI 接尾子無しでファイル名を使用して下さい。 以下がその例です。
\nimages/\n├── icon.png\n├── icon@2x.png\n└── icon@3x.png\nconst { Tray } = require('electron')\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconsole.log(appIcon)\n以下の DPI 接尾子がサポートされています。
\n@1x@1.25x@1.33x@1.4x@1.5x@1.8x@2x@2.5x@3x@4x@5xテンプレート画像は黒色とアルファチャンネルで構成されます。 テンプレート画像は単体の画像として使用するものではなく、通常、最終的にさせたい見た目を作成するため、他のコンテンツと混合されます。
\n最も一般的なケースは、メニューバーのアイコンに使用することです。これは明るいメニューバーと暗いメニューバーの両方に適応できます。
\n注釈: テンプレート画像は macOS でのみサポートされています。
\n画像をテンプレート画像としてマークするには、そのファイル名が Template で終わる必要があります。 以下がその例です。
xxxTemplate.pngxxxTemplate.pngnativeImage オブジェクトには以下のメソッドがあります。いずれも NativeImage クラスのインスタンスを返します。
nativeImage.createEmpty()戻り値 NativeImage
空の NativeImage インスタンスを作成します。
nativeImage.createThumbnailFromPath(path, maxSize) macOS Windowspath String - サムネイルを構築するためのファイルのパス。maxSize Size - 返されうるサムネイルの最大の幅と高さ (正の数)。 Windows の実装では、maxSize.height を無視し maxSize.width に従って高さを拡大縮小します。戻り値 Promise<NativeImage> - これは NativeImage であるファイルのサムネイルプレビュー画像で解決されます。
nativeImage.createFromPath(path)path String戻り値 NativeImage
path のファイルから新しい NativeImage インスタンスを作成します。 このメソッドは、path が存在しない、読めない、有効な画像でない場合は、空の画像を返します。
const nativeImage = require('electron').nativeImage\n\nconst image = nativeImage.createFromPath('/Users/somebody/images/icon.png')\nconsole.log(image)\nnativeImage.createFromBitmap(buffer, options)buffer Bufferoptions Objectwidth Integerheight IntegerscaleFactor Double (任意) - 省略値は 1.0。戻り値 NativeImage
buffer から新しい NativeImage インスタンスを作成します。これにはtoBitmap() によって返された生のビットマップピクセルデータが含まれます。 詳細な形式はプラットフォームに依存します。
nativeImage.createFromBuffer(buffer[, options])buffer Bufferoptions Object (任意)width Integer (任意) - ビットマップバッファに必要。height Integer (任意) - ビットマップバッファに必要。scaleFactor Double (任意) - 省略値は 1.0。戻り値 NativeImage
buffer から NativeImage の新しいインスタンスを作成します。 最初に PNG または JPEG としてデコードしようとします。
nativeImage.createFromDataURL(dataURL)dataURL String戻り値 NativeImage
dataURL から NativeImage の新しいインスタンスを作成します。
nativeImage.createFromNamedImage(imageName[, hslShift]) macOS戻り値 NativeImage
指定した画像名にマップされる NSImage から NativeImage の新しいインスタンスを作成します。 使用可能な値のリストは、システムアイコン を参照してください。
hslShift は以下のルールで画像に適用されます。
hsl_shift[0] (色相): 画像における色相の絶対値 - 0 から 1 が 色相カラーホイール (赤) の 0 から 360 に割り当てられます。hsl_shift[1] (彩度): 画像における彩度の変化量。 以下のキー値を使用します: 0 = すべての色を取り除く。 0.5 = そのまま変わらない。 1 = 完全に鮮やかにする。hsl_shift[2] (明るさ): 画像における明るさの変化量。以下のキー値を使用します。 0 = 明るさをすべて取り除く (すべてのピクセルを黒にする)。 0.5 = そのまま変わらない。 1 = 完全に明るい (すべてのピクセルを白にする)。つまり、[-1, 0, 1] は完全に白い画像になり、[-1, 1, 0] は完全に黒い画像になります。
場合によっては、NSImageName はその文字列表現と一致しません。 その一例が NSFolderImageName で、その文字列表現は実際には NSFolder です。 そのため、画像を渡す前に正しい文字列表現を特定する必要があります。 これは以下のようにしてできます。
echo -e '#import <Cocoa/Cocoa.h>\\nint main() { NSLog(@\"%@\", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test
SYSTEM_IMAGE_NAME は このリスト から任意の値に置き換えてください。
\n\ntray や Dock やアプリケーションアイコンのような画像を、ネイティブにラップします。
\n
プロセス: メイン、レンダラー
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
NativeImage クラスのインスタンスには、以下のメソッドがあります。
image.toPNG([options])options Object (任意)scaleFactor Double (任意) - 省略値は 1.0。戻り値 Buffer - PNG エンコードされた画像データを含む Buffer。
image.toJPEG(quality)quality Integer - 0 - 100 の間です。戻り値 Buffer - JPEG エンコードされた画像データを含む Buffer。
image.toBitmap([options])options Object (任意)scaleFactor Double (任意) - 省略値は 1.0。戻り値 Buffer - 生のビットマップ画像のピクセルデータのコピーを含む Buffer。
image.toDataURL([options])options Object (任意)scaleFactor Double (任意) - 省略値は 1.0。戻り値 String - 画像のデータURL。
image.getBitmap([options])options Object (任意)scaleFactor Double (任意) - 省略値は 1.0。戻り値 Buffer - 生のビットマップ画像のピクセルデータを含む Buffer。
getBitmap() と toBitmap() には違いがあります。getBitmap() はビットマップをコピーしないので、現在のイベントループティックで即座に使用しなければ、そのデータが変更または破棄される可能性があります。
image.getNativeHandle() macOS戻り値 Buffer - 画像の元になるネイティブハンドルへの C ポインタを格納する Buffer。 macOS では、NSImage のインスタンスのポインタが返されます。
返されるポインタは、コピーではなく、元のネイティブな画像へのウィークポインタであることに注意して下さい。関連する nativeImage インスタンスが確実に保持されなければなりません。
image.isEmpty()戻り値 Boolean - 画像が空かどうか。
image.getSize([scaleFactor])scaleFactor Double (任意) - 省略値は 1.0。戻り値 Size.
scaleFactor が渡された場合、渡された値に最も近い画像表現に対応するサイズを返します。
image.setTemplateImage(option)option Boolean画像をテンプレート画像としてマークします。
\nimage.isTemplateImage()戻り値 Boolean - 画像がテンプレート画像かどうか。
image.crop(rect)rect Rectangle - 画像をトリミングする領域。戻り値 NativeImage - トリミングされた画像。
image.resize(options)options Objectwidth Integer (任意) - 省略値は画像の幅。height Integer (任意) - 省略値は画像の高さ。quality String (任意) - リサイズした画像の希望する画質。 値は good、better、best のいずれかにできます。 省略値は、best です。 これらの値は、必要な画質と速度のトレードオフを表現する。 これらは、動作プラットフォームの機能 (CPU、GPU) に依存するアルゴリズム固有のメソッドに変換されます。 3 つのメソッド全てを、特定プラットフォーム上の同じアルゴリズムに割り当てることもできます。戻り値 NativeImage - リサイズされた画像。
height または width のどちらかのみが指定された場合、アスペクト比はリサイズされた画像でも保持されます。
image.getAspectRatio([scaleFactor])scaleFactor Double (任意) - 省略値は 1.0。戻り値 Float - イメージのアスペクト比。
scaleFactor が渡された場合、渡された値に最も近い画像表現に対応するアスペクト比を返します。
image.getScaleFactors()戻り値 Float[] - この NativeImage の表現に対応するすべての拡大率の配列。
image.addRepresentation(options)options ObjectscaleFactor Double - 画像を表現する際の拡大倍率。width Integer (任意) - 既定値は 0 です。 buffer にビットマップバッファが指定されている場合は必要です。height Integer (任意) - 既定値は 0 です。 buffer にビットマップバッファが指定されている場合は必要です。buffer Buffer (任意) - 生の画像データを格納するバッファ。dataURL String (任意) - Base64 エンコードした PNG または JPEG 画像を格納しているデータURL。画像の表現を指定された縮尺で追加します。 これによって、異なる縮尺の表現を明示的に画像へ追加できます。 空の画像で呼び出すことができます。
\nnativeImage.isMacTemplateImage macOSBoolean 型のプロパティです。その画像が テンプレート画像 と見なされるかどうかを決定します。
このプロパティは macOS にのみ影響することに注意してください。
", "title": "nativeImage", "description": "tray や Dock やアプリケーションのアイコンを PNG や JPG ファイルで作成します。" }, "/docs/api/native-theme": { "locale": "ja-JP", "slug": "native-theme", "href": "/docs/api/native-theme", "crowdinFileId": "256343", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/native-theme.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nChromium のネイティブカラーテーマの変更を読み取って対応します。
\n
プロセス: Main
\nnativeTheme モジュールには以下のイベントがあります。
基になる NativeTheme の何かが変更されたときに発行されます。 これは通常、shouldUseDarkColors、shouldUseHighContrastColors または shouldUseInvertedColorScheme のいずれかの値が変更されたことを意味します。 それらを確認して、どれが変更されたかを判断する必要があります。
nativeTheme モジュールには以下のプロパティがあります。
nativeTheme.shouldUseDarkColors 読み出し専用OS / Chromium で現在ダークモードが有効になっている、またはダークスタイルの UI を表示するように指示されているかどうかの Boolean。 この値を変更する場合は、以下の themeSource を使用する必要があります。
nativeTheme.themeSourceString 型のプロパティです。system、light か dark にできます。 Chromium が内部で使用することを選択した値をオーバーライドして置き換えるために使用されます。
このプロパティを system に設定するとオーバーライドが削除され、すべてが OS のデフォルトにリセットされます。 既定の themeSource は system です。
このプロパティを dark に設定すると、以下の効果があります。
nativeTheme.shouldUseDarkColors はアクセス時に true になりますprefers-color-scheme CSS が dark モードに親和します。updated イベントが発生します。このプロパティを light に設定すると、以下の効果があります。
nativeTheme.shouldUseDarkColors はアクセス時に false になりますprefers-color-scheme CSS が light モードに親和します。updated イベントが発生します。このプロパティを使用するにあたって、ユーザーに以下のような 3 つの選択肢がある、古典的なアプリケーションの \"ダークモード\" ステートマシンに合わせるべきです。
\nFollow OS --> themeSource = 'system'Dark Mode --> themeSource = 'dark'Light Mode --> themeSource = 'light'アプリケーションは、shouldUseDarkColors を使用して、適用する CSS を常に決定する必要があります。
nativeTheme.shouldUseHighContrastColors macOS Windows 読み出し専用OS / Chromium で現在ハイコントラストモードが有効になっている、またはハイコントラスト UI を表示するように指示されているかどうかの Boolean。
nativeTheme.shouldUseInvertedColorScheme macOS Windows 読み出し専用OS / Chromium が現在反転カラースキームを持っている、または反転カラースキームを使用するように指示されているかどうかの Boolean。
\n\nChromium のネイティブのネットワークライブラリを使用して、 HTTP/HTTPS リクエストを発行します。
\n
プロセス: Main
\nnet モジュールは HTTP(S) リクエストを発行するクライアントサイド API です。 これは Node.js の HTTP および HTTPS モジュールに似ていますが、Node.js 実装の代わりに Chromium のネイティブネットワークライブラリを使用し、ウェブプロキシをより効果的にサポートします。 また、ネットワーク状況の確認にも対応しています。
以下は、完全に網羅しているわけではありませんが、ネイティブ Node.js モジュールの代わりに net モジュールを使用することを検討する理由のリストです。
API コンポーネント (クラス、メソッド、プロパティ、イベント名など) は、Node.js で使用されているものと同様です。
\n使用例:
\nconst { app } = require('electron')\napp.whenReady().then(() => {\n const { net } = require('electron')\n const request = net.request('https://github.com')\n request.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`)\n console.log(`HEADERS: ${JSON.stringify(response.headers)}`)\n response.on('data', (chunk) => {\n console.log(`BODY: ${chunk}`)\n })\n response.on('end', () => {\n console.log('No more data in response.')\n })\n })\n request.end()\n})\nnet API は、アプリケーションが ready イベントを発生させた後でのみ使用できます。 ready イベントの前にモジュールを使用しようとすると、エラーがスローされます。
net モジュールには以下のメソッドがあります。
net.request(options)options (ClientRequestConstructorOptions | String) - ClientRequest コンストラクタのオプション。戻り値 ClientRequest
ClientRequest コンストラクタに直接転送される options を使用してClientRequest インスタンスを作成します。 net.request メソッドは、options オブジェクト内の指定されたプロトコルにしたがって、セキュアとインセキュア両方の HTTP リクエストを発行するために使用されます。
net.isOnline()戻り値 Boolean - 現在インターネットに接続しているかどうか。
戻り値が false の場合、ユーザーがリモートサイトに接続できないことをかなり強く示しています。 しかし、true の戻り値は決定的ではありません。いくつかのリンクが見当たらなくても、特定リモートサイトへの特定の接続試行が成功するかどうかは不確かです。
net.online 読み出し専用Boolean 型のプロパティです。 これは現在インターネットに接続しているかどうかです。
戻り値が false の場合、ユーザーがリモートサイトに接続できないことをかなり強く示しています。 しかし、true の戻り値は決定的ではありません。いくつかのリンクが見当たらなくても、特定リモートサイトへの特定の接続試行が成功するかどうかは不確かです。
\n\nセッションのネットワークイベントをロギングします。
\n
プロセス: Main
\nconst { netLog } = require('electron')\n\napp.whenReady().then(async () => {\n await netLog.startLogging('/path/to/net-log')\n // ネットワークイベントの後\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nアプリのライフサイクル全体にわたってネットワークイベントをロギングするには --log-net-log を参照してください。
注釈: 指定されていないすべてのメソッドは、app モジュールの ready イベントが発生した後にのみ使用できます。
netLog.startLogging(path[, options])path String - ネットワークログを記録するファイルパス。options Object (任意)captureMode String (任意) - キャプチャするデータの種類。 既定では、リクエストに関するメタデータのみがキャプチャされます。 これを includeSensitive にすると、Cookie と認証データが含まれます。 everything にすると、ソケットで転送されるすべてのバイトが含まれます。 default、includeSensitive または everything にできます。maxFileSize Number (任意) - ログがこのサイズを超えると、ロギングは自動的に停止します。 デフォルトでは無制限です。戻り値 Promise<void> - ネットログの記録が開始されると解決します。
path へネットワークイベントの記録を開始する。
netLog.stopLogging()戻り値 Promise<void> - ネットログがディスクに書き込まれたときに解決されます。
ネットワークイベントの記録を停止します。 もし呼ばれなければ、ネットロギングはアプリ終了時に自動的に終了します。
\nnetLog.currentlyLogging 読み出し専用Boolean 型のプロパティです。ネットワークログが現在記録されているかどうかを示します。
EventnewGuest BrowserWindow (optional)\n\nデスクトップ通知を作成します。
\n
プロセス: Main
\nレンダラープロセスから通知を表示したい場合は、HTML5 Notification API を使用する必要があります
\n\n\nデスクトップ通知を作成します。
\n
プロセス: Main
\nNotification は EventEmitter を継承しています。
options によって設定されたネイティブプロパティで新しい Notification を生成します。
Notification クラスには、次の静的メソッドがあります。
Notification.isSupported()戻り値 Boolean - 現在のシステムでデスクトップ通知がサポートされているかどうか。
new Notification([options])options Object (任意)title String (任意) - 通知ウィンドウの上部に表示される通知のタイトル.subtitle String (任意) macOS - タイトルの下に表示される、通知のサブタイトル。body String (任意) - タイトルやサブタイトルの下に表示さる、通知の本文。silent Boolean (任意) - 通知を表示するときにOSが通知音を鳴らすかどうか。icon (String | NativeImage) (任意) - 通知に使用されるアイコン。hasReply Boolean (任意) macOS - 通知に埋め込み返信オプションを追加するかどうか。timeoutType String (任意) Linux Windows - 通知の消失までの時間。 'default' か 'never' にできます。replyPlaceholder String (任意) macOS - 埋め込み返信入力フィールド内に書かれるプレースホルダ。sound String (任意) macOS - 通知が表示されるときに再生される音声ファイルの名前。urgency String (任意) Linux - 通知の緊急度レベル。 'normal'、'critical'、'low' のいずれかにできます。actions NotificationAction[] (任意) macOS - 通知に追加するアクション。 NotificationAction ドキュメント内の有効なアクションと制限を読んで下さい。closeButtonText String (任意) macOS - 通知を閉じるボタンのカスタムタイトル。 空の文字列の場合は、既定のローカライズされたテキストが使用されます。toastXml String (任意) Windows - Windows 通知のカスタム記述は、上記のプロパティすべてを上書きします。 これは通知のデザインと動作の完全なカスタマイズを提供します。new Notification で作成されたオブジェクトでは以下のイベントが発生します。
注: いくつかのイベントは特定のオペレーティングシステムでのみ利用可能で、そのように注記がつけられています。
\n戻り値：
\nevent Event通知がユーザーに表示されたときに発行されます。show() メソッドを使用して通知を複数回表示できることに注意して下さい。
戻り値：
\nevent Eventユーザによって通知がクリックされたときに発行されます。
\n戻り値：
\nevent Eventユーザの手によって手動で通知が閉じられたときに発行されます。
\nこのイベントは、通知が閉じられたすべての状況で発行されることは保証されていません。
\n戻り値：
\nevent Eventreply String - ユーザが埋め込み返信フィールドに入力した文字列.hasReply: true の通知上で、ユーザが \"返信\" ボタンをクリックしたときに発行されます。
戻り値：
\nevent Eventindex Number - アクティベートされたアクションのインデックス.戻り値：
\nevent Eventerror String - show() メソッドの実行中に発生したエラー。ネイティブ通知の作成および表示でエラーに遭遇した場合に発生します。
\nnew Notification で作成されたオブジェクトは、次のインスタンスメソッドを持っています。
notification.show()HTML5 Notification の実装とは異なり、new Notification でインスタンス化するだけでは、すぐにユーザに表示されないことに注意してください。OS が表示するためにこのメソッドを呼び出す必要があります。
以前にその通知が表示されている場合、このメソッドはその通知を閉じ、同じプロパティを持つ新しい通知を作成します。
\nnotification.close()通知を閉じます。
\nnotification.title通知のタイトルを表す String プロパティ。
notification.subtitle通知のサブタイトルを表す String プロパティ。
notification.body通知の本文を表す String プロパティ。
notification.replyPlaceholder通知の応答プレースホルダーを表す String プロパティ。
notification.sound通知音を表す String プロパティ。
notification.closeButtonText通知の閉じるボタンのテキストを表す String プロパティ。
notification.silent通知が無音かどうかを表す Boolean プロパティ。
notification.hasReply通知に応答アクションがあるかどうかを表す Boolean プロパティ。
notification.urgency Linux通知の緊急度を表す String プロパティ。 'normal'、'critical'、'low' のいずれかにできます。
省略値は 'low' - この詳細は NotifyUrgency を参照してください。
\nnotification.timeoutType Linux Windows通知がタイムアウトする種別を表す String プロパティ。 'default' か 'never' にできます。
timeoutType が 'never' に設定されている場合、通知は自動的に閉じられません。 呼び出し元の API かユーザによって閉じられるまで開いたままになります。
notification.actions通知のアクションを表す NotificationAction[] プロパティ。
notification.toastXml WindowsString 型のプロパティで、通知のカスタム Toast XML を表します。
macOS では、通知が表示されたときに再生したいサウンドの名前を指定することができます。 カスタムサウンドファイルに加えて、(システム環境設定 > サウンド にある) デフォルトサウンドのいずれかを使用することができます。 サウンドファイルがアプリバンドル (YourApp.app/Contents/Resources など) または以下のいずれかの場所にコピーされることに留意してください。
~/ライブラリ/Sounds/ライブラリ/Sounds/ネットワーク/ライブラリ/Sounds/システム/ライブラリ/Soundsより詳しくは、NSSound ドキュメントを参照して下さい。
type String - The type of action, can be button.text String (optional) - The label for the given action.| Action Type | Platform Support | Usage of text | Default text | Limitations |
|---|---|---|---|---|
button | macOS | Used as the label for the button | \"Show\" (or a localized string by system default if first of such button, otherwise empty) | Only the first one is used. If multiple are provided, those beyond the first will be listed as additional actions (displayed when mouse active over the action button). Any such action also is incompatible with hasReply and will be ignored if hasReply is true. |
In order for extra notification buttons to work on macOS your app must meet the following criteria.
\nNSUserNotificationAlertStyle set to alert in the Info.plist.If either of these requirements are not met the button won't appear.
", "title": "NotificationAction Object", "description": "" }, "/docs/api/structures/notification-response": { "locale": "ja-JP", "slug": "notification-response", "href": "/docs/api/structures/notification-response", "crowdinFileId": "256473", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/notification-response.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "actionIdentifier String - The identifier string of the action that the user selected.date Number - The delivery date of the notification.identifier String - The unique identifier for this notification request.userInfo Record<String, any> - A dictionary of custom information associated with the notification.userText String (optional) - The text entered or chosen by the user.3 つのオペレーティングシステムはすべて、アプリケーションがユーザに通知を送信する手段を提供しています。 通知を表示する方法はメインプロセスとレンダラーのプロセスで異なります。
\nレンダラープロセスでは、現在実行中のオペレーティングシステムのネイティブ通知 API を使用する、HTML5 通知 API で通知を送信して表示できます。
\nメインプロセスで通知を表示するには、Notification モジュールを使用する必要があります。
\nクイックスタートガイド の作業用アプリケーションから始めることにして、 index.html ファイルの </body> タグを閉じる手前に以下の行を追加します。
<script src=\"renderer.js\"></script>\n…そして renderer.js ファイルを追加します。
const NOTIFICATION_TITLE = 'Title'\nconst NOTIFICATION_BODY = 'Notification from the Renderer process. Click to log to console.'\nconst CLICK_MESSAGE = 'Notification clicked'\n\nnew Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY })\n .onclick = () => console.log(CLICK_MESSAGE)\nElectron アプリケーションを起動すると、以下のような通知が表示されるでしょう。
\n
さらに、通知をクリックすると、DOM が更新されて \"Notification clicked!\" と表示されます。
\nクイックスタートガイド の作業用アプリケーションから始めることにして、 main.js ファイルを以下の行の通りに更新します。
const { Notification } = require('electron')\n\nconst NOTIFICATION_TITLE = 'Basic Notification'\nconst NOTIFICATION_BODY = 'Notification from the Main process'\n\nfunction showNotification () {\n new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()\n}\n\napp.whenReady().then(createWindow).then(showNotification)\nElectron アプリケーションを起動すると、以下のようなシステム通知が表示されるでしょう。
\n
オペレーティングシステム間でのコードとユーザエクスペリエンスは似ていますが、微妙な違いがあります。
\nnode_modules\\electron\\dist\\electron.exe を追加することも一つの手です。 エクスプローラーでそのファイルを開き、右クリックして 'スタート メニューにピン留めする' を選択します。 そして、通知を表示するにはメインプロセスに app.setAppUserModelId(process.execPath) の一行を追加する必要があります。Electronは、アプリケーションユーザーモデル ID の作業を自動化しようとしています。 Electron をインストール&アップデートフレームワーク Squirrel と共に使用すると、ショートカットが自動的に正しく設定されます。 さらに、Electron は Squirrel が使用されたことを検出し、正しい値を指定して自動的に app.setAppUserModelId() を呼び出します。 開発中では、app.setAppUserModelId() を自身で呼び出す必要があります。
さらに、Windows 8では、通知本体の最大長は250文字で、Windowsチームは通知を200文字にすることを推奨しています。 この制限は Windows 10では削除されており、これは Windows チームは合理的にするために開発者の意見を聞いているということです。 巨大な量のテキスト (数千文字) を API に送信しようとすると、不安定になる可能性があります。
\nWindows の以降のバージョンでは、カスタムテンプレート、イメージ、その他の柔軟な要素を使用した高度な通知が可能です。 これらの通知を (メインプロセスかレンダラープロセスから) 送信するには、ToastNotification と TileNotification オブジェクトを送るネイティブ Node アドオンを使用する、electron-windows-notification ユーザーランドモジュールを使用します。
ボタンを含む通知は electron-windows-notifications で機能しますが、返信を処理するには electron-windows-interactive-notifications を使用する必要があります。これにより、必要な COM コンポーネントを登録し、入力したユーザーデータを使用して Electron アプリを呼び出すことができます。
通知を送信することが許可されているかどうかを検出するには、ユーザーランドモジュールの electron-notification-state を使用します。
\nこれにより、Windows が通知を無音で表示するかどうかを事前に判断することができます。
\nmacOS 上での通知は簡単ですが、通知に関する Apple のヒューマンインタフェースガイドライン を理解しておく必要があります。
\n通知サイズは256バイトに制限されており、その制限を超えると切り捨てられることに注意してください。
\n通知を送信することが許可されているかどうかを検出するには、electron-notification-state ユーザーランドモジュールを使用します。
\nこれにより、通知が表示されるかどうかを事前に検出することができます。
\n通知は、デスクトップ通知仕様 (Cinnamon、Enlightenment、Unity、GNOME、KDE) に従ってデスクトップ環境の通知を表示できる libnotify を使用して送信されます。
オフスクリーンレンダリングでは BrowserWindow のコンテンツを ビットマップで取得できます。これは、3D シーンのテクスチャのようにどこにでも描画できます。 Electron のオフスクリーンレンダリングは Chromium 埋め込みフレームワーク プロジェクトと似たアプローチを使用しています。
注意:
\npaint イベントに渡すことでより効率的なレンダリングができます。GPU アクセラレーションレンダリングとは、GPU が構成に使用されることを意味します。 GPU からのフレームのコピーにより多くのリソースを必要とするため、このモードはソフトウェア出力デバイスよりも遅くなります。 このモードのメリットは、WebGL と 3D CSS アニメーションがサポートされていることです。
\nこのモードでは、CPU レンダリングのソフトウェア出力デバイスが使用されているため、フレーム生成は非常に高速です。 したがって、このモードは GPU アクセラレーションよりも好まれます。
\nこのモードを有効にするには、app.disableHardwareAcceleration() API を呼び出して GPU アクセラレーションを無効にする必要があります。
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\n\napp.disableHardwareAcceleration()\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ webPreferences: { offscreen: true } })\n\n win.loadURL('https://github.com')\n win.webContents.on('paint', (event, dirty, image) => {\n fs.writeFileSync('ex.png', image.toPNG())\n })\n win.webContents.setFrameRate(60)\n})\nこの Electron アプリケーションを起動したら、アプリケーションを開いたフォルダを見てみましょう。描画された画像があるはずです。
", "title": "オフスクリーンレンダリング", "description": "" }, "/docs/tutorial/online-offline-events": { "locale": "ja-JP", "slug": "online-offline-events", "href": "/docs/tutorial/online-offline-events", "crowdinFileId": "256229", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/online-offline-events.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "標準 HTML5 API の一部である navigator.onLine 属性を使用して、オンラインおよびオフラインイベント の検出をレンダラープロセスに実装できます。
navigator.onLine 属性の戻り値は以下の通りです。
false ネットワーク要求が失敗することが保証されている場合、つまり確実にオフラインの (ネットワークから切断されている) 場合。true それ以外の状況。他のすべての条件で trueが返されるので、true の値は必ずしも Electron がインターネットアクセス可能であるとは限りません。誤検出に注意する必要があります。 例えば、仮想イーサネットアダプタを \"常時接続\" 状態にした仮想化ソフトをコンピュータ上で実行している場合などです。 したがって、Electron のインターネットアクセス状況を判定したい場合には、さらにこの確認手段を開発する必要があります。
このサンプルでは、HTML ファイル index.html から始めて、navigator.onLine API を用いた接続状態インジケータの構築方法を示します。
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n</head>\n<body>\n <h1>Connection status: <strong id='status'></strong></h1>\n <script src=\"renderer.js\"></script>\n</body>\n</html>\nDOM を変更するために、renderer.jsファイルを作成して、そこで window の 'online' と 'offline' の イベントにイベントリスナーを追加します。 イベントハンドラーでは、navigator.onLine の結果に応じて <strong id='status'> 要素の内容を設定します。
function updateOnlineStatus () {\n document.getElementById('status').innerHTML = navigator.onLine ? 'online' : 'offline'\n}\n\nwindow.addEventListener('online', updateOnlineStatus)\nwindow.addEventListener('offline', updateOnlineStatus)\n\nupdateOnlineStatus()\n最後に、メインプロセス用の main.js ファイルを作成し、そこでウインドウを作成します。
const { app, BrowserWindow } = require('electron')\n\nfunction createWindow () {\n const onlineStatusWindow = new BrowserWindow({\n width: 400,\n height: 100\n })\n\n onlineStatusWindow.loadFile('index.html')\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nElectron アプリケーションを起動すると、以下のような通知が表示されるでしょう。
\n
\n", "title": "オンライン/オフライン イベントの検出", "description": "注意: メインプロセスに接続状態を伝える必要がある場合は、IPC レンダラー API を使用してください。" }, "/docs/development/patches": { "locale": "ja-JP", "slug": "patches", "href": "/docs/development/patches", "crowdinFileId": "256161", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/patches.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "注意: メインプロセスに接続状態を伝える必要がある場合は、IPC レンダラー API を使用してください。
\n
Electron は、Chromium と Node.js という 2 つのメジャーな上流プロジェクトで構築されています。 これらのプロジェクトにも、それぞれ独自の依存関係がいくつかあります。 これらの依存関係をそのまま使用するように最善を尽くしていますが、ユースケースに合わせて上流の依存関係にパッチを適用しないと目標を達成できない場合があります。
\nElectron でのパッチは、すべてメンテナンスの負担になります。 上流のコードが変更されると、パッチが壊れる―パッチの競合やコンパイルエラーが発生することがあります。 これはパッチセットを最新かつ効果的に保つための継続的な取り組みです。 そのため、パッチの数を最小限に抑えるよう努めています。 そのために、すべてのパッチには、コミットメッセージに存在する理由を記述する必要があります。 その理由は、以下のいずれかでなければなりません。
\nProfile への参照のパッチを当てる) であるため上流にできない。 パッチなし (たとえば、サブクラス化またはコードのコピーによるもの) では変更を実装できない理由についての論述を含む。基本的に、私たちが作業するすべての上流プロジェクトは友好的な人々が携わっており、問題のコードが Electron と上流プロジェクトの両方と互換性を持つようにするリファクタリングを喜んで受け入れてくれます。 (たとえば、Chromium の この 変更を挙げると、同じことを行ったパッチを削除しています。また、Node の この 変更は、 Electron のバグ修正でもあります。) 可能な限り上流の変更を目指し、無期限のパッチを避けるべきです。
\n上流プロジェクトにパッチを適用することによってのみ行うことができる変更を行う必要がある、という不幸な立場にいる場合は、Electron でパッチを管理する方法を知る必要があります。
\nElectron の上流プロジェクトへのすべてのパッチは、patches/ ディレクトリに含まれています。 patches/ の各サブディレクトリには、いくつかのパッチファイルと、パッチを適用する順序をリストした .patches ファイルが含まれています。 これらのファイルは、チェックアウト後に上流プロジェクト上に適用される一連の git コミットを構成していると考えてください。
patches\n├── config.json <-- これはどのパッチセットディレクトリがどのプロジェクトに適用されるかを記述しています\n├── chromium\n│ ├── .patches\n│ ├── accelerator.patch\n│ ├── add_contentgpuclient_precreatemessageloop_callback.patch\n│ ⋮\n├── node\n│ ├── .patches\n│ ├── add_openssl_is_boringssl_guard_to_oaep_hash_check.patch\n│ ├── build_add_gn_build_files.patch\n│ ⋮\n⋮\nこれらのパッチセットを管理しやすくするために、git-import-patches と git-export-patches の 2 つのツールを提供しています。 git-import-patches は、各パッチを正しい順序で適用し、各パッチのコミットを作成することにより、一連のパッチファイルを git リポジトリにインポートします。 git-export-patches は逆の処理を行います。 リポジトリ内の一連の git コミットを、ディレクトリ内の一連のファイルとそれに付随する .patches ファイルにエクスポートします。
\n\n補足: パッチの順序に関連した競合を減らすために、各ファイルに
\n001-のような番号を追加するのではなく、.patchesファイルを使用して適用されるパッチの順序を維持しています。 これにより、2 つの PR の両方が同じ番号である次の連番にパッチを追加し、両方がマージされて重複した識別子になるといった状況を防ぎます。 また、連番の間のパッチが追加または削除された場合の混乱も減ります。
$ cd src/third_party/electron_node\n$ vim some/code/file.cc\n$ git commit\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\n\n\n注:
\ngit-export-patchesはコミットされていないファイルを無視するため、変更をエクスポートする場合はコミットを作成する必要があります。 パッチファイル名はコミットメッセージの件名に使用し、コミットメッセージの本文にパッチの存在理由を含める必要があります。
パッチを再エクスポートすると、無関連なパッチの SHA サムが変更される場合があります。 これは一般に無害であり、無視することができます (ただし、これらの変更を PR に追加しても他の人には見えません)。
\n$ cd src/v8\n$ vim some/code/file.cc\n$ git log\n# 編集するパッチのコミット SHA を見つけます。\n$ git commit --fixup [COMMIT_SHA]\n$ git rebase --autosquash -i [COMMIT_SHA]^\n$ ../electron/script/git-export-patches -o ../electron/patches/v8\n$ vim src/electron/patches/node/.patches\n# 削除するパッチ名の行を削除します\n$ cd src/third_party/electron_node\n$ git reset --hard refs/patches/upstream-head\n$ ../../electron/script/git-import-patches ../../electron/patches/node\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\n注意として、git-import-patches は refs/patches/upstream-head として実行されたときに HEAD だったコミットをマークします。 これにより、Electron パッチからのコミット (refs/patches/upstream-head の後にあるコミット) と上流にあるコミット (refs/patches/upstream-head の前にあるコミット) を追跡できます。
上流の依存関係を更新するとき、パッチをきれいに適用できない場合があります。 多くの場合、3 ウェイマージを使用して git で競合を自動的に解決できます。 -3 の引数を渡すことで、3 ウェイマージアルゴリズムを使用するように git-import-patches に指示できます。
$ cd src/third_party/electron_node\n# パッチの適用が途中で失敗した場合は、以下のようにしてリセットできます。\n$ git am --abort\n# そして 3 ウェイマージで再試行します。\n$ ../../electron/script/git-import-patches -3 ../../electron/patches/node\ngit-import-patches -3 が自動的に解決できないマージ競合を検出した場合、一時停止し、競合を手動で解決できます。 競合を解決したら、解決したファイルを git add し、git am --continue を実行して残りのパッチを適用し続けます。
開発者は Electron アプリケーションのパフォーマンスを最適化するための戦略について頻繁に尋ねます。 ソフトウェアエンジニア、消費者、フレームワークの開発者は、常に \"パフォーマンス\" は何を意味するかという 1 つの定義には同意しません。 このドキュメントでは、使用しているメモリ、CPU、およびディスクリソースの量を削減し、アプリがユーザー入力に応答し、操作をできるだけ早く完了するようにする、Electron メンテナー御用達の方法のいくつかを概説します。 さらに、すべてのパフォーマンス戦略においてアプリは高いセキュリティ水準を維持する必要があります。
\nJavaScript でパフォーマンスの高いウェブサイトを構築する方法に関する知恵と情報は、Electron アプリにも一般的に適用されます。 ある程度であれば、パフォーマンスの高い Node.js アプリケーションを構築する方法を述べたノウハウも適用されますが、Node.js バックエンドでの \"パフォーマンス\" という用語はクライアントで実行されるアプリケーションとは異なることを意味することに注意してください。
\nこのリストは利便性のために提供されており、セキュリティチェックリスト とよく似ていますが、完全なものではありません。 以下に概説するすべての手順に従っても、遅い Electron アプリを構築してしまうかもしれません。 Electron は強力な開発プラットフォームであり、開発者であるあなたがやりたいことは多かれ少なかれ行うことができます。 その自由はパフォーマンスがほとんどあなたの責任であることを意味します。
\n以下のリストには、かなり簡単で実装しやすい手順がいくつか含まれています。 しかし、アプリを最もパフォーマンスの良いバージョンに構築するには、多くの手順を越える必要があります。 代わりに、慎重にプロファイリングして測定することでアプリで実行されているすべてのコードを詳しく調べる必要があります。 ボトルネックはどこ? いつユーザーがボタンをクリックして、どの処理が時間を浪費をしている? アプリがただアイドル状態の間、どのオブジェクトが最もメモリを食っている?
\n幾度となく、パフォーマンスの高い Electron アプリを構築するための最も成功した戦略は、実行中のコードのプロファイルを作成し、その中で最もリソースを消費する部分を見つけ、最適化することであることがわかりました。 この一見面倒なプロセスを何度も繰り返すと、アプリのパフォーマンスは劇的に向上します。 Visual Studio Code や Slack などの主要なアプリで使用された経験から、この方法がパフォーマンスを向上させる最も信頼できる戦略であることが示されています。
\nアプリのコードをプロファイリングする方法について知りたいのであれば、Chrome デベロッパーツールと仲良くなってください。 複数のプロセスを同時に見て高度に分析するには、Chrome Trace ツールをご検討ください。
\nこれらの手順を実行すると、アプリが少しだけ無駄なく、高速になり、一般的にリソースの消費が少なくなる可能性があります。
\nNode.js モジュールをアプリケーションに追加する前に、そのモジュールを調べましょう。 そのモジュールにはどれだけの依存関係が含まれているでしょうか。 どの種類のリソースが、単に require() 文で呼び出す必要があるでしょうか。 NPM パッケージレジストリでダウンロード数が最も多かったり GitHub で最もスターの数が多かったりするモジュールは、実際には利用可能なもののうち最もすっきりとした最小のものではない場合があります。
この推奨事項の背後にある理由は、実例で最もよく説明されています。 Electron の初期の頃は、ネットワーク接続の信頼できる検出が問題でした。そのため、多くのアプリは簡易な isOnline() メソッドを公開しているモジュールを使用していました。
そのモジュールは、多くの有名なエンドポイントに到達するかどうかでネットワーク接続を検出しました。 これらのエンドポイントのリストについては、既知のポートのリストも含まれる別のモジュールに依存していました。 この依存モジュール自身は、ポートに関する情報を含むモジュールに依存していました。これは、100,000 行を超える内容の JSON ファイルの形式で提供されていました。 モジュールがロードされるたびに (通常は require('module') 文で)、すべての依存関係をロードし、最終的にこの JSON ファイルを読み取って解析します。 数千行の JSON の解析は非常に重い操作です。 遅いマシンでは、全体で数秒かかる場合があります。
多くのサーバーコンテキストでは、起動にかかる時間は実質的に無関係です。 すべてのポートに関する情報を必要とする Node.js サーバーは、サーバーが起動してリクエストをより高速に処理できるようになると、必要なすべての情報をメモリにロードするため実際に \"パフォーマンスが向上\" します。 この例で説明するモジュールは、\"悪質な\" モジュールではありません。 ただし、Electron アプリでは、実際に必要のない情報をメモリに読み込んで解析したり保存したりするべきではありません。
\n要するに、主に Linux で実行する Node.js サーバー用に書かれた一見優れたモジュールは、アプリのパフォーマンスにとって悪いニュースかもしれません。 この特定の例での正しいソリューションは、モジュールはまったく使用せず、代わりに Chromium の後のバージョンに含まれる接続チェックを使用することでした。
\nモジュールを検討するときは、以下を確認することを推奨します。
\nrequire()) に必要なリソースモジュールをロードするときの CPU プロファイルとヒープメモリプロファイルの生成は、コマンドライン上の 1 つのコマンドで実行できます。 以下の例では、人気のあるモジュール request を見ていきます。
node --cpu-prof --heap-prof -e \"require('request')\"\nこのコマンドを実行すると、実行したディレクトリに .cpuprofile ファイルと .heapprofile ファイルが作成されます。 両方のファイルは、Chrome デベロッパーツールを使用して、それぞれ Performance および Memory タブを使用して分析できます。
この例では、著者のマシンで request のロードに約 0.5 秒かかったのに対し、node-fetch のメモリ消費は劇的に少なく、50ms 未満でした。
重いセットアップ操作がある場合は、それらを後回しすることを検討してください。 アプリケーションの起動直後に実行されているすべての作業を調べます。 すべての操作をすぐに実行するのではなく、ユーザーの行程により近い順序で操作をずらすことを検討してください。
\n従来の Node.js 開発では、すべての require() ステートメントを先頭に配置する慣習がありました。 いま同じ戦略を使用 しつつ すぐ必要ではないサイズの大きいモジュールを使用している Electron アプリケーションを作成している場合、同じ戦略のうえで、より適切なタイミングで読み込むように後回しします。
モジュールのロードは、特に Windows では驚くほど重い操作です。 アプリの起動時に、ユーザーに現在必要のない操作で待たせてはなりません。
\nこれは当たり前のように思えるかもしれませんが、多くのアプリケーションは、更新の確認、後のフローで使用されるコンテンツのダウンロード、重いディスク I/O 操作の実行など、アプリの起動直後に大量の作業を行う傾向があります。
\n例として Visual Studio Code を考えてみましょう。 ファイルを開くと、コードを強調表示せずにすぐにファイルが表示され、テキストを操作する機能が優先されます。 その作業が完了すると、コードの強調表示に進みます。
\n例として、アプリケーションが架空の .foo 形式のファイルを解析していると仮定しましょう。 それをするためには、同様に架空の foo-parser モジュールに依存します。 従来の Node.js 開発では、依存関係を先にロードするコードを作成する場合があります。
const fs = require('fs')\nconst fooParser = require('foo-parser')\n\nclass Parser {\n constructor () {\n this.files = fs.readdirSync('.')\n }\n\n getParsedFiles () {\n return fooParser.parse(this.files)\n }\n}\n\nconst parser = new Parser()\n\nmodule.exports = { parser }\n上記の例では、ファイルがロードされるとすぐに多くの作業が実行されます。 解析されたファイルをすぐ取得する必要があるでしょうか。 getParsedFiles() が実際に呼び出されたときに、これを少し後で実行できるでしょうか。
// \"fs\" はすでにロードされている可能性が高いため、この `require()` 呼び出しは軽いです\nconst fs = require('fs')\n\nclass Parser {\n async getFiles () {\n // `getFiles` が呼ばれても、すぐにはディスクに触れません。\n // また、非同期バージョンを使用して\n // 他の操作をブロックしないことを保証します。\n this.files = this.files || await fs.readdir('.')\n\n return this.files\n }\n\n async getParsedFiles () {\n // この架空の foo-parser は大きくて重いモジュールであり\n // 実際にファイルを解析する必要があるまで動作を後回しにします。\n // `require()` にはモジュールキャッシュが付属しているため、\n // この `require()` 呼び出しは 1 回だけ重く、\n // 後続の `getParsedFiles()` 呼び出しはより高速になります。\n const fooParser = require('foo-parser')\n const files = await this.getFiles()\n\n return fooParser.parse(files)\n }\n}\n\n// この操作は、前の例よりもはるかに軽くなりました\nconst parser = new Parser()\n\nmodule.exports = { parser }\n要するに、アプリの起動時にリソースをすべて割り当てるのではなく、\"その時に合わせて\" リソースを割り当てます。
\nElectron のメインプロセス (\"ブラウザプロセス\" と呼ばれることもあります) は特別です。これは、アプリの他のすべてのプロセスの親プロセスであり、オペレーティングシステムが相互作用する一次プロセスです。 ウィンドウ、インタラクション、アプリ内のさまざまなコンポーネント間の通信を処理します。 UI スレッドも保持します。
\nどんな状況でも、このプロセスと UI スレッドを長い実行時間の操作でブロックしてはなりません。 UI スレッドをブロックすると、メインプロセスが処理を続行できる状態になるまで、アプリ全体がフリーズします。
\nメインプロセスとその UI スレッドは、基本的にアプリ内の主要な操作の制御塔です。 オペレーティングシステムがマウスクリックについてアプリに通知すると、そのクリックはウィンドウに到達する前にメインプロセスを通過します。 ウィンドウがぬるぬるした滑らかなアニメーションをレンダリングしている場合、それについて GPU プロセスとやり取りする必要があって―もう一度メインプロセスを通過します。
\nElectron と Chromium は、UI スレッドのブロックを回避するために、新しいスレッドに重いディスク I/O および CPU バウンド操作を配置するよう配慮します。 あなたもおなじようにしましょう。
\nElectron の強力なマルチプロセスアーキテクチャは、長時間実行するタスクを支援する準備ができていますが、少数のパフォーマンストラップも含まれています。
\n1) 長時間実行される CPU 負荷の高いタスクについては、Worker Thread を使用するか、それらを BrowserWindow に移動することを検討するか、(最後の手段として) 専用プロセスを生成します。
\n2) 同期 IPC と remote モジュールの使用はできるだけ避けてください。 正しい使用方法もありますが、remote モジュールを使用して知らないうちに UI スレッドをブロックするのは非常に容易です。
3) メインプロセスでブロックする I/O 操作の使用を避けてください。 要するに、コア Node.js モジュール (fs や child_process など) が同期バージョンと非同期バージョンを提供している場合は、常に非同期および非ブロッキングのものを選択するべきです。
Electron には Chrome の最新バージョンが同梱されているため、Web Platform が提供する最新で最良の機能を利用して、アプリをスムーズかつ応答性の良いように維持する手法で重い操作を後回しまたはオフロードできます。
\nレンダラープロセスで実行する JavaScript が、アプリに多く含まれているのかもしれません。 その仕掛けは、60fps でユーザー入力、アニメーションへの対応、スムーズなスクロールを維持するために、必要なリソースを奪わずに可能な限り迅速に操作を実行することです。
\nレンダラーのコードで操作の流れを調整することは、ユーザーがアプリの \"カクつき\" を時々訴える場合に特に役立ちます。
\n平たく言えば、最新のブラウザー用の高性能ウェブアプリを構築するためのすべてのアドバイスは、Electron のレンダリングにも適用されます。 現在、自由に使える 2 つの主要なツールがあります。小規模な操作用の requestIdleCallback() と、長時間実行する操作用の Web Workers です。
requestIdleCallback() により、開発者は、プロセスがアイドル期間に入るとすぐに実行される関数をキューに入れることができます。 これにより、ユーザーエクスペリエンスに影響を与えることなく、優先度の低い作業やバックグラウンド作業を実行できます。 使用方法の詳細については、MDNのドキュメントを参照してください。
Web Worker は別のスレッドでコードを実行する強力なツールです。 考慮すべき注意点がいくつかあります。注意点については、Electron の マルチスレッドドキュメント および Web Worker の MDN ドキュメント を参照してください。 長時間にわたって大量の CPU パワーを必要とするあらゆる操作に理想的な解決法です。
\nElectron の大きな利点の1つは、JavaScript、HTML、CSS をどのエンジンが解析するかを正確に知っていることです。 ウェブ向けに書かれたコードを再利用する場合は、Electron に含まれている機能を polyfill しないようにしてください。
\n今日のインターネット用のウェブアプリケーションを構築する場合、最も古い環境では、使用できる機能と使用できない機能が決まります。 Electron はパフォーマンスの良い CSS フィルターとアニメーションをサポートしていますが、古いブラウザはそうではないかもしれません。 WebGL を使用できる場合、古いスマートフォンをサポートするために、開発者はそのようなより多くのリソースを必要とする解決方法を選択していた可能性があります。
\nJavaScript に関しては、DOM セレクターのためだけの jQuery や regenerator-runtime のような async/await をサポートするためだけの polyfill ツールキットライブラリを含めることができます。
JavaScript ベースの polyfill が Electron の同等のネイティブ機能よりも高速になることはまれです。 標準ウェブプラットフォームの機能を自作して、Electron アプリの速度を落とさないでください。
\nElectron の現在のバージョンへの ployfill は不要であるという仮定の下で操作します。 疑問がある場合は、caniuse.com を確認し、利用している Electron のバージョンに対応した Chromium のバージョン が必要な機能をサポートしているかどうかを確認してください。
\nさらに、使用するライブラリを注意深く調べてください。 本当に必要なものでしょうか。 たとえば、jQuery は非常に成功したため、その機能の多くが 利用可能な標準 JavaScript 機能セット の一部になりました。
TypeScript などのトランスパイラー/コンパイラを使用している場合は、その構成を調べて、Electron でサポートされている最新の ECMAScript バージョンをターゲットにしていることを確認してください。
\nめったに変更されないリソースをアプリケーションへ簡単にバンドルできる場合は、インターネットから取得しないでください。
\nElectron の多くのユーザーは、デスクトップアプリケーションになりつつある完全にウェブベースのアプリから始めます。 ウェブ開発者として、さまざまなコンテンツ配信ネットワークからリソースをロードすることには慣れています。 今、あなたは適切なデスクトップアプリケーションを頒布しているのですから、可能な限り「ネットを切り捨てる」ようにして、決して変更されずアプリへ簡単に同梱できそうなリソースのためにユーザーを待たせないようにしましょう。
\nGoogle Fonts は典型例です。 多くの開発者は、コンテンツ配信ネットワークに付属する Google の印象的な無料フォントのコレクションを利用しています。 行程は簡単です。CSS に数行を含めると、Google が残りを処理します。
\nElectron アプリを作成するとき、フォントをダウンロードしてアプリのバンドルに含めると、ユーザーの体感が向上します。
\n理想的な世界では、アプリケーションが動作するためにはネットワークをまったく必要としません。 そこに到達するには、アプリが何をダウンロードしていてどのくらい大きいリソースなのかを理解する必要があります。
\nそのためには、デベロッパーツールを開きます。 Network タブに移動し、Disable cache オプションにチェックを入れます。 そして、レンダラーをリロードします。 アプリでこのようなリロードが禁止されていない限り、通常、開発者ツールにフォーカスを置いて Cmd + R または Ctrl + R を押すと、リロードを発生させられます。
これでこのツールはすべてのネットワーク要求を綿密に記録します。 最初のパスでは、ダウンロードされるすべてのリソースの在庫を確認し、最初に大きなファイルに注目します。 変更されず、バンドルに含めることができるような画像、フォント、メディアファイルはあるでしょうか。 もしあれば、同梱しましょう。
\n次のステップとして、Network Throttling を有効にします。 現在 Online と表示されているドロップダウンを見つけて、Fast 3G などの低速なものを選択します。 レンダラーをリロードし、アプリが不必要に待機しているリソースがあるかどうかを確認します。 アプリは多くの場合、実際に関連するリソースを必要としないにもかかわらず、ネットワークリクエストが完了するのを待っています。
豆知識として、アプリケーションの更新を公開するのではなくインターネットから変更したいリソースをロードすることも強力な戦略です。 リソースのロード方法を高度に制御するには、Service Worker への注力を検討してください。
\n\"あまりに早いコードのロードと実行\" で既に指摘したように、require() の呼び出しはコストのかかる操作です。 可能であれば、アプリケーションのコードを単一のファイルにバンドルしましょう。
最新の JavaScript 開発には通常、多くのファイルとモジュールが含まれます。 Electron での開発にはこれで十分ですが、アプリケーションをロードするときに require() の呼び出しに含まれるオーバーヘッドが一度だけ支払われるように、すべてのコードを1つのファイルにバンドルすることを強く推奨します。
多数の JavaScript バンドルが存在しますが、あるツールを別のツールよりも推奨してコミュニティを怒らせるよりも、良い方法が知られています。 ただし、Node.js 環境とブラウザ環境の両方を処理する必要がある Electron 独自の環境を処理できるバンドラーを使用することを推奨します。
\nこの記事を書いている時点での一般的な選択肢には、Webpack、Parcel、および rollup.js があります。
", "title": "パフォーマンス", "description": "" }, "/docs/api/structures/point": { "locale": "ja-JP", "slug": "point", "href": "/docs/api/structures/point", "crowdinFileId": "256475", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/point.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "x Numbery NumberNote: Both x and y must be whole integers, when providing a point object as input to an Electron API we will automatically round your x and y values to the nearest whole integer.
data (UploadRawData | UploadFile)[] - The post data to be sent to the new window.contentType String - The content-type header used for the data. One of application/x-www-form-urlencoded or multipart/form-data. Corresponds to the enctype attribute of the submitted HTML form.boundary String (optional) - The boundary used to separate multiple parts of the message. Only valid when contentType is multipart/form-data.Note that keys starting with -- are not currently supported. For example, this will errantly submit as multipart/form-data when nativeWindowOpen is set to false in webPreferences:
<form\n target=\"_blank\"\n method=\"POST\"\n enctype=\"application/x-www-form-urlencoded\"\n action=\"https://postman-echo.com/post\"\n>\n <input type=\"text\" name=\"--theKey\">\n <input type=\"submit\">\n</form>\n\n\n電源の状態の変化をモニターします。
\n
プロセス: Main
\npowerMonitor モジュールでは以下のイベントが発生します。
システムがサスペンドするときに発生します。
\nシステムが再開するときに発生します。
\nシステムが AC 電源に切り替わったときに発生します。
\nシステムがバッテリー電源に切り替わったときに発生します。
\nシステムが再起動またはシャットダウンしようとしているときに発生します。 イベントハンドラが e.preventDefault() を呼び出した場合、Electron は正常にアプリを終了するためにシステムのシャットダウンの遅延を試みます。 e.preventDefault() が呼ばれた場合、出来る限り app.quit() のようなものを呼ぶのと同じようにアプリを終了します。
システムがスクリーンをロックしようとしているときに発生します。
\nシステムスクリーンがアンロックされたときに発行されます。
\nログインセッションがアクティブになったときに発生します。 詳細は ドキュメント をご参照ください。
\nログインセッションが非アクティブになったときに発生します。 詳細は ドキュメント をご参照ください。
\npowerMonitor モジュールには以下のメソッドがあります。
powerMonitor.getSystemIdleState(idleThreshold)idleThreshold Integer戻り値 String - 現在のシステムの状態。 active 、 idle 、 locked 、 unknown のいずれか。
システムのアイドル状態を計算します。 idleThreshold は、アイドルとみなされるまでの時間 (秒) です。 locked はサポートされたシステムでのみ利用可能です。
powerMonitor.getSystemIdleTime()戻り値 Integer - アイドル状態の秒数
システムのアイドル時間を計算します。
\npowerMonitor.isOnBatteryPower()戻り値 Boolean - システムがバッテリー電源状態かどうか。
このプロパティの変更を監視するには、on-battery および on-ac イベントを使用します。
powerMonitor.onBatteryPowerBoolean 型のプロパティです。 システムがバッテリー電源状態ならば true です。
powerMonitor.isOnBatteryPower() をご参照ください。
\n\nシステムが省電力 (スリープ) モードに入るのを防ぎます。
\n
プロセス: Main
\n以下がその例です。
\nconst { powerSaveBlocker } = require('electron')\n\nconst id = powerSaveBlocker.start('prevent-display-sleep')\nconsole.log(powerSaveBlocker.isStarted(id))\n\npowerSaveBlocker.stop(id)\npowerSaveBlocker モジュールには以下のメソッドがあります。
powerSaveBlocker.start(type)type String - パワーセーブブロッカーの種類。prevent-app-suspension - アプリケーションが休止状態に入るのを防ぎます。 システムをアクティブに保ちますが、スクリーンは電源をオフにできます。 使用例: ファイルのダウンロードや音楽の再生。prevent-display-sleep - ディスプレイがスリープ状態に入るのを防ぎます。 システムとスクリーンをアクティブに保ちます。 使用例: 映像の再生。戻り値 Integer - この powerSaveBlocker に割り当てられたブロッカー ID.
システムが低電力モードに入るのを防ぎます。 パワーセーブブロッカーを識別する整数を返します。
\n注釈: prevent-display-sleep は prevent-app-suspension よりも高い優先順位を持ちます。 最も高い優先順位のタイプのみが有効になります。 つまり、prevent-display-sleep は prevent-app-suspension よりも常に優先されます。
たとえば、A が呼び出した API は prevent-app-suspension を要求し、もう1つの B の呼び出しは prevent-display-sleep を要求したとします。 B が要求を停止するまで、prevent-display-sleep が使用されます。 その後、prevent-app-suspension が使用されます。
powerSaveBlocker.stop(id)id Integer - powerSaveBlocker.start で返された powerSaveBlocker の ID。指定した powerSaveBlocker を停止します。
\npowerSaveBlocker.isStarted(id)id Integer - powerSaveBlocker.start で返された powerSaveBlocker の ID。戻り値 Boolean - 対応する powerSaveBlocker が開始されているかどうか。
name String - the name of the printer as understood by the OS.displayName String - the name of the printer as shown in Print Preview.description String - a longer description of the printer's type.status Number - the current status of the printer.isDefault Boolean - whether or not a given printer is set as the default printer on the OS.options Object - an object containing a variable number of platform-specific printer information.The number represented by status means different things on different platforms: on Windows its potential values can be found here, and on Linux and macOS they can be found here.
Below is an example of some of the additional options that may be set which may be different on each platform.
\n{\n name: 'Austin_4th_Floor_Printer___C02XK13BJHD4',\n displayName: 'Austin 4th Floor Printer @ C02XK13BJHD4',\n description: 'TOSHIBA ColorMFP',\n status: 3,\n isDefault: false,\n options: {\n copies: '1',\n 'device-uri': 'dnssd://Austin%204th%20Floor%20Printer%20%40%20C02XK13BJHD4._ipps._tcp.local./?uuid=71687f1e-1147-3274-6674-22de61b110bd',\n finishings: '3',\n 'job-cancel-after': '10800',\n 'job-hold-until': 'no-hold',\n 'job-priority': '50',\n 'job-sheets': 'none,none',\n 'marker-change-time': '0',\n 'number-up': '1',\n 'printer-commands': 'ReportLevels,PrintSelfTestPage,com.toshiba.ColourProfiles.update,com.toshiba.EFiling.update,com.toshiba.EFiling.checkPassword',\n 'printer-info': 'Austin 4th Floor Printer @ C02XK13BJHD4',\n 'printer-is-accepting-jobs': 'true',\n 'printer-is-shared': 'false',\n 'printer-is-temporary': 'false',\n 'printer-location': '',\n 'printer-make-and-model': 'TOSHIBA ColorMFP',\n 'printer-state': '3',\n 'printer-state-change-time': '1573472937',\n 'printer-state-reasons': 'offline-report,com.toshiba.snmp.failed',\n 'printer-type': '10531038',\n 'printer-uri-supported': 'ipp://localhost/printers/Austin_4th_Floor_Printer___C02XK13BJHD4',\n system_driverinfo: 'T'\n }\n}\n\n\n\nprocess オブジェクトの拡張です。
\n
Electron の process オブジェクトは、Node.js process object から拡張されています。 以下のイベント、プロパティ、メソッドが追加されます。
サンドボックス化されたレンダラーでは、process オブジェクトには以下に示す一部の API のみが含まれます。
crash()hang()getCreationTime()getHeapStatistics()getBlinkMemoryInfo()getProcessMemoryInfo()getSystemMemoryInfo()getSystemVersion()getCPUUsage()getIOCounters()uptime()argvexecPathenvpidarchplatformsandboxedcontextIsolatedtypeversionversionsmaswindowsStorecontextIdElectron が内部初期化スクリプトをロードし、ウェブページまたはメインスクリプトのロードを開始したときに発生します。
\nprocess.defaultApp 読み出し専用Boolean。 デフォルトアプリに、引数として渡されてアプリが起動されると、このプロパティはメインプロセス内で true になります。それ以外では undefined です。
process.isMainFrame 読み出し専用Booleanで、現在のレンダラーコンテキストが\"main\"レンダラー フレームの場合true。 現在のフレームの ID が必要な場合、webFrame.routingId を使用すべきです。
process.mas 読み出し専用Boolean。 Mac App Store ビルドの場合、このプロパティは true、他のビルドでは undefined です。
process.noAsarアプリケーション内の ASAR サポートを制御する Boolean 。 これをtrueに設定した場合、Nodeのビルトインモジュールのasarアーカイブのサポートが無効になります。
process.noDeprecation非推奨の警告が stderr へ出力されるかどうかを制御する Boolean。 これを true に設定すると非推奨の警告が無効になります。 --no-deprecation コマンドラインフラグの代わりにこのプロパティを使用します。
process.resourcesPath 読み出し専用リソースディレクトリのパスを表す String。
process.sandboxed 読み出し専用Boolean。 レンダラープロセスがサンドボックス化されている場合、このプロパティは true です。それ以外の場合は undefined です。
process.contextIsolated 読み出し専用Boolean 型で、現在のレンダラーコンテキストで contextIsolation が有効かどうかを示します。 これはメインプロセスでは undefined です。
process.throwDeprecation非推奨の警告が例外としてスローされるかどうかを制御する Boolean。 これを true に設定すると非推奨のエラーがスローされます。 --throw-deprecation コマンドラインフラグの代わりにこのプロパティを使用します。
process.traceDeprecationstderr に出力される非推奨にスタックトレースを含めるかどうかを制御する Boolean。 これを true に設定すると非推奨のスタックトレースが出力されます。 --trace-deprecation コマンドラインフラグの代わりにこのプロパティを使用します。
process.traceProcessWarningsstderr に出力されるプロセスの警告にスタックトレースを含めるかどうかを制御する Boolean。 これを true に設定するとプロセスの (非推奨を含む) 警告のスタックトレースが出力されます。 --trace-warnings コマンドラインフラグの代わりにこのプロパティを使用します。
process.type 読み出し専用現在のプロセスの種別を表す以下の String のいずれかになります。
browser - メインプロセスrenderer - レンダラープロセスworker - ウェブワーカーprocess.versions.chrome 読み出し専用Chrome のバージョン文字列を表す String。
process.versions.electron 読み出し専用Electron のバージョン文字列を表す String。
process.windowsStore 読み出し専用Boolean。 アプリが Windows Store アプリ (appx) として実行されている場合、このプロパティは true です。それ以外の場合は undefined です。
process.contextId 読み出し専用String 型 (任意) で、現在の JavaScript コンテキストにおけるグローバルな一意の ID を表します。 各フレームにはそれぞれ JavaScript コンテキストがあります。 contextIsolation が有効な場合、隔離ワールドにも個別の JavaScript コンテキストがあります。 このプロパティはレンダラープロセスでのみ利用可能です。
process オブジェクトには以下のメソッドがあります。
process.crash()現在のプロセスのメインスレッドでクラッシュを発生させます。
\nprocess.getCreationTime()戻り値 Number | null - 発生からのミリ秒数です。情報が利用できない場合は null を返します。
アプリケーションの作成時間を示します。 時間はエポックからのミリ秒数として表されます。 プロセスの作成時間を取得できない場合は null を返します。
\nprocess.getCPUUsage()戻り値 CPUUsage
process.getIOCounters() Windows Linux戻り値 IOCounters
process.getHeapStatistics()戻り値 Object:
totalHeapSize IntegertotalHeapSizeExecutable IntegertotalPhysicalSize IntegertotalAvailableSize IntegerusedHeapSize IntegerheapSizeLimit IntegermallocedMemory IntegerpeakMallocedMemory IntegerdoesZapGarbage BooleanV8ヒープの統計を持つオブジェクトを返します。 すべての統計情報はキロバイト単位で返ってくることに注意してください。
\nprocess.getBlinkMemoryInfo()戻り値 Object:
allocated Integer - キロバイト単位でのすべての確保されたオブジェクトのサイズ。marked Integer - キロバイト単位でのマークされたすべてのオブジェクトのサイズ。total Integer - キロバイト単位での確保された空間の合計。Blink のメモリ情報を持つオブジェクトを返します。 レンダリング/DOM 関連のメモリ問題のデバッグに役立ちます。 すべての数値はキロバイト単位で返ってくることに注意してください。
\nprocess.getProcessMemoryInfo()戻り値 Promise<ProcessMemoryInfo> - ProcessMemoryInfo で実行されます
現在のプロセスについてのメモリ使用量の統計情報を与えるオブジェクトを返します。 すべての統計情報はキロバイト単位で返ってくることに注意してください。 このAPIはアプリの準備ができた後に呼び出されるべきです。
\nChromium は macOS には residentSet の値を提供しません。 これは直近の使用されていないページを macOS がメモリ内で圧縮するためです。 結果として、residentSet の値は期待されるものではありません。 private メモリは、macOS でのプロセスの実際の圧縮前のメモリ使用量をよりよく表しています。
process.getSystemMemoryInfo()戻り値 Object:
total Integer - システムで利用可能な物理メモリの合計量 (キロバイト)。free Integer - アプリケーションまたはディスクキャッシュで使用されていないメモリの合計量。swapTotal Integer Windows Linux - システムが使用できるスワップメモリの合計量 (キロバイト) 。swapFree Integer Windows Linux - システムが使用できるスワップメモリの空き容量 (キロバイト)。システム全体についてのメモリ使用量の統計情報を与えるオブジェクトを返します。 すべての統計情報はキロバイト単位で返ってくることに注意してください。
\nprocess.getSystemVersion()戻り値 String - ホストのオペレーティングシステムのバージョン。
サンプル:
\nconst version = process.getSystemVersion()\nconsole.log(version)\n// macOS -> '10.13.6'\n// Windows -> '10.0.17763'\n// Linux -> '4.15.0-45-generic'\n注釈: os.release() とは異なり、macOS ではカーネルバージョンではなく実際のオペレーティングシステムのバージョンを返します。
process.takeHeapSnapshot(filePath)filePath String - 出力ファイルのパス戻り値 Boolean - スナップショットの作成が成功したかどうかを示します。
V8 ヒープのスナップショットを撮り、それを filePath に保存します。
process.hang()現在のプロセスのメインスレッドでハングを発生させます。
\nprocess.setFdLimit(maxDescriptors) macOS LinuxmaxDescriptors Integerファイルディスクリプタのソフトリミットを、maxDescriptors または OS のハードリミットの、いずれか低い方に設定します。
residentSet Integer Linux Windows - The amount of memory currently pinned to actual physical RAM in Kilobytes.private Integer - The amount of memory not shared by other processes, such as JS heap or HTML content in Kilobytes.shared Integer - The amount of memory shared between processes, typically memory consumed by the Electron code itself in Kilobytes.pid Integer - Process id of the process.type String - プロセスの種別。 以下の値のいずれかです。BrowserTabUtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownserviceName String (任意) - そのプロセスのローカライズされていない名前。name String (任意) - そのプロセスの名前。 ユーティリティの例: Audio Service, Content Decryption Module Service, Network Service, Video Captureなどcpu CPUUsage - CPU usage of the process.creationTime Number - Creation time for this process. The time is represented as number of milliseconds since epoch. Since the pid can be reused after a process dies, it is useful to use both the pid and the creationTime to uniquely identify a process.memory MemoryInfo - Memory information for the process.sandboxed Boolean (optional) macOS Windows - Whether the process is sandboxed on OS level.integrityLevel String (optional) Windows - One of the following values:untrustedlowmediumhighunknownElectron は Chromium のマルチプロセスアーキテクチャを継承しており、フレームワークのアーキテクチャは最新のウェブブラウザに酷似しています。 このガイドでは、最小限の クイックスタートアプリ で適用した、Electron の概念的な知識を解説します。
\nウェブブラウザは非常に複雑なアプリケーションです。 ウェブコンテンツを表示するという主な機能のほかに、複数のウィンドウ (またはタブ) を管理したり、サードパーティの拡張機能を読み込んだりするなど、多くの副次的な役割を担っています。
\n以前のブラウザでは、これらの機能を単一のプロセスで実現していました。 このやり方は開いているタブごとのオーバーヘッドを減らしますが、1 つのウェブサイトがクラッシュしたりハングアップしたりすると、ブラウザ全体に影響が及びます。
\nこの問題を解決するため、Chrome チームは各タブがそれぞれのプロセスで描画するようにすると決め、ウェブページ上のバグや悪意のあるコードがアプリ全体に与える影響を制限することにしました。 単一のブラウザプロセスはこれらのプロセスを制御し、アプリケーションのライフサイクル全体を制御します。 このモデルを視覚化したのが、Chrome 漫画本 の以下の図です。
\n
Electron アプリケーションも非常によく似た構造をしています。 Electron アプリ開発者の場合、メインとレンダラーの 2 種類のプロセスを制御します。 これらは、上述の Chrome 独自のブラウザプロセスとレンダラープロセスと似ています。
\n各 Electron アプリにつき一つのメインプロセスがあります。これはアプリケーションのエントリポイントとして機能します。 メインプロセスは Node.js 環境で動作します。つまり、モジュールを require したり Node.js のすべての API を利用したりできます。
メインプロセスの主な目的は、BrowserWindow モジュールを使ってアプリケーションウインドウを作成し管理することです。
BrowserWindow クラスの各インスタンスは、アプリケーションウインドウを作成し、その分かれたレンダラープロセス内でウェブページを読み込みます。 メインプロセスからは、ウインドウの webContents オブジェクトでこのウェブコンテンツを操作できます。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\n\n\n注意:
\nBrowserViewモジュールなどの ウェブ埋め込み 用のレンダラープロセスが作成されることもあります。webContentsオブジェクトは、埋め込みウェブコンテンツにもアクセスできます。
BrowserWindow モジュールは EventEmitter を継承しているため、様々なユーザーイベント (例えば、ウインドウの最小化や最大化) ハンドラの追加もできます。
BrowserWindow インスタンスが破棄されると、対応するレンダラープロセスも終了します。
メインプロセスは、Electron の app モジュールを介してアプリケーションのライフサイクルも制御します。 このモジュールには、アプリケーションの動作をカスタマイズするためのイベントやメソッドが多数用意されています (例えば、プログラム側でアプリケーションを終了したり、アプリケーションの Dock を変更したり、アプリについてのパネルを表示したりできます)。
実例として、クイックスタートガイド で紹介されているアプリでは app の API でよりネイティブなアプリケーションウインドウの体験を実現しています。
// 非 macOS プラットフォームでウインドウが開かれていない時にアプリを終了する\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nウェブコンテンツ用の Chromium ラッパーだけでなく Electron の機能を拡張するため、メインプロセスではユーザーのオペレーティングシステムと対話するカスタム API も追加しています。 Electron は、メニュー、ダイアログ、tray アイコンなど、ネイティブなデスクトップ機能を制御する様々なモジュールを公開しています。
\nElectron のメインプロセスのモジュール一覧は、API ドキュメントをご覧ください。
\n各 Electron アプリは、開いている BrowserWindow (及び各ウェブ埋め込み) ごとに個別のレンダラープロセスを生成します。 その名の通り、レンダラーはウェブコンテンツの レンダリング を担います。 あらゆる意図と目的において、レンダラープロセスで実行するコードは (少なくとも Chromium がそうである限り) ウェブ標準に従って動作しなければなりません。
そのため、あるブラウザウインドウ内のすべてのユーザーインターフェイスとアプリの機能は、ウェブの場合と同じツールとパラダイムで記述する必要があります。
\n全ウェブ仕様の説明はこのガイドの範疇の外ですが、最低限理解しておくべきことは以下の通りでしょう。
\n<script> 要素で追加できます。さらにこれは、レンダラーが require やその他 Node.js の API に直接アクセスできないことも意味します。 NPM モジュールをレンダラーに直接組み込むには、ウェブの場合と同じバンドラーツールチェイン (例えば、webpack や parcel など) を使用する必要があります。
\n\n注意: 開発を容易にするために、レンダラープロセスを完全な Node.js 環境で生成できます。 歴史的には、これがデフォルトでしたが、セキュリティ上の理由からこの機能は無効になりました。
\n
ここで、レンダラープロセスのユーザーインターフェイスが Node.js や Electron のネイティブデスクトップ機能にアクセスできずメインプロセスからのみできるのであれば、どのように協調して動作するのかと疑問に思うでしょう。 実際、Electron のコンテンツスクリプトを直接インポートする方法はありません。
\nプリロードスクリプトは、BrowserWindow コンストラクタの webPreferences オプションでメインプロセスからアタッチできます。
const { BrowserWindow } = require('electron')\n//...\nconst win = new BrowserWindow({\n webPreferences: {\n preload: 'path/to/preload.js'\n }\n})\n//...\nプリロードスクリプトは、グローバルな Window インターフェイスをレンダラーと共有し Node.js の API にアクセスすることができます。そのため、window グローバルに任意の API を公開してウェブコンテンツが利用できるようにすることで、レンダラーを強化する役割を果たしています。
プリロードスクリプトはアタッチされているレンダラーと window グローバルを共有しますが、contextIsolation のデフォルト値によりプリロードスクリプトの変数は window に直接アタッチできません。
window.myAPI = {\n desktop: true\n}\nconsole.log(window.myAPI)\n// => undefined\nコンテキスト分離 (contextIsolation) とは、プリロードスクリプトをレンダラーのメインワールドから分離し、特権的 API がウェブコンテンツのコードへ漏れないようにすることです。
\nこれを代わりに安全に実現するには、以下のように contextBridge モジュールを使用します。
const { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n desktop: true\n})\nconsole.log(window.myAPI)\n// => { desktop: true }\nこの機能は、主に以下に挙げる 2 つの目的において非常に便利です。
\nipcRenderer ヘルパーをレンダラーに公開することで、プロセス間通信 (IPC) を利用してレンダラーからメインプロセスのタスクを作動できます (その逆も可能)。window グローバルにカスタムプロパティを追加することで、ウェブクライアント側でデスクトップ専用のロジックを利用できます。productIdentifier String - The string that identifies the product to the Apple App Store.localizedDescription String - A description of the product.localizedTitle String - The name of the product.contentVersion String - A string that identifies the version of the content.contentLengths Number[] - The total size of the content, in bytes.price Number - The cost of the product in the local currency.formattedPrice String - The locale formatted price of the product.currencyCode String - 3 character code presenting a product's currency based on the ISO 4217 standard.isDownloadable Boolean - A Boolean value that indicates whether the App Store has downloadable content for this product. true if at least one file has been associated with the product.プログレスバーは、ユーザーがウィンドウの切り替え操作をすることなくユーザーに進捗情報を提供できます。
\nWindows では、タスクバーのボタンにプログレスバーを表示できます。
\n![Windows プログレスバー][https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png\\]
\nmacOS では、Dock のアイコンの一部としてプログレスバーを表示します。
\n
Linux では、Unity のグラフィカルインターフェイスにも同様の機能があり、ランチャー内でプログレスバーを指定できます。
\n
\n\n注意: Windows では各ウィンドウごとにプログレスバーを保有できますが、macOS と Linux (Unity) ではアプリケーションのプログレスバーが 1 つだけです。
\n
setProgressBar() メソッドは、BrowserWindow のインスタンスから利用できます。 進捗状況を示すには、0 から 1 の間の数でこのメソッドを呼び出します。 例えば、現在完了までの進捗率が 63% に達している長期のタスクがある場合、setProgressBar(0.63) のように呼び出します。
引数を負の値 (例: -1) にすると、プログレスバーが取り除かれます。 1 より大きい値にすると、Windows では不定のプログレスバーが表示され、他のオペレーティングシステムでは 100% に切り詰められます。 不定のプログレスバーはアクティブな状態を維持しますが、実際のパーセンテージは表示されません。これは、操作が完了するまでの時間がわからない場合に使用します。
より多くのオプションやモードについては API ドキュメント を参照してください。
\nこの例では、Node.js のタイマーを使って時間経過で増えるプログレスバーをメインウインドウに追加しています。
\n![https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png\\](\"https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png%5C\"){kind=link}
const { app, BrowserWindow } = require('electron')\n\nlet progressInterval\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n\n const INCREMENT = 0.03\n const INTERVAL_DELAY = 100 // ms\n\n let c = 0\n progressInterval = setInterval(() => {\n // プログレスバーを次の値へと更新する\n // 0 から 1 の値は進捗状況を示し、1 より大きい値は不定または 100% で留まります。\n win.setProgressBar(c)\n\n // プログレスバーの増加またはリセット\n if (c < 2) c += INCREMENT\n else c = 0\n }, INTERVAL_DELAY)\n}\n\napp.whenReady().then(createWindow)\n\n// アプリが終了される前に、両方のタイマーを消去\napp.on('before-quit', () => {\n clearInterval(progressInterval)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nElectron アプリケーションを起動すると、Dock (macOS) またはタスクバー (Windows、Unity) にプログレスバーが表示され、0 から始まり 100% で完了します。 その後、不定の表示 (Windows) や 100% で留まった表示 (他のオペレーティングシステム) が短時間表示され、ループします。
\n
macOS の場合、Mission Control の使用中でもアプリケーションのプログレスバーが表示されます。
\n
\n\nカスタムプロトコルを登録し、既存のプロトコルリクエストを傍受します。
\n
プロセス: Main
\nfile:// プロトコルと同じ効果を持つプロトコルの実装の例:
const { app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n})\n注釈: 指定されていないすべてのメソッドは、app モジュールの ready イベントが発生した後にのみ使用できます。
protocol をカスタムの partition や session で使用するプロトコルは特定の Electron session オブジェクトに登録されます。 セッションを指定しない場合は、Electron が使用するデフォルトセッションに protocol が適用されます。 ただし、browserWindow の webPreferences に partition または session を定義すると、そのウィンドウに electron.protocol.XXX を使用しただけでは別のセッションやカスタムプロトコルは機能しません。
カスタムプロトコルをカスタムセッションと組み合わせて機能させるには、それを明示的にそのセッションに登録する必要があります。
\nconst { session, app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const partition = 'persist:example'\n const ses = session.fromPartition(partition)\n\n ses.protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n\n mainWindow = new BrowserWindow({ webPreferences: { partition } })\n})\nprotocol モジュールには以下のメソッドがあります。
protocol.registerSchemesAsPrivileged(customSchemes)customSchemes CustomScheme[]注意: このメソッドは、app モジュールの ready イベントが発行される前にのみ使用でき、一度だけ呼び出すことができます。
scheme を標準の安全なものとして登録し、リソースに対するコンテンツセキュリティポリシーをバイパスし、ServiceWorker を登録し、fetch API と video/audioのストリーミングをサポートします。 機能を有効にするには、true の値で特権を指定します。
以下はコンテンツセキュリティポリシーをバイパスする特権スキームを登録する例です。
\nconst { protocol } = require('electron')\nprotocol.registerSchemesAsPrivileged([\n { scheme: 'foo', privileges: { bypassCSP: true } }\n])\n標準スキームは、RFC 3986 で Generic URI Syntax と呼ぶものに準拠しています。 例えば http と https は標準スキームですが、file はそうではありません。
スキームを標準として登録することにより、サービスが提供されるときに相対的および絶対的なリソースが正しく解決されます。 そうでないと、スキームは file プロトコルのように動作しますが、相対 URL を解決することはできません。
たとえば、標準スキームとして登録せずにカスタムプロトコルで以下のページをロードすると、非標準スキームが相対URLを認識できないため、イメージはロードされません。
\n<body>\n <img src='test.png'>\n</body>\nスキームを標準で登録すると、FileSystem API を介してファイルにアクセスできます。 そうしない場合、レンダラーはスキームのセキュリティエラーをスローします。
\nデフォルトの非標準スキームでは、ウェブストレージ API (localStorage、sessionStorage、webSQL、indexedDB、クッキー) が無効にされます。 そのため、一般的に、カスタムプロトコルを登録して http プロトコルを置き換える場合は、標準のスキームとして登録する必要があります。
(http やストリームプロトコルなどの、) ストリームを使用するプロトコルは、 stream: true を設定する必要があります。 <video> と <audio> HTML 要素はプロトコルがデフォルトで レスポンスをバッファすることを期待します。 stream フラグは、ストリーミング応答を期待する これらの要素を正しく設定します。
protocol.registerFileProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)戻り値 Boolean - protocol が正常に登録されたかどうか
ファイルをレスポンスとして送信する scheme のプロトコルを登録します。 handler は request と callback で呼び出されます。この request は scheme の接続リクエストです。
request を処理するには、callback を、ファイルのパスまたは path プロパティを持つオブジェクトのいずれかを使用して、例えば、callback(filePath) や callback({ path: filePath }) で呼び出す必要があります。 filePath は絶対パスでなければなりません。
デフォルトでは、scheme は http: のように扱われます。これは、file: のような \"Generic URI Syntax\" に従うプロトコルとは違った解析がなされます。
protocol.registerBufferProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)戻り値 Boolean - protocol が正常に登録されたかどうか
Buffer をレスポンスとして送信する scheme のプロトコルを登録します。
使い方は registerFileProtocol と同じですが、 callback を、Buffer オブジェクトか data プロパティを持つオブジェクトで呼び出す必要があります。
サンプル:
\nprotocol.registerBufferProtocol('atom', (request, callback) => {\n callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })\n})\nprotocol.registerStringProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)戻り値 Boolean - protocol が正常に登録されたかどうか
String をレスポンスとして送信する scheme のプロトコルを登録します。
使い方は registerFileProtocol と同じですが、 callback を、String か data プロパティを持つオブジェクトで呼び出す必要があります。
protocol.registerHttpProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse ProtocolResponse戻り値 Boolean - protocol が正常に登録されたかどうか
HTTP リクエストをレスポンスとして送信する scheme のプロトコルを登録します。
使い方は registerFileProtocol と同じですが、 callback を、url プロパティを持つオブジェクトで呼び出す必要があります。
protocol.registerStreamProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)戻り値 Boolean - protocol が正常に登録されたかどうか
ストリームをレスポンスとして送信する scheme のプロトコルを登録します。
使い方は registerFileProtocol と同じですが、 callback を、ReadableStream オブジェクトか data プロパティを持つオブジェクトで呼び出す必要があります。
サンプル:
\nconst { protocol } = require('electron')\nconst { PassThrough } = require('stream')\n\nfunction createStream (text) {\n const rv = new PassThrough() // PassThrough も ReadableStream の一種\n rv.push(text)\n rv.push(null)\n return rv\n}\n\nprotocol.registerStreamProtocol('atom', (request, callback) => {\n callback({\n statusCode: 200,\n headers: {\n 'content-type': 'text/html'\n },\n data: createStream('<h5>Response</h5>')\n })\n})\nReadable ストリーム API (data / end / error イベントが発生するもの) を実装するオブジェクトを渡すことが可能です。 例として、ファイルを返す方法を以下に示します。
protocol.registerStreamProtocol('atom', (request, callback) => {\n callback(fs.createReadStream('index.html'))\n})\nprotocol.unregisterProtocol(scheme)scheme String戻り値 Boolean - protocol が正常に登録解除されたかどうか
scheme のカスタムプロトコルを登録解除します。
protocol.isProtocolRegistered(scheme)scheme String戻り値 Boolean - scheme がすでに登録されているかどうか。
protocol.interceptFileProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)戻り値 Boolean - protocol が正常に割り込みされたかどうか
scheme プロトコルを傍受し、ファイルをレスポンスとして送信するプロトコルの新しいハンドラとして handler を使用します。
protocol.interceptStringProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)戻り値 Boolean - protocol が正常に割り込みされたかどうか
scheme プロトコルを傍受し、String をレスポンスとして送信するプロトコルの新しいハンドラとして handler を使用します。
protocol.interceptBufferProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)戻り値 Boolean - protocol が正常に割り込みされたかどうか
scheme プロトコルを傍受し、Buffer をレスポンスとして送信するプロトコルの新しいハンドラとして handler を使用します。
protocol.interceptHttpProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse ProtocolResponse戻り値 Boolean - protocol が正常に割り込みされたかどうか
scheme プロトコルを傍受し、新しい HTTP リクエストをレスポンスとして送信するプロトコルの新しいハンドラとして handler を使用します。
protocol.interceptStreamProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)戻り値 Boolean - protocol が正常に割り込みされたかどうか
protocol.registerStreamProtocol と同じですが、既存のプロトコルハンドラを置き換える点が異なります。
protocol.uninterceptProtocol(scheme)scheme String戻り値 Boolean - protocol が正常に割り込み解除されたかどうか
scheme のためにインストールされた傍受するハンドラを削除し、元のハンドラを復元します。
protocol.isProtocolIntercepted(scheme)scheme String戻り値 Boolean - scheme がすでにインターセプトされているかどうか。
url Stringreferrer Stringmethod StringuploadData UploadData[] (optional)headers Record<String, String>error Integer (optional) - When assigned, the request will fail with the error number . For the available error numbers you can use, please see the net error list.statusCode Number (optional) - The HTTP response code, default is 200.charset String (optional) - The charset of response body, default is \"utf-8\".mimeType String (optional) - The MIME type of response body, default is \"text/html\". Setting mimeType would implicitly set the content-type header in response, but if content-type is already set in headers, the mimeType would be ignored.headers Record<string, string | string[]> (optional) - An object containing the response headers. The keys must be String, and values must be either String or Array of String.data (Buffer | String | ReadableStream) (optional) - The response body. When returning stream as response, this is a Node.js readable stream representing the response body. When returning Buffer as response, this is a Buffer. When returning String as response, this is a String. This is ignored for other types of responses.path String (optional) - Path to the file which would be sent as response body. This is only used for file responses.url String (optional) - Download the url and pipe the result as response body. This is only used for URL responses.referrer String (optional) - The referrer URL. This is only used for file and URL responses.method String (optional) - The HTTP method. This is only used for file and URL responses.session Session (optional) - The session used for requesting URL, by default the HTTP request will reuse the current session. Setting session to null would use a random independent session. This is only used for URL responses.uploadData ProtocolResponseUploadData (optional) - The data used as upload data. This is only used for URL responses when method is \"POST\".contentType String - MIME type of the content.data String | Buffer - Content to be sent.GitHub でプロジェクトをフォークし、ローカルでフォークをクローンします。
\n$ git clone git@github.com:username/electron.git\n$ cd electron\n$ git remote add upstream https://github.com/electron/electron.git\n$ git fetch upstream\nビルド手順と依存関係は、オペレーティングシステムによって若干異なります。 Electron をローカルに構築する際は、これらの詳細なガイドを参照してください。
\n\nプロジェクトをローカルに構築したら、変更を始める準備が整います！
\n開発環境を整理しておくために、作業を支えるローカルのブランチを作りましょう。 これらは、main ブランチから直接分岐する必要があります。
$ git checkout -b my-branch -t upstream/main\nelectron/electron リポジトリに対して開かれたほとんどのプルリクエストには、shell/ フォルダの C/C++ コード、lib/ フォルダの JavaScript コード、docs/api/ のドキュメント、spec/ フォルダのテストの変更が含まれます。
コードの変更時に npm run lint を実行して、プロジェクトのコードスタイルに従うようにしてください。
プロジェクトのさまざまな部分でコードを変更する際のベストプラクティスの詳細については、コーディングスタイル を参照してください。
\n変更を個々のコミット内で論理的にグループ化しておくことを推奨します。 コントリビューターの多くが、複数のコミットに分割された変更をより簡単に確認できます。 プルリクエストのコミット数に制限はありません。
\n$ git add my/changed/files\n$ git commit\n複数のコミットは、取り込み時にしばしば縮められることに注意してください。
\n良いコミットメッセージは、何が何故変更されたのか、が記述されるべきです。 このElectronプロジェクトはセマンティックコミットメッセージをつかって、このリリースプロセスを合理化しています。
\nプルリクエストがマージされるためには、プルリクエストにタイトルがあり、それには意図を示すプレフィックスがなければなりません
\n意図を示すプレフィックスのあるコミットメッセージのの例です。:
\nfix: don't overwrite prevent_default if default wasn't preventedfeat: add app.isPackaged() methoddocs: app.isDefaultProtocolClient is now available on Linuxプレフィックスの例:
\nその他、コミットメッセージを作成するときに留意すること:
\nオプションの本体またはフッターのセクションの先頭に BREAKING CHANGE: のテキストがあるコミットは、API に破壊的な (セマンティックバージョン管理におけるメジャーと相関する) 変更をもたらします。 破壊的な変更はあらゆるタイプのコミットの一部になりえます。 例として、fix:、feat:、chore: やその他のタイプも加えてすべて当てはまります。
詳細については、conventionalcommits.org を参照してください。
\n変更をコミットしたら、git rebase (git merge ではない) を使用してメインリポジトリと作業を同期させることを推奨します。
$ git fetch upstream\n$ git rebase upstream/main\nこれにより作業ブランチに electron/electron の main の最新の変更が確実に反映されます。
バグの修正と機能追加には常にテストが必要です。 プロセスを簡単にするため、テストガイド が提供されています。 それらがどのように構築されるべきかを見るため、他のテストを見ることでも手助けになれます。
\nプルリクエストで変更を送信する前に、常に完全なテストスイートを実行してください。 テストを実行するには以下のようにします。
\n$ npm run test\nリンターが問題を報告していないこと、そしてすべてのテストが合格していることを確認してください。 いずれかのチェックに失敗したパッチは提出しないでください。
\nテストを更新していて、単一の仕様を実行してチェックしたい場合は、以下のようにします。
\n$ npm run test -match=menu\n上記の例では menu に一致する仕様のモジュールのみが実行されます。これは、テストサイクルの最後の最後にテストに取り組んでいる人にとって役に立ちます。
コミットの準備 ―― テストに合格して、lint をしている ―― ができたら、GitHub 上 のあなたのフォークに作業ブランチをプッシュして、プルリクエストを開くプロセスを開始します。
\n$ git push origin my-branch\nGitHub で、新しいプルリクエストを開くと、記入する必要のあるテンプレートが表示されます。
\n<!--\nプルリクエストありがとう。 上に説明を記述して、下の要件を確認してください。\n\nバグ修正や新機能には、テストやベンチマークが含まれている必要があります。\n\nコントリビューターガイド: https://github.com/electron/electron/blob/main/CONTRIBUTING.md\n-->\nおそらく、あなたはプルリクエストの変更に対するフィードバックやリクエストを得ます。 これは提出プロセスの大事な部分なので、がっかりさせないでください！ コントリビューターの中には、すぐにプルリクエストを承認する人がいます。 他の人には詳細なコメントやフィードバックがあるかもしれません。 これは、変更が正しいかどうかを評価するために必要なプロセスの一部です。
\n既存のプルリクエストを変更するには、ローカルブランチに変更を加え、それらの変更で新しいコミットを追加し、それらをあなたのフォークにプッシュします。 GitHub は自動的にプルリクエストを更新します。
\n$ git add my/changed/files\n$ git commit\n$ git push origin my-branch\n利用できる git rebase を使用して、コミットを管理するためのさらに高度なメカニズムがいくつかありますが、このガイドの範疇を超えています。
あなたが何らかの回答を待っている場合は、Ping レビュー担当者にプルリクエスト内でコメントを投稿してください。 不慣れな言葉や頭字語に遭遇した場合は、この 用語集 を参照してください。
\nすべてのプルリクエストは、取り込むために、変更した部分の Code Owner の承認が必要です。 管理者はプルリクエストをレビューするたびに、変更を要求することができます。 これらは、タイプミスを修正するなどの小さなもから、実質的な変更を伴うものまでにもなります。 このような要求は役に立ちますが、時には、特に変更する やり方 についての具体的な提案が含まれていないために、唐突だったり親切でないものに出くわすことがあります。
\nがっかりしないでください。 レビューが不公平であると感じる場合は、そう言い、別のプロジェクトのコントリビューターの意見を求めてください。 大抵の場合、そのようなコメントはレビュアーがレビューするのに十分な時間が無いためで、意図しないものです。 そのような困難はしばしば少しの忍耐で解決することができます。 要するに、レビュアーは親切なやりとりを提供することが期待されているということです。
\n取り込まれるには、少なくとも1人の Electron の Code Ownerがレビューして承認し、CI に合格する必要があります。 その後、他のコントリビューターからの異論がない場合、プルリクエストをマージすることができます。
\nおめでとう、あなたのコントリビューションに感謝します！
\nすべてのプルリクエストは、継続的インテグレーション (CI) システムでテストされ、 それが Electron のサポートされているプラットフォームで動作することを確認されます。
\n理想的には、プルリクエストは CI のすべてのプラットフォーム上で合格します (\"青になる\") 。 これは、すべてのテストが合格し、lint のエラーがないことを意味します。 しかし、CI インフラストラクチャ自体が特定のプラットフォームで失敗したり、いわゆる \"flaky\" テストに失敗する (\"赤になる\") ことは珍しいことではありません。 各 CI の失敗を手動で検査して原因を特定する必要があります。
\nプルリクエストを開くと、CI が自動的に開始されますが、メンテナーだけが CI の実行をリスタートできます。 CI が誤検知をしていると思われる場合は、メンテナーにテストをリスタートするよう依頼してください。
", "title": "プルリクエスト", "description": "" }, "/docs/tutorial/quick-start": { "locale": "ja-JP", "slug": "quick-start", "href": "/docs/tutorial/quick-start", "crowdinFileId": "256237", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/quick-start.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "This guide will step you through the process of creating a barebones Hello World app in Electron, similar to electron/electron-quick-start.
このチュートリアルを終えると、ブラウザウインドウを開いて Chromium、Node.js、Electron それぞれの実行バージョン情報のウェブページを表示できるアプリが完成します。
\nElectron を使用するには、 Node.js をインストールする必要があります。 利用可能な最新の LTS バージョンのインストールを推奨します。
\n\nお使いのプラットフォーム向けのビルド済みインストーラを使用して、Node.js をインストールするようにしてください。 さもなくば、他の開発ツールと互換性の問題が発生することがあります。
\n
Node.js が正しくインストールされたかどうかを確認するため、お使いのターミナルクライアントで以下のコマンドを入力してください。
\nnode -v\nnpm -v\nこのコマンドで、Node.js と npm のバージョンが表示されている必要があります。
\n注意: Electron は Node.js をバイナリに組み込んでいるため、コードを実行している Node.js のバージョンとシステムが実行しているバージョンは関係ありません。
\nElectron アプリは、他の Node.js プロジェクトと同様の一般的な構造に従います。 まず、フォルダを作成し npm パッケージを初期化します。
\nmkdir my-electron-app && cd my-electron-app\nnpm init\nこのインタラクティブな init コマンドでは、設定でいくつかフィールドの入力を促されます。 このチュートリアルの目的上、以下のルールに従ってください。
entry point は main.js でなければなりません。author と description はどのような値でも構いませんが、アプリのパッケージ化 で必要になります。package.json ファイルは、以下のようになっていなければなりません。
{\n \"name\": \"my-electron-app\",\n \"version\": \"1.0.0\",\n \"description\": \"Hello World!\",\n \"main\": \"main.js\",\n \"author\": \"Jane Doe\",\n \"license\": \"MIT\"\n}\nそして、アプリの devDependencies に electron パッケージインストールします。
$ npm install --save-dev electron\n\n\n注意: Electron のインストールで問題が発生した場合は、発展的なインストール のガイドをご参照ください。
\n
最後に、Electron を実行できるようにしたいと思います。 package.json の設定の scripts フィールドに、以下のような start コマンドを追加します。
{\n \"scripts\": {\n \"start\": \"electron .\"\n }\n}\nこの start コマンドにより、アプリを開発モードで開けます。
npm start\n\n\n注: このスクリプトは、Electron をプロジェクトのルートフォルダで実行するように指示しています。 今の段階のアプリでは、実行するアプリが見つからないというエラーが出ます。
\n
Electron アプリケーションのエントリポイントは、main スクリプトです。 このスクリプトは、メインプロセス を制御します。メインプロセスは完全な Node.js 環境で実行され、アプリのライフサイクルの制御、ネイティブインターフェースの表示、特権的操作の実行、レンダラープロセスの管理などを行います (詳細は後述)。
実行時、Electron はこのスクリプトをアプリの package.json の設定にある main フィールドから探します。これは プロジェクトの雛形を作る ステップで設定してあるはずです。
main スクリプトを書き始めるにあたって、プロジェクトのルートフォルダに main.js という空のファイルを作成します。
\n\n注: この時点で
\nstartスクリプトを再度実行すると、アプリはエラーを出さなくなります。 しかし、main.jsにコードを追加していないためまだ何もしません。
アプリケーションのウインドウを作成する前に、ウインドウが読み込むコンテンツを作成する必要があります。 Electron では、各ウインドウにローカルの HTML ファイルやリモート URL から読み込んだウェブコンテンツを表示します。
\nこのチュートリアルでは、前者を行います。 プロジェクトのルートフォルダに以下の index.html ファイルを作成しましょう。
\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n </body>\n</html>\n\n\n注: この HTML ドキュメントを見ると、バージョン番号が本文から抜けていることがわかります。 これは JavaScript で後から手動挿入します。
\n
ウェブページができたので、これをアプリケーションウインドウに読み込ませます。 そのためには、以下 2 つの Electron モジュールが必要です。
\napp モジュール。BrowserWindow モジュール。メインプロセスは Node.js で動作するので、これらを CommonJS モジュールとしてファイル先頭でインポートします。
\nconst { app, BrowserWindow } = require('electron')\n次に、createWindow() 関数を追加し、そこで index.html を新規作成した BrowserWindow インスタンスに読み込ませます。
function createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\n次に、この createWindow() 関数を呼び出してウインドウを開きます。
Electron では、app モジュールの ready イベントの発生以降のみ、ブラウザウインドウを作成できます。 このイベントは、app.whenReady() API を使用することで待てます。 whenReady() が Promise を解決した後、それが createWindow() を呼び出します。
app.whenReady().then(() => {\n createWindow()\n})\n\n\n注: この時点で、Electron アプリケーションはウェブページを表示するウィンドウを開くことに成功しているはずです。
\n
ブラウザウインドウを開くことができるようになりましたが、各プラットフォームでよりネイティブな感じを出すためには、いくつか追加の雛形コードが必要です。 アプリケーションウィンドウは OS ごとに異なる動作をしますが、Electron はこれらの規則をアプリに実装する責任を開発者負担にしています。
\n一般的には、process グローバルの platform 属性を使用して、特定のオペレーティングシステム専用のコードを実行できます。
一般的に Windows や Linux では、すべてのウィンドウを終了するとアプリケーションが完全に終了します。
\nこれを実装するには、app モジュールの 'window-all-closed' イベントをリッスンします。このイベントが発生し、ユーザーが macOS (darwin) でない場合に app.quit() を呼び出すようにします。
app.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nLinux や Windows のアプリはウインドウを開いていないと終了してしまいますが、macOS のアプリは一般的にウインドウを開いていなくても起動し続け、ウインドウがないときにアプリをアクティブにすると新規ウインドウが開きます。
\nこの機能を実装するには、app モジュールの activate イベントをリッスンします。ブラウザのウインドウが開いていなければ、既存の createWindow() メソッドを呼び出します。
ready イベントの前ではウインドウを作成できないので、アプリが初期化された後に activate イベントだけをリッスンする必要があります。 そのためには、既存の whenReady() コールバックの中で、イベントリスナーをアタッチします。
app.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n\n注: この時点で、ウインドウのコントロールが完全に機能しているはずです。
\n
さて、最後にやるべきことは Electron とその依存関係のバージョン番号をウェブページに出力することです。
\nこの情報へアクセスするには、Node のグローバルである process オブジェクトを介してメインプロセスで行うのが簡単です。 しかし、メインプロセスはレンダラーの document コンテキストにアクセスできないため、メインプロセスから DOM を編集できません。 これらは全く別のプロセスだからです！
\n\n注: Electron のプロセスについてもっと詳しく知りたい方は、プロセスモデル のドキュメントをご覧ください。
\n
そこで、プリロード スクリプトをレンダラーにアタッチすると便利です。 プリロードスクリプトは、レンダラープロセスが読み込まれる前に実行され、レンダラーのグローバル (window や document など) と Node.js 環境の両方にアクセスできます。
preload.js という名前の新規スクリプトを以下のように作成します。
window.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\n上記のコードでは、Node.js の process.versions オブジェクトにアクセスし、基本的な replaceText ヘルパー関数を実行して HTML ドキュメントにバージョン番号を挿入しています。
このスクリプトをレンダラープロセスにアタッチするには、既存の BrowserWindow コンストラクタの webPreferences.preload 引数にプリロードスクリプトへのパスを渡します。
// ファイルの先頭で Node.js の 'path' モジュールをインクルードします\nconst path = require('path')\n\n// 既存の createWindow() 関数を修正します\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n}\n// ...\nここでは、以下 2 つの Node.js のコンセプトが使われています。
\n__dirname 文字列は、現在実行中のスクリプトのパス (ここではプロジェクトのルートフォルダ) を指しています。path.join API は、複数のパス断片を結合し、すべてのプラットフォームで動作する結合パス文字列を作成します。現在実行中の JavaScript ファイルからの相対パスを使用しているので、開発モードとパッケージモードの両方で相対パスが機能します。
\nこの時点で、アプリケーションに機能を追加するにはどうしたらよいかと思われるかもしれません。
\nウェブコンテンツとやり取りする場合は、レンダラープロセスにスクリプトを追加する必要があります。 なぜならレンダラは通常のウェブ環境で動作するので、<script> タグを index.html ファイルの最後の </body> タグの直前に追加して任意のスクリプトをインクルードできます。
<script src=\"./renderer.js\"></script>\nrenderer.js に含まれるコードは、webpack でコードをバンドルして最小化したり、React を使用してユーザーインターフェースを管理するなど、一般的なフロントエンド開発と同じ JavaScript API やツールを利用できます。
以上の手順により、以下のような完全な機能の Electron のアプリケーションが完成しました。
\n
コード全体は以下のとおりです。
\n// main.js\n\n// アプリケーションの寿命の制御と、ネイティブなブラウザウインドウを作成するモジュール\nconst { app, BrowserWindow } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n // ブラウザウインドウを作成します。\n const mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n // そしてアプリの index.html を読み込みます。\n mainWindow.loadFile('index.html')\n\n // デベロッパー ツールを開きます。\n // mainWindow.webContents.openDevTools()\n}\n\n// このメソッドは、Electron の初期化が完了し、\n// ブラウザウインドウの作成準備ができたときに呼ばれます。\n// 一部のAPIはこのイベントが発生した後にのみ利用できます。\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n // macOS では、Dock アイコンのクリック時に他に開いているウインドウがない\n // 場合、アプリ内にウインドウを再作成するのが一般的です。\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n// macOS を除き、全ウインドウが閉じられたときに終了します。 ユーザーが\n// Cmd + Q で明示的に終了するまで、アプリケーションとそのメニューバーを\n// アクティブにするのが一般的です。\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\n\n// このファイルでは、アプリ内のとある他のメインプロセスコードを\n// インクルードできます。 \n// 別々のファイルに分割してここで require することもできます。\n// preload.js\n\n// Node.js の全 API は、プリロードプロセスで利用可能です。\n// Chrome 拡張機能と同じサンドボックスも持っています。\nwindow.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\n<!--index.html-->\n\n\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n\n <!-- このプロセスで他ファイルを require して実行することもできます -->\n <script src=\"./renderer.js\"></script>\n </body>\n</html>\nこれまでのステップを以下にまとめます。
\nNode.js アプリケーションを立ち上げ、Electron を依存関係に追加しました。
\nアプリ制御を担うメインプロセスを実行する main.js スクリプトを作成し、Node.js 環境で動作させました。 このスクリプトでは、Electron の app と BrowserWindow モジュールを使って、ウェブコンテンツを別のプロセス (レンダラー) で表示するブラウザウインドウを作成しました。
レンダラーで特定の Node.js の機能にアクセスするために、BrowserWindow のコンストラクタでプリロードスクリプトをアタッチしました。
できたてのアプリを頒布する最速手段は Electron Forge を利用する方法です。
\nアプリの開発用依存関係に Electron Forge を追加し、その import コマンドで Forge のセットアップをします。
npm install --save-dev @electron-forge/cli\nnpx electron-forge import\n\n✔ Checking your system\n✔ Initializing Git Repository\n✔ Writing modified package.json file\n✔ Installing dependencies\n✔ Writing modified package.json file\n✔ Fixing .gitignore\n\nWe have ATTEMPTED to convert your app to be in a format that electron-forge understands.\n\nThanks for using \"electron-forge\"!!!\n以下のように Forge の make コマンドで頒布形式を作成します。
npm run make\n\n> my-electron-app@1.0.0 make /my-electron-app\n> electron-forge make\n\n✔ Checking your system\n✔ Resolving Forge Config\nWe need to package your application before we can make it\n✔ Preparing to Package Application for arch: x64\n✔ Preparing native dependencies\n✔ Packaging Application\nMaking for the following targets: zip\n✔ Making for target: zip - On platform: darwin - For arch: x64\nElectron Forge は、out フォルダを作成してそこにパッケージを配置します。
// macOS 版の例\nout/\n├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip\n├── ...\n└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app\n電子版に合致するドキュメントを使用していることを確認してください。 バージョン番号は、ページ URL の一部である必要があります。 そうでなければ、おそらく、お使 いの電子版と互換性のないAPI 変更を含む可能性のある開発ブランチのドキュメントを使用している可能性があります。 古いバージョンのドキュメントを読むには、GitHub上でタグを見てみてください。\"Switch branches/tags\" のドロップダウンメニューを開いて、あなたが使っているバージョンと同じタグを選んでください。
\nここにはよく聞かれる質問が載っています。 Issue を作成する前に、こちらを確認してください。
\nこれらの個別のチュートリアルでは、上のガイドで説明したトピックを拡張しています。
\ndevelopment/README.md を参照してください
", "title": "公式ガイド", "description": "" }, "/docs/development/README": { "locale": "ja-JP", "slug": "README", "href": "/docs/development/README", "crowdinFileId": "256127", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/README.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "これらのガイドは、Electron プロジェクトそのものに取り組む人を対象にしています。 Electron アプリ開発のガイドについては、/docs/README.md を参照してください。
\nWindows と macOS は、それぞれジャンプリストまたは Dock メニューを介して、アプリケーションによって開かれた最近の書類のリストへのアクセスを提供します。
\nジャンプリスト:
\n
アプリケーションの Dock メニュー:
\n
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\n\nconst fileName = 'recently-used.md'\nfs.writeFile(fileName, 'Lorem Ipsum', () => {\n app.addRecentDocument(path.join(__dirname, fileName))\n})\n\napp.whenReady().then(createWindow)\n\napp.on('window-all-closed', () => {\n app.clearRecentDocuments()\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n最近開いた書類にファイルを追加するには、app.addRecentDocument API を使用します。
\nElectron アプリケーションの起動後、アプリケーションのアイコンを右クリックしてみましょう。 このガイドでは、そのアイテムはプロジェクトのルートにある Markdown ファイルとなっています。 最近開いたファイルのリストに recently-used.md が追加されているはずです。
最近開いた書類のリストを消去するには、app.clearRecentDocuments API を使用します。 このガイドでは、すべてのウインドウを閉じた時点でその書類のリストは消去されます。
\nWindows でこの機能を使用する際にアプリケーションが書類のファイルタイプのハンドラとして登録されていない場合、ファイルを追加してもジャンプリストに表示されません。 アプリケーションの登録については、Application Registration にすべて記載されています。
\nユーザーがジャンプリストからファイルをクリックすると、アプリケーションの新しいインスタンスが、ファイルのパスがコマンドライン引数として追加されて起動されます。
\n以下のコードスニペットをメニューテンプレートに追加することで、最近開いた書類にアクセスしたり消去したりするメニュー項目を追加できます。
\n{\n \"submenu\":[\n {\n \"label\":\"Open Recent\",\n \"role\":\"recentdocuments\",\n \"submenu\":[\n {\n \"label\":\"Clear Recent\",\n \"role\":\"clearrecentdocuments\"\n }\n ]\n }\n ]\n}\n以下のようにアプリケーションメニューを 'ready' イベントより後に追加し、それより前では追加しないようにしてください。さもなくばメニューアイテムは無効になります。
const { app, Menu } = require('electron')\n\nconst template = [\n // メニューテンプレートをこちらに\n]\nconst menu = Menu.buildFromTemplate(template)\n\napp.whenReady().then(() => {\n Menu.setApplicationMenu(menu)\n})\n
最近使った書類メニューからファイルが要求されると、それに対して app モジュールの open-file イベントが発生します。
x Number - The x coordinate of the origin of the rectangle (must be an integer).y Number - The y coordinate of the origin of the rectangle (must be an integer).width Number - The width of the rectangle (must be an integer).height Number - The height of the rectangle (must be an integer).url String - HTTP Referrer URL.policy String - Can be default, unsafe-url, no-referrer-when-downgrade, no-referrer, origin, strict-origin-when-cross-origin, same-origin or strict-origin. See the Referrer-Policy spec for more details on the meaning of these values.Read-Eval-Print-Loop (REPL, レプル) はシンプルな対話型コンピュータープログラミング環境で、単一のユーザー入力 (すなわち単一の式) を受け取り、それらを評価して結果をユーザーへ返します。
\nElectron は --interactive CLI フラグに応じてその Node.js repl モジュール を公開します。 ローカルプロジェクトの依存関係として electron がインストールされていれば、以下のコマンドで REPL にアクセスできるはずです。
./node_modules/.bin/electron --interactive\n注意: electron --interactive は Windows では利用できません (詳細は electron/electron#5776 をご参照ください)。
デベロッパー ツールの Console タブを使用すれば、あらゆるレンダラープロセスで REPL ができます。 より詳しく学びたい方は、Chrome ドキュメント をご覧ください。
", "title": "REPL", "description": "" }, "/docs/tutorial/represented-file": { "locale": "ja-JP", "slug": "represented-file", "href": "/docs/tutorial/represented-file", "crowdinFileId": "256243", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/represented-file.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "macOS では、アプリケーション内の任意のウインドウに表示中のファイルを設定できます。 表現中ファイルのアイコンはタイトルバーに表示され、ユーザーが Command-Click や Control-Click クリックをすると、ファイルへのパスを含むポップアップが表示されます。
\n\n注意: 上のスクリーンショットは、Atom テキストエディタで現在開いているファイルを表示するためにこの機能を使用している例です。
\n
ウインドウの編集状態を設定し、このウィンドウ内の書類が変更されたかどうかをファイルアイコンで表示することもできます。
\nウィンドウの表示中ファイルを設定するには、BrowserWindow.setRepresentedFilename と BrowserWindow.setDocumentEdited の API を使用します。
\nconst { app, BrowserWindow } = require('electron')\nconst os = require('os');\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n}\n\napp.whenReady().then(() => {\n const win = new BrowserWindow()\n\n win.setRepresentedFilename(os.homedir())\n win.setDocumentEdited(true)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nElectron アプリケーションを起動した後、Command または Control キーを押した状態でタイトルをクリックします。 すると、ウインドウが表すファイルのポップアップが上部に表示されるはずです。 このガイドでは、これはユーザのホームディレクトリです。
\n\n文字列をローカルマシンに保管するにあたって簡単な暗号化と復号へのアクセスを可能にします。
\n
プロセス: Main
\nこのモジュールは、ディスクに保存されたデータを、フルディスクアクセス権のある他のアプリケーションやユーザのアクセスから保護します。
\nなお、Mac ではシステムのキーチェーンへのアクセスが必要であり、これらの呼び出しがユーザ入力の収集のために現在のスレッドをブロックすることがあります。 パスワード管理ツールが利用可能な場合、Linux でも同じことが言えます。
\nsafeStorage モジュールには以下のメソッドがあります。
safeStorage.isEncryptionAvailable()戻り値 Boolean - 暗号化が利用可能かどうか。
Linux では、秘密鍵が利用可能であれば true を返します。 MacOS では、キーチェーンが利用可能な場合は true を返します。 Windows では、他の前提条件なしに true を返します。
\nsafeStorage.encryptString(plainText)plainText String戻り値 Buffer - 暗号化した文字列を表すバイトの配列。
この関数は、暗号化に失敗するとエラーを送出します。
\nsafeStorage.decryptString(encrypted)encrypted Buffer戻り値 String - 復号した文字列。 safeStorage.encryptString で得た暗号化されたバッファを、文字列に復号します。
この関数は、復号に失敗するとエラーを送出します。
", "title": "safeStorage", "description": "文字列をローカルマシンに保管するにあたって簡単な暗号化と復号へのアクセスを可能にします。" }, "/docs/tutorial/sandbox": { "locale": "ja-JP", "slug": "sandbox", "href": "/docs/tutorial/sandbox", "crowdinFileId": "256245", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/sandbox.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Chromium の重要なセキュリティ機能の一つは、プロセスをサンドボックス内で実行できることです。 サンドボックスは、ほとんどのシステムリソースへのアクセスを制限することで悪意のあるコードが引き起こす被害を制限します。サンドボックスのプロセスは、CPU サイクルとメモリのみを自由に使用できます。 サンドボックス化したプロセスで追加の特権を必要とする操作を実行するには、専用の通信チャンネルを使用してより特権のあるプロセスにタスクを委譲します。
\nChromium では、メインプロセス以外のほとんどのプロセスにサンドボックス化が適用されます。 これにはレンダラープロセスのほか、オーディオサービス、GPU サービス、ネットワークサービスなどのユーティリティプロセスも含まれます。
\n詳しい情報は Chromium の サンドボックスデザインのドキュメント をご参照ください。
\nElectron には混合サンドボックス環境があります。これは、サンドボックス化したプロセスと特権プロセスを横並びに実行するというものです。 デフォルトでは、レンダラープロセスはサンドボックスではなく、ユーティリティプロセスです。 注意として、Chromium と同様にメイン (ブラウザ) プロセスは特権プロセスであり、サンドボックス化できません。
\n歴史的には、アプリ開発者にとってレンダラーでの Node.js の利用は非常に強力なツールであるため、このような混合サンドボックス方式が確立されました。 あいにく、この機能は甚大なセキュリティ上の脆弱性でもあります。
\n理論的には、信頼されるコードだけを表示するデスクトップアプリケーションでは非サンドボックス化レンダラーは問題になりません。しかし、信頼されないウェブコンテンツを表示する場合の Electron は、Chromium よりも堅牢性が低くなります。 クロスサイトスクリプティング、コンテンツインジェクション、遠隔で読み込んだウェブサイトへの中間者攻撃など、悪意のある人間が利用できる攻撃手段は無数にあります。 念のため、大多数の状況ではレンダラーのサンドボックスの有効化を推奨します。
\n\nなお Issue トラッカーではレンダラーのサンドボックス化をデフォルトで有効にするための議論が活発に行われています。 詳しくは #28466) を参照してください。
\nElectron のサンドボックス化したプロセスは ほぼ Chromium と同じように動作しますが、Electron は Node.js とのインターフェイスであるために更に考慮すべき概念がいくつかあります。
\nElectron のレンダラープロセスをサンドボックス化すると、通常の Chrome レンダラーと同じように動作します。 サンドボックス化したレンダラーは Node.js 環境が初期化されません。
\n\nそのため、サンドボックスを有効にすると、レンダラープロセスはプロセス間通信 (IPC) を介したメインプロセスへのタスクの委譲によってのみ、特権的なタスク (ファイルシステムとのやりとり、システムへの変更、サブプロセスの生成など) を実行できます。
\nレンダラープロセスがメインプロセスと通信できるようにするため、サンドボックス化したレンダラーにアタッチされるプリロードスクリプトでは Node.js API をポリフィルしたサブセットを利用できるようになっています。 Node の require に似た require 関数のモジュールを公開してありますが、これは以下 Electron や Node の組み込みモジュールのサブセットしかインポートできません。
加えて、プリロードスクリプトは以下の Node.js プリミティブもグローバルとしてポリフィルします。
\nBufferプロセスclearImmediatesetImmediaterequire 関数は機能を限定したポリフィルであるため、CommonJS モジュール を利用したプリロードスクリプトの複数ファイル分割ができません。 プリロードコードを分割する必要がある場合は、webpack や Parcel のようなバンドラーを使用してください。
preload スクリプトに与えられる環境は、サンドボックス化したレンダラーの環境よりも大幅に特権的です。contextIsolation が有効になっていない限り、特権的な API をレンダラープロセスで実行している信頼されていないコードにリークできることに注意してください。
Electron では、BrowserWindow コンストラクタで sandbox: true を設定することでレンダラープロセスごとにサンドボックスを有効化できます。
// main.js\napp.whenReady().then(() => {\n const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n })\n win.loadURL('https://google.com')\n})\nすべてのレンダラーにサンドボックスを強制したい場合は、app.enableSandbox API も利用できます。 注意として、この API は app の ready イベントより前に呼ぶ必要があります。
// main.js\napp.enableSandbox()\napp.whenReady().then(() => {\n // app.enableSandbox() を呼んだので `sandbox: true` の指定は不要です。\n const win = new BrowserWindow()\n win.loadURL('https://google.com')\n})\n--no-sandbox CLI フラグで Chromium のサンドボックスを完全に無効化することもできます。これは、(ユーティリティプロセスを含む) すべてのプロセスのサンドボックスを無効化します。 このフラグはテスト目的でのみ使用し、本番環境では 絶対に 使用しないことを強く推奨します。
注意として、この状況で sandbox: true オプションを指定してもレンダラーの Node.js 環境は無効になります。
信頼されないコンテンツを Electron で描画することはまだ未知の領域ですが、いくつかのアプリケーションは成功を収めています (例: Beaker Browser)。 私たちの目標はサンドボックス化したコンテンツのセキュリティに関して Chrome にできるだけ近づくことですが、突き詰めるといくつかの基本的な問題のためにいつも後れを取ることになります。
\nChromium のセキュリティ修正を古いバージョンの Electron にバックポートするよう最善の努力をしていますが、すべての修正のバックポートは保証できません。 堅牢性を確保するには、Electron の最新の安定版を使用することが最善の方法です。
", "title": "プロセスのサンドボックス化", "description": "" }, "/docs/api/screen": { "locale": "ja-JP", "slug": "screen", "href": "/docs/api/screen", "crowdinFileId": "256361", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/screen.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n画面サイズ、ディスプレイ、カーソルの位置などについての情報を取得します。
\n
プロセス: Main
\napp モジュールの ready イベントが発生するまでは、このモジュールは使用できません。
screen は EventEmitter です。
注意: レンダラー / デベロッパー ツールでは、window.screen は予約された DOM プロパティなので、let { screen } = require('electron') と書くことはできません。
以下は画面全体を埋めるウインドウを作成する例です。
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\napp.whenReady().then(() => {\n const { width, height } = screen.getPrimaryDisplay().workAreaSize\n win = new BrowserWindow({ width, height })\n win.loadURL('https://github.com')\n})\n以下は外部ディスプレイにウィンドウを作成するもう一つの例です。
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n const displays = screen.getAllDisplays()\n const externalDisplay = displays.find((display) => {\n return display.bounds.x !== 0 || display.bounds.y !== 0\n })\n\n if (externalDisplay) {\n win = new BrowserWindow({\n x: externalDisplay.bounds.x + 50,\n y: externalDisplay.bounds.y + 50\n })\n win.loadURL('https://github.com')\n }\n})\nscreen モジュールには以下のイベントがあります。
戻り値：
\nevent EventnewDisplay DisplaynewDisplay が追加されたときに発生します。
戻り値：
\nevent EventoldDisplay DisplayoldDisplay が削除されたときに発生します。
戻り値：
\nevent Eventdisplay DisplaychangedMetrics String[]display 内の一つ以上の寸法が変化したときに発生します。 changedMetrics は、変化を示す文字列の配列です。 bounds、workArea、scaleFactor、rotation に変化できます。
screen モジュールには以下のメソッドがあります。
screen.getCursorScreenPoint()戻り値 Point
マウスポインタの現在の絶対位置。
\n注: 戻り値は DIP ポイント単位です。画面の物理ポイント単位ではありません。
\nscreen.getPrimaryDisplay()戻り値 Display - 主要なディスプレイ。
screen.getAllDisplays()戻り値 Display[] - 現在利用可能な display の配列。
screen.getDisplayNearestPoint(point)point Point戻り値 Display - 指定した point に最も近い display。
screen.getDisplayMatching(rect)rect Rectangle戻り値 Display - 指定した矩形に最も近い display。
screen.screenToDipPoint(point) Windowspoint Point戻り値 Point
スクリーン上の物理的な点をスクリーン上の DIP な点に変換します。 DPI スケールは、物理的な点のあるディスプレイに対して相対的なものになります。
\nscreen.dipToScreenPoint(point) Windowspoint Point戻り値 Point
スクリーン上の DIP な点をスクリーン上の物理的な点に変換します。 DPI スケールは、DIP な点のあるディスプレイに対して相対的なものになります。
\nscreen.screenToDipRect(window, rect) Windowswindow BrowserWindow | nullrect Rectangle戻り値 Rectangle
スクリーンの物理矩形をスクリーンのの DIP 矩形に変換します。 DPI スケールは window に近いディスプレイと相対的に計算されます。 window が null の場合、スケールは rect に近いディスプレイと相対的に計算されます。
screen.dipToScreenRect(window, rect) Windowswindow BrowserWindow | nullrect Rectangle戻り値 Rectangle
スクリーンの DIP 矩形をスクリーンのの物理矩形に変換します。 DPI スケールは window に近いディスプレイと相対的に計算されます。 window が null の場合、スケールは rect に近いディスプレイと相対的に計算されます。
label String (optional) - The text to appear in this item.icon NativeImage (optional) - The image to appear in this item.私たちは普段、Web開発者としてブラウザの強力なセキュリティを享受しています。つまり、私たちが書いたコードに起因するリスクは比較的小さいと言えます。 私たちのウェブサイトにはサンドボックスに限られた権限が与えられており、ユーザーは新たに発見されたセキュリティ上の脅威に迅速に対応できる、大規模なエンジニアチームによって構築されたブラウザを享受していると考えています。
\nElectron で開発する時、Electron はブラウザではないということを意識することが重要です。 使い慣れたウェブ技術を使用して、機能あふれるデスクトップアプリケーションを構築できますが、あなたのコードの方がはるかに大きな力を発揮します。 JavaScript はファイルシステム、ユーザシェルなどにアクセスできます。 これはつまり、質の高いネイティブアプリケーションを作成することができる反面、あなたの書くコードに与えられた権限に応じて固有のセキュリティリスクが増加するということです。
\nそれを念頭に置いて、信頼できないソースからの任意のコンテンツを表示するということは、Electron が扱うことを意図しない重大なセキュリティリスクを引き起こすということに注意してください。 実際、人気のある Electron アプリ (Atom、Slack、Visual Studio Code、等) は、主にローカル (あるいは信頼されており、なおかつ Node integration を使用しないリモート) のコンテンツを取り扱います。もしあなたのアプリケーションがオンライン上のリソースからコードを実行する場合、あなたの責任の下でそのコードが悪意のあるものではないことを確認する必要があります。
\nElectron の脆弱性を報告する正しい方法については SECURITY.md を参照してください。
\nElectron は、Chromiumのリリースとは交互に更新しています。 詳しくは、Electron リリースケイデンスのブログ記事 を参照してください。
\nあなたの Electron アプリケーションのセキュリティは、フレームワーク (Chromium、Node.js)、Electron 自身、NPM の依存関係、あなたのコード のセキュリティの結果であることを覚えておくことが大事です。 そのため、いくつかの重要なベストプラックティスに従う、責任があります。
\nあなたのアプリケーションは最新リリースの Electron フレームワークを使う。 あなたはプロダクトをリリースしたとき、Electron、 Chromium 共有ライブラリ、Node.js を組み込んでリリースしています。 これらのコンポーネントに影響する脆弱性は、あなたのアプリケーションのセキュリティに影響する可能性があります。 Electronを最新バージョンにアップデートすることで、あなたはクリティカルな脆弱性(例えば nodeIntegration bypasses) にパッチを当てた状態にして、あなたのアプリケーションで発現しないようにできます。 詳細については、\"現行バージョンの Electron を使う\" を参照してください。
\nあなたのアプリの依存関係の評価する。 NPM は 50万もの再利用できるパッケージを提供しています。一方、あなたは信頼するサードパーティのライブラリを選択する責任があります。 あなたが既知の脆弱性の影響を受けるライブラリを利用する場合や、あまりメンテナンスされていないコードに頼る場合、あなたのアプリケーションのセキュリティは低下し危険な状態になります。
\nセキュアコーディングプラクティスの採用。 あなたのアプリケーションの防衛の第一歩はあなたのコードです。 クロスサイトスクリプティング (XSS) のような一般的なウェブの脆弱性は Electron アプリケーションに大きなセキュリティ上の影響を与えるため、安全なソフトウェア開発のベストプラクティスの採用とセキュリティテストの実施を強く推奨します。
\n信用されていないソース (例えばリモートサーバー) からコードを受け取ってローカルで実行するときは、常にセキュリティの問題が存在します。 例として、リモートのウェブサイトがデフォルト BrowserWindow 内に表示されていると考えてください。 もし攻撃者がどうにかして(情報源そのものの攻撃や中間者攻撃によって) 得られる内容を変更した場合、ユーザーのPC上でネイティブコードを実行できることになります。
\n\n:警告: Node integration が有効な環境で、リモートコードの読み込みと実行を行ってはいけません。 代わりに、Node.js コードの実行にはローカルファイル (アプリケーションと一緒にパッケージ化されているもの) だけを使用してください。 remote コンテンツを表示するには、
\n<webview>tag またはBrowserViewを使用します。その時nodeIntegrationを無効に、contextIsolationを有効にすることを確認してください。
Electron 2.0 からでは、開発者は、開発者コンソールに出力される警告と推奨を見られます。 バイナリ名が Electron の場合にのみ表示され、開発者が現在コンソールを見ていることを示しています。
\nこれらの警告を、 process.env または window オブジェクトにELECTRON_ENABLE_SECURITY_WARNINGS または ELECTRON_DISABLE_SECURITY_WARNINGS を設定することで、強制的に有効または無効にできます。
あなたはあなたのアプリケーションのセキュリティーを向上させるために、少なくとも次のステップを実施してください。
\nses.setPermissionRequestHandler() を利用するwebSecurity を無効にしないContent-Security-Policy を定義して、スクリプトの読み込み元を制限する (例: script-src 'self')allowRunningInsecureContent を true にしないenableBlinkFeatures を使用しない<webview>: allowpopups を使用しない<webview>: オプションとパラメータを検証するopenExternal を使用しない設定ミスやセキュアでないパターンを自動的に検出するには、electronegativityが使用できます。 Electronを使用したアプリケーション開発時の潜在的な脆弱性やバグの埋め込みについてのより詳しい情報は、開発者承認者向けガイドguide for developers and auditorsを参照してください。
\nアプリケーションに含まれていない任意のリソースは、HTTPS のようなセキュアなプロトコルを使用して読み込まなければいけません。 つまり、HTTP のようなインセキュアなプロトコルを使用しないでください。 同様に、WS より WSS、FTP より FTPS の使用を推奨します。
HTTPS には、主に3つの利点があります。
1) あなたのアプリが偽装者ではなく正しいホストに接続するように、リモートサーバーを認証します。 2) アプリケーションとホスト間の転送中にデータが変更されていないことを確認し、データの整合性を保証します。 3) ユーザーと宛先ホスト間のトラフィックを暗号化し、アプリとホスト間で送信される情報を盗聴することをより難しくします。
\n// NG\nbrowserWindow.loadURL('http://example.com')\n\n// OK\nbrowserWindow.loadURL('https://example.com')\n<!-- NG -->\n<script crossorigin src=\"http://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"http://example.com/style.css\">\n\n<!-- OK -->\n<script crossorigin src=\"https://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"https://example.com/style.css\">\nこの推奨は、Electron 5.0.0 からデフォルトの振舞いです。
\nリモートコンテンツをロードするレンダラー (BrowserWindow、BrowserView、<webview>) で Node.js integration を有効にしないことが重要です。 リモートコンテンツに与える権限を制限することで、攻撃者がウェブサイトで JavaScript を実行できるようになった場合に、ユーザを傷つけることを劇的に難しくする目的があります。
その後、特定のホストに対して追加の権限を与えることができます。 例えば、https://example.com/ を指す BrowserWindow を開いている場合、あなたはそのウェブサイトに必要な権限を正確に与えることができますが、それ以上は与えられません。
クロスサイトスクリプティング (XSS) 攻撃は、攻撃者がレンダラープロセスを飛び越えてユーザのコンピュータ上でコードを実行できる場合、より危険です。 クロスサイトスクリプティングの攻撃はかなり一般的――かつ問題が発生している間、通常では、その力は実行されているウェブサイトをめちゃくちゃにするだけです。 Node.js integration を無効にすることは、XSS が昇華され、いわゆる \"遠隔コード実行\" (RCE) 攻撃になるのを防ぐのに役立ちます。
\n// 悪い\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n nodeIntegration: true,\n nodeIntegrationInWorker: true\n }\n})\n\nmainWindow.loadURL('https://example.com')\n// 良い\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n preload: path.join(app.getAppPath(), 'preload.js')\n }\n})\n\nmainWindow.loadURL('https://example.com')\n<!-- NG -->\n<webview nodeIntegration src=\"page.html\"></webview>\n\n<!-- OK -->\n<webview src=\"page.html\"></webview>\nNode.js integration を無効にすると、ウェブサイトへ Node.js モジュールまたは機能を使用する API を確認することができます。 プリロードスクリプトは引き続き require と他の Node.js の機能にアクセスできるため、開発者はコンテンツをリモートにロードするカスタム API を確認します。
次のプレロードスクリプトの例では、後でロードされたWebサイトは window.readConfig() メソッドにアクセスできますが、Node.js の機能は使用できません。
const { readFileSync } = require('fs')\n\nwindow.readConfig = function () {\n const data = readFileSync('./config.json')\n return data\n}\nコンテキストイソレーションは、開発者が専用の JavaScript コンテキストで、プリロードスクリプトと Electron API でコードを実行できるようにする Electron の機能です。 つまり、Array.prototype.push や JSON.parse などのグローバルオブジェクトは、レンダラープロセスで実行されているスクリプトでは変更できません。
Electron は Chromium の コンテンツスクリプト と同じ技術を使用してこの動作を可能にしています。
\nnodeIntegration: false を使用している場合でも、真に強力なアイソレーションを強制し Node プリミティブの使用を防ぐためには、contextIsolation も使用 しなければなりません。
contextIsolation が何であるのか及びこれを有効にする方法についての情報は、コンテキスト隔離 ドキュメントをご参照ください。
サンドボックス化 は Chromium の機能で、オペレーティングシステムを利用してレンダラープロセスのアクセス範囲を大幅に制限します。 すべてのレンダラーでサンドボックスを有効にするべきです。 メインプロセスを含むサンドボックス化されていないプロセスでは、信頼されないコンテンツをロードしたり、読んだり、処理したりすることはお勧めしません。
\nウインドウ作成時に、以下のように webPreferences に sandbox: true オプションを渡します。
const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n})\nChromeを使用しているときに許可リクエストが表示されていることがあります――ユーザーが手動で承認する必要がある機能 (通知など) をウェブサイトが使用しようとするたびにポップアップが表示されます。
\nAPI は Chromium 権限 API に基づいており、同じ種類のアクセス許可を実装しています。
\nデフォルトでは、開発者がカスタムハンドラを手動で設定していない限り、Electron はすべての権限リクエストを自動的に承認します。 セキュリティを意識した開発者は、堅実なデフォルトとしては、まったく反対のことを想定したかもしれません。
\nconst { session } = require('electron')\n\nsession\n .fromPartition('some-partition')\n .setPermissionRequestHandler((webContents, permission, callback) => {\n const url = webContents.getURL()\n\n if (permission === 'notifications') {\n // 権限リクエストを承認する\n callback(true)\n }\n\n // URL を認証する\n if (!url.startsWith('https://example.com/')) {\n // 権限リクエストを拒否する\n return callback(false)\n }\n })\nElectron のデフォルトを推奨しています
\nレンダラープロセス (BrowserWindow、BrowserView、<webview>) 上の webSecurity プロパティを無効にすることは、 重要なセキュリティ機能を無効にするということです。
製品としてのアプリケーションで webSecurity を無効にしないでください。
webSecurity を無効にすると、同一オリジンポリシーが無効になり、allowRunningInsecureContent プロパティが true に設定されます。 つまり、異なるドメインからの安全でないコードの実行を可能にしてしまいます。
// NG\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n webSecurity: false\n }\n})\n// OK\nconst mainWindow = new BrowserWindow()\n<!-- NG -->\n<webview disablewebsecurity src=\"page.html\"></webview>\n\n<!-- OK -->\n<webview src=\"page.html\"></webview>\nContent Security Policy (CSP) は、クロスサイトスクリプティング攻撃やデータインジェクション攻撃から保護する副層です。 Electron 内でロードする任意のウェブサイトで有効にすることを推奨します。
\nCSP を使用すると、コンテンツを提供するサーバーが、指定されたウェブページに Electron がロードできるリソースを、制限および制御できます。 https://example.com は、https://evil.attacker.com からのスクリプトは許可せず、定義したオリジンのスクリプトを読み込むことを許可して実行する必要があります。 CSP を定義することは、アプリケーションのセキュリティを向上させる簡単な方法です。
以下の CSP は、Electron が現在のウェブサイトと apis.example.com からスクリプトを実行できるようにします。
// NG\nContent-Security-Policy: '*'\n\n// OK\nContent-Security-Policy: script-src 'self' https://apis.example.com\nElectron は Content-Security-Policy HTTP ヘッダ とそれぞれの webRequest.onHeadersReceived タグを尊重します。
const { session } = require('electron')\n\nsession.defaultSession.webRequest.onHeadersReceived((details, callback) => {\n callback({\n responseHeaders: {\n ...details.responseHeaders,\n 'Content-Security-Policy': ['default-src \\'none\\'']\n }\n })\n})\nCSP の推奨伝達メカニズムは HTTP ヘッダですが、file:// プロトコルを使用してリソースをロードするときにこのメソッドを使用することはできません。 file:// プロトコルを使用する場合など、<meta> タグを使用してマークアップのページに直接ポリシーを設定すると便利な場合があります。
<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'\">\nallowRunningInsecureContent を true にしないElectron のデフォルトを推奨しています
\nデフォルトでは、Electron は HTTPS 上でロードされたウェブサイト上でのみ、安全でないソース (HTTP) からスクリプト、CSS、またはプラグインを読み込んで実行できるようにします。 allowRunningInsecureContent プロパティを true にすることで、その保護を無効にします。
HTTPS 経由でウェブサイトの初期 HTML を読み込んで、HTTP 経由で後続のリソースを読み込もうとすることを \"混合コンテンツ\" といいます。
HTTPS を介してコンテンツをロードすると、トラフィック自体を暗号化しながら、ロードされたリソースの信憑性と完全性が保証されます。 より詳しくは、セキュアなコンテンツのみを表示する を参照して下さい。
// NG\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n allowRunningInsecureContent: true\n }\n})\n// OK\nconst mainWindow = new BrowserWindow({})\nElectron のデフォルトを推奨しています
\nElectron の上級ユーザは、experimentalFeatures のプロパティを使用して Chromium の実験的な機能を有効にすることができます。
実験的な機能は、その名前が示すように、実験的であり、Chromium のすべてのユーザに有効にされていません。 さらに、Electron 全体への影響はテストされていない可能性が高いです。
\n正しい使用方法は存在しますが、何をしているのか分からない限り、このプロパティを有効にしないでください。
\n// NG\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n experimentalFeatures: true\n }\n})\n// OK\nconst mainWindow = new BrowserWindow({})\nenableBlinkFeatures を使用しないElectron のデフォルトを推奨しています
\nBlink は、Chromium のバックグラウンドにあるレンダリングエンジンの名前です。 experimentalFeatures と同様に、enableBlinkFeatures プロパティを使用すると、デフォルトで無効になっている機能を有効にすることができます。
一般に、機能がデフォルトで有効になっていない場合は、よい理由が考えられます。 その機能を有効にするための、正しい使用方法は存在します。 開発者は、機能を有効にする必要がある理由、影響の内容、アプリケーションのセキュリティにどのように影響するかを正確に把握する必要があります。 どのような場合においても、機能を推論的に有効にするべきではありません。
\n// 悪例\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n enableBlinkFeatures: 'ExecCommandInJavaScript'\n }\n})\n// OK\nconst mainWindow = new BrowserWindow()\nallowpopups を使用しないElectron のデフォルトを推奨しています
\n<webview> を使用している場合、新しいウィンドウを開くには <webview> タグにページとスクリプトをロードする必要があります。 allowpopups 属性は、window.open() メソッドを使用して新しい BrowserWindow を作成することができるようにします。 そうでなければ、<webview> は新しいウインドウを作成できません。
ポップアップが必要ない場合は、デフォルトで新しい BrowserWindow の作成を許可しないようにしたほうがよいでしょう。 これは必要最低限なアクセスの原則に従っています。ウェブサイトにその機能が必要でない限り、新しいポップアップを作成させないでください。
<!-- NG -->\n<webview allowpopups src=\"page.html\"></webview>\n\n<!-- OK -->\n<webview src=\"page.html\"></webview>\nNode.js integration が有効になっていないレンダラープロセスで作成された WebView は、integration 自体を有効にすることはできません。 しかし、WebView は常に独自の webPreferences を使用して、独立したレンダラープロセスを作成します。
メインプロセスから新しい <webview> タグの作成を制御し、webPreferences でセキュリティ機能を無効にしていないことを確認することを推奨します。
<webview> は DOM 内に存在するので、Node.js integration が無効になっていても、WebView はウェブサイトで実行されているスクリプトによって作成できます。
Electron では、開発者はレンダラープロセスを制御するさまざまなセキュリティ機能を無効にすることができます。 ほとんどの場合、開発者はこれらの機能を無効にする必要はありません。したがって、新しく作成した <webview> タグを使用します。
<webview> タグが適用される前に、Electron は will-attach-webview イベントを webContents ホスト上で発火します。 安全性の低いオプションを使用して webViews を作成しないようにするには、このイベントを使用します。
app.on('web-contents-created', (event, contents) => {\n contents.on('will-attach-webview', (event, webPreferences, params) => {\n // 未使用のプリロードスクリプトを削除するか、その場所が正当であることを確認する\n delete webPreferences.preload\n delete webPreferences.preloadURL\n\n // Node.js integration を無効にする\n webPreferences.nodeIntegration = false\n\n // ロードされる URL を確認する\n if (!params.src.startsWith('https://example.com/')) {\n event.preventDefault()\n }\n })\n})\n繰り返しになりますが、このリストは単にリスクを最小化するだけで、除去するものではありません。 ウェブサイトを表示することが目的であれば、ブラウザの方が安全性の高い選択肢になります。
\nアプリにナビゲートする必要がない場合、または既知のページにナビゲートするだけの場合は、ナビゲーションをその既知の範囲に完全に制限し、他の種類のナビゲーションを禁止することをお勧めします。
\nナビゲーションは一般的な攻撃方法です。 攻撃者が現在のページから移動するようにアプリを制御することができると、インターネット上の Web サイトを開くことをアプリに強制する可能性があります。 webContents がより安全に設定されている (nodeIntegration を無効にする、contextIsolation を有効にするなど) 場合でも、アプリにデタラメな Web サイトを開かせる アプリを悪用する方がはるかに簡単になります。
一般的な攻撃パターンは、攻撃者が、アプリでそのユーザに攻撃者のいずれかのページに移動するような方法で操作することを強いることです。 これは通常、リンク、プラグイン、またはその他のユーザー生成コンテンツを介して行われます。
\nアプリにナビゲーションが不要な場合は、will-navigate ハンドラ内 event.preventDefault() を呼び出すことができます。 アプリがどのページに移動するかがわかっている場合は、イベントハンドラで URL を確認し、予期している URL と一致する場合にのみナビゲーションを許可します。
URL には Node のパーサーを使用することを推奨します。 単純な文字列比較は時々だまされる可能性があります - startsWith('https://example.com') テストは https://example.com.attacker.com を通過させます 。
const URL = require('url').URL\n\napp.on('web-contents-created', (event, contents) => {\n contents.on('will-navigate', (event, navigationUrl) => {\n const parsedUrl = new URL(navigationUrl)\n\n if (parsedUrl.origin !== 'https://example.com') {\n event.preventDefault()\n }\n })\n})\n既知の一連のウインドウがある場合は、アプリ内での追加ウインドウの作成を制限することをお勧めします。
\nナビゲーションと同様、新しい webContents の作成は一般的な攻撃手段です。 攻撃者はそのままではページを開こうとしても開くことができないために、新しいウィンドウ、フレーム、その他のレンダラープロセスをより多くの権限で作成するようにアプリに強制しようとします。
あなたが作成する必要があると知っているものに加えてウィンドウを作成する必要がない場合は、作成を無効にするとノーコストで少しの追加のセキュリティが手に入ります。 これは1つの BrowserWindow を開き、実行時に任意の数の追加ウィンドウを開く必要がないアプリケーションで普遍的なケースです。
webContents は、新しいウインドウを作成する前に、ウインドウを開くハンドラー に委譲します。 ハンドラーは、他のパラメータの中の、ウィンドウを開くように要求された url とそのウィンドウを作成するために使用されたオプションを受け取ります。 ウインドウの作成を監視するハンドラを登録し、予期せぬウィンドウの作成は拒否するよう推奨します。
const { shell } = require('electron')\n\napp.on('web-contents-created', (event, contents) => {\n contents.setWindowOpenHandler(({ url }) => {\n // この例では、既定のブラウザでこのイベントのURLを開くように\n // オペレーティングシステムに依頼します。\n //\n // shell.openExternal に渡す URL を許可する基準ついては、\n // 以降の項目を参照してください。\n if (isSafeForExternalOpen(url)) {\n setImmediate(() => {\n shell.openExternal(url)\n })\n }\n\n return { action: 'deny' }\n })\n})\nopenExternal を使用しないShellの openExternal はデスクトップのネィティブユーティリティの指定した protocol URI で開けるようにします。 例えば、macOSのopen ターミナルコマンドユーティリティに似た機能で、URIとそのファイルタイプの関連に基づいた特定のアプリケーションで開きます。
openExternal の不適切な利用によって、そのユーザーのホストを危険に曝す可能性があります。 openExternalを信頼できないコンテンツで使用するとき、任意のコマンドの実行を許してしまう可能性があります。
// Bad\nconst { shell } = require('electron')\nshell.openExternal(USER_CONTROLLED_DATA_HERE)\n// Good\nconst { shell } = require('electron')\nshell.openExternal('https://example.com/index.html')\n常に最新バージョンの Electron を使用するように努力してください。 新しいメジャーバージョンがリリースされる度に、できるだけ早くアプリを更新しましょう。
\n古いバージョンの Electron、Chromium、Node.js で構築されたアプリケーションは、最新バージョンのこれらコンポーネントを使用しているアプリケーションよりも容易な標的です。 一般的に、古いバージョンの Chromium と Node.js ではより広いセキュリティ問題とエクスプロイトが適用できます。
\nChromium と Node.js はどちらも、何千人もの才能のある開発者によって構築された素晴らしい技術です。 人気を考えると、それらのセキュリティは同様に熟練したセキュリティ研究者によって慎重にテストされ分析されます。 これら研究者の多くは、脆弱性を責任を持って開示 しています。これは一般に、研究者が問題を公開する前に Chromium と Node.js に問題を修正する時間を与えることを意味します。 最新バージョンの Electron (および Chromium と Node.js) で実行している場合、潜在的なセキュリティ問題がそれほど広く知られておらずアプリケーションはより安全になります。
", "title": "セキュリティ、ネイティブ機能、あなたの責任", "description": ":警告: Node integration が有効な環境で、リモートコードの読み込みと実行を行ってはいけません。 代わりに、Node.js コードの実行にはローカルファイル (アプリケーションと一緒にパッケージ化されているもの) だけを使用してください。 remote コンテンツを表示するには、label String (optional) - The text to appear in this segment.icon NativeImage (optional) - The image to appear in this segment.enabled Boolean (optional) - Whether this segment is selectable. Default: true.portId String - Unique identifier for the port.portName String - Name of the port.displayName String - A string suitable for display to the user for describing this device.vendorId String - Optional USB vendor ID.productId String - Optional USB product ID.serialNumber String - The USB device serial number.usbDriverName String (optional) - Represents a single serial port on macOS can be enumerated by multiple drivers.deviceInstanceId String (optional) - A stable identifier on Windows that can be used for device permissions.scriptUrl String - The full URL to the script that this service worker runsscope String - The base URL that this service worker is active for.renderProcessId Number - The virtual ID of the process that this service worker is running in. This is not an OS level PID. This aligns with the ID set used for webContents.getProcessId().\n\nsession のアクティブなサービスワーカーからのイベントを問い合わせて受信します。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
ServiceWorkers クラスのインスタンスは、Session の serviceWorkers プロパティを使用してアクセスします。
以下がその例です。
\nconst { session } = require('electron')\n\n// すべてのサービスワーカーを取得します。\nconsole.log(session.defaultSession.serviceWorkers.getAllRunning())\n\n// ログを処理してサービスワーカー情報を取得します\nsession.defaultSession.serviceWorkers.on('console-message', (event, messageDetails) => {\n console.log(\n 'Got service worker message',\n messageDetails,\n 'from',\n session.defaultSession.serviceWorkers.getFromVersionID(messageDetails.versionId)\n )\n})\nServiceWorkers のインスタンスでは、以下のイベントが利用できます。
戻り値：
\nevent EventmessageDetails Object - コンソールメッセージに関する情報message String - 実際のコンソールメッセージversionId Number - ログメッセージを送信したサービスワーカーのバージョン IDsource String - このメッセージのソースの種別。 javascript、xml、network、console-api、storage、app-cache、rendering、security、deprecation、worker、violation、intervention、recommendation、other のいずれかにできます。level Number - 0 から 3 のログレベル。 順に verbose、info、warning、error に対応します。sourceUrl String - メッセージが送られてきた URLlineNumber Number - このコンソールメッセージのトリガーとなったソースの行番号サービスワーカーがコンソールに何かをロギングしたときに発生します。
\n戻り値：
\nevent Eventdetails Object - 登録されているサービスワーカーに関する情報scope String - サービスワーカーが登録している基底 URLサービスワーカーが登録されてたときに発生します。 navigator.serviceWorker.register('/sw.js') の呼び出しが成功した後や、Chrome 拡張機能が読み込まれた後に発生することがあります。
ServiceWorkers のインスタンスでは、以下のメソッドが利用できます。
serviceWorkers.getAllRunning()戻り値 Record<Number, ServiceWorkerInfo> - キーはサービスワーカーのバージョン ID、値は ServiceWorkerInfo オブジェクトで、そのサービスワーカーに関する情報です。
serviceWorkers.getFromVersionID(versionId)versionId Number戻り値 ServiceWorkerInfo - このサービスワーカーについての情報
サービスワーカーが存在しないか動作していない場合、このメソッドは例外を送出します。
", "title": "ServiceWorkerを有効にする", "description": "session のアクティブなサービスワーカーからのイベントを問い合わせて受信します。" }, "/docs/api/session": { "locale": "ja-JP", "slug": "session", "href": "/docs/api/session", "crowdinFileId": "256365", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/session.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nブラウザーセッション、クッキー、キャッシュ、プロキシの設定などを管理します。
\n
プロセス: Main
\nsession モジュールは、新しい session オブジェクトを作成するのに使用できます。
WebContents の session プロパティ、または session モジュールから、既存のページの session にアクセスすることもできます 。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nconst ses = win.webContents.session\nconsole.log(ses.getUserAgent())\nsession モジュールには以下のメソッドがあります。
session.fromPartition(partition[, options])partition Stringoptions Object (任意)cache Boolean - キャッシュを有効にするかどうか。戻り値 Session - partition 文字列からの Session のインスタンス。 同じ partition を持つ既存の session が存在する場合は、それが返されます。 それ以外の場合は、options で新しい session インスタンスが作成されます。
partition が persist: 始まりの場合、ページはアプリの全ページで利用可能な永続的なセッションを同じ partition で使用します。 persist: プレフィックスがない場合、ページは、インメモリセッションを使用します。 partition が空の場合は、アプリのデフォルトのセッションが返されます。
options で Session を作成するには、以前に partition との Session が使用されていないことを確認する必要があります。 既存の Session オブジェクトの options を変更する方法はありません。
session モジュールには以下のプロパティがあります。
session.defaultSessionアプリのデフォルトの Session オブジェクト。
\n\nセッションのプロパティを取得し、設定します。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
session モジュールでは、Session オブジェクトを作成できます。
const { session } = require('electron')\nconst ses = session.fromPartition('persist:name')\nconsole.log(ses.getUserAgent())\nSession のインスタンスでは、以下のイベントが利用できます。
戻り値：
\nevent Eventitem DownloadItemwebContents WebContentsElectron が webContents 内で item をダウンロードするときに発生します。
event.preventDefault() を呼び出すと、ダウンロードをキャンセルし、item はプロセスの次のティックから使用できなくなります。
const { session } = require('electron')\nsession.defaultSession.on('will-download', (event, item, webContents) => {\n event.preventDefault()\n require('got')(item.getURL()).then((response) => {\n require('fs').writeFileSync('/somewhere', response.body)\n })\n})\n戻り値：
\nevent Eventextension Extension拡張機能が読み込まれた後に発生します。 これは、拡張機能が \"有効な\" 拡張機能のセットに追加されるたびに発生します。 これは以下のものが含まれます。
\nSession.loadExtension から拡張機能が読み込まれるとき。chrome.runtime.reload())。戻り値：
\nevent Eventextension Extension拡張機能が取り除かれた後に発生します。 これは Session.removeExtension が呼ばれたときに発生します。
戻り値：
\nevent Eventextension Extension拡張機能が読み込まれ、必要なブラウザの状態がすべて初期化され、拡張機能のバックグラウンドページの開始をサポートするようになった後に発生します。
\n戻り値：
\nevent EventpreconnectUrl String - レンダラーによって事前接続に要求されている URL。allowCredentials Boolean - レンダラーが接続に資格情報を含めることを要求している場合は true です (詳細については、仕様 を参照してください)。一般的に リソースヒント が原因で、レンダリングプロセスが URL への事前接続を要求したときに生成されます。
\n戻り値：
\nevent EventlanguageCode String - 辞書ファイルの言語コードhunspell 辞書ファイルの初期化に成功したときに発生します。 これはファイルをダウンロードした後に発生します。
\n戻り値：
\nevent EventlanguageCode String - 辞書ファイルの言語コードhunspell 辞書ファイルのダウンロードが始まったときに発生します
\n戻り値：
\nevent EventlanguageCode String - 辞書ファイルの言語コードhunspell 辞書ファイルのダウンロードに成功したときに発生します
\n戻り値：
\nevent EventlanguageCode String - 辞書ファイルの言語コードhunspell 辞書ファイルのダウンロードが失敗したときに発生します。 失敗の詳細は、netlog を収集してダウンロードリクエストを調べる必要があります。
\n戻り値：
\nevent Eventdetails ObjectdeviceList HIDDevice[]frame WebFrameMaincallback FunctiondeviceId String | null (任意)navigator.hid.requestDevice の呼び出し時に HID デバイスを選択する必要がある場合に発生します。 callback は選択する deviceId で呼び出してください。callback に引数を渡さなければ、リクエストをキャンセルします。 また、ses.setPermissionCheckHandler(handler) や ses.setDevicePermissionHandler(handler)` を使うことで、navigator.hid の権限をさらに管理できます。
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // ここにロジックを追加して、HID の選択を許可すべきかどうかを判断します\n return true\n }\n return false\n })\n\n // 任意で、以前に永続化されたデバイスを永続ストアから取得します\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // このタイプのデバイスを常に許可します (これにより最初の `navigator.hid.requestDevice` の呼び出しを省略できます)\n return true\n }\n\n // 過去に許可されたデバイスのリストを検索します\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\n戻り値：
\nevent Eventdetails Objectdevice HIDDevice[]frame WebFrameMain新しい HID デバイスが利用可能になったときに発生します。 例えば、新しい USB デバイスが接続されたときに発生します。
\nこのイベントは、navigator.hid.requestDevice が呼び出されて select-hid-device が発火した後にのみ発生します。
戻り値：
\nevent Eventdetails Objectdevice HIDDevice[]frame WebFrameMainHID デバイスが接続解除されたときに発生します。 例えば、このイベントは USB デバイスが取り除かれたときに発生します。
\nこのイベントは、navigator.hid.requestDevice が呼び出されて select-hid-device が発火した後にのみ発生します。
戻り値：
\nevent EventportList SerialPort[]webContents WebContentscallback FunctionportId Stringnavigator.serial.requestPort の呼び出し時にシリアルポートを選択する必要がある場合に発生します。 callback は選んだ portId で呼び出されなければなりません。空の文字列を callback に渡すとリクエストがキャンセルされます。 さらに、ses.setPermissionCheckHandler(handler) を serial パーミッションで使用することで navigator.serial のパーミッションを管理できます。
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({\n width: 800,\n height: 600\n })\n win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {\n event.preventDefault()\n const selectedPort = portList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n if (!selectedPort) {\n callback('')\n } else {\n callback(selectedPort.portId)\n }\n })\n})\n戻り値：
\nevent Eventport SerialPortwebContents WebContentsnavigator.serial.requestPort が呼び出され新しいシリアルポートが利用可能になった場合に、select-serial-port が発生した後に発生します。 例えば、このイベントは新しい USB デバイスが接続されたときに発生します。
戻り値：
\nevent Eventport SerialPortwebContents WebContentsnavigator.serial.requestPort が呼び出されシリアルポートが削除された場合に、select-serial-port が発生した後に発生します。 例えば、このイベントは USB デバイスが取り除かれたときに発生します。
Session のインスタンスでは、以下のメソッドが利用できます。
ses.getCacheSize()戻り値 Promise<Integer> - バイト単位の、session の現在のキャッシュサイズ。
ses.clearCache()戻り値 Promise<void> - キャッシュクリア操作が完了すると実行されます。
セッションの HTTP キャッシュをクリアします。
\nses.clearStorageData([options])options Object (任意)origin String (任意) - window.location.origin の表記の scheme://host:port に従わなければいけません。storages String - クリアするストレージの種類。appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage を含めることができます。 指定しない場合は、全種類のストレージをクリアします。quotas String - クリアするクォータの種類。temporary, persistent, syncable を含むことができます。 指定しない場合は、全てのクオータをクリアします。戻り値 Promise<void> - ストレージデータがクリアされると実行されます。
ses.flushStorageData()未書き込みの DOM ストレージのデータをディスクに書き込みます。
\nses.setProxy(config)config Objectmode String (任意) - そのプロキシのモードです。 direct、auto_detect、pac_script、fixed_servers、system のうちの一つであるべきです。 指定しない場合は、他の指定オプションに基づいて自動決定されます。direct direct モードでは、すべての接続はプロキシを介さずに直接作成されます。auto_detect auto_detect モードでは、プロキシの設定は http://wpad/wpad.dat でダウンロードできる PAC スクリプトによって決定されます。pac_script pac_script モードでは、プロキシの設定は pacScript で指定された URL から取得される PAC スクリプトによって決定されます。 これは pacScript が指定されている場合のデフォルトモードです。fixed_servers fixed_servers モードでは、プロキシの設定を proxyRules で指定します。 これは proxyRules が指定されている場合のデフォルトモードです。system system モードでは、プロキシ構成をオペレーティングシステムから取得します。 system モードはプロキシ構成を設定しない場合とは異なりますのでご注意ください。 後者の場合、プロキシ設定に影響を与えるコマンドラインオプションがない場合にのみ、 Electron はシステム設定にフォールバックします。pacScript String (任意) - PAC ファイルに関連付けられた URL。proxyRules String (任意) - 使用するプロキシを示すルール。proxyBypassRules String (任意) - プロキシ設定をバイパスする URL を示すルール。戻り値 Promise<void> - プロキシ設定処理が完了すると実行されます。
プロキシ設定を設定します。
\nmode を指定せずに pacScript とproxyRules をどちらも一緒に指定した場合、proxyRules は オプションは無視され pacScript の設定が適用されます。
以前のプロキシでプールされたソケットが将来のリクエストで再利用されるのを防ぐには、現在フライト中の接続を閉じるために ses.closeAllConnections が必要でしょう。
proxyRules は以下のルールに従う必要があります。
proxyRules = schemeProxies[\";\"<schemeProxies>]\nschemeProxies = [<urlScheme>\"=\"]<proxyURIList>\nurlScheme = \"http\" | \"https\" | \"ftp\" | \"socks\"\nproxyURIList = <proxyURL>[\",\"<proxyURIList>]\nproxyURL = [<proxyScheme>\"://\"]<proxyHost>[\":\"<proxyPort>]\n以下がその例です。
\nhttp=foopy:80;ftp=foopy2 - http:// URL には HTTP プロキシ foopy:80 を、ftp:// URL には HTTP プロキシ foopy2:80 を使用する。foopy:80 - すべての URL に foopy:80 HTTP プロキシを使用する。foopy:80,bar,direct:// - すべての URL に foopy:80 HTTP プロキシを使用する。 foopy:80 が使用できない場合は bar にフェイルオーバーし、その後はプロキシを使用しません。socks4://foopy - すべての URL に SOCKS 4 プロキシ foopy:1080 を使用する。http=foopy,socks5://bar.com - HTTP の URL には HTTP プロキシ foopy を使用し、foopy が使用できない場合は SOCKS 5 プロキシ bar.com にフェイルオーバーします。http=foopy,socks5://bar.com - HTTP の URL には HTTP プロキシ foopy を使用し、foopy が使用できない場合はプロキシを使用しません。http=foopy;socks=foopy2 - HTTP の URL には HTTP プロキシ foopy を、ほかの URLには socks4://foopy2 を使用します。proxyBypassRules は以下に説明されているコンマ区切りのルールのリストです。
[ URL_SCHEME \"://\" ] HOSTNAME_PATTERN [ \":\" <port> ]
HOSTNAME_PATTERN パターンに一致するすべてのホスト名のマッチ。
\n例: \"foobar.com\", \"foobar.com\", \".foobar.com\", \"foobar.com:99\", \"https://x..y.com:99\"
\n\".\" HOSTNAME_SUFFIX_PATTERN [ \":\" PORT ]
特定のドメインサフィックスのマッチ。
\n例: \".google.com\", \".com\", \"http://.google.com\"
\n[ SCHEME \"://\" ] IP_LITERAL [ \":\" PORT ]
IP アドレスリテラルである URL のマッチ。
\n例: \"127.0.1\", \"[0:0::1]\", \"[::1]\", \"http://[::1]:99\"
\nIP_LITERAL \"/\" PREFIX_LENGTH_IN_BITS
指定された範囲内の IP リテラルに一致する URL のマッチ。 IP の範囲は CIDR 表記で指定します。
\n例: \"192.168.1.1/16\", \"fefe:13::abc/33\".
\n<local>
ローカルアドレスのマッチ。 <local> の意味は、ホストが \"127.0.0.1\"、\"::1\"、\"localhost\" のいずれかに一致するかどうかです。
ses.resolveProxy(url)url URL戻り値 Promise<String> - url のプロキシ情報で実行されます。
ses.forceReloadProxyConfig()戻り値 Promise<void> - プロキシサービスのすべての内部状態がリセットされたときに解決します。すでに利用可能な場合は最新のプロキシ設定が再適用されます。 プロキシモードが pac_script の場合、再び pacScript から PAC スクリプトが取得されます。
ses.setDownloadPath(path)path String - ダウンロード場所。ダウンロードの保存ディレクトリを設定します。 デフォルトでは、ダウンロードディレクトリは各アプリフォルダの下の ダウンロード (Downloads) になります。
ses.enableNetworkEmulation(options)options Objectoffline Boolean (任意) - ネットワークの停止をエミュレートするかどうか。 省略値は false です。latency Double (任意) - RTT ミリ秒。 省略値は 0 で、このときレイテンシのスロットルは無効化されます。downloadThroughput Double (任意) - 下りレート Bps。 省略値は 0 で、このときダウンロードのスロットルは無効化されます。uploadThroughput Double (任意) - 上りレート Bps。 省略値は 0 で、このときアップロードのスロットルは無効化されます。session の指定された構成でネットワークをエミュレートします。
// 50kbps のスループットと 500ms の待ち時間で GPRS 接続をエミュレートする。\nwindow.webContents.session.enableNetworkEmulation({\n latency: 500,\n downloadThroughput: 6400,\n uploadThroughput: 6400\n})\n\n// ネットワークの停止をエミュレートする。\nwindow.webContents.session.enableNetworkEmulation({ offline: true })\nses.preconnect(options)options Objecturl String - 事前接続する URL。 ソケットの開通に関係しているのはオリジンのみです。numSockets Number (任意) - 事前接続するソケット数。 1 から 6 にしてください。 省略値は 1 です。指定された数のソケットをオリジンに事前接続します。
\nses.closeAllConnections()戻り値 Promise<void> - すべての接続が閉じられた時に解決されます。
注: 現在フライト中のすべてのリクエストが終了/失敗します。
\nses.disableNetworkEmulation()session に対して既にアクティブなネットワークエミュレーションを無効にします。 元のネットワーク構成にリセットします。
ses.setCertificateVerifyProc(proc)proc Function | nullrequest Objecthostname Stringcertificate CertificatevalidatedCertificate CertificateverificationResult String - Chromium からの認証結果。errorCode Integer - エラーコード。callback FunctionverificationResult Integer - こちら の証明書エラーコードのうち一つの値を取ります。 証明書エラーコードの他に、以下の特殊コードを取ることがあります。0 - 成功を示し、証明書の透明性の検証を無効にします。-2 - 失敗を示します。-3 - Chromium からの認証結果を使用します。session の証明書検証プロセスを設定し、サーバー証明書の検証が要求されるたびにproc を proc(request, callback) で呼びます。 callback(0) を呼ぶと証明書を承認し、callback(-2) を呼ぶとそれを拒否します。
setCertificateVerifyProc(null) を呼び出すと、デフォルトの証明書検証プロシージャに戻ります。
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.webContents.session.setCertificateVerifyProc((request, callback) => {\n const { hostname } = request\n if (hostname === 'github.com') {\n callback(0)\n } else {\n callback(-2)\n }\n})\n\n\n注意: このプロシージャの結果は、ネットワークサービスによってキャッシュされます。
\n
ses.setPermissionRequestHandler(handler)handler Function | nullwebContents WebContents - 権限を要求している WebContents。 リクエストがサブフレームからのものである場合、リクエストのオリジンを確認するためには requestingUrl を使用する必要があることに注意してください。permission String - 要求されたパーミッションのタイプ。clipboard-read - クリップボードからの読み取りアクセスを要求する。media - カメラ、マイク、スピーカーなどのメディアデバイスへのアクセスを要求する。display-capture - 画面キャプチャへのアクセスをリクエストします。mediaKeySystem - DRM で保護されたコンテンツへのアクセスを要求します。geolocation - ユーザーの現在地へのアクセスを要求する。notifications - 通知の作成とユーザーのシステムトレイに表示する機能を要求します。midi - webmidi API で MIDI アクセスを要求します。midiSysex - webmidi API でシステム専用メッセージの使用を要求する。pointerLock - 入力方法としてマウスの動きを直接解釈するよう要求する。 詳細はこちら をクリックしてください。fullscreen - アプリがフルスクリーンモードになるよう要求する。openExternal - 外部アプリケーションでリンクを開くように要求する。unknown - 認識されない認可リクエストcallback FunctionpermissionGranted Boolean - 権限の許可か拒否.details Object - このプロパティの一部は、特定の権限タイプでのみ使用できます。session の、権限の要求に応答するために使用できるハンドラを設定します。 callback(true) を呼ぶと権限が許可され callback(false) を呼ぶと拒否されます。 ハンドラをクリアするには、setPermissionRequestHandler(null) を呼びます。 注意として、完全な認可処理にするには setPermissionCheckHandler も実装しなければなりません。 ほとんどのウェブ API は権限の確認を行い、確認が拒否されている場合は認可のリクエストを行います。
const { session } = require('electron')\nsession.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {\n if (webContents.getURL() === 'some-host' && permission === 'notifications') {\n return callback(false) // 拒否。\n }\n\n callback(true)\n})\nses.setPermissionCheckHandler(handler)handler Function\\webContents (WebContents | null) - 権限を確認している WebContents リクエストがサブフレームからのものである場合、リクエストのオリジンを確認するためには requestingUrl を使用する必要があることに注意してください。 すべてのクロスオリジンサブフレームによる権限の確認はハンドラの webContents に null が渡されますが、notifications の確認のような、ある特定の権限の確認では常に null が渡されます。 embeddingOrigin と requestingOrigin を使用して、所有しているフレームと要求しているフレームがそれぞれどのオリジンにあるかを判断する必要があります。permission String - 権限確認の種別です。 有効な値は midiSysex, notifications, geolocation, media, mediaKeySystem, midi, pointerLock, fullscreen, openExternal, hid, serial のいずれかです。requestingOrigin String - 権限チェックのオリジン URLdetails Object - このプロパティの一部は、特定の権限タイプでのみ使用できます。embeddingOrigin String (任意) - 権限の確認をしたフレームのオリジン。 権限の確認を行うクロスオリジンのサブフレームでのみ設定されます。securityOrigin String (任意) - media の確認でのセキュリティオリジン。mediaType String (任意) - 要求されたメディアアクセスの型で、video、audio か unknown になります。requestingUrl String (任意) - リクエストしているフレームが読み込んだ最後の URL. 権限の確認を行うクロスオリジンのサブフレームでは提供されません。isMainFrame Boolean - リクエストしたフレームがメインフレームかどうかsession の、権限のチェックに応答するために使用できるハンドラを設定します。 trueを返すと権限を許可し、false を返すとそれを拒否します。 注意として、完全な認可処理にするには setPermissionRequestHandler も実装しなければなりません。 ほとんどのウェブ API は権限の確認を行い、確認が拒否されている場合は認可のリクエストを行います。 ハンドラをクリアするには、 setPermissionCheckHandler(null) を呼びます。
const { session } = require('electron')\nconst url = require('url')\nsession.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {\n return true // 認可\n }\n\n return false // 拒否\n})\nses.setDevicePermissionHandler(handler)handler Function\\details ObjectdeviceType String - 許可が求められているデバイスのタイプで、hid になります。origin String - デバイス権限チェックのオリジン URL。device HIDDevice - 許可を求められているデバイス。frame WebFrameMain - デバイスの許可を確認している WebFrameMain。デバイスの権限チェックの応答に使用できるハンドラを session に設定します。 true を返すとデバイスに権限を許可し、false を返すとそれを拒否します。 ハンドラを消去するには setDevicePermissionHandler(null) と呼び出します。 このハンドラは、最初にデバイスへの許可の呼び出しを (navigator.hid.requestDevice などを介して) せずに、デバイスへのデフォルト権限を提供するために利用できます。 このハンドラが定義されていない場合、(navigator.hid.requestDevice などを介した) デバイスの選択において付与された権限をデフォルトのデバイス権限として使用します。 さらに、Electron のデフォルト動作では付与されたデバイス権限を対応する WebContents が有効の間だけ保存します。 より長期間の保存が必要な場合、開発者は付与されたデバイスのパーミッションを保存し (select-hid-device イベントを処理するときなど)、setDevicePermissionHandler でそのストレージから読み出しできます。
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // ここにロジックを追加して、HID の選択を許可すべきかどうかを判断します\n return true\n }\n return false\n })\n\n // 任意で、以前に永続化されたデバイスを永続ストアから取得します\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // このタイプのデバイスを常に許可します (これにより最初の `navigator.hid.requestDevice` の呼び出しを省略できます)\n return true\n }\n\n // 過去に許可されたデバイスのリストを検索します\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nses.clearHostResolverCache()戻り値 Promise<void> - 操作が完了すると実行されます。
ホスト解決のキャッシュをクリアします。
\nses.allowNTLMCredentialsForDomains(domains)domains String - 統合認証が有効であるサーバーのコンマ区切りのリスト。HTTP NTLM またはネゴシエート認証の資格情報を常に送信するかどうかを動的に設定します。
\nconst { session } = require('electron')\n// 統合認証に、`example.com`、`foobar.com`、`baz`\n// で終わる URL を考えます。\nsession.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')\n\n// 統合認証に、すべての URL を考えます。\nsession.defaultSession.allowNTLMCredentialsForDomains('*')\nses.setUserAgent(userAgent[, acceptLanguages])userAgent StringacceptLanguages String (任意)このセッションの userAgent と acceptLanguages をオーバーライドします。
acceptLanguages は、言語コードのカンマ区切りリスト (例: \"en-US, fr, de, ko, zh-CN, ja\") でなければなりません。
これは既存の WebContents には影響しません。それぞれの WebContents は webContents.setUserAgent を使用してセッション全体のユーザーエージェントをオーバーライドできます。
ses.isPersistent()戻り値 Boolean - このセッションが持続的なものであるかどうか。 BrowserWindow のデフォルトの webContents セッションは持続的です。 パーティションからセッションを作成する場合、persist: で始まるセッションは持続化され、他のセッションは一時的なものになります。
ses.getUserAgent()戻り値 String - このセッションのユーザエージェント。
ses.setSSLConfig(config)config ObjectminVersion String (任意) - tls1、tls1.1、tls1.2、tls1.3 のいずれかにできます。 これはリモートサーバーに接続する際に許可する最小の SSL バージョンです。 省略値は tls1 です。maxVersion String (任意) - tls1.2 か tls1.3 にできます。 これはリモートサーバーに接続する際に許可する最大の SSL バージョンです。 省略値は tls1.3 です。disabledCipherSuites Integer - ネット組み込みポリシーで無効化されたものに加えて、使用を禁止すべき暗号スートを明示したリスト。 0xAABB のようなリテラルの形式をサポートしています。ここで AA は cipher_suite[0] であり、BB は cipher_suite[1] です。これは RFC 2246 のセクション 7.4.1.2 で定義されています。 識別不可かつパース可能な暗号スートの形式であっても、エラーは返しません。 例: TLS_RSA_WITH_RC4_128_MD5 を無効にするには、0x0004 を指定し、TLS_ECDSA_WITH_RC4_128_SHA を無効にするには 0xC002 を指定します。 注意として、TLSv1.3 の暗号化方式はこの仕組みで無効にできません。セッションの SSL 構成を設定します。 それ以降のネットワークリクエストではすべて新しい構成を使用します。 既存のネットワーク接続 (WebSocket 接続など) は終了しませんが、プール内の古いソケットは新しい接続に再利用されません。
\nses.getBlobData(identifier)identifier String - 有効な UUID。戻り値 Promise<Buffer> - blob データで実行されます。
ses.downloadURL(url)url Stringurl にあるリソースのダウンロードを初期化します。 この API は、will-download イベントでアクセスできる DownloadItem を生成します。
注釈: これは webContents.downloadURL と異なり、ページのオリジンに関連するセキュリティチェックを実行しません。
ses.createInterruptedDownload(options)options Objectpath String - ダウンロードの絶対パス。urlChain String[] - ダウンロードの完全な URL チェーン。mimeType String (任意)offset Integer - ダウンロードの範囲の始端。length Integer - ダウンロードの長さ。lastModified String (任意) - ヘッダの最終更新日の値。eTag String (任意) - ヘッダの ETag の値。startTime Double (任意) - ダウンロードが開始されたときの UNIX エポックからの秒数。以前の Session からの、cancelled または interrupted なダウンロードの再開を許可します。 APIは、will-download イベントでアクセスできる DownloadItem を生成します。 DownloadItem はそれに関連付けられた WebContents を持たず、初期状態は interrupted です。 DownloadItem 上の resume API を呼ぶことでのみ、ダウンロードが開始されます。
ses.clearAuthCache()戻り値 Promise<void> - session の HTTP 認証キャッシュがクリアされると実行されます。
ses.setPreloads(preloads)preloads String[] - プリロードスクリプトへの絶対パスの配列通常の preload スクリプトが実行される直前に、このセッションに関連するすべてのウェブコンテンツで実行されるスクリプトを追加します。
ses.getPreloads()戻り値 String[] - 登録されているプリロードスクリプトへのパスの配列。
ses.setSpellCheckerEnabled(enable)enable Boolean組み込みスペルチェッカーを有効にするかどうかを設定します。
\nses.isSpellCheckerEnabled()戻り値 Boolean - 組み込みスペルチェッカーが有効化されているかどうか。
ses.setSpellCheckerLanguages(languages)languages String[] - スペルチェッカーを有効にする言語コードの配列。組み込みスペルチェッカーは、ユーザーが入力している言語を自動的に検出しません。 スペルチェッカーが単語を正しくチェックするには、言語コードの配列でこの API を呼び出す必要があります。 ses.availableSpellCheckerLanguages プロパティで、サポートしている言語コードのリストを取得できます。
注意: macOS では、OS のスペルチェッカーが使用されて言語が自動的に検出されます。 この API は、macOS では何もしません。
\nses.getSpellCheckerLanguages()戻り値 String[] - スペルチェッカーが有効になっている言語コードの配列。 このリストが空の場合、スペルチェッカーは en-US の使用へフォールバックします。 この設定が空のリストである場合、Electron は起動時に既定で現在の OS ロケールをこの設定に追加しようとします。 この設定は再起動後も持続します。
注意: macOS では、OS のスペルチェッカーが使用されて独自の言語リストを返します。 この API は、macOS では何もしません。
\nses.setSpellCheckerDictionaryDownloadURL(url)url String - Electron が hunspell 辞書をダウンロードする基底 URL。デフォルトでは、Electron は Chromium CDN から hunspell 辞書をダウンロードします。 この動作をオーバーライドする場合は、この API を使用して、独自ホスト版の hunspell 辞書を辞書ダウンローダーが指すようにすることができます。 ホストする必要があるファイルのリリースごとに hunspell_dictionaries.zip ファイルをファイルサーバーで公開します。ファイルサーバーは 大文字と小文字を区別しない ようにして、元通りの大文字小文字のファイルが入った ZIP ファイルと、全て小文字のファイル名にしたものの二通りを用意する必要があります。
hunspell_dictionaries.zip が https://example.com/dictionaries/language-code.bdic に存在して利用できる場合、ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/') を呼び出すことになります。 末尾のスラッシュに注意してください。 辞書への URL は、${url}${filename} の形式になります。
注意: macOS では、OS のスペルチェッカーが使用されるため辞書ファイルをダウンロードしません。 この API は、macOS では何もしません。
\nses.listWordsInSpellCheckerDictionary()戻り値 Promise<String[]> - アプリのカスタム辞書の全単語の配列。 ディスクから完全な辞書が読み込まれたときに解決されます。
ses.addWordToSpellCheckerDictionary(word)word String - 辞書に追加したい単語戻り値 Boolean - 単語がカスタム辞書に正常に書き込まれたかどうか。 この API は、持続的でない (一時的な) セッションでは動作しません。
注釈: macOS と Windows 10 では、この単語は OS カスタム辞書にも書き込まれます
\nses.removeWordFromSpellCheckerDictionary(word)word String - 辞書から削除したい単語戻り値 Boolean - 単語がカスタム辞書から正常に削除されたかどうか。 この API は、持続的でない (一時的な) セッションでは動作しません。
注釈: macOS と Windows 10 では、この単語は OS カスタム辞書からも削除されます
\nses.loadExtension(path[, options])path String - 解凍されていない Chrome 拡張機能を含んだディレクトリへのパスoptions Object (任意)allowFileAccess Boolean - 拡張機能が file:// プロトコルでローカルファイルを読み込んで file:// ページにコンテンツスクリプトを注入することを許可するかどうか。 これは、例えば file:// URL でデベロッパー ツール拡張機能を読み込むために必要です。 省略値は、false です。戻り値 Promise<Extension> - 拡張機能が読み込まれたときに解決されます。
このメソッドは、拡張機能を読み込めなかった場合に例外を発生させます。 拡張機能のインストール時に警告が発生した場合 (Electron が未サポートの API を拡張機能が要求した場合など) は、コンソールにログが記録されます。
\n注意として、Electron は Chrome 拡張機能の API のすべてをサポートしていません。 サポート内容の詳細については、サポートしている拡張機能 API を参照してください。
\n注意として、以前のバージョンの Electron では、読み込まれた拡張機能は以降のアプリケーション実行のために記憶されます。 現在はそうなっていません。拡張機能を読み込みたい場合は、アプリを起動するたびに loadExtension を呼び出す必要があります。
const { app, session } = require('electron')\nconst path = require('path')\n\napp.on('ready', async () => {\n await session.defaultSession.loadExtension(\n path.join(__dirname, 'react-devtools'),\n // allowFileAccess は、file:// URL でのデベロッパー ツール拡張機能の読み込みに必要です。\n { allowFileAccess: true }\n )\n // 注意として、React デベロッパー ツール拡張機能を使用するにはそのコピーを\n // ダウンロードして解凍する必要があります。\n})\nこの API は、パッケージした (.crx) 拡張機能の読み込みをサポートしていません。
\n注: このAPIは app モジュールの ready イベントが発生する前には呼び出すことはできません。
注: インメモリ (一時的な) セッションでの拡張機能読み込みはサポートされておらず、エラーが送出されます。
\nses.removeExtension(extensionId)extensionId String - 削除する拡張機能の ID拡張機能を取り除きます。
\n注: このAPIは app モジュールの ready イベントが発生する前には呼び出すことはできません。
ses.getExtension(extensionId)extensionId String - クエリする拡張機能の ID戻り値 Extension | null - 指定した ID である読み込まれた拡張機能。
注: このAPIは app モジュールの ready イベントが発生する前には呼び出すことはできません。
ses.getAllExtensions()戻り値 Extension[] - 読み込まれた拡張機能のリスト。
注: このAPIは app モジュールの ready イベントが発生する前には呼び出すことはできません。
ses.getStoragePath()String | null 型で、このセッションのデータが保存されているディスクのファイルシステムの絶対パスを示します。 インメモリセッションの場合、これは null を返します。
Session のインスタンスには以下のプロパティがあります。
ses.availableSpellCheckerLanguages 読み出し専用この String [] 配列は利用可能な既知のすべてのスペルチェッカー言語で構成されます。 この配列にない言語コードを setSpellCheckerLanguages API に提供すると、エラーが発生します。
ses.spellCheckerEnabledBoolean 型で、組み込みスペルチェッカーが有効かどうかを示します。
ses.storagePath 読み出し専用String | null 型で、このセッションのデータが保存されているディスクのファイルシステムの絶対パスを示します。 インメモリセッションの場合、これは null を返します。
ses.cookies 読み出し専用このセッションの Cookies オブジェクト。
ses.serviceWorkers 読み出し専用このセッションの ServiceWorkers オブジェクト。
ses.webRequest 読み出し専用このセッションの WebRequest オブジェクト。
ses.protocol 読み出し専用このセッションの Protocol オブジェクト。
const { app, session } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const protocol = session.fromPartition('some-partition').protocol\n if (!protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })) {\n console.error('Failed to register protocol')\n }\n})\nses.netLog 読み出し専用このセッションの NetLog オブジェクト。
const { app, session } = require('electron')\n\napp.whenReady().then(async () => {\n const netLog = session.fromPartition('some-partition').netLog\n netLog.startLogging('/path/to/net-log')\n // ネットワークイベントの後\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nデバッグシンボルは、よりよいデバッグセッションができるようにします。 それらは実行形式と動的ライブラリに含まれる関数についての情報を持ち、クリーンなコールスタックを取得するための情報を提供します。 Symbol Server を使用すると、デバッガは大きなデバッグファイルをユーザにダウンロードさせることなく、正しいシンボル、バイナリ、そしてソースを自動的にロードできます。 このサーバーは Microsoft's symbol server のように機能するもので、そこにあるドキュメントが役立つかもしれません。
\nリリースされた Electron ビルドは非常に最適化されているため、デバッグは必ずしも容易ではないことに注意してください。 デバッガはすべての変数の内容は表示できませんし、インラインに展開されたり、末尾再帰やその他のコンパイラによる最適化により実行経路は奇妙に見えるはずです。 唯一の回避策は、最適化されていないローカルビルドをビルドすることです。
\nElectron の公式シンボルサーバの URL は https://symbols.electronjs.org です。 この URL に直接アクセスすることはできません。デバッグツールのシンボルパスに追加する必要があります。 以下の例では、ローカルキャッシュディレクトリを使用してサーバーから PDB を繰り返し取得しないようにしています。 c:\\code\\symbols をコンピュータ上の適切なキャッシュディレクトリに置き換えてください。
Windbg シンボルパスは、アスタリスク文字で区切られた文字列値で構成されています。 Electron シンボルサーバーのみを使用するには、以下のシンボルパスに次のエントリを追加します (注意: c:\\code\\symbols をコンピュータ上の書き込み可能なディレクトリに置き換えてください)。
SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\nWindbg メニューを使用するか、または .sympath コマンドを入力して、環境内でこの文字列を _NT_SYMBOL_PATH に設定します。 Microsoft のシンボルサーバーからもシンボルを取得したい場合は、先にそれを並べる必要があります。
SRV*c:\\code\\symbols\\*https://msdl.microsoft.com/download/symbols;SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\n 設定\">
Windbg で次のコマンドを入力して、シンボルが読み込まれない理由を表示します。
\n> !sym noisy\n> .reload /f electron.exe\nShareMenu クラスは、macOS 上で 共有メニュー を作成し、現在のコンテキストからアプリやソーシャルメディアアカウント、その他のサービスに情報を共有するために使用できます。
他のメニューのサブメニューとして共有メニューを含めるには、MenuItem の shareMenu ロールを使用してください。
\n\nmacOS での共有メニューを作成します。
\n
プロセス: Main
\nnew ShareMenu(sharingItem)sharingItem SharingItem - 共有するアイテム。新しい共有メニューを作成します。
\nshareMenu オブジェクトには以下のメソッドがあります。
shareMenu.popup([options])options PopupOptions (任意)browserWindow BrowserWindow (任意) - 省略値はフォーカスされたウインドウです。x Number (任意) - 既定ではマウスカーソルの現在位置です。 y が宣言されている場合は宣言する必要があります。y Number (任意) - 既定ではマウスカーソルの現在位置です。 x が宣言されている場合は宣言する必要があります。positioningItem Number (任意) macOS - マウスカーソルの位置に配置するメニューアイテムのインデックス。 既定値は -1 です。callback Function (任意) - メニューが閉じたしたときに呼ばれます。この menu を BrowserWindow 内のコンテキストメニューとしてポップアップします。
shareMenu.closePopup([browserWindow])browserWindow BrowserWindow (任意) - 省略値はフォーカスされたウインドウです。browserWindow 内のこのコンテキストメニューを閉じます。
id String - The unique id of the shared worker.url String - The url of the shared worker.texts String - An array of text to share.filePaths String - An array of files to share.urls String - An array of URLs to share.\n\nデフォルトのアプリケーションを使用してファイルと URL を管理します。
\n
プロセス: メイン, レンダラー (非サンドボックス時のみ)
\nshell モジュールは、デスクトップの統合に関する機能を提供します。
以下はユーザの既定のブラウザで URL を開く例です。
\nconst { shell } = require('electron')\n\nshell.openExternal('https://github.com')\n注: shell モジュールはレンダラープロセスで使用できますが、サンドボックス化されたレンダラーでは機能しません。
shell モジュールには以下のメソッドがあります。
shell.showItemInFolder(fullPath)fullPath String指定したファイルをファイルマネージャに表示します。 可能であれば、ファイルを選択します。
\nshell.openPath(path)path String戻り値 Promise<String> - 障害が発生した場合、その障害に対応するエラーメッセージを含む文字列で解決します。それ以外では \"\" になります。
指定したファイルをデスクトップの既定の方法で開きます。
\nshell.openExternal(url[, options])url String - Windows では最大2081文字です。options Object (任意)activate Boolean (任意) macOS - true で開いたアプリケーションを前面に表示します。 省略値は true です。workingDirectory String (任意) Windows - 作業ディレクトリ。戻り値 Promise<void>
指定した外部プロトコルの URL をデスクトップ既定の方法で開きます。 (例えば、mailto: の URL はユーザのデフォルトのメールエージェントになります)。
\nshell.trashItem(path)path String - ゴミ箱へ送るアイテムのパス。戻り値 Promise<void> - 操作が完了したときに解決します。 要求されたアイテムの削除中にエラーが発生した場合に拒否します。
これにより、パスのものを OS 固有のゴミ箱の場所 (macOS ではゴミ箱、Windows ではごみ箱、Linux ではデスクトップ環境固有の場所) へ移動させます。
\nshell.beep()通知音を再生します。
\nshell.writeShortcutLink(shortcutPath[, operation], options) WindowsshortcutPath Stringoperation String (任意) - 省略値は create で、以下の値のいずれかにできます。create - 新しいショートカットを作成し、必要であれば上書きします。update - 既にあるショートカットのみを、指定したプロパティで更新します。replace - 既にあるショートカットを上書きし、存在しなければ失敗します。options ShortcutDetails戻り値 Boolean - ショートカットが正常に作成されたかどうか.
shortcutPath のショートカットリンクを作成か更新します。
shell.readShortcutLink(shortcutPath) WindowsshortcutPath String戻り値 ShortcutDetails
shortcutPath のショートカットリンクを解決します。
エラーが発生すると、例外がスローされます。
", "title": "shell", "description": "デフォルトのアプリケーションを使用してファイルと URL を管理します。" }, "/docs/api/structures/shortcut-details": { "locale": "ja-JP", "slug": "shortcut-details", "href": "/docs/api/structures/shortcut-details", "crowdinFileId": "256509", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/shortcut-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "target String - The target to launch from this shortcut.cwd String (optional) - The working directory. Default is empty.args String (optional) - The arguments to be applied to target when launching from this shortcut. Default is empty.description String (optional) - The description of the shortcut. Default is empty.icon String (optional) - The path to the icon, can be a DLL or EXE. icon and iconIndex have to be set together. Default is empty, which uses the target's icon.iconIndex Number (optional) - The resource ID of icon when icon is a DLL or EXE. Default is 0.appUserModelId String (optional) - The Application User Model ID. Default is empty.toastActivatorClsid String (optional) - The Application Toast Activator CLSID. Needed for participating in Action Center.width Numberheight Numberこのガイドは、Ubuntu Software Centerを含む、Snapcraft環境向けにあなたのElectronアプリケーションをパッケージする方法を提供します。
\n幅広いLinux コミュニティと共に、Canonicalは共通したソフトウェアインストールの問題を解決するために、snapcraftプロジェクトを開始しました。 Snaps は、依存関係と自動アップデートに必要なソフトウェアパッケージを含めたパッケージであり、システムを修正することなく多くのメジャーなLinuxディストリビューションで動作します。
.snap ファイルを作成する方法は3つあります。:
1) electron-forge または electron-builderの使用、両方のツールは snapですぐに使用できます。 これは最も簡単な選択肢です。 2) electron-installer-snapの使用、これはelectron-packagerのアウトプットを使用します。 3) 作成した.debパッケージの使用
場合によっては、snapcraft ツールをインストールしている必要があります。 特定ディストリビューションの snapcraft のインストール手順は こちら です。
electron-installer-snapの使用このモジュールは、electron-winstallerのように動作します。またそのスコープ内の類似のモジュールは、snapパッケージのビルドに制限されます。 次のようにインストールできます:
npm install --save-dev electron-installer-snap\nelectron-packager (または類似ツール) を用いてパッケージします。 アプリケーションサイズが大きくなるので、実際には必要ないモジュールをnode_modulesから確実に削除します。
出力はおおよそ以下のようになります:
\n.\n└── dist\n └── app-linux-x64\n ├── LICENSE\n ├── LICENSES.chromium.html\n ├── content_shell.pak\n ├── app\n ├── icudtl.dat\n ├── libgcrypt.so.11\n ├── libnode.so\n ├── locales\n ├── resources\n ├── v8_context_snapshot.bin\n └── version\nelectron-installer-snapの実行snapcraft が環境変数 PATH に含まれている状態で、ターミナルから electron-installer-snapを実行します。その際に、--srcパラメーターで、この第一ステップで作成するElectronアプリケーションの場所を指定します。
npx electron-installer-snap --src=out/myappname-linux-x64\nもし既存のビルドパイプラインがある場合は、 electron-installer-snapをプログラムとして利用できます。 詳しい情報については、Snapcraft API docsを参照してください。
const snap = require('electron-installer-snap')\n\nsnap(options)\n .then(snapPath => console.log(`Created snap at ${snapPath}!`))\nelectron-packager と共に snapcraft を使用するプロジェクトディレクトリを作成し、snap/snapcraft.yaml に以下を追加します。
name: electron-packager-hello-world\nversion: '0.1'\nsummary: Hello World Electron app\ndescription: |\n Simple Hello World Electron app as an example\nbase: core18\nconfinement: strict\ngrade: stable\n\napps:\n electron-packager-hello-world:\n command: electron-quick-start/electron-quick-start --no-sandbox\n extensions: [gnome-3-34]\n plugs:\n - browser-support\n - network\n - network-bind\n environment:\n # Chromium フレームワーク/Electron の TMPDIR パスを修正し、\n # libappindicator が読めるリソースを確保します。\n TMPDIR: $XDG_RUNTIME_DIR\n\nparts:\n electron-quick-start:\n plugin: nil\n source: https://github.com/electron/electron-quick-start.git\n override-build: |\n npm install electron electron-packager\n npx electron-packager . --overwrite --platform=linux --output=release-build --prune=true\n cp -rv ./electron-quick-start-linux-* $SNAPCRAFT_PART_INSTALL/electron-quick-start\n build-snaps:\n - node/14/stable\n build-packages:\n - unzip\n stage-packages:\n - libnss3\n - libnspr4\nこの例を既存のプロジェクトに適用する場合は以下のようにしましょう。
\nsource: https://github.com/electron/electron-quick-start.git を source: . に置き換えます。electron-quick-start の箇所をプロジェクト名に置き換えます。$ snapcraft\n\n<output snipped>\nSnapped electron-packager-hello-world_0.1_amd64.snap\nsudo snap install electron-packager-hello-world_0.1_amd64.snap --dangerous\nelectron-packager-hello-world\nSnapcraft は既存の.debファイルをもとに、.snap ファイルに変換できます。 この場合snapcraft.yamlを利用してsnapを作成します。このファイルは、ソース、依存関係、説明、コアのビルドブロックを記述します。
.deb パッケージがない場合、electron-installer-snapで容易 にsnapパッケージを作成できます。 しかし、Debian パッケージは作成方法がいくつかあります。例えば、electron-forge や electron-builder、electron-installer-debian があります。
利用可能な設定オプションの詳細については、snapcraft 構文のドキュメント を参照してください。 以下で例を見てみましょう。
\nname: myApp\nversion: '2.0.0'\nsummary: A little description for the app.\ndescription: |\n あなたは知っていますか？ このアプリはすごい。 あなたのために色々してくれます。 ある者はこれで若さが保てるといい、また幸せに慣れると言っています。\n\ngrade: stable\nconfinement: classic\n\nparts:\n slack:\n plugin: dump\n source: my-deb.deb\n source-type: deb\n after:\n - desktop-gtk3\n stage-packages:\n - libasound2\n - libnotify4\n - libnspr4\n - libnss3\n - libpcre3\n - libpulse0\n - libxss1\n - libxtst6\n electron-launch:\n plugin: dump\n source: files/\n prepare: |\n chmod +x bin/electron-launch\n\napps:\n myApp:\n command: bin/electron-launch $SNAP/usr/lib/myApp/myApp\n desktop: usr/share/applications/myApp.desktop\n # Chromium Framework/Electron の TMPDIR パスを修正し、\n # libappindicator が読み取れるリソースを確保します。\n environment:\n TMPDIR: $XDG_RUNTIME_DIR\nご覧の通り、snapcraft.yaml は electron-launch と呼ばれるファイルを起動するようにシステムに伝達しています。 この例では、以下のようにアプリのバイナリへ情報を渡します。
\nexec \"$@\" --executed-from=\"$(pwd)\" --pid=$$ > /dev/null 2>&1 &\n代替として、snap を strict 禁則でビルドした場合、以下のように desktop-launch コマンドを使用できます。
apps:\n myApp:\n # TMPDIR パスを、Chromium Framework/Electron が\n # libappindicator の読み取り可能リソースを確認するために埋めます\n command: env TMPDIR=$XDG_RUNTIME_DIR PATH=/usr/local/bin:${PATH} ${SNAP}/bin/desktop-launch $SNAP/myApp/desktop\n desktop: usr/share/applications/desktop.desktop\nElectron のソースコードは、いくつかの部分に分けられています。ほとんどの場合、分離規約上 Chromium に従っています。
\nソースコードをよりよく理解するためには、Chromium のマルチプロセスアーキテクチャ に慣れる必要があるかもしれません。
\nElectron\n├── build/ - GN でビルドするために必要なコンフィグファイルをビルドします。\n├── buildflags/ - 条件付きビルドに使用できる機能の集合を定義します。\n├── chromium_src/ - コンテンツレイヤーの一部でない Chromium からコピーされたソースコード。\n├── default_app/ - 消費者向けアプリ以外から Electron が起動されたときに\n| 実行されるデフォルトアプリ。\n├── docs/ - Electron のドキュメント。\n| ├── api/ - Electron の外部向けモジュールと API のドキュメント。\n| ├── development/ - Electron の開発と Electron による開発の支援ドキュメント。\n| ├── fiddles/ - Electron Fiddle で実行できるコードスニペットの集合。\n| ├── images/ - ドキュメントで使用される画像。\n| └── tutorial/ - Electron のさまざまな観点におけるチュートリアルドキュメント。\n/ lib / - JavaScript / TypeScript شفرة المصدر.\n| ├── browser/ - メインプロセス初期化コード。\n| | ├── api/ - メインプロセスモジュール API の実装。\n| | └── remote/ - メインプロセスで使用される\n| | リモートモジュールに関連したコード。\n| ├── common/ - メインとレンダラー両方のプロセスに必要なロジックに関連するものです。\n| | └── api/ - メインとレンダラー両方のプロセスに必要な\n| | モジュール API の実装\n| ├── isolated_renderer/ - contextIsolation が有効なとき\n| | イソレートレンダラープロセスの作成を処理します。\n| ├── renderer/ - レンダラープロセス初期化コード。\n| | ├── api/ - レンダラープロセスモジュール API の実装。\n| | ├── extension/ - Electron レンダラープロセスでの\n| | | Chrome 拡張機能の使用に関連したコード。\n| | ├── remote/ - メインプロセスでの remote モジュールの\n| | | 使用を処理するロジック。\n| | └── web-view/ - レンダラープロセスでの webview の\n| | 使用を処理するロジック。\n| ├── sandboxed_renderer/ - サンドボックスレンダラープロセスの作成を処理する\n| | | ロジック。\n| | └── api/ - サンドボックスレンダラープロセス API の実装。\n| └── worker/ - Web Worker で Node.js 環境の適切な機能を\n| 処理するロジック。\n├── patches/ - ユースケースと元の機能との差異を扱うために、\n| | Electron のコア依存関係上に適用されたパッチ。\n| ├── boringssl/ - Google の OpenSSL フォークである BoringSSL に適用されているパッチ。\n| ├── chromium/ - Chromium に適用されているパッチ。\n| ├── node/ - Node.js 上に適用されているパッチ。\n| └── v8/ - Google の V8 エンジンの上に適用されているパッチ。\n├── shell/ - C++ ソースコード。\n| ├── app/ - システムのエントリコード。\n| ├── browser/ - メインウィンドウ、UI と\n| | | メインプロセスの全てを含むフロントエンド。 これはレンダラーと連絡して Web ページを\n| | | 管理します。\n| | ├── ui/ - 異なるプラットフォーム間での UI のローレベルの実装。\n| | | ├── cocoa/ - Cocoa に関連したソースコード。\n| | | ├── win/ - Windows のGUIに関連したソースコード。\n| | | └── x/ - X11 に関連したソースコード。\n| | ├── api/ - メインプロセス API の実装。\n| | ├── net/ - ネットワークに関連したコード。\n| | ├── mac/ - Mac に関連した Objective-C のソースコード。\n| | └── resources/ - アイコン、プラットフォーム固有のファイルなど。\n| ├── renderer/ - レンダラープロセスで動くコード。\n| | └── api/ - レンダラープロセス API の実装。\n| └── common/ - Node のメッセージループを Chromium のメッセージループに\n| | 統合するためのユーティリティ関数やコードなど、\n| | メインプロセスとレンダラープロセスの両方で使用されるコード。\n| └── api/ - 共通の API の実装と、\n| Electron の組み込みモジュールの基礎。\n├── spec/ - レンダラープロセスで実行される Electron の連続テストのコンポーネント。\n├── spec-main/ - メインプロセスで実行される Electron の連続テストのコンポーネント。\n└── BUILD.gn - Electronのビルドルール。\nscript/create-dist.py スクリプトが作成する一時的なディレクトリ。ninjaの一時的な出力用ディレクトリ。script/ - Electron がさまざまな目的で実行するすべてのスクリプトの集合。\n├── codesign/ - Electron アプリのコード署名を偽装します。テスト用です。\n├── lib/ - その他の Python のユーティリティスクリプト。\n└── release/ - Electron のリリースプロセス中に実行されるスクリプト。\n ├── notes/ - 新しいバージョンの Electron のリリースノートを生成します。\n └── uploaders/ - リリース中にさまざまなリリースに関するファイルをアップロードします。\nv8 以降の Electron は Chromium のスペルチェッカーを内蔵しています。 WindowsとLinuxではHunspell辞書が搭載されており、macOSではネイティブのspellchecker APIが使用されています。
\nElectron v9 以降では、スペルチェッカーはデフォルトで有効になっています。 Electron 8 では、 webPreferences で有効にする必要があります。
const myWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: true\n }\n})\nmacOS ではネイティブ API を使用しているため、スペルチェッカーが使用する言語を設定する方法はありません。 macOS では、デフォルトでネイティブのスペルチェッカーが自動的に使用されている言語を検出します。
\nWindows および Linux の場合、スペルチェッカーの言語を設定するために使用する Electron API がいくつかあります。
\n// アメリカ英語とフランス語のチェックする\nmyWindow.session.setSpellCheckerLanguages(['en-US', 'fr'])\n\n// 利用できる言語コードの配列\nconst possibleLanguages = myWindow.session.availableSpellCheckerLanguages\nデフォルトで、spellchecker は現在の OS ロケールに一致する言語を有効にします。
\nコンテキストメニューを生成するために必要なすべての情報は、各 webContents インスタンス上の context-menu イベントで提供されます。 この情報を使ってコンテキストメニューを作る簡単な方法を以下に示します。
const { Menu, MenuItem } = require('electron')\n\nmyWindow.webContents.on('context-menu', (event, params) => {\n const menu = new Menu()\n\n // スペルの補完をそれぞれ追加します\n for (const suggestion of params.dictionarySuggestions) {\n menu.append(new MenuItem({\n label: suggestion,\n click: () => mainWindow.webContents.replaceMisspelling(suggestion)\n }))\n }\n\n // ユーザーがスペルミスの単語を辞書に登録できるようにします\n if (params.misspelledWord) {\n menu.append(\n new MenuItem({\n label: 'Add to dictionary',\n click: () => mainWindow.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord)\n })\n )\n }\n\n menu.popup()\n})\nスペルチェッカー自体はタイプした文字列をGoogleサービスへ送信しませんが、 hunspell 辞書ファイルがGoogle CDNからダウンロードされます。 この動作を避けたい場合は、辞書をダウンロードするための代替URLを指定することができます。
\nmyWindow.session.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/')\n辞書ファイルの取得場所や、ホストするにあたって必要な事項についての詳細な情報は、session.setSpellCheckerDictionaryDownloadURL のドキュメントを確認してください。
Electronのドキュメント（英語）を書くためのガイドラインです。
\n#レベルのタイトルが必要です。## レベルの見出しが必要です。# が必要です。Quick Start（クイックスタート） を例にすると、以下のようになります。
# Quick Start\n\n...\n\n## Main process\n\n...\n\n## Renderer process\n\n...\n\n## Run your app\n\n...\n\n### Run as a distribution\n\n...\n\n### Manually downloaded Electron binary\n\n...\nただし、 API リファレンスに関してはこのルールの例外があります。
\nこのリポジトリでは、一貫した Markdown スタイルにするために markdownlint パッケージを使用しています。 正確なルールについては、ルートフォルダ内の .markdownlint.json ファイルをご参照ください。
リンターのルールではカバーしきれないような、いくつかのスタイルガイドラインを以下に示します。
\n\ncmd の代わりに sh を使用します (構文ハイライトのため)。js と javascript コードブロックは、standard-markdown によって整形されます。以下のルールは、API のドキュメントにのみ適用されます。
\n各モジュールの API ドキュメントでは、require('electron') が返す実際のオブジェクト名をタイトルとして使用しなければなりません (BrowserWindow、autoUpdater、session など)。
ページタイトル直下に、モジュールの説明を 1 行で Markdown の引用文として (> 始まりで) 追加します。
session モジュールを例にすると、以下のようにします。
# session\n\n> ブラウザーセッション、Cookie、キャッシュ、プロキシ設定などを管理します。\nモジュールはクラスではありません。そのメソッドとイベントは ## Methods と ## Events の章の下に列挙しなければなりません。
autoUpdater を例にすると、以下のようになります。
# autoUpdater\n\n## Events\n\n### Event: 'error'\n\n## Methods\n\n### `autoUpdater.setFeedURL(url[, requestHeaders])`\n## Class: クラス名 の章の下に列挙しなければなりません。### 階層のタイトルで列挙する必要があります。### Static Methods の章の配下に列挙しなければなりません。### Instance Methods の章の配下に列挙しなければなりません。[型] - [戻り値の説明]\" というように書き始めてください。Object を返す場合、その構造を記述します。コロンとそれに続く改行、そして関数の引数と同じスタイルでプロパティの順序なしリストにします。### Instance Events の章の下に列挙しなければなりません。### Instance Properties の章の下に列挙しなければなりません。Session と Cookies クラスを例にすると、以下のようにします。
# session\n\n## Methods\n\n### session.fromPartition(partition)\n\n## Static Properties\n\n### session.defaultSession\n\n## Class: Session\n\n### Instance Events\n\n#### Event: 'will-download'\n\n### Instance Methods\n\n#### `ses.getCacheSize()`\n\n### Instance Properties\n\n#### `ses.cookies`\n\n## Class: Cookies\n\n### Instance Methods\n\n#### `cookies.get(filter, callback)`\nメソッドの章はつぎの形式でなければなません。
\n### `objectName.methodName(required[, optional]))`\n\n* `required` String - 引数の説明。\n* `optional` Integer (optional) - 他の引数の説明。\n\n...\n見出しは、メソッドがモジュールに属するかクラスに属するかに応じて、### か #### レベルになります。
モジュールでは、objectName がモジュールの名前です。 クラスでは、クラスのインスタンスの名前にするべきで、モジュールの名前と同じではいけません。
例として、session モジュール下の Session クラスのメソッドは ses を objectName として使用しなければなりません。
任意の引数は、角括弧 [] で囲んで表記し、この任意の引数が他の引数に続く場合はカンマが必要です。
必須[, 任意]\n各引数の詳細は、そのメソッドの下に順序なしリストで記載します。 引数の種類は、JavaScript のプリミティブ (例: String、Promise、Object)、Electron の Cookie のようなカスタム API の構造体、またはワイルドカードである any のいずれかで表記してください。
引数の型が Array の場合は、配列内の値の型に [] の省略形を使用してください (例えば、any[] や String[])。
引数が Promise 型の場合、Promise が何に解決するかを型引数にします (例えば、Promise<void> や Promise<String>)。
引数が複数の型を取りうる場合は、| で型を区切ります。
Function 型引数の説明は、それがどのように呼ばれるのかを明確にし、それに渡される引数の型を列挙しなければなりません。
引数またはメソッドが特定のプラットフォーム固有のものである場合、そのプラットフォームはデータ型に続くスペース区切りのイタリック体リストを用いて示されます。 値は macOS、Windows、Linux にできます。
* `animate` Boolean (任意) _macOS_ _Windows_ - ものをアニメーションします。\nイベントの章はつぎの形式でなければなません。
\n### Event: 'wake-up'\n\nReturns:\n\n* `time` String\n\n...\n見出しは、イベントがモジュールに属するかクラスに属するかに応じて、### か #### レベルになります。
イベントの引数についてはメソッドと同じルールに従います。
\nプロパティの章はつぎの形式でなければなません。
\n### session.defaultSession\n\n...\n見出しは、プロパティがモジュールに属するかクラスに属するかに応じて、### か #### レベルになります。
electron/i18n を参照してください
", "title": "Electron ドキュメントスタイルガイド", "description": "" }, "/docs/tutorial/support": { "locale": "ja-JP", "slug": "support", "href": "/docs/tutorial/support", "crowdinFileId": "256253", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/support.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "セキュリティ上の相談がある場合は、セキュリティドキュメント をご参照ください。
\nプログラミングの質問とその回答を探したり、Electron を使っている他の開発者との議論に参加したりしたいのであれば、以下のロケーションのコミュニティで対話できます。
\nElectron の Discord にはこのようなチャンネルがあります:electron カテゴリ#electron チャンネルelectron-ru (ロシア)electron-br (ブラジルポルトガル語)electron-kr (韓国語)electron-jp (日本語)electron-tr (トルコ語)electron-id (インドネシア語)electron-pl (ポーランド語)Electron にコントリビュートしたい場合は、コントリビュートドキュメント をご参照ください。
\nElectron の サポートしているバージョン にバグを見つけた場合は、issue tracker にご報告していただけると幸いです。
\nawesome-electronはコミュニティで保守されている有益なサンプルアプリ、ツール、リソースのリストです。
\n注: 2021 年 9 月の Electron 15 から、Electron チームは最新から 4 つの 安定版メジャーバージョンを一時的にサポートします。 このサポート延長は、Electron の開発者が 新しい 8 週間のリリースケイデンス に移行することを目的に、2022 年 5 月の Electron 19 のリリースまで継続されます。 その時点で、Electron チームはサポートを最新から 3 つの安定版メジャーバージョンに戻します。
\n最新の 3 つの 安定した メジャーバージョンは Electron チームによってサポートされます。 たとえば、最新のリリースが 6.1.x の場合、5.0.x と 4.2.x 系列がサポートされます。 安定リリース系列ごとに最新のマイナーリリースのみをサポートしています。 つまり、セキュリティ修正の場合 6.1.x は修正を受けますが、6.0.x の新しいバージョンはリリースしません。
\n最新の安定版リリースは一方的に main からすべての修正を受け取り、それ以前のバージョンは時間と容量が許すようなこれら修正の大部分を受けています。 サポートされている最も古いリリースラインには、セキュリティ修正のみが直接送られます。
サポートされているすべてのリリースラインは、以前 main にマージされた修正をバックポートする外部のプルリクエストを受け付けます。これは、一部の古いサポートラインではケースバイケースとなります。 すべてのリリースラインのバックポートに関する紛糾は、バックポートプルリクエストが発行された週に、週1回の会議での議題項目として リリースワーキンググループ によって解決されます。
既存の機能を破壊するような API の変更や削除がされた場合、可能であれば、その機能は削除されるまでに最低 2 つのメジャーバージョンでサポートされます。 例えば、3 引数を取る関数が、メジャーバージョン 10 で 2 引数になった場合、3 引数版は少なくともメジャーバージョン 12 まで動作し続けます。 最低 2 つのバージョンという基準を過ぎた後は、メンテナンスの負担が大きすぎるとメンテナが感じるまで、2 つのバージョンより長く下位互換性をサポートします。
\nリリースブランチがサポートサイクルの終わりに達すると、npm では非推奨となり、最後のサポート終了リリースが行われる予定です。 このリリースでは、サポートされていないバージョンの Electron が使用されていることを知らせるための警告が追加されます。
\nこれらの手順は、使用しているブランチがサポートされなくなったときにアプリ開発者が学習できるようにするためのものですが、エンドユーザが過度に煩わされることはありません。
\nアプリケーションに例外的な状況があり、サポートされていない一連の Electron を使用し続ける必要がある場合、開発者はアプリケーションの package.json 内の devDependencies から最終リリースを省略することでサポート終了の警告を黙らせることができます。 たとえば、1-6-x シリーズは 1.6.18 リリースでサポートを終了したため、開発者はdevDependency を \"electron\": 1.6.0 - 1.6.17 とすることで警告なしで 1-6-x シリーズを使用することを選択できます。
Electronは以下のプラットフォームをサポートしています。
\nmacOS 向けには 64bit バイナリのみが提供されます。対応する macOS のバージョンは macOS 10.11 (El Capitan) 以降です。
\nElectron 11.0.0 から、Apple Silicon (arm64) デバイスのネイティブサポートを追加しました。
Windows 7以降に対応しています。Vista以前のOSはサポートされておらず、動作もしません。
\nWindows向けにはia32 (x86) とx64 (amd64) バイナリの両方が提供されています。 Electron 6.0.8 から、Windows on Arm (arm64) デバイスのネイティブサポートを追加しました。 ia32 バイナリを使用すると、以前のバージョンでパッケージ化されたアプリを実行できます。
Electron のビルド済みバイナリは Ubuntu 18.04 上でビルドしています。
\nElectronがどのディストリビューションで動作するかどうかは、ビルドプラットフォームでリンクされたライブラリが存在するかによりますので、Ubuntu 18.04 のみを動作保証していますが、次のプラットフォームについてもビルド済みのElectronバイナリを実行できるか検証しています：
\n\n\nNode.js と Electron API を使用する方法。
\n
Node.js の組み込みモジュール のすべては、Electron およびサードパーティの Node モジュール (ネイティブモジュール を含む) でも完全にサポートされています。
\nElectron はネイティブのデスクトップアプリケーションを開発するためのモジュールもいくつか追加しています。 モジュールの中には、メインプロセスでしか利用できないものもあれば、レンダラープロセス (ウェブページ) でしか利用できないもの、どちらのプロセスタイプでも利用できるものもあります。
\n基本的なルールはとしては、モジュールが GUI または低レベルのシステムに関わる場合、メインプロセスでのみ使用可能にする必要があります。 これらのモジュールを使いこなすには、メインプロセスとレンダラープロセスのスクリプトの概念に精通している必要があります。
\nメインプロセスのスクリプトは、通常の Node.js スクリプトとほぼ同じです。
\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL('https://github.com')\n})\nレンダラープロセスは、nodeIntegration が有効になっている場合は以下のように Node のモジュールを使用できるという特別な機能を除いて、通常のウェブページと変わりません。
\n<html>\n<body>\n<script>\n const fs = require('fs')\n console.log(fs.readFileSync(__filename, 'utf8'))\n</script>\n</body>\n</html>\n0.37から、分割代入 を使用して組み込みモジュールを使いやすくすることができます。
\nconst { app, BrowserWindow } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nelectron モジュール全体が必要な場合は、それを require してから、electron から個々のモジュールにアクセスするために分割することができます。
const electron = require('electron')\nconst { app, BrowserWindow } = electron\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nこれは以下のコードと同等です。
\nconst electron = require('electron')\nconst app = electron.app\nconst BrowserWindow = electron.BrowserWindow\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\n\n\nシステムの環境設定を取得します。
\n
プロセス: Main
\nconst { systemPreferences } = require('electron')\nconsole.log(systemPreferences.isDarkMode())\nsystemPreferences オブジェクトは以下のイベントを発生させます。
戻り値：
\nevent EventnewColor String - ユーザがシステムのアクセントカラーに割り当てる新しいRGBAカラー。戻り値：
\nevent Event戻り値：
\nevent EventinvertedColorScheme Boolean - 反転配色 (明るいテキストと暗い背景のハイコントラスト配色) が使用されている場合は true、それ以外の場合は false です。非推奨: 新しく nativeTheme モジュールの updated イベントを使用する必要があります。
戻り値：
\nevent EventhighContrastColorScheme Boolean - ハイコントラストテーマが使用されている場合は true、そうでない場合は false です。非推奨: 新しく nativeTheme モジュールの updated イベントを使用する必要があります。
systemPreferences.isDarkMode() macOS Windows Deprecated戻り値 Boolean - システムがダークモードかどうか。
非推奨: 新しく nativeTheme.shouldUseDarkColors API を使用する必要があります。
systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS戻り値 Boolean - ページ間をスワイプの設定がオンかどうか。
systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOSevent StringuserInfo Record<String, any>deliverImmediately Boolean (任意) - サブスクライブ中のアプリがアクティブでなくても通知をすぐに送信する場合は true です。macOS のネイティブ通知として event を送信します。 userInfo は、通知とともに送信されるユーザ情報辞書を含むオブジェクトです。
systemPreferences.postLocalNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>macOS のネイティブ通知として event を送信します。 userInfo は、通知とともに送信されるユーザ情報辞書を含むオブジェクトです。
systemPreferences.postWorkspaceNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>macOS のネイティブ通知として event を送信します。 userInfo は、通知とともに送信されるユーザ情報辞書を含むオブジェクトです。
systemPreferences.subscribeNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object String戻り値 Number - この登録のID。
対応する event が発生したときに、macOS のネイティブ通知を監視し、callback が callback(event, userInfo) で呼ばれます。 userInfo は、通知とともに送信されるユーザ情報辞書を含むオブジェクトです。 object は通知の送信者であり、現時点では NSString の値のみをサポートしています。
event の登録を解除するために使用できる、監視者の id が返されます。
このAPIの下で、NSDistributedNotificationCenter に登録します。event の値の例は以下になります。
AppleInterfaceThemeChangedNotificationAppleAquaColorVariantChangedAppleColorPreferencesChangedNotificationAppleShowScrollBarsSettingChangedsystemPreferences.subscribeLocalNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object String戻り値 Number - この登録のID。
subscribeNotification と同じですが、ローカルデフォルトでは NSNotificationCenter を使用します。 これは、NSUserDefaultsDidChangeNotification などのイベントに必要です。
systemPreferences.subscribeWorkspaceNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object String戻り値 Number - この登録のID。
subscribeNotification と同じですが、NSWorkspace.sharedWorkspace.notificationCenter を使用します。 これは NSWorkspaceDidActivateApplicationNotification といったイベントに必要です。
systemPreferences.unsubscribeNotification(id) macOSid Integerid の監視者を削除します。
systemPreferences.unsubscribeLocalNotification(id) macOSid IntegerunsubscribeNotification と同じですが、NSNotificationCenter から監視者を削除します。
systemPreferences.unsubscribeWorkspaceNotification(id) macOSid IntegerunsubscribeNotification と同じですが、NSWorkspace.sharedWorkspace.notificationCenter から監視者を削除します。
systemPreferences.registerDefaults(defaults) macOSdefaults Record<String, String | Boolean | Number> - ユーザデフォルト (key: value) の辞書配列アプリケーションの NSUserDefaults へ指定したデフォルトを追加します。
systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOSkey Stringtype Type - string、boolean、integer、float、double、url、array、dictionary のいずれかにできます。戻り値 UserDefaultTypes[Type] - NSUserDefaults 内の key の値。
いくつかの一般的な key と value は以下です。
AppleInterfaceStyle: stringAppleAquaColorVariant: integerAppleHighlightColor: stringAppleShowScrollBars: stringNSNavRecentPlaces: arrayNSPreferredWebServices: dictionaryNSUserDictionaryReplacementItems: arraysystemPreferences.setUserDefault(key, type, value) macOSkey Stringtype String - string、boolean、integer、float、double、url、array、dictionary のいずれかにできます。value StringNSUserDefaults 内の key の値を設定します。
type は value の実際の型と一致する必要があります。 そうでない場合は例外が送出されます。
いくつかの一般的な key と value は以下です。
ApplePressAndHoldEnabled: booleansystemPreferences.removeUserDefault(key) macOSkey StringNSUserDefaults 内のその key を削除します。 これは、以前に setUserDefaultで設定された key のデフォルトまたはグローバル値を復元するために使用できます。
systemPreferences.isAeroGlassEnabled() Windows戻り値 Boolean - DWM Composition (Aero Glass) が有効な場合は true、それ以外は false。
透明なウィンドウを作成するかどうかを決定するためにこのメソッドを使用する例です (透明なウィンドウは、DWM Composition が無効のときは正しく動作しません)。
\nconst { BrowserWindow, systemPreferences } = require('electron')\nconst browserOptions = { width: 1000, height: 800 }\n\n// Windowを透明にする。ただしプラットフォームがサポートしている場合に限る。\nif (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {\n browserOptions.transparent = true\n browserOptions.frame = false\n}\n\n// windowを作成します。\nconst win = new BrowserWindow(browserOptions)\n\n// 移動します。\nif (browserOptions.transparent) {\n win.loadURL(`file://${__dirname}/index.html`)\n} else {\n // 透明化がないので、基本的なスタールを使用するフォールバックを読み込む。\n win.loadURL(`file://${__dirname}/fallback.html`)\n}\nsystemPreferences.getAccentColor() Windows macOS戻り値 String - RGBA の16進数形式で、ユーザの現在のシステム全体のアクセント色の設定を表します。
const color = systemPreferences.getAccentColor() // `\"aabbccdd\"`\nconst red = color.substr(0, 2) // \"aa\"\nconst green = color.substr(2, 2) // \"bb\"\nconst blue = color.substr(4, 2) // \"cc\"\nconst alpha = color.substr(6, 2) // \"dd\"\nこの API は macOS 10.14 Mojave 以降でのみ利用可能です。
\nsystemPreferences.getColor(color) Windows macOScolor String - 以下の値のいずれか。3d-dark-shadow - 3D 表示要素の暗い影の色。3d-face - 3D 表示要素とダイアログボックスの背景の表面の色。3d-highlight - 3D 表示要素のハイライト色。3d-light - 3D 表示要素の光源色。3d-shadow - 3D 表示要素の影の色。active-border - アクティブなウインドウの縁の色。active-caption - アクティブなウインドウのタイトルバーの色。 グラデーション効果が有効な場合は、その左側の色になります。active-caption-gradient - アクティブなウィンドウのタイトルバーのグラデーション色における右側の色。app-workspace - マルチドキュメントインターフェース (MDI) アプリケーションの背景色。button-text - 押しボタンのテキスト色。caption-text - キャプション、サイズボックス、スクロールバー、矢印ボックス内のテキスト色。desktop - デスクトップ背景色。disabled-text - グレーの (無効化された) テキスト色。highlight - コントロール内で選択されたアイテム色。highlight-text - コントロール内で選択されたアイテムのテキスト色。hotlight - ハイパーリンクかホットトラックされたアイテムの色。inactive-border - 非アクティブなウインドウの縁の色。inactive-caption - 非アクティブなウインドウのタイトルバーの色。 グラデーション効果が有効な場合は、その左側の色になります。inactive-caption-gradient - 非アクティブなウィンドウのタイトルバーのグラデーション色における右側の色。inactive-caption-text - 非アクティブなキャプション内のテキストの色。info-background - ツールチップコントロールの背景色。info-text - ツールチップコントロールのテキスト色。menu - メニューの背景色。menu-highlight - メニューがフラットメニューとして表示されたときにメニュー項目をハイライト表示するために使用される色。menubar - メニューがフラットメニューとして表示されたときのメニューの背景色。menu-text - メニューのテキスト色。scrollbar - スクロールバーのグレーの領域の色。window - ウインドウの背景色。window-frame - ウインドウフレームの色。window-text - ウインドウ内のテキスト色。alternate-selected-control-text - リストまたは表の選択された面のテキスト。 非推奨control-background - ブラウザやテーブルなど、大きなインターフェイス要素の背景。control - コントロールの表面。control-text - 無効にされていないコントロールのテキスト。disabled-control-text - 無効になっているコントロールのテキスト。find-highlight - 検索インジケーターの色。grid - テーブルなどのインタフェース要素のグリッド線。header-text - テーブル内のヘッダーセルのテキスト。highlight - 画面上の仮想光源keyboard-focus-indicator - インタフェースナビゲーションにキーボードを使用しているときに、現在フォーカスされているコントロールの周囲に表示されるリング。label - 一次コンテンツを含むラベルのテキスト。link - 他のコンテンツへのリンク。placeholder-text - コントロールビューまたはテキストビューのプレースホルダ文字列。quaternary-label - 透かしテキストなどの3次ラベルよりも重要度の低いラベルのテキスト。scrubber-textured-background - タッチバーのスクラバーの背景。secondary-label - 小見出しや追加情報を表すために使用されるラベルなど、通常のラベルよりも重要度の低いラベルのテキスト。selected-content-background - キーウィンドウまたはビューで選択したコンテンツの背景。selected-control - 選択したコントロールの表面selected-control-text - 選択したコントロールのテキスト。selected-menu-item-text - 選択されたメニューのテキストselected-text-background - 選択したテキストの背景selected-text - 選択したテキストseparator - コンテンツのさまざまなセクション間の区切り文字。shadow - 画面上の隆起したオブジェクトによって投げかけられた仮想の影。tertiary-label - 無効なテキストを表すために使用されるラベルなど、2次ラベルより重要度の低いラベルのテキスト。text-background - テキストの背景text - 文書内のテキストunder-page-background - 文書のコンテンツの背景。unemphasized-selected-content-background - 非キーウィンドウまたはビューで選択されているコンテンツ。unemphasized-selected-text-background - 非キーウィンドウまたはビューで選択されているテキストの背景。unemphasized-selected-text - 非キーウィンドウまたはビューで選択されているテキスト。window-background - ウィンドウの背景window-frame-text - ウィンドウのタイトルバー領域のテキスト。戻り値 String - RGB の16進数形式 (#ABCDEF) のシステム色の設定。 詳細は Windows ドキュメント 及び macOS ドキュメント をご参照ください。
次の色は macOS 10.14 でのみ使用可能です。find-highlight、selected-content-background、separator、unemphasized-selected-content-background、unemphasized-selected-text-background、unemphasized-selected-text。
systemPreferences.getSystemColor(color) macOScolor String - 以下の値のいずれか。bluebrowngraygreenorangepinkpurpleredyellow戻り値 String - #RRGGBBAA の形式の標準システムカラー。
「コントラストを上げる」や「透明度を下げる」など、鮮やかさやアクセシビリティ設定の変更に自動的に適応する標準のシステムカラーの1つを返します。 詳しくは、Apple のドキュメントをご覧ください。
\nsystemPreferences.isInvertedColorScheme() Windows 非推奨戻り値 Boolean - 反転配色 (明るいテキストと暗い背景のハイコントラスト配色) がアクティブの場合は true、それ以外の場合は false です。
非推奨: 新しく nativeTheme.shouldUseInvertedColorScheme API を使用する必要があります。
systemPreferences.isHighContrastColorScheme() macOS Windows 非推奨戻り値 Boolean - ハイコントラストテーマがアクティブの場合は true、それ以外の場合は false です。
非推奨: 新しい nativeTheme.shouldUseHighContrastColors API を使用するようにしてください。
systemPreferences.getEffectiveAppearance() macOS戻り値 String - dark、light か unknown になります。
NSApplication.effectiveAppearance に割り当てられている、現在アプリケーションに適用されている macOS の外観設定を取得します。
\nsystemPreferences.getAppLevelAppearance() macOS 非推奨戻り値 String | null - dark、light か unknown になります。
NSApplication.appearance に割り当てられている、アプリケーションに必要であることを宣言した macOS の外観設定を取得します。 この値を設定するには setAppLevelAppearance API が使用できます。
systemPreferences.setAppLevelAppearance(appearance) macOS 非推奨appearance String | null - dark か light にできますアプリケーションの外観設定を設定します。これはシステムデフォルトを上書きし、getEffectiveAppearance の値を上書きします。
systemPreferences.canPromptTouchID() macOS戻り値 Boolean - このデバイスが Touch ID を使用できるかどうか。
注意: この API は Sierra 10.12.2 より古い macOS システムでは false を返します。
systemPreferences.promptTouchID(reason) macOSreason String - あなたが Touch ID 認証を求める理由戻り値 Promise<void> - ユーザが Touch ID で正常に認証された場合に実行されます。
const { systemPreferences } = require('electron')\n\nsystemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {\n console.log('You have successfully authenticated with Touch ID!')\n}).catch(err => {\n console.log(err)\n})\nこの API 自体はあなたのユーザーデータを保護しません。むしろ、あなたがそうしてもよいようにするメカニズムです。 ネイティブアプリでは、キーチェーンエントリに アクセスコントロール定数 を、kSecAccessControlUserPresence のように設定する必要があります。これを読み取ると、Touch ID の生体認証に自動的に同意するようになります。 これは node-keytar で暗号化キーを保存し、promptTouchID() の場合にのみそれを取得するように、node-keytar を使用して実行されます。
注意: この API は Sierra 10.12.2 より古い macOS システムでは拒否された Promise になります。
\nsystemPreferences.isTrustedAccessibilityClient(prompt) macOSprompt Boolean - 現在のプロセスが信頼できない場合にユーザにプロンプトで通知するかどうか。戻り値 Boolean -現在のプロセスが信頼されたアクセシビリティクライアントである場合 true で、そうでない場合は false です。
systemPreferences.getMediaAccessStatus(mediaType) Windows macOSmediaType String - microphone、camera、screen のいずれかにできます。戻り値 String - not-determined、granted、denied、restricted か unknown になります。
macOS 10.13 High Sierra 以前では、このユーザーの同意は必要なかったので、このメソッドは常に granted を返します。 macOS 10.14 Mojave 以降では、microphone と camera へのアクセスに同意が必要です。 macOS 10.15 Catalina 以降では、screen へのアクセスに同意が必要です。
Windows 10 には、すべての win32 アプリケーションの microphone と camera へのアクセスを制御するグローバル設定があります。 これは screen と古いバージョンの Windows すべてのメディアタイプに対して常に granted を返します。
systemPreferences.askForMediaAccess(mediaType) macOSmediaType String - 要求されるメディアのタイプで、microphone、camera にできます。戻り値 Promise<Boolean> - 許可された場合は true で、拒否された場合は false で解決する Promise。 無効な mediaType を渡した場合、Promise は reject されます。 アクセス要求が拒否されて後でシステム環境設定パネルを通して変更した場合、新しい権限の効果を得るためにアプリの再起動が必要です。 すでにアクセスを要求して拒否された場合、設定パネルを通して変更しなければなりません。警告はポップアップせずに Promise は現在のアクセス状態で解決します。
重要: この API を正しく活用するには、アプリの Info.plist ファイルに NSMicrophoneUsageDescription と NSCameraUsageDescription の文字列を設定する必要があります。 これらのキーの値は許可ダイアログに使用され、許可要求の目的についてユーザーに適切に通知されます。 Electron のコンテキスト内でどのようにこれらを設定するのかについての更なる情報は、Electron アプリケーション頒布 を参照してください。
このユーザーの同意は macOS 10.14 Mojave まで必要ではなかったので、システムを 10.13 High Sierra 以下で実行している場合このメソッドは常に true を返します。
systemPreferences.getAnimationSettings()戻り値 Object:
shouldRenderRichAnimation Boolean - リッチアニメーションをレンダリングする必要がある場合は true を返します。 セッションの種類 (例えばリモートデスクトップ) とアクセシビリティの設定を調べて、重いアニメーションのガイダンスを提供します。scrollAnimationsEnabledBySystem Boolean - スクロールアニメーション (例えばホームキーやエンドキーで生成されるもの) を有効にするかどうかがプラットフォームごとに決定されます。prefersReducedMotion Boolean - ユーザーがプラットフォーム API に基づいてモーションの削減を望むかどうかが決定されます。システムアニメーション設定を持つオブジェクトを返します。
\nsystemPreferences.appLevelAppearance macOSString 型のプロパティです。dark、light か unknown にできます。 アプリケーションの macOS 外観設定を決定します。 これは NSApplication.appearance の値に対応します。 これを設定すると、システムのデフォルトと getEffectiveAppearance の値が上書きされます。
設定可能な値は dark か light です。戻り値に取りうる値は dark、light、および unknown。
このプロパティは macOS 10.14 Mojave 以降でのみ利用可能です。
\nsystemPreferences.effectiveAppearance macOS ReadonlyString 型のプロパティです。dark、light か unknown にできます。
NSApplication.effectiveAppearance に割り当てられている、現在アプリケーションに適用されている macOS の外観設定を返します。
", "title": "systemPreferences", "description": "システムの環境設定を取得します。" }, "/docs/api/structures/task": { "locale": "ja-JP", "slug": "task", "href": "/docs/api/structures/task", "crowdinFileId": "256513", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/task.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "program String - Path of the program to execute, usually you should specify process.execPath which opens the current program.arguments String - The command line arguments when program is executed.title String - The string to be displayed in a JumpList.description String - Description of this task.iconPath String - The absolute path to an icon to be displayed in a JumpList, which can be an arbitrary resource file that contains an icon. You can usually specify process.execPath to show the icon of the program.iconIndex Number - The icon index in the icon file. If an icon file consists of two or more icons, set this value to identify the icon. If an icon file consists of one icon, this value is 0.workingDirectory String (optional) - The working directory. Default is empty.私達は Electron のコード網羅率を維持することを目指しています。 すべてのプルリクエストは、既存のすべてのテストに合格するだけでなく、変更されたコードと新しいシナリオをカバーする新しいテストを追加することを推奨します。 できるだけ多くのコードパスと Electron のユースケースを確保することで、より少ないバグでアプリを出荷することができます。
\nこのリポジトリには、JavaScript と C++ の両方に対する lint ルール、同様に対応するユニットテストと統合テストが付属しています。 Electron のコーディングスタイルの詳細については、コーディングスタイル ドキュメントを参照してください。
\nJavaScript が Electron コーディングスタイルに準拠していることを確認するには、npm run lint-js を実行します。これは、Electron 自身とユニットテストの両方に対し standard を実行します。 プラグイン/アドオンシステムを備えたエディタを使用している場合は、多くの StandardJS アドオン にコーディングスタイルの違反が通知されます。
引数つきで standard を実行するには、npm run lint-js -- に standard に渡したい引数を続けて書いて実行します。
C++ が Electron コーディングスタイルに準拠していることを確認するには、npm run lint-cpp を実行します。これは、cpplint スクリプトを実行します。 clang-format と用意された 短いチュートリアル を使うことを推奨します。
このリポジトリに Python が多数あるわけではありませんが、これもコーディングスタイル規則によって管理されています。 npm run lint-py を実行すれば、pylint を使ってすべての Python をチェックします。
build-tools を使用していない場合は、Electron のローカルビルド用コンフィグ名を確認してください。これは、Testing、Release、Default、Debug、設定した process.env.ELECTRON_OUT_DIR のいずれかです。 これらをセットしていないと、Electron はテスト前の手順を実行できないことがあります。
すべてのユニットテストを実行するには、npm run test を実行します。 ユニットテストは spec フォルダにある Electron アプリ (ｵﾄﾞﾛｷ!) です。 その package.json もあり、その依存関係はトップレベルの package.json には定義されていないことに注意してください。
パターンに一致する特定のテストだけを実行するには、npm run test -- -g=PATTERN で、PATTERN を実行したいテストに一致する正規表現に置き換えて実行します。 例として、IPC テストのみを実行したい場合は、npm run test -g ipc を実行します。
Visual Studio 2019 をインストールする必要があります。
\nNode ヘッダーは構成に合わせてコンパイルする必要があります。
\nninja -C out\\Testing third_party\\electron_node:headers\nelectron.lib を node.lib としてコピーする必要があります。
\ncd out\\Testing\nmkdir gen\\node_headers\\Release\ncopy electron.lib gen\\node_headers\\Release\\node.lib\n一部の Windows 10 デバイス はメイリオフォントがインストールされていない状態で出荷されるため、フォントフォールバックテストが失敗する可能性があります。 メイリオをインストールするには以下のようにします。
\n正確なピクセル測定値に依存するようなテストは、浮動小数点精度の誤差のために Hi-DPI 画面設定のデバイスでは正しく動作しない場合があります。 これらのテストを正常に実行するには、そのデバイスが倍率 100% に設定されていることを確認してください。
\nディスプレイ倍率を設定するには、
\nChromium ベースであるが故に、 Electron の動作にはディスプレイドライバが必要です。 もし、Chromiumがディスプレイドライバを見つけられない場合、Electronは起動に失敗します。そのため、あなたがどのように実行するかに関わらず、あなたのテストは実行できません。 Travis、Circle、Jenkins などのシステムで Electron ベースのアプリをテストするには、ちょっとした設定が必要です。 要するに、仮想ディスプレイドライバを使う必要があります。
\nまず、Xvfb をインストールします。 これは仮想フレームバッファで、X11 ディスプレイサーバプロトコルを実装しています。このフレームバッファは、画面出力を行うことなくメモリ内ですべてのグラフィック操作を行います。
\nそれから、仮想 Xvfb スクリーンを作成し、DISPLAY 環境変数でそれを指定します。 Electron の Chromium は自動的に $DISPLAY を探してくれるので、アプリの設定は特に必要ありません。 このステップは、Anaïs Betts 氏の xvfb-maybe で自動化できます。テストコマンドに xvfb-maybe を加えると、この小さなツールは必要な場合に自動で Xvfb を設定します。 Windows や macOSでは何もしません。
## Windows や macOS はelectron-mochaを起動します。\n## Linuxで ヘッドレス環境の場合、これは\n## xvfb-run electron-mocha ./test/*.js と同じです。\nxvfb-maybe electron-mocha ./test/*.js\nTravisにおいては、 .travis.yml を以下のようなものにしてください。
addons:\n apt:\n packages:\n - xvfb\n\ninstall:\n - export DISPLAY=':99.0'\n - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &\nJenkins 用の Xvfb プラグインが利用可能です。
\nCircle CI はよくできており、 Xvfb と $DISPLAY が すでにセットアップされているのでこれ以上の設定は不要 です。
Windows上で AppVeyor は実行します。また Selenium、 Chromium、 Electron またそれに類似したツールをすぐに使用できます。 - 設定は必要ありません。
", "title": "ヘッドレスCIシステムでのテスト (Travis CI, Jenkins)", "description": "" }, "/docs/tutorial/testing-widevine-cdm": { "locale": "ja-JP", "slug": "testing-widevine-cdm", "href": "/docs/tutorial/testing-widevine-cdm", "crowdinFileId": "256257", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/testing-widevine-cdm.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron では、Chrome ブラウザに同梱されている Widevine CDM ライブラリを使用できます。
\nWidevine Content Decryption Modules (CDMs) は、Flash や Silverlight のような NPAPI プラグインに頼ることなく、ストリーミングサービスが HTML 5 ビデオを使用して Web ブラウザにコンテンツを保護する方法です。 Widevine サポートは、DRM 保護されたビデオコンテンツの再生に現在 Silverlight を使用しているストリーミングサービスの代替ソリューションです。 Web サイトは NPAPI プラグインを使用せずに Firefox で DRM 保護されたビデオコンテンツを表示することができます。 Widevine CDM はオープンソースの CDM サンドボックスで実行され、NPAPI プラグインよりも優れたユーザーセキュリティを提供します。
\nElectron v1.8.0 (Chrome v59) 以降では、以下のステップは Widevine を有効にするために必要なステップの一部に過ぎません。Widevine CDM を使用する予定の、そのバージョン以降のアプリは、Widevine 自体から取得したライセンスを使用して署名する必要があります。
Widevine あたり:
\n\n\nChrome 59 (以降) には、検証済みメディアパス (VMP) のサポートが含まれています。 VMP はデバイスプラットフォームの信頼性を検証する方法を提供します。 ブラウザ展開の場合、これはブラウザベースの実装が信頼性があり安全であるかどうかを判断するための追加のシグナルを提供します。
\nプロキシ統合ガイドが VMP およびライセンスの発行方法に関する情報で更新されました。
\nWidevine は、私たちのブラウザベースの統合 (ベンダおよびブラウザベースのアプリケーション) が VMP のサポートを追加することを推奨しています。
\n
この新しい制限でビデオの再生を可能にするために、castLabs は、Widevine から必要なライセンスを取得した場合に、Widevine を Electron アプリケーションで再生できるようにするために必要な変更を実装した fork を作成しました。
\nChrome ブラウザで chrome://components/ を開き、Widevine Content Decryption Module を見つけて最新のものであることを確認したら、アプリケーションディレクトリからライブラリファイルを見つけることができます。
ライブラリファイル widevinecdm.dll は、Program Files(x86)/Google/Chrome/Application/CHROME_VERSION/WidevineCdm/_platform_specific/win_(x86|x64)/ ディレクトリにあります。
ライブラリファイル libwidevinecdm.dylib は、/Applications/Google Chrome.app/Contents/Versions/CHROME_VERSION/Google Chrome Framework.framework/Versions/A/Libraries/WidevineCdm/_platform_specific/mac_(x86|x64)/ ディレクトリにあります。
注意: Electron が使用する chrome バージョンが、Chrome の widevine cdm コンポーネントの min_chrome_version 値以上であることを確認してください。 値は、WidevineCdm ディレクトリの manifest.json にあります。
ライブラリファイルを取得したら、--widevine-cdm-path コマンドラインスイッチを使用してファイルへのパスを渡し、--widevine-cdm-version スイッチを使用してライブラリのバージョンを渡す必要があります。 app モジュールの ready イベントが発行される前に、コマンドラインスイッチを渡す必要があります。
コード例
\nconst { app, BrowserWindow } = require('electron')\n\n// You have to pass the directory that contains widevine library here, it is\n// * `libwidevinecdm.dylib` on macOS,\n// * `widevinecdm.dll` on Windows.\napp.commandLine.appendSwitch('widevine-cdm-path', '/path/to/widevine_library')\n// プラグインのバージョンは Chrome 内の `chrome://components` ページから取得できます。\napp.commandLine.appendSwitch('widevine-cdm-version', '1.4.8.866')\n\nlet win = null\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.show()\n})\nwidevine が機能するかどうかを確認するには、次の方法を使用できます。
\nWidevine を使用するマニフェストを読み込みます。bitdash uses Widevine in your browser と表示されているかどうかを確認してから、ビデオを再生します。icon NativeImage - The icon showing in thumbnail toolbar.click Functiontooltip String (optional) - The text of the button's tooltip.flags String - Control specific states and behaviors of the button. By default, it is ['enabled'].The flags is an array that can include following Strings:
enabled - The button is active and available to the user.disabled - The button is disabled. It is present, but has a visual state indicating it will not respond to user action.dismissonclick - When the button is clicked, the thumbnail window closes immediately.nobackground - Do not draw a button border, use only the image.hidden - The button is not shown to the user.noninteractive - The button is enabled but not interactive; no pressed button state is drawn. This value is intended for instances where the button is used in a notification.\n\nネイティブ macOS アプリ向けに、TouchBar レイアウトを作成します
\n
プロセス: Main
\nnew TouchBar(options)options Objectitems (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer)escapeItem (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer | null) (任意)指定したアイテムの新しい Touch Bar を作成します。 BrowserWindow.setTouchBar でウインドウに TouchBar を追加することができます。
Note: TouchBar API は現在実験的な機能です。そのため、将来的には変更されたり削除されたりする可能性があります。
\nヒント: Touch Bar 付きの MacBook をお持ちでない場合は、Touch Bar を使用するアプリの検証に Touch Bar シミュレータ をぜひご利用ください。
\nTouchBarButtontypeof TouchBarButton であり、TouchBarButton クラスの参照です。
TouchBarColorPickertypeof TouchBarColorPicker であり、TouchBarColorPicker クラスの参照です。
TouchBarGrouptypeof TouchBarGroup であり、TouchBarGroup クラスの参照です。
TouchBarLabeltypeof TouchBarLabel であり、TouchBarLabel クラスの参照です。
TouchBarPopovertypeof TouchBarPopover であり、TouchBarPopover クラスの参照です。
TouchBarScrubbertypeof TouchBarScrubber であり、TouchBarScrubber クラスの参照です。
TouchBarSegmentedControltypeof TouchBarSegmentedControl であり、TouchBarSegmentedControl クラスの参照です。
TouchBarSlidertypeof TouchBarSlider であり、TouchBarSlider クラスの参照です。
TouchBarSpacertypeof TouchBarSpacer であり、TouchBarSpacer クラスの参照です。
TouchBarOtherItemsProxytypeof TouchBarOtherItemsProxy であり、TouchBarOtherItemsProxy クラスの参照です。
TouchBar のインスタンスには以下のプロパティがあります。
touchBar.escapeItem設定すると、タッチバーの \"esc\" ボタンを置き換える TouchBarItem。 null に設定するとデフォルトの \"esc\" ボタンが復元されます。 この値を変更すると、タッチバーのエスケープアイテムがすぐに更新されます。
ボタンといくつかのラベルで構成される、シンプルな TouchBar 向けスロットゲームのコード例を示します。
\nconst { app, BrowserWindow, TouchBar } = require('electron')\n\nconst { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar\n\nlet spinning = false\n\n// リールのラベル\nconst reel1 = new TouchBarLabel()\nconst reel2 = new TouchBarLabel()\nconst reel3 = new TouchBarLabel()\n\n// 回した結果のラベル\nconst result = new TouchBarLabel()\n\n// 回すボタン\nconst spin = new TouchBarButton({\n label: '🎰 Spin',\n backgroundColor: '#7851A9',\n click: () => {\n // 回転中のクリックを無視\n if (spinning) {\n return\n }\n\n spinning = true\n result.label = ''\n\n let timeout = 10\n const spinLength = 4 * 1000 // 4 秒\n const startTime = Date.now()\n\n const spinReels = () => {\n updateReels()\n\n if ((Date.now() - startTime) >= spinLength) {\n finishSpin()\n } else {\n // 各回転を少し遅くする\n timeout *= 1.1\n setTimeout(spinReels, timeout)\n }\n }\n\n spinReels()\n }\n})\n\nconst getRandomValue = () => {\n const values = ['🍒', '💎', '7️⃣', '🍊', '🔔', '⭐', '🍇', '🍀']\n return values[Math.floor(Math.random() * values.length)]\n}\n\nconst updateReels = () => {\n reel1.label = getRandomValue()\n reel2.label = getRandomValue()\n reel3.label = getRandomValue()\n}\n\nconst finishSpin = () => {\n const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size\n if (uniqueValues === 1) {\n // 3 つすべての値が同じ場合\n result.label = '💰 ジャックポット!'\n result.textColor = '#FDFF00'\n } else if (uniqueValues === 2) {\n // 2 つの値が同じ場合\n result.label = '😍 やったね!'\n result.textColor = '#FDFF00'\n } else {\n // 同じ値がない場合\n result.label = '🙁 もう一度'\n result.textColor = null\n }\n spinning = false\n}\n\nconst touchBar = new TouchBar({\n items: [\n spin,\n new TouchBarSpacer({ size: 'large' }),\n reel1,\n new TouchBarSpacer({ size: 'small' }),\n reel2,\n new TouchBarSpacer({ size: 'small' }),\n reel3,\n new TouchBarSpacer({ size: 'large' }),\n result\n ]\n})\n\nlet window\n\napp.whenReady().then(() => {\n window = new BrowserWindow({\n frame: false,\n titleBarStyle: 'hiddenInset',\n width: 200,\n height: 200,\n backgroundColor: '#000'\n })\n window.loadURL('about:blank')\n window.setTouchBar(touchBar)\n})\n上記のサンプルを実行するには、(予めターミナルで適当なディレクトリを開いた上で) 以下の操作を行ってください。
\ntouchbar.js として保存するnpm install electron と入力し、 Electron をインストールします./node_modules/.bin/electron touchbar.js と入力し、Electron でサンプルを実行するすると、 Electron のウィンドウと、 Touch Bar 上（あるいは Touch Bar エミュレータ上）で動作するサンプルアプリをご覧になる事ができるはずです。
", "title": "TouchBar", "description": "ネイティブ macOS アプリ向けに、TouchBar レイアウトを作成します" }, "/docs/api/touch-bar-button": { "locale": "ja-JP", "slug": "touch-bar-button", "href": "/docs/api/touch-bar-button", "crowdinFileId": "256375", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/touch-bar-button.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nネイティブ macOS アプリケーション用のタッチバー内にボタンを作成する
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
new TouchBarButton(options)options Objectlabel String (任意) - ボタンのテキスト。accessibilityLabel String (任意) - VoiceOver などのスクリーンリーダーが使用するボタンの簡単な説明文。backgroundColor String (任意) - 16進数形式、即ち #ABCDEF のボタンの背景色。icon NativeImage | String (任意) - ボタンのアイコン。iconPosition String (任意) - left、right、overlay にできます。 省略値は overlay。click Function (任意) - ボタンがクリックされたときに呼ぶ関数。enabled Boolean (任意) - ボタンが有効な状態かどうか。 省略値は true です。accessibilityLabel を定義するときは、macOS ベストプラクティス を満たしていることを確認してください。
TouchBarButton のインスタンスには以下のプロパティがあります。
touchBarButton.accessibilityLabelスクリーンリーダーが読み上げるボタンの説明文を表す String。 ラベルが設定されていない場合に限り、スクリーンリーダーが読み上げます。
touchBarButton.labelボタンの現在のテキストを表す String。 この値を変更すると、タッチバー内のボタンがすぐに更新されます。
touchBarButton.backgroundColorボタンの背景色を表す 16 進数の String。 この値を変更すると、タッチバー内のボタンがすぐに更新されます。
touchBarButton.iconボタンの現在のアイコンを表す NativeImage。 この値を変更すると、タッチバー内のボタンがすぐに更新されます。
touchBarButton.iconPositionString - left または right または overlay のいずれか。 省略値は overlay。
touchBarButton.enabledボタンが有効な状態かどうかを表す Boolean。
\n\nネイティブ macOS アプリケーション用のタッチバー内にカラーピッカーを作成する
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
new TouchBarColorPicker(options)options ObjectTouchBarColorPicker のインスタンスには以下のプロパティがあります。
touchBarColorPicker.availableColorsカラーピッカーで選択できる色を表す String[] 配列。 この値を変更すると、タッチバー内のカラーピッカーがすぐに更新されます。
touchBarColorPicker.selectedColorカラーピッカーで選択した色を表す 16 進数の String。 この値を変更すると、タッチバー内のカラーピッカーがすぐに更新されます。
\n\nネイティブ macOS アプリケーション用のタッチバー内にグループを作成する
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
new TouchBarGroup(options)options Objectitems TouchBar - グループとして表示するアイテム。\n\nネイティブ macOS アプリケーション用のタッチバー内にラベルを作成する
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
new TouchBarLabel(options)options Objectlabel String (任意) - 表示するテキスト。accessibilityLabel String (任意) - VoiceOver などのスクリーンリーダーが使用するボタンの簡単な説明文。textColor String (任意) - 16進数形式、即ち #ABCDEF のテキスト色。accessibilityLabel を定義するときは、macOS ベストプラクティス を満たしていることを確認してください。
TouchBarLabel のインスタンスには以下のプロパティがあります。
touchBarLabel.labelラベルの現在のテキストを表す String。 この値を変更すると、タッチバー内のラベルがすぐに更新されます。
touchBarLabel.accessibilityLabelスクリーンリーダーが読み上げるラベルの説明文を表す String。
touchBarLabel.textColorラベルの現在のテキストの色を表す 16 進数の String。 この値を変更すると、タッチバー内のラベルがすぐに更新されます。
\n\n特別な「その他のアイテムのプロキシ」をインスタンス化します。これは、プロキシが指定するスペースに、Chromiumから継承された TouchBar の要素を含有します。 既定では、入力の最後のそれぞれの TouchBar にプロキシを追加します。 詳細は、AppKit ドキュメントの NSTouchBarItemIdentifierOtherItemsProxy を参照してください。
\n注意: TouchBar 1 つあたりに追加できるのは、このクラスのインスタンス 1 つだけです。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
new TouchBarOtherItemsProxy()\n\nネイティブ macOS アプリケーション用のタッチバー内にポップオーバーを作成する
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
new TouchBarPopover(options)options Objectlabel String (任意) - ポップオーバーするボタンのテキスト。icon NativeImage (任意) - ポップオーバーするボタンのアイコン。items TouchBar - ポップオーバー内に表示するアイテム。showCloseButton Boolean (任意) - true にするとポップオーバーの左に閉じるボタンを表示し、false にすると表示しません。 省略値は true です。TouchBarPopover のインスタンスには以下のプロパティがあります。
touchBarPopover.labelポップオーバーの現在のボタンのテキストを表す String。 この値を変更すると、タッチバー内のポップオーバーのコントロールがすぐに更新されます。
touchBarPopover.iconポップオーバーの現在のボタンのアイコンを表す NativeImage。 この値を変更すると、タッチバー内のポップオーバーのコントロールがすぐに更新されます。
\n\nスクラバー (スクロールできるセレクタ) を作成します。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
new TouchBarScrubber(options)options Objectitems ScrubberItem[] - このスクラバーに配置するアイテムの配列.select Function (任意) - ユーザーがタップしたアイテムが、最後にタップしたアイテムではないと呼ばれます。selectedIndex Integer - ユーザが選択したアイテムのインデックス.highlight Function (任意) - ユーザが任意のアイテムをタップしたときに呼ばれます。highlightedIndex Integer - ユーザがタッチしたアイテムのインデックス.selectedStyle String (任意) - 選択したアイテムのスタイル。 background、outline、none のいずれかにできます。 省略値は none です。overlayStyle String (任意) - 選択したオーバーレイアイテムのスタイル。 background、outline、none のいずれかにできます。 省略値は none です。showArrowButtons Boolean (任意) - 矢印ボタンを表示するかどうか。 省略値は false で、items が空でない場合にのみ表示されます。mode String (任意) - fixed か free にできます。 省略値は free です。continuous Boolean (任意) - 省略値は、true になります。TouchBarScrubber のインスタンスには以下のプロパティがあります。
touchBarScrubber.itemsこのスクラバー内のアイテムを表す ScrubberItem[] 配列。 この値を更新すると、タッチバーのコントロールがすぐに更新されます。 この配列の要素の中のプロパティを更新しても タッチバーは更新されません。
touchBarScrubber.selectedStyleスクラバー内の選択したアイテムのスタイルを表す String。 この値を更新すると、タッチバーのコントロールがすぐに更新されます。 取りうる値:
background - [NSScrubberSelectionStyle roundedBackgroundStyle] に割り当て.outline - [NSScrubberSelectionStyle outlineOverlayStyle] に割り当て.none - スタイルを全て除去します。touchBarScrubber.overlayStyleスクラバー内の選択したアイテムのスタイルを表す String。 このスタイルは、その後ろに置かれるのではなく、スクラバーアイテムの上に重ねられます。 この値を更新すると、タッチバーのコントロールがすぐに更新されます。 取りうる値:
background - [NSScrubberSelectionStyle roundedBackgroundStyle] に割り当て.outline - [NSScrubberSelectionStyle outlineOverlayStyle] に割り当て.none - スタイルを全て除去します。touchBarScrubber.showArrowButtonsこのスクラバーに左 / 右の選択矢印を表示するかどうかを表す Boolean。 この値を更新すると、タッチバー内のコントロールがすぐに更新されます。
touchBarScrubber.modeこのスクラバーのモードを表す String。 この値を更新すると、タッチバーのコントロールがすぐに更新されます。 取りうる値:
fixed - NSScrubberModeFixed に割り当て.free - NSScrubberModeFree に割り当て.touchBarScrubber.continuousこのスクラバーが連続しているかどうかを表す Boolean。 この値を更新すると、タッチバーのコントロールがすぐに更新されます。
\n\n1つのボタンが選択状態になっているセグメントコントロール (ボタングループ) を作成します
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
new TouchBarSegmentedControl(options)options ObjectsegmentStyle String (任意) - 以下のセグメントのスタイルのいずれかです。automatic - デフォルト。 セグメントコントロールの見た目は、コントロールを表示しているウインドウタイプとウインドウ内の位置に基づいて自動決定されます。 NSSegmentStyleAutomatic に対応します。rounded - コントロールは丸みのあるスタイルで表示されます。 NSSegmentStyleRounded に対応します。textured-rounded - コントロールは、テクスチャ付きの丸みのあるスタイルで表示されます。 NSSegmentStyleTexturedRounded に対応します。round-rect - コントロールは丸角のスタイルで表示されます。 Maps to NSSegmentStyleRoundRect.textured-rounded - コントロールは、テクスチャ付きの丸角のスタイルで表示されます。 NSSegmentStyleTexturedSquare に対応します。capsule - コントロールはカプセル状のスタイルで表示されます。 NSSegmentStyleCapsule に対応します。small-square - コントロールは小さな正方形のスタイルで表示されます。 NSSegmentStyleSmallSquare に対応します。separated - コントロール内のセグメントは、互いに非常に近く表示されますが、接触しません。 NSSegmentStyleSeparated に対応します。mode String (任意) - コントロールの選択モード。single - 既定値。 一度に 1 つアイテムを選択し、どれかを選択すると、前に選択したアイテムの選択が解除されます。 NSSegmentSwitchTrackingSelectOne に対応します。multiple - 一度に複数のアイテムを選択できます。 NSSegmentSwitchTrackingSelectAny に対応します。buttons - セグメントをボタンとして動作させ、各セグメントを押して離すことができますが、アクティブとしてマークされることはありません。 NSSegmentSwitchTrackingMomentary に対応します。segments SegmentedControlSegment[] - このコントロールに配置するセグメントの配列。selectedIndex Integer (任意) - ユーザの操作によって自動的に更新される、現在選択されているセグメントのインデックス。 multiple モードでは、これは最後に選択したアイテムになります。change Function (任意) - ユーザが新しいセグメントを選択したときに呼ばれます。selectedIndex Integer - ユーザが選択したセグメントのインデックス。isSelected Boolean - ユーザの選択結果として、セグメントが選択されたかどうか。TouchBarSegmentedControl のインスタンスには以下のプロパティがあります。
touchBarSegmentedControl.segmentStyleコントロールの現在のセグメントスタイルを表す String。 この値を更新すると、タッチバー内のコントロールがすぐに更新されます。
touchBarSegmentedControl.segmentsこのコントロールのセグメントを表す SegmentedControlSegment[] 配列。 この値を更新すると、タッチバーのコントロールがすぐに更新されます。 この配列の要素の中のプロパティを更新しても タッチバーは更新されません。
touchBarSegmentedControl.selectedIndex現在選択されているセグメントを表す Integer。 この値を変更すると、タッチバーのコントロールがすぐに更新されます。 ユーザがタッチバーに接触すると、この値が自動的に更新されます。
touchBarSegmentedControl.modeコントロールの、現在の選択モードを表す Stringです。 single、multiple、buttons のいずれかにできます。
\n\nネイティブ macOS アプリケーション用のタッチバー内にスライダーを作成する
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
new TouchBarSlider(options)options Objectlabel String (任意) - ラベルのテキスト。value Integer (任意) - 選択されている値。minValue Integer (任意) - 最小値。maxValue Integer (任意) - 最大値。change Function (任意) - スライダーが変更されたときに呼ぶ関数。newValue Number - Slider 上でユーザが選択した値。TouchBarSlider のインスタンスには以下のプロパティがあります。
touchBarSlider.labelスライダーの現在のテキストを表す String。 この値を変更すると、タッチバー内のスライダーのコントロールがすぐに更新されます。
touchBarSlider.valueスライダーの現在の値を表す Number。 この値を変更すると、タッチバー内のスライダーのコントロールがすぐに更新されます。
touchBarSlider.minValueスライダーの現在の最小値を表す Number。 この値を変更すると、タッチバー内のスライダーのコントロールがすぐに更新されます。
touchBarSlider.maxValueスライダーの現在の最大値を表す Number。 この値を変更すると、タッチバー内のスライダーのコントロールがすぐに更新されます。
\n\nネイティブ macOS アプリケーション用のタッチバー内に2つのアイテム間のスペーサーを作成する
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
new TouchBarSpacer(options)options Objectsize String (任意) - スペーサのサイズ。設定可能な値:small - アイテム間の小さいスペース。 NSTouchBarItemIdentifierFixedSpaceSmall に対応します。 これが既定値です。large - アイテム間の大きいスペース。 NSTouchBarItemIdentifierFixedSpaceLarge に対応します。flexible - 利用可能なスペース全てを埋める。 NSTouchBarItemIdentifierFlexibleSpace に対応します。TouchBarSpacer のインスタンスには以下のプロパティがあります。
touchBarSpacer.sizeこのススペーサーのサイズを表す String。 small、large、flexible のいずれかにできます。
categoryFilter String - A filter to control what category groups should be traced. A filter can have an optional '-' prefix to exclude category groups that contain a matching category. Having both included and excluded category patterns in the same list is not supported. Examples: test_MyTest*, test_MyTest*,test_OtherStuff, -excluded_category1,-excluded_category2.traceOptions String - Controls what kind of tracing is enabled, it is a comma-delimited sequence of the following strings: record-until-full, record-continuously, trace-to-console, enable-sampling, enable-systrace, e.g. 'record-until-full,enable-sampling'. The first 3 options are trace recording modes and hence mutually exclusive. If more than one trace recording modes appear in the traceOptions string, the last one takes precedence. If none of the trace recording modes are specified, recording mode is record-until-full. The trace option will first be reset to the default option (record_mode set to record-until-full, enable_sampling and enable_systrace set to false) before options parsed from traceOptions are applied on it.recording_mode String (optional) - Can be record-until-full, record-continuously, record-as-much-as-possible or trace-to-console. Defaults to record-until-full.trace_buffer_size_in_kb number (optional) - maximum size of the trace recording buffer in kilobytes. Defaults to 100MB.trace_buffer_size_in_events number (optional) - maximum size of the trace recording buffer in events.enable_argument_filter boolean (optional) - if true, filter event data according to a specific list of events that have been manually vetted to not include any PII. See the implementation in Chromium for specifics.included_categories String - a list of tracing categories to include. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.excluded_categories String - a list of tracing categories to exclude. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.included_process_ids number - a list of process IDs to include in the trace. If not specified, trace all processes.histogram_names String - a list of histogram names to report with the trace.memory_dump_config Record<String, any> (optional) - if the disabled-by-default-memory-infra category is enabled, this contains optional additional configuration for data collection. See the Chromium memory-infra docs for more information.An example TraceConfig that roughly matches what Chrome DevTools records:
\n{\n recording_mode: 'record-until-full',\n included_categories: [\n 'devtools.timeline',\n 'disabled-by-default-devtools.timeline',\n 'disabled-by-default-devtools.timeline.frame',\n 'disabled-by-default-devtools.timeline.stack',\n 'v8.execute',\n 'blink.console',\n 'blink.user_timing',\n 'latencyInfo',\n 'disabled-by-default-v8.cpu_profiler',\n 'disabled-by-default-v8.cpu_profiler.hires'\n ],\n excluded_categories: ['*']\n}\ntransactionIdentifier String - A string that uniquely identifies a successful payment transaction.transactionDate String - The date the transaction was added to the App Store’s payment queue.originalTransactionIdentifier String - The identifier of the restored transaction by the App Store.transactionState String - The transaction state, can be purchasing, purchased, failed, restored or deferred.errorCode Integer - The error code if an error occurred while processing the transaction.errorMessage String - The error message if an error occurred while processing the transaction.payment ObjectproductIdentifier String - The identifier of the purchased product.quantity Integer - The quantity purchased.\n\nシステムの通知領域にアイコンやコンテキスト メニューを追加します。
\n
プロセス: Main
\nTray は EventEmitter です。
const { app, Menu, Tray } = require('electron')\n\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n ])\n tray.setToolTip('This is my application.')\n tray.setContextMenu(contextMenu)\n})\nプラットフォームによる制限:
\nGtkStatusIcon が代わりに使用されます。libappindicator1 をインストールする必要があります。click イベントは無視されます。MenuItem に加えられた変更を有効にするには、setContextMenu を再び呼ぶ必要があります。 以下がその例です。const { app, Menu, Tray } = require('electron')\n\nlet appIcon = null\napp.whenReady().then(() => {\n appIcon = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' }\n ])\n\n // コンテキストメニューを変更する\n contextMenu.items[1].checked = false\n\n // Linux ではコンテキストメニューを変更したのでこれを呼び出し直します\n appIcon.setContextMenu(contextMenu)\n})\nICO 形式のアイコンファイルを使用することが推奨されています。すべてのプラットフォームでまったく同じ動作を維持したい場合は、click イベントに頼らず、tray アイコンに常にコンテキストメニューを適用して下さい。
new Tray(image, [guid])image (NativeImage | String)guid String (optional) Windows - tray アイコンに割り当てる GUID。 実行形式が署名されていて署名の主体者が組織である場合は、GUID がその署名に恒久的に関連付けられます。 システム tray の tray アイコンの位置など OS レベルの設定は、実行ファイルのパスが変わっても維持されます。 実行形式がコード署名されていない場合は、GUID が実行形式のパスへ永続的に関連付けられます。 実行形式のパスを変更すると、tray アイコンの作成は破棄され、新しい GUID を使用する必要があります。 ただし、この GUID 引数はコード署名された実行形式のみと組み合わせて使用することを強く推奨します。 アプリが複数の tray アイコンを定義している場合は、それぞれのアイコンで別々の GUID を使用する必要があります。image に関連する新しい tray アイコンを作成します。
tray モジュールには以下のイベントがあります。
戻り値：
\nevent KeyboardEventbounds Rectangle - tray アイコンの境界。position Point - イベントの位置。tray アイコンがクリックされたときに発行されます。
\n戻り値：
\nevent KeyboardEventbounds Rectangle - tray アイコンの境界。tray アイコンが右クリックされたときに発行されます。
\n戻り値：
\nevent KeyboardEventbounds Rectangle - tray アイコンの境界。tray アイコンがダブルクリックされたときに発行されます。
\ntray バルーンを表示するときに発行されます。
\ntray バルーンがクリックされたときに発行されます。
\ntray バルーンが、タイムアウトかユーザの手動で、閉じられたときに発行されます。
\ntray アイコン上に何かのドラッグされたアイテムがドロップされたときに発行されます。
\n戻り値：
\nevent Eventfiles String[] - ドロップされたファイルのパス。tray アイコン上にドラッグされたファイルがドロップされたときに発行されます。
\n戻り値：
\nevent Eventtext String - ドロップされたテキスト文字列。tray アイコン上にドラッグされたテキストがドロップされたときに発行されます。
\nドラッグ操作が tray アイコン内に入ったときに発行されます。
\nドラッグ操作が tray アイコン内から出たときに発行されます。
\nドラッグ操作が、tray 上か他の場所で終了したときに発行されます。
\n戻り値：
\nevent KeyboardEventposition Point - イベントの位置。tray アイコンをクリックしてマウスを離したときに発生します。
\n注意: macOS レベルの制約によるもので、tray.setContextMenu を使って tray にコンテキストメニューを設定するとこれは発生しません。
戻り値：
\nevent KeyboardEventposition Point - イベントの位置。tray アイコンをマウスクリックしたときに発生します。
\n戻り値：
\nevent KeyboardEventposition Point - イベントの位置。マウスが tray アイコン内に入ったときに発行されます。
\n戻り値：
\nevent KeyboardEventposition Point - イベントの位置。マウスが tray アイコン内から出たときに発行されます。
\n戻り値：
\nevent KeyboardEventposition Point - イベントの位置。マウスが tray アイコン内で動いたときに発行されます。
\nTray クラスは以下のメソッドを持ちます。
tray.destroy()tray アイコンを即座に削除します。
\ntray.setImage(image)image (NativeImage | String)この tray アイコンに関連付けられた image を設定します。
tray.setPressedImage(image) macOSimage (NativeImage | String)macOS において、この tray アイコンが押されたときの関連付けられた image を設定します。
tray.setToolTip(toolTip)toolTip Stringこの tray アイコンのホバーテキストを設定します。
\ntray.setTitle(title[, options]) macOStitle Stringoptions Object (任意)fontType String (任意) - 表示するフォントファミリのバリアント。 monospaced または monospacedDigit のどちらかです。 monospaced は macOS 10.15またはそれ以上で利用でき、 monospacedDigit は macOS 10.11またはそれ以上で利用できます。 空白の場合、タイトルにはデフォルトのシステムフォントを使用します。ステータスバー内の tray アイコンの隣に表示されるタイトル (ANSI カラーサポート) を設定します。
\ntray.getTitle() macOS戻り値 String - ステータスバーの tray アイコンの隣に表示されるタイトル
tray.setIgnoreDoubleClickEvents(ignore) macOSignore Booleanダブルクリックイベントを無視するオプションを設定します。 これらのイベントを無視することで tray アイコンそれぞれの独立したクリックを検知することを許可します。
\nこの値はデフォルトで false にセットされます。
\ntray.getIgnoreDoubleClickEvents() macOS戻り値 Boolean - ダブルクリックイベントが無視されているかどうか。
tray.displayBalloon(options) Windowsoptions Objecticon (NativeImage | String) (任意) - iconType が custom のときに使うアイコン。iconType String (任意) - none、info、warning、error、custom のいずれかにできます。 省略値は custom です。title Stringcontent StringlargeIcon Boolean (任意) - 大きなバージョンのアイコン。できればこちらを使用します。 省略値は true です。 NIIF_LARGE_ICON に対応します。noSound Boolean (任意) - 関連付けられたサウンドを再生しないようにします。 省略値は false です。 NIIF_NOSOUND に対応します。respectQuietTime Boolean (任意) - ユーザが現在 \"おやすみモード\" の場合、バルーン通知を表示しないようにします。 省略値は false です。 NIIF_RESPECT_QUIET_TIME に対応します。tray のバルーンを表示します。
\ntray.removeBalloon() Windowstray のバルーンを除去します。
\ntray.focus() Windowsタスクバーの通知領域にフォーカスを戻します。 通知領域アイコンは、UI 操作が完了したときにこのメッセージを使う必要があります。 たとえば、アイコンがショートカットメニューを表示しているけれど、ユーザーが ESC を押してキャンセルする場合、tray.focus() を使用して通知領域にフォーカスを戻します。
tray.popUpContextMenu([menu, position]) macOS Windowsmenu Menu (任意)position Point (任意) - ポップアップ位置。tray アイコンのコンテキストメニューをポップアップ表示します。 menu が渡されると、tray アイコンのコンテキストメニューの代わりに menu を表示します。
position は Windows でのみ有効で、省略値は (0, 0) です。
tray.closeContextMenu() macOS Windowstray.setContextMenu() でセットすることで、開かれたコンテキストメニューを閉じます。
tray.setContextMenu(menu)menu Menu | nullこのアイコンのコンテキストメニューを設定します。
\ntray.getBounds() macOS Windows戻り値 Rectangle
Object としてのこの tray アイコンの bounds。
tray.isDestroyed()戻り値 Boolean - tray アイコンが破棄されたかどうか。
title: Tray\ndescription: このガイドでは、システムの通知エリアにそれ独自のコンテキストメニューがある Tray アイコンを作成する手順を一緒に見ていきます。\nslug: tray
\nこのガイドでは、システムの通知エリアにそれ独自のコンテキストメニューがある Tray アイコンを作成する手順を一緒に見ていきます。
\nMacOS および Ubuntu では、Tray は画面の右上に位置し、バッテリーや Wi-Fi のアイコンと隣接します。 Windows の Tray は通常、右下に位置します。
\nまず electron から app、Tray、Menu、nativeImage をインポートしなければなりません。
const { app, Tray, Menu, nativeImage } = require('electron')\n次に Tray を作成します。 このために、NativeImage アイコンを使用することにします。これはいずれかの メソッド で作成できます。 Tray の作成コードを app.whenReady で囲んでいるのは、Electron アプリの初期化完了を待つ必要があるからです。
let tray\n\napp.whenReady().then(() => {\n const icon = nativeImage.createFromPath('path/to/asset.png')\n tray = new Tray(icon)\n\n // 注釈: contextMenu、Tooltip、Title のコードはこちらで!\n})\nこれでうまくいきました。 それでは以下のように Tray へコンテキストメニューを付けていきます。
\nconst contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n])\n\ntray.setContextMenu(contextMenu)\n上記のコードは、コンテキストメニューに 4 つで別々のラジオタイプのアイテムを作成します。 ネイティブメニューの構築についてご覧になりたい方は、こちら をクリックしてください。
\n最後に、Tray にツールチップとタイトルを入れましょう。
\ntray.setToolTip('This is my application')\ntray.setTitle('This is my title')\nElectron アプリを起動すると、オペレーティングシステムに応じて、画面の右上や右下に Tray が表示されます。\nfiddle docs/fiddles/native-ui/tray
Electron アプリケーションを更新する方法はいくつかあります。 最も簡単で、公式にサポートされているものは、組み込みの Squirrel フレームワークと Electron の autoUpdater モジュールの利用です。
\nupdate.electronjs.orgの使用Electron チームは update.electronjs.org をメンテナンスしています。これは、Electron を自己更新するためのオープンソースウェブサービスです。 このサービスは次の条件を満すElectronアプリ用に設計されています。
\nこのサービスを使う最も簡単な方法はupdate-electron-appをインストールすることで、update.electronjs.orgをつかって、事前調整されたNode.js モジュールを使う方法です。
\nモジュールのインストール
\nnpm install update-electron-app\nあなたのmain processファイルからこのupdaterを起動します。
\nrequire('update-electron-app')()\nデフォルト設定で、このモジュールはアプリの起動時に更新をチェックします。または10分毎にチェックします。 アップデートがみつかったとき、自動的にバックグラウンドでダウンロードします。 そのダウンロードが完了したとき、ダイアログを表示してユーザーにアプリの再起動許可を取ります。
\n設定をカスタマイズしたい場合、update-electron-appにオプションを渡すか、またはアップデートサービスを直接使用ができます。
プライベートの Electron アプリケーションを開発している場合、または GitHub リリースにリリースを公開していない場合は、独自のアップデートサーバーを実行する必要があるかもしれません。
\nニーズに応じて、次のいずれかから選択できます。
\nアップデートサーバをデプロイしたら、コードに必要なモジュールをインポートします。 次のコードはサーバソフトウェアによって異なる場合がありますが、Hazel を使用したときの説明のように機能します。
\n重要: 以下のコードは、開発中ではなく、パッケージ化されたアプリでのみ実行されるようにしてください。 electron-is-dev を使って環境をチェックすることができます。
\nconst { app, autoUpdater, dialog } = require('electron')\n次に、アップデートサーバーの URL を作成し、それについて autoUpdater に伝えます。
\nconst server = 'https://your-deployment-url.com'\nconst url = `${server}/update/${process.platform}/${app.getVersion()}`\n\nautoUpdater.setFeedURL({ url })\n最後のステップとして、更新を確認します。 以下の例では、毎分確認します。
\nsetInterval(() => {\n autoUpdater.checkForUpdates()\n}, 60000)\nアプリケーションがパッケージ化されると、公開した新しい GitHub Release ごとにアップデートが届きます。
\nアプリケーションの基本的な更新メカニズムを設定したので、更新があるとユーザに通知されるようにする必要があります。 これは autoUpdater API events を使用して実現できます。
\nautoUpdater.on('update-downloaded', (event, releaseNotes, releaseName) => {\n const dialogOpts = {\n type: 'info',\n buttons: ['Restart', 'Later'],\n title: 'Application Update',\n message: process.platform === 'win32' ? releaseNotes : releaseName,\n detail: 'A new version has been downloaded. Restart the application to apply the updates.'\n }\n\n dialog.showMessageBox(dialogOpts).then((returnValue) => {\n if (returnValue.response === 0) autoUpdater.quitAndInstall()\n })\n})\nエラーが ハンドリングされている ことも確認してください。 これは stderr にログを出力するための例です。
autoUpdater.on('error', message => {\n console.error('There was a problem updating the application')\n console.error(message)\n})\n自動更新によるリクエストは直接管理されていないため、対応が難しい状況が発生することがあります (更新サーバーが認証下にある場合など)。 url フィールドはファイルをサポートしていますので、工夫次第でサーバーとの通信を回避できます。 こちらにその動作例があります。
bytes Buffer - Content being sent.file String (optional) - Path of file being uploaded.blobUUID String (optional) - UUID of blob data. Use ses.getBlobData method to retrieve the data.type 'file' - file.filePath String - Path of file to be uploaded.offset Integer - Defaults to 0.length Integer - Number of bytes to read from offset. Defaults to 0.modificationTime Double - Last Modification time in number of seconds since the UNIX epoch.type 'rawData' - rawData.bytes Buffer - Data to be uploaded.string Stringboolean Booleaninteger Numberfloat Numberdouble Numberurl Stringarray Array\\dictionary Record\\<string, unknown>この型はヘルパーエイリアスであり、この型のオブジェクトが存在することはありません。
", "title": "UserDefaultTypes オブジェクト", "description": "" }, "/docs/tutorial/using-native-node-modules": { "locale": "ja-JP", "slug": "using-native-node-modules", "href": "/docs/tutorial/using-native-node-modules", "crowdinFileId": "256263", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-native-node-modules.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron ではネイティブ Node.js モジュールがサポートされていますが、Electron は (OpenSSL ではなく Chromium の BoringSSL を使用するなどの違いにより) 指定の Node.js バイナリと異なる アプリケーションバイナリインターフェイス (ABI) であるため、使用するネイティブモジュールを Electron 向けに再コンパイルする必要があります。 そうしなければ、以下の類のエラーが実行しようとしたときに発生します。
\nError: The module '/path/to/native/module.node'\nwas compiled against a different Node.js version using\nNODE_MODULE_VERSION $XYZ. This version of Node.js requires\nNODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing\nthe module (for instance, using `npm rebuild` or `npm install`).\nネイティブモジュールをインストールするにはいくつかの異なる方法があります。
\n他の Node プロジェクト同様にモジュールをインストールしてから、electron-rebuild パッケージで Electron 向けにモジュールを再ビルドします。 このモジュールは自動で Electron のバージョンを取得でき、ヘッダのダウンロードやアプリ向けにネイティブモジュールを再ビルドする手動の手順を処理できます。 Electron Forge を使用している場合、このツールは開発モードでも頒布物の作成でも自動で使用されます。
例えば、スタンドアローンの electron-rebuild ツールをインストールして、コマンドラインからモジュールを再ビルドするには、以下のようにします。
npm install --save-dev electron-rebuild\n\n# \"npm install\" を実行するごとに、こちらを実行します。\n./node_modules/.bin/electron-rebuild\n\n# Windows で問題が発生する場合はこちらをお試しください。\n.\\node_modules\\.bin\\electron-rebuild.cmd\nElectron Packager のような他ツールとの統合や使い方の詳細は、当該プロジェクトの README を参照してください。
\nnpm を使用いくつかの環境変数を設定することにより、モジュールを直接インストールするのに npm を使用できます。
例として、以下のように Electron 向けにすべての依存関係をインストールします。
\n# Electronのバージョン\nexport npm_config_target=1.2.3\n# Electron のアーキテクチャ。サポートされているアーキテクチャについては、 https://electronjs.org/docs/tutorial/support#supported-platforms\n# を参照してください。\nexport npm_config_arch=x64\nexport npm_config_target_arch=x64\n# Electronのヘッダファイルをダウンロード\nexport npm_config_disturl=https://electronjs.org/headers\n# node-pre-gyp にElectronのビルドであることを知らせる\nexport npm_config_runtime=electron\n# node-pre-gypにソースコードからのビルドであることを知らせる\nexport npm_config_build_from_source=true\n# すべての依存をインストールし、キャッシュを~/.electron-gypに保存する\nHOME=~/.electron-gyp npm install\nもしあなたがネイティブモジュールの開発者でElectronでの動作を検証したいのであれば、Electron用にモジュールを手動で再構築したいことと思います。 node-gypを使用することで、モジュールをElectron用にビルドできます。
cd /path-to-module/\nHOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://electronjs.org/headers\nHOME=~/.electron-gyp は開発用のヘッダーを探す場所によって変わります。--target=1.2.3 は Electron のバージョンです。--dist-url=... はヘッダをダウンロードする場所を指定します。--arch=x64 はモジュールを 64bit システム向けにビルドします。公開されているリリースと一致しない Electron のカスタムビルドに対してネイティブの Node モジュールをコンパイルするには、カスタムビルドにバンドルされている Node のバージョンを使用するように npm に指示します。
npm rebuild --nodedir=/path/to/src/out/Default/gen/node_headers\nもしネイティブモジュールがインストールされていてもうまく動いていないと気づいた場合は、下記のことを確認してみてください。
\nelectron-rebuild を実行しましょう。binding.gyp 内の win_delay_load_hook が false にセットされていないことを確認してください。win_delay_load_hook についての注釈Windows のデフォルトでは、node-gyp は node.dll に対してネイティブモジュールをリンクします。 しかし Electron 4.x 以降では、ネイティブモジュールで必要とされるシンボルは electron.exe によってエクスポートされ、node.dll は存在しません。 Windows にネイティブモジュールをロードするために、node-gyp はネイティブモジュールがロードされたときにトリガーされる delay-load-hook をインストールします。これはライブラリの (何も出てこない) 検索パスで node.dll を探す代わりに、ロード可能な実行可能ファイルを使用するように node.dll 参照をリダイレクトします。 そのため、Electron 4.x 以降でネイティブモジュールをロードするには 'win_delay_load_hook': 'true' が必要です。
モジュールが自己登録されなかった や 指定されたプロシージャが見つかりませんでした のようなエラーが得られた場合は、使用しようとしているモジュールが見つからないことを意味しているかもしれません。遅延読み込みフックを正しくインクルードしてください。 モジュールが node-gyp でビルドされている場合、binding.gyp ファイルで win_delay_load_hook 変数が true に設定されておらず、どこかで上書きされていないことを確認します。 モジュールが別のシステムでビルドされている場合は、メインの .node ファイルにインストールされている遅延読み込みフックを使用してビルドする必要があります。 link.exe の呼び出しは以下ようにしなければなりません。
link.exe /OUT:\"foo.node\" \"...\\node.lib\" delayimp.lib /DELAYLOAD:node.exe /DLL\n \"my_addon.obj\" \"win_delay_load_hook.obj\"\n特に、次のことが重要です。
\nnode.lib に対してリンクします。 間違った node.lib に対してリンクすると、Electron のモジュールが必要になったときにロード時エラーが発生します。/DELAYLOAD:node.exe フラグをインクルードします。 node.exe のリンクが遅延されていない場合、遅延読み込みフックが起動する機会がなく、Node のシンボルは正しく解決されません。win_delay_load_hook.obj は、最終的な DLL に直接リンクされます。 依存 DLL にフックが設定されていると、正しいタイミングで起動しません。遅延ロードフックを独自で実装する例については node-gyp を参照してください。
prebuildを使用したモジュールprebuild は、ネイティブの Node モジュールを複数の Node と Electron のバージョン向けに、ビルド済みバイナリとともに公開する方法を提供します。
prebuild を搭載したモジュールが Electron 向けのバイナリを提供している場合、ビルド済みバイナリを最大限に活用するために --build-from-source と npm_config_build_from_source 環境変数は省略してください。
node-pre-gypを使用したモジュールnode-pre-gypは、ビルド済みのバイナリを含んだネイティブNodeモジュールを展開する方法を提供します。多くの人気のモジュールがこのツールを使用しています。
これらのモジュールが Electron でも正常に動作することはありますが、Electron 固有のバイナリがない場合はソースからビルドする必要があります。 このため、これらのモジュールには electron-rebuild の使用を推奨します。
npm でモジュールをインストールする場合は、--build-from-source を npm に渡すか npm_config_build_from_source 環境変数を設定する必要があります。
Chrome がサポートを終了したため、Electron は Pepper Flash プラグインをサポートしていません。
\n詳細は Chromium の Flash ロードマップ を参照してください。
", "title": "Pepper Flash プラグイン", "description": "" }, "/docs/tutorial/using-selenium-and-webdriver": { "locale": "ja-JP", "slug": "using-selenium-and-webdriver", "href": "/docs/tutorial/using-selenium-and-webdriver", "crowdinFileId": "256267", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-selenium-and-webdriver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "ChromeDriver - クローム向けのWebDriver:
\n\n\nWebDriverは、ブラウザを横断的なテストの自動化を実現するためのオープンソースツールです。 このドライバはウェブページの遷移、インプット項目への入力、JavaScriptの実行などの機能を提供します。 ChromeDriverはChromium向けWebDriverのワイヤープロトコルを実装した、スタンドアローンサーバです。 このドライバは、ChromiumとWebDriverチームによって開発されています。
\n
SpectronはオフィシャルにサポートされているElectron向けChromeDriverテストフレームワークです。 これはWebdriverIO上に構築されており、テストプログラム内でElectron APIにアクセスする為のヘルパーとChromeDriverを内包しています。
\n$ npm install --save-dev spectron\n// A simple test to verify a visible window is opened with a title\nconst Application = require('spectron').Application\nconst assert = require('assert')\n\nconst myApp = new Application({\n path: '/Applications/MyApp.app/Contents/MacOS/MyApp'\n})\n\nconst verifyWindowIsVisibleWithTitle = async (app) => {\n await app.start()\n try {\n // Check if the window is visible\n const isVisible = await app.browserWindow.isVisible()\n // Verify the window is visible\n assert.strictEqual(isVisible, true)\n // Get the window's title\n const title = await app.client.getTitle()\n // Verify the window's title\n assert.strictEqual(title, 'My App')\n } catch (error) {\n // Log any failures\n console.error('Test failed', error.message)\n }\n // Stop the application\n await app.stop()\n}\n\nverifyWindowIsVisibleWithTitle(myApp)\nWebDriverJs は、Web Driver でテストするための Node パッケージを提供します。ここでは例として使用します。
\n最初に、chromedriver バイナリをダウンロードして実行する必要があります。
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\n後で使用されるポート番号 9515 を覚えておいてください。
$ npm install selenium-webdriver\nElectron での selenium-webdriver の使用方法は、手動で chrome driver の接続方法と Electron のバイナリの検索場所を指定する必要があることを除いて、upstream と同じです。
const webdriver = require('selenium-webdriver')\n\nconst driver = new webdriver.Builder()\n // The \"9515\" is the port opened by chrome driver.\n .usingServer('http://localhost:9515')\n .withCapabilities({\n 'goog:chromeOptions': {\n // ここに Electron バイナリへのパスを入れます。\n binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'\n }\n })\n .forBrowser('chrome') // 注: selenium-webdriver <= 3.6.0 では .forBrowser('electron') を使用します\n .build()\n\ndriver.get('http://www.google.com')\ndriver.findElement(webdriver.By.name('q')).sendKeys('webdriver')\ndriver.findElement(webdriver.By.name('btnG')).click()\ndriver.wait(() => {\n return driver.getTitle().then((title) => {\n return title === 'webdriver - Google Search'\n })\n}, 1000)\n\ndriver.quit()\nWebdriverIO は、Web Driver でテストするための Node パッケージを提供します。
\n最初に、chromedriver バイナリをダウンロードして実行する必要があります。
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver --url-base=wd/hub --port=9515\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\n後で使用されるポート番号 9515 を覚えておいてください。
$ npm install webdriverio\nconst webdriverio = require('webdriverio')\nconst options = {\n host: 'localhost', // Use localhost as chrome driver server\n port: 9515, // \"9515\" is the port opened by chrome driver.\n desiredCapabilities: {\n browserName: 'chrome',\n 'goog:chromeOptions': {\n binary: '/Path-to-Your-App/electron', // Electron バイナリへのパス.\n args: [/* Cliの引数 */] // オプション、例えば 'app=' + /path/to/your/app/\n }\n }\n}\n\nconst client = webdriverio.remote(options)\n\nclient\n .init()\n .url('http://google.com')\n .setValue('#q', 'webdriverio')\n .click('#btnG')\n .getTitle().then((title) => {\n console.log('Title was: ' + title)\n })\n .end()\nElectron を再構築せずにアプリケーションをテストするには、アプリケーションソースを Electron のリソースディレクトリに配置します。
\nElectron バイナリに引数を渡すことでも、実行するアプリのフォルダを指定できます。 こうすれば、アプリを Electron のリソースディレクトリにコピーペーストする必要はありません。
", "title": "Selenium と WebDriver", "description": "WebDriverは、ブラウザを横断的なテストの自動化を実現するためのオープンソースツールです。 このドライバはウェブページの遷移、インプット項目への入力、JavaScriptの実行などの機能を提供します。 ChromeDriverはChromium向けWebDriverのワイヤープロトコルを実装した、スタンドアローンサーバです。 このドライバは、ChromiumとWebDriverチームによって開発されています。" }, "/docs/development/v8-development": { "locale": "ja-JP", "slug": "v8-development", "href": "/docs/development/v8-development", "crowdinFileId": "256171", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/v8-development.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "\n\nV8の学習や使用のためのリソースを収集しています。
\n
--prof, --trace-ic, --trace-opt, --trace-deopt, --print-bytecode, --print-opt-code\n\nウェブページを描画、制御します。
\n
プロセス: Main
\nwebContents は EventEmitter を継承しています。 BrowserWindow オブジェクトのプロパティには、ウェブページを描画し、制御する責任があります。 以下は、webContents オブジェクトにアクセスする例です。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('http://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\nこれらのメソッドは、webContents モジュールからアクセスできます。
const { webContents } = require('electron')\nconsole.log(webContents)\nwebContents.getAllWebContents()戻り値 WebContents[] - すべての WebContents インスタンスの配列。 これには、すべてのウインドウ、開かれた開発者向けツール、開発者向けツールのバックグラウンド拡張のページが含まれます。
webContents.getFocusedWebContents()戻り値 WebContents - このアプリケーション内でフォーカス中の WebContents。無ければ null。
webContents.fromId(id)id Integer戻り値 WebContents | undefined - 指定 ID の WebContents インスタンス。指定 ID に関連付けられた WebContents が存在しない場合は undefined です。
webContents.fromDevToolsTargetId(targetId)targetId String - WebContents インスタンスに関連付けられた Chrome デベロッパー ツールプロトコルの TargetID。戻り値 WebContents | undefined - 指定 TargetID の WebContents インスタンス。指定 TargetID に関連付けられた WebContents が存在しない場合は undefined です。
Chrome デベロッパー ツールプロトコル と通信する際に、割り当てられた TargetID で WebContents インスタンスを検索すると便利な場合があります。
\nasync function lookupTargetId (browserWindow) {\n const wc = browserWindow.webContents\n await wc.debugger.attach('1.3')\n const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')\n const { targetId } = targetInfo\n const targetWebContents = await webContents.fromDevToolsTargetId(targetId)\n}\n\n\nBrowserWindow インスタンスのコンテンツを、描画し、制御します。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
ナビゲーションが終了した時、すなわち、タブのくるくるが止まったときや、onload イベントが送られた後に、発行されます。
戻り値：
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId Integerこのイベントは did-finish-load に似ていますが、ロードが失敗したときも発行されます。 エラーコードとその意味のすべてのリストは こちら です。
戻り値：
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId Integerこのイベントは did-fail-load に似ていますが、ロードがキャンセルされたときに発行されます (例えば window.stop() が呼び出されたときなど)。
戻り値：
\nevent EventisMainFrame BooleanframeProcessId IntegerframeRoutingId Integerフレームのナビゲーションが終了したときに発行されます。
\nタブのくるくるが始まったタイミングに対応しています。
\nタブのくるくるが止まったタイミングに対応しています。
\n戻り値：
\nevent Event最上位フレームの document が読み込まれたときに発生します。
\n戻り値：
\nevent Eventtitle StringexplicitSet Booleanナビゲーション中にページタイトルが設定されると発生します。 explicitSet は、タイトルがファイル URL から合成されている場合に false になります。
戻り値：
\nevent Eventfavicons String[] - URLの配列。ページがファビコンの URL を受け取ると発行されます。
\n戻り値：
\nevent NewWindowWebContentsEventurl StringframeName Stringdisposition String - default、foreground-tab、background-tab、new-window、save-to-disk、other にできる。options BrowserWindowConstructorOptions - 新しい BrowserWindow を作成するのに使われるオプション。additionalFeatures String[] - window.open() に与えられている、標準でない機能 (Chromium や Electron によって処理されない機能)。 非推奨であり、現在は必ず空の配列 [] になります。referrer Referrer - 新しいウィンドウへ渡される Referrer。 Referrer のポリシーに依存しているので、Referrer ヘッダを送信されるようにしてもしなくてもかまいません。postBody PostBody (任意) - 新しいウィンドウに送信する POST データと、それにセットする適切なヘッダ。 送信する POST データが無い場合、値は null になります。 これは target=_blank を設定したフォームによってウィンドウが作成されている場合にのみセットされます。これは webContents.setWindowOpenHandler に代わって非推奨となりました。
ページが url のための新しいウィンドウを開く要求をすると発生します。 window.open か <a target='_blank'> のような外部リンクによるリクエストである可能性があります。
デフォルトでは、url の新しい BrowserWindow が作成されます。
event.preventDefault() を呼ぶと、Electron が自動的に新しい BrowserWindow を作成するのを防ぎます。 もし event.preventDefault() を呼び、新しい BrowserWindow を手動で作る場合、新しい BrowserWindow インスタンスの参照を event.newGuest にセットしなければ、予期しない動作になる可能性があります。 以下がその例です。
myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {\n event.preventDefault()\n const win = new BrowserWindow({\n webContents: options.webContents, // あれば既存の webContents を使用する\n show: false\n })\n win.once('ready-to-show', () => win.show())\n if (!options.webContents) {\n const loadOptions = {\n httpReferrer: referrer\n }\n if (postBody != null) {\n const { data, contentType, boundary } = postBody\n loadOptions.postData = postBody.data\n loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`\n }\n\n win.loadURL(url, loadOptions) // 自動で既存の webContents をナビゲーションする\n }\n event.newGuest = win\n})\n戻り値：
\nwindow BrowserWindowdetails Objecturl String - 作成したウインドウの URL。frameName String - window.open() の呼び出しで作成したウインドウに指定した名前。options BrowserWindowConstructorOptions - その BrowserWindow の作成に使用したオプション。 これらは、window.open() の features 文字列から解析されたオプション、親ウインドウから継承されたセキュリティ関連の webPreferences、webContents.setWindowOpenHandler で与えられたオプションなどが優先度の高い順に結合されたものです。 認識できないオプションが取り除かれることはありません。referrer Referrer - 新しいウィンドウへ渡される Referrer。 リファラのポリシーに応じた Referer ヘッダーが送信されるとは限りません。postBody PostBody (任意) - 新しいウィンドウに送信される POST データと、設定される適切なヘッダです。 送信する POST データが無い場合、値は null になります。 これは target=_blank を設定したフォームによってウィンドウが作成されている場合にのみセットされます。disposition String - default、foreground-tab、background-tab、new-window、save-to-disk、other にできます。レンダラーで window.open を使用したウィンドウの作成に成功した 後 に発生します。 webContents.setWindowOpenHandler からウインドウの作成がキャンセルされた場合には発生しません。
詳細や webContents.setWindowOpenHandler と併せた使用方法については window.open() をご参照ください。
戻り値：
\nevent Eventurl Stringユーザーまたはページがナビゲーションを開始しようとしたときに発生します。 window.location オブジェクトが変更されるか、ユーザがページ内のリンクをクリックしたときに発生することがあります。
このイベントは、 webContents.loadURL や webContents.back のような API によって、プログラム上から開始されるナビゲーションのときには発行されません。
これは、アンカーリンクのクリックや window.location.hash の更新のような、ページ内ナビゲーションでも発行されません。 これを意図する場合は did-navigate-in-page を使用して下さい。
event.preventDefault() を呼ぶとナビゲーションが阻害されます。
戻り値：
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId Integerフレーム (メインを含む) がナビゲーションを始めているときに発生します。 ページ内ナビゲーションの場合、isInPlace が true になります。
戻り値：
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId Integerナビゲーション中にサーバーサイドリダイレクトが発生すると発行されます。 302 リダイレクトなどがその例です。
\nこのイベントは常に、同一ナビゲーションで did-start-navigation の後かつ did-redirect-navigation イベントの前に発行されます。
event.preventDefault() を呼ぶとナビゲーション (リダイレクトではない) が阻害されます。
戻り値：
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId Integerナビゲーション後にサーバーサイドリダイレクトが発生すると発行されます。 302 リダイレクトなどがその例です。
\nこのイベントを阻害することはできません。リダイレクトを防ぎたい場合は、上記の will-redirect イベントを確認してください。
戻り値：
\nevent Eventurl StringhttpResponseCode Integer - HTTP ナビゲーションが無い場合は-1httpStatusText String - HTTP ナビゲーションが無い場合は空メインフレームのナビゲーションが完了したときに発生します。
\nこのイベントは、アンカーリンクのクリックや window.location.hash の更新のような、ページ内ナビゲーションでは発行されません。 これを意図する場合は did-navigate-in-page を使用して下さい。
戻り値：
\nevent Eventurl StringhttpResponseCode Integer - HTTP ナビゲーションが無い場合は-1httpStatusText String - HTTP ナビゲーションが無い場合は空。isMainFrame BooleanframeProcessId IntegerframeRoutingId Integerフレームのナビゲーションが完了したときに発生します。
\nこのイベントは、アンカーリンクのクリックや window.location.hash の更新のような、ページ内ナビゲーションでは発行されません。 これを意図する場合は did-navigate-in-page を使用して下さい。
戻り値：
\nevent Eventurl StringisMainFrame BooleanframeProcessId IntegerframeRoutingId Integerフレームのページ内ナビゲーションが発生したときに発生します。
\nページ内ナビゲーションが行われるとき、ページのURLは変更されますがページ外でのナビゲーションは発生しません。 これが発生する例は、アンカーリンクがクリックされたときや、DOM の hashchange イベントがトリガーされたときです。
戻り値：
\nevent Eventbeforeunload イベントハンドラがページのアンロードをキャンセルしようとしたときに発行されます。
event.preventDefault() を呼ぶと、beforeunload イベントハンドラが無視され、 ページをアンロードできます。
const { BrowserWindow, dialog } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.webContents.on('will-prevent-unload', (event) => {\n const choice = dialog.showMessageBoxSync(win, {\n type: 'question',\n buttons: ['Leave', 'Stay'],\n title: 'Do you want to leave this site?',\n message: 'Changes you made may not be saved.',\n defaultId: 0,\n cancelId: 1\n })\n const leave = (choice === 0)\n if (leave) {\n event.preventDefault()\n }\n})\n注意: これは BrowserView に対して発生しますが、尊重 されません。これは、仕様 にあるように、BrowserView のライフサイクルはそれを所有する BrowserWindow に結び付けないとしたためです。
戻り値：
\nevent Eventkilled Booleanレンダラープロセスがクラッシュしたり、強制終了されたりしたときに発行されます。
\n非推奨: このイベントは render-process-gone イベント によって引き継がれます。このイベントには、子プロセスが失われた理由についての詳細情報が含まれています。 これはクラッシュした場合に限りません。 移植する場合は、Boolean 型の killed だと reason === 'killed' をチェックするように置き換えればできます。
戻り値：
\nevent Eventdetails Objectreason String - レンダープロセスがなくなった理由。 取りうる値:clean-exit - 終了コードが0でプロセスが終了したabnormal-exit - ゼロでない終了コードでプロセスを終了しました。killed - プロセスへSIGTERMシグナルが送信されたか、その他の方法で殺されました。crashed - プロセスがクラッシュしたoom - プロセスがメモリ不足になったlaunch-failed - プロセスが正常に起動されなかったintegrity-failure - Windows コードの整合性チェックに失敗しましたexitCode Integer - プロセスの終了コードです。reason が launch-failed でなければ、exitCode はプラットフォーム固有の起動失敗のエラーコードになります。renderer processが予期せず消えたときに発生します。 プロセスがクラッシュした場合やまたは殺された場合、これは正常です。
\nWebページが応答しなくなるときに発生します。
\n応答しないWebページが再び応答するようになるときに発生します。
\n戻り値：
\nevent Eventname Stringversion Stringプラグインプロセスがクラッシュしたときに発行されます。
\nwebContents が破棄されたときに発生します。
戻り値：
\nevent Eventinput Object - 入力プロパティ。type String - keyUp か keyDown。key String - KeyboardEvent.key と等価です。code String - KeyboardEvent.code と等価です。isAutoRepeat Boolean - KeyboardEvent.repeat と等価です。isComposing Boolean - KeyboardEvent.isComposing と等価です。shift Boolean - KeyboardEvent.shiftKey と等価です。control Boolean - KeyboardEvent.controlKey と等価です。alt Boolean - KeyboardEvent.altKey と等価です。meta Boolean - KeyboardEvent.metaKey と等価です。location Number - KeyboardEvent.location と同等。modifiers String[] - InputEvent.modifiers をご参照ください。ページ内の keydown と keyup イベントが発生する直前に発行されます。 event.preventDefault を呼ぶと、ページの keydown/keyup イベントとメニューショートカットを阻害します。
メニューショートカットだけを阻害するには、以下のように setIgnoreMenuShortcuts を使用します。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nwin.webContents.on('before-input-event', (event, input) => {\n // 例として、Ctrl/Cmd が押下されているときだけアプリケーションメニューの\n // キーボードショートカットを有効にしてみます。\n win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)\n})\nウインドウがHTML APIによってフルスクリーン状態に入るときに発生します。
\nウインドウがHTML APIによってフルスクリーン状態を抜けるときに発生します。
\n戻り値：
\nevent EventzoomDirection String - in か out にできます。ユーザーがマウスホイールを使用してズームレベルの変更を要求しているときに生成されます。
\n開発者向けツールが開かれたときに発行されます。
\n開発者向けツールが閉じられたときに発行されます。
\n開発者向けツールがフォーカスされた / 開かれたときに発行されます。
\n戻り値：
\nevent Eventurl Stringerror String - エラーコード。certificate Certificatecallback FunctionisTrusted Boolean - 証明書が信頼できるとみなされるかどうかを示す。isMainFrame Booleanurl の certificate の認証に失敗したときに発行されます。
使い方は、app の certificate-error イベント と同じです。
戻り値：
\nevent Eventurl URLcertificateList Certificate[]callback Functioncertificate Certificate - 指定されたリストの証明書でなければならない。クライアント証明書が要求されたときに発生します。
\n使い方は、app の select-client-certificate イベント と同じです。
戻り値：
\nevent EventauthenticationResponseDetails Objecturl URLauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (任意)password String (任意)webContents がBasic認証を要求すると発生します。
使い方は、app の login イベント と同じです。
戻り値：
\nevent Eventresult ObjectrequestId IntegeractiveMatchOrdinal Integer - アクティブなマッチの位置。matches Integer - マッチの個数。selectionArea Rectangle - 最初に一致した領域の座標。finalUpdate Boolean[webContents.findINPage] リクエストの結果が有効なときに発行されます。
メディアの再生を開始するときに発行されます。
\nメディアが一時停止、または再生が終了したときに発行されます。
\n戻り値：
\nevent Eventcolor (String | null) - '#rrggbb' 形式のテーマカラー。 テーマカラーが設定されていないと null です。ページのテーマカラーが変わったときに発生します。 これは通常、メタタグを発見すると起こります。
\n<meta name='theme-color' content='#ff0000'>\n戻り値：
\nevent Eventurl Stringマウスをリンクにマウスオーバーしたり、キーボードでリンクにフォーカスしたときに発行されます。
\n戻り値：
\nevent Eventtype Stringimage NativeImage (任意)scale Float (任意) - カスタムカーソルの拡大率。size Size (任意) - image のサイズ。hotspot Point (任意) - カスタムカーソルのホットスポットの座標。カーソルの種類が変更されたときに発行されます。 type は default、crosshair、pointer、text、wait、help、e-resize、n-resize,ne-resize、nw-resize、s-resize、se-resize、sw-resize、w-resize,ns-resize、ew-resize、nesw-resize、nwse-resize、col-resize,row-resize、m-panning、e-panning、n-panning、ne-panning、nw-panning,s-panning、se-panning、sw-panning、w-panning、move、vertical-text,cell、context-menu、alias、progress、nodrop、copy、none,not-allowed、zoom-in、zoom-out、grab、grabbing、custom になれます。
もし type パラメータが custom の場合、image パラメータはカスタムカーソルの NativeImage を、scale、size、hotspot はカスタムカーソルについての追加の情報を持ちます。
戻り値：
\nevent Eventparams Objectx Integer - x 座標。y Integer - y 座標。frame WebFrameMain - コンテキストメニューが呼び出されたフレーム。linkURL String - コンテキストメニューが呼び出されたノードを囲うリンク URL。linkText String - リンクに関連付けたテキスト。 リンクのコンテンツが画像の場合は、空文字列になります。pageURL String - コンテキストメニューが呼び出された最上位のページの URL。frameURL String - コンテキストメニューが呼び出されたサブフレームの URL。srcURL String - コンテキストメニューが呼び出された要素のソース URL。 ソース URL を持つ要素は、画像、オーディオ、ビデオです。mediaType String - コンテキストメニューが呼び出されたノードの種類。 none、image、audio、video、canvas、file、plugin になれる。hasImageContents Boolean - 空でないコンテンツ画像の上でコンテキストメニューが呼び出されたかどうか。isEditable Boolean - コンテキストが編集可能かどうか。selectionText String - コンテキストメニューが呼び出されたときの選択テキスト。titleText String - コンテキストメニューが呼び出された選択範囲のタイトルテキスト。altText String - コンテキストメニューが呼び出された選択範囲の代替テキスト。suggestedFilename String - コンテキストメニューの 'リンク先を名前を付けて保存' オプションでファイルを保存する際に使用されるファイル名の候補。selectionRect Rectangle - 選択範囲の document 空間における座標を表す矩形。selectionStartOffset Number - 選択テキストの開始位置。referrerPolicy Referrer - メニューが呼び出されるフレームのリファラポリシー。misspelledWord String - カーソルの下のスペルミスした単語 (もしあるならば)。dictionarySuggestions String[] - ユーザに misspelledWord の置き換えを示す推測した単語の配列。 単語のスペルミスがあり、スペルチェッカーが有効な場合にのみ利用できます。frameCharset String - メニューが呼び出されたときのフレームのテキストエンコーディング。inputFieldType String - 入力フィールド内でコンテキストメニューが呼び出されたときの、そのタイプ。 none、plainText、password、other になれる。spellcheckEnabled Boolean - そのコンテキストが編集可能な場合に、スペルチェックが有効かどうか。menuSourceType String - コンテキストメニューを呼び出した入力ソース。 none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, adjustSelectionReset のいずれかになります。mediaFlags Object - コンテキストメニューが呼び出されたメディア要素のフラグ。inError Boolean - メディア要素がクラッシュしたかどうか。isPaused Boolean - メディア要素が一時停止されているかどうか。isMuted Boolean - メディア要素がミュートされているかどうか。hasAudio Boolean - メディア要素に音声があるかどうか。isLooping Boolean - メディア要素をループしているかどうか。isControlsVisible Boolean - メディア要素のコントロールが見えるかどうか。canToggleControls Boolean - メディア要素のコントロールがトグル切り替えできるかどうか。canPrint Boolean - そのメディア要素が印刷できるかどうか。canSave Boolean - そのメディア要素がダウンロードできるかどうか。canShowPictureInPicture Boolean - そのメディア要素がピクチャインピクチャ表示できるかどうか。isShowingPictureInPicture Boolean - そのメディア要素をピクチャインピクチャ表示しているかどうか。canRotate Boolean - メディア要素を回転できるかどうか。canLoop Boolean - そのメディア要素をループ再生できるかどうか。editFlags Object - これらのフラグは、レンダラーが対応するアクションを実行できると信頼しているかどうかを示します。canUndo Boolean - レンダラーが、undo できると信頼しているかどうか。canUndo Boolean - レンダラーが、redo できると信頼しているかどうか。canCut Boolean - レンダラーが、カットできると信頼しているかどうか。canCopy Boolean - レンダラーがコピーできると信頼しているかどうか。canPaste Boolean - レンダラーが、ペーストできると信頼しているかどうか。canDelete Boolean - レンダラーが、削除できると信頼しているかどうか。canSelectAll Boolean - レンダラーが、全選択できると信頼しているかどうか。canEditRichly Boolean - レンダラーがテキストをリッチ編集できると信頼しているかどうか。処理が必要な新しいコンテキストメニューがあるときに発行されます。
\n戻り値：
\nevent Eventdevices BluetoothDevice[]callback FunctiondeviceId Stringnavigator.bluetooth.requestDevice を呼ぶうえで、Bluetooth デバイスを選択する必要があるときに発行されます。 navigator.bluetooth を使用するには、webBluetooth API を有効にする必要があります。 もし event.preventDefault が呼ばれなければ、最初に有効なデバイスが選択されます。 callback は選択された deviceId で呼ばれます。リクエストがキャンセルされると、callbback に空文字列が渡されます。
const { app, BrowserWindow } = require('electron')\n\nlet win = null\napp.commandLine.appendSwitch('enable-experimental-web-platform-features')\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {\n event.preventDefault()\n const result = deviceList.find((device) => {\n return device.deviceName === 'test'\n })\n if (!result) {\n callback('')\n } else {\n callback(result.deviceId)\n }\n })\n})\n戻り値：
\nevent EventdirtyRect Rectangleimage NativeImage - フレーム全体の画像データ。新しいフレームが生成されたときに発生します。 バッファには変更された部分だけが渡されます。
\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ webPreferences: { offscreen: true } })\nwin.webContents.on('paint', (event, dirty, image) => {\n // updateBitmap(dirty, image.getBitmap())\n})\nwin.loadURL('http://github.com')\n開発者向けツールウインドウが webContents にリロードを指示したときに発行されます。
\n戻り値：
\nevent EventwebPreferences WebPreferences - ゲストページで使用されるウェブ設定。 このオブジェクトを変更して、ゲストページの設定を調整できます。params Record<string, string> - 他の <webview> パラメーター。src URL などがこれにあたります。 このオブジェクトを変更して、ゲストページのパラメーターを調整できます。<webview> の webContents がこの webContents に適用されようとしているときに発行されます。 event.preventDefault() を呼ぶとゲストページを破棄します。
このイベントは、 webContents の <webview> が読み込まれる前に webPreferences を設定するのに使用でき、<webview> の属性を通して設定できない設定を、設定する機能を提供します。
注釈: 指定された preload スクリプトオプションは、このイベントが発行された webPreferences オブジェクト内の、preloadURL (preload ではない) として現れます。
戻り値：
\nevent EventwebContents WebContents - <webview> で使われるゲスト WebContents。<webview> がこの webContents に適用されたときに発行されます。
戻り値：
\nevent Eventlevel Integer - 0 から 3 のログレベル。 順に verbose、info、warning、error に対応します。message String - 実際のコンソールメッセージline Integer - このコンソールメッセージのトリガーとなったソースの行番号sourceId String関連付けられたウインドウがコンソールメッセージを出力すると発生します。
\n戻り値：
\nevent EventpreloadPath Stringerror Errorプリロードスクリプト preloadPath がハンドルされていない例外 error を投げたときに発行されます。
戻り値：
\nevent Eventchannel String...args any[]レンダラープロセスが ipcRenderer.send() を介して非同期メッセージを送信したときに発生します。
戻り値：
\nevent Eventchannel String...args any[]レンダラープロセスが ipcRenderer.sendSync() を介して同期メッセージを送信したときに発生します。
戻り値：
\nevent Eventレンダラープロセス内で desktopCapture.getSources() が呼ばれたときに発生します。 event.preventDefault() を呼び出すと、空のソースを返します。
戻り値：
\nevent EventpreferredSize Size - スクロールなしでドキュメントのレイアウトを格納するのに必要な最小サイズ。WebContents の優先サイズが変更された場合に発生します。
このイベントは、webPreferences で enablePreferredSizeMode が true に設定されている場合にのみ発生します。
戻り値：
\nevent Eventdetails Objectframe WebFrameMainmainFrame、<iframe>、ネストした <iframe> がページ内に読み込まれると発生します。
contents.loadURL(url[, options])url Stringoptions Object (任意)httpReferrer (String | Referrer) (任意) - HTTPリファラのURL。userAgent String (任意) - リクエスト元のユーザーエージェント。extraHeaders String (任意) - \"\\n\" で区切られた追加のヘッダー。postData (UploadRawData | UploadFile)baseURLForDataURL String (任意) - データURLによってロードされたファイルの (最後のパス区切り文字を含む) ベースURL。 これは指定された url がデータURLで、他のファイルをロードする必要がある場合のみ必要です。戻り値 Promise<void> - ページ読み込みが完了した時 (did-finish-load を参照) に解決され、ページの読み込みに失敗した時 (did-fail-load を参照) に拒否される Promise。 無操作拒否ハンドラーが既にアタッチされているため、未処理の拒否エラーは回避されます。
ウインドウ内に url を読み込みます。 url は、http:// や file:// のようなプロトコルの接頭子を含まなければなりません。 HTTP キャッシュをバイパスする必要があるロードの場合は、pragma ヘッダを使用してそれを実現します。
const { webContents } = require('electron')\nconst options = { extraHeaders: 'pragma: no-cache\\n' }\nwebContents.loadURL('https://github.com', options)\ncontents.loadFile(filePath[, options])filePath Stringoptions Object (任意)search Record<String, String> (任意) - url.format() に渡されます。search String (任意) - url.format() に渡されます。hash String (任意) - url.format() に渡されます。戻り値 Promise<void> - ページ読み込みが完了した時 (did-finish-load を参照) に解決され、ページの読み込みに失敗した時 (did-fail-load を参照) に拒否される Promise。
指定されたファイルをウインドウにロードします。filePath は、アプリケーションのルートを基準にした HTML ファイルへのパスにする必要があります。 たとえば以下のようなアプリの構造において、
| root\n| - package.json\n| - src\n| - main.js\n| - index.html\nこのようなコードが必要です。
\nwin.loadFile('src/index.html')\ncontents.downloadURL(url)url Stringナビゲーションなしで url のリソースのダウンロードを初期化します。 session の will-download イベントが発生します。
contents.getURL()戻り値 String - 現在のウェブページの URL。
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com').then(() => {\n const currentURL = win.webContents.getURL()\n console.log(currentURL)\n})\ncontents.getTitle()戻り値 String - 現在のウェブページのタイトル。
contents.isDestroyed()戻り値 Boolean - ウェブページが破棄されているかどうか。
contents.focus()ウェブページにフォーカスします。
\ncontents.isFocused()戻り値 Boolean - ウェブページがフォーカスされているかどうか。
contents.isLoading()戻り値 Boolean - ウェブページがまだリソースを読み込んでいるかどうか。
contents.isLoadingMainFrame()戻り値 Boolean - メインフレーム (iframe やフレーム内のフレームだけではない) がまだ読み込んでいるかどうか。
contents.isWaitingForResponse()戻り値 Boolean - ウェブページが、ページのメインリソースからの最初の応答を待機しているかどうか。
contents.stop()保留中のナビゲーションを停止します。
\ncontents.reload()現在のページを再読み込みします。
\ncontents.reloadIgnoringCache()現在のページを、キャッシュを無視して再読み込みします。
\ncontents.canGoBack()戻り値 Boolean - ブラウザが前のウェブページへ戻れるかどうか。
contents.canGoForward()戻り値 Boolean - ブラウザが次のウェブページへ進めるかどうか。
contents.canGoToOffset(offset)offset Integer戻り値 Boolean - offset 番目のウェブページへ行けるかどうか。
contents.clearHistory()ナビゲーション履歴を消去します。
\ncontents.goBack()ブラウザを前のページへ戻させます。
\ncontents.goForward()ブラウザを次のページへ進めさせます。
\ncontents.goToIndex(index)index Integerブラウザを指定した絶対ウェブページインデックスへナビゲーションします。
\ncontents.goToOffset(offset)offset Integer現在のエントリから指定したオフセットへナビゲーションします。
\ncontents.isCrashed()戻り値 Boolean - レンダラープロセスがクラッシュしたかどうか。
contents.forcefullyCrashRenderer()このwebContents を現在ホスティングしているレンダラープロセスを強制終了します。 これにより、 reason=kill || reason=crashed である、render-process-gone イベントが発生します。 レンダラープロセスを共有しているWebContents の中には、このメソッドを呼び出すと、他のウェブコンテンツのホストプロセスがクラッシュする場合がありますのでご注意ください。
メソッドを呼び出した直後にこの reload() を呼び出すと、新しいプロセスでリロードが発生します。 これは、このプロセスが不安定または使用不可の場合、例えば unresponsive イベントから回復する際に使用されるべきです。
contents.on('unresponsive', async () => {\n const { response } = await dialog.showMessageBox({\n message: 'App X has become unresponsive',\n title: 'Do you want to try forcefully reloading the app?',\n buttons: ['OK', 'Cancel'],\n cancelId: 1\n })\n if (response === 0) {\n contents.forcefullyCrashRenderer()\n contents.reload()\n }\n})\ncontents.setUserAgent(userAgent)userAgent Stringこのウェブページのユーザエージェントをオーバーライドします。
\ncontents.getUserAgent()戻り値 String - このウェブページのユーザエージェント。
contents.insertCSS(css[, options])css Stringoptions Object (任意)cssOrigin String (任意) - 'user' または 'author' のいずれかです。'user' を指定すると、挿入した CSS がウェブサイトによって上書きされるのを防ぐことができます。 既定値は 'author' です。戻り値 Promise<String> - 挿入された CSS のキーで解決される promise。後で contents.removeInsertedCSS(key) を使用して CSS を削除するために使用できます。
現在のウェブページに CSS を挿入し、挿入されたスタイルシートの一意なキーを返します。
\ncontents.on('did-finish-load', () => {\n contents.insertCSS('html, body { background-color: #f00; }')\n})\ncontents.removeInsertedCSS(key)key String戻り値 Promise<void> - 削除に成功すると解決されます。
現在のウェブページから挿入された CSS を削除します。 スタイルシートは contents.insertCSS(css) から返されるキーで識別されます。
contents.on('did-finish-load', async () => {\n const key = await contents.insertCSS('html, body { background-color: #f00; }')\n contents.removeInsertedCSS(key)\n})\ncontents.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (任意) - 省略値は false。戻り値 Promise<any> - 実行されたコードの結果で resolve する Promise。コードの結果が reject な Promise である場合は reject な Promise。
ページ内の code を評価します。
ブラウザウインドウでは、requestFullScreen のような、いくつかの HTML API は、ユーザからのジェスチャーでのみ呼び出されます。 userGesture を true にセットすることでこの制限がなくなります。
コードの実行は、ウェブページの読み込みが停止するまで中断されます。
\ncontents.executeJavaScript('fetch(\"https://jsonplaceholder.typicode.com/users/1\").then(resp => resp.json())', true)\n .then((result) => {\n console.log(result) // フェッチ呼び出しの JSON オブジェクトになります\n })\ncontents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])worldId Integer - JavaScript を実行するワールドの ID。0 はデフォルトのワールドで、999 は Electron の contextIsolation 機能で使用されるワールドです。 任意の整数を指定できます。scripts WebSource[]userGesture Boolean (任意) - 省略値は false。戻り値 Promise<any> - 実行されたコードの結果で resolve する Promise。コードの結果が reject な Promise である場合は reject な Promise。
executeJavaScript のように動きますが、 scripts はイソレートコンテキスト内で評価します。
contents.setIgnoreMenuShortcuts(ignore)ignore Booleanこの WebContents がフォーカスされている間、アプリケーションのメニューショートカットを無視します。
\ncontents.setWindowOpenHandler(handler)handler Function<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>
details Objecturl String - window.open() に渡されて 解決された URL。 例えば window.open('foo') でウインドウを開くと、これは https://the-origin/the/current/path/foo のようになります。frameName String - window.open() で指定されたウインドウ名features String - window.open() で指定されたウインドウ機能のカンマ区切りリスト。disposition String - default、foreground-tab、background-tab、new-window、save-to-disk、other のいずれかにできます。referrer Referrer - 新しいウィンドウへ渡される Referrer。 Referrer のポリシーに依存しているので、Referrer ヘッダを送信されるようにしてもしなくてもかまいません。postBody PostBody (任意) - 新しいウィンドウに送信する POST データと、それにセットする適切なヘッダ。 送信する POST データが無い場合、値は null になります。 これは target=_blank を設定したフォームによってウィンドウが作成されている場合にのみセットされます。戻り値 {action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny を返すと新規ウインドウの作成をキャンセルします。 allow を返すと新規ウインドウが作成されます。 overrideBrowserWindowOptions を指定すると、作成されるウィンドウをカスタマイズできます。 null、undefined、規定の 'action' の値を持たないオブジェクトといった認識されない値を返すと、コンソールエラーになり、{action: 'deny'} を返すのと同じ効果となります。
window.open()、target=\"_blank\" のリンク、リンクのシフトクリック、<form target=\"_blank\"> のフォーム送信などによりレンダラーが新しいウインドウを要求すると、ウインドウ作成前に呼び出されます。 詳細や did-create-window と併せた使用方法については window.open() をご参照ください。
contents.setAudioMuted(muted)muted Boolean現在のウェブページのオーディオをミュートします。
\ncontents.isAudioMuted()戻り値 Boolean - このページがミュートされているかどうか。
contents.isCurrentlyAudible()戻り値 Boolean - 音声が現在再生中かどうか。
contents.setZoomFactor(factor)factor Double - 拡大率。省略値は 1.0 です。指定の拡大率に変更します。 拡大率は百分率なので、300% = 3.0 です。
\n拡大率は 0.0 より大きい必要があります。
\ncontents.getZoomFactor()戻り値 Number - 現在の拡大率。
contents.setZoomLevel(level)level Number - 拡大レベル。指定レベルに拡大レベルを変更します。 原寸は 0 で、各増減分はそれぞれ 20% ずつの拡大または縮小を表し、デフォルトで元のサイズの 300% から 50% までに制限されています。 この式は scale := 1.2 ^ level です。
\n\n注意: Chromium でのズームポリシーはドメインごとです。すなわち、特定ドメインのズームレベルは、同じドメインのウィンドウの全インスタンスに伝播します。 ウインドウの URL が別々であれば、ウインドウごとのズームになります。
\n
contents.getZoomLevel()戻り値 Number - 現在の拡大レベル。
contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel Number戻り値 Promise<void>
ピンチによる拡大レベルの最大値と最小値を設定します。
\n\n\n注意: Electron ではデフォルトで視覚ズームは無効化されています。 再び有効にする場合は以下を呼び出します。
\n\ncontents.setVisualZoomLevelLimits(1, 3)\n
contents.undo()ウェブページの undo 編集コマンドを実行します。
contents.redo()ウェブページの redo 編集コマンドを実行します。
contents.cut()ウェブページの cut 編集コマンドを実行します。
contents.copy()ウェブページの copy 編集コマンドを実行します。
contents.copyImageAt(x, y)x Integery Integer指定した位置の画像をクリップボードにコピーします。
\ncontents.paste()ウェブページの paste 編集コマンドを実行します。
contents.pasteAndMatchStyle()ウェブページの pasteAndMatchStyle 編集コマンドを実行します。
contents.delete()ウェブページの delete 編集コマンドを実行します。
contents.selectAll()ウェブページの selectAll 編集コマンドを実行します。
contents.unselect()ウェブページの unselect 編集コマンドを実行します。
contents.replace(text)text Stringウェブページの replace 編集コマンドを実行します。
contents.replaceMisspelling(text)text Stringウェブページの replaceMisspelling 編集コマンドを実行します。
contents.insertText(text)text String戻り値 Promise<void>
フォーカスされた要素に text を挿入します。
contents.findInPage(text[, options])text String - 検索するコンテンツ。空にしてはいけません。options Object (任意)forward Boolean (任意) - 前方または後方を検索するかどうか。省略値は true。findNext Boolean (任意) - この要求で新規テキスト検索セッションを開始するかどうか。 最初の要求では true に、二度目以降の要求では false にする必要があります。 省略値は false 。matchCase Boolean (任意) - 大文字と小文字を区別する検索かどうか。省略値は false。戻り値 Integer - リクエストに使われたリクエスト ID。
ウェブページ内の text のすべてのマッチを探すリクエストを開始します。 リクエストの結果は found-in-page イベントを読むことで取得できます。
contents.stopFindInPage(action)action String - [webContents.findInPage] リクエストを終了する際に行う動作を指定します。clearSelection - 選択を消去する。keepSelection - その選択を通常の選択に変換する。activateSelection - 選択ノードをフォーカスして、クリックする。指定された action で、webContents の findInPage リクエストを停止します。
const { webContents } = require('electron')\nwebContents.on('found-in-page', (event, result) => {\n if (result.finalUpdate) webContents.stopFindInPage('clearSelection')\n})\n\nconst requestId = webContents.findInPage('api')\nconsole.log(requestId)\ncontents.capturePage([rect])rect Rectangle (任意) - キャプチャするページ内の領域。戻り値 Promise<NativeImage> - NativeImage を解決します
rect 内のページのスナップショットをキャプチャします。 rect を省略すると、表示されているページ全体をキャプチャします。
contents.isBeingCaptured()Returns Boolean - このページがキャプチャされているかどうか。 キャプチャーの数が 0 より大きい場合は true を返します。
contents.incrementCapturerCount([size, stayHidden, stayAwake])size Size (任意) - キャプチャの優先サイズ。stayHidden Boolean (任意) - ページを表示せずに非表示のままにします。stayAwake Boolean (任意) - システムをスリープさせずに、起きたままにします。キャプチャ回数は 1 ずつ増加します。 ブラウザーウインドウが非表示でもキャプチャ回数がゼロではない場合、ページは表示されていると見なされます。 ページを非表示のままにする場合は、stayHidden を true に設定していることを確認してください。
これは Page Visibility API にも影響を与えます。
\ncontents.decrementCapturerCount([stayHidden, stayAwake])stayHidden Boolean (任意) - ページを表示状態にせず非表示のままにします。stayAwake Boolean (任意) - システムをスリープさせずに、起きたままにします。キャプチャ回数は 1 ずつ減少します。 ブラウザウィンドウが隠されるまたはオクルージョンされるか、キャプチャーカウントが 0 になると、ページは非表示状態やオクルージョン状態にセットされます。 代わりに非表示のキャプチャ回数を減らしたい場合は、stayHidden を true に設定してください。
contents.getPrinters()システムプリンタのリストを取得します。
\n戻り値 PrinterInfo[]
contents.print([options], [callback])options Object (任意)silent Boolean (任意) - プリンタの設定をユーザに尋ねないかどうか。 省略値は false です。printBackground Boolean (任意) - ウェブページの背景色と画像を印刷するかどうか。 省略値は false です。deviceName String (任意) - 使用するプリンタデバイスの名前をセットします。 '人間向けの' 名称ではなくシステム定義名である必要があります。例えば、'Brother QL-820NWB' ではなく 'Brother_QL_820NWB' とします。color Boolean (任意) - 印刷するウェブページをカラーにするかグレースケールにするかを設定します。 省略値は true です。margins Object (任意)marginType String (任意) - default、none、printableArea か custom にできます。 custom を選択した場合、top、bottom、left、right も指定する必要があります。top Number (任意) - 印刷されたウェブページの上側のマージン。ピクセル単位です。bottom Number (任意) - 印刷されたウェブページの下側のマージン。ピクセル単位です。left Number (任意) - 印刷されたウェブページの左側のマージン。ピクセル単位です。right Number (任意) - 印刷されたウェブページの右側のマージン。ピクセル単位です。landscape Boolean (任意) - ウェブページを横向きモードで印刷するかどうか。 省略値は false です。scaleFactor Number (任意) - ウェブページのスケール係数。pagesPerSheet Number (任意) - ページシートごとに印刷するページ数。collate Boolean (任意) - ウェブページを校合するかどうか。copies Number (任意) - 印刷するウェブページの版数。pageRanges Object - 印刷するページ範囲。 macOS では 1 つの範囲のみが許可されています。from Number - 印刷する最初のページのインデックス (0 始まり)。to Number - 印刷する最後のページのインデックス (これを含む) (0 始まり)。duplexMode String (任意) - 印刷されるウェブページの両面モードを設定します。 simplex、shortEdge、longEdge のいずれかにできます。dpi Record<string, number> (任意)horizontal Number (任意) - 水平 DPI。vertical Number (任意) - 垂直 DPI。header String (任意) - ページヘッダーとして印刷される文字列。footer String (任意) - ページフッターとして印刷される文字列。pageSize String | Size (任意) - 印刷するドキュメントのページサイズを指定します。 A3、A4、A5、Legal、Letter、Tabloid のいずれかにするか、height を含む Object にできます。callback Function (任意)success Boolean - 印刷呼び出しの成功を示す。failureReason String - 印刷に失敗した場合に呼び戻されるエラーの説明。カスタムの pageSize を渡すと、Chromium は width_microns と height_microns それぞれのプラットフォーム固有の最小値を検証しようとします。 幅、高さともに最低 353 ミクロンでなければなりませんが、オペレーティングシステムによってはそれ以上になることがあります。
ウインドウのウェブページを印刷します。 silent が true にセットされたとき、deviceName が空で印刷のデフォルト設定があれば、Electron はシステムのデフォルトプリンタを選択します。
page-break-before: always; CSS スタイルを使用して、強制的に改ページして印刷できます。
使用例:
\nconst options = {\n silent: true,\n deviceName: 'My-Printer',\n pageRanges: [{\n from: 0,\n to: 1\n }]\n}\nwin.webContents.print(options, (success, errorType) => {\n if (!success) console.log(errorType)\n})\ncontents.printToPDF(options)options ObjectheaderFooter Record<string, string> (任意) - PDF のヘッダーとフッター。title String - PDF ヘッダーのタイトル。url String - PDF フッターの URL。landscape Boolean (任意) - true で横向き、false で縦向き。marginsType Integer (optional) - 使用する余白の種類を指定します。 0 で既定値、1 で余白なし、2 で最小限の余白になります。scaleFactor Number (任意) - ウェブページのスケール係数。 0 から 100 の範囲にできます。pageRanges Record<string, number> (任意) - 印刷するページ範囲。from Number - 印刷する最初のページのインデックス (0 始まり)。to Number - 印刷する最後のページのインデックス (これを含む) (0 始まり)。pageSize String | Size (任意) - 生成する PDF のページサイズを指定します。 A3、A4、A5、Legal、Letter、Tabloid、またはミクロン単位の height と width を含む Object にできます。printBackground Boolean (任意) - CSS 背景を印刷するかどうか。printSelectionOnly Boolean (任意) - 選択部分だけを印刷するかどうか。戻り値 Promise<Buffer> - 生成された PDF データで実行されます。
Chromium の印刷のカスタム設定のプレビューで、PDF としてウインドウのウェブページを出力します。
\n@page CSS ルールがウェブページ内で使われている場合、landscape は無視されます。
デフォルトでは、空の options は以下のようにみなされます。
{\n marginsType: 0,\n printBackground: false,\n printSelectionOnly: false,\n landscape: false,\n pageSize: 'A4',\n scaleFactor: 100\n}\npage-break-before: always; CSS スタイルを使用して、強制的に改ページして印刷できます。
これは webContents.printToPDF の例です。
const { BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\nconst os = require('os')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nwin.webContents.on('did-finish-load', () => {\n // 既定の印刷オプションを使用します\n win.webContents.printToPDF({}).then(data => {\n const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')\n fs.writeFile(pdfPath, data, (error) => {\n if (error) throw error\n console.log(`Wrote PDF successfully to ${pdfPath}`)\n })\n }).catch(error => {\n console.log(`Failed to write PDF to ${pdfPath}: `, error)\n })\n})\ncontents.addWorkSpace(path)path String指定したパスをデベロッパー ツールのワークスペースに追加します。 デベロッパー ツールが生成された後で使用しなければいけません。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.on('devtools-opened', () => {\n win.webContents.addWorkSpace(__dirname)\n})\ncontents.removeWorkSpace(path)path String開発者向けツールのワークスペースから指定したパスを削除します。
\ncontents.setDevToolsWebContents(devToolsWebContents)devToolsWebContents WebContentsdevToolsWebContents を開発者向けツールを表示するターゲット WebContents として使用します。
devToolsWebContents はナビゲーションを行ってはいけません。また、コール後に他の目的に使用することはできません。
デフォルトでは、Electron は開発者が制御を非常に制限したネイティブビューを持つ内部 WebContents を作成することによって開発者向けツールを管理します。 setDevToolsWebContents メソッドでは、開発者は任意の WebContents を使用して、BrowserWindow、BrowserView、<webview> タグなどの開発者向けツールを表示できます。
開発者向けツールを閉じても devToolsWebContents は破棄されないことに注意してください。 devToolsWebContents を破棄するのは呼び出し元の責任です。
<webview> タグ内で開発者向けツールを表示する例:
<html>\n<head>\n <style type=\"text/css\">\n * { margin: 0; }\n #browser { height: 70%; }\n #devtools { height: 30%; }\n </style>\n</head>\n<body>\n <webview id=\"browser\" src=\"https://github.com\"></webview>\n <webview id=\"devtools\" src=\"about:blank\"></webview>\n <script>\n const { ipcRenderer } = require('electron')\n const emittedOnce = (element, eventName) => new Promise(resolve => {\n element.addEventListener(eventName, event => resolve(event), { once: true })\n })\n const browserView = document.getElementById('browser')\n const devtoolsView = document.getElementById('devtools')\n const browserReady = emittedOnce(browserView, 'dom-ready')\n const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')\n Promise.all([browserReady, devtoolsReady]).then(() => {\n const targetId = browserView.getWebContentsId()\n const devtoolsId = devtoolsView.getWebContentsId()\n ipcRenderer.send('open-devtools', targetId, devtoolsId)\n })\n </script>\n</body>\n</html>\n// メインプロセス\nconst { ipcMain, webContents } = require('electron')\nipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {\n const target = webContents.fromId(targetContentsId)\n const devtools = webContents.fromId(devtoolsContentsId)\n target.setDevToolsWebContents(devtools)\n target.openDevTools()\n})\nBrowserWindow 内で開発者向けツールを表示する例:
const { app, BrowserWindow } = require('electron')\n\nlet win = null\nlet devtools = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n devtools = new BrowserWindow()\n win.loadURL('https://github.com')\n win.webContents.setDevToolsWebContents(devtools.webContents)\n win.webContents.openDevTools({ mode: 'detach' })\n})\ncontents.openDevTools([options])options Object (任意)mode String - 指定したドック状態で開発者向けツールを開く。right、bottom、undocked、detach にできる。 省略値は最後に使用したときのドック状態。 undocked モードではドックを後ろにやれる。 detach モードではできない。activate Boolean (任意) - 開かれたデベロッパー ツールウインドウを前面に表示するかどうか。 省略値は true です。開発者向けツールを開く。
\ncontents が <webview> タグである場合、デフォルトでは mode が detach になり、空の mode を明示的に渡すと最後に使用されたドックステートを使用して強制的に実行されます。
contents.closeDevTools()開発者向けツールを閉じる。
\ncontents.isDevToolsOpened()戻り値 Boolean - 開発者向けツールが開かれているかどうか。
contents.isDevToolsFocused()戻り値 Boolean - 開発者向けツールがフォーカスされているかどうか。
contents.toggleDevTools()開発者向けツールをトグル切り替えします。
\ncontents.inspectElement(x, y)x Integery Integer(x, y) の位置の要素の検査を開始します。
contents.inspectSharedWorker()共有ワーカーコンテキストの開発者向けツールを開きます。
\ncontents.inspectSharedWorkerById(workerId)workerId StringID に基づいて共有ワーカーのインスペクターを起動します。
\ncontents.getAllSharedWorkers()戻り値 SharedWorkerInfo[] - すべての共有ワーカーに関する情報。
contents.inspectServiceWorker()サービスワーカコンテキストの開発者向けツールを開きます。
\ncontents.send(channel, ...args)channel String...args any[]引数と共に、channel を介してレンダラープロセスに非同期メッセージを送信します。 引数は postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。
\n\n注意: DOM オブジェクトや特殊な Electron オブジェクトなど、非標準の JavaScript 型を送信すると例外が発生します。
\n
レンダラープロセスは ipcRenderer モジュールで channel を聞いてメッセージを処理できます。
以下はメインプロセスからレンダラープロセスにメッセージを送る例です。
\n// メインプロセス\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL(`file://${__dirname}/index.html`)\n win.webContents.on('did-finish-load', () => {\n win.webContents.send('ping', 'whoooooooh!')\n })\n})\n<!-- index.html -->\n<html>\n<body>\n <script>\n require('electron').ipcRenderer.on('ping', (event, message) => {\n console.log(message) // Prints 'whoooooooh!'\n })\n </script>\n</body>\n</html>\ncontents.sendToFrame(frameId, channel, ...args)frameId Integer | [number, number] - 送信先のフレームの ID、またはフレームがメインフレームと異なるプロセスにある場合に [processId, frameId] の組み合わせを指定します。channel String...args any[]引数と共に、channel を介してレンダラープロセス内の指定のフレームに非同期メッセージを送信します。 引数は postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。
\n\n注意: DOM オブジェクトや特殊な Electron オブジェクトなど、非標準の JavaScript 型を送信すると例外が発生します。
\n
レンダラープロセスは ipcRenderer モジュールで channel を聞いてメッセージを処理できます。
与えられたレンダラーコンテキストの frameId を取得したい場合は、webFrame.routingId の値を使用します。 以下は例です。
// レンダラープロセス内\nconsole.log('My frameId is:', require('electron').webFrame.routingId)\nメインプロセス内の受信した IPC メッセージすべてから frameId を読み取ることもできます。
// メインプロセス内\nipcMain.on('ping', (event) => {\n console.info('Message came from frameId:', event.frameId)\n})\ncontents.postMessage(channel, message, [transfer])レンダラープロセスにメッセージを送信し、任意で 0 個以上の [MessagePortMain][] オブジェクトの所有権を転送します。
転送された MessagePortMain オブジェクトは、レンダラープロセスで発生したイベントの ports プロパティにアクセスすれば利用できます。 レンダラーに着くと、それらはネイティブの DOM MessagePort オブジェクトになります。
以下がその例です。
\n// メインプロセス\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.postMessage('port', { message: 'hello' }, [port1])\n\n// レンダラープロセス\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\ncontents.enableDeviceEmulation(parameters)parameters ObjectscreenPosition String - エミュレートする画面の種類を以下から指定します (省略値: desktop)。desktop - デスクトップ画面タイプ.mobile - モバイル画面タイプ.screenSize Size - エミュレートされる画面サイズの設定 (screenPosition == mobile).viewPosition Point - スクリーン上のビューの位置 (screenPosition == mobile) (省略値: { x: 0, y: 0 }).deviceScaleFactor Integer - デバイスの拡大率の設定 (ゼロなら元々のデバイスの拡大率) (省略値: 0).screenSize Size - エミュレートされるビューのサイズの設定 (空は上書きしないことを意味する)scale Float - 有効なスペース内のエミュレートするビューの拡大率。 (表示モードにフィットしない) (省略値: 1).与えられた引数でデバイスのエミュレートを有効にします
\ncontents.disableDeviceEmulation()webContents.enableDeviceEmulation で有効にしたデバイスのエミュレートを向こうにします。
contents.sendInputEvent(inputEvent)inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent入力 event をページに送ります。 注釈: sendInputEvent() が動くには、そのコンテツを含む BrowserWindow がフォーカスされている必要があります。
contents.beginFrameSubscription([onlyDirty ,]callback)onlyDirty Boolean (任意) - 省略値は false。callback Functionimage NativeImagedirtyRect Rectangleプレゼンテーションイベントとキャプチャされたフレームの監視を開始し、プレゼンテーションイベントがあれば、callbabck が callback(image, dirtyRect) で呼ばれます。
image はキャプチャされたフレームを格納する NativeImage のインスタンスです。
dirtyRect は 再描画されたページの部分を示す x, y, width, height プロパティのオブジェクトです。 もし onlyDirty が true にセットされている場合、image は再描画された領域だけを含みます。 onlyDirty の省略値は false です。
contents.endFrameSubscription()フレームプレゼンテーションイベントの監視を終了します。
\ncontents.startDrag(item)item Objectfile String - ドラッグされているファイルのパス。files String - ドラッグされている複数ファイルのパス。 (files は file フィールドより優先されます)icon NativeImage | String - 画像です。macOS では空にできません。現在の D&D 操作のドラッグアイテムに item をセットします。file はドラッグされるファイルへの絶対パスで、icon はドラッグするときにカーソルの下に表示される画像です。
contents.savePage(fullPath, saveType)fullPath String - 完全なファイルパス。saveType String - 保存のタイプを指定します。HTMLOnly - ページの HTML だけを保存する。HTMLComplete - 完全な HTML ページを保存する。MHTML - MHTML として完全な HTML ページを保存する。戻り値 Promise<void> - ページが保存された場合に実行されます。
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.loadURL('https://github.com')\n\nwin.webContents.on('did-finish-load', async () => {\n win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {\n console.log('Page was saved successfully.')\n }).catch(err => {\n console.log(err)\n })\n})\ncontents.showDefinitionForSelection() macOSページ上の選択された単語を検索するポップアップ辞書を表示します。
\ncontents.isOffscreen()戻り値 Boolean - オフスクリーンレンダリング が有効にされているかどうかを示す。
contents.startPainting()もし オフスクリーンレンダリング が有効かつ描画中でなければ、描画を開始します。
\ncontents.stopPainting()もし オフスクリーンレンダリング が有効かつ描画中であれば、描画を終了します。
\ncontents.isPainting()戻り値 Boolean - もし オフスクリーンレンダリング が有効であれば、現在描画中かどうかを返します。
contents.setFrameRate(fps)fps Integerもし オフスクリーンレンダリング が有効であれば指定された数字にフレームレートをセットします。 1 から 240 の値のみを受け取ります。
\ncontents.getFrameRate()戻り値 Boolean - もし オフスクリーンレンダリング が有効であれば、現在のフレームレートを返します。
contents.invalidate()このウェブコンテンツが入っているウインドウの完全な再描画をスケジュールします。
\nもし オフスクリーンレンダリング が有効であれば、フレームを無効にし、'paint' を通して新しいフレームを生成します。
contents.getWebRTCIPHandlingPolicy()戻り値 String - WebRTC IP ハンドリングポリシーを返します。
contents.setWebRTCIPHandlingPolicy(policy)policy String - WebRTC IP ハンドリングポリシーを指定します。default - ユーザの公開IPとローカルIPを公開します。 これはデフォルトの動作です。 このポリシーが使用されるとき、WebRTC には、すべてのインターフェースを列挙し、それらを結合して公開インターフェースを検出する権利があります。default_public_interface_only - ユーザの公開IPを公開しますが、ユーザのローカルIPは公開しません。 このポリシーが使用されるとき、WebRTC は HTTP が使用するデフォルトのルートのみを使用する必要があります。 これはどのローカルアドレスも公開しません。default_public_and_private_interfaces - ユーザの公開IPとローカルIPを公開します。 このポリシーが使用されるとき、WebRTC は HTTP が使用するデフォルトのルートのみを使用する必要があります。 これは関連するデフォルトのプライベートアドレスも公開します。 デフォルトルートは、マルチホームのエンドポイント上で OS によって選択されたルートです。disable_non_proxied_udp - パブリック IP やローカル IP を非公開にします。 このポリシーが使用される WebRTC は、プロキシサーバーが UDP をサポートしていない限り、TCP を使用してピアまたはサーバーに接続する必要があります。WebRTC IP ハンドリングポリシーを設定すると、WebRTC を介して公開される IP を制御できます。 より詳しくは BrowserLeaks を参照して下さい。
\ncontents.getOSProcessId()戻り値 Integer - 関連するレンダラープロセスのオペレーティングシステムの pid。
contents.getProcessId()戻り値 Integer - 関連するレンダラーの Chromium 内部の pid。 フレーム特有のナビゲーションイベント (did-frame-navigate など) で渡される frameProcessId と比較できます。
contents.takeHeapSnapshot(filePath)filePath String - 出力ファイルのパス戻り値 Promise<void> - スナップショットの作成が成功したかどうかを示します。
V8 ヒープのスナップショットを撮り、それを filePath に保存します。
contents.getBackgroundThrottling()戻り値 Boolean - ページがバックグラウンドになったときに、この WebContents がアニメーションやタイマーを抑制するかどうか。 これは Page Visibility API にも影響を与えます。
contents.setBackgroundThrottling(allowed)allowed Booleanページがバックグラウンドになったときにこの WebContents がアニメーションとタイマーを抑制するかどうかを制御します。 これは Page Visibility API にも影響を与えます。
\ncontents.getType()Returns String - webContents の型。 backgroundPage、window、browserView、remote、webview か offscreen になります。
contents.setImageAnimationPolicy(policy)policy String - animate、animateOnce か noAnimation にできます。この webContents の画像アニメーションポリシーを設定します。 このポリシーは 新しく読み込まれた 画像にのみ適用され、現在アニメーションを行っている既存の画像は影響を受けません。 これは Chromium の既知の制限で、img.src = img.src とすることで画像のアニメーションを強制的に再計算させられます。この場合、ネットワークトラフィックは発生しませんが、アニメーションポリシーが更新されます。
これは、Chromium のアクセシビリティ機能である animationPolicy に対応します。
\ncontents.audioMutedこのページをミュートするかどうかを決定する Boolean プロパティ。
contents.userAgentこのウェブページのユーザーエージェントを決定する String プロパティ。
contents.zoomLevelこのウェブコンテンツのズームレベルを決定する Number プロパティ。
原寸は 0 で、各増減分はそれぞれ 20% ずつの拡大または縮小を表し、デフォルトで元のサイズの 300% から 50% までに制限されています。 The formula for this is scale := 1.2 ^ level.
contents.zoomFactorNumber 型のプロパティです。このウェブコンテンツのズーム率を決定します。
ズーム率は百分率のズームなので、300% = 3.0 になります。
\ncontents.frameRateInteger 型のプロパティです。ウェブコンテンツのフレームレートを指定された数値に設定します。 1 から 240 の値のみを受け取ります。
オフスクリーンレンダリング が有効な場合にのみ適用されます。
\ncontents.id 読み出し専用この WebContents の一意のIDを表す Integer。 各 ID は、この Electron アプリケーション全体のすべての WebContents インスタンス間で一意です。
contents.session 読み出し専用この webContents で使われる Session。
contents.hostWebContents 読み出し専用この WebContents を所有するかもしれない WebContents インスタンス。
contents.devToolsWebContents 読み出し専用WebContents | null 型のプロパティ。その WebContents に関連付けられたデベロッパー ツール の WebContents を表します。
注釈: 開発者向けツールが閉じられたときに null になる可能性があるので、このオブジェクトは決して格納しないで下さい。
contents.debugger 読み出し専用この webContents の Debugger インスタンス。
contents.backgroundThrottlingBoolean 型のプロパティです。ページがバックグラウンドになったときに、この WebContents がアニメーションやタイマーを抑制するかどうかを決定します。 これは Page Visibility API にも影響を与えます。
contents.mainFrame 読み出し専用WebFrameMain 型のプロパティで、ページの最上位階層のフレームを表します。
Electron の BrowserWindow に (サードパーティ) ウェブコンテンツを埋め込みたい場合は、<iframe> タグ、<webview> タグ、 BrowserView の 3 つの選択肢があります。 それぞれ多少の異なる機能を提供しており、さまざまな状況で役立ちます。 これらの選択を支援するため、このガイドではそれぞれの選択肢の違いと機能について説明します。
Electron の iframe は一般的なブラウザの iframe のように動作します。 コンテンツセキュリティポリシー で許可されている場合、ページの <iframe> 要素に外部ウェブページを表示できます。 <iframe> タグ内のサイト機能を制限するために、sandbox 属性 を使用してサポートしたい機能のみを許可することを推奨します。
\n\n重要な注意: WebView タグはアプリケーションの安定性に影響を与えうる劇的なアーキテクチャ変更を受けているため、これの利用は非推奨です。
\niframeや Electron のBrowserViewのような代替品や、設計の段階からコンテンツ埋め込みを避けるアーキテクチャへ切り替えるように検討してください。
WebView は Chromium の WebView が基ですが、Electron は明示的にサポートしていません。 将来の Electron のバージョンでも WebView API が利用できる保証はありません。 <webview> タグを使用する場合、BrowserWindow の webPreferences に内で webviewTag を true に設定する必要があります。
WebView は、Electron 内でのみ機能するカスタム要素 (<webview>) です。 これは \"プロセス外 iframe\" として実装されています。 つまり、<webview> とのすべての通信は IPC を用いて非同期的に行われます。 <webview> 要素には、webContents と同様に多くのカスタムメソッドとイベントがあり、コンテンツのより広い制御を提供します。
<iframe> と比較して <webview> はやや遅い傾向がありますが、サードパーティコンテンツのロード、通信など、さまざまなイベントの処理をより広く制御できます。
BrowserView は DOM の一部ではなく、メインプロセスで作成および制御されます。 これは、単に既存のウインドウ上に別のレイヤーでウェブコンテンツがあるだけです。 つまり、作成してある BrowserWindow のコンテンツから完全に分離され、その位置は DOM や CSS によって制御されません。 その代わり、メインプロセスで領域を設定して制御します。
BrowserView は BrowserWindow の動作と同じになる様に webContents を実装しているので、コンテンツに対して最大限の制御を提供できます。 しかし、BrowserView は DOM の一部ではなく画面上に重ねてあるだけなので、その位置は手動で管理する必要があります。
\n\n現在のウェブページの描画をカスタマイズします。
\n
プロセス: Renderer
\nwebFrame は現在の BrowserWindow のトップフレームで表示されている WebFrame クラスのインスタンスをエクスポートする Electron のモジュールです。 サブフレームは特定のプロパティとメソッド (webFrame.firstChild など) によって取得されます。
現在のページを 200% にズームするサンプルです。
\nconst { webFrame } = require('electron')\n\nwebFrame.setZoomFactor(2)\nWebFrameクラスには以下のメソッドがあります。
webFrame.setZoomFactor(factor)factor Double - 拡大率。省略値は 1.0 です。指定の拡大率に変更します。 拡大率は百分率なので、300% = 3.0 です。
\n拡大率は 0.0 より大きい必要があります。
\nwebFrame.getZoomFactor()戻り値 Number - 現在の拡大率。
webFrame.setZoomLevel(level)level Number - 拡大レベル。指定レベルに拡大レベルを変更します。 原寸は 0 で、各増減分はそれぞれ 20% ずつの拡大または縮小を表し、デフォルトで元のサイズの 300% から 50% までに制限されています。
\n\n\n注意: Chromium でのズームポリシーはドメインごとです。すなわち、特定ドメインのズームレベルは、同じドメインのウィンドウの全インスタンスに伝播します。 ウインドウの URL が別々であれば、ウインドウごとのズームになります。
\n
webFrame.getZoomLevel()戻り値 Number - 現在の拡大レベル。
webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel Numberピンチによる拡大レベルの最大値と最小値を設定します。
\n\n\n注意: Electron ではデフォルトで視覚ズームは無効化されています。 再び有効にする場合は以下を呼び出します。
\n\nwebFrame.setVisualZoomLevelLimits(1, 3)\n
\n\n注意: 視覚ズームはピンチによるズームの動作でのみ適用されます。 Cmd+/-/0 ズームのショートカットは、それぞれアプリケーションの Menu の 'zoomIn'、'zoomOut'、'resetZoom' の MenuItem ロールで制御されます。 ショートカットを無効にするには、手動で Menu の定義 を行い、定義からズームのロールを除きます。
\n
webFrame.setSpellCheckProvider(language, provider)language Stringprovider ObjectspellCheck Functionwords String[]callback FunctionmisspeltWords String[]入力フィールドとテキストエリアのスペルチェックのプロバイダを設定します。
\nこのメソッドを使用する場合は、ウインドウを構築するときに組み込みスペルチェックを無効にする必要があります。
\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: false\n }\n})\nprovider は、スペルチェックのために個々の単語の配列を受け取る spellCheck メソッドを持つオブジェクトである必要があります。 spellCheck 関数は非同期的に実行され、完了時にスペルミスの単語を含む callback 関数を呼び出します。
node-spellchecker をプロバイダとして使用するサンプルです。
\nconst { webFrame } = require('electron')\nconst spellChecker = require('spellchecker')\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck (words, callback) {\n setTimeout(() => {\n const spellchecker = require('spellchecker')\n const misspelled = words.filter(x => spellchecker.isMisspelled(x))\n callback(misspelled)\n }, 0)\n }\n})\nwebFrame.insertCSS(css)css String - CSS ソースコード。戻り値 String - 挿入された CSS のキー。後で webFrame.removeInsertedCSS(key) を介して CSS を削除するために使用できます。
現在のウェブページに CSS を挿入し、挿入されたスタイルシートの一意なキーを返します。
\nwebFrame.removeInsertedCSS(key)key String現在のウェブページから挿入された CSS を削除します。 スタイルシートは webFrame.insertCSS(css) から返されるキーで識別されます。
webFrame.insertText(text)text Stringフォーカスされた要素に text を挿入します。
webFrame.executeJavaScript(code[, userGesture, callback])code StringuserGesture Boolean (任意) - 省略値は false。callback Function (任意) - スクリプトの実行後に呼び出されます。 フレームがサスペンド (モーダルアラートの表示など) されない限り、実行は同期的に行われ、メソッドから戻る前にコールバックが呼び出されます。 このメソッドは古いバージョンとの互換性のため、エラーが第 2 引数です。result Anyerror Error戻り値 Promise<any> - 実行されたコードの結果で resolve されるか、実行でスロー又は reject された結果の場合に reject される Promise。
ページ内の code を評価します。
ブラウザウインドウでは、requestFullScreen のような、いくつかの HTML API は、ユーザからのジェスチャーでのみ呼び出されます。 userGesture を true にセットすることでこの制限がなくなります。
webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])worldId Integer - 0 は (コンテンツを実行する) デフォルトのメインワールド、999 は Electron の contextIsolation 機能で使用されるワールドです。 1..536870911 の範囲の値を受け付けます。scripts WebSource[]userGesture Boolean (任意) - 省略値は false。callback Function (任意) - スクリプトの実行後に呼び出されます。 フレームがサスペンド (モーダルアラートの表示など) されない限り、実行は同期的に行われ、メソッドから戻る前にコールバックが呼び出されます。 このメソッドは古いバージョンとの互換性のため、エラーが第 2 引数です。result Anyerror Error戻り値 Promise<any> - コードの実行結果で resolve するか、実行を開始できなかった場合に reject される Promise。
executeJavaScript のように動きますが、 scripts はイソレートコンテキスト内で評価します。
スクリプトの実行そのものが失敗した場合、返された Promise 拒否されず result は undefined になることに注意してください。 これは、Chromium が隔離されたワールドから外のワールドへエラーを転送しないためです。
webFrame.setIsolatedWorldInfo(worldId, info)worldId Integer - JavaScript を実行するワールドの ID。0 はデフォルトのワールドで、999 は Electron の contextIsolation 機能で使用されるワールドです。 Chrome 拡張機能の ID は [1 << 20, 1 << 29) の範囲で確保します。 任意の整数を指定できます。info ObjectsecurityOrigin String (任意) - 隔離された空間のためのセキュリティオリジンcsp String (任意) - 隔離された空間のためのコンテンツセキュリティポリシーname String (任意) - 隔離されたワールドの名前。 デベロッパー ツールで役立ちます。隔離されたワールドのセキュリティオリジン、コンテンツセキュリティポリシー、名前を設定します。 注: csp が指定されている場合は、securityOrigin も指定する必要があります。
webFrame.getResourceUsage()戻り値 Object:
images MemoryUsageDetailsscripts MemoryUsageDetailscssStyleSheets MemoryUsageDetailsxslStyleSheets MemoryUsageDetailsfonts MemoryUsageDetailsother MemoryUsageDetailsBlink の内部メモリキャッシュの使用情報を記述しているオブジェクトを返します。
\nconst { webFrame } = require('electron')\nconsole.log(webFrame.getResourceUsage())\nこれが生成されます。
\n{\n images: {\n count: 22,\n size: 2549,\n liveSize: 2542\n },\n cssStyleSheets: { /* \"images\" と同じ */ },\n xslStyleSheets: { /* \"images\" と同じ */ },\n fonts: { /* \"images\" と同じ */ },\n other: { /* \"images\" と同じ\" */ }\n}\nwebFrame.clearCache()以前使用していたメモリを解放しようとします (以前のナビゲーションの画像など)。
\nこのメソッドを盲目的に呼び出すと、空になったキャッシュを補充する必要があるため、Electron の処理速度が遅くなる可能性があることに注意してください。アプリ内のイベントが発生してページの実際のメモリ使用量が少なくなったと思われる場合にのみ呼び出すようにしてください (即ち、とても重いページから空のページへナビゲートし、そこにとどまるとき)。
\nwebFrame.getFrameForSelector(selector)selector String - フレーム要素の CSS セレクタ。戻り値 WebFrame - selector によって選択された webFrame のドキュメント。selector がフレームを選択していないか現在のレンダラープロセスにそのフレームがない場合、null が返されます。
webFrame.findFrameByName(name)name String戻り値 WebFrame - 与えられた name である webFrame の子。そのようなフレームが存在しないか現在のレンダラープロセスにそのフレームがない場合、null が返されます。
webFrame.findFrameByRoutingId(routingId)routingId Integer - 現在のレンダラープロセスでの一意なフレーム ID を表す Integer。 ルーティング ID は WebFrame インスタンス (webFrame.routingId) や、フレーム特有の WebContents ナビゲーションイベント (did-frame-navigate など) から取得できます。戻り値 WebFrame - 渡された routingId のもの。見つからなければ null。
webFrame.isWordMisspelled(word)word String - スペルチェックされる単語。戻り値 Boolean - 組み込みスペルチェッカーでスペルミスを検知した場合は true、そうでない場合は false です。 辞書が読み込まれていない場合は、常に false を返します。
webFrame.getWordSuggestions(word)word String - スペルミスのある単語。戻り値 String[] - 指定の単語に対する候補のリスト。 単語のスペルが正しければ、結果は空です。
webFrame.top 読み出し専用webFrame が属するフレーム階層内のトップフレームを表す WebFrame | null。トップフレームが現在のレンダラープロセスにない場合、プロパティは null になります。
webFrame.opener 読み出し専用webFrame が開かれたフレームを表す WebFrame | null。開いたフレームが存在しないか現在のレンダラープロセスにない場合、プロパティは null になります。
webFrame.parent 読み出し専用webFrame の親フレームを表す WebFrame | null。webFrame がトップフレームか現在のレンダラープロセスにない場合、プロパティは null になります。
webFrame.firstChild 読み出し専用webFrame の最初の子フレームを表す WebFrame | null。webFrame に子フレームが存在しないか現在のレンダラープロセスにない場合、プロパティは null になります。
webFrame.nextSibling 読み出し専用次の兄弟フレームを表す WebFrame | null。webFrame がその親の最後の子フレームか、次の兄弟フレームが現在のレンダラープロセスにない場合、プロパティは null になります。
webFrame.routingId 読み出し専用現在のレンダラープロセスでの一意なフレーム ID を表す Integer。 同じ基底フレームを参照する WebFrame インスタンスは、同じ routingId を持ちます。
\n\nウェブページと iframe を制御します。
\n
プロセス: Main
\nwebFrameMain モジュールは、既存の WebContents インスタンスを横断したフレームの探索に利用できます。 ナビゲーションイベントがよくあるユースケースでしょう。
const { BrowserWindow, webFrameMain } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://twitter.com')\n\nwin.webContents.on(\n 'did-frame-navigate',\n (event, url, isMainFrame, frameProcessId, frameRoutingId) => {\n const frame = webFrameMain.fromId(frameProcessId, frameRoutingId)\n if (frame) {\n const code = 'document.body.innerHTML = document.body.innerHTML.replaceAll(\"heck\", \"h*ck\")'\n frame.executeJavaScript(code)\n }\n }\n)\nまた、WebContents の mainFrame プロパティを使用することでも既存ページのフレームへアクセスできます。
const { BrowserWindow } = require('electron')\n\nasync function main () {\n const win = new BrowserWindow({ width: 800, height: 600 })\n await win.loadURL('https://reddit.com')\n\n const youtubeEmbeds = win.webContents.mainFrame.frames.filter((frame) => {\n try {\n const url = new URL(frame.url)\n return url.host === 'www.youtube.com'\n } catch {\n return false\n }\n })\n\n console.log(youtubeEmbeds)\n}\n\nmain()\nこれらのメソッドは、webFrameMain モジュールからアクセスできます。
webFrameMain.fromId(processId, routingId)processId Integer - Integer 型で、そのフレームを所有しているプロセスの内部 ID を表します。routingId Integer - Integer 型で、現在のレンダラープロセスでの一意なフレーム ID を表します。 ルーティング ID は、WebFrameMain インスタンス (frame.routingId) から取得できるほか、フレーム固有の WebContents ナビゲーションイベント (did-frame-navigate など) によっても渡されます。戻り値 WebFrameMain | undefined - 指定のプロセスとルーティングの ID のフレームです。指定の ID に関連付けられた WebFrameMain がない場合は undefined になります。
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
document が読み込まれたときに発生します
\nframe.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (任意) - 省略値は false。戻り値 Promise<unknown> - Promise 型で、コードの実行結果で解決され、実行で例外の送出または実行結果が拒否された Promise の場合は拒否されます。
ページ内の code を評価します。
ブラウザウインドウでは、requestFullScreen のような、いくつかの HTML API は、ユーザからのジェスチャーでのみ呼び出されます。 userGesture を true にセットすることでこの制限がなくなります。
frame.reload()戻り値 boolean - リロードが正常に開始されたかどうか。 フレームに履歴がない場合のみ false になります。
frame.send(channel, ...args)channel String...args any[]引数と共に、channel を介してレンダラープロセスに非同期メッセージを送信します。 引数は [postMessage][] と同様に [構造化複製アルゴリズム][SCA] でシリアライズされるので、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。
レンダラープロセスは ipcRenderer モジュールで channel を聞いてメッセージを処理できます。
frame.postMessage(channel, message, [transfer])レンダラープロセスにメッセージを送信し、任意で 0 個以上の [MessagePortMain][] オブジェクトの所有権を転送します。
転送された MessagePortMain オブジェクトは、レンダラープロセスで発生したイベントの ports プロパティにアクセスすれば利用できます。 レンダラーに着くと、それらはネイティブの DOM MessagePort オブジェクトになります。
以下がその例です。
\n// メインプロセス\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])\n\n// レンダラープロセス\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nframe.url 読み出し専用string 型で、そのフレームの現在の URL を表します。
frame.top 読み出し専用WebFrameMain | null 型で、frame が属するフレーム階層の最上位フレームを表します。
frame.parent 読み出し専用WebFrameMain | null 型で、frame の親フレームを表します。frame がそのフレーム階層の最上位フレームであれば、このプロパティは null です。
frame.frames 読み出し専用WebFrameMain[] 型で、frame の直接の子フレームを格納するコレクションです。
frame.framesInSubtree 読み出し専用WebFrameMain[] 型で、frame のサブツリーのうち自身を含んだ全フレームのコレクションです。 これは、すべてのフレームをトラバースするときに便利です。
frame.frameTreeNodeId 読み出し専用Integer 型で、フレーム内部の FrameTreeNode インスタンスの ID を表します。 この ID はブラウザー内で共通となっており、コンテンツをホストするフレームを一意に識別します。 識別子はフレーム作成時に固定され、フレームが有効である間は変化しません。 フレームが削除されると、その ID が再び使用されることはありません。
frame.name 読み出し専用String 型で、そのフレームの名前を表します。
frame.osProcessId 読み出し専用Integer 型で、このフレームを所有するプロセスのオペレーティングシステムの pid を表します。
frame.processId 読み出し専用Integer 型で、このフレームを所有するプロセスの Chromium 内部の pid を表します。 これは OS のプロセス ID と同じではありません。それを読み出すには frame.osProcessId を使用してください。
frame.routingId 読み出し専用現在のレンダラープロセスでの一意なフレーム ID を表す Integer。 同じ基底フレームを参照する WebFrameMain インスタンスすべては、それぞれ同じ routingId になります。
frame.visibilityState 読み出し専用string 型で、そのフレームの 可視性の状態 を表します。
Page 可視性 API が他の Electron API から受ける影響についてもご覧ください。
", "title": "webFrameMain", "description": "ウェブページと iframe を制御します。" }, "/docs/api/web-request": { "locale": "ja-JP", "slug": "web-request", "href": "/docs/api/web-request", "crowdinFileId": "256405", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-request.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nライフタイムのさまざまな段階でリクエストのコンテンツを傍受し、変更します。
\n
プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
WebRequest クラスのインスタンスには、Session の webRequest プロパティを使用してアクセスします。
WebRequest のメソッドは、任意の filter と listener を受け取ります。 listener は、リクエストが終了したときに listener(details) で呼ばれます。 details オブジェクトはリクエストについて記述します。
⚠️ 最後にアタッチされた listener のみが使用されます。 null を listener として渡すと、イベントの監視が解除されます。
filter オブジェクトには、urls プロパティがあります。これは、URL パターンと一致しないリクエストをフィルタリングするために使用される URL パターンの配列です。 filter を省略するとすべてのリクエストがマッチします。
特定のイベントでは、listener には callback が渡されます。これは、listener が処理を終えたときに response オブジェクトとともに呼び出される必要があります。
以下はリクエストに User-Agent ヘッダーを追加する例です。
const { session } = require('electron')\n\n// 以下の URL へのすべてのリクエストのユーザエージェントを変更します。\nconst filter = {\n urls: ['https://*.github.com/*', '*://electron.github.io']\n}\n\nsession.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {\n details.requestHeaders['User-Agent'] = 'MyAgent'\n callback({ requestHeaders: details.requestHeaders })\n})\nWebRequest のインスタンスでは、以下のメソッドが利用できます。
webRequest.onBeforeRequest([filter, ]listener)filter WebRequestFilter (任意)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (任意)webContents WebContents (任意)frame WebFrameMain (任意)resourceType String - mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket、other のいずれかにできます。referrer Stringtimestamp DoubleuploadData UploadData[]callback Functionresponse Objectcancel Boolean (任意)redirectURL String (任意) - 元のリクエストは送信または終了されず、代わりに指定された URL にリダイレクトされます。listener は、リクエストが発生しようとしているときに listener(details, callback) で呼ばれます。
uploadData は、UploadData オブジェクトの配列です。
callback は、response オブジェクトで呼ぶ必要があります。
いくつか有効な url の例を示します。
'http://foo:1234/'\n'http://foo.com/'\n'http://foo:1234/bar'\n'*://*/*'\n'*://example.com/*'\n'*://example.com/foo/*'\n'http://*.foo:1234/'\n'file://foo:1234/bar'\n'http://foo:*/'\n'*://www.foo.com/'\nwebRequest.onBeforeSendHeaders([filter, ]listener)filter WebRequestFilter (任意)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (任意)webContents WebContents (任意)frame WebFrameMain (任意)resourceType String - mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket、other のいずれかにできます。referrer Stringtimestamp DoublerequestHeaders Record<string, string>callback FunctionbeforeSendResponse Objectcancel Boolean (任意)requestHeaders Record<string, string | string[]> (任意) - 指定すると、これらのヘッダでリクエストが作成されます。リクエストヘッダが利用可能になると、HTTP リクエストを送信する前に listener が listener(details, callback) で呼び出されます。 これは、サーバーに TCP 接続が行われた後、HTTP データが送信される前に発生する可能性があります。
callback は、response オブジェクトで呼ぶ必要があります。
webRequest.onSendHeaders([filter, ]listener)filter WebRequestFilter (任意)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (任意)webContents WebContents (任意)frame WebFrameMain (任意)resourceType String - mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket、other のいずれかにできます。referrer Stringtimestamp DoublerequestHeaders Record<string, string>listener は、リクエストがサーバに送信される直前に listener(details) で呼び出され、以前の onBeforeSendHeaders レスポンスの変更は、このリスナが起動される時までに表示されます。
webRequest.onHeadersReceived([filter, ]listener)filter WebRequestFilter (任意)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (任意)webContents WebContents (任意)frame WebFrameMain (任意)resourceType String - mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket、other のいずれかにできます。referrer Stringtimestamp DoublestatusLine StringstatusCode IntegerresponseHeaders Record<string, string[]> (任意)callback FunctionheadersReceivedResponse Objectcancel Boolean (任意)responseHeaders Record<string, string | string[]> (任意) - 指定すると、サーバはこれらのヘッダでレスポンスしたものとみなされます。statusLine String (任意) - ヘッダのステータスを変更するために responseHeaders をオーバーライドする場合に指定する必要があります。そうしないと、元の応答ヘッダのステータスが使用されます。listener は、HTTP リクエストのレスポンスヘッダを受信したときに listener(details, callback) で呼ばれます。
callback は、response オブジェクトで呼ぶ必要があります。
webRequest.onResponseStarted([filter, ]listener)filter WebRequestFilter (任意)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (任意)webContents WebContents (任意)frame WebFrameMain (任意)resourceType String - mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket、other のいずれかにできます。referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (任意)fromCache Boolean - レスポンスがディスクキャッシュからフェッチされたかどうかを示します。statusCode IntegerstatusLine Stringlistener は、レスポンスボディの最初のバイトを受信したときに listener(details) で呼ばれます。 HTTP リクエストの場合、これはステータスラインとレスポンスヘッダが使用可能であることを意味します。
webRequest.onBeforeRedirect([filter, ]listener)filter WebRequestFilter (任意)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (任意)webContents WebContents (任意)frame WebFrameMain (任意)resourceType String - mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket、other のいずれかにできます。referrer Stringtimestamp DoubleredirectURL StringstatusCode IntegerstatusLine Stringip String (任意) - リクエストが実際に送信されたサーバーの IP アドレス。fromCache BooleanresponseHeaders Record<string, string[]> (任意)listener は、サーバーが始めたリダイレクトが発生しようとしているときに listener(details) で呼ばれます。
webRequest.onCompleted([filter, ]listener)filter WebRequestFilter (任意)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (任意)webContents WebContents (任意)frame WebFrameMain (任意)resourceType String - mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket、other のいずれかにできます。referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (任意)fromCache BooleanstatusCode IntegerstatusLine Stringerror Stringlistener は、リクエストが終了したときに listener(details) で呼ばれます。
webRequest.onErrorOccurred([filter, ]listener)filter WebRequestFilter (任意)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (任意)webContents WebContents (任意)frame WebFrameMain (任意)resourceType String - mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket、other のいずれかにできます。referrer Stringtimestamp DoublefromCache Booleanerror String - エラーの内容。listener は、エラーが発生したときに listener(details) で呼ばれます。
urls String[] - URL パターンと一致しないリクエストを除去するために使用される URL パターンの配列。code Stringurl String (optional)startLine Integer (optional) - Default is 1.<webview>タグElectron の webview タグは Chromium の webview に基づきつつ、劇的に変更されています。 これはレンダリング、ナビゲーション、イベントルーティングを含む webview の安定性に影響しています。 私たちは webview タグを使用せずに、iframe や Electron の BrowserView、または埋め込みコンテンツを完全に避けるアーキテクチャにするといった代替案の検討を推奨しています。
既定では webview タグは Electron >= 5 では無効化されています。 タグを有効にするには、BrowserWindow を構築するときに webviewTag webPreferences オプションを設定します。 詳しい情報については、BrowserWindow コンストラクタ を参照してください。
\n\n分離したフレームとプロセスに外部ウェブコンテンツを表示します。
\n
プロセス: レンダラー
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。
webviewタグを使用して、Electron アプリに 'ゲスト' コンテンツ (ウェブページなど) を埋め込むことができます。 ゲストコンテンツは webview コンテナに含まれています。 アプリ内の埋め込みページは、ゲストコンテンツのレイアウトとレンダリングの方法を制御します。
iframe と異なり、 webview はアプリとは別のプロセスで実行されます。 これはウェブページと同じ権限を持っておらず、アプリと埋め込みコンテンツの間のやりとりは全て非同期になります。 これにより、埋め込みコンテンツからアプリが保護されます。 注釈: ホストページから webview 上で呼び出されるほとんどのメソッドは、メインプロセスへの同期呼び出しを必要とします。
アプリにウェブページを埋め込むには、アプリの埋め込みページ (これはゲストコンテンツを表示するアプリページ) へ webview タグを追加します。 最もシンプルな形式では、webview タグには、ウェブページの src と、webview コンテナの見た目を制御する CSS スタイルが含まれます。
<webview id=\"foo\" src=\"https://www.github.com/\" style=\"display:inline-flex; width:640px; height:480px\"></webview>\nゲストコンテンツを制御したい場合は、webview のイベントを傍受し、webview のメソッドを使用してそれらのイベントに応答する JavaScript を記述することでできます。 ここでは、2つのイベントリスナーを持つサンプルコードを示します。1つはウェブページのロード開始を、もう1つはウェブページのロード停止を傍受し、ロード時に \"ロード中...\" というメッセージを表示します。
<script>\n onload = () => {\n const webview = document.querySelector('webview')\n const indicator = document.querySelector('.indicator')\n\n const loadstart = () => {\n indicator.innerText = 'loading...'\n }\n\n const loadstop = () => {\n indicator.innerText = ''\n }\n\n webview.addEventListener('did-start-loading', loadstart)\n webview.addEventListener('did-stop-loading', loadstop)\n }\n</script>\n内部では webview は Out-of-Process iframe (OOPIF) で実装されています。 webview タグは本質的には、見えない DOM を用いてその内側に iframe 要素をラップしたカスタム要素です。
なので webview の動作はクロスドメイン iframe ととても似ています。例として、
webviewをクリックしたとき、ページフォーカスが埋め込みフレームから webview に移動します。webview にキーボード、マウス、スクロールイベントリスナを追加することはできません。webview 間のすべての反応は非同期です。webview タグのスタイルでは、webview コンテナでの子の iframe 要素の高さと幅を完全に埋めるのに内部的に display:flex; を使用しているので、古典的かつフレックスボックスなレイアウトを使用するときは注意して下さい。 display:inline-flex; をインラインレイアウトに指定しない限り、デフォルトのdisplay:flex; CSS プロパティを上書きしないでください。
webview タグには以下の属性があります。
src<webview src=\"https://www.github.com/\"></webview>\n表示される URL を表す String。 この属性に書き込むと、最上位のナビゲーションが始まります。
src に独自の値を代入すると、現在のページがリロードされます。
src 属性は、data:text/plain,Hello, world! などのデータ URL を受け取ることもできます。
nodeintegration<webview src=\"http://www.google.com/\" nodeintegration></webview>\nBoolean。 この属性が存在する場合、webview のゲストページは Node Integration を持ち、低レベルのシステムリソースにアクセスするのに、require や process のような Node API が使用できます。 デフォルトでは、ゲストページ内の Node Integration は無効化されています。
nodeintegrationinsubframes<webview src=\"http://www.google.com/\" nodeintegrationinsubframes></webview>\nこの Boolean は webview 内の iframe などのサブフレームで NodeJS サポートを有効にするための実験的オプションです。 すべてのプリロードは iframe 毎にロードされます。メインフレーム内かそうでないか判断するには process.isMainFrame が使用できます。 デフォルトではゲストページ内のこのオプションは無効化されています。
plugins<webview src=\"https://www.github.com/\" plugins></webview>\nBoolean。 この属性が存在する場合、webview 内のゲストページはブラウザのプラグインを使用できます。 プラグインはデフォルトで無効です。
preload<!-- ファイルから -->\n<webview src=\"https://www.github.com/\" preload=\"./test.js\"></webview>\n<!-- または asar アーカイブから読み込みたい場合 -->\n<webview src=\"https://www.github.com/\" preload=\"./app.asar/test.js\"></webview>\nこの String は、ゲストのページで他のスクリプトを実行する前に読み込まれるスクリプトを指定します。 スクリプトの URL のプロトコルは file: である必要があります (asar: アーカイブを使用している場合でも)。これは、内部で Node の require によって、asar: アーカイブを仮想ディレクトリとして扱い読み込むためです。
ゲストページに Node Integration がない場合、このスクリプトはすべての Node APIにアクセスできますが、Node によって挿入されたグローバルオブジェクトはこのスクリプトの実行が終了した後に削除されます。
\n注: このオプションは、will-attach-webview イベントに指定された webPreferences に preloadURL (preload ではない) として表示されます。
httpreferrer<webview src=\"https://www.github.com/\" httpreferrer=\"http://cheng.guru\"></webview>\nゲストページの参照先 URL を設定する String。
useragent<webview src=\"https://www.github.com/\" useragent=\"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko\"></webview>\nページがナビゲーションされる前に設定するゲストページのユーザーエージェントの String。 そのページがロードされると、setUserAgent メソッドでユーザーエージェントを変更します。
disablewebsecurity<webview src=\"https://www.github.com/\" disablewebsecurity></webview>\nBoolean。 この属性が存在すると、ゲストページでウェブセキュリティが無効になります。 ウェブセキュリティはデフォルトで有効です。
partition<webview src=\"https://github.com\" partition=\"persist:github\"></webview>\n<webview src=\"https://electronjs.org\" partition=\"electron\"></webview>\nページが使用するセッションを設定する String です。 partition が persist: 始まりの場合、ページはアプリの全ページで利用可能な永続的なセッションを同じ partition で使用します。 persist: プレフィックスがない場合、ページは、インメモリセッションを使用します。 同じ partition を割り当てることによって、複数のページが同じセッションを共有できます。 partition が設定されていない場合は、アプリのデフォルトのセッションが使用されます。
アクティブなレンダラープロセスのセッションは変更できないため、この値は最初のナビゲーションの前にのみ変更できます。 その後の値の変更は、DOM 例外で失敗します。
\nallowpopups<webview src=\"https://www.github.com/\" allowpopups></webview>\nBoolean。 この属性が存在すると、ゲストページは新しいウィンドウを開くことができます。 ポップアップはデフォルトで無効です。
webpreferences<webview src=\"https://github.com\" webpreferences=\"allowRunningInsecureContent, javascript=no\"></webview>\nwebview に設定するウェブ設定を指定する文字列のコンマ区切りリストの String です。 サポートされている設定の文字列の完全なリストは、BrowserWindow にあります。
この文字列は、window.open の features 文字列と同じ形式に従います。 名前自体には true のブール値が与えられます。 設定は、= とそれに続く値を含めることによって別の値に設定できます。 特殊な値として、yes と 1 は true として解釈され、no と 0 は false として解釈されます。
enableblinkfeatures<webview src=\"https://www.github.com/\" enableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\n有効にする Blink 機能を指定する , 区切りの文字列リストである String です。 サポートされている機能の文字列の完全なリストは、RuntimeEnabledFeatures.json5 ファイルにあります。
disableblinkfeatures<webview src=\"https://www.github.com/\" disableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\n無効にする Blink 機能を指定する , 区切りの文字列リストである String です。 サポートされている機能の文字列の完全なリストは、RuntimeEnabledFeatures.json5 ファイルにあります。
webview タグには以下のメソッドがあります。
注釈: メソッドを使用する前に webview 要素をロードする必要があります。
\nサンプル
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('dom-ready', () => {\n webview.openDevTools()\n})\n<webview>.loadURL(url[, options])url URLoptions Object (任意)httpReferrer (String | Referrer) (任意) - HTTPリファラのURL。userAgent String (任意) - リクエスト元のユーザーエージェント。extraHeaders String (任意) - \"\\n\" で区切られた追加のヘッダーpostData (UploadRawData | UploadFile)baseURLForDataURL String (任意) - データURLによってロードされたファイルの (最後のパス区切り文字を含む) ベースURL。 これは指定された url がデータURLで、他のファイルをロードする必要がある場合のみ必要です。戻り値 Promise<void> - この promise は、ページ読み込みが完了した時 (did-finish-load を参照) に解決され、ページの読み込みに失敗した時 (did-fail-load を参照) に拒否されます。
url を webview にロードします。url には、http:// または file:// のような、プロトコルのプレフィックスを含みます。
<webview>.downloadURL(url)url Stringナビゲーションなしで url のリソースのダウンロードを初期化します。
<webview>.getURL()戻り値 String - ゲストページの URL。
<webview>.getTitle()戻り値 String - ゲストページのタイトル。
<webview>.isLoading()戻り値 Boolean - ゲストページがまだリソースを読み込んでいるかどうか。
<webview>.isLoadingMainFrame()戻り値 Boolean - メインフレーム (iframe やフレーム内のフレームだけではない) がまだ読み込んでいるかどうか。
<webview>.isWaitingForResponse()戻り値 Boolean - ゲストページが、ページのメインリソースからの最初の応答を待機しているかどうか。
<webview>.stop()保留中のナビゲーションを停止します。
\n<webview>.reload()ゲストページを再読み込みします。
\n<webview>.reloadIgnoringCache()ゲストページを、キャッシュを無視して再読み込みします。
\n<webview>.canGoBack()戻り値 Boolean - ゲストページが前に戻れるかどうか。
<webview>.canGoForward()戻り値 Boolean - ゲストページが次に進めるかどうか。
<webview>.canGoToOffset(offset)offset Integer戻り値 Boolean - offset 番目のゲストページへ行けるかどうか。
<webview>.clearHistory()ナビゲーション履歴を消去します。
\n<webview>.goBack()ゲストページを前に戻します。
\n<webview>.goForward()ゲストページを次に進めます。
\n<webview>.goToIndex(index)index Integer指定した絶対インデックスへナビゲーションします。
\n<webview>.goToOffset(offset)offset Integer現在のエントリから指定したオフセットへナビゲーションします。
\n<webview>.isCrashed()戻り値 Boolean - レンダラープロセスがクラッシュしたかどうか。
<webview>.setUserAgent(userAgent)userAgent Stringゲストページページのユーザエージェントをオーバーライドします。
\n<webview>.getUserAgent()戻り値 String - ゲストページのユーザエージェント。
<webview>.insertCSS(css)css String戻り値 Promise<String> - 挿入された CSS のキーで解決される promise。後で <webview>.removeInsertedCSS(key) を使用して CSS を削除するために使用できます。
現在のウェブページに CSS を挿入し、挿入されたスタイルシートの一意なキーを返します。
\n<webview>.removeInsertedCSS(key)key String戻り値 Promise<void> - 削除に成功すると解決されます。
現在のウェブページから挿入された CSS を削除します。 スタイルシートは <webview>.insertCSS(css) から返されるキーで識別されます。
<webview>.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (任意) - 省略値は false。戻り値 Promise<any> - 実行されたコードの結果で resolve する Promise。コードの結果が reject な Promise である場合は reject な Promise。
ページ内の code を評価します。 userGesture が設定されている場合、ページのユーザジェスチャコンテキストが作成されます。 requestFullScreen のようなユーザの操作を必要とする HTML API は、このオプションを自動化に利用できます。
<webview>.openDevTools()ゲストページの開発者向けツールウインドウを開きます。
\n<webview>.closeDevTools()ゲストページの開発者向けツールウインドウを閉じます。
\n<webview>.isDevToolsOpened()戻り値 Boolean - ゲストページに開発者向けツールウインドウが適用されているかどうか。
<webview>.isDevToolsFocused()戻り値 Boolean - ゲストページの開発者向けツールウインドウがフォーカスされているかどうか。
<webview>.inspectElement(x, y)x Integery Integerゲストページの (x, y) の位置の要素の検査を開始します。
<webview>.inspectSharedWorker()ゲストページに表示されている共有ワーカーコンテキストの開発者向けツールを開きます。
\n<webview>.inspectServiceWorker()ゲストページに表示されているサービスワーカコンテキストの開発者向けツールを開きます。
\n<webview>.setAudioMuted(muted)muted Booleanゲストページをミュートに設定します。
\n<webview>.isAudioMuted()戻り値 Boolean - ゲストページがミュートされているかどうか。
<webview>.isCurrentlyAudible()戻り値 Boolean - 音声が現在再生中かどうか。
<webview>.undo()ページの undo 編集コマンドを実行します。
<webview>.redo()ページの redo 編集コマンドを実行します。
<webview>.cut()ページの cut 編集コマンドを実行します。
<webview>.copy()ページの copy 編集コマンドを実行します。
<webview>.paste()ページの paste 編集コマンドを実行します。
<webview>.pasteAndMatchStyle()ページの pasteAndMatchStyle 編集コマンドを実行します。
<webview>.delete()ページの delete 編集コマンドを実行します。
<webview>.selectAll()ページの selectAll 編集コマンドを実行します。
<webview>.unselect()ページの unselect 編集コマンドを実行します。
<webview>.replace(text)text Stringページの replace 編集コマンドを実行します。
<webview>.replaceMisspelling(text)text Stringページの replaceMisspelling 編集コマンドを実行します。
<webview>.insertText(text)text String戻り値 Promise<void>
フォーカスされた要素に text を挿入します。
<webview>.findInPage(text[, options])text String - 検索するコンテンツ。空にしてはいけません。options Object (任意)forward Boolean (任意) - 前方または後方を検索するかどうか。省略値は true。findNext Boolean (任意) - この要求で新規テキスト検索セッションを開始するかどうか。 最初の要求では true に、二度目以降の要求では false にする必要があります。 省略値は false 。matchCase Boolean (任意) - 大文字と小文字を区別する検索かどうか。省略値は false。戻り値 Integer - リクエストに使われたリクエスト ID。
ウェブページ内の text のすべてのマッチを探すリクエストを開始します。 リクエストの結果は found-in-page イベントを読むことで取得できます。
<webview>.stopFindInPage(action)action String - <webview>.findInPage リクエストを終了する際に行うアクションを指定します。clearSelection - 選択を消去する。keepSelection - その選択を通常の選択に変換する。activateSelection - 選択ノードをフォーカスして、クリックする。指定された action で、webview の findInPage リクエストを停止します。
<webview>.print([options])options Object (任意)silent Boolean (任意) - プリンタの設定をユーザに尋ねないかどうか。 省略値は false です。printBackground Boolean (任意) - ウェブページの背景色と画像を印刷するかどうか。 省略値は false です。deviceName String (任意) - 使用するプリンタデバイスの名前をセットします。 '人間向けの' 名称ではなくシステム定義名である必要があります。例えば、'Brother QL-820NWB' ではなく 'Brother_QL_820NWB' とします。color Boolean (任意) - 印刷するウェブページをカラーにするかグレースケールにするかを設定します。 省略値は true です。margins Object (任意)marginType String (任意) - default、none、printableArea か custom にできます。 custom を選択した場合、top、bottom、left、right も指定する必要があります。top Number (任意) - 印刷されたウェブページの上側のマージン。ピクセル単位です。bottom Number (任意) - 印刷されたウェブページの下側のマージン。ピクセル単位です。left Number (任意) - 印刷されたウェブページの左側のマージン。ピクセル単位です。right Number (任意) - 印刷されたウェブページの右側のマージン。ピクセル単位です。landscape Boolean (任意) - ウェブページを横向きモードで印刷するかどうか。 省略値は false です。scaleFactor Number (任意) - ウェブページのスケール係数。pagesPerSheet Number (任意) - ページシートごとに印刷するページ数。collate Boolean (任意) - ウェブページを校合するかどうか。copies Number (任意) - 印刷するウェブページの版数。pageRanges Object - 印刷するページ範囲。from Number - 印刷する最初のページのインデックス (0 始まり)。to Number - 印刷する最後のページのインデックス (これを含む) (0 始まり)。duplexMode String (任意) - 印刷されるウェブページの両面モードを設定します。 simplex、shortEdge、longEdge のいずれかにできます。dpi Record<string, number> (任意)horizontal Number (任意) - 水平 DPI。vertical Number (任意) - 垂直 DPI。header String (任意) - ページヘッダーとして印刷される文字列。footer String (任意) - ページフッターとして印刷される文字列。pageSize String | Size (任意) - 印刷するドキュメントのページサイズを指定します。 A3、A4、A5、Legal、Letter、Tabloid のいずれかにするか、height を含む Object にできます。戻り値 Promise<void>
webview のウェブページを印刷します。 webContents.print([options]) と同じです。
<webview>.printToPDF(options)options ObjectheaderFooter Record<string, string> (任意) - PDF のヘッダーとフッター。title String - PDF ヘッダーのタイトル。url String - PDF フッターの URL。landscape Boolean (任意) - true で横向き、false で縦向き。marginsType Integer (optional) - 使用する余白の種類を指定します。 0 で既定値、1 で余白なし、2 で最小限の余白になります。 width はミクロン単位です。scaleFactor Number (任意) - ウェブページのスケール係数。 0 から 100 の範囲にできます。pageRanges Record<string, number> (任意) - 印刷するページ範囲。 macOS では最初の範囲のみが使用されます。from Number - 印刷する最初のページのインデックス (0 始まり)。to Number - 印刷する最後のページのインデックス (これを含む) (0 始まり)。pageSize String | Size (任意) - 生成する PDF のページサイズを指定します。 A3、A4、A5、Legal、Letter、Tabloid のいずれかにするか、height を含む Object にできます。printBackground Boolean (任意) - CSS 背景を印刷するかどうか。printSelectionOnly Boolean (任意) - 選択部分だけを印刷するかどうか。戻り値 Promise<Uint8Array> - 生成された PDF データで実行されます。
webview のウェブページを PDF として印刷します。webContents.printToPDF(options) と同じです。
<webview>.capturePage([rect])rect Rectangle (任意) - キャプチャするページ内の領域。戻り値 Promise<NativeImage> - NativeImage を解決します
rect 内のページのスナップショットをキャプチャします。 rect を省略すると、表示されているページ全体をキャプチャします。
<webview>.send(channel, ...args)channel String...args any[]戻り値 Promise<void>
channel を介してレンダラープロセスに非同期メッセージを送信します。任意の引数を送ることもできます。 レンダラープロセスは ipcRenderer モジュールで channel イベントをリッスンしてメッセージを処理できます。
サンプルについては webContents.send を参照して下さい。
\n<webview>.sendToFrame(frameId, channel, ...args)frameId [number, number] - [processId, frameId]channel String...args any[]戻り値 Promise<void>
channel を介してレンダラープロセスに非同期メッセージを送信します。任意の引数を送ることもできます。 レンダラープロセスは ipcRenderer モジュールで channel イベントをリッスンしてメッセージを処理できます。
サンプルは webContents.sendToFrame をご参照ください。
\n<webview>.sendInputEvent(event)event MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent戻り値 Promise<void>
入力 event をページに送ります。
event オブジェクトの詳細については、webContents.sendInputEvent を参照してください。
<webview>.setZoomFactor(factor)factor Number - 拡大率。指定の拡大率に変更します。 拡大率は百分率なので、300% = 3.0 です。
\n<webview>.setZoomLevel(level)level Number - 拡大レベル。指定レベルに拡大レベルを変更します。 原寸は 0 で、各増減分はそれぞれ 20% ずつの拡大または縮小を表し、デフォルトで元のサイズの 300% から 50% までに制限されています。 この式は scale := 1.2 ^ level です。
\n\n注意: Chromium でのズームポリシーはドメインごとです。すなわち、特定ドメインのズームレベルは、同じドメインのウィンドウの全インスタンスに伝播します。 ウインドウの URL が別々であれば、ウインドウごとのズームになります。
\n
<webview>.getZoomFactor()戻り値 Number - 現在の拡大率。
<webview>.getZoomLevel()戻り値 Number - 現在の拡大レベル。
<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel Number戻り値 Promise<void>
ピンチによる拡大レベルの最大値と最小値を設定します。
\n<webview>.showDefinitionForSelection() macOSページ上の選択された単語を検索するポップアップ辞書を表示します。
\n<webview>.getWebContentsId()戻り値 Number - この webview の WebContents ID。
webview タグでは、以下の DOM イベントを使用できます。
戻り値：
\nurl StringisMainFrame Booleanロードを要求したときに発生します。 これには、現在のドキュメント内のナビゲーションとサブフレームのドキュメントレベルのロードが含まれますが、非同期のリソース読み込みは含まれません。
\nナビゲーションが終了した時、すなわち、タブのくるくるが止まったときや、onload イベントが送られた後に、発行されます。
戻り値：
\nerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame Booleanこのイベントは did-finish-load のようですが、ロードが失敗した、キャンセルされた、window.stop() が呼び出されたなどで発生します。
戻り値：
\nisMainFrame Booleanフレームのナビゲーションが終了したときに発行されます。
\nタブのくるくるが始まるタイミングに対応しています。
\nタブのくるくるが止まるタイミングに対応しています。
\n埋め込みWebコンテンツに添付したときに発行されます。
\n指定のフレームの document が読み込まれたときに発行されます。
\n戻り値：
\ntitle StringexplicitSet Booleanナビゲーション中にページタイトルが設定されると発生します。 explicitSet は、タイトルがファイル URL から合成されている場合に false になります。
戻り値：
\nfavicons String[] - URLの配列。ページがファビコンの URL を受け取ると発行されます。
\nHTML API にトリガーされてページがフルスクリーンになるときに発生します。
\nHTML API にトリガーされてページがフルスクリーンから抜けるときに発生します。
\n戻り値：
\nlevel Integer - 0 から 3 のログレベル。 順に verbose、info、warning、error に対応します。message String - 実際のコンソールメッセージline Integer - このコンソールメッセージのトリガーとなったソースの行番号sourceId Stringゲストウィンドウがコンソールメッセージをロギングすると発行されます。
\n以下のサンプルコードは、ログレベルやその他のプロパティに関係なく、すべてのログメッセージを埋め込みのコンソールに転送します。
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('console-message', (e) => {\n console.log('ゲストページのメッセージログ:', e.message)\n})\n戻り値：
\nresult ObjectrequestId IntegeractiveMatchOrdinal Integer - アクティブなマッチの位置。matches Integer - マッチの個数。selectionArea Rectangle - 最初に一致した領域の座標。finalUpdate Booleanwebview.findInPage リクエストの結果が有効なときに発行されます。
const webview = document.querySelector('webview')\nwebview.addEventListener('found-in-page', (e) => {\n webview.stopFindInPage('keepSelection')\n})\n\nconst requestId = webview.findInPage('test')\nconsole.log(requestId)\n戻り値：
\nurl StringframeName Stringdisposition String - default、foreground-tab、background-tab、new-window、save-to-disk、other にできる。options BrowserWindowConstructorOptions - 新しい BrowserWindow を作成するのに使われるべきオプション。ゲストページが新しいブラウザウィンドウを開くときに発生します。
\n以下のサンプルコードは、システムのデフォルトブラウザで新しい URL を開きます。
\nconst { shell } = require('electron')\nconst webview = document.querySelector('webview')\n\nwebview.addEventListener('new-window', async (e) => {\n const protocol = (new URL(e.url)).protocol\n if (protocol === 'http:' || protocol === 'https:') {\n await shell.openExternal(e.url)\n }\n})\n戻り値：
\nurl Stringユーザーまたはページがナビゲーションを開始しようとしたときに発生します。 window.location オブジェクトが変更されるか、ユーザがページ内のリンクをクリックしたときに発生することがあります。
このイベントは、 <webview>.loadURL や <webview>.back のような、API によってプログラム上から開始されるナビゲーションのときには発行されません。
アンカーリンクのクリックや window.location.hash の更新のような、ページ内ナビゲーションでも発行されません。 これを意図する場合は did-navigate-in-page を使用して下さい。
event.preventDefault() を呼んでも効果は ありません。
戻り値：
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId Integerフレーム (メインを含む) がナビゲーションを始めているときに発生します。 ページ内ナビゲーションの場合、isInPlace が true になります。
戻り値：
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId Integerナビゲーション後にサーバーサイドリダイレクトが発生すると発行されます。 302 リダイレクトなどがその例です。
\n戻り値：
\nurl Stringナビゲーションが完了したときに発行されます。
\nこのイベントは、アンカーリンクのクリックや window.location.hash の更新のような、ページ内ナビゲーションでは発行されません。 これを意図する場合は did-navigate-in-page を使用して下さい。
戻り値：
\nurl StringhttpResponseCode Integer - HTTP ナビゲーションが無い場合は-1httpStatusText String - HTTP ナビゲーションが無い場合は空。isMainFrame BooleanframeProcessId IntegerframeRoutingId Integerフレームのナビゲーションが完了したときに発生します。
\nこのイベントは、アンカーリンクのクリックや window.location.hash の更新のような、ページ内ナビゲーションでは発行されません。 これを意図する場合は did-navigate-in-page を使用して下さい。
戻り値：
\nisMainFrame Booleanurl Stringページ内ナビゲーションが発生したときに発行されます。
\nページ内ナビゲーションが行われるとき、ページのURLは変更されますがページ外でのナビゲーションは発生しません。 これが発生する例は、アンカーリンクがクリックされたときや、DOM の hashchange イベントがトリガーされたときです。
ゲストのページ自身が閉じようとしたときに発生します。
\n以下のサンプルコードは、ゲストが自身を閉じるときに webview を about:blank にナビゲートします。
const webview = document.querySelector('webview')\nwebview.addEventListener('close', () => {\n webview.src = 'about:blank'\n})\n戻り値：
\nframeId [number, number] - [processId, frameId] のペア。channel Stringargs any[]ゲストページが埋め込みページに非同期メッセージを送信したときに発生します。
\nsendToHost メソッドと ipc-message イベントを使用すると、ゲストページと埋め込みページの間で通信できます。
// 埋め込みページ内\nconst webview = document.querySelector('webview')\nwebview.addEventListener('ipc-message', (event) => {\n console.log(event.channel)\n // \"pong\" が出力される\n})\nwebview.send('ping')\n// ゲストページ内\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('ping', () => {\n ipcRenderer.sendToHost('pong')\n})\nレンダラープロセスがクラッシュしたときに発生します。
\n戻り値：
\nname Stringversion Stringプラグインプロセスがクラッシュしたときに発行されます。
\nwebContents が破棄されたときに発生します。
\nメディアの再生を開始するときに発行されます。
\nメディアが一時停止、または再生が終了したときに発行されます。
\n戻り値：
\nthemeColor Stringページのテーマカラーが変わったときに発生します。 これは通常、メタタグを発見すると起こります。
\n<meta name='theme-color' content='#ff0000'>\n戻り値：
\nurl Stringマウスをリンクにマウスオーバーしたり、キーボードでリンクにフォーカスしたときに発行されます。
\n開発者向けツールが開かれたときに発行されます。
\n開発者向けツールが閉じられたときに発行されます。
\n開発者向けツールがフォーカスされた / 開かれたときに発行されます。
", "title": "レンダラー内での信頼されたもしくは信頼されていないコンテンツからのウインドウ作成を制御する方法がいくつかあります。 ウインドウはレンダラーから以下の 2 つの方法で作成できます。
\ntarget=_blank が付加された、リンクのクリックやフォームの送信window.open() 呼び出し同一オリジンコンテンツの場合、新しいウインドウは同じプロセス内で作成され、親が子ウィンドウに直接アクセスできるようになります。 これは、アプリのサブウインドウが環境設定パネルなどとして機能する場合に非常に便利です。親はサブウインドウに対して、あたかも親が持つ div のように直接レンダリングできます。 これはブラウザと同じ動作です。
nativeWindowOpen を false に設定すると、window.open は代わりに BrowserWindow の軽いラッパーである BrowserWindowProxy を作成します。
Electron は、このネイティブの Chrome Window と BrowserWindow をペアリングします。 レンダラーで作成されたウインドウに対して webContents.setWindowOpenHandler() を使用することで、メインプロセスでの BrowserWindow 作成と同じすべてのカスタマイズを活用できます。
BrowserWindow コンストラクタのオプションは、window.open() の features 文字列からパースされたオプション、親ウインドウから継承されたセキュリティ関連の webPreferences、webContents.setWindowOpenHandler で与えられたオプションの順に設定されます。 注意として、webContents.setWindowOpenHandler はメインプロセスで呼び出されるため、最終的な決定権と完全なアクセス権限があります。
window.open(url[, frameName][, features])url StringframeName String (任意)features String (任意)戻り値 BrowserWindowProxy | Window
features は、ブラウザの標準フォーマットに従ったカンマ区切りのキーバリューリストです。 Electron は便宜上、このリストから BrowserWindowConstructorOptions をできるだけ解析します。 完全な制御とより良い人間工学を実現するため、webContents.setWindowOpenHandler で BrowserWindow の作成をカスタマイズするようにご検討ください。
WebPreferences のうちのいくつかは、次の features 文字列から直接フラットに設定できます。zoomFactor、nodeIntegration、preload、javascript、contextIsolation、webviewTag が設定できます。
以下がその例です。
\nwindow.open('https://github.com', '_blank', 'top=500,left=200,frame=false,nodeIntegration=no')\n注釈:
\nwindow でも常に無効になります。window で常に有効になります。window でも常に無効になります。features で指定された非標準機能 (Chromium や Electron によって処理されない) は、options 引数内の登録された webContents の did-create-window イベントハンドラに渡されます。frameName は、ネイティブのドキュメント にある windowName の仕様に従います。ウインドウの作成をカスタマイズまたはキャンセルするにあたって、メインプロセスから webContents.setWindowOpenHandler() でオーバーライドハンドラーを任意設定できます。 { action: 'deny' } を返すと、ウィンドウはキャンセルされます。 { action: 'allow', overrideBrowserWindowOptions: { ... } } を返すと、ウインドウを開くことと、ウィンドウ作成時に使用する BrowserWindowConstructorOptions の設定を許可します。 これは、feature 文字列でオプションを渡すよりも強力であることに注意してください。レンダラーは、セキュリティ設定を決定する権限がメインプロセスよりも制限されているからです。
Window のサンプル// main.js\nconst mainWindow = new BrowserWindow()\n\n// この例では、URL が `about:blank` であるウインドウのみが作成されます。\n// ほかのすべての URL はブロックされます。\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url === 'about:blank') {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n frame: false,\n fullscreenable: false,\n backgroundColor: 'black',\n webPreferences: {\n preload: 'my-child-window-preload-script.js'\n }\n }\n }\n }\n return { action: 'deny' }\n})\n// レンダラープロセス (mainWindow)\nconst childWindow = window.open('', 'modal')\nchildWindow.document.write('<h1>Hello</h1>')\nBrowserWindowProxy のサンプル\n// main.js\nconst mainWindow = new BrowserWindow({\n webPreferences: { nativeWindowOpen: false }\n})\n\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url.startsWith('https://github.com/')) {\n return { action: 'allow' }\n }\n return { action: 'deny' }\n})\n\nmainWindow.webContents.on('did-create-window', (childWindow) => {\n // 例えば...\n childWindow.webContents.on('will-navigate', (e) => {\n e.preventDefault()\n })\n})\n// renderer.js\nconst windowProxy = window.open('https://github.com/', null, 'minimizable=false')\nwindowProxy.postMessage('hi', '*')\nアプリを Electron 6.0.8 以降で実行している場合、Arm 版 Windows 10 向けにビルドできます。 これによりパフォーマンスが大幅に向上しますが、アプリで使用されているネイティブモジュールを再コンパイルする必要があります。 また、ビルドおよびパッケージ化スクリプトの小さな修正が必要になる場合があります。
\nアプリがネイティブモジュールを使用していない場合は、アプリの Arm 版は簡単に作成できます。
\nnode_modules ディレクトリが空であることを確認してください。set npm_config_arch = arm64 を実行してから、同じように npm install / yarn install を実行します。Windows 固有コードの多くには if... else ロジックが含まれています。これは、x64 アーキテクチャと x86 アーキテクチャのどちらかを選択するものです。
\nif (process.arch === 'x64') {\n // 64 ビット固有の処理をする...\n} else {\n // 32 ビット固有の処理をする...\n}\narm64 をターゲットにしたい場合、このようなロジックは通常間違ったアーキテクチャを選択するため、アプリケーションを慎重に確認したうえで、このような条件のスクリプトを作成してください。 カスタムビルドおよびパッケージスクリプトでは、現在の process.arch に依存するのではなく、環境内の npm_config_arch の値を常に確認する必要があります。
ネイティブモジュールを使用する場合は、MSVC コンパイラの v142 (Visual Studio 2017 で提供) に対してコンパイルしていることを確認する必要があります。 また、ネイティブモジュールによって提供または参照されているビルド済みの .dll または .lib ファイルが Arm 版 Windows で使用できることも確認する必要があります。
アプリをテストするには、Windows 10 (バージョン 1903 以降) を実行している Arm 版 Windows デバイスを使用します。 必ずターゲットデバイスにアプリケーションをコピーしてください。Chromium のサンドボックスは、ネットワーク位置上からアプリケーションアセットを読み込むと正しく機能しません。
\nNode.js v12.9.0 以降を推奨します。 新しいバージョンの Node へのアップデートが望ましくない場合は、代わりに npm の node-gyp のコピーを手動でバージョン 5.0.2 以降に更新 できます。これには、Arm 向けのネイティブモジュールをコンパイルするために必要な変更が含まれています。
\nネイティブモジュールのクロスコンパイルには、Visual Studio 2017 (いずれかのエディション) が必要です。 Visual Studio Community 2017 は、Microsoft の Visual Studio Dev Essentials プログラム からダウンロードできます。 インストール後、コマンドプロンプト から次のコマンドを実行して、Arm 固有のコンポーネントを追加できます。
\nvs_installer.exe ^\n--add Microsoft.VisualStudio.Workload.NativeDesktop ^\n--add Microsoft.VisualStudio.Component.VC.ATLMFC ^\n--add Microsoft.VisualStudio.Component.VC.Tools.ARM64 ^\n--add Microsoft.VisualStudio.Component.VC.MFC.ARM64 ^\n--includeRecommended\n環境で npm_config_arch = arm64 を設定すると、正しい arm64 の .obj ファイルが作成されますが、VS 2017 標準の 開発者向けコマンドプロンプト for VS 2017 は x64 リンカーを使用します 。 これを修正するには以下のようにします。
vcvarsamd64_x86.bat ではなく、最後のvcvarsamd64_arm64.bat を読み取るように変更します。正常に完了すると、そのコマンドプロンプトは起動時に以下のようなものを出力するはずです。
\n**********************************************************************\n** Visual Studio 2017 Developer Command Prompt v15.9.15\n** Copyright (c) 2017 Microsoft Corporation\n**********************************************************************\n[vcvarsall.bat] Environment initialized for: 'x64_arm64'\nArm 版 Windows デバイスでアプリケーションを直接開発したい場合は、デバイスの x86 エミュレーションでクロスコンパイルが発生するように、Target を vcvarsx86_arm64.bat に置き換えます。
node.lib に対してリンクするデフォルトでは、node-gyp は Electron の node ヘッダーをアンパックし、node.lib の x86 および x64 バージョンを %APPDATA%\\..\\Local\\node-gyp\\Cache にダウンロードします。ただし、arm64 バージョンはダウンロードされません (この修正は開発中です)。 これを修正するには以下のようにします。
node.lib をダウンロードします%APPDATA%\\..\\Local\\node-gyp\\Cache\\6.0.9\\arm64\\node.lib に移動します6.0.9 は使用しているバージョンに置き換えてください。
上記のすべてを完了した後、クロスコンパイルコマンドプロンプトを開き、set npm_config_arch = arm64 を実行します。 そして npm install を使用して、通常どおりプロジェクトをビルドします。 x86 モジュールのクロスコンパイルと同様に、事前に別のアーキテクチャ用にコンパイルされたネイティブモジュールを強制的に再コンパイルするには、node_modules を削除する必要があります。
ネイティブモジュールのデバッグは、Visual Studio 2017 (開発マシン上で実行) および対応する Visual Studio Remote Debugger をターゲットのデバイス上で実行することで実行できます。 デバッグするには以下のようにします。
\n.exe を起動します (これに -inspect-brk を渡すと、ネイティブモジュールがロードされる前に一時停止します)。.pdb シンボルが含まれたフォルダーを追加します。このドキュメントで問題に遭遇した場合、または x86 向けにコンパイルされたアプリが動作しても arm64 向けにコンパイルされたアプリが動作しない場合は、タイトルに \"Windows on Arm\" と入れて Issue を提出 してください。
", "title": "Arm 版 Windows", "description": "" }, "/docs/tutorial/windows-store-guide": { "locale": "ja-JP", "slug": "windows-store-guide", "href": "/docs/tutorial/windows-store-guide", "crowdinFileId": "256273", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-store-guide.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Windows 10では、古き良き Win32 実行形式は新たな兄弟をむかえました: Universal Windows Platform。 新しい .appx フォーマットは、Cortana や Push通知のような新しい強力な API を利用できるだけでなく、Windows ストアを通じて、シンプルなインストールとアップデートが可能になります。
Microsoft は Electron アプリを .appx パッケージとしてコンパイル可能なツールを開発したため、開発者は新しいアプリケーション モデルの一部を使用できます。 このガイドではその使用方法 - Electron AppX パッケージの機能と制限について解説します。
Windows 10 \"Anniversary Update\" では、仮想ファイルシステムとレジストリと共に起動することで win32 .exe バイナリを実行できます。 どちらも、Windows Container内部でアプリとインストーラーを実行することで、インストール中のオペレーティングシステムに対する変更を正確に検出できます。 仮想ファイルシステムと仮想レジストリを実行ファイルのペアにすることで、Windowsがワンクリックでインストールとアンインストールが可能になる。
さらにexeは内部的にはappxモデルとして起動される - つまりUniversal Windows Platformで利用可能なAPIの多くを使用できる。 より多くの機能として、Electronアプリは exeと共に、バックグラウンドでタスクを実行する、プッシュ通知を受け取る、他のUWPアプリケーションと通信するなど、表示しないUWPバックグラウンドタスクを組合せることができます。
既存のElectronアプリをコンパイルするには、以下の要件を満たしていることを確認してください:
\nnode -vを実行してチェックできます)次に、electron-windows-store CLIに移動してインストールする:
npm install -g electron-windows-store\nelectron-packager (または類似ツール) を用いてパッケージします。 アプリケーションサイズが大きくなるので、実際には必要ないモジュールをnode_modulesから確実に削除します。
出力はおおよそ以下のようになります:
\n├── Ghost.exe\n├── LICENSE\n├── content_resources_200_percent.pak\n├── content_shell.pak\n├── d3dcompiler_47.dll\n├── ffmpeg.dll\n├── icudtl.dat\n├── libEGL.dll\n├── libGLESv2.dll\n├── locales\n│ ├── am.pak\n│ ├── ar.pak\n│ ├── [...]\n├── node.dll\n├── resources\n│ └── app.asar\n├── v8_context_snapshot.bin\n├── squirrel.exe\n└── ui_resources_200_percent.pak\n昇格したPowerShell(管理者として実行) で、入力と出力ディレクトリ、アプリ名とバージョン、node_modulesをフラット化することの確認など、必要なパラメーターと共にelectron-windows-storeを実行する。
electron-windows-store `\n --input-directory C:\\myelectronapp `\n --output-directory C:\\output\\myelectronapp `\n --package-version 1.0.0.0 `\n --package-name myelectronapp\n一度ツールが実行されると: Electronアプリを入力として受け入れて、node_modulesをフラット化します。 次にアプリケーションをapp.zipとしてアーカイブします。 インストーラーとWindows Containerを使って、ツールは、出力フォルダーにWindows Application Manifest (AppXManifest.xml) 、仮想ファイルシステム、仮想レジストリーを含む「拡張された」AppXパッケージを作成します。
拡張されたAppXファイルが作成されると、ツールはディスク上のそれらのファイルから、単一ファイルのAppXパッケージを作成するためにWindows App Packager(MakeAppx.exe) を使用します。 最後にツールはAppXパッケージを署名するためにコンピューター上に信頼された証明書を作成します。 署名されたAppXパッケージを使うと、CLIはマシンにパッケージを自動的にインストールすることもできる。
あなたのパッケージを実行するために、ユーザーは\"Anniversary Update\"と呼ばれるWindows 10が必要です。Windowsを更新する方法の詳細はここをご参照ください。
\n従来のUWPアプリと対照的に、パッケージ化されたアプリは、現在、ここで申請できる手動検証プロセスが必要です。 全てのユーザーはパッケージをダブルクリックすることでインストールできるため、もしより簡単なインストール方法を探しているのであれば、ストアへのサブミットは必要ではありません。 (通常はエンタープライズなど) 管理された環境 では、Add-AppxPackage PowerShell Cmdletを使用して自動的にインストールできる。
もう一つの重要な制限は、コンパイルされたAppXパッケージはまだWin32実行形式であり、Xbox、HoloLens、Phoneでは実行できないことです。
\nプッシュ通知、Cortana統合、ライブタイルなど、Windows 10機能を完全に使った非表示UWPバックグラウンドタスクとElectronアプリを組み合わせることができます。
\nElectronアプリがバックグラウンドタスクを使って、トースト通知の送信とライブタイルを利用する方法は、マイクロソフトが提供するサンプルをチェックしてください。
\nほとんどのElectronアプリは、AppX パッケージを生成するためにelectron-windows-store CLIで動作するテンプレートを使っている。 しかし、もしもカスタムインストーラーを使った場合や、生成されたパッケージで問題が発生した場合には、Windows Containerでコンパイルを使ったパッケージ作成を試すことができ、このモデルでは、アプリケーションがオペレーティングシステムに対して具体的にどんな変更をしているのかを検出するため、CLIは空のWindows Containerにアプリケーションをインストールして実行します。
初めてCLIを実行する前に「Windows Desktop App Converter」をセットアップする必要があります。 これには数分かかりますが、一度だけなので心配する必要はありません。 ここからDesktop App Conveterをダウンロードします。 あなたは2つのファイルを受け取ります: DesktopAppConverter.zipとBaseImage-14316.wim
DesktopAppConverter.zipを展開します。 (管理者として実行) で昇格したPowerShellでSet-ExecutionPolicy bypassを呼び出して、システム実行ポリシーで全ての実行を可能にします。BaseImage-14316.wimとしてダウンロードされた) Windowsベースイメージの場所を渡して、.\\DesktopAppConverter.ps1 -Setup -BaseImage .\\BaseImage-14316.wimを呼び出します。インストールが成功すると、Electronアプリのコンパイルに進むことができます。
", "title": "Windowsストア ガイド", "description": "" }, "/docs/tutorial/windows-taskbar": { "locale": "ja-JP", "slug": "windows-taskbar", "href": "/docs/tutorial/windows-taskbar", "crowdinFileId": "256275", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-taskbar.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron には Windows のタスクバー中のアプリアイコンを設定するための API があります。 このAPIは、ジャンプリスト の作成、カスタムサムネイルやツールバー などの Windows 専用機能と、アイコンオーバーレイ、いわゆる \"枠点滅\" 効果、最近開いたドキュメント、アプリケーションの進捗状況 などのクロスプラットフォーム機能があります。
Windows では、ユーザがタスクバーのアプリのアイコンを右クリックしたときに表示されるカスタムコンテキストメニューを定義できます。 このコンテキストメニューは ジャンプ リスト と呼ばれます。 ジャンプリストの タスク カテゴリのカスタムアクションを指定します。以下は MSDN からの引用です。
\n\nアプリケーションは、プログラムの機能と、ユーザがそれらを使用することが期待されるべきことの両方に基づいてタスクを定義します。 タスクを実行するためにアプリケーションを実行する必要がないという点で、タスクはコンテキストフリーである必要があります。 それらは、電子メールのメッセージを作成したり、メールプログラムでカレンダーを開いたり、ワープロで新しい文書を作成したり、特定のモードでアプリケーションを起動したりするなど、通常のユーザーがアプリケーションで実行する統計的に最も一般的なアクション、またはそのサブコマンドの1つでもあります。 アプリケーションは、標準ユーザが必要としない高度な機能や、登録などの1回限りの操作でメニューを乱雑にするべきではありません。 アップグレードや特別オファーなどのプロモーションの道具にタスクを使用しないでください。
\nタスクリストは静的にすることを強く推奨します。 これはアプリケーションの状態や状態に関係なく、同じままにするべきです。 リストを動的に変更することは可能ですが、宛先リストのその部分が変更されることを期待していないユーザを混乱させる可能性があることを考慮する必要があります。
\n
\n\n注意: 上のスクリーンショットは、Internet Explorer の一般的なタスクの例です。
\n
実際のメニューである macOS のドックメニューとは異なり、Windows のユーザータスクはアプリケーションショートカットのように機能します。 例えば、ユーザーがタスクをクリックするとプログラムを指定の引数で実行します。
\nアプリケーションにユーザタスクを設定するには、以下のように app.setUserTasks API を使用します。
\nクイックスタートガイド の作業用アプリケーションから始めることにして、 main.js ファイルを以下の行の通りに更新します。
const { app } = require('electron')\n\napp.setUserTasks([\n {\n program: process.execPath,\n arguments: '--new-window',\n iconPath: process.execPath,\n iconIndex: 0,\n title: 'New Window',\n description: 'Create a new window'\n }\n])\nタスクリストを消去するには、main.js ファイルで app.setUserTasks に空の配列を渡して呼び出す必要があります。
const { app } = require('electron')\n\napp.setUserTasks([])\n\n\n注意: ユーザータスクはアプリケーションを閉じた後も表示されるので、タスクに指定したアイコンとプログラムのパスは、アプリケーションがアンインストールされるまで存在するべきです。
\n
Windows では、アプリケーションウィンドウのタスクバーレイアウトに、指定されたボタンを含むサムネイルツールバーを追加できます。 ウィンドウを復元したりアクティブにしたりすることなく、特定のウィンドウのコマンドにアクセスする方法をユーザーに提供します。
\n以下は MSDN からの引用です。
\n\n\nこのツールバーは、おなじみの標準ツールバー共通コントロールです。 最大で7つのボタンを持てます。 各ボタンのID、画像、ツールチップ、および状態は構造体で定義され、その構造体はタスクバーに渡されます。 アプリケーションは、現在の状態に応じてサムネイルツールバーからボタンを表示、有効化、無効化、または非表示にさせることができます。
\nたとえば、Windows Media Player では、再生、一時停止、ミュート、停止などの標準のメディア送りコントロールを提供できます。
\n
\n\n注意: 上のスクリーンショットは、Windows メディアプレイヤーのサムネイルツールバーの例です。
\n
アプリケーションにサムネイルツールバーを設定するには、BrowserWindow.setThumbarButtons を使用する必要があります。
\nクイックスタートガイド の作業用アプリケーションから始めることにして、 main.js ファイルを以下の行の通りに更新します。
const { BrowserWindow } = require('electron')\nconst path = require('path')\n\nconst win = new BrowserWindow()\n\nwin.setThumbarButtons([\n {\n tooltip: 'button1',\n icon: path.join(__dirname, 'button1.png'),\n click () { console.log('button1 clicked') }\n }, {\n tooltip: 'button2',\n icon: path.join(__dirname, 'button2.png'),\n flags: ['enabled', 'dismissonclick'],\n click () { console.log('button2 clicked.') }\n }\n])\nサムネイルツールバーをきれいにするには、main.js で以下のように BrowserWindow.setThumbarButtons を空の配列で呼び出してください。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.setThumbarButtons([])\nWindows では、タスクバーボタンで小さなオーバーレイを使用してアプリケーションのステータスを表示できます。
\n以下は MSDN からの引用です。
\n\n\nアイコンオーバーレイは状況のコンテキスト通知として機能し、その情報をユーザーに伝達するための別の通知領域ステータスアイコンの必要性を否定することを目的としています。 たとえば、現在通知領域に表示されている Microsoft Outlook の新着メールステータスは、タスクバーボタンの上にオーバーレイ表示されるようになりました。 繰り返しますが、開発サイクルの中でどの方法があなたのアプリケーションに最適であるかを決める必要があります。 オーバーレイアイコンは、ネットワークステータス、メッセンジャーステータス、新着メールなど、重要な長期にわたるステータスや通知を提供することを目的としています。 ユーザには、絶えず変化するオーバーレイやアニメーションを表示してはいけません。
\n
\n\n注意: 上のスクリーンショットは、タスクバーボタンのオーバーレイの例です。
\n
ウインドウのオーバーレイアイコンを設定するには、BrowserWindow.setOverlayIcon API を使用する必要があります。
\nクイックスタートガイド の作業用アプリケーションから始めることにして、 main.js ファイルを以下の行の通りに更新します。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.setOverlayIcon('path/to/overlay.png', 'Description for overlay')\nWindows では、タスクバーボタンをハイライトしてユーザの注意を引くことができます。 これは macOS で Dock アイコンがバウンスするのに似ています。
\n以下は MSDN からの引用です。
\n\n\n通常、ウィンドウは注意が必要でも現在キーボードフォーカスがないことをユーザーに知らせるために点滅します。
\n
BrowserWindow のタスクバーボタンを点滅させるには、BrowserWindow.flashFrame API を使用する必要があります。
\nクイックスタートガイド の作業用アプリケーションから始めることにして、 main.js ファイルを以下の行の通りに更新します。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.once('focus', () => win.flashFrame(false))\nwin.flashFrame(true)\n\n", "title": "タスクバーのカスタマイズ (Windows)", "description": "アプリケーションは、プログラムの機能と、ユーザがそれらを使用することが期待されるべきことの両方に基づいてタスクを定義します。 タスクを実行するためにアプリケーションを実行する必要がないという点で、タスクはコンテキストフリーである必要があります。 それらは、電子メールのメッセージを作成したり、メールプログラムでカレンダーを開いたり、ワープロで新しい文書を作成したり、特定のモードでアプリケーションを起動したりするなど、通常のユーザーがアプリケーションで実行する統計的に最も一般的なアクション、またはそのサブコマンドの1つでもあります。 アプリケーションは、標準ユーザが必要としない高度な機能や、登録などの1回限りの操作でメニューを乱雑にするべきではありません。 アップグレードや特別オファーなどのプロモーションの道具にタスクを使用しないでください。\nタスクリストは静的にすることを強く推奨します。 これはアプリケーションの状態や状態に関係なく、同じままにするべきです。 リストを動的に変更することは可能ですが、宛先リストのその部分が変更されることを期待していないユーザを混乱させる可能性があることを考慮する必要があります。" } }, "es-ES": { "/docs/api/accelerator": { "locale": "es-ES", "slug": "accelerator", "href": "/docs/api/accelerator", "crowdinFileId": "256277", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/accelerator.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "注意:
\nwin.flashFrame(false)を呼び出して点滅を切ることを、忘れないようにしてください。 上記の例ではウインドウがフォーカスされたときに呼び出されますが、タイムアウトなどのイベントを使用して無効にすることもできます。
\n\nDefinir atajos del teclado.
\n
Los Atajos son strings que pueden contener múltiples modificadores y un único código clave, en combinación con el carácter + se utilizan para definir métodos abreviados de teclado a través de su aplicación.
Ejemplos:
\nCommandOControl+ACommandOControl+Shift+ZLos atajos son registrados con el módulo e globalShortcut usando el método register, ejemplo.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+Y' shortcut listener.\n globalShortcut.register('CommandOrControl+Y', () => {\n // Hacer algo cuando se presiona tanto Tecla Command o Control + Y.\n })\n})\nEn Linux y Windows, la clave Command no tiene ningún efecto, así que se utilizar CommandOrControl que representa Command para macOS y Control para Linux y Windows para definir algunos Aceleradores.
Usa Alt en lugar de Opción. La clave Opción sólo existe en macOS, mientras que la clave Alt está disponible en todas las plataformas.
La clave Super (o Meta) esta asignada a la tecla Windows en Windows y linux, Cmd en macOS.
Command (o Cmd resumido)Control (o Ctrl resumido)ComandoOControl (o CmdOrCtrl resumido)AltOpciónAlt derechaShiftSuperMeta0 a 9A a ZF1 a F24~, !, @, #, $, etc.MásEspacioTabBloq MayúsNumlockBloqueo de desplazamientoRetrocesoSuprimirInsertarReturn (o Enter como alias)Arriba, Abajo, Izquierda y DerechaHome y EndPageUp y PageDownEscape (o Esc resumido)VolumeUp, VolumeDown y VolumeMuteMediaNextTrack, MediaPreviousTrack, MediaStop y MediaPlayPausePrintScreennum0 - num9numdec - clave decimalnumadd - teclado numérico tecla +numsub - teclado numérico tecla -nummult - teclado numérico tecla *numdiv - teclado numérico tecla ÷Hacer que las aplicaciones sean accesibless es importante y estemos encantados de proporcionar funcionalidad en Devtron y Spectron que le brinda a los programadores la oportunidad de hacer que sus aplicaciones sean mejoren para todos.
\nLos problemas de accesibilidad en las aplicaciones Electron son similares a los de los sitios web debido a que ambos son básicamente HTML. Sin embargo, con las aplicaciones de Electron, no puedes usar los recursos online para las auditorías de accesibilidad, ya que la aplicación no posee una URL para apuntar al auditor.
\nThese features bring those auditing tools to your Electron app. You can choose to add audits to your tests with Spectron or use them within DevTools with Devtron. Sigue leyendo para un resumen de las herramientas.
\nIn the testing framework Spectron, you can now audit each window and <webview> tag in your application. Por ejemplo:
app.client.auditAccessibility().then(function (audit) {\n if (audit.failed) {\n console.error(audit.message)\n }\n})\nPuede leer más acerca de esta herramienta en la documentación de Spectron.
\nIn Devtron, there is an accessibility tab which will allow you to audit a page in your app, sort and filter the results.
\n
Ambas herramientas están utilizando la biblioteca Herramientas de desarrollo de accesibilidad creada por Google para Chrome. Usted puede aprender más acerca de las reglas de auditoría de accesibilidad que esta biblioteca usa en la wiki del repositorio.
\nSi conoces de otras herramientas de gran accesibilidad para Electron, añádelas al documentado de accesibilidad con un pull request.
\nElectron applications will automatically enable accessibility features in the presence of assistive technology (e.g. JAWS on Windows or VoiceOver on macOS). Consulte la documentación de accesibilidad de Chrome para obtener más detalles.
\nYou can also manually toggle these features either within your Electron application or by setting flags in third-party native software.
\nBy using the app.setAccessibilitySupportEnabled(enabled) API, you can manually expose Chrome's accessibility tree to users in the application preferences. Note that the user's system assistive utilities have priority over this setting and will override it.
On macOS, third-party assistive technology can toggle accessibility features inside Electron applications by setting the AXManualAccessibility attribute programmatically:
CFStringRef kAXManualAccessibility = CFSTR(\"AXManualAccessibility\");\n\n+ (void)enableAccessibility:(BOOL)enable inElectronApplication:(NSRunningApplication *)app\n{\n AXUIElementRef appRef = AXUIElementCreateApplication(app.processIdentifier);\n if (appRef == nil)\n return;\n\n CFBooleanRef value = enable ? kCFBooleanTrue : kCFBooleanFalse;\n AXUIElementSetAttributeValue(appRef, kAXManualAccessibility, value);\n CFRelease(appRef);\n}\n\n\nControla el ciclo de vida de los eventos de su aplicación.
\n
Proceso: principal</0>
\nLos siguientes ejemplos muestran como salir de la aplicación cuando la última ventana está cerrada:
\nconst { app } = require('electron')\napp.on('window-all-closed', () => {\n app.quit()\n})\nEl objeto app emite los siguientes eventos:
Emitido cuando la aplicación ha terminado su iniciación básica. En windows y Linux el evento will-finish-launching es el mismo que el evento ready; en macOS este evento representa la notificación applicationWillFinishLaunching de NSApplication. Normalmente configurará aquí los receptores para los eventos open-file y open-url, e iniciará el informador de errores y el actualizador automático.
En la mayoría de los casos usted debe hacer todo desde el controlador del evento ready.
Devuelve:
\neventlaunchInfo Record<string, any> | NotificationResponse macOSSe emite una vez, cuando Electron ha terminado de iniciarse. En macOS launchInfo almacena el userInfo de NSUserNotification o la información de UNNotificationResponse que fue usado para abrir la aplicación, si este fue lanzado desde el Centro de Notificaciones. Además puede llamar a app.isReady() para comprobar si el evento ha sido lanzado y app.whenReady() para obtener una Promise que se cumple cuando Electron está inicializado.
Emitido cuando todas las ventanas han sido cerradas.
\nSi no se subscribe a este evento y todas las ventanas están cerradas, el comportamiento por defecto es salir de la aplicación; sin embargo, si se subscribe, usted controla si la aplicación se cierra o no. Si el usuario presionó Cmd + Q, o el desarrollador llamó a app.quit(), Electron primero tratará de cerrar todas las ventanas y entonces emitir el evento will-quit, y en este caso el evento window-all-closed no será emitido.
Devuelve:
\neventEmitido antes de que la aplicación empiece a cerrar sus ventanas. Llamando a event.preventDefault() evitará el comportamiento por defecto, que es terminar la aplicación.
Note: Si el cierre de la aplicación fue iniciada por autoUpdater.quitAndInstall(), luego before-quit es emitido after emitiendo el evento close en todas las ventanas y cerrándolas.
Nota: En Windows, este evento no será emitido si la aplicación se cierra debido a un apagado/reinicio del sistema o el cierre de sesión de un usuario.
\nDevuelve:
\neventEmitido cuando todas las ventanas han sido cerradas y la aplicación se cerrará. Llamando a event.preventDefault() evitará el comportamiento por defecto, que es terminar la aplicación.
Consulte la descripción del evento window-all-closed por las diferencias con los eventos will-quit y window-all-closed.
Nota: En Windows, este evento no será emitido si la aplicación se cierra debido a un apagado/reinicio del sistema o el cierre de sesión de un usuario.
\nDevuelve:
\neventexitCode IntegerEmitido cuando la aplicación se está cerrando.
\nNota: En Windows, este evento no será emitido si la aplicación se cierra debido a un apagado/reinicio del sistema o el cierre de sesión de un usuario.
\nDevuelve:
\neventpath StringEmitido cuando el usuario quiere abrir un archivo con la aplicación. El evento open-file es emitido usualmente cuando la aplicación está ya abierta y el sistema operativo quiere reusar la aplicación para abrir el archivo. open-file también es emitido cuando el archivo es soltado dentro del dock y la aplicación todavía no se está ejecutando. Asegúrese de escuchar sobre el evento open-file muy temprano en el el inicio de su aplicación para manejar este caso (incluso antes de que el evento ready sea emitido).
Usted debe llamar a event.preventDefault() si quiere manejar este evento.
En Windows, tiene que analizar process.argv (en el proceso principal) para encontrar la ruta del archivo.
Devuelve:
\neventurl StringEmitido cuando el usuario quiere abrir una URL con la aplicación. El archivo Info.plist de tu aplicación debe definir el esquema URL dentro de la llave CFBundleURLTypes y configurar NSPrincipalClass a AtomApplication.
Usted debe llamar a event.preventDefault() si quiere manejar este evento.
Devuelve:
\neventhasVisibleWindows BooleanEmitido cuando la aplicación está activada. Varias acciones puede activar este evento, como iniciar la aplicación por primera vez, intentar relanzar la aplicación cuando ya está corriendo, o hacer click en el dock de la aplicación o en el ícono de la barra de tareas.
\nDevuelve:
\neventEmitido cuando la aplicación mac se activa. La diferencia del evento activate es que did-become-active es emitido cada vez que la aplicación se activa, no solo cuando el icono en el Dock es pulsado o la aplicación es re-lanzada.
Devuelve:
\neventtype String - Una cadena identificando la actividad. Se asigna a NSUserActivity.activityType.userInfo unknown - Contiene el estado especifico de la aplicación guardado por la actividad en otro dispositivo.details ObjectwebpageURL String (opcional) - Una cadena que identifica la URL de la página web accedida por la actividad en otro dispositivo, si está disponible.Emitido durante Handoff cuando una actividad de un artefacto diferente quiere ser reanudado. Usted debe llamar event.preventDefault() si quiere manejar este evento.
La actividad de un usuario puede ser continuada solo en una aplicación que tenga la misma identificación de equipo de desarrolladores como la la aplicación fuente de las actividades y que soporte los tipos de actividad. Los tipos de actividades soportadas están en el Info.plist de la aplicación bajo la llave NSUserActivityTypes.
Devuelve:
\neventtype String - Una cadena identificando la actividad. Se asigna a NSUserActivity.activityType.Emitido durante Handoff cuando una actividad de un artefacto diferente quiere ser reanudado. Usted debe llamar event.preventDefault() si quiere manejar este evento.
Devuelve:
\neventtype String - Una cadena identificando la actividad. Se asigna a NSUserActivity.activityType.error String - Una cadena en el idioma local con la descripción del error.Emitido durante Handoff cuando una actividad desde un artefacto diferente falla al ser reanudada.
\nDevuelve:
\neventtype String - Una cadena identificando la actividad. Se asigna a NSUserActivity.activityType.userInfo unknown - Contiene el estado especifico de la aplicación guardado por la actividad.Emitido durante Handoff después de que una actividad de este artefacto haya sido reanudado con éxito en otro.
\nDevuelve:
\neventtype String - Una cadena identificando la actividad. Se asigna a NSUserActivity.activityType.userInfo unknown - Contiene el estado especifico de la aplicación guardado por la actividad.Emitido cuando Handoff va a ser reanudado en otro artefacto. Si necesita actualizar el estado que se transferirá, debe llamar a event.preventDefault () inmediatamente, crear un nuevo diccionario userInfo y llamar a app.updateCurrentActivity() de manera oportuna. De otra manera, la operación fallará en continue-activity-error será llamada.
Devuelve:
\neventEmitido cuando el usuario hace clic en el botón de nueva pestaña nativa de macOS. El botón de nueva pestaña solo es visible si el BrowserWindow actual tiene un tabbingIdentifier
Devuelve:
\neventwindow BrowserWindowEmitido cuando el browserWindow está borroso.
\nDevuelve:
\neventwindow BrowserWindowEmitido cuando se enfoca un browserWindow.
\nDevuelve:
\neventwindow BrowserWindowEmitido cuando se crea un browserWindow.
\nDevuelve:
\neventwebContents WebContentsEmitido cuando un nuevo contenidoweb es creado.
\nDevuelve:
\neventwebContents WebContentsurl Stringerror cadena - el error del códigocertificate certificatecallback FunciónisTrusted Boleano - Si considera que el certificado como de confianzaEsElFramePrincipal BooleanEmitido cuando falla la verificación de certificate por url, al confiar en el certificado usted debe prevenir el comportamiento con event.preventDefault() y llamar callback(true).
const { app } = require('electron')\n\napp.on('certificate-error', (event, webContents, url, error, certificate, callback) => {\n if (url === 'https://github.com') {\n // Verification logic.\n event.preventDefault()\n callback(true)\n } else {\n callback(false)\n }\n})\nDevuelve:
\neventwebContents WebContentsurl URLcertificateListCertificate[]callback FuncióncertificateCertificate(opcional)Emitido cuando el certificado de un cliente es requerido.
\nLa url corresponde a la entrada de navegación requerida al certificado del cliente y callback puede ser llamado con una entrada filtrada de la lista. Usando event.preventDefault() previene que la aplicación use el primer certificado almacenado.
const { app } = require('electron')\n\napp.on('select-client-certificate', (event, webContents, url, list, callback) => {\n event.preventDefault()\n callback(list[0])\n})\nDevuelve:
\neventwebContents WebContentsauthenticationResponseDetails Objecturl URLauthInfo ObjectisProxy Booleanscheme Stringanfitrión Cadenapuerto Íntegrorealm Cadenacallback Funciónusername String (opcional)password String (opcional)Emitido cuando webContents quiere hacer una autenticación básica.
El comportamiento por defecto es cancelar todas las autenticaciones. Para sobrescribir esto de debe evitar el comportamiento por defecto con event.preventDefault() y llamar a callback(username, password) con las credenciales.
const { app } = require('electron')\n\napp.on('login', (event, webContents, details, authInfo, callback) => {\n event.preventDefault()\n callback('username', 'secret')\n})\nSi callback es llamado sin un nombre de usuario o contraseña, la solicitud de autenticación sera cancelada y el error de autenticación será retornado a la página.
Emitido cada vez que hay una actualización de información de la GPU.
\nDevuelve:
\neventkilled BooleanoEmitido cuando el proceso de la GPU se crashea o es terminado.
\nObsoleto: Este evento es reemplazado por el evento child-process-gone el cual contiene más información acerca de porque desapareció el proceso secundario. No siempre se debe a que haya dejado de funcionar. El booleano killed puede ser reemplazado al comprobar que reason === 'killed' cuando se cambie a ese evento.
Devuelve:
\neventwebContents WebContentskilled BooleanoEmitido cuando el proceso render de webContents se bloquea o es matado.
Obsoleto: Este evento es reemplazado por el evento render-process-gone el cual contiene más información acerca de porque desapareció el renderer process. No siempre se debe a que haya dejado de funcionar. El booleano killed puede ser reemplazado al comprobar que reason === 'killed' cuando se cambie a ese evento.
Devuelve:
\neventwebContents WebContentsdetails Objectreason String - La razón por la que finalizo el proceso. Posibles valores:clean-exit -El proceso ha finalizado con un exit code de ceroabnormal-exit - El proceso a finalizado con un exit code distinto de cerokilled - El proceso a enviado un SIGTERM o se a finalizado externamentecrashed - El proceso crasheooom - El proceso se quedo sin memorialaunch-failed - El proceso nunca se ha ejecutado correctamenteintegrity-failure - las verificaciones de integridad de código de Windows fallaronexitCode Integer - El código de salida del proceso, a menos que reason sea launch-failed, en cuyo caso exitCode será un código de error de ejecución especifico de la plataforma.Emitido cuando el renderer process desaparece inesperadamente. Esto se debe comúnmente porque se crasheo o cerro.
\nDevuelve:
\neventdetails Objecttype String - Tipo de proceso. Uno de los siguiente valores:UtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownreason String - La razón por la que se cerro el proceso hijo. Posibles valores:clean-exit -El proceso ha finalizado con un exit code de ceroabnormal-exit - El proceso a finalizado con un exit code distinto de cerokilled - El proceso a enviado un SIGTERM o se a finalizado externamentecrashed - El proceso crasheooom - El proceso se quedo sin memorialaunch-failed - El proceso nunca se ha ejecutado correctamenteintegrity-failure - las verificaciones de integridad de código de Windows fallaronexitCode Number - El exit code del proceso (por ejemplo, estado de waitpid si esta en posix, de GetExitCodeProcess en Windows).serviceName String (opcional) - El nombre no localizado del proceso.name String (opcional) - El nombre del proceso. Examples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.Emitted when the child process unexpectedly disappears. Esto se debe comúnmente porque se crasheo o cerro. It does not include renderer processes.
\nDevuelve:
\neventaccessibilitySupportEnabled Booleano - true cuando el soporte de accesibilidad de Chrome está activado, de lo contrario false.Es emitido cuando el soporte de accesibilidad de Chrome es modificado. Este evento se dispara cuando las tecnologías de asistencia, como un lector de pantalla, sin activados o desactivados. Vea https://www.chromium.org/developers/design-documents/accessibility para mas información.
\nDevuelve:
\nsession SessionEmitido cuando Electron ha creado una nueva session.
const { app } = require('electron')\n\napp.on('session-created', (session) => {\n console.log(session)\n})\nDevuelve:
\neventargv Cadena[] - Un arreglo de las líneas de argumentos de comandos de segunda instanciaworkingDirectory Cadena - El directorio de trabajo de segunda instanciaEste evento será emitido dentro de la primera instancia de tu aplicación cuando una segunda instancia ha sido ejecutada y llama app.requestSingleInstanceLock().
argv Es un Array los argumentos de la línea de comando de la segunda instancia y workingDirectory es su actual directorio de trabajo. Usualmente las aplicaciones responden a esto haciendo su ventana principal concentrada y no minimizada.
Note: If the second instance is started by a different user than the first, the argv array will not include the arguments.
Este evento garantiza que se ejecute después del evento ready de app para ser emitido.
Note: Chromium podría agregar argumentos extras de línea de comando, por ejemplo --original-process-start-time.
Devuelve:
\neventwebContents WebContentsEmitido cuando desktopCapturer.getSources() es llamado en el render process del webContents. Llamando a event.preventDefault() hará que devuelva fuentes vacías.
El objeto app tiene los siguientes métodos:
Note: Algunos métodos solo están disponibles en sistemas operativos específicos y son etiquetados como tal.
\napp.quit()Intenta cerrar todas las ventanas. El evento before-quit se producirá primero. Si todas las ventas son cerradas exitosamente, el evento will-quit será emitido y por defecto la aplicación se cerrará.
Este método asegura que todos los controladores para los eventos beforeunload y unload se ejecutan correctamente. Es posible que una ventana cancele la salida devolviendo falso en el controlador de eventos beforeunload.
app.exit([exitCode])exitCode Íntegro (opcional)Sale inmediatamente con exitCode. exitCode por defecto 0.
Todas las ventanas serán cerradas de inmediato sin preguntarle al usuario, y los eventos before-quit y will-quit no serán emitidos.
app.relaunch([options])options Object (opcional)args String[] - (opcional)execPath String (opcional)Reinicia la aplicación cuando la instancia actual se cierra.
\nPor defecto, la nueva instancia va a usar el mismo directorio de trabajo y los argumentos de la linea de comando con la instancia actual. Cuando se especifican args, entonces args se pasarán como argumentos de línea de comandos. Si se especifica execPath, entonces execPath se ejecutará como reinicio de la aplicación en vez de la aplicación actual.
Note que este método no finaliza la aplicación cuando se ejecuta, debe llamar a app.quit o app.exit después de llamar app.relaunch para hacer que la aplicación se reinicie.
Cuando app.relaunch se llama múltiples veces, se iniciarán múltiples instancias después de que la instancia actual finalice.
Un ejemplo de reiniciar la instancia actual de forma inmediata y agregar un nuevo argumento a la línea de comandos de la nueva instancia:
\nconst { app } = require('electron')\n\napp.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) })\napp.exit(0)\napp.isReady()Devuelve Boolean - true Si Electron ha terminado de inicializarse, de lo contrario false. See also app.whenReady().
app.whenReady()Retorna Promise<void> - cumplido cuando Electron esta inicializado. También puede ser utilizado para comprobar el estado de: app.isReady() y registrar al evento ready si la aplicación aun no esta lista.
app.focus([options])options Object (opcional)steal Boolean macOS - Make the receiver the active app even if another app is currently active.En Linux, se centra en la primera ventana visible. On macOS, makes the application the active app. On Windows, focuses on the application's first window.
\nYou should seek to use the steal option as sparingly as possible.
app.hide() macOSOculta todas la ventanas de la aplicación sin minimizarlas.
\napp.show() macOSMuestra las ventanas de la aplicación luego de que se ocultaron. No los enfoca automáticamente.
\napp.setAppLogsPath([path])path String (opcional) - Una ruta personalizada para tus registros. Debe ser absoluta.Establece o crea un directorio de registros de tu aplicación el cual puede ser manipulado con app.getPath() o app.setPath(pathName, newPath).
Llamando app.setAppLogsPath() sin un parámetro path resultará en que este directorio sea establecido a ~/Library/Logs/YourAppName en macOS, y dentro del directorio userData en Linux y Windows.
app.getAppPath()Devuelve String - El directorio actual de la aplicación.
app.getPath(name)name String - You can request the following paths by the name:home Directorio personal del usuario.appData Directorio de datos de la aplicación por usuario, el cual por defecto apunta a:%APPDATA% en Windows$XDG_CONFIG_HOME o ~/.config en Linux~/Library/Application Support en marcOSuserData El directorio para almacenar los archivos de configuración de su aplicación, que es por defecto, el directorio appData seguido del nombre de su aplicación.chachétemp Directorio temporal.exe El archivo ejecutable actual.module La librería libchromiumcontent.desktop El escritorio actual del usuario.documents Directorio \"Mis documentos\" del usuario.downloads Directorio para las descargas del usuario.music Directorio para la música del usuario.pictures Directorio para las imágenes del usuario.videos Directorio para los vídeos del usuario.recent Directory for the user's recent files (Windows only).logs Directorio para los archivos de registro de la aplicación.crashDumps Directory where crash dumps are stored.Devuelve String - Una ruta a un directorio especial o un archivo asociado con name. En caso de falla, un Error es lanzado.
Si se llama a app.getPath('logs') sin que se llame primero a app.setAppLogsPath(), se creará un directorio de registro por defecto equivalente a llamar a app.setAppLogsPath() sin un parámetro path.
app.getFileIcon(path[, options])path Stringoptions Object (opcional)size Stringpequeño - 16x16normal - 32x32large - 48x48 en Linux, 32x32 en Windows, no soportado en macOS.Devuelve Promise<NativeImage> - cumplido con el icono de la aplicación, el cual es un NativeImage.
Obtiene el icono asociado a la ruta.
\nEn Windows, Hay dos tipos de iconos:
\n.mp3, .png, etc..exe, .dll, .ico.En Linux y macOS, los iconos dependen de la aplicación asociada al tipo de archivo.
\napp.setPath(name, path)name Stringpath StringReemplaza el path a un directorio especial o un archivo asociado con name. Si la ruta especifica un directorio que no existe, un Error es lanzado. En ese caso, el directorio devería ser creado con fs.mkdirSync o similar.
Solo puede sobrescribir rutas de un name definido en app.getPath.
Por defecto, las cookies y el caché de una página web serán almacenados en el directorio userData. Si quiere cambiar su localización, tiene que sobrescribir la ruta de userData ante de que el evento ready del módulo app se emita.
app.getVersion()Devuelve String - La versión de la aplicación cargada. Si no se encuentra la versión en el fichero package.json de la aplicación, se devuelve la versión del paquete o ejecutable.
app.getName()Devuelve String - El nombre actual de la aplicación, que se corresponde con el nombre especificado en el fichero package.json de la aplicación.
Usualmente el campo name de package.json es un nombre corto en minúscula, de acuerdo con las especificaciones de los módulos npm. Normalmente debe especificar un productName también, el cual es el nombre de su aplicación en mayúsculas, y que será preferido por Electron sobre name.
app.setName(name)name StringReescribe el nombre de la aplicación actual.
\nNota: Esta función anula el nombre usado internamente por Electron; no afecta el nombre que el usa el sistema operativo.
\napp.getLocale()Devuelve String - Los parámetros regionales actuales de la aplicación, recopilados usando la biblioteca l10n_util de Chromium. Los posibles valores de retorno son documentados aquí.
Para establecer el locale, querrás usar un interruptor de línea de comandos al inicio de la aplicación, que puede encontrarse aquí.
\nNota: Al distribuir su aplicación empaquetada, también tiene que enviar las carpetas locales.
Note: En windows, tienes que llamarlo después del los eventos ready sean emitidos.
app.getLocaleCountryCode()Devuelve String - El código de país ISO 3166 de dos letras del sistema operativo del usuario. El valor es tomado desde APIs nativas del sistema operativo.
Note: Cuando no se puede detectar el código de país local, devuelve una cadena vacía.
\napp.addRecentDocument(path) macOS Windowspath StringAñade la ruta a la lista de documentos recientes.
Esta lista es administrada por el sistema operativo. En Windows, puede visitar la lista desde la barra de tarea y en macOS, puede visitar la desde el menu dock.
\napp.clearRecentDocuments() macOS WindowsBorra la lista de documentos recientes.
\napp.setAsDefaultProtocolClient(protocol[, path, args])protocolo String - El nombre de su protocolo, sin el ://. Por ejemplo si quiere que su aplicación maneje enlaces electron://, llame este método con electron como el parámetro.path String (optional) Windows - The path to the Electron executable. Por defecto a process.execPathargs String Windows - Arguments passed to the executable. Por defecto a un array vacíoRegresa Boolean - Siempre que el llamado fue exitoso.
Establece el ejecutable actual as el manejador por defecto para un protocolo (alias esquema URI). Te permite integrar tu app aún más en el sistema operativo. Una vez registrado. todos los enlaces con tu-protocolo:// serán abiertos con el ejecutable actual. Todo el enlace, incluyendo el protocolo, sera pasado a tu aplicación como un parámetro.
Nota: En macOS, solo puede registrar protocolos que han sido agregados al info.plist de tu aplicación, el cual no puede ser modificado en tiempo de ejecución. Sin embargo, puede cambiar el archivo durante el tiempo de construcción a través de Electron Forge, Electron Packager, o editando información. listar con un editor de texto. Vea la Apple's documentation para mas información.
Note: En un entorno de Windows Store (cuando se empaqueta como appx) esta API devolverá true para todas las llamadas pero la clave de registro que establece no será accesible por otras aplicaciones. Para registrar tu aplicación de Windows Store como gestor de protocolo determinado debe declare the protocol in your manifest.
La API usa el Registro de Windows y LSSetDefaultHandlerForURLScheme internamente.
app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windowsprotocolo String - El nombre de su protocolo, sin el ://.ruta String (opcional) Windows - por defecto a process.execPathargs String Windows - por defecto a un arreglo vacíoRegresa Boolean - Siempre que el llamado fue exitoso.
This method checks if the current executable as the default handler for a protocol (aka URI scheme). If so, it will remove the app as the default handler.
\napp.isDefaultProtocolClient(protocol[, path, args])protocolo String - El nombre de su protocolo, sin el ://.ruta String (opcional) Windows - por defecto a process.execPathargs String Windows - por defecto a un arreglo vacíoDeveulve Boolean -Si el ejecutable actual es el manejador por defecto para un protocolo (alias esquema URI).
Nota: En macOS puede usar este método para verificar si la aplicación ha sido registrada como controladora por defecto para un protocolo. También puedes verificar esto al marcar ~/Library/Preferences/com.apple.LaunchServices.plist en el dispositivo macOS. Por favor vea la documentación de Apple para detalles.
La API usa el Registro de Windows y LSCopyDefaultHandlerForURLScheme internamente.
app.getApplicationNameForProtocol(url)url String - un URL con el nombre del protocolo para verificar. A diferencia de otros métodos de esta familia, este acepta una URL entera, incluyendo :// a un mínimo de (por ejemplo https://).Devuelve String - Nombre de la aplicación que controla el protocolo o un string vacío si no hay controlador. Por ejemplo, si Electron es el controlador por defecto de la URL, este podría ser Electron en Windows y Mac. Sin embargo, no confíe en el formato preciso que no se garantiza que no cambie. Espere un formato diferente en Linux, posiblemente con un sufijo .desktop.
Este método devuelve el nombre de la aplicación del controlador para el protocolo de la URL (alias schema URI).
\napp.getApplicationInfoForProtocol(url) macOS Windowsurl String - un URL con el nombre del protocolo para verificar. A diferencia de otros métodos de esta familia, este acepta una URL entera, incluyendo :// a un mínimo de (por ejemplo https://).Devuelve Promise<Object> - Resuelve con un objeto conteniendo lo siguiente:
icon NativeImage - the display icon of the app handling the protocol.path String - installation path of the app handling the protocol.name String - display name of the app handling the protocol.Este método devuelve una promesa que contiene el nombre, ícono y ruta de la aplicación del manejador predeterminado para el protocolo (esquema URI) de una URL.
\napp.setUserTasks(tasks) Windowstarea Tarea[] - Arreglo de objetos TareaAgrega tasks a la categoría Tasks de la Jump List en Windows.
tareas es un arreglo de objetos Task.
Regresa Boolean - Siempre que el llamado fue exitoso.
Nota: Si quisiese personalizar la lista de saltos aún más use en su lugar app.setJumpList(categories).
app.getJumpListSettings() WindowsDevuelve Objeto:
minItems Entero - El número mínimo de elementos que será mostrado en la lista (Para una descripción detallada de este valor vea el documento MSDN).removedItems JumpListItem[] - Array JumpListItem de objetos que corresponden a elementos que el usuario explícitamente a eliminado de la categorías personalizadas en el Jump List. Estos elementos no deben ser añadidos nuevamente a la jump list en el próximo llamado a app.setJumpList(), Windows no mostrará ninguna categoría personalizada que contenga alguno de los elementos removidos.app.setJumpList(categories) Windowscategories JumpListCategory[] | null - Array de objetos JumpListCategory.Configura o remueve una Jump list personalizada para la aplicación, y devuelve una de las siguientes cadenas:
\nok - Nada salió mal.error - Uno o más errores ocurrieron, habilite el registro del tiempo de corrida para averiguar la causa probable.invalidSeparatorError - An attempt was made to add a separator to a custom category in the Jump List. Separators are only allowed in the standard Tasks category.fileTypeRegistrationError - Fue realizado un intento de añadir el enlace del archivo a la Jump list para un tipo de archivo que la aplicación no está registrada para controlar.customCategoryAccessDeniedError - Cateogrías personalizadas no pueden ser añadidas a la Jump List debido a la privacidad del usuario o a la política del grupo.Si categories es null la configuración personalizada previa de la Jump List (si hay alguna) será reemplazada por la Jump List estándar para la aplicación (manejada por Windows).
Nota: Si un objeto JumpListCategory no tiene la propiedad type o name establecidas, entones se asume que el type es tasks. Si la propiedad name está establecida pero la propiedad type esta omitida entonces se asume que el type es custom.
Nota: Usuarios pueden remover elementos de las categorías personalizadas y Windows no permitirá que un elemento removido sea añadido de nuevo a la categoría personalizada hasta después del siguiente llamado exitoso a app.setJumpList(categories). Cualquier intento de añadir nuevamente el elemento a la categoría personalizada antes que eso resultará en que la categoría entera sea omitida de la Jump List. La lista de elemento removidos puede ser obtenida usando app.getJumpListSettings().
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
Aquí hay un ejemplo sencillo de cómo crear una Jump List personalizada:
\nconst { app } = require('electron')\n\napp.setJumpList([\n {\n type: 'custom',\n name: 'Recent Projects',\n items: [\n { type: 'file', path: 'C:\\\\Projects\\\\project1.proj' },\n { type: 'file', path: 'C:\\\\Projects\\\\project2.proj' }\n ]\n },\n { // has a name so `type` is assumed to be \"custom\"\n name: 'Tools',\n items: [\n {\n type: 'task',\n title: 'Tool A',\n program: process.execPath,\n args: '--run-tool-a',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool A'\n },\n {\n type: 'task',\n title: 'Tool B',\n program: process.execPath,\n args: '--run-tool-b',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool B'\n }\n ]\n },\n { type: 'frequent' },\n { // has no name and no type so `type` is assumed to be \"tasks\"\n items: [\n {\n type: 'task',\n title: 'New Project',\n program: process.execPath,\n args: '--new-project',\n description: 'Create a new project.'\n },\n { type: 'separator' },\n {\n type: 'task',\n title: 'Recover Project',\n program: process.execPath,\n args: '--recover-project',\n description: 'Recover Project'\n }\n ]\n }\n])\napp.requestSingleInstanceLock()Devuelve Boolean
El valor devuelto de este método indica si esta instancia de su aplicación obtuvo con éxito el bloqueo. Si no se puede obtener el bloqueo, puedes asumir que otra instancia de tu aplicación ya está corriendo con el bloqueo y salir inmediatamente.
\nI.e. Este método devuelve true si el proceso es la instancia principal de tu aplicación y tu aplicación debe seguir cargando. Retorna false si su proceso deja inmediatamente de enviar parámetros a otra instancia que ya haya adquirido el bloqueo con anterioridad.
En macOS, el sistema fuerza instancias únicas automáticamente cuando los usuario intentan abrir una segunda instancia de tu aplicación en Finder, y los eventos open-file y open-url seran emitidos por eso. Como sea, cuando los usuarios inicien tu aplicación en la linea de comando, el mecanismo de instancias única del sistema del sistema serán puenteadas, y tendrás que usar este método para asegurar una única instancia.
Un ejemplo de activar la ventana de la instancia primaria cuando una de segunda instancia se inicia:
\nconst { app } = require('electron')\nlet myWindow = null\n\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Someone tried to run a second instance, we should focus our window.\n if (myWindow) {\n if (myWindow.isMinimized()) myWindow.restore()\n myWindow.focus()\n }\n })\n\n // Create myWindow, load the rest of the app, etc...\n app.whenReady().then(() => {\n myWindow = createWindow()\n })\n}\napp.hasSingleInstanceLock()Devuelve Boolean
Este método devuelve si esta instancia de tu aplicación es actualmente manteniendo el bloqueo de una sola instancia. Usted puede realiza un bloqueo con app.requestSingleInstanceLock() o liberarlo con app.releaseSingleInstanceLock()
app.releaseSingleInstanceLock()Releases all locks that were created by requestSingleInstanceLock. This will allow multiple instances of the application to once again run side by side.
app.setUserActivity(type, userInfo[, webpageURL]) macOStype Caden - Raramente identifica la actividad. Se asigna a NSUserActivity.activityType.userInfo any - Estado especifico de la aplicación para almacenar para su uso por otro dispositivo.webpageURL String (optional) - The webpage to load in a browser if no suitable app is installed on the resuming device. The scheme must be http or https.Crea un NSUserActivity y se establece como la actividad actual. La actividad es elegible para Handoff a otro dispositivo luego.
app.getCurrentActivityType() macOSDevuelve String - El tipo de la actividad que se está ejecutando actualmente.
app.invalidateCurrentActivity() macOSInvalida la actividad actual Handoff del usuario.
\napp.resignCurrentActivity() macOSMarca la actividad actual del usuario Handoff como inactiva sin invalidarla.
\napp.updateCurrentActivity(type, userInfo) macOStype Caden - Raramente identifica la actividad. Se asigna a NSUserActivity.activityType.userInfo any - Estado especifico de la aplicación para almacenar para su uso por otro dispositivo.Actualiza la actividad actual si su tipo coincide type, fusionando las entradas de userInfo en su actual diccionario userInfo.
app.setAppUserModelId(id) Windowsid CadenaCambia el Id Modelo de Usuario de la Aplicación a id.
app.setActivationPolicy(policy) macOSpolicy String - Can be 'regular', 'accessory', or 'prohibited'.Sets the activation policy for a given app.
\nActivation policy types:
\napp.importCertificate(options, callback) Linuxoptions Objectcetificado Cadena - camino para el archivo pkcs12.contraseña Cadena - Frase clave para el certificado.callback Funciónresultado Entero - Resultado del importe.Importa el certificado en formato pkcs12 dentro del certificado de la plataforma. callback es llamado con el result de la operación de importación, un valor 0 indica que fue exitoso mientras que cualquier otro valor indica que fallo de acuerdo a Chromium net_error_list.
app.configureHostResolver(options)options ObjectenableBuiltInResolver Boolean (opcional) - Si el resolver de host integrado se utiliza en preferencia para getaddrinfo. Cuando está activado, el resolver integrado intentara usar las configuraciones DNS del sistema para hacer las consultas DNS por si mismo. Activado por defecto en macOS, desactivado por defecto en Windows y Linux.secureDnsMode String (opcional) - Puede ser \"off\", \"automatic\" o \"secure\". Configura el modo DNS-over-HTTP. Cuando es \"off\", las búsquedas DoH no se realizarán. Cuando es \"automatic\", las búsquedas DoH se realizarán primero si DoH está disponible, y las búsquedas DNS se realizarán como una reserva. Cuando es \"secure\", sólo se realizarán búsquedas DoH. Por defecto es \"automatic\".secureDnsServers String[] (opcional) - Una lista de plantillas de servidor DNS-over-HTTP. Vea RFC8484 § 3 para más detalles sobre el formato de la plantilla. La mayoría de los servidores soportan el método POST; la plantilla para estos servidores es simplemente una URI. Tenga en cuenta que para algunos proveedores DNS , el resolver actualizará automáticamente a DoH a menos que DoH este explícitamente desactivado, incluso si no hay servidores DoH proporcionados en esta lista.enableAdditionalDnsQueryTypes Boolean (opcional) - Controla si consultas DNS de tipos adicionales, p.e. HTTPS(DNS type 65) serán permitidas ademas de las tradicionales consultas A y AAAA cuando una solicitud esta siendo hecha a través de DNS inseguro. No tiene efecto en DNS seguro que siempre permite tipos adicionales. Defaults to true.Configure la resolución de host (DNS y DNS-over-HTTPS). Por defecto, se utilizarán los siguientes resolutores en orden:
\ngetaddrinfo).Esto puede ser configurado tanto para restringir el uso de DNS no-encriptado (secureDnsMode: \"secure\"), o desactivar DNS-over-HTTPS (secureDnsMode:\"off\"). También es posible activar o desactivar el resolver incorporado.
Para desactivar DNS inseguro, puede especificar secureDnsMode de \"secure\". Si usted hace eso, debería asegurarse de proveer una lista de servidores DNS-overHTTPS para usar, en caso de que la configuración DNS del usuario no incluya un proveedor que soporte DoH.
app.configureHostResolver({\n secureDnsMode: 'secure',\n secureDnsServers: [\n 'https://cloudflare-dns.com/dns-query'\n ]\n})\nEsta API debe ser llamada antes que el evento ready sea emitido.
app.disableHardwareAcceleration()Desactiva la aceleración por hardware para esta aplicación.
\nEste método solo puede ser llamado despues de iniciada la aplicación.
\napp.disableDomainBlockingFor3DAPIs()By default, Chromium disables 3D APIs (e.g. WebGL) until restart on a per domain basis if the GPU processes crashes too frequently. This function disables that behavior.
\nEste método solo puede ser llamado despues de iniciada la aplicación.
\napp.getAppMetrics()Devuelve ProcessMetric[]: Array de ProcessMetric objetos que corresponden a la memoria y estadísticas de uso de la CPU de todos los procesos asociados con la aplicación.
app.getGPUFeatureStatus()Devuelve GPUFeatureStatus - el estado de la función de gráficos de chrome://gpu/.
Note: Esta información sólo es usable después de que le evento gpu-info-update es emitido.
app.getGPUInfo(infoType)infoType String - Puede ser basic o complete.Devuelve Promise<unknown>
Para infoType igual a complete: La promesa es completada con Object conteniendo toda la información de la GPU como chromium's GPUInfo object. Esto incluye la versión y la información del controlador que es mostrada en la pagina chrome://gpu.
Para infoType igual a basic: La promesa se cumple con Object que contiene pocos atributos que son solicitados con complete. Aquí hay un ejemplo de respuesta básica:
{\n auxAttributes:\n {\n amdSwitchable: true,\n canSupportThreadedTextureMailbox: false,\n directComposition: false,\n directRendering: true,\n glResetNotificationStrategy: 0,\n inProcessGpu: true,\n initializationTime: 0,\n jpegDecodeAcceleratorSupported: false,\n optimus: false,\n passthroughCmdDecoder: false,\n sandboxed: false,\n softwareRendering: false,\n supportsOverlays: false,\n videoDecodeAcceleratorFlags: 0\n },\n gpuDevice:\n [{ active: true, deviceId: 26657, vendorId: 4098 },\n { active: false, deviceId: 3366, vendorId: 32902 }],\n machineModelName: 'MacBookPro',\n machineModelVersion: '11.5'\n}\nEl uso de basic debería ser preferido si sólo se necesita información básica como vendorId o driverId.
app.setBadgeCount([count]) Linux macOScount Integer (opcional) - Si un valor es proporcionado, establece el badge al valor proporcionado de lo contrario en macOS, muestra un simple punto blanco (p. ej. número desconocido de notificaciones). En Linux, si un valor no es proporcionado el badge no se mostrará.Regresa Boolean - Siempre que el llamado fue exitoso.
Sets the counter badge for current app. Setting the count to 0 will hide the badge.
On macOS, it shows on the dock icon. En Linux, solo funciona para Unity launcher.
\nNota: El lanzador de Unity necesita un archivo .desktop para funcionar. Para más información, por favor lee la documentación de integración con Unity.
app.getBadgeCount() Linux macOSDevolver Entero - El valor actual establecido en la insignia contraria.
app.isUnityRunning() LinuxDevuelve Boolean - Aunque el ambiente del escritorio actual sea un ejecutador de Unity.
app.getLoginItemSettings([options]) macOS Windowsoptions Object (opcional)Su proporcionas las opciones path y args a app.setLoginItemSettings, entonces necesitas pasar los mismos argumentos aquí para openAtLogin para que sea correctamente configurado.
Devuelve Objeto:
openAtLogin Boolean - true si la aplicación es establecida para abrirse al iniciar.openAsHidden Boolean macOS - true if the app is set to open as hidden at login. Esta configuración no está disponible en builds para la tienda de aplicaciones de MAC.wasOpenedAtLogin Boolean macOS - true if the app was opened at login automatically. Esta configuración no está disponible en builds para la tienda de aplicaciones de MAC.wasOpenedAsHidden Boolean macOS - true if the app was opened as a hidden login item. Esto indica que la aplicación no debería abrir ninguna ventana al inicio. Esta configuración no está disponible en builds para la tienda de aplicaciones de MAC.restoreState Boolean macOS - true if the app was opened as a login item that should restore the state from the previous session. Esto indica que la aplicación debería restaurar las ventanas que fueron abiertas la última vez que la aplicación fue cerrada. Esta configuración no está disponible en builds para la tienda de aplicaciones de MAC.executableWillLaunchAtLogin Boolean Windows - true if app is set to open at login and its run key is not deactivated. This differs from openAtLogin as it ignores the args option, this property will be true if the given executable would be launched at login with any arguments.launchItems Object[] Windowsname String Windows - name value of a registry entry.path String Windows - The executable to an app that corresponds to a registry entry.args String[] Windows - the command-line arguments to pass to the executable.scope String Windows - one of user or machine. Indicates whether the registry entry is under HKEY_CURRENT USER or HKEY_LOCAL_MACHINE.enabled Boolean Windows - true if the app registry key is startup approved and therefore shows as enabled in Task Manager and Windows settings.app.setLoginItemSettings(settings) macOS Windowssettings ObjectopenAtLogin Boolean (optional) - true to open the app at login, false to remove the app as a login item. Por defecto es false.openAsHidden Boolean (optional) macOS - true to open the app as hidden. Por defecto a false. El usuario puede editar esta configuración desde la Preferencias del Sistema, así que app.getLoginItemSettings().wasOpenedAsHidden debe ser comprobado cuanto la aplicación es abierta para conocer el valor actual. Esta configuración no está disponible en builds para la tienda de aplicaciones de MAC.path String (optional) Windows - The executable to launch at login. Por defecto a process.execPath.args String Windows - The command-line arguments to pass to the executable. Por defecto a un array vacío. Take care to wrap paths in quotes.enabled Boolean (optional) Windows - true will change the startup approved registry key and enable / disable the App in Task Manager and Windows Settings. Por defecto es true.name String (optional) Windows - value name to write into registry. Defaults to the app's AppUserModelId(). Establece los objetos de inicio de ajuste de la aplicación.Para trabajar con autoUpdater de Electron en Windows, el cual usa Squirrel, querrás establecer el camino de ejecución de Update.exe, y pasarán los argumentos que especifican el nombre de tu aplicación. Por ejemplo:
const appFolder = path.dirname(process.execPath)\nconst updateExe = path.resolve(appFolder, '..', 'Update.exe')\nconst exeName = path.basename(process.execPath)\n\napp.setLoginItemSettings({\n openAtLogin: true,\n path: updateExe,\n args: [\n '--processStart', `\"${exeName}\"`,\n '--process-start-args', `\"--hidden\"`\n ]\n})\napp.isAccessibilitySupportEnabled() macOS WindowsDevuelve Boolean - true si la accesibilidad de soporte de Chrome es habilitado, o false de otra manera. Esta API devolverá true si el uso de tecnologías asistivas, como leectores de pantallas, son detectadas. Ver https://www.chromium.org/developers/design-documents/accessibility para más detalles.
app.setAccessibilitySupportEnabled(enabled) macOS Windowsenabled Boolean - Activa o desactiva el renderizado del árbol de accesibilidadManualmente habilita el soporte de accesibilidad de Chrome, lo que permite exponer el interruptor de accesibilidad a los usuarios en la configuración de la aplicación. Mira Chromium's accessibility docs para mas detalles. Desactivado por defecto.
\nEsta API debe ser llamada antes que el evento ready sea emitido.
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
\napp.showAboutPanel()Show the app's about panel options. These options can be overridden with app.setAboutPanelOptions(options).
app.setAboutPanelOptions(options)options ObjectapplicationName Cadena (opcional) - El nombre de la aplicación.applicationVersion Cadena (opcional) - La versión de la aplicación.copyright Cadena (opcional) - La información de Copyright.version String (optional) macOS - The app's build version number.credits String (optional) macOS Windows - Credit information.authors String Linux - List of app authors.website String (optional) Linux - The app's website.iconPath String (optional) Linux Windows - Path to the app's icon in a JPEG or PNG file format. On Linux, will be shown as 64x64 pixels while retaining aspect ratio.Establece el panel de opciones. This will override the values defined in the app's .plist file on macOS. Ver el Apple docs para más detalles. En Linux, los valores deben establecerse para ser mostrados; no hay valores por defecto.
Si no estableces credits pero aún deseas sacarlos en tu aplicación, AppKit buscará por un archivo llamado \"Credits.html\", \"Credits.rtf\", y \"Credits.rtfd\", en ese orden, en el paquete devuelto por el método de clase principal NSBundle. El primer archivo encontrado es usado, y si no se encuentra ninguno, el área de información se deja en blanco. Vea la documentation de Apple para más información.
app.isEmojiPanelSupported()Devuelve Boolean - si la versión del sistema operativo actual permite permite o no los selectores de emoji nativos.
app.showEmojiPanel() macOS WindowsMuestra el selector de emoji nativo de la plataforma.
\napp.startAccessingSecurityScopedResource(bookmarkData) masbookmarkData String - El marcador de datos de ámbito de seguridad de codificación base64 devuelto por los métodos dialog.showOpenDialog o dialog.showSaveDialog.Returns Function - This function must be called once you have finished accessing the security scoped file. Si no recuerdas de dejar de acceder el marcador, recursos de nucleo se fugarán y tu aplicación se perderá su capacidad de alcanzar afuera del entorno aislado completamente hasta que se reinicia tu aplicación.
// Start accessing the file.\nconst stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)\n// You can now access the file outside of the sandbox 🎉\n\n// Remember to stop accessing the file once you've finished with it.\nstopAccessingSecurityScopedResource()\nEmpezar a acceder un recurso de ámbito de seguridad. Con este método las aplicaciones Electron que están empaquetadas para la Mac App Store pueden llegar fuera de su caja de arena para acceder a los archivos elegidos por el usuario. Ver a Apple's documentation por una descripción de cómo funciona este sistema.
\napp.enableSandbox()Habilita el modo sandbox completo en la aplicación. This means that all renderers will be launched sandboxed, regardless of the value of the sandbox flag in WebPreferences.
Este método solo puede ser llamado despues de iniciada la aplicación.
\napp.isInApplicationsFolder() macOSDevuelve Boolean - Si la aplicación esta actualmente ejecutándose desde la carpeta de Aplicación del sistema. Use in combination with app.moveToApplicationsFolder()
app.moveToApplicationsFolder([options]) macOSoptions Object (opcional)conflictHandler Function\\conflictType String - El tipo de conflicto de movimiento encontrado por el controlador; puede ser exists o existsAndRunning, donde exists quiere decir que una aplicación con el mismo nombre está presente el directorio de las Aplicaciones y existsAndRunning quiere decir que que existe y que se está ejecutando actualmente.Devuelve Boolean - Si el movimiento fue realizado correctamente. Por favor, ten en cuenta que si el movimiento es exitoso, tu aplicación se cerrará y se reiniciará.
No confirmation dialog will be presented by default. If you wish to allow the user to confirm the operation, you may do so using the dialog API.
NOTE: This method throws errors if anything other than the user causes the move to fail. Por ejemplo si el usuario cancela el dialogo de autorización, este método va a devolver falso. Si nosotros no realizamos la copia, entonces este método va a lanzar un error. The message in the error should be informative and tell you exactly what went wrong.
\nBy default, if an app of the same name as the one being moved exists in the Applications directory and is not running, the existing app will be trashed and the active app moved into its place. If it is running, the pre-existing running app will assume focus and the previously active app will quit itself. Este comportamiento puede ser cambiado proporcionando un controlador de conflicto opcional, donde el booleano devuelto por el controlado determina si el conflicto de movimiento se resuelve o no con el controlador por defecto. es decir, devolviendo false se asegura que no se tomaran más acciones, devolviendo true resultará en el comportamiento por defecto y el método continuando.
Por ejemplo:
\napp.moveToApplicationsFolder({\n conflictHandler: (conflictType) => {\n if (conflictType === 'exists') {\n return dialog.showMessageBoxSync({\n type: 'question',\n buttons: ['Halt Move', 'Continue Move'],\n defaultId: 0,\n message: 'An app of this name already exists'\n }) === 1\n }\n }\n})\nSignificaría que si una aplicación ya existe en el directorio del usuario, si el usuario elige 'Continuar Mover' entonces la función debería continuar con su comportamiento por defecto y la aplicación existente será eliminada y la aplicación activa será movida en su lugar.
\napp.isSecureKeyboardEntryEnabled() macOSReturns Boolean - whether Secure Keyboard Entry is enabled.
By default this API will return false.
app.setSecureKeyboardEntryEnabled(enabled) macOSenabled Boolean - Enable or disable Secure Keyboard EntrySet the Secure Keyboard Entry is enabled in your application.
By using this API, important information such as password and other sensitive information can be prevented from being intercepted by other processes.
\nSee Apple's documentation for more details.
\nNote: Enable Secure Keyboard Entry only when it is needed and disable it when it is no longer needed.
app.accessibilitySupportEnabled macOS WindowsUn propiedad Boolean eso es true si el soporte de accesibilidad de Chrome esta activado, false de otra manera. Esta propiedad será true si se ha detectado el uso de tecnologías asistitivas, como lectores de pantalla. Estableciendo esta propiedad manualmente a true se activá el soporte de accesibilidad de Chrome, permitiendo a los desarrolladores exponer el cambio de accesibilidad a los usuarios en la configuración de la aplicación.
See Chromium's accessibility docs for more details. Desactivado por defecto.
\nEsta API debe ser llamada antes que el evento ready sea emitido.
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
\napp.applicationMenuUna propiedad Menu | null que devuelve Menu si uno ha sido establecido y null de lo contrario. Los usuarios pueden pasar un Menú para establecer esta propiedad.
app.badgeCount Linux macOSUna propiedad Integer que devuelve el recuento de insignias para la aplicación actual. Setting the count to 0 will hide the badge.
On macOS, setting this with any nonzero integer shows on the dock icon. On Linux, this property only works for Unity launcher.
\nNota: El lanzador de Unity necesita un archivo .desktop para funcionar. Para más información, por favor lee la documentación de integración con Unity.
Note: On macOS, you need to ensure that your application has the permission to display notifications for this property to take effect.
\napp.commandLine ReadonlyUn objeto CommandLine que te permite leer y manipular los argumentos de linea de comando que usa Chromium.
app.dock macOS ReadonlyA Dock | undefined object that allows you to perform actions on your app icon in the user's dock on macOS.
app.isPackaged ReadonlyUna propiedad Boolean que retorna true si la aplicación está empaquetada, false si no lo está. Para muchas aplicaciones, esta propiedad puede ser usada para distinguir los ambientes de desarrollo y producción.
app.nameUna propiedad String que índica el nombre actual de la aplicación, el cual es el nombre en el archivo package.json de la aplicación.
Usualmente el campo name de package.json es un nombre corto en minúscula, de acuerdo con las especificaciones de los módulos npm. Normalmente debe especificar un productName también, el cual es el nombre de su aplicación en mayúsculas, y que será preferido por Electron sobre name.
app.userAgentFallbackUn String que es la cadena de agente de usuario Electron usará como una regresión global.
Este es el agente de usuario que se utilizará cuando ningún agente de usuario está establecido en el nivel webContents o session. Es útil para asegurar que la aplicación entera tiene el mismo agente de usuario. Establecer a un valor personalizado lo antes posible en la inicialización de tu aplicación para asegurar que el valor sobrescrito es usado.
app.runningUnderRosettaTranslation macOS Readonly DeprecatedA Boolean which when true indicates that the app is currently running under the Rosetta Translator Environment.
You can use this property to prompt users to download the arm64 version of your application when they are running the x64 version under Rosetta incorrectly.
\nObsoleto: Esta propiedad es reemplazada por la propiedad runningUnderARM64Translation la cual detecta cuando la aplicación esta traducida a ARM64 tanto en macOS y Windows.
app.runningUnderARM64Translation Readonly macOS WindowsUn Boolean el cual cuando es true indica que la aplicación actualmente está ejecutándose bajo un traductor ARM64 (como el Rosetta Translator Environment de macOS o WOW de Windows).
You can use this property to prompt users to download the arm64 version of your application when they are running the x64 version under Rosetta incorrectly.
", "title": "app", "description": "Controla el ciclo de vida de los eventos de su aplicación." }, "/docs/tutorial/application-debugging": { "locale": "es-ES", "slug": "application-debugging", "href": "/docs/tutorial/application-debugging", "crowdinFileId": "256175", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/application-debugging.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Cada vez que su aplicación de Electron no se comporta de la manera que desea, una variedad de herramientas de depuración pueden ayudarte a encontrar errores en el código, rendimiento, u oportunidades de optimización.
\nLa herramienta mas completa para depurar un proceso de renderización individualmente son las Chromium Developer Tools. Está disponible para todos los procesos de renderización, incluyendo BrowserWindow, BrowserView, y WebView. Puedes abrirla programáticamente usando la API openDevTools() de la instancia de webContents:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.webContents.openDevTools()\nGoogle ofrece documentación excelente para sus herramientas de desarrollo. Recomendamos que se familiarice con ello - son una de las utilidades más versátiles para cualquier desarrollador de aplicaciones de Electron.
\nLa depuración del proceso principal es un poco más complicada, porque en este caso no se pueden abrir las Developer Tools. Las Chromium Developer Tools pueden ser usadas para depurar el proceso principal de Electron gracias a una colaboración cercana entre Google / Chrome y Node.js, pero puede encontrar obstáculos como la ausencia de require en la consola.
Para mas información, vea la documentación de Depurando el Proceso Principal.
\nSi el contexto V8 se bloquea, el DevTools mostrará este mensaje.
\nDevTools fue desconectado de la página. Una vez que la pagina sea recargada, DevTools se reconectará automáticamente.
Los registros de Chromium puden ser habilitados a través de la variable de entorno ELECTRON_ENABLE_LOGGING. Para más información, vea la documentacion de variables de entorno.
Alternativamente, el argumento de linea de comando --enable-logging puede ser pasado. Más información esta disponible en la la documentación de parámetros de la línea de comando.
Para distribuir tu aplicación de Electron, necesitas empaquetarla y cambiar el nombre. Para hacer esto, puedes usar herramientas especializadas o manualmente.
\nPuedes usar las siguientes herramientas para distribuir tu aplicación:
\n\nEstas herramientas se encargaran de todo los pasos necesarios para crear una aplicación de Electron distribuible, como empaquetar tu aplicación, cambiar el nombre del ejecutable y configurar los iconos correctos.
\nYou can check the example of how to package your app with electron-forge in the Quick Start guide.
Para distribuir tu aplicación manualmente, necesitas descargar los prebuilt binaries de Electron. Luego, la carpeta que contiene tu aplicación debe llamarse app y colocarse en el directorio de recursos de Electron como se muestra en los siguientes ejemplos.
\n\nNOTA: la ubicación de los binarios preconstruidos de Electron esta indicado con
\nelectron/en los siguientes ejemplos.
En macOS:
\nelectron/Electron.app/Contents/Resources/app/\n├── package.json\n├── main.js\n└── index.html\nEn Windows y Linux:
\nelectron/resources/app\n├── package.json\n├── main.js\n└── index.html\nLuego ejecuta Electron.app en macOS, electron en Linux, o electron.exe en Windows, y tu aplicación Electron se ejecutará. El directorio electron será el que hay que dar a tus usuarios.
En lugar de enviar tu aplicación copiando todos sus archivos de origen, puedes empaquetar tu aplicación en un archivo asar para mejorar el rendimiento de los archivos de lectura en plataformas como Windows, si aún no estás usando un bundler como como Parcel o WebPack.
\nPara usar un archivo asar para reemplazar la carpeta app, debe cambiar el nombre del archivo. archive a app.asar, y póngalo en el directorio de recursos de Electron como a continuación, y Electron intentará leer el archivo y comenzar desde allí.
En macOS:
\nelectron/Electron.app/Contents/Resources/\n└── app.asar\nEn Windows y Linux:
\nelectron/resources/\n└── app.asar\nPuedes encontrar más detalles de como usar asar en el repositorio electron/asar .
Después de empaquetar su aplicación en Electron, querrá cambiar la marca de Electron antes de distribuirlo a sus usuarios.
\nPuede cambiar el nombre Electron.app a cualquier nombre que desee, y también debe cambiar el valor de los campos CFBundleDisplayName, CFBundleIdentifier y CFBundleName en los siguientes archivos:
Electron.app/Contents/Info.plistElectron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plistTambién puede cambiar el nombre de la aplicación auxiliar para evitar mostrar Electron Helper en el Monitor de actividad, pero asegúrese de haber cambiado el nombre del archivo ejecutable de la aplicación auxiliar.
La estructura de una aplicación renombrada sería similar a:
\nMyApp.app/Contents\n├── Info.plist\n├── MacOS/\n│ └── MyApp\n└── Frameworks/\n └── MyApp Helper.app\n ├── Info.plist\n └── MacOS/\n └── MyApp Helper\nPuede cambiar el nombre electron.exe a cualquier nombre que desee, y editar su icono y otra información con herramientas como rcedit.
Puede cambiar el nombre del archivo ejecutable electron a cualquier nombre que desee.
También es posible renombrar Electron simplemente cambiando el nombre del producto y volver a compilarlo desde el código fuente. Para hacerlo, necesita que el argumento de compilación se corresponda con el nombre del producto (electron_product_name = \"YourProductName\") en el archivo args.gn y recompilarlo.
\n\nEnable apps to automatically update themselves.
\n
Proceso: principal</0>
\nPuede Ver: Una guía detallada sobre cómo implementar las actualizaciones en su aplicación.
\nautoUpdater es un EventEmitter.
Actualmente, sólo macOS y Windows son soportados. No hay soporte para auto actualizaciones en Linux, por lo que es recomendable que use el gestor de paquetes de la distribución para actualizar su aplicación.
\nAdicionalmente, hay algunas diferencias sutiles en cada plataforma:
\nEn macOS, el módulo autoUpdater está construido sobre Squirrel.Mac, lo que significa que no necesita ninguna configuración especial para que funcione. Para los requisitos de servidor, puede leer Soporte de servidor. Tenga en cuenta que App Transport Security (ATS) se aplica para todas las solicitudes creadas como parte del proceso de actualizaciones. Aplicaciones que necesitan para desactivar ATS pueden agregar la clave de NSAllowsArbitraryLoads a su .plist de su aplicación.
Nota: Su aplicación debe ser firmada para actualizaciones automáticas en macOS. Este es un requerimiento de Squirrel.Mac.
On Windows, you have to install your app into a user's machine before you can use the autoUpdater, so it is recommended that you use the electron-winstaller, electron-forge or the grunt-electron-installer package to generate a Windows installer.
When using electron-winstaller or electron-forge make sure you do not try to update your app the first time it runs (Also see this issue for more info). Se recomienda usar electron-squirrel-startup para obtener acceso directo en el escritorio para su aplicación.
\nThe installer generated with Squirrel will create a shortcut icon with an Application User Model ID in the format of com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE, examples are com.squirrel.slack.Slack and com.squirrel.code.Code. Tu debes usar el mismo ID de tu aplicación con app.setAppUserModelId API, de lo contrario Windows no podría ejecutarlo correctamente en la barra de tareas.
Like Squirrel.Mac, Windows can host updates on S3 or any other static file host. You can read the documents of Squirrel.Windows to get more details about how Squirrel.Windows works.
\nEl objeto app emite los siguientes eventos:
Devuelve:
\nerror ErrorAparece cuando hay un error al actualizar.
\nAparece al comprobar si una actualización ya ha empezado.
\nEmitido cuando hay una actualización disponible. La actualización es descargada automáticamente.
\nAparece cuando no hay una actualización disponible.
\nDevuelve:
\neventreleaseNotes StringreleaseName StringreleaseDate DateupdateURL StringAparece cuando se ha descargado una actualización.
\nSolo esta disponible en Windows releaseName.
Nota: No es estrictamente necesario manejar este evento. Una actualización descargada con éxito se aplicará la próxima vez que la aplicación inicie.
\nEste evento se ejecuta luego que un usuario llama al método: quitAndInstall().
Cuando se hace el llamado a la API, el evento before-quit no se ejecuta hasta que todas las ventanas estén cerradas. Como resultado usted debe escuchar a este evento si desea realizar acciones antes de que las ventanas sean cerradas, mientras el proceso está finalizando, así como también escuchar al proceso: before-quit.
El objeto autoUpdater tiene los siguientes métodos:
autoUpdater.setFeedURL(options)options Objecturl Stringheaders Record<String, String> (opcional) macOS - Cabeceras de peticiones HTTP.serverType String (optional) macOS - Can be json or default, see the Squirrel.Mac README for more information.Configura el url e inicializa la actualización automática.
autoUpdater.getFeedURL()Devuelve String - La actualización actual provee el URL.
autoUpdater.checkForUpdates()Pregunta al servidor si hay una actualización. Debes llamar a setFeedURL antes de usar esta API.
Note: If an update is available it will be downloaded automatically. Calling autoUpdater.checkForUpdates() twice will download the update two times.
autoUpdater.quitAndInstall()Reinicia la aplicación e instala la actualización después que esta ha sido descargada. Sólo debería llamarse después de que update-downloaded ha sido emitido.
Llamar a autoUpdater.quitAndInstall() bajo la capucha cerrará todas las ventanas de la aplicación, y llamará automáticamente a app.quit() después de que se hayan cerrado todas las ventanas.
Note: It is not strictly necessary to call this function to apply an update, as a successfully downloaded update will always be applied the next time the application starts.
", "title": "autoUpdater", "description": "Enable apps to automatically update themselves." }, "/docs/tutorial/automated-testing-with-a-custom-driver": { "locale": "es-ES", "slug": "automated-testing-with-a-custom-driver", "href": "/docs/tutorial/automated-testing-with-a-custom-driver", "crowdinFileId": "256179", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/automated-testing-with-a-custom-driver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Para escribir pruebas automatizadas para su aplicación Electron, necesitará una forma de \"manejar\" su aplicación. Spectron es una solución de uso común que le permite emular las acciones de los usuarios a través de WebDriver. Sin embargo, también es posible escribir su propio controlador personalizado utilizando el IPC-over-STDIO incorporado en el nodo. El beneficio de un controlador personalizado es que tiende a requerir menos gastos generales que Spectron, y le permite exponer métodos personalizados a su conjunto de pruebas.
\nPara crear un controlador personalizado, usaremos la API de Node.js child_process. El conjunto de pruebas generará el proceso de Electron, luego establecerá un protocolo de mensajería simple:
\nconst childProcess = require('child_process')\nconst electronPath = require('electron')\n\n// spawn the process\nconst env = { /* ... */ }\nconst stdio = ['inherit', 'inherit', 'inherit', 'ipc']\nconst appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })\n\n// listen for IPC messages from the app\nappProcess.on('message', (msg) => {\n // ...\n})\n\n// envía un mensaje IPC a la aplicación \nappProcess.send({ my: 'message' })\nDesde dentro de la aplicación Electron, puedes escuchar mensajes y enviar respuestas usando la API de Node.js process:
\n// escuchar por mensajes IPC desde el suite de prueba\nprocess.on('message', (msg) => {\n // ...\n})\n\n// enviar un mensaje IPC al suite de prueba\nprocess.send({ my: 'message' })\nAhora podemos comunicar desde la suite de test a la aplicación Electron usando el objeto appProcess.
Por conveniencia, es posible que desee encapsular appProcess en un objeto controlador, que provea funciones de más alto nivel. Este es un ejemplo de como podría hacerlo:
class TestDriver {\n constructor ({ path, args, env }) {\n this.rpcCalls = []\n\n // start child process\n env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages\n this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })\n\n // handle rpc responses\n this.process.on('message', (message) => {\n // pop the handler\n const rpcCall = this.rpcCalls[message.msgId]\n if (!rpcCall) return\n this.rpcCalls[message.msgId] = null\n // reject/resolve\n if (message.reject) rpcCall.reject(message.reject)\n else rpcCall.resolve(message.resolve)\n })\n\n // wait for ready\n this.isReady = this.rpc('isReady').catch((err) => {\n console.error('Application failed to start', err)\n this.stop()\n process.exit(1)\n })\n }\n\n // simple RPC call\n // to use: driver.rpc('method', 1, 2, 3).then(...)\n async rpc (cmd, ...args) {\n // send rpc request\n const msgId = this.rpcCalls.length\n this.process.send({ msgId, cmd, args })\n return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))\n }\n\n stop () {\n this.process.kill()\n }\n}\nEn la aplicación, necesitará escribir un controlador sencillo para las llamadas RPC:
\nif (process.env.APP_TEST_DRIVER) {\n process.on('message', onMessage)\n}\n\nasync function onMessage ({ msgId, cmd, args }) {\n let method = METHODS[cmd]\n if (!method) method = () => new Error('Invalid method: ' + cmd)\n try {\n const resolve = await method(...args)\n process.send({ msgId, resolve })\n } catch (err) {\n const reject = {\n message: err.message,\n stack: err.stack,\n name: err.name\n }\n process.send({ msgId, reject })\n }\n}\n\nconst METHODS = {\n isReady () {\n // do any setup needed\n return true\n }\n // define your RPC-able methods here\n}\nLuego, en su suite de pruebas puede usar sus test-driver del siguiente modo:
\nconst test = require('ava')\nconst electronPath = require('electron')\n\nconst app = new TestDriver({\n path: electronPath,\n args: ['./app'],\n env: {\n NODE_ENV: 'test'\n }\n})\ntest.before(async t => {\n await app.isReady\n})\ntest.after.always('cleanup', async t => {\n await app.stop()\n})\nElectron CI on Windows uses AppVeyor, which in turn uses Azure VM images to run. Ocasionalmente, estas imagenes VM necesitan actualizarse debido a cambios en los requerimientos de Chormium. Para actualizar usted necesitará PowerShell y el Azure PowerShell module.
\nOcasionalmente necesitaremos actualizar estas imágenes debido a cambios en Chromium u otros requisitos varios de construcción.
\nEjemplo Caso de uso:\n* Necesitamos VS15.9 y tenemos instalada VS15.7; esto requeriría que actualicemos una imagen Azure.
Identifique la imagen que desea modificar.
\nObtenga la clave de la cuenta de almacenamiento Azure
\nappveyorlibccbuilds Disk Storage Account Name you'd look for appveyorlibccbuilds in the list of storage accounts @ Home < Storage AccountsAccess Keys, y luego puede utilizar cualquiera de las claves presentes en la lista.Obtenga la URI completa de imagen de maquina virtual de Azure
\n$ACCT_NAME < Blobs < ImagesCopiar la imagen usando el Copy Master Image PowerShell script.
\n(images)libcc-20core-vs2017-15.9-2019-04-15.vhdHaz una nueva VM usando el Crear VM Master de VHD PowerShell.
\nps1 con ./create_master_vm_from_vhd.ps1Standard_F32s_v2East USVuelva a iniciar sesión en Azure y encuentre la VM que recién ha sido creada en Home < Virtual Machines < $YOUR_NEW_VM
Usando Microsoft Remote Desktop, haga clic en Connect para conectarse a la VM.
AppVeyor Enterprise master VM.Modificar la VM como sea necesario.
\nApagar la VM y luego borrarla en Azure.
\nAgreagar la nueva imagen a l configuracion de la nube Appveyor o modifique una imagen para apuntar al nuevo VHD.
\ndeviceName StringdeviceId StringEl desarrollo con Electron es libre de opiniones, y no hay una \"única manera\" de desarrollar, construir, empaquetar y desplegar una aplicación Electron. Características adicionales, tanto para la fase de build como para la ejecución, pueden encontrarse con frecuencia en npm en paquetes individuales, permitiendo a los desarrolladores construir tanto las aplicaciones como los pipelines que necesiten.
\nEse nivel de modularidad y extensibilidad asegura que todos los desarrolladores que trabajan con Electron, ambos equipos grandes y pequeños, nunca estén restringidos en que pueden o no puedan hacer en cualquier momento durante sus ciclos de vida del desarrollo. Sin embargo, para muchos desarrolladores, uno de los boilerplates comunitarios o herramientas de línea de comandos podría facilitar dramáticamente el compilar, empacar y liberar una aplicación.
\nUn boilerplate es sólo un punto de partida -un lienzo en blanco, por así decirlo- a partir del cual construir su aplicación. Generalmente vienen en la forma de un repositorio, que se puede clonar y personalizar a gusto.
\nPor otro, lado una herramienta de línea de comandos sigue para apoyarle a lo largo del desarrollo y la liberación. Son mas útiles y serviciales pero encarga lineas directrices en cómo su código debe ser estructurado y construido. Especialmente para principiantes, el uso de una herramienta de linea de comando es probable que sea útil.
\nUna \"herramienta completa para las construcción de aplicaciones Electron modernas\". Electron Forge unifica las herramientas de construcción existentes (y bien mantenidas) para el desarrollo de Electron en un paquete cohesivo de manera que cualquiera pueda saltar directamente al desarrollo en Electron.
\nForge viene con a ready-to-use template usando Webpack como empaquetador. Incluye una configuración de tipo typescript y proporciona dos archivos de configuración para permitir una personalización fácil. Utiliza los mismos módulos de núcleo usados por la gran mayoría en la comunidad Electron (como electron-packager) -los cambios hechos por los mantenedores a cargo de Electron (como Slack), benefician también a los usuarios de Forge.
Puede encontrar información y documentación en electronforge.io.
\nUna \" solución completa para empaquetar y construir una aplicación Electron lista para su distribución\" que se centra en una experiencia integrada. electron-builder añade una única dependencia enfocada en la simplicidad y gestiona todos los requisitos internamente.
electron-builder reemplaza las características y módulos usados por los mantenedores a cargo de Electron (tales como el auto-actualizador) con los personalizados. Generalmente son bien integrados pero tendrán menos en común con las aplicaciones Electron populares como Atom, Visual Studio Code, o Slack.
Puede encontrar mas información y documentación en el repositorio.
\nSi no quiere herramientas, sólo un boilerplate sólido desde el que construir, puede que merezca la pena darle un vistazo a CT Lin's electron-react-boilerplate. Es muy popular en la comunidad y utiliza electron-builder internamente.
La lista \"Electron impresionante\" contiene más herramientas y boilerplates para escoger. Si encuentra la extensión de la lista algo intimidante, no olvide que añadir herramientas mientras avanza, también es un enfoque valido.
", "title": "Plantillas y CLIs", "description": "" }, "/docs/breaking-changes": { "locale": "es-ES", "slug": "breaking-changes", "href": "/docs/breaking-changes", "crowdinFileId": "256117", "githubUrl": "https://github.com/electron/electron/tree/main/docs/breaking-changes.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Los cambios de ruptura se documentaran aquí y se agregaran advertencias de desaprobación al código JS cuando sea posible, al menos una versión superior se publicará, antes de que se realice cualquier cambio.
\nEste documento usa la siguiente convención para clasificar los cambios de ruptura:
\nremote moduleThe remote module was deprecated in Electron 12, and will be removed in Electron 14. Es reemplazado por el módulo @electron/remote.
// Obsoleto en Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// Reemplazar con:\nconst { BrowserWindow } = require('@electron/remote')\n\n// En el proceso principal:\nrequire('@electron/remote/main').initialize()\napp.allowRendererProcessReuseThe app.allowRendererProcessReuse property will be removed as part of our plan to more closely align with Chromium's process model for security, performance and maintainability.
Para información más detallada vea #18397.
\nLa opción affinity al construir una nueva BrowserWindow se eliminará como parte de nuestro plan para alinear más estrechamente con el modelo de proceso de Chromium por seguridad, rendimiento y mantenimiento.
Para información más detallada vea #18397.
\nwindow.open()El parámetro opcional frameName ya no se establecerá como el título de la ventana. Esto ahora sigue la especificación descrita por la documentación nativa bajo el correspondiente parámetro windowName.
Si estaba usando este parámetro para establecer el título de una ventana, puede usar win.setTitle(title) en su lugar.
\nworldSafeExecuteJavaScriptEn Electron 14 worldSafeExecuteJavaScript será eliminado. No hay alternativa, por favor asegúrese que su código trabaja con esta propiedad activada. Ha sido activada por defecto desde Electron\n12.
Será afectado por este cambio si usted utliza webFrame.executeJavaScript o webFrame.executeJavaScriptInIsolatedWorld. Necesitará asegurase que los valores devueltos por cualquiera de esos métodos son soportados por Context Bridge API ya que estos métodos utilizan la misma semántica de paso de valores.
nativeWindowOpen por defecto a truePrior to Electron 14, window.open was by default shimmed to use BrowserWindowProxy. This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. nativeWindowOpen is no longer experimental, and is now the default.
See the documentation for window.open in Electron for more details.
\nPrior to Electron 14, windows opened with window.open would inherit BrowserWindow constructor options such as transparent and resizable from their parent window. Beginning with Electron 14, this behavior is removed, and windows will not inherit any BrowserWindow constructor options from their parents.
Instead, explicitly set options for the new window with setWindowOpenHandler:
webContents.setWindowOpenHandler((details) => {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n // ...\n }\n }\n})\nadditionalFeaturesThe deprecated additionalFeatures property in the new-window and did-create-window events of WebContents has been removed. Since new-window uses positional arguments, the argument is still present, but will always be the empty array []. (Though note, the new-window event itself is deprecated, and is replaced by setWindowOpenHandler.) Bare keys in window features will now present as keys with the value true in the options object.
// Removed in Electron 14\n// Triggered by window.open('...', '', 'my-key')\nwebContents.on('did-create-window', (window, details) => {\n if (details.additionalFeatures.includes('my-key')) {\n // ...\n }\n})\n\n// Replace with\nwebContents.on('did-create-window', (window, details) => {\n if (details.options['my-key']) {\n // ...\n }\n})\nsession.setPermissionCheckHandler(handler)El primer parámetro de los métodos handler anteriormente siempre era un webContents, ahora puede ser a veces null. Debe usar las propiedades requestingOrigin, embeddingOrigin y securityOrigin para responder correctamente a la verificación de permiso. Como el webContents puede ser null ya no se puede confiar en él.
// Old code\nsession.setPermissionCheckHandler((webContents, permission) => {\n if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {\n return true\n }\n return false\n})\n\n// Replace with\nsession.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {\n return true\n }\n return false\n})\nshell.moveItemToTrash()Se ha eliminado la API síncrona shell.moveItemToTrash() obsoleta. Utilice en su lugar shell.trashItem().
// Removed in Electron 13\nshell.moveItemToTrash(path)\n// Replace with\nshell.trashItem(path).then(/* ... */)\nBrowserWindowLa APIs de extensión han sido eliminadas:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()En su lugar use las APIs de session:
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Removed in Electron 13\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Replace with\nsession.defaultSession.loadExtension(path)\n// Removed in Electron 13\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// Replace with\nsession.defaultSession.removeExtension(extension_id)\n// Removed in Electron 13\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Replace with\nsession.defaultSession.getAllExtensions()\nsystemPreferencesLos métodos siguientes de systemPreferences han quedado obsoletos:
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()En su lugar, usa las siguientes propiedades nativeTheme:
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Removed in Electron 13\nsystemPreferences.isDarkMode()\n// Replace with\nnativeTheme.shouldUseDarkColors\n\n// Removed in Electron 13\nsystemPreferences.isInvertedColorScheme()\n// Replace with\nnativeTheme.shouldUseInvertedColorScheme\n\n// Removed in Electron 13\nsystemPreferences.isHighContrastColorScheme()\n// Replace with\nnativeTheme.shouldUseHighContrastColors\nnueva ventanaEl evento new-window de WebContents está obsoleto. Es reemplazado por webContents.setWindowOpenHandler().
// Obsoleto en Electron 13\nwebContents.on('new-window', (event) => {\n event.preventDefault()\n})\n\n// Reemplazar por\nwebContents.setWindowOpenHandler((details) => {\n return { action: 'deny' }\n})\nChromium a eliminado el soporte para Flash, por lo tanto nosotros debemos seguir el ejemplo. Vea el Flash Roadmap de Chromium para más detalles.
\nworldSafeExecuteJavaScript por defecto a trueEn Electron 12, worldSafeExecuteJavaScript será activado por defecto. Para restuaurar el comportamiento anterior, worldSafeExecuteJavaScript: false debe especificarse en WebPreferences. Por favor tenga en cuenta que estableciendo esta opción a false es inseguro.
Esta opción sera removida en Electron 14, así que por favor migra tu código para soportar el valor por defecto.
\ncontextIsolation por defecto a trueEn Electron 12, contextIsolation será activado por defecto. Para restaurar el comportamiento anterior contextIsolation: false debe ser especificado en WebPreferences.
Nosotros recomendamos tener contextIsolation activado por la seguridad de su aplicación.
\nOtra implicación es que require() no puede ser usada en el renderer process a menos que nodeIntegration sea true y contextIsolation sea false.
Para más detalles ver: https://github.com/electron/electron/issues/23506
\ncrashReporter.getCrashesDirectory()El método crashReporter.getCrashesDirectory ha sido eliminado. Uso debe ser reemplazado por app.getPath('crashDumps').
// Eliminado en Electron 12\ncrashReporter.getCrashesDirectory()\n// Reeamplazar con\napp.getPath('crashDumps')\ncrashReporter en el render processLos siguientes métodos crashReporter ya no están disponible en el renderer process:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryDeberían ser llamados solo desde el proceso principal.
\nVea #23265 para más detalles.
\ncrashReporter.start({ compress: true })El valor por defecto de la opción compress a crashReporter.start ha cambiado de false a true. Esto significa que los volcados se subirán al servidor de ingestión de errores con el encabezado Content-Encoding: gzip y el cuerpo será comprimido.
Si su servidor de gestión de fallos no soporta cargas comprimidas, puedes desactivar la compresión especificando { compress: false } en las opciones del reportero de errores .
remoteEl módulo remote está obsoleto en Electron 12 y sera eliminado en Electron 14. Es reemplazado por el módulo @electron/remote.
// Obsoleto en Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// Reemplazar con:\nconst { BrowserWindow } = require('@electron/remote')\n\n// En el proceso principal:\nrequire('@electron/remote/main').initialize()\nshell.moveItemToTrash()El síncrono shell.moveItemToTrash() ha sido reemplazado por el nuevo asíncrono shell.trashItem().
// Deprecated in Electron 12\nshell.moveItemToTrash(path)\n// Replace with\nshell.trashItem(path).then(/* ... */)\nBrowserView.{destroy, fromId, fromWebContents, getAllViews} y id propiedad de BrowserViewLas APIs experimentales BrowserView.{destroy, fromId, fromWebContents, getAllViews} fueron removidas. Adicionalmente, la propiedad id de BrowserView también ha sido removida.
Para ver más información, consulta #23578.
\ncompanyName para crashReporter.start()El argumento companyName para crashReporter.start(), que era previamente requerido, ahora es opcional, y aún más, está desaprobado. Para obtener el mismo comportamiento de una forma no desaprobada, pude pasar un valor companyName en globalExtra.
// Desaprobado en Electron 10\ncrashReporter.start({ companyName: 'Umbrella Corporation' })\n// Reemplazar con \ncrashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })\ncrashReporter.getCrashesDirectory()El método crashReporter.getCrashesDirectory ha sido desaprobado. Uso debe ser reemplazado por app.getPath('crashDumps').
// Obsoleto en Electron 10\ncrashReporter.getCrashesDirectory()\n// Reemplazar con\napp.getPath('crashDumps')\ncrashReporter en el renderer processLlamar a los siguientes métodos crashReporter desde el renderer process es obsoleto:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryLos únicos métodos no desaprobados restantes en el modulo crashReporter en el render son addExtraParameter, removeExtraParameter y getParameters.
Todos los métodos anteriores permanecen no desaprobados cuando son llamados desde el proceso principal.
\nVea #23265 para más detalles.
\ncrashReporter.start({ compress: false })Establecer { compress: false } en crashReporter.start está obsoleto. Casi todos los servidores de gestión de fallos soportan compresión gzip. Esta opción será eliminada en una versión futura de Electron.
enableRemoteModule por defecto a falseEn Electron 9, usar el módulo remoto sin habilitarlo explícitamente a través de la opción enableRemoteModule WebPreferences comenzó a emitir una advertencia. En Electron 10, el módulo remote está deshabilitado por defecto. Para usar el módulo remote debe especificarse enableRemoteModule: true en WebPreferences:
const w = new BrowserWindow({\n webPreferences: {\n enableRemoteModule: true\n }\n})\nNosotros recomendamos alejarse del módulo remote.
\nprotocol.unregisterProtocolprotocol.uninterceptProtocolLas APIs ahora son síncronas y el callback opcional ya no es necesario.
\n// Obsoleto\nprotocol.unregisterProtocol(scheme, () => { /* ... */ })\n// Reemplazar con \nprotocol.unregisterProtocol(scheme)\nprotocol.registerFileProtocolprotocol.registerBufferProtocolprotocol.registerStringProtocolprotocol.registerHttpProtocolprotocol.registerStreamProtocolprotocol.interceptFileProtocolprotocol.interceptStringProtocolprotocol.interceptBufferProtocolprotocol.interceptHttpProtocolprotocol.interceptStreamProtocolLas APIs ahora son síncronas y el callback opcional ya no es necesario.
\n// Obsoleto\nprotocol.registerFileProtocol(scheme, handler, () => { /* ... */ })\n// Reemplazar con \nprotocol.registerFileProtocol(scheme, handler)\nEl protocolo registrado o interceptado no tiene efecto en la página actual hasta que ocurra la navegación.
\nprotocol.isProtocolHandledEsta API está obsoleta y los usuarios deberían usar protocol.isProtocolRegistered y protocol.isProtocolIntercepted en su lugar.
// Obsoleto\nprotocol.isProtocolHandled(scheme).then(() => { /* ... */ })\n// Reemplazar con\nconst isRegistered = protocol.isProtocolRegistered(scheme)\nconst isIntercepted = protocol.isProtocolIntercepted(scheme)\nA partir de Electron 9 no permitimos la carga de módulos nativos no conscientes del contexto en el proceso de renderizado. Esto es para mejorar la seguridad, el rendimiento y el mantenimiento de Electron como proyecto.
\nSi esto te impacta, puedes configurar de forma temporal app.allowRendererProcessReuse a false para revertir el comportamiento antiguo. Esta marca solo será una opción hasta Electron 11 y deberías planear actualizar tus módulos nativos para que sean conscientes del contexto.
Para información más detallada vea #18397.
\nBrowserWindowLas siguientes APIs de extensión han sido marcadas como obsoletas:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()En su lugar use las APIs de session:
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Obsoleto en Electron 9\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Reemplazar con\nsession.defaultSession.loadExtension(path)\n// Obsoleto en Electron 9\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// Reemplazar con\nsession.defaultSession.removeExtension(extension_id)\n// Obsoleto en Electron 9\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Reemplazar con\nsession.defaultSession.getAllExtensions()\n<webview>.getWebContents()Esta API la cual fue marcada como obsoleta en Electron 8.0, ahora es eliminada.
\n// Eliminado en Electron 9.0\nwebview.getWebContents()\n// Reemplazar con \nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium ha eliminado el soporte para cambiar los limites del nivel de zoom del diseño y esta más allá de la capacidad de Electron el mantenerlo. La función fue marcada como obsoleta en Electron 8.x, y ha sido eliminada en Electron 9.x. Los niveles de zoom limites ahora están fijados a un mínimo de 0.25 y un máximo de 5.0, como se define aquí.
\nEn Electron 8.0, el IPC se cambió para que utilizara el algoritmo de clon estructurado, con importantes mejoras de rendimiento. To help ease the transition, the old IPC serialization algorithm was kept and used for some objects that aren't serializable with Structured Clone. In particular, DOM objects (e.g. Element, Location and DOMMatrix), Node.js objects backed by C++ classes (e.g. process.env, some members of Stream), and Electron objects backed by C++ classes (e.g. WebContents, BrowserWindow and WebFrame) are not serializable with Structured Clone. Siempre que se invocaba el algoritmo anterior, se imprimía una advertencia de desaprobación.
En Electron 9,0, se eliminó el algoritmo de serialización anterior, y enviar tales objetos no serializables ahora lanzará un error \"no se pudo clonar el objeto\".
\nshell.openItem ahora es shell.openPathLa API shell.openItem ha sido reemplazada con una API asíncrona shell.openPath. Puede ver el la propuesta y lógica original la API aquí.
El algoritmo usado para serializar los objetos enviados sobre IPC (mediante ipcRenderer.send, ipcRenderer.sendSync, WebContents.send y métodos relacionados) han sido cambiados de un algoritmo personalizado a los de V8 Structured Clone Algorithm, el mismo algoritmo usado para serializar los mensajes para postMessage. Esto conlleva una mejora en el rendimiento de 2x para mensajes grandes, pero también trae algunos cambios de comportamiento.
undefined.// Anteriormente:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => results in { value: 3 } arriving in the main process\n\n// Desde Electron 8:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => throws Error(\"() => {} could not be cloned.\")\nNaN, Infinity y -Infinity Ahora serán correctamente serializados en lugar de ser convertidos a null.null.Set, Map, Error y RegExp ahora serán correctamente serializados en lugar de ser convertidos a {}.BigInt ahora serán correctamente serializados en lugar de ser convertidos a null.nulls.Date serán transferidos como objetos Date, en lugar de ser convertidos en su representación de cadena ISO.Uint8Array, Uint16Array, Uint32Array y así sucesivamente) serán transferidas como tales, en lugar de ser convertida a Node.js Buffer.Buffer serán transferidos como Uint8Arrays. Puedes convertir un Uint8Array de nuevo a un Node.js Buffer envolviendo el ArrayBuffer subyacente:Buffer.from(value.buffer, value.byteOffset, value.byteLength)\nEnviar objetos que no son de tipos nativos de JS, tales como objetos DOM (p.ej. Element, Location, DOMMatrix),objetos Node.js (p.ej. process.env, Stream), u objetos Electron (p.ej. WebContents, BrowserWindow, WebFrame) es obsoleto. En Electron 8, estos objetos serán serializados como antes con un mensaje DeprecationWarning, pero a partir de Electron 9, enviar estos tipos de objetos lanzará un error 'could not be cloned'.
<webview>.getWebContents()Esta API está implementada usando el módulo remote, que tiene implicaciones de rendimiento y seguridad. Por lo tanto, su uso debe ser explícito.
// Obsoleto\nwebview.getWebContents()\n// Reemplazar con\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nSin embargo, es recomendado evitar el uso por completo del modulo remote.
// main\nconst { ipcMain, webContents } = require('electron')\n\nconst getGuestForWebContents = (webContentsId, contents) => {\n const guest = webContents.fromId(webContentsId)\n if (!guest) {\n throw new Error(`Invalid webContentsId: ${webContentsId}`)\n }\n if (guest.hostWebContents !== contents) {\n throw new Error('Access denied to webContents')\n }\n return guest\n}\n\nipcMain.handle('openDevTools', (event, webContentsId) => {\n const guest = getGuestForWebContents(webContentsId, event.sender)\n guest.openDevTools()\n})\n\n// renderer\nconst { ipcRenderer } = require('electron')\n\nipcRenderer.invoke('openDevTools', webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium ha eliminado el soporte para cambiar los limites del nivel de zoom del diseño y esta más allá de la capacidad de Electron el mantenerlo. La función emitirá una advertencia en Electron 8.x, y dejará de existir en Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.
\nsystemPreferencesLos siguientes eventos systemPreferences han sido marcados como obsoletos:
inverted-color-scheme-changedhigh-contrast-color-scheme-changedUse el nuevo evento updated en el módulo nativeTheme en su lugar.
// Obsoleto\nsystemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })\nsystemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })\n\n// Reemplazar con\nnativeTheme.on('updated', () => { /* ... */ })\nsystemPreferencesLos métodos siguientes de systemPreferences han quedado obsoletos:
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()En su lugar, usa las siguientes propiedades nativeTheme:
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Obsoleto\nsystemPreferences.isDarkMode()\n// Reemplazar con\nnativeTheme.shouldUseDarkColors\n\n// Obsoleto\nsystemPreferences.isInvertedColorScheme()\n// Reemplazar con\nnativeTheme.shouldUseInvertedColorScheme\n\n// Obsoleto\nsystemPreferences.isHighContrastColorScheme()\n// Reemplazar con\nnativeTheme.shouldUseHighContrastColors\nEste es el URL especificado como disturl en un archivo .npmrc o como el comando de linea --dist-url al construir los módulos nativos de nodo. Ambos serán admitidos para el futuro previsible, pero se recomienda que cambies.
Obsoleto: https://atom.io/download/electron
\nReemplazar con: https://electronjs.org/headers
\nsession.clearAuthCache() ya no acepta opcionesLa API session.clearAuthCache ya no acepta opciones de que limpiar y en su lugar incondicionalmente limpia la cache entera.
// Deprecated\nsession.clearAuthCache({ type: 'password' })\n// Replace with\nsession.clearAuthCache()\npowerMonitor.querySystemIdleState ahora es powerMonitor.getSystemIdleState// Removed in Electron 7.0\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime ahora es powerMonitor.getSystemIdleTime// Eliminada en Electron 7.0\npowerMonitor.querySystemIdleTime(callback)\n// Reemplazar con API síncrona\nconst idleTime = powerMonitor.getSystemIdleTime()\nwebFrame.setIsolatedWorldInfo reemplaza métodos separados// Removed in Electron 7.0\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Replace with\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nmarked en getBlinkMemoryInfoEsta propiedad fue removida en Chromium 77, y como tal ya no está disponible.
\nwebkitdirectory a <input type=\"file\"/> ahora lista el contenido del directorioLa propiedad webkitdirectory en las entradas de archivos HTML les permite seleccionar carpetas. Las versiones anteriores de Electron tenían una implementación incorrecta donde la entrada de event.target.files retornaba un FileList que retornaba un File correspondiente a la carpeta seleccionada.
As of Electron 7, that FileList is now list of all files contained within the folder, similarly to Chrome, Firefox, and Edge (link to MDN docs).
Como una ilustración, toma una carpeta con esta estructura:
\nfolder\n├── file1\n├── file2\n└── file3\nEn Electron <=6, esto debería retornar un FileList con un objeto File para:
path/to/folder\nEn Electron 7, esto ahora retorna un FileList con un objeto File para:
/path/to/folder/file3\n/path/to/folder/file2\n/path/to/folder/file1\nTenga en cuenta que webkitdirectory ya no expone la ruta de la carpeta seleccionada. Si requieras la ruta a la carpeta seleccionada en lugar de los contenidos de la carpeta, ver el Dialog. showOpenDialog API (Link).
Electron 5 y Electron 6 introdujeron versiones basadas en Promise de las API asíncornas existentes y desaprobaron sus contrapartes antiguas basadas en callback. En Electron 7, todas las APIs desaprobadas basadas en callback ahora están eliminadas.
\nEstas funciones ahora sólo devuelven Promises:
\napp.getFileIcon() #15742app.dock.show() #16904contentTracing.getCategories() #16583contentTracing.getTraceBufferUsage() #16600contentTracing.startRecording() #16584contentTracing.stopRecording() #16584contents.executeJavaScript() #17312cookies.flushStore() #16464cookies.get() #16464cookies.remove() #16464cookies.set() #16464debugger.sendCommand() #16861dialog.showCertificateTrustDialog() #17181inAppPurchase.getProducts() #17355inAppPurchase.purchaseProduct()#17355netLog.stopLogging() #16862session.clearAuthCache() #17259session.clearCache() #17185session.clearHostResolverCache() #17229session.clearStorageData() #17249session.getBlobData() #17303session.getCacheSize() #17185session.resolveProxy() #17222session.setProxy() #17222shell.openExternal() #16176webContents.loadFile() #15855webContents.loadURL() #15855webContents.hasServiceWorker() #16535webContents.printToPDF() #16795webContents.savePage() #16742webFrame.executeJavaScript() #17312webFrame.executeJavaScriptInIsolatedWorld() #17312webviewTag.executeJavaScript() #17312win.capturePage() #15743These functions now have two forms, synchronous and Promise-based asynchronous:
\ndialog.showMessageBox()/dialog.showMessageBoxSync() #17298dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054win.setMenu(null) ahora es win.removeMenu()// Deprecado\nwin.setMenu(null)\n// Reemplazar con \nwin.removeMenu()\nelectron.screen en el proceso renderer debe ser accedido a través de remote// Deprecado\nrequire('electron').screen\n// Reemplazar con \nrequire('electron').remote.screen\nrequire() los ing integrados de node builtins en renderizadores sandboxed no carga más de forma implícita la versión remote// Deprecado\nrequire('child_process')\n// Reemplazar con\nrequire('electron').remote.require('child_process')\n\n// Deprecado\nrequire('fs')\n// Reemplazar con\nrequire('electron').remote.require('fs')\n\n// Deprecado\nrequire('os')\n// Reemplazar con\nrequire('electron').remote.require('os')\n\n// Deprecado\nrequire('path')\n// Reemplazar con\nrequire('electron').remote.require('path')\npowerMonitor.querySystemIdleState reemplazar con powerMonitor.getSystemIdleState// Obsoleto\npowerMonitor.querySystemIdleState(threshold, callback)\n// Reemplazar con API síncrona\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime reemplazado con powerMonitor.getSystemIdleTime// Obsoleto\npowerMonitor.querySystemIdleTime(callback)\n// Reemplazar con API síncrona\nconst idleTime = powerMonitor.getSystemIdleTime()\napp.enableMixedSandbox() ya no es necesario// Obsoleto\napp.enableMixedSandbox()\nEl modo Mixed-sandbox ahora está activado por defecto.
\nTray.setHighlightModeBajo macOS Catalina nuestra implementación Tray se rompe. El sustituto nativo de Apple no soporta cambiar el comportamiento de resaltado.
\n// Deprecado\ntray.setHighlightMode(mode)\n// API sera eliminada en V7.0 sin reemplazo.\nnodeIntegration y webviewTag por defecto a false, contextIsolation por defecto a trueLos siguientes valores por defectos de opción webPreferences están obsoletos a favor de los nuevos valores por defectos listados a continuación.
| Propiedad | Valor obsoleto | El valor por defecto nuevo |
|---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration if set else true | false |
P.e. Volver a habilitar el webviewTag
\nconst w = new BrowserWindow({\n webPreferences: {\n webviewTag: true\n }\n})\nnodeIntegration en ventanas hijas abiertas a través de nativeWindowOpenChild windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is true.
Renderer process APIs webFrame.registerURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. Una nueva API, protocol.registerSchemesAsPrivileged ha sido agregada y debe ser usada para registrar esquemas personalizados con los privilegios requeridos. Se requieren esquemas personalizados para ser registrados antes de que la aplicación esté lista.
webFrame.setIsolatedWorld* reemplazado con webFrame.setIsolatedWorldInfo// Deprecated\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Replace with\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nwebFrame.setSpellCheckProvider ahora toma un callbak asíncronoEl callback spellCheck ahora es asincrónico y el parámetro autoCorrectWord ha sido removido.
// Obsoleto\nwebFrame.setSpellCheckProvider('en-US', true, {\n spellCheck: (text) => {\n return !spellchecker.isMisspelled(text)\n }\n})\n// Reemplazar con\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck: (words, callback) => {\n callback(words.filter(text => spellchecker.isMisspelled(text)))\n }\n})\nwebContents.getZoomLevel y webContents.getZoomFactor ahora son síncronowebContents.getZoomLevel y webContents.getZoomFactor ya no toman parámetros callback, en su lugar devuelven directamente sus valores numéricos.
// Deprecated\nwebContents.getZoomLevel((level) => {\n console.log(level)\n})\n// Replace with\nconst level = webContents.getZoomLevel()\nconsole.log(level)\n// Deprecated\nwebContents.getZoomFactor((factor) => {\n console.log(factor)\n})\n// Replace with\nconst factor = webContents.getZoomFactor()\nconsole.log(factor)\nLa siguiente lista incluye cambios efectuados en la API 4.0 de Electrón.
\napp.makeSingleInstance// Deprecated\napp.makeSingleInstance((argv, cwd) => {\n /* ... */\n})\n// Replace with\napp.requestSingleInstanceLock()\napp.on('second-instance', (event, argv, cwd) => {\n /* ... */\n})\napp.releaseSingleInstance// Obsoleto\napp.releaseSingleInstance()\n// Reemplazar con\napp.releaseSingleInstanceLock()\napp.getGPUInfoapp.getGPUInfo('completo')\n// Ahora se comporta lo mismo con `basic` en macOS\napp.getGPUInfo('básico')\nwin_delay_load_hookCuando se construye módulos nativos para windows, la variable win_delay_load_hook del módulo binding.gyp debe ser true (el cual es por defecto). Si este hook no esta presente, luego el módulo nativo va a fallar al cargar en Windows, con un mensaje de error como Cannot find module. Consulte la guía de módulo nativo para más infromación.
La siguiente lista incluye cambios efectuados en la API 3.0 de Electrón.
\napp// Obsoleto\napp.getAppMemoryInfo()\n// Remplazar con\napp.getAppMetrics()\n\n// Obsoleto\nconst metrics = app.getAppMetrics()\nconst { memory } = metrics[0] // Propiedad Obsoleta\nBrowserWindow// Obsoleto\nconst optionsA = { webPreferences: { blinkFeatures: '' } }\nconst windowA = new BrowserWindow(optionsA)\n// Reemplazar con\nconst optionsB = { webPreferences: { enableBlinkFeatures: '' } }\nconst windowB = new BrowserWindow(optionsB)\n\n// Obsoleto\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play_pause') {\n // do something\n }\n})\n// Reemplazar con\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play-pause') {\n // do something\n }\n})\nclipboard// Cambiar\nclipboard.readRtf()\n// Reemplazar con\nclipboard.readRTF()\n\n// Cambiar\nclipboard.writeRtf()\n// Reemplazar con\nclipboard.writeRTF()\n\n// Cambiar\nclipboard.readHtml()\n// Reemplazar con\nclipboard.readHTML()\n\n// Cambiar\nclipboard.writeHtml()\n// Reemplazar con\nclipboard.writeHTML()\ncrashReporter// Cambiar\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n autoSubmit: true\n})\n// Reemplazar con\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n uploadToServer: true\n})\nnativeImage// Obsoleto\nnativeImage.createFromBuffer(buffer, 1.0)\n// Reemplazar con\nnativeImage.createFromBuffer(buffer, {\n scaleFactor: 1.0\n})\nprocess// Obsoleto\nconst info = process.getProcessMemoryInfo()\nscreen// Obsoleto\nscreen.getMenuBarHeight()\n// Reemplazar con\nscreen.getPrimaryDisplay().workArea\nsession// Deprecado\nses.setCertificateVerifyProc((hostname, certificate, callback) => {\n callback(true)\n})\n// Reemplazar con\nses.setCertificateVerifyProc((request, callback) => {\n callback(0)\n})\nTray// Cambiar\ntray.setHighlightMode(true)\n// Reemplazar con\ntray.setHighlightMode('on')\n\n// Cambiar\ntray.setHighlightMode(false)\n// Reemplazar con\ntray.setHighlightMode('off')\nwebContents// Deprecated\nwebContents.openDevTools({ detach: true })\n// Replace with\nwebContents.openDevTools({ mode: 'detach' })\n\n// Removed\nwebContents.setSize(options)\n// There is no replacement for this API\nwebFrame// Deprecated\nwebFrame.registerURLSchemeAsSecure('app')\n// Replace with\nprotocol.registerStandardSchemes(['app'], { secure: true })\n\n// Deprecated\nwebFrame.registerURLSchemeAsPrivileged('app', { secure: true })\n// Replace with\nprotocol.registerStandardSchemes(['app'], { secure: true })\n<webview>// Eliminado\nwebview.setAttribute('disableguestresize', '')\n// No hay reemplazo para esto en la API\n\n// Eliminado\nwebview.setAttribute('guestinstance', instanceId)\n// No hay reemplazo para esto en la API\n\n// Los eventos de tecldo ya no funcionan en la etiqueta de webview\nwebview.onkeydown = () => { /* handler */ }\nwebview.onkeyup = () => { /* handler */ }\nEste es el URL especificado como disturl en un archivo .npmrc o como el comando de linea --dist-url al construir los módulos nativos de nodo.
Cambiar: https://atom.io/download/atom-shell
\nReemplazar con: https://atom.io/download/electron
\nLa siguiente lista incluye cambios efectuados en la API 2.0 de Electrón.
\nBrowserWindow// Obsoleto\nconst optionsA = { titleBarStyle: 'hidden-inset' }\nconst windowA = new BrowserWindow(optionsA)\n// Reemplazar con\nconst optionsB = { titleBarStyle: 'hiddenInset' }\nconst windowB = new BrowserWindow(optionsB)\nmenu// Removed\nmenu.popup(browserWindow, 100, 200, 2)\n// Replaced with\nmenu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })\nnativeImage// Obsoleto\nnativeImage.toPng()\n// Reemplazar con\nnativeImage.toPNG()\n\n// Obsoleto\nnativeImage.toJpeg()\n// Reemplazar con\nnativeImage.toJPEG()\nprocessVersión de procesos de Electron y Versión de procesos de Chrome Serán propiedades de solo lectura para la consistencia con otras propiedades de process.versions configuradas por Node.webContents// Obsoleto\nwebContents.setZoomLevelLimits(1, 2)\n// Reemplazar con\nwebContents.setVisualZoomLevelLimits(1, 2)\nwebFrame// Obsoleto\nwebFrame.setZoomLevelLimits(1, 2)\n// Reemplazar con\nwebFrame.setVisualZoomLevelLimits(1, 2)\n<webview>// Obsoleto\nwebview.setZoomLevelLimits(1, 2)\n// Reemplazar con\nwebview.setVisualZoomLevelLimits(1, 2)\nCada versión de Electrón incluye dos versiones de ARM idénticas con diferentes nombres de archivo, como: electron-v1.7.3-linux-arm.zip y electron-v1.7.3-linux-armv7l.zip. Se agregó el archivo con el prefijo v7l para aclarar a los usuarios qué versión de ARM soporta y desambiguar los futuros archivos de armv6l y arm64 que pueden ser producidos.
The file without the prefix is still being published to avoid breaking any setups that may be consuming it. A partir de 2.0, el archivo sin prefijo ya no será publicado.
\nPara más detalles, vea: 6986 y 7189.
", "title": "Restaurar archivos borrados", "description": "" }, "/docs/api/browser-view": { "locale": "es-ES", "slug": "browser-view", "href": "/docs/api/browser-view", "crowdinFileId": "256283", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-view.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Se puede utilizar un BrowserView para incrustar contenido web adicional dentro de un BrowserWindow. Es como una ventana hija, excepto que su posición es relativa a la de su ventana propietaria. Se puede considerar como una alternativa al tag webview.
\n\nCrear y controlar vistas.
\n
Proceso: principal</0>
\n/// In the main process.\nconst { BrowserView, BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nconst view = new BrowserView()\nwin.setBrowserView(view)\nview.setBounds({ x: 0, y: 0, width: 300, height: 300 })\nview.webContents.loadURL('https://electronjs.org')\nnew BrowserView([options]) Experimentaloptions Object (opcional)webPreferences Object (opcional) - Vea BrowserWindow.Los objetos creados con new BrowserView tienen las siguientes propiedades:
view.webContents ExperimentalUn objeto WebContents, que pertenece a esta vista.
Los objetos creados con new BrowserView tiene los siguientes métodos de instancia:
view.setAutoResize(options) Experimentaloptions Objectwidth Boolean (optional) - If true, the view's width will grow and shrink together with the window. false por defecto.height Boolean (optional) - If true, the view's height will grow and shrink together with the window. false por defecto.horizontal Boolean (optional) - If true, the view's x position and width will grow and shrink proportionally with the window. false por defecto.vertical Boolean (optional) - If true, the view's y position and height will grow and shrink proportionally with the window. false por defecto.view.setBounds(bounds) Experimentalbounds RectangleRedimensiona y mueve la vista a los limites proporcionados en relación a la ventana.
\nview.getBounds() ExperimentalDevuelve Rectangle
Los límites bounds de esta instancia de BrowserView como un Object.
view.setBackgroundColor(color) Experimentalcolor String - Color in #aarrggbb or #argb form. The alpha channel is optional.\n\nCrea y controla las ventanas del navegador.
\n
Proceso: principal</0>
\n/// In the main process.\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\n// Load a remote URL\nwin.loadURL('https://github.com')\n\n// Or load a local HTML file\nwin.loadFile('index.html')\nPara crear una ventana sin usar chrome, o una vertana transparente de cualquier forma, puede usar la API Frameless Window.
\nCuando 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.
\nready-to-showMientras 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')\nconst win = new BrowserWindow({ show: false })\nwin.once('ready-to-show', () => {\n win.show()\n})\nEste 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
backgroundColorPara 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')\n\nconst win = new BrowserWindow({ backgroundColor: '#2e2c29' })\nwin.loadURL('https://github.com')\nTenga en cuenta que incluso para aplicaciones que utilizan el evento ready-to-show, aún se recomienda establecer backgroundColor para que la aplicación parezca más nativa.
Al usar la opción parent, se pueden crean ventanas secundarias:
const { BrowserWindow } = require('electron')\n\nconst top = new BrowserWindow()\nconst child = new BrowserWindow({ parent: top })\nchild.show()\ntop.show()\nLa ventana child se mostrará siempre por encima de la ventana top.
Una ventana modal es una ventana secundaria que deshabilita la ventana principal, para crear una ventana modal, hay que establecer ambas opciones parent y modal:
const { BrowserWindow } = require('electron')\n\nconst child = new BrowserWindow({ parent: top, modal: true, show: false })\nchild.loadURL('https://github.com')\nchild.once('ready-to-show', () => {\n child.show()\n})\nLa Page Visibility API funciona de la siguiente manera:
\nhidden. En otras plataformas, el estado de visibilidad será hidden solo si la ventana esta minimizada o explícitamente oculta con win.hide().BrowserWindow con show: false, el estado de visibilidad inicial será visible a pesar de que la ventana esté oculta realmente.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.
dialog.\n\nCrea y controla las ventanas del navegador.
\n
Proceso: principal</0>
\nBrowserWindow es un EventEmitter.
Crea una nueva BrowserWindow con propiedades nativas como las establecidas por las options.
new BrowserWindow([options])options Object (opcional)width Integer (opcional) - El ancho de la ventana en pixeles. Por defecto es 800.height Integer (opcional) - La altura de la ventana en pixeles. Por defecto es 600.x Integer (opcional) - (required si y es usado) Desplazamiento a la izquierda de la ventana de la pantalla. Por defecto es centrar en la ventana.y Integer (opcional) - (required si x es usado) Desplazamiento superior de la ventana desde la pantalla. Por defecto es centrar en la ventana.useContentSize Boolean (opcional) - width y height se utilizan como el tamaño de la página web. Esto significa que el tamaño actual de la ventana incluirá el tamaño del marco de la ventana y será un poco más grande. Por defecto es false.center Boolean (opcional) - Muestra la ventana en el centro de la pantalla.minWidth Integer (opcional) - Ancho mínimo de a ventana. Por defecto es 0.minHeight Integer (opcional) - Altura mínima de la ventana. Por defecto es 0.maxWidth Integer (opcional) - Ancho máximo de la ventana. Por defecto no hay limite.maxHeight Integer (opcional) - Altura máxima de la ventana. Por defecto no hay limite.resizable Boolean (opcional) - Si la ventana puede ser redimencionada. Por defecto es true.movable Boolean (opcional) - Si la ventana puede ser movida. Esto no está implementado en Linux. Por defecto es true.minimizable Boolean (opcional) - Si la ventana puede ser minimizada. Esto no está implementado en Linux. Por defecto es true.maximizable Boolean (opcional) - Si la ventana puede ser maximizada. Esto no está implementado en Linux. Por defecto es true.closable Boolean (opcional) - Si la ventana puede ser cerrada. Esto no está implementado en Linux. Por defecto es true.focusable Boolean (opcional) - si la ventana se puede enfocar. Por defecto es true. En Windows, la configuración focusable: false también quiere decir que skipTaskbar: true. En Linux, la configuración focusable: false hace que la ventana deje de interactuar con wm, así la ventana siempre se mantendrá en la parte superior en todas las áreas de trabajo.alwaysOnTop Boolean (opcional) - Si la ventana debería permanecer siempre por ensima de otras ventanas. Por defecto es false.fullscreen Boolean(opcional) - si la ventana debería mostrarse en pantalla completa. Cuando se establece explícitamente false el botón de la pantalla completa estará oculta o deshabilitada en macOS. Por defecto es false.fullscreenable Boolean (opcional) - si la ventana puede ponerse el modo pantalla completa. En macOS, también si el botón maximizar o acercarse debería alternar el modo pantalla completa o maximizar la ventana. Por defecto es true.simpleFullscreen Boolean (opcional) - Usa pantalla completa pre-Lion en macOS. Por defecto es false.skipTaskbar Boolean (opcional) - Si mostrar la ventana en la barra de tarea. Por defecto es false.kiosk Boolean (opcional) - Si la ventana está en modo kiosk. Por defecto es false.title String (opcional) - Titulo de la ventana por defecto. Por defecto es \"Electron\". Si la etiqueta HTML <title> es definida en el archivo HTML cargado por loadURL(), esta propiedad será ignorada.icon (NativeImage | String) (opcional) - El icono de la ventana. En Windows, se recomienda usar iconos ICO para obtener mejores efectos visuales. También se se puede dejar sin definir, de esta manera se utilizará el icono del ejecutable.show Boolean (opcional) - Si la ventana debería ser mostrada cuando se crea. Por defecto es true.paintWhenInitiallyHidden Boolean (opcional) - Si el renderer debería estar activo cuando show es false y recién ha sido creado. Para que document.visibilityState funcione correctamente en la primera carga con show: false debería establecer esto a false. Estableciendo esto a false causará que el evento ready-to-show no se dispare. Por defecto es true.frame Boolean (opcional) - Especifica false para crear un Frameless Window. Por defecto es true.parent BrowserWindow (opcional) - Especifica la ventana padre. Por defecto es null.modal Boolean (opcional) - Si es una ventana modal. Esto sólo funciona cuando la ventana es una ventana hija. Por defecto es false.acceptFirstMouse Boolean (optional) - Whether clicking an inactive window will also click through to the web contents. Default is false on macOS. This option is not configurable on other platforms.disableAutoHideCursor Boolean (opcional) - Si ocultar el cursor cuando se está escriniendo. Por defecto es false.autoHideMenuBar Boolean (opcional) - Auto ocultar la barra de menú a menos que la tecla Alt este presionada. Por defecto es false.enableLargerThanScreen Boolean (opcional) - Permite que la ventana se redimensione mayor que la pantalla. Solo relevante para macOS, ya que los otros sistemas operativos permiten ventanas más grandes que la pantalla por defecto. Por defecto es false.backgroundColor String (opcional) - El color de fondo de la Ventana como un valor hexadecimal, como #66CD00 o #FFF o #80FFFFFF (alfa en formato #AARRGGBB es soportado si transparent es establecido a true). Por defecto es #FFF (blanco).hasShadow Boolean (opcional) - Si la ventana debería tener una sombra. Por defecto es true.opacity Number (opcional) - Establece la opacidad inicial de la ventana, entre 0.0 (totalmente transparente) y 1.0 (totalmente opaco). Esto sólo está implementado en Windows y macOS.darkTheme Boolean (opcional) - Fuerza el uso del tema obscuro en la ventana, solo funciona en algunos entornos de escritorio GTK+3. Por defecto es false.transparent Boolean (opcional) - Hace la ventana tranparente. Por defecto es false. En Windows, no funciona a menos que la ventana sea sin marco.type String (opcional) - El tipo de ventana, por defecto es una ventana normal. Vea más sobre esto a continuación.visualEffectState String (opcional) - Especifica como la apariencia del material debe reflejar el estado de actividad de la ventana en macOS. Must be used with the vibrancy property. Los valores posibles son:followWindow - The backdrop should automatically appear active when the window is active, and inactive when it is not. Este es el valor predeterminado.active - The backdrop should always appear active.inactive - The backdrop should always appear inactive.titleBarStyle String (optional) macOS Windows - The style of window title bar. Por defecto es default. Los valores posibles son:default - Results in the standard title bar for macOS or Windows respectively.hidden - Results in a hidden title bar and a full size content window. On macOS, the window still has the standard window controls (“traffic lights”) in the top left. On Windows, when combined with titleBarOverlay: true it will activate the Window Controls Overlay (see titleBarOverlay for more information), otherwise no window controls will be shown.hiddenInset - Only on macOS, results in a hidden title bar with an alternative look where the traffic light buttons are slightly more inset from the window edge.customButtonsOnHover - Only on macOS, results in a hidden title bar and a full size content window, the traffic light buttons will display when being hovered over in the top left of the window. Note: Esta opción es experimental actualmente.trafficLightPosition Point (opcional) - Establece una posición para los botones del semáforo en ventanas sin marco.roundedCorners Boolean (opcional) - Si la ventana sin marco debería tener o no esquinas redondeadas macOS. Por defecto es true.fullscreenWindowTitle Boolean (opcional) Obsoleto - Muestra el título en la barra de título en el modo de pantalla completa en macOS para hiddenInset titleBarStyle. Por defecto es false.thickFrame Boolean (opcional) - Utilice el estilo WS_THICKFRAME para ventanas sin marco en Windows, la cual agrega un marco de ventana estándar. Configurarlo en false eliminará la sombra de la ventana y las animaciones de la ventana. Por defecto es true.vibrancy Cadena (opcional) - Añade un tipo de efecto de vibración a la ventana. Funciona solamente en macOS. Puede ser appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, o under-page. Por favor tenga en cuenta que appearance-based, light, dark, medium-light, and ultra-dark están obsoletas y han sido eliminadas en macOS Catalina (10.15).zoomToPageWidth Boolean (optional) - Controls the behavior on macOS when option-clicking the green stoplight button on the toolbar or by clicking the Window > Zoom menu item. Si es true, la ventana crecerá al ancho recomendado de la página web cuando se haga zoom. false hará que haga zoom hasta el ancho de la pantalla. Esto también afectará el comportamiento cuando se llama directamente maximize(). Por defecto es false.tabbingIdentifier String (opcional) - Crea una pestaña del nombre del grupo. Permite abrir la ventana como una pestaña nativa en macOC 10.12+. Las ventanas con el mismo identificador de pestaña se agruparán juntos. Esto también añade un nuevo botón de pestañas nativo a la barra de pestañas de la ventana y permite que la app y la ventana reciban el evento new-window-for-tab.webPreferences Object (optional) - Settings of web page's features.devTools Boolean (opcional) - Si se habilita el DevTools. Si se configura a false, no puede utilizarse BrowserWindow.webContents.openDevTools() para abrir DevTools. Por defecto es true.nodeIntegration Boolean (optional) - Whether node integration is enabled. Por defecto es false.nodeIntegrationInWorker Boolean (opcional) - Si la integración de nodos está habilitada en los trabajadores de la web. Por defecto es false. Se pueden encontrar más detalles en Multithreading.nodeIntegrationInSubFrames Boolean (opcional) - Opcion experimental para habilitar soporte Node.js en sub-frames como iframes y ventas hijos. Todos tus preloads cargarán por cada iframe, puedes usar process.isMainFrame para determinar si estás en el marco principal o no.preload String (opcional) - Especifica un script que será cargado antes del otros scripts en la página. Este script siempre tendrá acceso al nodo APIs sin importar si la integración de nodos esté activada o no. El valor debería ser la ruta del archivo absoluto al script. Cuando la integración de nodos esta desactivada, la precarga del script puede reintroducir de vuelta al ámbito global los símbolos globales del Nodo. Ver ejemplo aquí.sandbox Boolean (opcional) - Si se configura, protegerá al renderizador asociado a la ventana, haciéndolo compatible con el sandbox de Chromium OS-level, deshabilitando el motor Node.js. Esto no es lo mismo que la opción de nodeIntegration y las APIs disponibles para el script de precarga son más limitadas. Leer más sobre la opción aquí.session Session (opcional) - Configura la sesión usada por la página. En lugar de pasar directamente el objeto de la sesión, se puede optar por utilizar la opción de partition, la cual acepta una cadena de partición. Cuando se proporcionen session y partition, se preferirá session. Default es la sesión por defecto.partition Cadena (opcional) - Configura la sesión utilizada por la página según la cadena de partición de la sesión. Si la partition empieza con persist:, la página utilizará una sesión persistente disponible para todas las páginas en la partición con la misma partition. Si no está el prefijo persist:, la página usara una sesión de la memoria interna. Al asignar la misma partition, las páginas múltiples pueden compartir la misma sesión. Default es la sesión por defecto.zoomFactor Number (optional) - The default zoom factor of the page, 3.0 represents 300%. Por defecto es 1.0.javascript Boolean (optional) - Enables JavaScript support. Por defecto es true.webSecurity Boolean (opcional) - Cuando es false, desactivará la política de same-origin (por lo general se utiliza cuando la gente prueba los sitios web), y configurará allowRunningInsecureContenta true en caso de que estas opciones no hayan sido configuradas por el usuario. Por defecto es true.allowRunningInsecureContent Boolean (optional) - Allow an https page to run JavaScript, CSS or plugins from http URLs. Por defecto es false.images Boolean (optional) - Enables image support. Por defecto es true.imageAnimationPolicy String (opcional) - Especifica cómo correr la animaciones de la imagen (P.e. GIFs). Puede ser animate, animateOnce o noAnimation. Predeterminadamente, es animate.textAreasAreResizable Boolean (optional) - Make TextArea elements resizable. Default is true.webgl Boolean (optional) - Enables WebGL support. Por defecto es true.plugins Boolean (optional) - Whether plugins should be enabled. Por defecto es false.experimentalFeatures Boolean (optional) - Enables Chromium's experimental features. Por defecto es false.scrollBounce Boolean (optional) - Enables scroll bounce (rubber banding) effect on macOS. Por defecto es false.enableBlinkFeatures String (opcional) - Una lista de cadenas de características separadas por ,, para habilitar como CSSVariables,KeyboardEventKey. La lista completa de cadenas distintivas soportadas pueden encontrarse en el archivo RuntimeEnabledFeatures.json5.disableblinkFeatures String (opcional) - Una lista de cadenas distintivas separadas por ,,como CSSVariables,KeyboardEventKey para deshabilitar. La lista completa de cadenas características soportadas puede ser encontrada en el archivo RuntimeEnabledFeatures.json5.defaultFontFamily Object (optional) - Sets the default font for the font-family.standard String (opcional) - Por defecto es Times New Roman.serif String (opcional) - Por defecto es Times New Roman.sansSerif String (opcional) - Por defecto es Arial.monospace String (opcional) - Por defecto es Courier New.cursive String (opcional) - Por defecto es Script.fantasy String (opcional) - Por defecto es Impact.defaultFontSize Integer (opcional) - Por defecto es 16.defaultMonospaceFontSize Integer (opcional) - Por defecto es 13.minimumFontSize Integer (opcional) - Por defecto es 0.defaultEncoding String (opcional) - Por defecto es ISO-8859-1.backgroundThrottling Boolean (opcional) - Para acelerar animaciones y temporizadores cuando la página esta al fondo. Esto también afecta a Page Visibility API. Por defecto es true.offscreen Boolean(optional) - Para habilitar el renderizado offscreen para el navegador de la ventana. Por defecto es false. Para más detalles, ver offscreen rendering tutorial.contextIsolation Boolean(opcional) - Para ejecutar las APIs de Electron y el script especificado preload en un contexto JavaScript independiente. Por defecto es true. The context that the preload script runs in will only have access to its own dedicated document and window globals, as well as its own set of JavaScript builtins (Array, Object, JSON, etc.), which are all invisible to the loaded content. The Electron API will only be available in the preload script and not the loaded page. This option should be used when loading potentially untrusted remote content to ensure the loaded content cannot tamper with the preload script and any Electron APIs being used. Esta opción utiliza la misa técnica usada por Chrome Content Scripts. You can access this context in the dev tools by selecting the 'Electron Isolated Context' entry in the combo box at the top of the Console tab.nativeWindowOpen Boolean (opcional) - Si se usa el nativo window.open(). Por defecto es true. Las ventanas hijas siempre tienen la integración con node desabilidata a menos que nodeIntegrationInSubFrames es true.webviewTag Boolean (opcional) - Si se habilita o no el <webview> tag. Por defecto es false. Nota: El script preload configurado para el <webview>tendrá la integración de nodos habilitada cuando se ejecuta por lo que hay que asegurarse que el contenido remoto o posiblemente dañino no sea capaz de crear una etiqueta de <webview>con un script preload posiblemente malicioso. Puede utilizarse el evento will-attach-webview en webContents para quitar el script preload y validar o alterar la configuración inicial de <webview>.additionalArguments String - A list of strings that will be appended to process.argv in the renderer process of this app. Useful for passing small bits of data down to renderer process preload scripts.safeDialogs Boolean (optional) - Whether to enable browser style consecutive dialog protection. Por defecto es false.safeDialogsMessage String (opcional) - El mensaje a mostrar cuando la protección de diálogo consecutivo es lanzada. So no se define el mensaje por defecto sería utilizado, note que actualmente el mensaje por defecto esta en Inglés y no localizado.disableDialogs Boolean (optional) - Whether to disable dialogs completely. Overrides safeDialogs. Por defecto es false.navigateOnDragDrop Boolean (optional) - Whether dragging and dropping a file or link onto the page causes a navigation. Por defecto es false.autoplayPolicy String (opcional) - Política de autoplay para aplicar al contenido en la ventana, puede ser no-user-gesture-required, user-gesture-required, document-user-activation-required. Por defecto a no-user-gesture-required.disableHtmlFullscreenWindowResize Boolean (optional) - Whether to prevent the window from resizing when entering HTML Fullscreen. Default is false.accessibleTitle String (optional) - An alternative title string provided only to accessibility tools such as screen readers. Esta cadena no es directamente visible para los usuarios.spellcheck Boolean (optional) - Whether to enable the builtin spellchecker. Por defecto es true.enableWebSQL Boolean (optional) - Whether to enable the WebSQL api. Por defecto es true.v8CacheOptions String (optional) - Enforces the v8 code caching policy used by blink. Accepted values arenone - Disables code cachingcode - Heuristic based code cachingbypassHeatCheck - Bypass code caching heuristics but with lazy compilationbypassHeatCheckAndEagerCompile - Same as above except compilation is eager. Default policy is code.enablePreferredSizeMode Boolean (optional) - Whether to enable preferred size mode. The preferred size is the minimum size needed to contain the layout of the document—without requiring scrolling. Enabling this will cause the preferred-size-changed event to be emitted on the WebContents when the preferred size changes. Por defecto es false.titleBarOverlay Object | Boolean (opcional) - Cuando se usa una ventana sin marco en conjunción con win.setWindowButtonVisibility(true) en macOS o usando titleBarStyle para que los controles de la ventana estándar (\"traffic lights\" en macOS) estén visibles, esta propiedad activa el Window Controls Overlay JavaScript APIs y CSS Environment Variables. Specifying true will result in an overlay with default system colors. Por defecto es false.color String (optional) Windows - The CSS color of the Window Controls Overlay when enabled. Default is the system color.symbolColor String (optional) Windows - The CSS color of the symbols on the Window Controls Overlay when enabled. Default is the system color.Cuando se configura el tamaño máximo o mínimo de la ventana con minWidth/maxWidth/ minHeight/maxHeight, solo limita a los usuarios. No impide pasar de un tamaño que no sigue las restricciones de tamaño asetBounds/setSize o al constructor de BrowserWindow.
Los posibles valores y comportamientos de la opción type son dependientes de la plataforma. Los valores posibles son:
desktop, dock, toolbar, splash, notification.desktop, textured.textured añade una aspecto de tono metálico (NSTexturedBackgroundWindowMask).desktop coloca la ventana en el nivel de la ventana de fondo de escritorio (kCGDesktopWindowLevel - 1). Tenga en cuenta que la ventana de escritorio no recibirá enfoque alguno, ni eventos del ratón o del teclado, pero se puede utilizar globalShortcut para recibir input con moderación.toolbar.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.
\nDevuelve:
\neventtitle StringexplicitSet BoolenAparece 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.
Devuelve:
\neventAparece 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) => {\n console.log('I do not want to be closed')\n\n // Unlike usual browsers that a message box will be prompted to users, returning\n // a non-void value will silently cancel the close.\n // It is recommended to use the dialog API to let the user confirm closing the\n // application.\n e.returnValue = false // equivalente a `return false` pero no es recomendado\n}\nNota: 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.
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.
\nAparece 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.
\nAparece cuando la página web deja de responder.
\nAparece cuando la página web que no responde vuelve a responder.
\nAparece cuando la ventana pierde el enfoque.
\nAparece cuando la ventana recupera el enfoque.
\nAparece cuando se muestra la ventana.
\nAparece cuando se oculta la ventana.
\nAparece cuando la página web ha sido renderizada (mientras no está siendo mostrada) y la ventana puede mostrarse sin un visual flash.
\nPor 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
Aparece cuando se maximiza la ventana.
\nAparece cuando la ventana sale de un estado maximizado.
\nAparece cuando se minimiza la ventana.
\nAparece cuando se restaura la ventana de un estado minimizado.
\nDevuelve:
\neventnewBounds 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 ser bottom, left, right, top-left, top-right, bottom-left o bottom-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:
bottom, top, left, right, top-left, top-right, bottom-left, bottom-right.bottom y right.bottom es usado para denotar un cambio de tamaño vertical.right es usado para denotar un cambio de tamaño horizontal.Emitido después que la ventana se haya redimensionada.
\nEmitted once when the window has finished being resized.
\nThis 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.
Devuelve:
\neventnewBounds 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.
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.
Aparece cuando la ventana se mueve a una nueva posición.
\nAparece solo una vez cuando la ventana se mueve a una nueva posición.
\nNote: En macOS este evento es un alias de move.
Aparece cuando la ventana entra en un estado pantalla completa.
\nAparece cuando la ventana sale del estado pantalla completa.
\nAparece cuando la ventana entra en un estado pantalla completa activado por la API HTML.
\nAparece cuando la ventana sale de un estado pantalla completa activado por la API HTML.
\nDevuelve:
\neventisAlwaysOnTop BooleanEmitido cuando la ventana es configurada o no configurada para mostrarse siempre en la parte superior de las otras ventanas.
\nDevuelve:
\neventcommand CadenaAparece 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.
\nLos 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')\nconst win = new BrowserWindow()\nwin.on('app-command', (e, cmd) => {\n // Navigate the window back when the user hits their mouse back button\n if (cmd === 'browser-backward' && win.webContents.canGoBack()) {\n win.webContents.goBack()\n }\n})\nLos siguientes comandos de aplicación están explícitamente soportados en Linux:
\nbrowser-backwardbrowser-forwardAparece cuando la fase del evento de la rueda de desplazamiento ha empezado.
\nAparece cuando la fase del evento de la rueda de desplazamiento ha concluido.
\nAparece cuando la fase del evento de la rueda desplazamiento ha alcanzado el borde del elemento.
\nDevuelve:
\neventdirection StringEmitted 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'.
Devuelve:
\neventrotation FloatEmitido en el gesto de rotación del trackpad. Emitido continuamente hasta que el gesto de rotación se termine. El valor de rotation en cada emisión es el angulo en grado rotado desde la última emisión. El último evento emitido sobra un gesto de rotación siempre será el valor de 0. Los valores de rotación en sentido contrario a las agujas del reloj son positivos, mientras que los del sentido de las agujas del reloj son Negativo.
Aparece cuando la ventana abre una hoja.
\nAparece cuando la ventana cierra una hoja.
\nAparece cuando se hace clic al botón de nueva pestaña nativa.
\nDevuelve:
\neventpoint Point - Las coordenadas de la pantalla del menú contextual que fue activado enEmitido 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.
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 WebContentsDevuelve BrowserWindow | null - La ventana a que pertenece el webContents indicado o null si los contenidos no son propiedad de una ventana.
BrowserWindow.fromBrowserView(browserView)browserView BrowserViewDevuelve 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 ÍntegroDevuelve BrowserWindow | null -La ventana con la id especificada.
Los objetos creados con new BrowserWindow tienen las siguientes propiedades:
const { BrowserWindow } = require('electron')\n// In this example `win` is our instance\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('https://github.com')\nwin.webContents SoloLecturaUn 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 SoloLecturaUna 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.autoHideMenuBarUna 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 el menu bar ya está visible, estableciendo esta propiedad a true no lo ocultará inmediatamente.
win.simpleFullScreenA Boolean property that determines whether the window is in simple (pre-Lion) fullscreen mode.
win.fullScreenA Boolean property that determines whether the window is in fullscreen mode.
win.focusable Windows macOSUna propiedad Boolean que determina si la ventana es enfocable.
win.visibleOnAllWorkspacesA Boolean property that determines whether the window is visible on all workspaces.
Note: Always returns false on Windows.
\nwin.shadowA Boolean property that determines whether the window has a shadow.
win.menuBarVisible Windows LinuxA 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.kioskA Boolean property that determines whether the window is in kiosk mode.
win.documentEdited macOSA 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 macOSA 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.titleA 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.
\nwin.minimizableUna 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.maximizableUna 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.fullScreenableUna propiedad Boolean que determina si los botones de la ventana maximizar/ampliar alterna el modo de pantalla completa o maximiza la ventana.
win.resizableUna propiedad Boolean que determina si la ventana puede ser redimencionada manualmente por el usuario.
win.closableUna 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.movableUna 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 macOSUna 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 })\n\nconst template = [\n {\n role: 'windowmenu'\n }\n]\n\nwin.excludedFromShownWindowsMenu = true\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nwin.accessibleTitleA 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.
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.
\nwin.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.
\nwin.focus()Enfoca la ventana.
\nwin.blur()Elimina el enfoque de la ventana.
\nwin.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.
\nwin.showInactive()Muestra la ventana pero no la enfoca.
\nwin.hide()Oculta la ventana.
\nwin.isVisible()Devuelve Boolean - Si la ventana es visible o no al usuario.
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.
\nwin.unmaximize()Sale del estado maximizado de la ventana.
\nwin.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.
\nwin.restore()Restaura la ventana desde un estado minimizado a su estado previo.
\nwin.isMinimized()Devuelve Boolean - Si la ventana está minimizada o no.
win.setFullScreen(flag)flag BooleanEstablece si la ventana debe estar o no en modo pantalla completa.
\nwin.isFullScreen()Devuelve Boolean - Si la ventana está o no en pantalla completa.
win.setSimpleFullScreen(flag) macOSflag BooleanEntra o sale del modo simple de pantalla completa.
\nSimple fullscreen mode emulates the native fullscreen behavior found in versions of macOS prior to Lion (10.7).
\nwin.isSimpleFullScreen() macOSDevuelve 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.
\nConsidere 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. In order to maintain a 16:9 aspect ratio (standard aspect ratio for HD @1920x1080) within the player itself we would call this function with arguments of 16/9 and\n{ 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.
\nLa relación de aspecto no se respeta cuando la ventana se redimensiona programáticamente con APIs como win.setSize.
win.setBackgroundColor(backgroundColor)backgroundColor String - Color de fondo de la ventana como un valor hexadecimal, como #66CD00 o #FFF o #80FFFFFF (alpha es soportada si transparent es true). Por defecto es #FFF (blanco).Establece el color de fondo de la ventana. Ver Setting backgroundColor.
win.previewFile(path[, displayName]) macOSpath 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 es path.Utiliza Quick Look para previsualizar un archivo de una ruta determinada.
\nwin.closeFilePreview() macOSCierra el panel actual de Quick Look.
\nwin.setBounds(bounds[, animate])bounds Partial<Rectangle>animate Boolean (opcional) macOSRedimensiona y mueve la ventana a los límites proporcionados. Cualquier propiedad que no se proporcione tendrá sus valores actuales por defecto.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\n// set all bounds properties\nwin.setBounds({ x: 440, y: 225, width: 800, height: 600 })\n\n// set a single bounds property\nwin.setBounds({ width: 100 })\n\n// { x: 440, y: 225, width: 100, height: 600 }\nconsole.log(win.getBounds())\nwin.getBounds()Retorna Rectangle - El bounds de la ventana como Object.
win.getBackgroundColor()Returns String - Gets the background color of the window. Ver Setting backgroundColor.
win.setContentBounds(bounds[, animate])bounds Rectangleanimate Boolean (opcional) macOSRedimensiona y mueve el área del cliente de la ventana (por ejemplo, la página web) hasta los límites proporcionados.
\nwin.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 BooleanHabilita o deshabilita la ventana.
\nwin.isEnabled()Devuelce Boolean -si la ventana está activada.
win.setSize(width, height[, animate])width Integeralto Integeranimate Boolean (opcional) macOSCambia 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 Boolean (opcional) macOSCambia 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 IntegerEstablece el tamaño mínimo de la ventana a widthy height.
win.getMinimumSize()Devuelve Integer[] - Contiene la anchura y altura mínima de la ventana.
win.setMaximumSize(width, height)width Integeralto IntegerEstablece el tamaño máximo de la ventana a widthy height.
win.getMaximumSize()Devuelve Integer[] - Contiene la anchura y altura máxima de la ventana.
win.setResizable(resizable)resizable BooleanSets whether the window can be manually resized by the user.
\nwin.isResizable()Returns Boolean - Whether the window can be manually resized by the user.
win.setMovable(movable) macOS Windowsmovable BooleanSets whether the window can be moved by user. En Linux no hace nada.
\nwin.isMovable() macOS WindowsDevuelve Boolean - Si la ventana puede ser movida por el usuario.
En Linux siempre devuelve true.
win.setMinimizable(minimizable) macOS Windowsminimizable BooleanSets whether the window can be manually minimized by user. En Linux no hace nada.
\nwin.isMinimizable() macOS WindowsReturns Boolean - Whether the window can be manually minimized by the user.
En Linux siempre devuelve true.
win.setMaximizable(maximizable) macOS Windowsmaximizable BooleanSets whether the window can be manually maximized by user. En Linux no hace nada.
\nwin.isMaximizable() macOS WindowsDevuelve Boolean - Si la ventana puede ser maximizada manualmente por el usuario.
En Linux siempre devuelve true.
win.setFullScreenable(fullscreenable)fullscreenable BooleanSets whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
\nwin.isFullScreenable()Returns Boolean - Whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
win.setClosable(closable) macOS Windowsclosable BooleanSets whether the window can be manually closed by user. En Linux no hace nada.
\nwin.isClosable() macOS WindowsDevuelve Boolean - Si la ventana puede ser o no cerrada manualmente por el usuario.
En Linux siempre devuelve true.
win.setAlwaysOnTop(flag[, level][, relativeLevel])flag Booleanlevel String (opcional) macOS Windows - Valores incluyen normal, floating, torn-off-menu, modal-panel, main-menu, status, pop-up-menu, screen-saver, y dockfloating cuando flag es true. El level se restablece a normal cuando la bandera es false. Tenga en cuenta que desde floating a status incluido, la venta está colocada debajo del Dock en macOS y debajo de la barra de tarea en Windows. Desde pop-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 al level determinado. Por defecto es 0. Tenga en cuenta que Apple desalienta establecer niveles superiores a 1 sobre screen-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.
\nwin.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
\nwin.center()Mueve la ventana al centro de la pantalla.
\nwin.setPosition(x, y[, animate])x Integery Integeranimate Boolean (opcional) macOSMueve la ventana a x y y.
win.getPosition()Devuelve Integer[] - Contiene la posición actual de la ventana.
win.setTitle(title)title StringCambia 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.
\nwin.setSheetOffset(offsetY[, offsetX]) macOSoffsetY 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:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nconst toolbarRect = document.getElementById('toolbar').getBoundingClientRect()\nwin.setSheetOffset(toolbarRect.height)\nwin.flashFrame(flag)flag BooleanEmpieza y deja de hacer parpadear la ventana para atraer la atención del usuario.
\nwin.setSkipTaskbar(skip)skip BooleanoHace que la ventana no se muestre en la barra de tareas.
\nwin.setKiosk(flag)flag BooleanEntra / sale del modo Kiosko.
\nwin.isKiosk()Devuelve Boolean - Si la ventana está o no en modo kiosco.
win.isTabletMode() WindowsReturns Boolean - Whether the window is in Windows 10 tablet mode.
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.
\nThis API returns whether the window is in tablet mode, and the resize event can be be used to listen to changes to tablet mode.
win.getMediaSourceId()Returns String - Window id in the format of DesktopCapturerSource's id. 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) Windowsmessage Integercallback FunciónwParam any - El wParam proveído al WndProclParam any - El lParam proveído al WndProcEngancha una ventana de mensaje. The callback is called when the message is received in the WndProc.
win.isWindowMessageHooked(message) Windowsmessage IntegerDevuelve Boolean - true o false dependiendo de si el mensaje esta anclado o no.
win.unhookWindowMessage(message) Windowsmessage IntegerDesancla el mensaje de la ventana.
\nwin.unhookAllWindowMessages() WindowsDesancla todos los mensajes de la ventana.
\nwin.setRepresentedFilename(filename) macOSfilename CadenaEstablece 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.
\nwin.getRepresentedFilename() macOSDevuelve String - El nombre de la ruta del archivo que la ventana representa.
win.setDocumentEdited(edited) macOSedited BooleanEspecifica 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() macOSDevuelve Boolean - Si se ha editado el documento de la ventana.
win.focusOnWebView()win.blurWebView()win.capturePage([rect])rect Rectangle (opcional) - Los límites para capturarDevuelve Promise<NativeImage> - Resuelve con el un NativeImage
Captura una foto instantánea de la página dentro de rect. Omitiendo rect capturará toda la página visible. Si la página no es visible, rect puede estar vacía.
win.loadURL(url[, options])url Stringoptions Object (opcional)httpReferrer (String | Referrer) (opcional) - Una URL de referencia HTTP.userAgent Cadena (opcional) - Un agente de usuario originando el pedido.extraHeaders Cadena (opcional) - Encabezados extras separados por \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (opcional) - URL base (con separador de ruta final) para archivos a ser cargados por el data URL. Esto solo es necesario si la url especificada es una data URL y necesita cargar otros archivos.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 url = require('url').format({\n protocol: 'file',\n slashes: true,\n pathname: require('path').join(__dirname, 'index.html')\n})\n\nwin.loadURL(url)\nSe puede cargar un URL utilizando la solicitud POST con los datos codificados de URL haciendo lo siguiente:
win.loadURL('http://localhost:8000/post', {\n postData: [{\n type: 'rawData',\n bytes: Buffer.from('hello=world')\n }],\n extraHeaders: 'Content-Type: application/x-www-form-urlencoded'\n})\nwin.loadFile(filePath[, options])filePath Stringoptions Object (opcional)query Record<String, String> (opcional) - Pasado a url.format().search String (opcional) - Pasado a url.format().hash String (opcional) - Pasado a url.format().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 Windowsmenu Menu | nullEstablece el menu como el menu bar de la ventana.
win.removeMenu() Linux WindowsEliminar la barra de menú de la ventana.
\nwin.setProgressBar(progress[, options])progress Doubleoptions Object (opcional)mode String Windows - Mode for the progress bar. Puede ser none, normal, indeterminate, error o paused.Establece el valor del progreso en el progress bar. Rango valido es [0, 1.0].
\nElimina la barra de progreso cuando el progreso es < 0; cambia a modo indeterminado cuando el progreso es >1.
\nEn 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, será asumido {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) Windowsoverlay NativeImage | null - el icono a mostrar en la parte inferior derecha del icono de la barra de tareas. Si este parámetro es null, se borra la superposicióndescription Cadena- una descripción que se facilitará a los lectores de la pantalla AccessibilityEstablece 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.
\nwin.setHasShadow(hasShadow)hasShadow BooleanEstablece si la ventana debe tener una sombra.
\nwin.hasShadow()Devuelve Boolean - Si la ventana tiene o no una sombra.
win.setOpacity(opacity) Windows macOSopacity 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.
\nwin.getOpacity()Devuelve number - entre 0.0 (completamente transparente) y 1.0 (totalmente opaco). En Linux, siempre devuelve 1.
win.setShape(rects) Windows Linux Experimentalrects 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.
\nwin.setThumbarButtons(buttons) Windowsbuttons 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.
\nLos buttons es un arreglo de objetos Button:
Button Objecticon NativeImage - El icono que muestra la barra de herramientas de la vista previa.click Funcióntooltip String (opcional): el texto de la información sobre el botón.flags String - Controla los estados y comportamientos específicos del botón. Por defecto, es ['enabled'].Los flags es una matriz que puede incluir siguientes Strings:
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) Windowsregion Rectangle - la región de la ventanaEstablece 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) WindowstoolTip StringConfigura la descripción emergente que se muestra cuando se pasa sobre la vista previa de la ventana en la barra de tareas.
\nwin.setAppDetails(options) Windowsoptions ObjectappId String (opcional) - El App User Model ID de Windows. Tiene que estar configurado, de lo contrario las otras opciones no tendrán efecto.appIconPath String (opcional) - El Relaunch Icon de Windows.appIconIndex Integer (optional) - Index of the icon in appIconPath. Ignored when appIconPath is not set. Por defecto es 0.relaunchCommand String (opcional) - El Relaunch Command de Windows.relaunchDisplayName String (opcional) - El Relaunch Display Name de Windows.Establece las propiedades para el botón de la barra de herramientas de la ventana.
\nNote: relaunchCommand y relaunchDisplayName siempre deben ser establecidos juntos. Si una de esas propiedades no está establecida, entonces ninguna será usada.
win.showDefinitionForSelection() macOSEs igual a webContents.showDefinitionForSelection().
win.setIcon(icon) Windows Linuxicon NativeImage | StringCambia el icono de la ventana.
\nwin.setWindowButtonVisibility(visible) macOSvisible BooleanEstablece si los botones de luz del tráfico de ventana deben estar visibles.
\nwin.setAutoHideMenuBar(hide)hide BooleanEstablece 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()Devuelve Boolean - Si la barra de menú se oculta o no automáticamente.
win.setMenuBarVisibility(visible) Windows Linuxvisible BooleanEstablece 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()Devuelve Boolean - Si la barra de menú es visible o no.
win.setVisibleOnAllWorkspaces(visible[, options])visible Booleanoptions Object (opcional)visibleOnFullScreen Boolean (opcional) macOS - Establece si la ventana debe ser visible encima de la ventanas de pantalla completas.skipTransformProcessType Boolean (opcional) macOS - Llamando a setVisibleOnAllWorkspaces por defecto transformará el tipo de proceso entre UIElementApplication y ForegroundApplication para asegurar el comportamiento correcto. Sin embargo, esto ocultará la ventana y el dock por un tiempo corto cada vez que es llamado. Si su ventana ya es de tipo UIElementApplication, puede saltarse esta tranformación pasando true a skipTransformProcessType.Establece si la ventana debe ser visible o no en todos los espacios de trabajo.
\nNota: Esta API no hace nada en Windows.
\nwin.isVisibleOnAllWorkspaces()Devuelve Boolean - Si la ventana es visible en todos los espacios de trabajo.
Nota: Esta API siempre devuelve false en Windows.
\nwin.setIgnoreMouseEvents(ignore[, options])ignore Booleanoptions Object (opcional)forward Boolean (opcional) macOS Windows - Si es true, enviá el mensaje de movimiento de mouse a Chromium, permitiendo eventos relacionados tal como mouseleave. Solo se usa cuando ignore es verdadero. Si ignore es falso, el reenvío está simpre desactivado independientemente de este valor.Hace que la ventana ignore todos los eventos del ratón.
\nTodos 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.
\nwin.setContentProtection(enable) macOS Windowsenable BooleanEvita que los contenidos de la ventana sean capturados por otras aplicaciones.
\nOn 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 Windowsfocusable BooleanCambia si se puede enfocar o no la ventana.
\nEn macOS no elimina el foco de la ventana.
\nwin.isFocusable() macOS WindowsDevuelve si la ventana puede ser enfocada.
\nwin.setParentWindow(parent)parent BrowserWindow | nullEstablece 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 - La ventana principal.
win.getChildWindows()Devuelve BrowserWindow[] - Todas las ventanas secundarias.
win.setAutoHideCursor(autoHide) macOSautoHide BooleanControla si se debe ocultar el cursor al escribir.
\nwin.selectPreviousTab() macOSSelecciona la pestaña previa cuando las pestañas nativas están activas y hay otras pestañas en la ventana.
\nwin.selectNextTab() macOSSelecciona la siguiente pestaña cuando las pestañas nativas están activas y hay otras pestañas en la ventana.
\nwin.mergeAllWindows() macOSUnifica 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.
\nwin.moveTabToNewWindow() macOSMueve 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.
\nwin.toggleTabBar() macOSConmuta 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.
\nwin.addTabbedWindow(browserWindow) macOSbrowserWindow BrowserWindowAñade una ventana como pestaña de la ventana actual, después de la pestaña para la instancia de la ventana actual.
\nwin.setVibrancy(type) macOStype String | null - Puede ser appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, o under-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.
Note que appearance-based, light, dark, medium-light, y ultra-dark han sido marcadas como obsoletas y serán eliminadas un un próxima versión de macOS.
win.setTrafficLightPosition(position) macOSposition PuntoEstablece una posición personalizada para los botones del semáforo en la ventana sin marco.
\nwin.getTrafficLightPosition() macOSDevuelve Point - La posición personalizada para los botones del semáforo en la ventana sin marco.
win.setTouchBar(touchBar) macOStouchBar TouchBar | nullConfigura el plano de la touchBar para la ventana actual. Espeficando null o undefined elimina la barra táctil. Este método solo es efectivo si la máquina tiene una barra táctil y si se está ejecutando en macOS 10.12.1+.
Nota: La API TouchBar API actualmente es experimental y puede cambiar o ser eliminada en futuras versiones de Electron.
\nwin.setBrowserView(browserView) ExperimentalbrowserView BrowserView | null - Adjunta browserView a win. Si hay otros BrowserViews adjuntos, se eliminarán de esta ventana.win.getBrowserView() ExperimentalDevuelve BrowserView | null - El BrowserView adjunto a win. Devuelve null si uno no esta adjunto. Lanza un error si múltiples BrowserView son adjuntos.
win.addBrowserView(browserView) ExperimentalbrowserView BrowserViewAPI de reemplazo para setBrowserView soporta el trabajo con múltiples vistas de navegador.
\nwin.removeBrowserView(browserView) ExperimentalbrowserView BrowserViewwin.setTopBrowserView(browserView) ExperimentalbrowserView BrowserViewLevanta un browserView sobre otro BrowserView adjunto a win. Lanza un error si browserView no está adjunto a win.
win.getBrowserViews() ExperimentalDevuelve BrowserView[] - Un array de todos los BrowserViews que han sido adjuntados con addBrowserView or setBrowserView.
Nota: actualmente la API BrowserView es experimental y puede cambiar o ser eliminada en versiones futuras de Electron.
", "title": "BrowserWindow", "description": "Crea y controla las ventanas del navegador." }, "/docs/api/browser-window-proxy": { "locale": "es-ES", "slug": "browser-window-proxy", "href": "/docs/api/browser-window-proxy", "crowdinFileId": "256285", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-window-proxy.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nManipula la ventana secundaria del navegador
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
El objeto BrowserWindowProxy es devuelto de window.open y proporciona una funcionalidad limitada con la ventana secundaria.
El objeto BrowserWindowProxy tiene los siguientes métodos de instancia:
win.blur()Elimina el enfoque de la ventana secundaria.
\nwin.close()Cierra a la fuerza la ventana secundaria sin llamar a su evento de descarga.
\nwin.eval(code)code StringEvalúa el código en la ventana secundaria.
\nwin.focus()Enfoca la ventana secundaria (trae la ventana al frente).
\nwin.print()Invoca en cuadro de diálogo en la ventana secundaria.
\nwin.postMessage(message, targetOrigin)mensaje cualquieratargetOrigin StringEnvía un mensaje a la ventana secundaria con el origen específicado o * sin origen de preferencia.
Además de estos métodos, la ventana secundaria implementa el objeto window.opener sin ninguna propiedad y un método único.
El objeto BrowserWindowProxy tiene las siguientes propiedades de instancia:
win.closedUn Boolean que cambia a true cuando la ventana secundaria se cierra.
Follow the guidelines below for building Electron itself, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nComprueba los pre-requisitos de tu plataforma para la compilación antes de avanzar
\n\nElectron's Build Tools automate much of the setup for compiling Electron from source with different configurations and build targets. Si deseas configurar el entorno de forma manual, las instrucciones se enumeran a continuación.
\nNecesitaras instalar depot_tools, el conjunto de herramientas usadas para consumir Chromium y sus dependencias.
Ademas, en Windows, tendrás que asignar la variable de ambiente DEPOT_TOOLS_WIN_TOOLCHAIN=0. Para hacerlo, abre Panel de Control → Sistema y Seguridad → Sistema → Opciones de Configuración Avanzadas y agrega a tu sistema la variable de ambiente DEPOT_TOOLS_WIN_TOOLCHAIN con el valor 0. Esto le indica a depot_tools que utilice tu version instalada de Visual Studio (por defecto, depot_tools intentará descargar una version interna de Google, a la cual solo empleados de Google tienen acceso).
Si planeas hacer checkout de Electron más de una vez (por ejemplo, para tener múltiples directorios paralelos verificados en diferentes ramas), el uso del cache git acelerará las llamadas posteriores a gclient. Para hacer esto, establezca una variable de entorno GIT_CACHE_PATH:
$ export GIT_CACHE_PATH=\"${HOME}/.git_cache\"\n$ mkdir -p \"${GIT_CACHE_PATH}\"\n# Esto usará alrededor de 16G.\n$ mkdir electron && cd electron\n$ gclient config --name \"src/electron\" --unmanaged https://github.com/electron/electron\n$ gclient sync --with_branch_heads --with_tags\n# This will take a while, go get a coffee.\n\n\nEn lugar de
\nhttps://github.com/electron/electron, puedes usar tu propio fork aquí (algo comohttps://github.com/<username>/electron).
Si usted tiene la intención de git pull or git push desde el repositorio oficial electron en el futuro, ahora necesita actualizar las URLs de la carpeta origin correspondiente.
$ cd src/electron\n$ git remote remove origin\n$ git remote add origin https://github.com/electron/electron\n$ git checkout main\n$ git branch --set-upstream-to=origin/main\n$ cd -\n📝 gclient funciona verificando las dependencias en un archivo llamado DEPS dentro de la carpeta src/electron (tales como Chromium o Node.js). Ejecutar gclient sync -f asegura que todas las dependencias requeridas para compilar Electron coninciden con ese archivo.
Así que, para tirar, ejecutarías los siguientes comandos:
\n$ cd src/electron\n$ git pull\n$ gclient sync -f\n$ cd src\n$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nO en Windows (sin el argumento opcional):
\n$ cd src\n$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\\buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\")\"\nEsto generará un directorio de compilación out/Testing under src/ con la configuración de compilación de pruebas. Usted puede reemplazar Testing con otro nombre, pero debería ser a subdirectorio de out. Además no deberías ejecutar gn gen de nuevo — si quieres cambiar los argumentos de compilación, puedes ejecutar gn args out/Testing para traer un editor.
Para ver la lista de opciones de configuraciones disponible, ejecute gn args out/Testing --list.
Para generar la configuración de compilación de prueba de Electron:
\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nPara generar la configuración de lanzamiento (alias \"non-component\" o \"static\") de Electron:
\n$ gn gen out/Release --args=\"import(\\\"//electron/build/args/release.gn\\\") $GN_EXTRA_ARGS\"\nPara compilar, corra ninja con el electron target: Nota Bene: Esto también tomará un tiempo y probablemente calentará tu regazo.
Para la configuración de depuración:
\n$ ninja -C out/Testing electron\nPara la configuración de la lanzamiento:
\n$ ninja -C out/Release electron\nThis will build all of what was previously 'libchromiumcontent' (i.e. the content/ directory of chromium and its dependencies, incl. WebKit and V8), so it will take a while.
El ejecutable compilado estará en ./out/Testing:
$ ./out/Testing/Electron.app/Contents/MacOS/Electron\n# or, on Windows\n$ ./out/Testing/electron.exe\n# or, on Linux\n$ ./out/Testing/electron\nEn linux, primero elimine la información de depuración y de símbolos:
\nelectron/script/strip-binaries.py -d out/Release\nPara empaquetar la aplicación compilada electron como un archivo zip distribuible:
\nninja -C out/Release electron:electron_dist_zip\nPara compilar una plataforma que no sea la misma que la que estás construyendo, establece los argumentos GN target_cpu y target_os. Por ejemplo, para compilar un objetivo x86 de un host x64, especificar target_cpu = \"x86\" en gn args.
$ gn gen out/Testing-x86 --args='... target_cpu = \"x86\"'\nNo todas las combinaciones de origen y destino sea CPU/SO son compatibles con Chromium.
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Host | Objetivo | Estado |
|---|---|---|
| Windows x64 | Windows arm64 | Experimental |
| Windows x64 | Windows x86 | Automáticamente probado |
| Linux x64 | Linux x86 | Automáticamente probado |
Si prueba otras combinaciones y las encuentra para funcionar, por favor actualice este documento :)
\nSee the GN reference for allowable values of target_os and target_cpu.
Para compilar de forma cruzada para Windows en Arm, follow Chromium's guide para obtener las dependencias necesarias, SDK y librerias, luego construir con ELECTRON_BUILDING_WOA=1 en su entorno antes de ejecutar gclient sync.
set ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nO (si usa PowerShell):
\n$env:ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nDespues, corra gn gen como arriba con target_cpu=\"arm64\".
Para ejecutar las pruebas, primero deberás compilar los módulos de prueba en la misma versión de node.js en la que se creó el proceso de compilación. Para generar cabeceras de compilación para los módulos a compilar, ejecute lo siguiente en el directorio src/.
$ ninja -C out/Testing third_party/electron_node:headers\nAhora puede ejecutar run the tests.
\nSi estás depurando algo, puede ser de gran ayuda pasarle algunas banderas adicionales a el binario de Electron:
\n$ npm run test -- \\\n --enable-logging -g 'BrowserWindow module'\nEs posible compartir este directorio con otras máquinas exportándolo como SMB share en Linux, pero solo un proceso/máquina puede usar la memoria caché a la vez. Los bloqueos creados por el script git-cache intentarán evitar esto, pero puede que no funcione perfectamente en una red.
\nEn Windows, SMBv2 tiene un caché de directorio que causará problemas con el script del git cache, por lo que es necesario desactivarlo configurando la clave de registro
\nHKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\\DirectoryCacheLifetime\na cero. Para más información: https://stackoverflow.com/a/9935126
\nEsto puede establecerse rápidamente en powershell (ejecutado como administrador):
\nNew-ItemProperty -Path \"HKLM:\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force\nSi gclient sync es interrumpido el arbol de git puede quedar en mal estado, lo que conduce a un mensaje críptico cuando se ejecuta gclient sync en el futuro:
2> Conflict while rebasing this branch.\n2> Fix the conflict and run gclient again.\n2> See man git-rebase for details.\nSi no hay conflictos de git o rebases en src/electron, puede necesitar abortar un git am en src:
$ cd ../\n$ git am --abort\n$ cd electron\n$ gclient sync -f\nSi ve un prompt para Username for 'https://chrome-internal.googlesource.com': cuando corre gclient sync en Windows, es probable que la variable de entorno DEPOT_TOOLS_WIN_TOOLCHAIN no esta establecida a 0. Abra Control Panel → System and Security → System → Advanced system settings y agregue un variable de sistema DEPOT_TOOLS_WIN_TOOLCHAIN con valor 0. Esto le indica a depot_tools que utilice tu version instalada de Visual Studio (por defecto, depot_tools intentará descargar una version interna de Google, a la cual solo empleados de Google tienen acceso).
Follow the guidelines below for building Electron itself on Linux, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nAt least 25GB disk space and 8GB RAM.
\nPython 2.7.x. Some distributions like CentOS 6.x still use Python 2.6.x so you may need to check your Python version with python -V.
Please also ensure that your system and Python version support at least TLS 1.2. For a quick test, run the following script:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, use your system's package manager to update Python to the latest version in the 2.7.x branch. Alternatively, visit https://www.python.org/downloads/ for detailed instructions.
\nNode.js. There are various ways to install Node. You can download source code from nodejs.org and compile it. Doing so permits installing Node on your own home directory as a standard user. Or try repositories such as NodeSource.
\nclang 3.4 or later.
\nDevelopment headers of GTK 3 and libnotify.
\nOn Ubuntu, install the following libraries:
\n$ sudo apt-get install build-essential clang libdbus-1-dev libgtk-3-dev \\\n libnotify-dev libgnome-keyring-dev \\\n libasound2-dev libcap-dev libcups2-dev libxtst-dev \\\n libxss1 libnss3-dev gcc-multilib g++-multilib curl \\\n gperf bison python-dbusmock openjdk-8-jre\nOn RHEL / CentOS, install the following libraries:
\n$ sudo yum install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Fedora, install the following libraries:
\n$ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Arch Linux / Manjaro, install the following libraries:
\n$ sudo pacman -Syu base-devel clang libdbus gtk2 libnotify \\\n libgnome-keyring alsa-lib libcap libcups libxtst \\\n libxss nss gcc-multilib curl gperf bison \\\n python2 python-dbusmock jdk8-openjdk\nOther distributions may offer similar packages for installation via package managers such as pacman. Or one can compile from source code.
\nIf you want to build for an arm target you should also install the following dependencies:
$ sudo apt-get install libc6-dev-armhf-cross linux-libc-dev-armhf-cross \\\n g++-arm-linux-gnueabihf\nSimilarly for arm64, install the following:
$ sudo apt-get install libc6-dev-arm64-cross linux-libc-dev-arm64-cross \\\n g++-aarch64-linux-gnu\nAnd to cross-compile for arm or ia32 targets, you should pass the target_cpu parameter to gn gen:
$ gn gen out/Testing --args='import(...) target_cpu=\"arm\"'\nPrebuilt clang will try to link to libtinfo.so.5. Depending on the host architecture, symlink to appropriate libncurses:
$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5\nThe default building configuration is targeted for major desktop Linux distributions. To build for a specific distribution or device, the following information may help you.
\nclang instead of downloaded clang binariesBy default Electron is built with prebuilt clang binaries provided by the Chromium project. If for some reason you want to build with the clang installed in your system, you can specify the clang_base_path argument in the GN args.
For example if you installed clang under /usr/local/bin/clang:
$ gn gen out/Testing --args='import(\"//electron/build/args/testing.gn\") clang_base_path = \"/usr/local/bin\"'\nclangBuilding Electron with compilers other than clang is not supported.
Follow the guidelines below for building Electron itself on macOS, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nPlease also ensure that your system and Python version support at least TLS 1.2. Esto depende tanto de la versión de macOS como la de Python. Para una prueba rápida, ejecuta:
\n$ npx @electron/check-python-tls\nSi el script devuelve que tu configuración está usando un protocolo de seguridad obsoleto, puedes actualizar macOS a High Sierra o instalar una nueva versión de Python 2.7.x. Para actualizar Python, usa Homebrew:
\n$ brew install python@2 && brew link python@2 --force\nSi está utilizando Python descargado por Homebrew, también debe instalar los siguientes módulos de Python:
\nUsted puede usar pip para instalarlo:
$ pip install pyobjc\nSi simplemente estás desarrollando Electron y no planeas redistribuir tu compilación personalizada de Electron, puede omitir esta sección.
\nLas compilaciones oficiales de Electron son construidas con Xcode 12.2 y el SDK 11.0 de macOS. Construir con un SDK más nuevo también funciona, pero las versiones actualmente usan el SDK 11.0.
\nFollow the guidelines below for building Electron itself on Windows, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nvs2019_install = DRIVE:\\path\\to\\Microsoft Visual Studio\\2019\\Community, sustituyendo 2019 y Comunidad por sus versiones instaladas y sustituyendo DRIVE: por la unidad en la que Visual Studio está activada. A menudo, esto será C:.WINDOWSSDKDIR = DRIVE:\\path\\to\\Windows Kits\\10, replacing DRIVE: with the drive that Windows Kits is on. A menudo, esto será C:.symstore.exe is used for creating a symbol store from .pdb files.Modify → Individual Components, scroll down and select the appropriate Windows SDK to install. Otra opción sería mirar el Windows SDK y el archivo emulador y descargar la versión independiente del SDK respectivamente.Panel de Control → Programas → Programas y Características → Seleccione \"Windows Software Development Kit\" → Change → Change → Check \"Debugging Tools For Windows\" → Change. O puede descargar el instalador independiente del SDK y usarlo para instalar el Debugging Tools.Si actualmente no tiene una instalación de Windows, dev.microsoftedge.com tiene versiones temporales de Windows que usted puede usar para construir Electron.
\nElectron se construye casi completamente con script de comandos de linea y no puede ser generado con Visual Studio. Puede desarrollar Electron con cualquier editor pero el soporte para construir con Visual Studio vendrá en el futuro.
\nNota: A pesar de que Visual Studio no es usado para construir, todavía se requiere debido a que necesitamos las herramientas que provee para construir.
\nWindows Security doesn't like one of the files in the Chromium source code (see https://crbug.com/441184), so it will constantly delete it, causing gclient sync issues. You can exclude the source tree from being monitored by Windows Security by following these instructions.
Para construir para 32bit, usted necesita pasar target_cpu = \"x86\" como un argumento GN. Usted puede construir para 32bit junto con el target de 64bit usando diferentes carpetas de salida para GN, por ejemplo: out/Release-x86 con diferentes argumentos.
$ gn gen out/Release-x86 --args=\"import(\\\"//electron/build/args/release.gn\\\") target_cpu=\\\"x86\\\"\"\nEl resto de los pasos son exactamente los mismos.
\nPara generar un project de Visual Studio, puede pasar el parametro --ide=vs2017 a gn gen:
$ gn gen out/Testing --ide=vs2017\nSi encuentra un error como Comand xxxx not found, intente usar la Consola de Comandos de VS2015 para ejecutar los scripts de compilacion.
Asegúrese de que tiene instalada la última versión de Visual Studio.
\nIntente reinstalar Node.js 32bit.
\nCreando ese directorio should fix the problem:
\n$ mkdir ~\\AppData\\Roaming\\npm\nDebe obtener este error si está usando Git Bash para la compilación, en cambio debería usar PowerShell o la ventana de comandos de VS2015.
\nnode.js tiene algunos extremely long pathnames, y por defecto git en windows no maneja correctamente los nombres de rutas largos(a pesar de que windows los soporta). Esto debería arreglarlo:
\n$ git config --system core.longpaths true\nThis can happen during build, when Debugging Tools for Windows has been installed with Windows Driver Kit. Uninstall Windows Driver Kit and install Debugging Tools with steps described above.
\nAsegúrese de haber instalado pywin32 con pip install pywin32.
Este error es una \"característica\" del intérprete de comandos de Windows. Ocurre cuando se pulsa dentro de la ventana prompt con QuickEdit habilitado y está destinado a permitir seleccionar y copiar el texto de la salida fácilmente. Dado que cada click accidental pausará el proceso de compilación, puede que quiera desactivar esta característica en la propiedades del símbolo del sistema.
Electron usa gyp para la generación de proyectos y ninja para su compilación. Las configuraciones del Proyecto puede ser encontradas en los archivos .gn y .gni.
Los siguientes archivos gn contienen las reglas principales para la construcción de Electron:
BUILD.gn define como Electron mismo es construido e incluye la configuraciones predeterminadas para enlazar con Chromium.build/args/{debug,release,all}.gn contiene los argumentos por defecto para la construcción de Electron.Dado que Chromium es un proyecto bastante grande, la etapa final de enlace puede tomar bastantes minutos, lo que dificulta el desarrollo. Para resolver esto, Chromium introdujo la \"construcción de componentes\", que construye cada componente como una biblioteca compartida separada, lo que hace que el enlace sea muy rápido pero sacrificando el tamaño del archivo y rendimiento.
\nElectron hereda esta opción de construcción de Chromium. En versiones Debug se enlazará al binario con una versión de biblioteca compartida de los componentes de Chromium para lograr un tiempo de enlace rápido; para versiones Release, el binario estará vinculado a las versiones estáticas de la biblioteca, de modo que podemos tener el mejor tamaño de binario posible y rendimiento.
NB esta sección está desactualizada y contiene información que ya no es relevante para el GN-built electron.
\nPruebe sus cambios conforme al estilo de codificación del proyecto usando:
\n$ npm run lint\nPruebe la funcionalidad usando:
\n$ npm test\nCada vez que realice cambios en el código fuente de Electron, deberá volver a ejecutar la compilación antes de las pruebas:
\n$ npm run build && npm test\nPuede hacer que la prueba en suite corra más rápido al aislar la prueba específica o bloquear su trabajo actual en la característica prueba exclusiva de Mocha. Agregar .only a cualquier describe o it función llama:
describe.only('alguna característica', () => {\n // ... solo pruebas se ejecutarán en este bloque\n})\nAlternativamente, puede usar la opción de mocha grep de solo correr prueba que coincidan con un patrón regular de expresión:
$ npm test -- --grep child_process\nPruebas que incluyan módulos nativos (como por ejemplo runas) no pueden ser ejecutadas con el compilador de depuración (vea #2558 para más detalles), pero estos trabajarán con el compilado lanzado.
Para ejecutar las pruebas con el lanzamiento compila el uso:
\n$ npm test -- -R\ndata String - PEM encoded dataissuer CertificatePrincipal - Issuer principalissuerName String - Issuer's Common NameissuerCert Certificate - Issuer certificate (if not self-signed)subject CertificatePrincipal - Subject principalsubjectName String - Subject's Common NameserialNumber String - Hex value represented stringvalidStart Number - Start date of the certificate being valid in secondsvalidExpiry Number - End date of the certificate being valid in secondsfingerprint String - Fingerprint of the certificatecommonName String - Common Name.organizations String[] - Organization names.organizationUnits String[] - Organization Unit names.locality String - Locality.state String - State or province.country String - Country or region.\n\nUna colección de recursos para aprender sobre Chromium y rastrear su desarrollo
\n
Ver también Desarrollo V8
", "title": "Desarrollo de Chromium", "description": "Una colección de recursos para aprender sobre Chromium y rastrear su desarrollo" }, "/docs/development/clang-format": { "locale": "es-ES", "slug": "clang-format", "href": "/docs/development/clang-format", "crowdinFileId": "256143", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/clang-format.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "clang-format es una herramienta para formatear automáticamente el código C/C++/Objective-C, de modo que los desarrolladores no tengan que preocuparse por los problemas de estilo durante las revisiones del código.
Se recomienda formatear su código C++ modificado antes de abrir solicitudes de extracción, lo que le ahorrará tiempo a usted y a los evaluadores.
\nPuede instalar clang-format y git-clang-format a través de npm install -g clang-format.
To automatically format a file according to Electron C++ code style, run clang-format -i path/to/electron/file.cc. It should work on macOS/Linux/Windows.
El flujo de trabajo para formatear su código modificado:
\ngit add your_changed_file.cc.git-clang-format, y probablemente verá modificaciones en your_changed_file.cc, estas modificaciones se generan a partir de clang-format.git agregue su_archivo_registrado.cc y confirme su cambio.If you want to format the changed code on your latest git commit (HEAD), you can run git-clang-format HEAD~1. See git-clang-format -h for more details.
You can also integrate clang-format directly into your favorite editors. For further guidance on setting up editor integration, see these pages:
clang-tidy is a tool to automatically check C/C++/Objective-C code for style violations, programming errors, and best practices.
Electron's clang-tidy integration is provided as a linter script which can be run with npm run lint:clang-tidy. While clang-tidy checks your on-disk files, you need to have built Electron so that it knows which compiler flags were used. There is one required option for the script --output-dir, which tells the script which build directory to pull the compilation information from. A typical usage would be: npm run lint:clang-tidy --out-dir ../out/Testing
With no filenames provided, all C/C++/Objective-C files will be checked. You can provide a list of files to be checked by passing the filenames after the options: npm run lint:clang-tidy --out-dir ../out/Testing shell/browser/api/electron_api_app.cc
While clang-tidy has a long list of possible checks, in Electron only a few are enabled by default. At the moment Electron doesn't have a .clang-tidy config, so clang-tidy will find the one from Chromium at src/.clang-tidy and use the checks which Chromium has enabled. You can change which checks are run by using the --checks= option. This is passed straight through to clang-tidy, so see its documentation for full details. Wildcards can be used, and checks can be disabled by prefixing a -. By default any checks listed are added to those in .clang-tidy, so if you'd like to limit the checks to specific ones you should first exclude all checks then add back what you want, like --checks=-*,performance*.
Running clang-tidy is rather slow - internally it compiles each file and then runs the checks so it will always be some factor slower than compilation. While you can use parallel runs to speed it up using the --jobs|-j option, clang-tidy also uses a lot of memory during its checks, so it can easily run into out-of-memory errors. As such the default number of jobs is one.
\n\nHace solicitudes HTTP/HTTPS.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Peticiones del cliente implementa la interfaz de corriente de escritura y por lo tanto es un emitidor de eventos.
new ClientRequest(options)options (Object | String) - Si options es un String, es interpretado como la URL de la solicitud. Si es un objeto, se espera que especifique completamente una solicitud HTTP a través de las siguientes propiedades:method String (opcional) - El método de la solicitud HTTP. Por defecto es el método GET.url String (opcional) - La URL de la solicitud. Debe ser proporcionada de forma absoluta con el esquema del protocolo especificado como http o https.session Session (opcional) - La instancia de Session con la cual la solicitud esta asociada.partición Cadena (opcional) - el nombre de la partición en la cual está asociada la solicitud. Por defecto es la cadena vacía. The session option supersedes partition. De esta manera si una sesión está explícitamente especificada, partición es ignorada.credentials String (opcional) - Puede ser include o omit. Whether to send credentials with this request. If set to include, credentials from the session associated with the request will be used. If set to omit, credentials will not be sent with the request (and the 'login' event will not be triggered in the event of a 401). This matches the behavior of the fetch option of the same name. If this option is not specified, authentication data from the session will be sent, and cookies will not be sent (unless useSessionCookies is set).useSessionCookies Boolean (opcional) - Si enviar cookies con esta solicitud desde la sesión poporcionada. If credentials is specified, this option has no effect. Por defecto es false.protocol String (opcional) - Puede ser http: o https:. The protocol scheme in the form 'scheme:'. Por defecto 'http:'.host Cadena (opcional) - El servidor central proporcionado como una concatenación de nombres de anfitrión y el número de puerto \"nombre del host:puerto\".nombre de anfitrión Cadena (opcional) - el nombre del servidor central.Puerto Entero (opcional) - el número de puerto listado en el servidor.ruta Cadena (opcional) - La parte de la ruta de la solicitud URL.redirect String (optional) - Can be follow, error or manual. The redirect mode for this request. When mode is error, any redirection will be aborted. When mode is manual the redirection will be cancelled unless request.followRedirect is invoked synchronously during the redirect event. Por defecto es seguir.origin String (optional) - The origin URL of the request.opcions propiedades como protocolo, central, nombre de anfitrión, puerto y ruta siguen estrictamente al modo Node.js como es descrito en el módulo URL.
Por ejemplo, podemos haber creado la misma solicitud a 'github.com' como sigue:
\nconst request = net.request({\n method: 'GET',\n protocol: 'https:',\n hostname: 'github.com',\n port: 443,\n path: '/'\n})\nDevuelve:
\nresponse IncomingMessage - An object representing the HTTP response message.Devuelve:
\nauthInfo ObjectisProxy Booleanscheme Stringanfitrión Cadenapuerto Íntegrorealm Cadenacallback Funciónusername String (opcional)password String (opcional)Emitido cuando un proxy de autenticación requiere las credenciales del usuario.
\nSe espera que la función retrollamada sea llamada de vuelta con las credenciales del usuario:
username Stringpassword Stringrequest.on('login', (authInfo, callback) => {\n callback('username', 'password')\n})\nProporcional credenciales vacías cancelará la solicitud y reportará un error de autenticación en el objeto de respuesta:
\nrequest.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`);\n response.on('error', (error) => {\n console.log(`ERROR: ${JSON.stringify(error)}`)\n })\n})\nrequest.on('login', (authInfo, callback) => {\n callback()\n})\nEmitido justo antes de que el último paquete de los datos de la solicitud haya sido escrito en el objeto solicitud.
Emitido cuando la request es abortada. El evento abort no será lanzado si la request ya está cerrada.
Devuelve:
\nerror Error - un objeto error proporciona cierta información sobre la falla.Emitido cuando el módulo net falla en emitir una solicitud de red. Típicamente cuando el objeto solicitud emite un evento error, un evento cerrar lo seguirá subsecuentemente y ningún objeto respuesta será proporcionado.
Emitido cuando el último evento en la transacción solicitud-respuesta HTTP. El evento cerrar indica que ningún otro evento será emitido en los objetos solicitud o respuesta.
Devuelve:
\nEstatus de código enteromethod StringRedirigir Url CadenaresponseHeaders Record<String, String[]>Emitido cuando el servidor devuelve una respuesta redirect (por ejemplo 301 Moved Permanently). Llamar a request.followRedirect continuará con la redirección. Si este evento es manejado, request.followRedirect debe ser llamado synchronously, de otra manera la solicitud será cancelada.
request.chunkedEncodingUn Booleano especificando cuando la solicitud usará el la codificación de transferencia del paquete HTTP o no. Por defecto es falso. La propiedad es de lectura y escritura, sin embargo puede ser configurada antes de la primera operación de escritura debido a que el encabezado HTTP no se ha puesto en el hilo. Tratar de configurar la propiedad codificación empaquetada después de la primera escritura arrojará un error.
Utilizar codificación empaquetada es fuertemente recomendado si no necesita enviar una solicitud grande dado que lo datos serán transmitidos en paquetes pequeños en lugar de ser cargados internamente en la memoria de proceso de Electron.
\nrequest.setHeader(name, value)nombre Cadena - Un nombre de encabezado HTTP extra.value String - Un valor de cabecera HTTP extra.Añade otro encabezado HTTP. El nombre de la cabecera se emitirá tal cual sin convertirlas a minúscula. Será llamado solo antes de la primera escritura. Llamar a este método despues de la primera escritura arrojará un error. Si el valor pasado no es una Cadena, llamará a su método toString() para obtener el valor final.
Ciertos encabezados están restringidos de ser definidos por aplicaciones. Estos encabezados se enlistan a continuación. Más información sobre encabezados restringidos puede ser encontrada en Chromium's header utils.
\nContent-LengthHostTrailer or TeUpgradeCookie2Keep-AliveTransfer-EncodingAdemás, definir el encabezado Connection al valor upgrade también está dehabilitado.
request.getHeader(name)nombre Cadena - Especifica el nombre del encabezado extra.Devuelve String - El valor de un nombre de cabecera extra establecido anteriormente.
request.removeHeader(name)nombre Cadena - Especifica el nombre del encabezado extra.Elimina un nombre de cabecera establecido previamente. This method can be called only before first write. Trying to call it after the first write will throw an error.
\nrequest.write(chunk[, encoding][, callback])chunk (String | Buffer) - A chunk of the request body's data. If it is a string, it is converted into a Buffer using the specified encoding.encoding String (optional) - Used to convert string chunks into Buffer objects. Defaults to 'utf-8'.retrollamada función (opcional) - Llamado cuando se haya realizado la operación de escritura.La retrollamada es esencialmente una función sencilla introducida con el propósito de mantener similitudes con el API Node.js. Es llamada asincrónicamente en el siguiente tick después de que el contenido del paquete haya sido entregado a la capa de red de Chromium. A diferencia de la implementación de Node.js, no está garantizado que el contenido del paquete haya sido entregado en el hilo antes de que sea llamada retrollamada.
Agrega un paquete de datos al cuerpo de la solicitud. La primera operación de escritura pudiese causar que el encabezado de la solicitud sea cambiado en el hilo. Después de la primera operación de escritura, no está permitido el añadir o remover un encabezado personalizado.
\nrequest.end([chunk][, encoding][, callback])paquete (Cadena | Almacenamiento) (opcional)codificación Cadena (opcional)retrocallback Funcion (opcional)Sends the last chunk of the request data. Subsequent write or end operations will not be allowed. The finish event is emitted just after the end operation.
request.abort()Cancela una transacción HTTP en proceso. Si la solicitud ya emitió el evento de cerrar, la operación abortar no tendrá ningún efecto. De otra manera un evento en proceso emitirá los eventos abortar y cerrar. Adicionalmente, si hay algún objeto de respuesta activo, será emitido el evento abortado.
request.followRedirect()Continues any pending redirection. Can only be called during a 'redirect' event.
request.getUploadProgress()Devuelve Objeto:
active Boolean - Whether the request is currently active. If this is false no other properties will be setstarted Boolean - Whether the upload has started. If this is false both current and total will be set to 0.current Integer - El número de bytes que se han subido hasta ahoratotal Integer - El número de bytes que ha subido esta solicitudPuedes usar este método en conjunto con solicitudes POST para obtener el progreso de la carga de un archivo u otro dato de transferencia.
\n\n\nRealiza las operaciones de copiar y pegar en el portapapeles del sistema.
\n
En Linux, también hay un portapapeles selección. Para manipularlo necesita pasar selección a cada método:
const { clipboard } = require('electron')\n\nclipboard.writeText('Example String', 'selection')\nconsole.log(clipboard.readText('selection'))\nEl módulo portapapeles tiene los siguientes métodos:
Nota: APIs experimentales son marcadas como tales y podría ser removidas en el futuro.
\nclipboard.readText([type])type String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Devuelve Cadena - El contenido en el portapapeles como texto sin formato.
const { clipboard } = require('electron')\n\nclipboard.writeText('hello i am a bit of text!')\n\nconst text = clipboard.readText()\nconsole.log(text)\n// hello i am a bit of text!'\nclipboard.writeText(texto[, type])texto Cadenatype String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Escribe el texto en el portapapeles como texto sin formato.
const { clipboard } = require('electron')\n\nconst text = 'hello i am a bit of text!'\nclipboard.writeText(text)\nclipboard.readHTML([type])type String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Devuelve Cadena - El contenido en el portapapeles como marca.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b>')\nconst html = clipboard.readHTML()\n\nconsole.log(html)\n// <meta charset='utf-8'><b>Hi</b>\nclipboard.writeHTML(markup[, type])markup Cadenatype String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Escribe markup en el portapapeles.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b')\nclipboard.readImage([type])type String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Devuelve NativeImage - El contenido de la imagen en el portapapeles.
clipboard.writeImage(image[, type])image NativeImagetype String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Escribe image en el portapapeles.
clipboard.readRTF([type])type String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Devuelve Cadena - El contenido en el portapapeles como RTF.
const { clipboard } = require('electron')\n\nclipboard.writeRTF('{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}')\n\nconst rtf = clipboard.readRTF()\nconsole.log(rtf)\n// {\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}\nclipboard.writeRTF(text[, type])texto Cadenatype String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Escribe el text en el portapapeles en RTF.
const { clipboard } = require('electron')\n\nconst rtf = '{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}'\nclipboard.writeRTF(rtf)\nclipboard.readBookmark() macOS WindowsDevuelve Objeto:
title Stringurl StringDevuelve un Objeto que contiene las claves title y url que representan el marcador en el portapapeles. Los valores title y url serán cadenas vacías cuando el marcador no está disponible.
clipboard.writeBookmark(title, url[, type]) macOS Windowstitle Stringurl Stringtype String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Escribe el título y la url en el portapapeles como un marcador.
Nota: La mayoría de las aplicaciones en Windows no soportan el pegado de marcadores dentro de ellas así que puedes usar clipboard.write para escribir tanto un marcador como un texto de respaldo en el portapapeles.
const { clipboard } = require('electron')\n\nclipboard.writeBookmark({\n text: 'https://electronjs.org',\n bookmark: 'Electron Homepage'\n})\nclipboard.readFindText() macOSDevuelve String - El texto en el portapapeles de búsqueda, el cual es el portapapeles que contiene información sobre el estado actual del panel de búsqueda de la aplicación.
Este método usa IPC síncrono cuando se llama desde el renderer process. El valor almacenado en el cache es re leído desde portapapeles de búsqueda cada vez que la aplicación se activa.
\nclipboard.writeFindText(text) macOStexto CadenaEscribe el text portapapeles de búsqueda ( portapapeles que contiene información sobre el estado actual del panel de búsqueda de la aplicación) como texto plano. Este método usa IPC síncrono cuando se llama desde el renderer process.
clipboard.clear([type])type String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Borra el contenido del portapapeles.
\nclipboard.availableFormats([type])type String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Devuelve Cadena[] - Una matriz de formatos admitidos para el portapapeles type.
const { clipboard } = require('electron')\n\nconst formats = clipboard.availableFormats()\nconsole.log(formats)\n// [ 'text/plain', 'text/html' ]\nclipboard.has(format[, type]) Experimentalformato Cadenatype String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Devuelve Boolean: si el portapapeles admite el formato especificado.
const { clipboard } = require('electron')\n\nconst hasFormat = clipboard.has('<p>selection</p>')\nconsole.log(hasFormat)\n// 'true' or 'false'\nclipboard.read(format) Experimentalformato CadenaDevuelve String - Lee el tipo de formato del portapapeles.
format should contain valid ASCII characters and have / separator. a/c, a/bc are valid formats while /abc, abc/, a/, /a, a are not valid.
clipboard.readBuffer(format) Experimentalformato CadenaDevuelve Buffer - Lee el formato del portapapeles.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('this is binary', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\n\nconst ret = clipboard.readBuffer('public/utf8-plain-text')\n\nconsole.log(buffer.equals(out))\n// true\nclipboard.writeBuffer(format, buffer[, type]) Experimentalformato Cadenabuffer Buffertype String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Escribe el buffer en el portapapeles como formato.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('writeBuffer', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\nclipboard.write(data[, type])data Objecttext Cadena (opcional)html Cadena (opcional)image NativeImage (opcional)rtf Cadena (opcional)bookmark String (opcional) - El título de la URL en text.type String (opcional) - Puede ser selection o clipboard; por defecto es 'clipboard'. selection solo está disponible en Linux.Escribe datos en el portapapeles.
const { clipboard } = require('electron')\n\nclipboard.write({\n text: 'test',\n html: '<b>Hi</b>',\n rtf: '{\\\\rtf1\\\\utf8 text}',\n bookmark: 'a title'\n})\n\nconsole.log(clipboard.readText())\n// 'test'\n\nconsole.log(clipboard.readHTML())\n// <meta charset='utf-8'><b>Hi</b>\n\nconsole.log(clipboard.readRTF())\n// '{\\\\rtf1\\\\utf8 text}'\n\nconsole.log(clipboard.readBookmark())\n// { title: 'a title', url: 'test' }\nLa firma de código es una tecnología de seguridad que utiliza para certificar que una aplicación fue creada por usted.
\nEn macOS el sistema puede detectar cualquier cambio en la aplicación, tanto si el cambio es introducido accidentalmente como por código malicioso.
\nOn Windows, the system assigns a trust level to your code signing certificate which if you don't have, or if your trust level is low, will cause security dialogs to appear when users start using your application. Trust level builds over time so it's better to start code signing as early as possible.
\nSi bien es posible distribuir aplicaciones sin firmar, no es recomendable. Both Windows and macOS will, by default, prevent either the download or the execution of unsigned applications. Starting with macOS Catalina (version 10.15), users have to go through multiple manual steps to open unsigned applications.
\n
Como puedes ver, los usuarios tienen dos opciones: Mover la aplicación directamente a la papelera o cancelar la ejecución. Tú no quieres que tus usuarios vean ese diálogo.
\nIf you are building an Electron app that you intend to package and distribute, it should be code-signed.
\nProperly preparing macOS applications for release requires two steps: First, the app needs to be code-signed. Then, the app needs to be uploaded to Apple for a process called \"notarization\", where automated systems will further verify that your app isn't doing anything to endanger its users.
\nTo start the process, ensure that you fulfill the requirements for signing and notarizing your app:
\nElectron's ecosystem favors configuration and freedom, so there are multiple ways to get your application signed and notarized.
\nelectron-forgeIf you're using Electron's favorite build tool, getting your application signed and notarized requires a few additions to your configuration. Forge is a collection of the official Electron tools, using electron-packager, electron-osx-sign, and electron-notarize under the hood.
Let's take a look at an example configuration with all required fields. Not all of them are required: the tools will be clever enough to automatically find a suitable identity, for instance, but we recommend that you are explicit.
{\n \"name\": \"my-app\",\n \"version\": \"0.0.1\",\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"osxSign\": {\n \"identity\": \"Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)\",\n \"hardened-runtime\": true,\n \"entitlements\": \"entitlements.plist\",\n \"entitlements-inherit\": \"entitlements.plist\",\n \"signature-flags\": \"library\"\n },\n \"osxNotarize\": {\n \"appleId\": \"felix@felix.fun\",\n \"appleIdPassword\": \"my-apple-id-password\",\n }\n }\n }\n }\n}\nThe plist file referenced here needs the following macOS-specific entitlements to assure the Apple security mechanisms that your app is doing these things without meaning any harm:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nNote that up until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required as well. However, it should not be used anymore if it can be avoided.
To see all of this in action, check out Electron Fiddle's source code, especially its electron-forge configuration file.
If you plan to access the microphone or camera within your app using Electron's APIs, you'll also need to add the following entitlements:
\n<key>com.apple.security.device.audio-input</key>\n<true/>\n<key>com.apple.security.device.camera</key>\n<true/>\nIf these are not present in your app's entitlements when you invoke, for example:
\nconst { systemPreferences } = require('electron')\n\nconst microphone = systemPreferences.askForMediaAccess('microphone')\nPuede que tu aplicación falle. See the Resource Access section in Hardened Runtime for more information and entitlements you may need.
\nElectron-builderElectron Builder viene con una solución personalizada para la firma de su aplicación. Usted puede encontar its documentation here.
\nelectron-packagerIf you're not using an integrated build pipeline like Forge or Builder, you are likely using electron-packager, which includes electron-osx-sign and electron-notarize.
If you're using Packager's API, you can pass in configuration that both signs and notarizes your application.
\nconst packager = require('electron-packager')\n\npackager({\n dir: '/path/to/my/app',\n osxSign: {\n identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',\n 'hardened-runtime': true,\n entitlements: 'entitlements.plist',\n 'entitlements-inherit': 'entitlements.plist',\n 'signature-flags': 'library'\n },\n osxNotarize: {\n appleId: 'felix@felix.fun',\n appleIdPassword: 'my-apple-id-password'\n }\n})\nThe plist file referenced here needs the following macOS-specific entitlements to assure the Apple security mechanisms that your app is doing these things without meaning any harm:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nUp until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required as well. However, it should not be used anymore if it can be avoided.
Ver la Mac App Store Guide.
\nAntes de Firmar Compilaciones Windows, tu debes hacer lo siguiente:
\nUsted puede obtener una certificado de firma de código desde muchos revendedores. Prices vary, so it may be worth your time to shop around. Entre los revendedores populares se incluyen:
\nHay una serie de herramientas para firmar su aplicación empaquetada:
\nelectron-winstaller will generate an installer for windows and sign it for youelectron-forge can sign installers it generates through the Squirrel.Windows or MSI targets.electron-builder can sign some of its windows targetsVer la Windows Store Guide.
", "title": "Firma de código", "description": "" }, "/docs/development/coding-style": { "locale": "es-ES", "slug": "coding-style", "href": "/docs/development/coding-style", "crowdinFileId": "256147", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/coding-style.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Estas son las pautas de estilo para la codificación en Electron.
\nPara mostrar los problemas de estilo detectados por cpplint y eslint, puede ejecutar npm run lint.
path)ipc, app)@)path.join() para concatenar nombres de archivos.os.tmpdir() en lugar de /tmp cuando necesite referencias el directorio temporal.return when returning explicitly at the end of a function.return null, return undefined, null o undefinedPara C++ y Python, seguimos el estilo de código de Chromium. Puede usar el formato clang-format para el código C++ automáticamente. También hay un script script/cpplint.py para comprobar si todos los archivos se cumplen con los requisitos.
La versión de Python que estamos utilizando actualmente es Python 2.7.
\nEl código de C ++ utiliza una gran cantidad de abstracciones y tipos de Chromium, por lo que se recomienda familiarizarse con ellos. Un buen lugar para empezar es el documento de Chromium Important Abstractions and Data Structures. El documento menciona algunos tipos especiales, tipos de ámbito (que liberan automáticamente su memoria cuando salen del ámbito), mecanismos de registro etc.
\nPuede ejecutar npm run lint-docs para asegurarse de que los cambios en su documentación tengan el formato correcto.
- en lugar de _, por ejemplo file-name.js en vez de file_name.js, porque en el módulo github/atom los nombres están generalmente en la forma module-name. Esta regla solo aplica a archivos .js.const Para solicitudes y otras constantes. Si el valor es un primitivo, use nombre en mayúsculas (por ejemplo, const NUMBER_OF_RETRIES = 5).let para definir variablesfunction () { }+Las API de Electron utilizan el esquema de capitalización usado en Node.js:
\nBrowserWindow, use PascalCase.globalShortcut, use camelCase.win.webContents, utilice mixedCase.<webview> Tag o Process Object.Cuando se crea una nueva API, se prefiere utilizar captadores y establecedores en lugar del estilo one-function de JQuery. Por ejemplo, se prefiere .getText() y .setText(text), en lugar de .text([text]). Hay una discussion sobre esto.
\n\nManipula los argumentos de la línea de comandos para tu aplicación que Chromium lee
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
El siguiente ejemplo muestra como comprobar si la bandera --disable-gpu está activada.
const { app } = require('electron')\napp.commandLine.hasSwitch('disable-gpu')\nPara más información sobre que tipos de banderas e interruptores puedes usar, revisa el documento Command Line Switches.
\ncommandLine.appendSwitch(switch[, value])switch String - Un interruptor de la linea de comandos, sin el líder --value Cadena (opcional) - Un valor para el cambio dadoAdjuntar un cambio (con valor opcional) al comando de de línea de Chromium.
Nota: Esto no afectará a process.argv. El uso previsto de esta función is controlar el comportamiento de Chromium.
commandLine.appendArgument(value)valor Cadena - El argumento a adjuntar a la línea de comandoAgrega un argumento a la línea de comando de Chromium. El argumento será citado correctamente. Los interruptores precederán a los argumentos independientemente de orden agregado.
\nSi estas añadiendo un argumento como --switch=value, considere usar en su lugar appendSwitch('switch', 'value').
Nota: Esto no afectará a process.argv. El uso previsto de esta función is controlar el comportamiento de Chromium.
commandLine.hasSwitch(switch)switch Cadena - Un cambio en la línea de comandoDevuelve Boolean - Si el interruptor de la línea de comando esta presente.
commandLine.getSwitchValue(switch)switch Cadena - Un cambio en la línea de comandoDevuelve String - El valor del interruptor de la linea de comando.
Note: Cando el interruptor no esta presento o no tiene un valor, revuelve una cadena vacía.
", "title": "Clase: CommandLine", "description": "Manipula los argumentos de la línea de comandos para tu aplicación que Chromium lee" }, "/docs/api/command-line-switches": { "locale": "es-ES", "slug": "command-line-switches", "href": "/docs/api/command-line-switches", "crowdinFileId": "256293", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/command-line-switches.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nOpciones de la linea de comandos soportados por Electron.
\n
Puedes usar app.commandLine.appendSwitch para añadirlas en el código principal de tu app antes de que el evento ready del modulo app es emitido:
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('remote-debugging-port', '8315')\napp.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')\n\napp.whenReady().then(() => {\n // Your code here\n})\nurlUna lista de servidores separadas por comas por los que la autentificación integrada esta habilitada.
\nPor ejemplo:
\n--auth-server-whitelist='*example.com, *foobar.com, *baz'\nentonces cualquier url acabando con example.com, foobar.com, baz será considerada por la autentificación integrada. Sin el prefijo * la URL ha de coincidir exactamente.
urlA comma-separated list of servers for which delegation of user credentials is required. Sin el prefijo * la URL ha de coincidir exactamente.
Disables NTLM v2 for posix platforms, no effect elsewhere.
\nDesactiva la cache de disco para las peticiones HTTP.
\nDesactiva los protocolos HTTP/2 y SPDY/3.
\nPreviene Chromium disminuir la prioridad de los procesos render de páginas invisibles.
\nEsta opción es global a todos los procesos de render, si solamente quieres deshabilitar el ajuste en una ventana, puedes usar el truco de pasar playing silent audio.
\nsizeFuerza el espacio máximo de disco a utilizar por la caché de disco, en bytes.
\nHabilita el caller stack logging para las siguientes APIs (eventos filtrados):
\ndesktopCapturer.getSources() / desktop-capturer-get-sourcesPrints Chromium's logging to stderr (or a log file).
\nThe ELECTRON_ENABLE_LOGGING environment variable has the same effect as passing --enable-logging.
Passing --enable-logging will result in logs being printed on stderr. Passing --enable-logging=file will result in logs being saved to the file specified by --log-file=..., or to electron_debug.log in the user-data directory if --log-file is not specified.
\n\nNote: On Windows, logs from child processes cannot be sent to stderr. Logging to a file is the most reliable way to collect logs on Windows.
\n
See also --log-file, --log-level, --v, and --vmodule.
trialsLas pruebas de campo se habilitan o deshabilitan por la fuerza.
\nPor ejemplo: WebRTC-Audio-Red-For-Opus/Enabled/
rulesLista de rules separadas por coma que controlan como los nombres de host son mapeados.
Por ejemplo:
\nMAP * 127.0.0.1 Fuerza todos los nombres de host a ser mapeados a 127.0.0.1MAP *.google.com proxy Fuerza todos los subdominios google.com a ser resueltos como \"proxy\".MAP test.com [::1]:77 Forces \"test.com\" to resolve to IPv6 loopback. Will also force the port of the resulting socket address to be 77.MAP * baz, EXCLUDE www.google.com Mapeara todo a \"baz\", excepto para \"www.google.com\".Estos mapeados aplican al host punto final en una petición de red (la conexión TCP y el host se solventan en una conexión directa, CONNECT en una conexión HTTP proxy, y el host punto fila en una conexión proxy SOCKS).
rulesComo --host-rules pero estas rules solamente aplican a el host resolutor.
Ignora los errores relacionados con el certificado.
\ndomainsIgnore el limite de conexión para la lista de domains separados por ,.
flagsSpecifies the flags passed to the Node.js engine. It has to be passed when starting Electron if you want to enable the flags in the main process.
$ electron --js-flags=\"--harmony_proxies --harmony_collections\" your-app\nVea la Documentación de Node.js o ejecute node --help en su terminal para una lista de las opciones disponibles. Adicionalmente, ejecute node --v8-options para ver una lista de opciones que se refieren específicamente al motor Node.js's V8 JavaScript.
Establecer una configuración regional personalizada.
\npathIf --enable-logging is specified, logs will be written to the given path. The parent directory must exist.
Setting the ELECTRON_LOG_FILE environment variable is equivalent to passing this flag. If both are present, the command-line switch takes precedence.
pathHabilita el registro de los eventos de red para ser salvados y escritos en la ruta path.
NSets the verbosity of logging when used together with --enable-logging. N should be one of Chrome's LogSeverities.
Note that two complimentary logging mechanisms in Chromium -- LOG() and VLOG() -- are controlled by different switches. --log-level controls LOG() messages, while --v and --vmodule control VLOG() messages. So you may want to use a combination of these three switches depending on the granularity you want and what logging calls are made by the code you're trying to watch.
See Chromium Logging source for more information on how LOG() and VLOG() interact. Loosely speaking, VLOG() can be thought of as sub-levels / per-module levels inside LOG(INFO) to control the firehose of LOG(INFO) data.
See also --enable-logging, --log-level, --v, and --vmodule.
Don't use a proxy server and always make direct connections. Overrides any other proxy server flags that are passed.
\nDisables the Chromium sandbox. Forces renderer process and Chromium helper processes to run un-sandboxed. Solo debe usarse para pruebas.
\nhostsInstructs Electron to bypass the proxy server for the given semi-colon-separated list of hosts. This flag has an effect only if used in tandem with --proxy-server.
Por ejemplo:
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')\nUtilizará el servidor proxy para todos los host excepto para las direcciones locales (localhost, 127.0.0.1 etc.), subdominios google.com, hosts que contienen el sufijo foo.com y cualquiera en 1.2.3.4:5678.
urlUsa el programa PAC en la url especificada.
address:portUsa un servidor proxy especifico, el cual sobrescribe la configuración del sistema. Esta opción solo afecta peticiones con protocolo HTTP, incluyendo peticiones HTTPS y WebSocket. También cabe destacar que no todos los servidores proxy aceptan peticiones HTTPS y WebSocket. La URL del proxy no soporta la autenticacón usuario y clave per Chromium issue.
\nportHabilita depuración remota sobre HTTP en el port especificado.
log_levelGives the default maximal active V-logging level; 0 is the default. Normally positive values are used for V-logging levels.
\nEsta opción solo funciona cuando --enable-logging es también pasada.
See also --enable-logging, --log-level, and --vmodule.
patternPermite que el nivel máximo por module de V-logging sobrepase el valor dado por --v. P.e. my_module=2,foo*=3 would change the logging level for all code in source files my_module.* and foo*.*.
Cualquier patrón que contenga una barra hacia adelante o una barra hacia atras será probado contra el nombre de la ruta completa y no solo contra el módulo. P.e. */foo/bar/*=2 would change the logging level for all code in the source files under a foo/bar directory.
Esta opción solo funciona cuando --enable-logging es también pasada.
See also --enable-logging, --log-level, and --v.
Force using discrete GPU when there are multiple GPUs available.
\nForce using integrated GPU when there are multiple GPUs available.
\nElectron soporta algunas de las CLI flags soportadas por Node.js.
\nNote: Passing unsupported command line switches to Electron when it is not running in ELECTRON_RUN_AS_NODE will have no effect.
Activate inspector on host:port and break at start of user script. Default host:port is 127.0.0.1:9229.
\nAliased to --debug-brk=[host:]port.
Set the host:port to be used when the inspector is activated. Useful when activating the inspector by sending the SIGUSR1 signal. Default host is 127.0.0.1.
Aliased to --debug-port=[host:]port.
Activate inspector on host:port. Por defecto es 127.0.0.1:9229.
V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug and profile Electron instances. The tools attach to Electron instances via a TCP port and communicate using the Chrome DevTools Protocol.
\nVea la guía de Debugging the Main Process para más detalles.
\nAliased to --debug[=[host:]port.
Specify ways of the inspector web socket url exposure.
\nBy default inspector websocket url is available in stderr and under /json/list endpoint on http://host:port/json/list.
", "title": "Cambios de línea de comandos soportados", "description": "Opciones de la linea de comandos soportados por Electron." }, "/docs/api/content-tracing": { "locale": "es-ES", "slug": "content-tracing", "href": "/docs/api/content-tracing", "crowdinFileId": "256297", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/content-tracing.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRecopile datos de rastreo del módulo de contenido de Chromium para encontrar cuellos de botella de rendimiento y operaciones lentas.
\n
Proceso: principal</0>
\nEste módulo no incluye una interfaz web. Para ver las huellas gravadas, use trace viewer, disponible en chrome://tracing en Chrome.
Note: You should not use this module until the ready event of the app module is emitted.
const { app, contentTracing } = require('electron')\n\napp.whenReady().then(() => {\n (async () => {\n await contentTracing.startRecording({\n included_categories: ['*']\n })\n console.log('Tracing started')\n await new Promise(resolve => setTimeout(resolve, 5000))\n const path = await contentTracing.stopRecording()\n console.log('Tracing data recorded to ' + path)\n })()\n})\nEl módulo contentTracing tiene los siguientes métodos:
contentTracing.getCategories()Devuelve Promise<String[]> - resuelve con un array de grupos de categorías una vez que todos los procesos hijos han confirmado la solicitud getCategories
Obtener un conjunto de grupos de categorías. La categoría de grupos puede cambiar a medida que se alcanza nuevas rutas de código. Ver también lista de categorías de seguimiento integradas.
\n\n\nNOTA: Electron añade una categoría de seguimiento no predeterminada llamada
\n\"electron\". Esta categoría se puede utilizar para capturar eventos de seguimiento específicos de Electron.
contentTracing.startRecording(options)options (TraceConfig | TraceCategoriesAndOptions)Devuelve Promise<void> - resuelto una vez que todos los procesos hijos han confirmado la solicitud startRecording.
Iniciar la grabación en todos los procesos.
\nLa grabación se inicia de manera inmediata de forma local y asincrónica en los procesos secundarios tan pronto como reciben la solicitud de habilitación de grabación.
\nSi una grabación ya está corriendo, la promesa será inmediatamente resulta, ya que sólo un operación de seguimiento puede estar en progrese a la vez.
\ncontentTracing.stopRecording([resultFilePath])resultFilePath String (opcional)Devuelve Promise<String> - resuleve con una ruta al archivo que contiene los datos rastreados una vez que los procesos hijos han reconocido la solicitud stopRecording
Dejar de grabar en todos los procesos.
\nLos procesos secundarios normalmente almacenan en caché los datos de rastreo y solo raramente limpian y envían datos de rastreo al proceso principal. Esto ayuda a minimizar la sobrecarga de tiempo de ejecución del rastreo ya que el envío de datos de rastreo a través de IPC puede ser una operación costosa. Por lo tanto, para finalizar un seguimiento, Chromium solicita de forma asíncrona a todos los procesos hijos que eliminen cualquier seguimiento de datos pendiente.
\nLos datos de rastreo se escribirán dentro de resultFilePath. Si resultFilePath está vacío o no es proporcionado, los datos de rastreo serán escrito en un archivo temporal, y la ruta será retornada en el promise.
contentTracing.getTraceBufferUsage()Devuelve Promise<Object> - Resuelve con un objeto conteniendo el value y percentage de máximo uso de trace buffer
value Númeropercentage NúmeroObtener el uso máximo a través de procesos de trace buffer como un porcentaje del estado completo.
", "title": "contentTracing", "description": "Recopile datos de rastreo del módulo de contenido de Chromium para encontrar cuellos de botella de rendimiento y operaciones lentas." }, "/docs/api/context-bridge": { "locale": "es-ES", "slug": "context-bridge", "href": "/docs/api/context-bridge", "crowdinFileId": "256299", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/context-bridge.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCree un puente seguro, bidireccional y sincrónico a través de contextos aislados
\n
Proceso: Renderer
\nA continuación se muestra un ejemplo de exponer una API a un renderer desde un script de precarga aislado:
\n// Preload (Isolated World)\nconst { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing')\n }\n)\n// Renderer (Main World)\n\nwindow.electron.doThing()\nEl \"Main World\" es el contexto de JavaScript que corre tu código renderer principal. Por defecto, la página que cargas en el tu renderer ejecuta código en este mundo.
\nCuando contextIsolation está activado en tu webPreferences (este es el comportamiento por defecto desde Electron 12.0.0), tus scripts preload corren en un \"Mundo aislado\". Puede leer más sobre aislamiento del contexto y que afecta en los documentos security.
El módulo contextBridge tiene los siguientes métodos:
contextBridge.exposeInMainWorld(apiKey, api)apiKey String - La clave para inyectar la API en la ventana window. La API será accesible en window[apiKey].api any - Tu API más información sobre qué puede ser esta API y como funciona esta disponible a continuación.La api proveeida a exposeInMainWorld debe ser una Function, String, Number, Array, Boolean, o un objeto cuya llaves son strings y los valores son una Function, String, Number, Array, Boolean, u otro objeto anidado que cumpa con las mismas condiciones.
Los valores Function se transfieren a otro contexto y todos los demás valores son copiados y congedados. Cualquier dato / primitivos enviado en la API se vuelve inmutable y las actualizaciones de una lado del puente no resulta en una actualización en el otro lado.
A continuación se muestra un ejemplo de una API compleja:
\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing'),\n myPromises: [Promise.resolve(), Promise.reject(new Error('whoops'))],\n anAsyncFunction: async () => 123,\n data: {\n myFlags: ['a', 'b', 'c'],\n bootTime: 1234\n },\n nestedAPI: {\n evenDeeper: {\n youCanDoThisAsMuchAsYouWant: {\n fn: () => ({\n returnData: 123\n })\n }\n }\n }\n }\n)\nLos valores de Function que enlazas a través de contextBridge son proxyados a través de Electron para asegurar que los contextos permanezcan aislados. Esto da como resultado algunas limitaciones claves que hemos descrito a continuación.
Dado que los parámetros, errores y valores de retorno son copiados cuando son enviados sobre el puente, solo hay ciertos tipos que pueden ser usados. En un nivel alto, si el tipo que desea usar se puede serializar y deserializar en el mismo objeto, funcionará. A continuación, se incluye una tabla de soporte de tipo para que esté completa:
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Tipo | Complejidad | Soporte de parámetros | Valor de Retorno Soportado | Limitaciones |
|---|---|---|---|---|
String | Simple | ✅ | ✅ | N/A |
Number | Simple | ✅ | ✅ | N/A |
Boolean | Simple | ✅ | ✅ | N/A |
Object | Complejo | ✅ | ✅ | Las llaves deben ser soportadas usando solo los tipos \"Simple\" en esta tabla. Los valores deben ser soportadas en esta tabla. Las modificaciones del prototipo se eliminan. Enviar clases personalizadas copiará valores pero no el prototipo. |
Array | Complejo | ✅ | ✅ | Mismas limitaciones para el tipo Object |
Error | Complejo | ✅ | ✅ | Los errores que se lanzan también se copian, esto puede resultar en que el mensaje y el seguimiento de la pila del error cambien ligeramente debido a que se lanzan en un contexto diferente |
Promise | Complejo | ✅ | ✅ | Las promesas solo se transfieren si son el valor de retorno o el parámetro exacto. Las promesas anidadas en arrays o objetos serán eliminadas. |
Function | Complejo | ✅ | ✅ | Las modificaciones del prototipo se eliminan. Enviar clases o constructores no funcionará. |
| Tipos Clonables | Simple | ✅ | ✅ | Veer el documento vinculado en tipos clonables |
Elemento | Complejo | ✅ | ✅ | Las modificaciones del prototipo se eliminan. Enviar elementos personalizados no funcionará. |
Blob | Complejo | ✅ | ✅ | N/A |
Símbolo | N/A | ❌ | ❌ | Los Symbols no pueden ser copiados a través de contextos así que son eliminados |
Si el tipo que te interesa no está en la tabla anterior, probablemente no esté soportado.
\nEl contextBridge puede ser utilizado por el script de precarga para dar acceso al renderizador a las APIs de Node. La tabla de tipos soportados descrita anteriormente aplica también a las APIs de Node que expongas a través de contextBridge. Tenga en cuenta que muchas APIs de Nodo conceden acceso a los recursos del sistema local. Se muy cauteloso sobre que APIs y globales expones a contenido remoto que no es de confianza.
const { contextBridge } = require('electron')\nconst crypto = require('crypto')\ncontextBridge.exposeInMainWorld('nodeCrypto', {\n sha256sum (data) {\n const hash = crypto.createHash('sha256')\n hash.update(data)\n return hash.digest('hex')\n }\n})\nContext Isolation is a feature that ensures that both your preload scripts and Electron's internal logic run in a separate context to the website you load in a webContents. This is important for security purposes as it helps prevent the website from accessing Electron internals or the powerful APIs your preload script has access to.
This means that the window object that your preload script has access to is actually a different object than the website would have access to. For example, if you set window.hello = 'wave' in your preload script and context isolation is enabled, window.hello will be undefined if the website tries to access it.
Context isolation has been enabled by default since Electron 12, and it is a recommended security setting for all applications.
\n\n\nWithout context isolation, I used to provide APIs from my preload script using
\nwindow.X = apiObject. Now what?
Exposing APIs from your preload script to a loaded website in the renderer process is a common use-case. With context isolation disabled, your preload script would share a common global window object with the renderer. You could then attach arbitrary properties to a preload script:
// preload with contextIsolation disabled\nwindow.myAPI = {\n doAThing: () => {}\n}\nThe doAThing() function could then be used directly in the renderer process:
// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nThere is a dedicated module in Electron to help you do this in a painless way. The contextBridge module can be used to safely expose APIs from your preload script's isolated context to the context the website is running in. The API will also be accessible from the website on window.myAPI just like it was before.
// preload with contextIsolation enabled\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n doAThing: () => {}\n})\n// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nPlease read the contextBridge documentation linked above to fully understand its limitations. For instance, you can't send custom prototypes or symbols over the bridge.
Just enabling contextIsolation and using contextBridge does not automatically mean that everything you do is safe. For instance, this code is unsafe.
// ❌ Bad code\ncontextBridge.exposeInMainWorld('myAPI', {\n send: ipcRenderer.send\n})\nIt directly exposes a powerful API without any kind of argument filtering. This would allow any website to send arbitrary IPC messages, which you do not want to be possible. The correct way to expose IPC-based APIs would instead be to provide one method per IPC message.
\n// ✅ Good code\ncontextBridge.exposeInMainWorld('myAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nSI está construyendo su aplicación Electron con TypeScript, querrá añadir tipos a sus APIs expuestas sobre el puente del contexto. El objeto window del renderizador no tendrá los tipos correctos a menos que extienda los tipos con un declaration file.
Por ejemplo, dado este script preload.ts:
contextBridge.exposeInMainWorld('electronAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nPuede crear un archivo de declaración renderer.d.ts y aumentar globalmente la interfaz Window:
export interface IElectronAPI {\n loadPreferences: () => Promise<void>,\n}\n\ndeclare global {\n interface Window {\n electronAPI: IElectronAPI\n }\n}\nAl hacerlo se asegurará que el compilador de TypeScript sepa sobre la propiedad electronAPI en su objeto global window al escribir scripts en su proceso renderizador:
window.electronAPI.loadPreferences()\nname String - The name of the cookie.value String - The value of the cookie.domain String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains.hostOnly Boolean (optional) - Whether the cookie is a host-only cookie; this will only be true if no domain was passed.path String (optional) - The path of the cookie.secure Boolean (optional) - Whether the cookie is marked as secure.httpOnly Boolean (optional) - Whether the cookie is marked as HTTP only.session Boolean (optional) - Whether the cookie is a session cookie or a persistent cookie with an expiration date.expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.sameSite String - The Same Site policy applied to this cookie. Can be unspecified, no_restriction, lax or strict.\n\nBusca y modifica las cookies de la sesión.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Las instancias de la clase Cookies son accedidas utilizado la propiedad cookies de una Session.
Por ejemplo:
\nconst { session } = require('electron')\n\n// Query all cookies.\nsession.defaultSession.cookies.get({})\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// Consulta todas las cookies asociadas con un url especifica.\nsession.defaultSession.cookies.get({ url: 'http://www.github.com' })\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// Establece un cookie con los datos de la misma.\n// puede sobrescriba cookies iguales si existen.\nconst cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }\nsession.defaultSession.cookies.set(cookie)\n .then(() => {\n // success\n }, (error) => {\n console.error(error)\n })\nLos siguientes eventos están disponibles en las instancias de Cookies:
Devuelve:
\neventcookie Cookie - La cookie que se ha cambiado.cause String - La causa del cambio con uno de los siguientes valores:explicit - La cookie se cambió directamente por la acción de un consumidor.overwrite - La cookie se eliminó automáticamente debido a una operación insertada que la sobreescribió.expired - La cookie se eliminó automáticamente debido a que expiró.evicted - La cookie fue desecha automáticamente durante la recolección de desechos.expired-overwrite - La cookie fue sobreescrita con una fecha de vencimiento ya expirada.removed Booleano - true si la cookie se eliminó, false si no lo hizo.Aparece cuando se cambia una cookie porque fue añadida, editada, eliminada o expirada.
\nLos siguientes métodos están disponibles en las instancias de Cookies:
cookies.get(filter)filterurl String (opcional) - Recupera las cookies las cuales están asociadas con la url. Vacío implica recuperar las cookies de todas las URLs.name Cadena (opcional) - Filtra las cookies por nombre.domain Cadena (opcional) - Recupera las cookies de cuyos dominios coinciden o son subdominios de domains.path Cadena (opcional) - Recupera las cookies de cuya ruta coincide con path.secure Booleano (opcional) - Filtra las cookies por su propiedad Secure.session Booleano (opcional) - Filtra las cookies fuera de la sesión o cookies persistentes.Returns Promise<Cookie[]> - Una promesa que resulve un array de objetos cookies.
Envía una solicitud para obtener todas las cookies que coincidan con filter, y resuelve una promesa con la respuesta.
cookies.set(details)details Objecturl String - La URL con la que asociar la cookie. La promise será rechazada si la URL es invalida.name String (opcional) - El nombre de la cookie. Vacío por defecto si se omite.value String (opcional) - El valor de la cookie. Vacío por defecto si se omite.domain String (optional) - El dominio de la cookie; este será normalizado por precediéndolo con un punto para que también sea valido para el uso de subdominios. Vacío por defecto si se omite.path String (opcional) - La ruta de la cookie. Vacío por defecto si se omite.secure Boolean (opcional) - Si la cookie debería ser marcado como Segura o no. Defaults to false unless Same Site=None attribute is used.httpOnly Boolean (opcional) - Si la cookie debería ser marcada como sólo HTTP. Por defecto es falso.expirationDate Doble (opcional) - La fecha de vencimiento de la cookie como el número de segundos desde la época UNIX. Si se omite, entonces la cookie cambia a una cookie de sesión y no se conservará entre sesiones.sameSite String (opcional) - La política del Mismo sitio para aplicar a esta cookie. Puede ser unspecified, no_restriction, lax o strict. Por defecto es no_restriction.Returns Promise<void> - Una promesa que resuelve cuando la cookie ha sido establecida
Establece una cookie con detalles.
cookies.remove(url, name)url Cadena - La URL asociada con la cookie.name Cadena - El nombre de la cookie que será eliminada.Devuelve Promise<void> - Una promesa que se resuelve cuando la cookie ha sido removida
Elimina las cookies que coinciden con url y name
cookies.flushStore()Devuelve Promise<void> - Una promesa que se resuelve cuando el almacenamiento de la cookie ha sido borrado
Escribe cualquier dato de cookies en el disco que no haya sido escrito.
", "title": "Clase: Cookies", "description": "Busca y modifica las cookies de la sesión." }, "/docs/api/structures/cpu-usage": { "locale": "es-ES", "slug": "cpu-usage", "href": "/docs/api/structures/cpu-usage", "crowdinFileId": "256419", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/cpu-usage.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "percentCPUUsage Number - Percentage of CPU used since the last call to getCPUUsage. First call returns 0.idleWakeupsPerSecond Number - The number of average idle CPU wakeups per second since the last call to getCPUUsage. First call returns 0. Will always return 0 on Windows.date Dateid Cadena\n\n\nEnvía los informes de fallos a un servidor remoto.
\n
El siguiente es un ejemplo de como configurar Electron para que envié automáticamente reportes de error a un servidor remoto:
\nconst { crashReporter } = require('electron')\n\ncrashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })\nPara configurar un servidor que acepte y procese los informes de fallos, se pueden utilizar los siguientes proyectos:
\n\nO utilice una solución alojada por terceros:
\n\nLos reportes de errores son almacenados temporalmente antes de ser alzados en un directorio debajo del directorio de datos del usuario (llamado 'Crashpad' en Windows y Mac o 'Crash Reports' en Linux). Puedes sobrescribir este directorio llamando a app.setPath('crashDumps', '/path/to/crashes') antes de iniciar al crash reporter.
En Windows y macOS, Electron usa crashpad para monitorear y reportar fallos. En Linux, Electron usa breakpad. Este es un detalle de implementación impulsado por Chromium y puede cambiar en el futuro. En particular, crashpad es más nuevo y es probable que eventualmente reemplace a breakpad en todas las plataformas.
\nIf you are using the Node.js child_process module and want to report crashes from those processes on Linux, there is an extra step you will need to take to properly initialize the crash reporter in the child process. This is not necessary on Mac or Windows, as those platforms use Crashpad, which automatically monitors child processes.
Since require('electron') is not available in Node child processes, the following APIs are available on the process object in Node child processes. Note that, on Linux, each Node child process has its own separate instance of the breakpad crash reporter. This is dissimilar to renderer child processes, which have a \"stub\" breakpad reporter which returns information to the main process for reporting.
process.crashReporter.start(options)process.crashReporter.getParameters()See crashReporter.getParameters().
process.crashReporter.addExtraParameter(key, value)See crashReporter.addExtraParameter(key, value).
process.crashReporter.removeExtraParameter(key)See crashReporter.removeExtraParameter(key).
El módulo crashReporter tiene los siguientes métodos:
crashReporter.start(options)options ObjectsubmitURL String (opcional) - URL a la que serán enviados los reportes de fallos como POST. Requerido a menos que uploadToServer sea false.productName String (opcional) - Por defecto app.name.companyName String (optional) Deprecated - Deprecated alias for { globalExtra: { _companyName: ... } }.uploadToServer Boolean (octional) - Si los reportes de fallos deberían ser enviados a un servidor. Si es false, los reportes de fallos serán recolectados y almacenados en un directorio de fallas, pero no serán subidos. Por defecto es true.ignoreSystemCrashHandler Boolean (opcional) - Si es true, los fallos generados en el main process no serán reenviados al gestor de gallos del sistema. Por defecto es false.rateLimit Boolean (opcional) macOS Windows - Si es true, limita el numero de fallos subidos a 1/hora. Por defecto es false.compress Boolean (opcional) - Si es true, los reportes de fallos serán comprimidos y subidos con Content-Encoding: gzip. Por defecto es true.extra Record<String, String> (opcional) - Extra string con anotaciónes clave/valor que serán enviados junto con los reportes de fallos en el main process. Sólo se admiten valores de cadena. Los fallos generados en los procesos hijos no contendrán estos parámetros extras, para reportes de fallos generados desde los procesos hijos, llame addExtraParameter desde el proceso hijo.globalExtra Record<String, String> (opcional) - Extra string con anotaciónes clave/valor que serán enviados junto con los reportes de fallos generados en cualquier proceso. Estas anotaciones no pueden ser cambiadas una vez que el crash reporter ha sido iniciado. Si una clave esta presente en los parámetros global extra y en los parámetros extra process-specific, entonces el parámetro global tomará precedencia. Por defecto, productName y la versión de la aplicación son incluidas, así como la versión de Electron.Este método debe ser llamada antes de usar cualquier otra APIs crashReporter. Una vez inicializado de esta manera, el crashpad handler recopila los fallos desde todos los procesos creados posteriormente. El crash reporter no puede ser desactiva una vez iniciado.
Este método debería ser llamado tan pronto como sea posible al iniciar la aplicación, preferentemente antes de app.on('ready'). Si el crash reporter no está iniciado al tiempo que un renderer process este creado, entonces ese renderer process no será monitoreado por el crash reporter.
Nota: Puedes probar el crash reporter generando un fallo usando process.crash().
Nota: Si necesitas enviar parámetros extra adicionales/actualizados después de tu primera llamada start puedes llamar a addExtraParameter.
Nota: Los parámetros pasados en extra, globalExtra o establecidos con addExtraParameter tienen un limite en la longitud de la llaves y los valores. Los nombre de la llaves deben ser como máximo de 39 bytes de largo, y los valores no deben ser mayor que 127 bytes. Las llaves con nombres más largo que el máximo serán ignoradas de forma silenciosa. Los valores de las llaves más largo que la longitud máxima serán truncados.
Nota: Este método solo está disponible en el proceso principal.
\ncrashReporter.getLastCrashReport()Devuelve CrashReport - La fecha y el ID del último reporte de error. Solo los reportes de fallos que han sido alzados serán retornados; incluso si un reporte de fallo esta presente en el disco este no sera retornado a menos que este alzado. En caso de que no haya reportes subidos, null es retornado.
Nota: Este método solo está disponible en el proceso principal.
\ncrashReporter.getUploadedReports()Devuelve CrashReport []:
Returns all uploaded crash reports. Each report contains the date and uploaded ID.
\nNota: Este método solo está disponible en el proceso principal.
\ncrashReporter.getUploadToServer()Returns Boolean - Whether reports should be submitted to the server. Set through the start method or setUploadToServer.
Nota: Este método solo está disponible en el proceso principal.
\ncrashReporter.setUploadToServer(uploadToServer)uploadToServer Boolean - Si los reportes deben enviarse o no al servidor.This would normally be controlled by user preferences. This has no effect if called before start is called.
Nota: Este método solo está disponible en el proceso principal.
\ncrashReporter.addExtraParameter(key, value)key String - La clave del parámetro, debe tener menos de 39 bytes.key String - La clave del parámetro, debe tener menos de 127 bytes.Establecer un parámetro adicional que se enviará con el informe de fallos. Los valores especificados aquí serán enviados, adicionalmente cualquier valor establecidos a través de la opción extra cuando fue llamado start.
Los parámetros agregados de esta manera (o a través del parámetro extra al crashReporter.start) son específicos del proceso de llamada. Agregar parámetros extras en el main process no causarán que esos parámetros sean enviado junto con los fallos del renderer u otros procesos hijos. De manera similar, agregar parámetros extras en un renderer process no dará como resultado que esos parámetros sean enviados con los fallos que ocurren en otros renderer processes o en el main process.
Nota: Los parámetros tienen límites de longitud de llaves y valores. Los nombre de la llaves deben ser como máximo de 39 bytes de largo, y los valores no deben ser mayor que 127 bytes. Las llaves con nombres más largo que el máximo serán ignoradas de forma silenciosa. Los valores de las llaves más largo que la longitud máxima serán truncados.
\nNota: En linux los valores que son más grandes que 127 bytes se dividirá en varias claves, cada una de 127 bytes de longitud. E.g. addExtraParameter('foo', 'a'.repeat(130)) will result in two chunked keys foo__1 and foo__2, the first will contain the first 127 bytes and the second will contain the remaining 3 bytes. En el backend de informes de fallos, debería unir las claves en este formato.
crashReporter.removeExtraParameter(key)key String - La clave del parámetro, debe tener menos de 39 bytes.Remove an extra parameter from the current set of parameters. Los fallos futuros no incluirán este parámetro.
\ncrashReporter.getParameters()Devuelve Record<String, String> - Los parámetros 'extra' actuales del reportador de errores.
El informador de fallos enviará la siguiente información al submitURL como un multipart/form-data POST:
ver Cadena- La versión de Electron.platform Cadena - por ejemplo, \"win32\".process_type Cadena - por ejemplo, \"renderizador\".guid String - por ejemplo, \"5e1286fc-da97-479e-918b-6bfb0c3d1c72\"._version Cadena - La versión en package.json._productName Cadena - El nombre del producto en el objeto crashReporter options.prod String - Nombre del producto subyacente. En esta caso Electron._companyName Cadena - El nombre de la empresa en el objeto crashReporter options.upload_file_minidump Archivo - El informe de fallos en el formato de minidump.extra en el objeto crashReporter options.scheme String - Custom schemes to be registered with options.privileges Object (optional)standard Boolean (optional) - Default false.secure Boolean (optional) - Default false.bypassCSP Boolean (optional) - Default false.allowServiceWorkers Boolean (optional) - Default false.supportFetchAPI Boolean (optional) - Default false.corsEnabled Boolean (optional) - Default false.stream Boolean (optional) - Default false.\"Native interfaces\" include the file picker, window border, dialogs, context menus, and more - anything where the UI comes from your operating system and not from your app. The default behavior is to opt into this automatic theming from the OS.
\nIf your app has its own dark mode, you should toggle it on and off in sync with the system's dark mode setting. You can do this by using the [prefer-color-scheme] CSS media query.
\nSi quieres cambiar manualmente entre los modos light/dark, puedes hacerlo configurando el modo deseado en la propiedad themeSource del módulo nativeTheme. This property's value will be propagated to your Renderer process. Any CSS rules related to prefers-color-scheme will be updated accordingly.
En macOS 10.14 Mojave, Apple introdujo un nuevo modo oscuro para todo el sistema en sus ordenadores macOS. If your Electron app has a dark mode, you can make it follow the system-wide dark mode setting using the nativeTheme api.
In macOS 10.15 Catalina, Apple introduced a new \"automatic\" dark mode option for all macOS computers. In order for the nativeTheme.shouldUseDarkColors and Tray APIs to work correctly in this mode on Catalina, you need to use Electron >=7.0.0, or set NSRequiresAquaSystemAppearance to false in your Info.plist file for older versions. Both Electron Packager and Electron Forge have a darwinDarkModeSupport option to automate the Info.plist changes during app build time.
If you wish to opt-out while using Electron > 8.0.0, you must set the NSRequiresAquaSystemAppearance key in the Info.plist file to true. Please note that Electron 8.0.0 and above will not let you opt-out of this theming, due to the use of the macOS 10.14 SDK.
This example demonstrates an Electron application that derives its theme colors from the nativeTheme. Additionally, it provides theme toggle and reset controls using IPC channels.
Starting with the index.html file:
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n <link rel=\"stylesheet\" type=\"text/css\" href=\"./styles.css\">\n</head>\n<body>\n <h1>Hello World!</h1>\n <p>Current theme source: <strong id=\"theme-source\">System</strong></p>\n\n <button id=\"toggle-dark-mode\">Toggle Dark Mode</button>\n <button id=\"reset-to-system\">Reset to System Theme</button>\n\n <script src=\"renderer.js\"></script>\n </body>\n</body>\n</html>\nAnd the styles.css file:
@media (prefers-color-scheme: dark) {\n body { background: #333; color: white; }\n}\n\n@media (prefers-color-scheme: light) {\n body { background: #ddd; color: black; }\n}\nThe example renders an HTML page with a couple elements. The <strong id=\"theme-source\"> element shows which theme is currently selected, and the two <button> elements are the controls. The CSS file uses the prefers-color-scheme media query to set the <body> element background and text colors.
The preload.js script adds a new API to the window object called darkMode. Esta API expone dos canales IPC al proceso renderizador, 'dark-mode:toggle' y 'dark-mode:system'. It also assigns two methods, toggle and system, which pass messages from the renderer to the main process.
const { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld('darkMode', {\n toggle: () => ipcRenderer.invoke('dark-mode:toggle'),\n system: () => ipcRenderer.invoke('dark-mode:system')\n})\nNow the renderer process can communicate with the main process securely and perform the necessary mutations to the nativeTheme object.
The renderer.js file is responsible for controlling the <button> functionality.
document.getElementById('toggle-dark-mode').addEventListener('click', async () => {\n const isDarkMode = await window.darkMode.toggle()\n document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'\n})\n\ndocument.getElementById('reset-to-system').addEventListener('click', async () => {\n await window.darkMode.system()\n document.getElementById('theme-source').innerHTML = 'System'\n})\nUsing addEventListener, the renderer.js file adds 'click' event listeners to each button element. Each event listener handler makes calls to the respective window.darkMode API methods.
Finally, the main.js file represents the main process and contains the actual nativeTheme API.
const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n\n ipcMain.handle('dark-mode:toggle', () => {\n if (nativeTheme.shouldUseDarkColors) {\n nativeTheme.themeSource = 'light'\n } else {\n nativeTheme.themeSource = 'dark'\n }\n return nativeTheme.shouldUseDarkColors\n })\n\n ipcMain.handle('dark-mode:system', () => {\n nativeTheme.themeSource = 'system'\n })\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nThe ipcMain.handle methods are how the main process responds to the click events from the buttons on the HTML page.
The 'dark-mode:toggle' IPC channel handler method checks the shouldUseDarkColors boolean property, sets the corresponding themeSource, and then returns the current shouldUseDarkColors property. Looking back on the renderer process event listener for this IPC channel, the return value from this handler is utilized to assign the correct text to the <strong id='theme-source'> element.
The 'dark-mode:system' IPC channel handler method assigns the string 'system' to the themeSource and returns nothing. This also corresponds with the relative renderer process event listener as the method is awaited with no return value expected.
Run the example using Electron Fiddle and then click the \"Toggle Dark Mode\" button; the app should start alternating between a light and dark background color.
\n
Si usted tiene bloqueos o problemas en Electron que cree que no son causados por la aplicación de JavaScript, sino por Electron, la depuración puede ser un poco difícil, especialmente para desarrolladores que no están acostumbrados a la depuración nativa/C++. Sin embargo, usando Visual Studio, el servidor de símbolos de Electron y el código fuente de Electron, puede habilitar la depuración paso a paso con puntos de ruptura dentro de código fuente de Electron.
\nVea también: hay una gran cantidad de información sobre la depuración de Chromium, mucha de la cual también se aplica a Electron, en el sitio de desarrolladores de Chromium: Debugging Chromium on Windows.
\nConstruir una depuración de Electron: la forma más fácil es usualmente que usted mismo lo construya, utilizando las herramientas y los requisitos previos enumerados en instrucciones de compilación para Windows. Aunque puede adjuntar y depurar Electrón a medida que lo descarga directamente, encontrará que está muy optimizado, lo que dificulta considerablemente la depuración: el depurador no podrá mostrarle el contenido de todas las variables y la ruta de ejecución puede parecer extraña debido a las llamadas en línea, las llamadas de cola y otras optimizaciones del compilador.
\nVisual Studio con herramientas de C++: las ediciones de la comunidad gratuitas de Visual Studio 2013 y 2015 funcionan. Una vez instalado, configure Visual Studio to use Electron's Symbol server. Le permitirá a Visual Studio obtener una mejor comprensión de lo que sucede dentro de Electron, haciendo que sea más fácil presentar las variables en un formato de lectura.
\nProcMon: la herramienta gratuita SysInternals le permite inspeccionar los parámetros de los procesos, los manejadores de archivos y las operaciones de registro.
\nPara iniciar una sesión de depuración, abra PowerShell/CMD y ejecute su versión de depuración de Electron, usando la aplicación para abrir como parámetro.
\n$ ./out/Debug/electron.exe ~/my-electron-app/\nLuego, abre Visual Studio. Electron no está construido con Visual Studio y, por lo tanto, no contiene un archivo de proyecto - sin embargo, usted puede abrir los archivos de código fuente \"Como archivo\", lo que significa que Visual Studio los abrirá por sí mismo. Usted puede todavía establecer puntos de interrupción - Visual Studio automáticamente descifrará que el código fuente coincide con el código que se ejecuta en el proceso adjunto y se romperá en consecuencia.
\nRelevant code files can be found in ./shell/.
Usted puede conectar el depurador de Visual Studio a un proceso en ejecución en una computadora local o remota. Después de que se esté ejecutando el proceso, haga clic en Depurar / Adjuntar al proceso (o presione CTRL+ALT+P) para abrir el cuadro de diálogo \"Adjuntar al proceso\". Usted puede usar esta capacidad para depurar aplicaciones que se ejecutan en una computadora local o remota, depurará múltiples procesos simultáneamente.
Si Electron se ejecuta con una cuenta de usuario diferente, seleccione mostrar procesos de todos los usuarios en la casilla. Tenga en cuenta que dependiendo de cuántos BrowserWindows su aplicación tenga abiertos, verá múltiples procesos. Una típica aplicación de una ventana dará como resultado que Visual Studio le presente dos entradas Electron.exe: una para el proceso principal y otra para el proceso renderizado. Dado que la lista solo le da nombres, actualmente no hay una forma confiable de descubrir cuál es cuál.
Código ejecutado dentro del proceso principal (es decir, código encontrado en o eventualmente ejecutado por su archivo JavaScript principal) se ejecutara dentro del proceso principal, mientras que otro código se ejecutara dentro de su respectivo proceso renderer.
\nPuede estar conectado a varios programas cuando se está depurando, pero solamente un programa está activo en el depurador en cualquier momento. Puedes configurar el programa activo en la barra de herramientas Ubicación de depuración o en la ventana de procesos.
Mientras que Visual Studio es fantástico para inspeccionar rutas de código específicas, la fortaleza de ProcMon está realmente en observar todo lo que su aplicación está haciendo con el sistema operativo: captura los detalles de archivo, registro, red, proceso y perfil detallado de los procesos. Intenta registrar todos los eventos que se producen y puede ser bastante abrumador, pero si intenta comprender qué y cómo está trabajando su aplicación en el sistema operativo, puede ser un recurso valioso.
\nPara obtener una introducción a las funciones de depuración básicas y avanzadas de ProcMon, consulte el video proveído por Microsoft this video tutorial.
", "title": "Depuración en Windows", "description": "" }, "/docs/api/debugger": { "locale": "es-ES", "slug": "debugger", "href": "/docs/api/debugger", "crowdinFileId": "256305", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/debugger.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nUn transporte alternativo para el protocolo de depuración remoto de Chrome.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Las herramientas para desarrolladores de Chrome tiene un special binding disponible en JavaScript runtime que permite interactuar con las páginas y equiparlas.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\ntry {\n win.webContents.debugger.attach('1.1')\n} catch (err) {\n console.log('Debugger attach failed : ', err)\n}\n\nwin.webContents.debugger.on('detach', (event, reason) => {\n console.log('Debugger detached due to : ', reason)\n})\n\nwin.webContents.debugger.on('message', (event, method, params) => {\n if (method === 'Network.requestWillBeSent') {\n if (params.request.url === 'https://www.github.com') {\n win.webContents.debugger.detach()\n }\n }\n})\n\nwin.webContents.debugger.sendCommand('Network.enable')\nDevuelve:
\neventreason Cadena - Razón para desasociar el depurador.Emitido cuando la sesión de depuración es terminada. Esto ocurre cuando webContents es cerrado o el devtools es invocado para el webContents adjunto.
Devuelve:
\neventmethod Cadena- Nombre del método.params any - Event parameters defined by the 'parameters' attribute in the remote debugging protocol.sessionId String - Unique identifier of attached debugging session, will match the value sent from debugger.sendCommand.Emitido cada vez que el objetivo de depuración emite un evento de instrumentación.
\ndebugger.attach([protocolVersion])protocolVersion Cadena (opcional) - Versión solicitada del protocolo de depuración.Adjunta el depurador al webContents.
debugger.isAttached()Devuelve Boolean - Si un depurador se adjunta o no a la webContents.
debugger.detach()Desasocia el depurador de la webContents.
debugger.sendCommand(method[, commandParams, sessionId])method String - Method name, should be one of the methods defined by the remote debugging protocol.commandParams any (opcional) - Objeto JSON con parámetros de la solicitud.sessionId String (optional) - send command to the target with associated debugging session id. The initial value can be obtained by sending Target.attachToTarget message.Devuelve Promise<any> - Una promesa que resuelve con la respuesta definida por el atributo 'returns' del comando de descripción en el protocolo de depuración remoto o es rechazada indicando el fallo del comando.
Envía el comando al objetivo de la depuración.
", "title": "Clase: Debugger", "description": "Un transporte alternativo para el protocolo de depuración remoto de Chrome." }, "/docs/development/debugging-instructions-macos": { "locale": "es-ES", "slug": "debugging-instructions-macos", "href": "/docs/development/debugging-instructions-macos", "crowdinFileId": "256153", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Si usted tiene bloqueos o problemas en Electron que cree que no son causados por la aplicación de JavaScript, sino por Electron, la depuración puede ser un poco difícil, especialmente para desarrolladores que no están acostumbrados a la depuración nativa/C++. Sin embargo, usando lldb y el código fuente de Electron, puede habilitar la depuración paso a paso con puntos de interrupción dentro del código fuente de Electron. También puede usar XCode for debugging si prefiere una interfaz gráfica.
\nConstrucción de una depuración de Electron: La manera más fácil usualmente es construirlo usted mismo, usando las herramientas y prerrequisitos especificados en el Instrucciones de construcción para macOS. Aunque puede adjuntar y depurar Electrón a medida que lo descarga directamente, encontrará que está muy optimizado, lo que dificulta considerablemente la depuración: el depurador no podrá mostrarle el contenido de todas las variables y la ruta de ejecución puede parecer extraña debido a las llamadas en línea, las llamadas de cola y otras optimizaciones del compilador.
\nCódigo X: adicional al código X, también instala las herramientas del comando de linea de este. Incluyen LLDB, el depurador predeterminado en Xcode en macOS. Admite depuración de C, Objective-C y C++ en el escritorio y los dispositivos y simuladores iOS.
\n.lldbinit: Crear o editar ~/.lldbinit para permitir que el código de Chromium sea correctamente mapeado de fuentes.
# p. ej.: [' ~/electron/src/tools/lldb ']\nscript sys. Path [: 0] = ['<... path/to/electron/src/tools/lldb>']\nscript import lldbinit\nPara empezar una sesión de depuración, abra el terminal e inicie lldb, pasando al constructo de depuración de Electron como un parámetro.
$ lldb ./out/Testing/Electron.app\n(lldb) target create \"./out/Testing/Electron.app\"\nCurrent executable set to './out/Testing/Electron.app' (x86_64).\nLLDB es una herramienta poderosa y soporta múltiples estrategias para la inspección de código. Para esta instrucción básica, asumamos que está llamando un comando para JavaScript que no se está comportando correctamente - así que a usted le gustaría separarlo en la contraparte de esos comandos en C++ dentro de la fuente Electron.
\nRelevant code files can be found in ./shell/.
Asumamos que quiere depurar app.setName(), el cual está definido en browser.cc como Browser::SetName(). Configure un punto de separación usando el comando breakpoint, especificando el archivo y la linea que quiere separar:
(lldb) breakpoint set --file browser.cc --line 117\nBreakpoint 1: where = Electron Framework`atom::Browser::SetName(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) + 20 at browser.cc:118, address = 0x000000000015fdb4\nLuego, inicie Electron:
\n(lldb) run\nLa aplicación será pausada inmediatamente, mientras Electron configura el nombre de esta en el lanzador:
\n(lldb) run\nProcess 25244 launched: '/Users/fr/Code/electron/out/Testing/Electron.app/Contents/MacOS/Electron' (x86_64)\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1\n frame #0: 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118\n 115 }\n 116\n 117 void Browser::SetName(const std::string& name) {\n-> 118 name_override_ = name;\n 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n(lldb)\nPara mostrar los argumentos y las variables locales para la estructura actual, corra variable de estructura (o fr v), que le mostrará que la aplicación está siendo configurada con el nombre de \"Electron\".
(lldb) frame variable\n(atom::Browser *) this = 0x0000000108b14f20\n(const string &) name = \"Electron\": {\n [...]\n}\nPara hacer un solo paso en el nivel de la fuente en el hilo seleccionado, ejecute paso (o s). Esto lo llevará dentro de name_override_.empty(). Para proceder y dar otro paso, corra siguiente (o n).
(lldb) step\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119, queue = 'com.apple.main-thread', stop reason = step in\n frame #0: 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119\n 116\n 117 void Browser::SetName(const std::string& name) {\n 118 name_override_ = name;\n-> 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n 122 return badge_count_;\nNOTA: Si no ves el código fuente cuando crees que deberías, es posible que no hayas añadido el archivo ~/.lldbinit anterior.
Para finalizar la depuración en este punto, corra continuar proceso. También puede continuar hasta cierta linea es tocada en este hilo (hilo hasta 100). Este comando correrá el hilo en la estructura actual hasta que alcance la linea 100 en este, o se detiene si deja la estructura en la que se encuentra.
Ahora, si abre las herramientas para desarrolladores y llama setName, alcanzará de nuevo el punto de interrupción.
LLDB es una herramienta poderosa con una gran documentación. Para aprender más sobre esto, considera leer la documentación sobre la depuración de Apple, como LLDB Command Structure Reference o la introducción de Using LLDB as a Standalone Debugger.
\nYou can also check out LLDB's fantastic manual and tutorial, which will explain more complex debugging scenarios.
", "title": "Depuración en macOS", "description": "" }, "/docs/development/debugging-instructions-macos-xcode": { "locale": "es-ES", "slug": "debugging-instructions-macos-xcode", "href": "/docs/development/debugging-instructions-macos-xcode", "crowdinFileId": "256151", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos-xcode.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Ejecutar gn gen con el argumento --ide=xcode.
$ gn gen out/Testing --ide=xcode\nEsto generará el electron.ninja.xcworkspace. Tendrás que abrir este espacio de trabajo para establecer puntos de interrupción e inspeccionar.
\nVea gn help gen para más información sobre la generación de proyectos IDE con GN.
Inicia la aplicación Electron después de construir. You can now open the xcode workspace created above and attach to the Electron process through the Debug > Attach To Process > Electron debug menu. [Nota: Si usted quiere depurar el proceso renderizador, necesita adjuntar al Helper de Electron también.]
\nAhora puede establecer puntos de interrupción en cualquiera de los archivos indexados. Sin embargo, no podrás establecer puntos de interrupción directamente en la fuente Chromium. To set break points in the Chromium source, you can choose Debug > Breakpoints > Create Symbolic Breakpoint and set any function name as the symbol. Esto establecerá el punto de interrupción para todas las funciones con ese nombre, de todas las clases si hay más de una. También puedes hacer este paso de establecer puntos de interrupción antes de adjuntar el depurador, sin embargo, los puntos de interrupción reales para funciones simbólicas de punto de interrupción pueden no aparecer hasta que el depurador esté adjuntado a la aplicación.
", "title": "Depurar con XCode", "description": "" }, "/docs/tutorial/debugging-main-process": { "locale": "es-ES", "slug": "debugging-main-process", "href": "/docs/tutorial/debugging-main-process", "crowdinFileId": "256189", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/debugging-main-process.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "DevTools en una ventana del navegador Electron solo puede depurar JavaScript ejecutado en esa ventana (es decir, las páginas web). Para depurar JavaScript que es ejecutado en el proceso principal, se necesita utilizar un depurador externo y ejecutar Electron con el switch --inspect o --inspect-brk.
Use uno de los siguientes interruptores de línea de comando para habilitar la depuración del proceso principal:
\n--inspect=[port]Electron will listen for V8 inspector protocol messages on the specified port, an external debugger will need to connect on this port. The default port is 5858.
electron --inspect=5858 your/app\n--inspect-brk=[port]Como --inspect pero pausa la ejecución en la primera línea de JavaScript.
Tendrá que usar un depurador que admita el protocolo de inspector V8.
\nchrome://inspect y selecciona inspeccionar en la aplicación de Electron ejecutada allí presente.This guide goes over how to set up VSCode debugging for both your own Electron project as well as the native Electron codebase.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json con la siguiente configuración:{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"Debug Main Process\",\n \"type\": \"node\",\n \"request\": \"launch\",\n \"cwd\": \"${workspaceFolder}\",\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron\",\n \"windows\": {\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron.cmd\"\n },\n \"args\" : [\".\"],\n \"outputCapture\": \"std\"\n }\n ]\n}\nSet some breakpoints in main.js, and start debugging in the Debug View. You should be able to hit the breakpoints.
Aquí hay un proyecto preconfigurado que puede descargar y depurar directamente en VSCode: https://github.com/octref/vscode-electron-debug/tree/master/electron-quick-start
\nIf you want to build Electron from source and modify the native Electron codebase, this section will help you in testing your modifications.
\nFor those unsure where to acquire this code or how to build it, Electron's Build Tools automates and explains most of this process. Si desea establecer el entorno manualmente, en su lugar puede utilizar estas build instructions.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json con la siguiente configuración:{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"(Windows) Launch\",\n \"type\": \"cppvsdbg\",\n \"request\": \"launch\",\n \"program\": \"${workspaceFolder}\\\\out\\\\your-executable-location\\\\electron.exe\",\n \"args\": [\"your-electron-project-path\"],\n \"stopAtEntry\": false,\n \"cwd\": \"${workspaceFolder}\",\n \"environment\": [\n {\"name\": \"ELECTRON_ENABLE_LOGGING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_ENABLE_STACK_DUMPING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_RUN_AS_NODE\", \"value\": \"\"},\n ],\n \"externalConsole\": false,\n \"sourceFileMap\": {\n \"o:\\\\\": \"${workspaceFolder}\",\n },\n },\n ]\n}\nConfiguration Notes
\ncppvsdbg requires the built-in C/C++ extension be enabled.${workspaceFolder} is the full path to Chromium's src directory.your-executable-location will be one of the following depending on a few items:Testing: Si esta utilizando las configuraciones por defecto de Electron's Build-Tools o las instrucciones por defecto cuando building from source.Release: If you built a Release build rather than a Testing build.your-directory-name: If you modified this during your build process from the default, this will be whatever you specified.args array string \"your-electron-project-path\" should be the absolute path to either the directory or main.js file of the Electron project you are using for testing. In this example, it should be your path to electron-quick-start.Set some breakpoints in the .cc files of your choosing in the native Electron C++ code, and start debugging in the Debug View.
", "title": "Depurando en VSCode", "description": "" }, "/docs/api/desktop-capturer": { "locale": "es-ES", "slug": "desktop-capturer", "href": "/docs/api/desktop-capturer", "crowdinFileId": "256307", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/desktop-capturer.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n\nAccess information about media sources that can be used to capture audio and video from the desktop using the
\nnavigator.mediaDevices.getUserMediaAPI.
En el siguiente ejemplo se muestra cómo capturar vídeo desde una ventana de escritorio cuyo título es Electron:
// En el proceso de renderizado.\nconst { desktopCapturer } = require('electron')\n\ndesktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources => {\n for (const source of sources) {\n if (source.name === 'Electron') {\n try {\n const stream = await navigator.mediaDevices.getUserMedia({\n audio: false,\n video: {\n mandatory: {\n chromeMediaSource: 'desktop',\n chromeMediaSourceId: source.id,\n minWidth: 1280,\n maxWidth: 1280,\n minHeight: 720,\n maxHeight: 720\n }\n }\n })\n handleStream(stream)\n } catch (e) {\n handleError(e)\n }\n return\n }\n }\n})\n\nfunction handleStream (stream) {\n const video = document.querySelector('video')\n video.srcObject = stream\n video.onloadedmetadata = (e) => video.play()\n}\n\nfunction handleError (e) {\n console.log(e)\n}\nTo capture video from a source provided by desktopCapturer the constraints passed to navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop', and audio: false.
To capture both audio and video from the entire desktop the constraints passed to navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop', for both audio and video, but should not include a chromeMediaSourceId constraint.
const constraints = {\n audio: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n },\n video: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n }\n}\nEl módulo desktopCapturer tiene los siguientes métodos:
desktopCapturer.getSources(options)options Objecttypes String[] - Un arreglo de cadenas que crea una lista de los tipos de fuentes de escritorio para ser capturadas. Los tipos disponibles son screen y window.thumbnailSize Size (opcional) - El tamaño de la miniatura de la fuente al cual deber ser escalado. Por defecto es 150 x 150. Establecer ancho o alto a 0 cuando no necesitas las miniaturas. Esto guardara el tiempo de procesamiento requerido para capturar el contenido de cada ventana y pantalla.fetchWindowIcons Boolean (opcional) - Establece a true para activar la obtención de los iconos de ventana. El valor por defecto es falso. Cuando es false la propiedad appIcon de las fuentes devuelve null. Mismo si una fuente tiene el tipo pantalla.Devuelve Promise<DesktopCapturerSource[]> - Resuelve con un array de objetos DesktopCapturerSource, cada DesktopCapturerSource representa una pantalla o una ventana individual que puede ser capturada.
Note Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher, which can detected by systemPreferences.getMediaAccessStatus.
navigator.mediaDevices.getUserMedia no trabaja en macOS para captura de audio debido a una limitación fundamental porque las aplicaciones que quieren acceder al audio del sistema requieren un signed kernel extension. Chromium, y por extensión Electron, no proporciona esto.
Es posible eludir esta limitación capturando el audio del sistema con otra aplicación macOS como Soundflower y pasar esto a través de una dispositivo de entrada de audio virtual. Este dispositivo virtual puede ser consultado con navigator.mediaDevices.getUserMedia.
id String - The identifier of a window or screen that can be used as a chromeMediaSourceId constraint when calling [navigator.webkitGetUserMedia]. The format of the identifier will be window:XX:YY or screen:ZZ:0. XX is the windowID/handle. YY is 1 for the current process, and 0 for all others. ZZ is a sequential number that represents the screen, and it does not equal to the index in the source's name.name String - A screen source will be named either Entire Screen or Screen <index>, while the name of a window source will match the window title.thumbnail NativeImage - A thumbnail image. Note: There is no guarantee that the size of the thumbnail is the same as the thumbnailSize specified in the options passed to desktopCapturer.getSources. The actual size depends on the scale of the screen or window.display_id String - A unique identifier that will correspond to the id of the matching Display returned by the Screen API. On some platforms, this is equivalent to the XX portion of the id field above and on others it will differ. It will be an empty string if not available.appIcon NativeImage - An icon image of the application that owns the window or null if the source has a type screen. The size of the icon is not known in advance and depends on what the application provides.Al igual que los navegadores basados en Chromium, Electron proporciona acceso al dispositivo del hardware a través de las APIs web. En la mayor parte estas APIs trabajan como lo hacen en un navegador, pero hay algunas diferencias que necesitan ser tomadas en cuenta. La diferencia principal entre Electron y los navegadores es lo que ocurre cuando el acceso al dispositivo es solicitado. En un navegador, a los usuarios se le presenta una ventana emergente donde ellos puede otorgar acceso a un dispositivo individual. En Electron, se proporcionan APIs que un desarrollador puede utilizar para elegir automáticamente un dispositivo o para solicitar a los usuarios que elijan un dispositivo a través de una interfaz creada por el desarrollador.
\nLa Web Bluetooth API puede ser utilizada para comunicarse con dispositivos bluetooth. Para poder utilizar esta API en Electron, los desarrolladores necesitan manejar el evento select-bluetooth-device en el webContents asociado con la solicitud del dispositivo.
Este ejemplo demuestra un aplicación Electron que automáticamente selecciona el primer dispositivo bluetooth disponible cuando el botón Test Bluetooth es pulsado.
La WebHID API puede ser usada para acceder a dispositivos HID tales como teclados y gamepads. Electron proporciona varias APIs, para trabajar con la API WebHID:
\nselect-hid-device en la Session puede ser usado para seleccionar un dispositivo HID cuando se hace una llamada a navigator.hid.requestDevice. Adicionalmente, los eventos hid-device-added y hid-device-removed en la Session pueden ser utilizados para manejar dispositivos que se conectan o desconectan durante el proceso navigator.hid.requestDevice.ses.setDevicePermissionHandler(handler) puede ser utilizado para proveer permisos predeterminados a los dispositivos sin llamar primero para obtener permiso a dispositivo a través de navigator.hid.requestDevice. Adicionalmente el comportamiento por defecto de Electron es almacenar el permiso de dispositivo concedido a través de la vida útil del correspondiente WebContents. Si se necesita almacenamiento a más largo plazo, un desarrollado puede almacenar los permisos de dispositivos otorgados (pj cuando se maneja el evento select-hid-device) y luego leer desde ese almacenamiento con setDevicePermissionHandler.ses.setPermissionCheckHandler(handler) puede ser usado para desactivar el acceso a HID a orígenes específicos.Por defecto Electron emplea la misma blocklist usada por Chromium. Si desea anular este comportamiento, puede hacerlo estableciendo la bandera disable-hid-blocklist:
app.commandLine.appendSwitch('disable-hid-blocklist')\nEste ejemplo demuestra una aplicación Electron que automáticamente selecciona dispositivos HID a través de ses.setDevicePermissionHandler(handler) y a través del evento select-hid-device en la Session cuando el botón Test WebHID es pulsado.
La Web Serial API puede ser utilizada para acceder a dispositivos seriales que están conectados a través de la puerta serial, USB, or Bluetooth. Para utilizar esta API en Electron, los desarrolladores necesitan manejar el evento select-serial-port en la Session asociado con la solicitud de puerto serial.
Hay varias APIs adicionales para trabajar con la API Web Serial:
\nserial-port-added y serial-port-removed en la Session pueden ser usados para maenjar dispositivos que están conectados o desconectados durante el proceso navigator.serial.requestPort.ses.setPermissionCheckHandler(handler) puede ser usado para desactivar el acceso serial a orígenes específicos.Este ejemplo demuestra una aplicación Electron que automáticamente selecciona el primer dispositivo serial Arduino Uno (si está conectado) a través del evento select-serial-port en la Session cuando el botón Test Web Serial es pulsado.
Electron soporta Chrome DevTools extensions, las cuales pueden ser usadas para extender las funcionalidades de las herramientas de desarrollo de Chrome para depurar web frameworks populares.
\nLa forma más fácil de cargar una extensión DevTools es utilizar herramientas de terceros para automatizar el proceso por usted. electron-devtools-installer es un popular paquete NPM que hace justamente eso.
\nSi no quiere usar el enfoque de herramientas, también puede hacer todas las operaciones necesarias a mano. Para cargar una extensión en Electron, necesitas descargarlo a través Chrome, localiza la ruta de su sistema de archivo y luego cárgalo dentro de tu Session llamando a la API [ses.loadExtension].
Usando el React Developer Tools como un ejemplo:
\nInstala la extensión en Google Chrome.
\nAcceder a chrome://extensions, e identificar el ID de la extensión, que es una cadena de texto como fmkadmapgofadopljbjfkapdkoienihi.
Encuentra la ubicación del sistema de archivo usado por Chrome para alamacenar las extensiones:
\n%LOCALAPPDATA%\\Google\\Chrome\\User Data\\Default\\Extensions;~/.config/google-chrome/Default/Extensions/~/.config/google-chrome-beta/Default/Extensions/~/.config/google-chrome-canary/Default/Extensions/~/.config/chromium/Default/Extensions/~/Library/Application Support/Google/Chrome/Default/Extensions.Pasa la ubicación de la extensión a la API ses.loadExtension. Para React Developer Tools v4.9.0, se ve algo como:
const { app, session } = require('electron')\n const path = require('path')\n const os = require('os')\n\n // on macOS\n const reactDevToolsPath = path.join(\n os.homedir(),\n '/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.9.0_0'\n )\n\n app.whenReady().then(async () => {\n await session.defaultSession.loadExtension(reactDevToolsPath)\n })\nNotas:
\nloadExtension devuelve una Promise con un Extension object, que contiene metadatos sobre la extensión que fue cargada. Esta promise necesita resolver (p. ej. con una expresión await) antes de cargar una página. De lo contrario, no estará garantizada la carga de la extensión.loadExtension no puede ser llamada antes de que el evento ready del módulo appsea emitido, ni puede ser llamado en sesiones en memoria (no persistente).loadExtension debe ser llamado en cada arranque de tu aplicación si quieres que la extensión sea cargada.Puedes pasar la ID de la extensión a la API ses.removeExtension para eliminarla de tu Session. Las extensiones cargadas no son persistidas entre los lanzamientos de la aplicación.
Electron sólo soporta un limitado conjunto de APIs de chrome.*, así que las extensiones usando APIs de chrome.* no soportadas bajo el capo puede que no funcione.
Las siguientes extensiones Devtools han siso probadas para funcionar en Electron:
\nPrimero, por favor asegúrese que la extensión todavía sigue siendo mantenida y es compatible con la última versión de Google Chrome. No podemos proveer soporte adicional para extensiones no soportadas.
\nSi la extensión funciona en Chrome pero no en Electron, registra el error en el issue tracker de Electron y describe que parte de la extensión no esta funcionando como se espera.
", "title": "Extensión de herramientas de desarrollo", "description": "" }, "/docs/api/dialog": { "locale": "es-ES", "slug": "dialog", "href": "/docs/api/dialog", "crowdinFileId": "256309", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/dialog.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nMuestra diálogos nativos del sistema para abrir y guardar archivos, alertas, etc.
\n
Proceso: principal</0>
\nUn ejemplo de mostrar un dialogo para seleccionar múltiples archivos:
\nconst { dialog } = require('electron')\nconsole.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))\nEl módulo dialogo tiene los siguientes métodos:
dialog.showOpenDialogSync([browserWindow, ]options)browserWindowBrowserWindow(opcional)options Objecttítulo cadena (opcional)defaultPath Cadena (optional)buttonLabel cadena (optional) - Etiqueta predeterminada para el botón de confirmación, cuando esta se deja vacía la etiqueta predeterminada será usada.filters FileFilter[] (optional)properties String[] (optional) - Contains which features the dialog should use. Los siguientes valores son soportados:openFile - Le permite a los archivos ser seleccionados.openDirectory - Le permite a los directorios ser seleccionados.multiSelections - Permite que varios caminos sean seleccionados.showHiddenFiles - Muestra archivos ocultos en diálogo.createDirectory macOS- Permite crear nuevos directorios a partir del diálogo.promptToCreate Windows - Aviso para la creación si la ruta de fichero insertado en el diálogo no existe. Esto no crea realmente un archivo en el camino pero permite a caminos no existentes a regresar que deberían ser creados por la aplicación.noResolveAliases macOS - Deshabilite la resolución automática de la ruta de alias (enlace simbólico). Los alias seleccionados ahora devolverán la ruta de alias en lugar de la ruta de destino.treatPackageAsDirectory macOS - Trata paquetes como carpetas .app, como un directorio en vez de como un fichero.dontAddToRecent Windows - No agregar el elemento que se esta abriendo a la lista de documentos recientes.message Cadena (opcional) macOS - Mensaje a mostrar encima de las cajas de entrada.securityScopedBookmarks Boolean (opcional) macOS mas - Crear marcadores con ámbito de seguridad cuando es empaquetado para la Mac App Store.Devuelve String[] | undefined, la ruta del archivo elegido por el usuario, si el diálogo es cancelado devuelve undefined.
El argumento de browserWindow permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad.
The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Por ejemplo:
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nLos extensions arreglos deberían contener extensiones sin comodines o puntos (e.g. 'png' es bueno, pero '.png' y '*.png' son malos). Para mostrar todos los archivos, usa el '*' comodín (ningún otro comodín es compatible).
Nota: En Windows y Linux, un diálogo abierto no puede ser un selector de archivo y un selector de directorio a la vez, así que si estableces properties a el ['openFile', 'openDirectory'] en estas plataformas, un selector de directorio.
dialog.showOpenDialogSync(mainWindow, {\n properties: ['openFile', 'openDirectory']\n})\ndialog.showOpenDialog([browserWindow, ]options)browserWindowBrowserWindow(opcional)options Objecttítulo cadena (opcional)defaultPath Cadena (optional)buttonLabel cadena (optional) - Etiqueta predeterminada para el botón de confirmación, cuando esta se deja vacía la etiqueta predeterminada será usada.filters FileFilter[] (optional)properties String[] (optional) - Contains which features the dialog should use. Los siguientes valores son soportados:openFile - Le permite a los archivos ser seleccionados.openDirectory - Le permite a los directorios ser seleccionados.multiSelections - Permite que varios caminos sean seleccionados.showHiddenFiles - Muestra archivos ocultos en diálogo.createDirectory macOS- Permite crear nuevos directorios a partir del diálogo.promptToCreate Windows - Aviso para la creación si la ruta de fichero insertado en el diálogo no existe. Esto no crea realmente un archivo en el camino pero permite a caminos no existentes a regresar que deberían ser creados por la aplicación.noResolveAliases macOS - Deshabilite la resolución automática de la ruta de alias (enlace simbólico). Los alias seleccionados ahora devolverán la ruta de alias en lugar de la ruta de destino.treatPackageAsDirectory macOS - Trata paquetes como carpetas .app, como un directorio en vez de como un fichero.dontAddToRecent Windows - No agregar el elemento que se esta abriendo a la lista de documentos recientes.message Cadena (opcional) macOS - Mensaje a mostrar encima de las cajas de entrada.securityScopedBookmarks Boolean (opcional) macOS mas - Crear marcadores con ámbito de seguridad cuando es empaquetado para la Mac App Store.Devuelve Promise<Object> - Resuelve con un objeto conteniendo lo siguiente:
canceled Boolean - si el diálogo fue o no cancelado.filePaths Cadena[] - Un arreglo del camino de archivos elegido por el usuario. Si es dialog es cancelado esto será un array vacío.bookmarks String[] (optional) macOS mas - An array matching the filePaths array of base64 encoded strings which contains security scoped bookmark data. securityScopedBookmarks debe estar activado para ser poblado. (Para devolver valores, vea tabla aquí.)El argumento de browserWindow permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad.
The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Por ejemplo:
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nLos extensions arreglos deberían contener extensiones sin comodines o puntos (e.g. 'png' es bueno, pero '.png' y '*.png' son malos). Para mostrar todos los archivos, usa el '*' comodín (ningún otro comodín es compatible).
Nota: En Windows y Linux, un diálogo abierto no puede ser un selector de archivo y un selector de directorio a la vez, así que si estableces properties a el ['openFile', 'openDirectory'] en estas plataformas, un selector de directorio.
dialog.showOpenDialog(mainWindow, {\n properties: ['openFile', 'openDirectory']\n}).then(result => {\n console.log(result.canceled)\n console.log(result.filePaths)\n}).catch(err => {\n console.log(err)\n})\ndialog.showSaveDialogSync([browserWindow, ]options)browserWindowBrowserWindow(opcional)options Objecttitle Cadena (opcional) - Título del diálogo. No puede mostrarse en algunos entornos de escritorio de Linux.defaultPath Cadena (opcional) - El camino de directorio absoluto, el camino de archivo absoluto o el nombre del archivo a usar por defecto.buttonLabel cadena (optional) - Etiqueta predeterminada para el botón de confirmación, cuando esta se deja vacía la etiqueta predeterminada será usada.filters FileFilter[] (optional)message Cadena (opcional) macOS - Mensaje a mostrar por encima de los campos de texto.nameFieldLabel Cadena (opcional) macOS - Etiqueta personalizada para el texto mostrado en frente al nombre del archivo del campo de texto.showsTagField Boolean (opcional) macOS - Muestra las etiquetas de las cajas de entrada, por defecto a true.properties String[] (optional)showHiddenFiles - Muestra archivos ocultos en diálogo.createDirectory macOS- Permite crear nuevos directorios a partir del diálogo.treatPackageAsDirectory macOS - Trata paquetes como carpetas .app, como un directorio en vez de como un fichero.showOverwriteConfirmation Linux - Establece si al usuario será presentado un dialogo de confirmación si escribe el nombre de un archivo que ya existe.dontAddToRecent Windows - No añadir el elemento que se está guardando en la lista de documentos recientes.securityScopedBookmarks Boolean (opcional) macOS mas - Crear un security scoped bookmark es empaquetado para el Mac App Store. Si esta opción está activada y el fichero no existe todavía, se creará un fichero en blanco en la carpeta seleccionada.Devuelve String | undefined, la ruta del archivo elegido por el usuario; si el cuadro de dialogo es cancelado retorna undefined.
El argumento de browserWindow permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad.
Los filtros especifican un arreglo de los tipos de archivos can pueden ser mostrados, ver dialog.showOpenDialog por un ejemplo.
dialog.showSaveDialog([browserWindow, ]options)browserWindowBrowserWindow(opcional)options Objecttitle Cadena (opcional) - Título del diálogo. No puede mostrarse en algunos entornos de escritorio de Linux.defaultPath Cadena (opcional) - El camino de directorio absoluto, el camino de archivo absoluto o el nombre del archivo a usar por defecto.buttonLabel cadena (optional) - Etiqueta predeterminada para el botón de confirmación, cuando esta se deja vacía la etiqueta predeterminada será usada.filters FileFilter[] (optional)message Cadena (opcional) macOS - Mensaje a mostrar por encima de los campos de texto.nameFieldLabel Cadena (opcional) macOS - Etiqueta personalizada para el texto mostrado en frente al nombre del archivo del campo de texto.showsTagField Boolean (opcional) macOS - Muestra las etiquetas input box, por defecto true.properties String[] (optional)showHiddenFiles - Muestra archivos ocultos en diálogo.createDirectory macOS- Permite crear nuevos directorios a partir del diálogo.treatPackageAsDirectory macOS - Trata paquetes como carpetas .app, como un directorio en vez de como un fichero.showOverwriteConfirmation Linux - Establece si al usuario será presentado un dialogo de confirmación si escribe el nombre de un archivo que ya existe.dontAddToRecent Windows - No añadir el elemento que se está guardando en la lista de documentos recientes.securityScopedBookmarks Boolean (opcional) macOS mas - Crear un security scoped bookmark es empaquetado para el Mac App Store. Si esta opción está activada y el fichero no existe todavía, se creará un fichero en blanco en la carpeta seleccionada.Devuelve Promise<Object> - Resuelve con un objeto conteniendo lo siguiente:
canceled Boolean - si el diálogo fue o no cancelado.filePath String (opcional) - Si el dialog es cancelado, esto será undefined.bookmark String (opcional) macOS mas - Cadena codificada en Base64 que contiene los datos del marcador con ámbito de seguridad para el archivo guardado. securityScopedBookmarks deben estar activados para estar presentes. (Para devolver valores, vea tabla aquí.)El argumento de browserWindow permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad.
Los filtros especifican un arreglo de los tipos de archivos can pueden ser mostrados, ver dialog.showOpenDialog por un ejemplo.
Nota: En macOS, se recomienda usar la versión asincrona para evitar problemas cuando expanda y colapsa el diálogo.
\ndialog.showMessageBoxSync([browserWindow, ]options)browserWindowBrowserWindow(opcional)options Objectmessage Cadena - Contenido de la caja de mensaje.type Cadena (opcional) - Puede ser \"none\", \"info\", \"error\", \"question\" o \"warning\". En Windows, \"question\" muestra el mismo icono que \"info\", a menos que tu dispongas un icono usando la opción \"icon\". En macOS, tanto \"warning\" como \"error\" muestran el mismo icono de peligro.buttons String[] (optional) - Array of texts for buttons. En Windows, un array vacío resultará en un botón con al etiqueta \"OK\".defaultId Íntegro (opcional) - El índice del botón en el arreglo de los botones, el cual será selecto por defecto cuando el mensaje de la caja se abra.title Cadena (opcional) - Título del mensaje de la caja, algunas plataformas no se mostrarán.detail Cadena (opcional) - Información extra del mensaje.icon (NativeImage | String) (opcional)textWidth Integer (opcional) macOS - Ancho personalizado del texto en el cuadro de mensaje.cancelId Íntegro (opcional) - El índice el botón a ser usado a cancelar el diálogo, por vía la llave Esc. Por defecto, esto es asignado a el primer botón con \"cancelar\" o \"no\" como una etiqueta. Si no existen tales botones etiquetados y esta opción no esta configurada, 0 será usada como el valor de retorno.noLink Boolean (opcional) - En Windows Electron se tratará de averiguar cuál de los buttons son botones comunes (como \"Cancelar\" o \"Sí\"), y muestra los otros como links de comandos en el diálogo. Esto puede hacer que el diálogo aparezca en el estilo de las aplicaciones modernas de Windows. Si no te gusta este comportamiento, puedes establecer noLink a true.normalizeAccessKeys Boolean (opcional) - Normalizar el acceso al teclado a través de las plataformas. Por defecto es false. Permitir esto asume que & es usado en las etiquetas de los botones para el colocamiento de los atajos de acceso de las teclas del teclado y las etiquetas serán convertidas para que funcionen correctamente en cada plataforma, & personajes serán eliminados de macOS, convertidos a _ en Linux, y dejado intacto en Windows. Por ejemplo, una etiqueta de botón de Vie&w será convertida a Vie_w en Linux y View en macOS y puede ser seleccionado vía Alt-W en Windows y Linux.Devuelve Integer - el índice del botón pulsado.
Muestra un cuadro de mensaje, bloqueará el proceso hasta que el cuadro de mensaje esté cerrado. Devuelve el indice del botón pulsado.
\nEl argumento de browserWindow permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad. Si browserWindow no es mostrado no se le adjuntará el dialog. In such case it will be displayed as an independent window.
dialog.showMessageBox([browserWindow, ]options)browserWindowBrowserWindow(opcional)options Objectmessage Cadena - Contenido de la caja de mensaje.type Cadena (opcional) - Puede ser \"none\", \"info\", \"error\", \"question\" o \"warning\". En Windows, \"question\" muestra el mismo icono que \"info\", a menos que tu dispongas un icono usando la opción \"icon\". En macOS, tanto \"warning\" como \"error\" muestran el mismo icono de peligro.buttons String[] (optional) - Array of texts for buttons. En Windows, un array vacío resultará en un botón con al etiqueta \"OK\".defaultId Íntegro (opcional) - El índice del botón en el arreglo de los botones, el cual será selecto por defecto cuando el mensaje de la caja se abra.signal AbortSignal (opcional) - Pasar un instancia de AbortSignal a opcionalmente cerrar el cuadro de mensaje, el cuadro de mensaje se comportará como si fuera cancelado por el usuario. En macOS, signal no funciona con los cuadros de mensajes que no tengan una ventana padre, dado que esos cuadros de mensajes se ejecutan de forma sincrónica debido a las limitaciones de la plataforma.title Cadena (opcional) - Título del mensaje de la caja, algunas plataformas no se mostrarán.detail Cadena (opcional) - Información extra del mensaje.checkboxLabel String (opcional) - Si se proporciona, el cuadro de mensaje será incluido como un checkbox con la etiqueta dada.checkboxChecked Boolean (opcional) - Estado inicial checked del checkbox. false por defecto.icon NativeImage (opcional)textWidth Integer (opcional) macOS - Ancho personalizado del texto en el cuadro de mensaje.cancelId Íntegro (opcional) - El índice el botón a ser usado a cancelar el diálogo, por vía la llave Esc. Por defecto, esto es asignado a el primer botón con \"cancelar\" o \"no\" como una etiqueta. Si no existen tales botones etiquetados y esta opción no esta configurada, 0 será usada como el valor de retorno.noLink Boolean (opcional) - En Windows Electron se tratará de averiguar cuál de los buttons son botones comunes (como \"Cancelar\" o \"Sí\"), y muestra los otros como links de comandos en el diálogo. Esto puede hacer que el diálogo aparezca en el estilo de las aplicaciones modernas de Windows. Si no te gusta este comportamiento, puedes establecer noLink a true.normalizeAccessKeys Boolean (opcional) - Normalizar el acceso al teclado a través de las plataformas. Por defecto es false. Permitir esto asume que & es usado en las etiquetas de los botones para el colocamiento de los atajos de acceso de las teclas del teclado y las etiquetas serán convertidas para que funcionen correctamente en cada plataforma, & personajes serán eliminados de macOS, convertidos a _ en Linux, y dejado intacto en Windows. Por ejemplo, una etiqueta de botón de Vie&w será convertida a Vie_w en Linux y View en macOS y puede ser seleccionado vía Alt-W en Windows y Linux.Devuelve Promise<Object> - resuelve con una promesa conteniendo lo siguiente:
response Number - El índice del botón pulsado.checkboxChecked Boolean - El estado checked state del checkbox si checkboxLabel fue establecido. De lo contrario false.Shows a message box.
\nEl argumento de browserWindow permite el diálogo a adjuntarse a una ventana parental, haciéndola una modalidad.
dialog.showErrorBox(title, content)title Cadena - El título a mostrar en la caja de error.content Cadena - El texto contiene a mostrar en la caja de error.Muestra un diálogo de modalidad que muestra un error de mensaje.
\nEsta API puede ser llamada seguramente antes que el evento ready el módulo app emite, es usualmente usado a reportar errores en las etapas tempranas del inicio. Si llamado antes de la aplicación ready evento en Linux, el mensaje será emitido a stderr, y no aparecerá diálogo GUI.
dialog.showCertificateTrustDialog([browserWindow, ]options) macOS WindowsbrowserWindowBrowserWindow(opcional)options Objectcertificate Certificate - El certificado a confiar/importar.message Cadena - El mensaje a mostrar al usuario.Devuelve Promise<void> - resuelve cuando se muestra el diálogo de confianza del certificado.
En macOS, esto muestra un diálogo modelo que muestra un mensaje e información certificada, y da al usuario la opción de confiar/importar el certificado. Si tú provees un argumento browserWindow el diálogo será adjuntado a la ventana parental, haciéndolo un modelo.
En Windows, las opciones son más limitadas, debido a que el Win32 APIs usado:
\nmessage no es usado, como el OS provee su propio diálogo de confirmación.browserWindow es ignorado ya que no es posible hacer este diálogo modelo de confirmación.showOpenDialog, showOpenDialogSync, showSaveDialog, y showSaveDialogSync retornarán un array bookmarks.
| Tipo de compilación | securityScopedBookmarks boolean | Tipo de Retorno | Valor de Retorno |
|---|---|---|---|
| macOS mas | True | Éxito | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | Error | [''] (array de cadena vacía) |
| macOS mas | False | NA | [] (array vacío) |
| no mas | cualquiera | NA | [] (array vacío) |
En macOS, los diálogos son presentados como hojas ancladas a una ventana si se indica una referencia de BrowserWindow en el parámetro browserWindow, o modales si no se indica ventana.
Puedes llamar a BrowserWindow.getCurrentWindow().setSheetOffset(offset) para cambiar el offset del cuadro de la ventana en donde las páginas fueron adjuntadas.
id Number - Unique identifier associated with the display.rotation Number - Can be 0, 90, 180, 270, represents screen rotation in clock-wise degrees.scaleFactor Number - Output device's pixel scale factor.touchSupport String - Can be available, unavailable, unknown.monochrome Boolean - Whether or not the display is a monochrome display.accelerometerSupport String - Can be available, unavailable, unknown.colorSpace String - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversionscolorDepth Number - The number of bits per pixel.depthPerComponent Number - The number of bits per color component.displayFrequency Number - The display refresh rate.bounds Rectangle - the bounds of the display in DIP points.size SizeworkArea Rectangle - the work area of the display in DIP points.workAreaSize Sizeinternal Boolean - true for an internal display and false for an external displayThe Display object represents a physical display connected to the system. A fake Display may exist on a headless system, or a Display may correspond to a remote, virtual display.
\n\nControla tu aplicación en el dock de macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
El siguiente ejemplo muestra como rebotar tu ícono en el dock.
\nconst { app } = require('electron')\napp.dock.bounce()\ndock.bounce([type]) macOStype String (opcional) - Puede ser critical o informational. Por defecto es informationalDevuelve Integer - un ID que representa la solicitud.
Cuando critical es pasado, el ícono del punto rebotará hasta que la aplicación se vuelva activa o la petición sea cancelada.
Cuando informational es pasado, el icono del dock rebotará por un segundo. Sin embargo, la solicitud permanece activa hasta que la aplicación se vuelta activa o la solicitud sea cancelada.
Nota Bene: Este método solo puede ser usada mientras la aplicación no este enfocada; cuando la aplicación está enfocada retornará -1.
\ndock.cancelBounce(id) macOSid ÍntegroCancela el rebote de id.
dock.downloadFinished(filePath) macOSfilePath StringRebota la apilación de descargas si el archivo de camino está dentro de la carpeta de descargas.
\ndock.setBadge(text) macOStexto CadenaEstablece la cadena para ser mostrada en el área de insignia del punto.
\ndock.getBadge() macOSDevuelve String - La insignia cadena del punto.
dock.hide() macOSEsconde el icono del punto.
\ndock.show() macOSDevuelve Promise<void> - Se resuelve cuando se muestra el icono del dock.
dock.isVisible() macOSDevuelve Boolean - Si el icono del dock es visible.
dock.setMenu(menu) macOSmenu MenuEstablece el [dock menu][dock-menu] de la aplicación.
\ndock.getMenu() macOSDevuelve Menu | null -El [dock menu][dock-menu] de la aplicación.
dock.setIcon(image) macOSimage (NativeImage | String)Establece la image asociada con el ícono del punto.
\n\nControl de descargas de archivos desde fuentes remotas.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
DownloadItem es un EventEmitter que representa un ítem descargado en Electron. Se utiliza en el evento will-download de la clase Session, y permite a los usuarios controlar el elemento descargado.
/// In the main process.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.session.on('will-download', (event, item, webContents) => {\n // Set the save path, making Electron not to prompt a save dialog.\n item.setSavePath('/tmp/save.pdf')\n\n item.on('updated', (event, state) => {\n if (state === 'interrupted') {\n console.log('Download is interrupted but can be resumed')\n } else if (state === 'progressing') {\n if (item.isPaused()) {\n console.log('Download is paused')\n } else {\n console.log(`Received bytes: ${item.getReceivedBytes()}`)\n }\n }\n })\n item.once('done', (event, state) => {\n if (state === 'completed') {\n console.log('Download successfully')\n } else {\n console.log(`Download failed: ${state}`)\n }\n })\n})\nDevuelve:
\neventstate String - Puede ser en progresso o interrumpido.Aparece cuando la descara ha sido actualizada y no está terminada.
\nEl state puede ser uno de los siguientes:
progressing - La descarga está en proceso.interrupted - La descarga ha sido interrumpida y puede ser reanudada.Devuelve:
\neventstate String - Puede ser completado, cancelado o interrumpido.Emitido cuando la descarga está en un estado terminal. Esto incluye una descarga completa, una descarga cancelada (a través de downloadItem.cancel()), y descargas interrumpidas que no pueden ser reanudadas.
El state puede ser uno de los siguientes:
completed - La descarga se ha completado con éxito.cancelled - La descarga ha sido cancelada.interrupted - La descarga ha sido interrumpida y no puede ser reanudada.El objeto downloadItem tiene los siguientes métodos:
downloadItem.setSavePath(path)path Cadena - Configura la ruta del archivo de guardado del elemento descargado.La API solo está disponible en la función callback will-download de la sesión. If path doesn't exist, Electron will try to make the directory recursively. Si el usuario no establece una ruta para guardar a través de la API, Electron usará la rutina original para determinar la ruta para guardar; esto usualmente genera un cuadro de dialogo para guardar.
downloadItem.getSavePath()Returns String - The save path of the download item. This will be either the path set via downloadItem.setSavePath(path) or the path selected from the shown save dialog.
downloadItem.setSaveDialogOptions(options)options SaveDialogOptions - Establece las opciones del diálogo de guardar archivos. Este objeto tiene la misma propiedad como el parámetro options de dialog.showSaveDialog().This API allows the user to set custom options for the save dialog that opens for the download item by default. La API solo está disponible en la función callback will-download de la sesión.
downloadItem.getSaveDialogOptions()Devuelve SaveDialogOptions - Devuelve el objeto previamente establecido por downloadItem.setSaveDialogOptions(options).
downloadItem.pause()Pausa la descarga.
\ndownloadItem.isPaused()Devuelve Boolean - Si la ventana esta pausada o no.
downloadItem.resume()Reanuda la descarga que ha sido pausada.
\nNote: To enable resumable downloads the server you are downloading from must support range requests and provide both Last-Modified and ETag header values. De lo contrario, resume() descartará los bytes recibidos anteriormente y reiniciará la descarga desde el principio.
downloadItem.canResume()Devuelve Boolean - Si se puede reanudar la descarga.
downloadItem.cancel()Cancela la operación de la descarga.
\ndownloadItem.getURL()Devuelve String - La URL origen de donde el elemento se descarga.
downloadItem.getMimeType()Devuelve String - El tipo de archivo.
downloadItem.hasUserGesture()Devuelve Boolean - Si la descarga tiene o no gestos de usuario.
downloadItem.getFilename()Devuelve String - El nombre de archivo del elemento descargado.
Note: The file name is not always the same as the actual one saved in local disk. Si el usuario cambia el nombre del archivo en el cuadro de diálogo de guardado de la descarga, el nombre actual del archivo guardado será diferente.
\ndownloadItem.getTotalBytes()Devuelve Integer - El tamaño total en bytes del elemento descargado.
Si se desconoce el tamaño, devuelve 0.
\ndownloadItem.getReceivedBytes()Devuelve Integer - Los bytes recibidos del elemento descargado.
downloadItem.getContentDisposition()Devuelve String - El campo Content-Disposition desde la cabecera de respuesta.
downloadItem.getState()Returns String - The current state. Can be progressing, completed, cancelled or interrupted.
Note: The following methods are useful specifically to resume a cancelled item when session is restarted.
downloadItem.getURLChain()Devuelve String[] - La cadena URL completa del elemento incluyendo cualquier redirección.
downloadItem.getLastModifiedTime()Devuelve String - El valor de cabecera Last-Modified.
downloadItem.getETag()Devuelve String - El valor de cabecera Etag.
downloadItem.getStartTime()Devuelve Double - Número de segundos desde el UNIX epoch cuando se inició la descarga.
downloadItem.savePathUna propiedad String que determina la ruta del archivo de guardado del elemento de descarga.
La propiedad solo esta disponible en la función callback will-download de la sesión. Si el usuario no establece la ruta de guardado a través de la propiedad, Electron usará la rutina original para determinar la ruta de guardado; esto suele generar un cuadro de diálogo para guardar.
Notas especiales:
\n-beta.1 y stable son nuestras fechas de lanzamiento sólidas.| Electron | Alfa | Beta | Estable | Chrome | Nodo |
|---|---|---|---|---|---|
| 2.0.0 | -- | 2018-Feb-21 | 2018-May-01 | M61 | v8.9 |
| 3.0.0 | -- | 2018-Jun-21 | 2018-Sep-18 | M66 | v10.2 |
| 4.0.0 | -- | 2018-Oct-11 | 2018-Dec-20 | M69 | v10.11 |
| 5.0.0 | -- | 2019-Jan-22 | 2019-Apr-24 | M73 | v12.0 |
| 6.0.0 | -- | 2019-May-01 | 2019-Jul-30 | M76 | v12.4 |
| 7.0.0 | -- | 2019-Aug-01 | 2019-Oct-22 | M78 | v12.8 |
| 8.0.0 | -- | 2019-Oct-24 | 2020-Feb-04 | M80 | v12.13 |
| 9.0.0 | -- | 2020-Feb-06 | 2020-May-19 | M83 | v12.14 |
| 10.0.0 | -- | 2020-May-21 | 2020-Aug-25 | M85 | v12.16 |
| 11.0.0 | -- | 2020-Aug-27 | 2020-Nov-17 | M87 | v12.18 |
| 12.0.0 | -- | 2020-Nov-19 | 2021-Mar-02 | M89 | v14.16 |
| 13.0.0 | -- | 2021-Mar-04 | 2021-May-25 | M91 | v14.16 |
| 14.0.0 | -- | 2021-May-27 | 2021-Aug-31 | M93 | v14.17 |
| 15.0.0 | 2021-Jul-20 | 2021-Sep-01 | 2021-Sep-21 | M94 | v16.5 |
| 16.0.0 | -- | 23-Sept-2021 | 2021-Nov-16 | M96 | TBD |
\n\nUna mirada detallada en la política e implementación de las versiones.
\n
A partir de la versión 2.0.0, Electron sigue SemVer. The following command will install the most recent stable build of Electron:
\nnpm install --save-dev electron\nPara actualizar un proyecto existente para que use la última versión estable:
\nnpm install --save-dev electron@latest\nLas versiones < 2.0 de Electron no se ajustaban a las especificaciones de SemVer: las versiones major correspondían a los cambios en la API del usuario final, las versiones minor correspondían a las versiones major de Chromium y las versiones patch correspondían a las nuevas características y correcciones de errores. Mientras que es conveniente para los desarrolladores combinar características, crea problemas para los desarrolladores de aplicaciones orientadas al cliente. Los ciclos de pruebas QA de aplicaciones importantes como Slack, Stride, Teams, Skype, VS Code, Atom, y Desktop pueden ser muy completos y la estabilidad es un resultado muy deseado. Hay un riesgo grande adoptando nuevas características mientras se está tratando de asimilar las soluciones de errores.
\nAquí hay un ejemplo de la estrategia 1.x:
\n
Una aplicación desarrollada con 1.8.1 no puede tener la solución de errores 1.8.3 sin asimilar las características 1.8.2, o portando la solución y manteniendo un nueva línea de publicación.
There are several major changes from our 1.x strategy outlined below. Each change is intended to satisfy the needs and priorities of developers/maintainers and app developers.
\n-betamaster no tiene versiones: solo las ramas de estabilización contienen información de las versionesReseñamos en detalle cómo funcionan las ramas git, cómo funcionan las etiquetas de npm, qué es lo que los desarrolladores esperan ver, y como se pueden portar cambios a versiones anteriores.
\nDesde la versión 2.0 en adelante, Electron seguirá SemVer.
\nA continuación una tabla que mapea explícitamente los tipos de cambios con sus correspondiente categoría de SemVer (p. e. Major, Minor, Patch).
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Incrementos de versiones major | Incrementos de version minor | Incrementos en la versión patch |
|---|---|---|
| Cambios incompatibles con la API de Electron | Cambios compatibles de la API de Electron | Solución a fallos de Electron |
| Actualizaciones en la version major de Node.js | Actualizaciones en la version minor de Node.js | Actualizaciones en la version patch de Node.js |
| Actualización de versiones de Chromium | parches de chromium relacionados con soluciones de problemas |
Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
\nStabilization branches are branches that run parallel to master, taking in only cherry-picked commits that are related to security or stability. These branches are never merged back to master.
\n
Desde Electron 8, las ramas de estabilización son siempre de las líneas de versión mayor y se nombran contra la siguiente plantilla $MAJOR-x-y p.e. 8-x-y. Antes de eso nosotros usabamos la lineas de version minor y las nombrabamos como $MAJOR-$MINOR-x p.e. 2-0-x
Permitimos a varias ramas estabilizadoras existir simultaneamente e intentamos soportar por lo menos dos en paralelo todo el tiempo, los arreglos de seguridad por la puerta trasera son necesarios.
Líneas antiguas no serán soportadas por GitHub, pero otros grupos pueden tomar la propiedad y estabilizar por la puerta trasera y hacer arreglos de seguridad por si mismos. Incitamos que no se haga esto, pero reconocemos que haría la vida de varios desarrolladores de aplicación más fácil.
\nLos desarrolladores quieren saber cuáles publicaciones son seguras. Hasta características que parecen inocentes pueden introducir grandes regresiones en aplicaciones complejas. Al mismo tiempo, quedarse con una versión arreglada es peligroso porque está ignorando parches de seguridad y arreglos de errores que pudieron salir desde su versión. Nuestra meta es permitir que el siguiente rango semver estandar en package.json :
~2.0.0 para admitir solo arreglo relacionados con la estabilidad o seguridad de su publicación 2.0.0.^2.0.0 para admitir características no frágiles y razonablemente estables que trabajen tanto en seguridad como en arreglo de errores.Lo que es importante del segundo punto es que las aplicaciones que usan ^ aún deben ser capaces de esperar cierto nivel de estabilidad. Para lograr esto, SemVer permite un identificador de pre-lanzamiento para indicar que una versión en particular no es segura o estable.
Sin importar lo que elija, periódicamente tendrá que golpear su versión en su package.json como cambios que son un hecho en la vida útil de Chromium.
El proceso es el siguiente:
\nbeta.N de SemVer, p.e. 2.0.0-beta.1. Después de la primera beta, las versiones beta que la sigan deben cumplir con las siguientes condiciones:2.0.0-beta.2.2.0.0. Después le primera versión estable, todos los cambios deben ser compatibles con versiones anteriores, correcciones de error o de seguridad.2.0.1.Específicamente, lo anterior significa:
\nPor cada cambio mayor y menor, debería esperar ver algo como lo siguiente:
\n2.0.0-beta.1\n2.0.0-beta.2\n2.0.0-beta.3\n2.0.0\n2.0.1\n2.0.2\nUn ejemplo del ciclo de vida en imágenes:
\n2.0.0-beta.1. 2.0.0-beta.2. 2.0.0. 2-0-x line and release 2.0.1. Algunos ejemplos de como varios rangos SemVer recogerán los nuevos lanzamientos:
\n
Nuestra estrategia tiene algunas compensaciones, que por ahora sentimos que son apropiadas. Más importante que las nuevas características en la maestra pueden tomar un tiempo antes de alcanzar una linea de lanzamiento estable. Si quiere tratar nuevas características inmediatamente, tendrá que construir Electron usted mismo.
\nComo consideración futura, podemos introducir uno o ambos de los siguientes:
\nBanderas de características son prácticas comunes en Chromium, y son bien establecidas en el ecosistema de diseño web. En el contexto de Electron, banderas de características o ramas suaves deben seguir las siguientes propiedades:
\nBuscamos aumentar la claridad en todos los niveles del proceso de actualización y publicación. Comenzando con 2.0.0 necesitaremos retirar solicitudes adheridas a la especificación Conventional Commits, la cual se puede resumir como:
Los commits que resultarían en una versión major de SemVer deben empezar sus cuerpos con BREAKING CHANGE:.
Los commits que resultarían en una versión minor de SemVer debe empezar con feat:.
Los commits que resultarían en una versión patch de SemVer deben empezar con fix:.
We allow squashing of commits, provided that the squashed message adheres to the above message format.
\nEs aceptable que algunos compromisos en una solicitud de pull no incluyan un prefijo semántico, siempre que el título de pull request contenga un mensaje semántico significativo.
\nmastermaster siempre contendrá la siguiente versión mayor X.0.0-nightly.DATE en su package.jsonpackage.jsonmaster is always versioned as the next theoretical release branchComo NW.js, Electron provee una plataforma para escribir aplicaciones de escritorio con tecnologías web. Ambas plataformas permiten a los desarrolladores usar HTML, JavaScript y Node.js. En la superficie, parecen muy similares.
\nSin embargo, hay diferencias fundamentales ente los dos proyectos que hacen a Electron un producto completamente separado de NW.js.
\nEn NW.js, el principal punto de entrada puede ser una pagina web HTML. En ese caso, NW.js abrirá el punto de entrada dado en una ventana del navegador.
\nEn Electron, el punto de entrada es siempre un script JavaScript. En lugar de proveer directamente un URL, creas manualmente una ventana del navegador y cargas un archivo HTML usando la API. También necesitas escuchar los eventos de la ventana para decidir cuándo cerrar de la aplicación.
\nElectron trabaja más como el runtime de Node.js. Las APIs de Electron son de más bajo nivel, así que puedes usarlas para las pruevas del navegador en lugar de PhantomJS.
\nEn NW.js, la integración de Node en paginas web requiere parchear Chromium para trabajar, mientras en Electron nosotros elegimos una forma diferente de integrar le bucle libuv con el bucle de mensaje de cada plataforma para evitar parchear Chromium. Mira el código node_bindings para ver cómo se hizo eso.
Si eres un usuario experimentado de NW. js, deberías estar familiarizado con el concepto de contexto de Node y el contexto Web. Estos conceptos fueron inventados debido a como NW.js fue implementado.
\nMediante el uso de la característica multi-context de Node, Electron no introduce un nuevo contexto JavaScript en las páginas web.
\nNota: NW.js ha apoyado de manera opcional multi-contexto desde la versión 0.13.
\nNW.js aún ofrece una \"versión antigua\" que soporta Windows XP. No recibe actualizaciones de seguridad.
\nDado que los fabricantes de hardware, Microsoft, Chromium y Node.js no han lanzado ni siquiera actualizaciones de seguridad críticas para ese sistema, tenemos que advertirte que usando Windows XP es salvajemente inseguro y francamente irresponsable.
\nSin embargo, entendemos que los requisitos fuera de nuestra imaginación más salvaje pueden existir, así que si estás buscando algo como Electron que corra en Windows Xp, la versión antigua de NW.js puede ser la adecuada para ti.
\nHay numerosas diferencias en la cantidad de características soportadas. Electron tiene una comunidad más grande, con más aplicaciones en producción usándolo y una mayor cantidad de módulos userland disponibles en npm.
\nComo ejemplo, Electron tiene soporte integrado para actualizaciones automáticas e incontables herramientas que facilitan la creación de instaladores. Como ejemplo a favor de NW.js, NW.js soporta más APIs de Chrome.* para el desarrollo de aplicaciones Chrome.
Naturalmente, nosotros creemos que Electron es la mejor plataforma para aplicaciones de producción pulidas construidas con tecnologías web (como Visual Studio Code, Slack, o Facebook Messenger); sin embargo, queremos ser justos con nuestros amigos de las tecnología web. Si tienes necesidades de características que Electron no cumple, puede que quieras probar NW.js.
", "title": "Diferencias técnicas entre Electron y NW.js", "description": "" }, "/docs/api/environment-variables": { "locale": "es-ES", "slug": "environment-variables", "href": "/docs/api/environment-variables", "crowdinFileId": "256315", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/environment-variables.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nConfiguración y comportamiento de la aplicación de control sin cambiar el código.
\n
Ciertos comportamientos de Electron están controlados por variables de entorno debido a que son inicializadas antes que las flags de la línea de comandos y que el código de la applicación.
\nEjemplo de shell POSIX:
\n$ export ELECTRON_ENABLE_LOGGING=true\n$ electron\nEjemplo de la consola de Windows:
\n> set ELECTRON_ENABLE_LOGGING=true\n> electron\nLas siguientes variables de entorno están diseñadas principalmente para usarse en los módulos de ejecución en las aplicaciones preconfiguradas de Electron.
\nNODE_OPTIONSElectron incluye soporte para un subconjunto de NODE_OPTIONS de Node. La mayoría son soportadas con la excepción de aquellos que entran en conflicto con el uso de BoringSSL de Chromium.
Ejemplo:
\nexport NODE_OPTIONS=\"--no-warnings --max-old-space-size=2048\"\nLas opciones no respaldadas son:
\n--use-bundled-ca\n--force-fips\n--enable-fips\n--openssl-config\n--use-openssl-ca\nNODE_OPTIONS están explícitamente deshabilitadas en las aplicaciones empaquetadas, excepto para lo siguiente:
--max-http-header-size\n--http-parser\nGOOGLE_API_KEYEl soporte de geolocalización en Electron requiere el uso del servicio web de Google Cloud Platform. Para habilitar esta función, adquiera una Google API key y coloque el siguiente código en su archivo de proceso principal, antes de abrir cualquier ventana de buscador que vaya a realizar solicitudes de geolocalización:
\nprocess.env.GOOGLE_API_KEY = 'TU_CLAVE_AQUI'\nPor defecto, una clave API de Google recientemente generada podría no tener permitido hacer solicitudes de geolocalización. Para habilitar el servicio web de geolocalización para su proyecto, habilítelo a través de la API library.
\nN.B. You will need to add a Billing Account to the project associated to the API key for the geolocation webservice to work.
\nELECTRON_NO_ASARDisables ASAR support. This variable is only supported in forked child processes and spawned child processes that set ELECTRON_RUN_AS_NODE.
ELECTRON_RUN_AS_NODEInicia el proceso como un proceso normal de Node.js.
\nEn este modo, podrás ser capaz de pasar opciones cli a Node.js como lo harías cuando corres el ejecutable normal de Node.js, con la excepción de las siguientes banderas:
\nThese flags are disabled owing to the fact that Electron uses BoringSSL instead of OpenSSL when building Node.js' crypto module, and so will not work as designed.
ELECTRON_NO_ATTACH_CONSOLE WindowsNo se adjunta a la sesión de la consola actual.
\nELECTRON_FORCE_WINDOW_MENU_BAR LinuxNo utilizar la barra de menú global en Linux.
\nELECTRON_TRASH LinuxSet the trash implementation on Linux. Por defecto es gio.
Opciones:
\ngvfs-trashtrash-clikioclient5kioclientLas siguientes variables de entorno están principalmente diseñadas para propósitos de desarrollo y depuración.
\nELECTRON_ENABLE_LOGGINGPrints Chromium's internal logging to the console.
\nSetting this variable is the same as passing --enable-logging on the command line. For more info, see --enable-logging in command-line switches.
ELECTRON_LOG_FILESets the file destination for Chromium's internal logging.
\nSetting this variable is the same as passing --log-file on the command line. For more info, see --log-file in command-line switches.
ELECTRON_DEBUG_DRAG_REGIONSAgrega coloración a regiones arrastrables en BrowserView en macOS - Las regiones que se pueden arrastrar se colorearán en verde y las regiones que no se pueden arrastrar se colorearán en rojo para facilitar la depuración.
ELECTRON_DEBUG_NOTIFICATIONSAgrega registros adicionales al ciclos de vida Notification en macOS para ayudar a depurar. Se mostrará un registro adicional cuando se creen o activen nuevas notificaciones. They will also be displayed when common a tions are taken: a notification is shown, dismissed, its button is clicked, or it is replied to.
Ejemplo de salida:
\nNotification created (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification displayed (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification activated (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification replied to (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nELECTRON_LOG_ASAR_READSWhen Electron reads from an ASAR file, log the read offset and file path to the system tmpdir. The resulting file can be provided to the ASAR module to optimize file ordering.
ELECTRON_ENABLE_STACK_DUMPINGImprime el rastro de la pila a la consola cuando Electron falla.
\nEsta variable de entorno no funcionará si se inicia el crashReporter.
ELECTRON_DEFAULT_ERROR_MODE WindowsMuestra el cuadro de dialogo del fallo de Windows cuando falla Electron.
\nEsta variable de entorno no funcionará si se inicia el crashReporter.
ELECTRON_OVERRIDE_DIST_PATHCuando corre desde el paquete electron, esta variable dice al comando electron para usar la instancia especificada del constructor de Electron en lugar de uno descargado por npm install. Uso:
export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing\nElectron define algunas variables en su entorno en el momento de ejecución.
\nORIGINAL_XDG_CURRENT_DESKTOPEsta variable es establecida con al valor de XDG_CURRENT_DESKTOP con el que originalmente tu aplicación fue lanzada. A veces, Electron modifica el valor de XDG_CURRENT_DESKTOP para afectar otra lógica dentro de Chromium, así que si quieres acceder al valor original original en su lugar deberías buscar esta variable de entorno.
GlobalEventpreventDefault VoidFunctionSome of Electrons APIs are tagged with _Experimental_ in the documentation. This tag indicates that the API may not be considered stable and the API may be removed or modified more frequently than other APIs with less warning.
Anyone can request an API be tagged as experimental in a feature PR, disagreements on the experimental nature of a feature can be discussed in the API WG if they can't be resolved in the PR.
\nOnce an API has been stable and in at least two major stable release lines it can be nominated to have its experimental tag removed. This discussion should happen at an API WG meeting. Things to consider when discussing / nominating:
\nid Cadenamanifest any - Copy of the extension's manifest data.name Stringpath String - The extension's file path.version Stringurl String - The extension's chrome-extension:// URL.name Stringversion StringElectron supports a subset of the Chrome Extensions API, primarily to support DevTools extensions and Chromium-internal extensions, but it also happens to support some other extension capabilities.
\n\n\nNote: Electron does not support arbitrary Chrome extensions from the store, and it is a non-goal of the Electron project to be perfectly compatible with Chrome's implementation of Extensions.
\n
Electron only supports loading unpacked extensions (i.e., .crx files do not work). Extensions are installed per-session. Para cargar una extensión, llame a ses.loadExtension:
const { session } = require('electron')\n\nsession.loadExtension('path/to/unpacked/extension').then(({ id }) => {\n // ...\n})\nLoaded extensions will not be automatically remembered across exits; if you do not call loadExtension when the app runs, the extension will not be loaded.
Note that loading extensions is only supported in persistent sessions. Attempting to load an extension into an in-memory session will throw an error.
\nSee the session documentation for more information about loading, unloading, and querying active extensions.
We support the following extensions APIs, with some caveats. Other APIs may additionally be supported, but support for any APIs not listed here is provisional and may be removed.
\nchrome.devtools.inspectedWindowTodas las características de esta API son compatibles.
\nchrome.devtools.networkTodas las características de esta API son compatibles.
\nchrome.devtools.panelsTodas las características de esta API son compatibles.
\nchrome.extensionSe admiten las siguientes propiedades de chrome.extension :
chrome.extension.lastErrorLos siguientes métodos de chrome.extension son soportados:
chrome.extension.getURLchrome.extension.getBackgroundPagechrome.runtimeLas siguientes propiedades de chrome.runtime son soportadas:
chrome.runtime.lastErrorchrome.runtime.idLos siguientes métodos de chrome.runtime son soportados:
chrome.runtime.getBackgroundPagechrome.runtime.getManifestchrome.runtime.getPlatformInfochrome.runtime.getURLchrome.runtime.connectchrome.runtime.sendMessagechrome.runtime.reloadLos siguientes eventos de chrome.runtime están soportados:
chrome.runtime.onStartupchrome.runtime.onInstalledchrome.runtime.onSuspendchrome.runtime.onSuspendCanceledchrome.runtime.onConnectchrome.runtime.onMessagechrome.storageSolo chrome.storage.local está soportado; chrome.storage.sync y chrome.storage.managed no lo están.
chrome.tabsLos siguientes métodos de chrome.tabs son soportados:
chrome.tabs.sendMessagechrome.tabs.executeScript\n\nNote: In Chrome, passing
\n-1as a tab ID signifies the \"currently active tab\". Since Electron has no such concept, passing-1as a tab ID is not supported and will raise an error.
chrome.managementLos siguientes métodos de chrome.management son soportados:
chrome.management.getAllchrome.management.getchrome.management.getSelfchrome.management.getPermissionWarningsByIdchrome.management.getPermissionWarningsByManifestchrome.management.onEnabledchrome.management.onDisabledchrome.webRequestTodas las características de esta API son compatibles.
\n\n", "title": "Chrome Extension Support", "description": "Note: Electron does not support arbitrary Chrome extensions from the store, and it is a non-goal of the Electron project to be perfectly compatible with Chrome's implementation of Extensions." }, "/docs/faq": { "locale": "es-ES", "slug": "faq", "href": "/docs/faq", "crowdinFileId": "256121", "githubUrl": "https://github.com/electron/electron/tree/main/docs/faq.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "NOTE: Electron's
\nwebRequestmodule takes precedence overchrome.webRequestif there are conflicting handlers.
Cuando ejecutamos npm install electron, ocasionalmente algunos usuarios encuentran errores en la instalación.
En casi todos los casos, estos errores son resultados de problemas en la red y no de problemas con el paquete npm de electron. Errores como ELIFECYCLE, EAI_AGAIN, ECONNRESET y ETIMEDOUT son indicadores de dichos problemas de red. La mejor solución es tratar de cambiar las redes, o esperar un poco e instalar de nuevo.
También puede intentar descargar Electron directamente de electron/electron/releases si la ruta de instalación npm está fallando.
La versión de Chrome de Electron es usualmente actualizada con una o dos semanas después de que una nueva versión estable de Chrome es publicada. Esta estimación no se garantiza y depende de la carga de trabajo que implica la actualización.
\nOnly the stable channel of Chrome is used. If an important fix is in beta or dev channel, we will back-port it.
\nPara mas información, por favor lea la introducción de seguridad.
\nCuando una nueva versión de Node.js es publicada, usualmente esperamos aproximadamente un mes antes de actualizar la versión de Electron. Con esto evitamos afectarnos por bugs introducidos en la nueva versión de Node.js, lo cual sucede frecuentemente.
\nNovedades de Node.js están generalmente presentadas por mejoras V8, puesto que el Electron está utilizando el V8 enviados por el navegador Chrome, JavaScript nuevo brillante característica de una nueva versión de Node.js es generalmente ya en Electron.
\nPara compartir datos entre páginas web (el proceso de renderizado) la manera más simple es usar el API de HTML5 el cual ya está disponible en navegadores. Buenos candidatos son Storage API, localStorage, sessionStorage, y IndexedDB.
Alternatively, you can use the IPC primitives that are provided by Electron. To share data between the main and renderer processes, you can use the ipcMain and ipcRenderer modules. To communicate directly between web pages, you can send a MessagePort from one to the other, possibly via the main process using ipcRenderer.postMessage(). Subsequent communication over message ports is direct and does not detour through the main process.
Esto sucede cuando la variable que es usada para almacenar la ventana/bandeja se limpia de la basura.
\nSi encuentra este problema, los siguientes artículos pudiesen resultar útiles:
\n\nSi quiere una solución rápida, puede volver sus variables globales cambiando su código de este:
\nconst { app, Tray } = require('electron')\napp.whenReady().then(() => {\n const tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\na este:
\nconst { app, Tray } = require('electron')\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\nDebido a la integración de Node.js de Electron, hay algunos símbolos extras insertados en la DOM como module, exports, require. Esto causa problemas para algunas librerías dado que ellas quieren insertar símbolos con los mismos nombres.
Para solucionar esto, puede desactivar la integración de Node en Electron:
\n/// In the main process.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n webPreferences: {\n nodeIntegration: false\n }\n})\nwin.show()\nPero si desea mantener la capacidad de utilizar Node.js y APIs de Electron, tienes que cambiar el nombre de los símbolos en la página antes de incluir otras bibliotecas:
\n<head>\n<script>\nwindow.nodeRequire = require;\ndelete window.require;\ndelete window.exports;\ndelete window.module;\n</script>\n<script type=\"text/javascript\" src=\"jquery.js\"></script>\n</head>\nrequire('electron').xxx no está definido.Cuando se utiliza el módulo de Electron puede encontrar un error como este:
\n> require('electron').webFrame.setZoomFactor(1.0)\nUncaught TypeError: Cannot read property 'setZoomLevel' of undefined\nIt is very likely you are using the module in the wrong process. Por ejemplo electron.app puede ser utilizado en el proceso principal, mientras que electron.webFrame sólo está disponible en los procesos de renderizado.
If sub-pixel anti-aliasing is deactivated, then fonts on LCD screens can look blurry. Ejemplo:
\n
El anti-aliasing de Sub-píxeles necesita un fondo no transparente de la capa que contenga los glifos de fuente. (Vea this issue para más información).
\nTo achieve this goal, set the background in the constructor for BrowserWindow:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n backgroundColor: '#fff'\n})\nEl efecto es visible sólo en (algunos?) Pantallas LCD. Even if you don't see a difference, some of your users may. It is best to always set the background this way, unless you have reasons not to do so.
\nTenga en cuenta que sólo establecer el fondo en el CSS no tiene el efecto deseado.
", "title": "Preguntas más frecuentes sobre Electron", "description": "" }, "/docs/api/structures/file-filter": { "locale": "es-ES", "slug": "file-filter", "href": "/docs/api/structures/file-filter", "crowdinFileId": "256435", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/file-filter.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "name Stringextensions String[]Archivo Objeto\n\nUtiliza la API HTML5
\nFilepara trabajar de forma nativa con los archivos en filesystem.
La interfaz del archivo de DOM proporciona abstracción alrededor de los archivos nativos para permitir a los usuarios trabajar sobre los archivos nativos directamente con la API del archivo HTML5. Electron tiene un atributo path adicional a la interfaz File el cual revela la ruta real del archivo en filesystem.
Ejemplo para obtener una ruta real desde un archivo arrastrado dentro de la aplicación:
\n<div id=\"holder\">\n Drag your file here\n</div>\n\n<script>\n document.addEventListener('drop', (e) => {\n e.preventDefault();\n e.stopPropagation();\n\n for (const f of e.dataTransfer.files) {\n console.log('File(s) you dragged here: ', f.path)\n }\n });\n document.addEventListener('dragover', (e) => {\n e.preventDefault();\n e.stopPropagation();\n });\n</script>\npath String - The path to the file to send.headers Record<string, string> (optional) - Additional headers to be sent.\n\nAbrir una ventana sin barras de herramientas, bordes u otro \"chrome\" gráfico.
\n
Una ventana sin bordes es una ventana que no tiene chrome, ni las partes de la ventana, como barra de herramientas, que no forman parte de la página web. Estas son las opciones en la clase BrowserWindow.
Para crear una ventana sin marco, necesitas establecer frame a false en las options de BrowserWindow:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600, frame: false })\nwin.show()\nThere's an alternative way to specify a chromeless window on macOS and Windows. Instead of setting frame to false which disables both the titlebar and window controls, you may want to have the title bar hidden and your content extend to the full window size, yet still preserve the window controls (\"traffic lights\" on macOS) for standard window actions. Puede hacerse especificando la opción titleBarStyle:
hiddenResults in a hidden title bar and a full size content window. On macOS, the title bar still has the standard window controls (“traffic lights”) in the top left.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hidden' })\nwin.show()\nhiddenInsetEs una barra de título oculta con un aspecto alternativo donde los botones de traffic light están ligeramente mas insertados desde el borde de la ventana.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })\nwin.show()\ncustomButtonsOnHoverUsa botones personalizados de cierre y miniaturiza que se muestran cuando se activa en la parte superior izquierda de la ventana. The fullscreen button is not available due to restrictions of frameless windows as they interface with Apple's macOS window masks. Estos botones personalizados evitaran problemas con los eventos de ratón que ocurren con los botones de la barra de herramientas estándar. Esta opción sólo es aplicable para ventanas sin marco.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover', frame: false })\nwin.show()\nWhen using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS, using one of the titleBarStyles as described above so that the traffic lights are visible, or using titleBarStyle: hidden on Windows, you can access the Window Controls Overlay JavaScript APIs and CSS Environment Variables by setting the titleBarOverlay option to true. Specifying true will result in an overlay with default system colors.
On Windows, you can also specify the color of the overlay and its symbols by setting titleBarOverlay to an object with the options color and symbolColor. If an option is not specified, the color will default to its system color for the window control buttons:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: true\n})\nwin.show()\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: {\n color: '#2f3241',\n symbolColor: '#74b1be'\n }\n})\nwin.show()\nAl configurar la opción transparent a true, se puede hacer transparente la ventana sin bordes:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ transparent: true, frame: false })\nwin.show()\nresizable a true puede hacer que una ventana transparente deje de funcionar en algunas plataformas.blur solo aplica a la página web, por lo que no hay manera de aplicar el efecto blur al contenido debajo de la ventana (por ejemplo, otras aplicaciones abiertas en el sistema del usuario).--enable-transparent-visuals --disable-gpu en la línea de comandos para deshabilitar el GPU y permitir ARGB para hacer transparente la ventana, esto es causado por un bug ascendente donde el canal alfa no funciona en algunos controladores NVidia en Linux.Para crear una ventana click-through, por ejemplo hacer que la ventana ignore todos los eventos del ratón, puedes llamar la API win.setIgnoreMouseEvents(ignore):
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.setIgnoreMouseEvents(true)\nIgnorar los mensajes de movimiento del ratón hace la página agena al movimiento del ratón, lo que significa que los eventos no se emitirán. En los sistemas operativos Windows se puede usar un parámetro opcional para reenviar los mensajes de movimiento del ratón a la página web, permitiendo que eventos como mouseleave se emitan:
const { ipcRenderer } = require('electron')\nconst el = document.getElementById('clickThroughElement')\nel.addEventListener('mouseenter', () => {\n ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })\n})\nel.addEventListener('mouseleave', () => {\n ipcRenderer.send('set-ignore-mouse-events', false)\n})\n\n// Main process\nconst { ipcMain } = require('electron')\nipcMain.on('set-ignore-mouse-events', (event, ...args) => {\n BrowserWindow.fromWebContents(event.sender).setIgnoreMouseEvents(...args)\n})\nEsto hace que la página web sea \"click-through\" cuando se situa el ratón sobre el, y vuelva a su estado normal cuando se abandona.
Por defecto, una ventana sin bordes no se puede desplazar. La aplicación necesita especificar -webkit-app-region: drag en CSS para indicarle a Electron cuales regiones son desplazables (como la barra de títulos estándar del sistema operativo). Las aplicaciones también pueden usar -webkit-app-region: no-drag para excluir el área no desplazable de las regiones desplazables. Tenga en cuenta que solo las formas rectangulares son soportadas.
Nota: -webkit-app-region: drag es conocida por tener problemas mientras las herramientas del desarrollador están abiertas. Para mas información ver este GitHub issue incluida una solución.
Para hacer que toda la ventana sea desplazable, puedes agregar -webkit-app-region: drag como el estilo de body:
<body style=\"-webkit-app-region: drag\">\n</body>\nY tenga en cuenta que si se hace toda la ventana desplazable, se debe marcar los botones como no desplazable, de lo contrario sería imposible para los usuarios hacer clic sobre ellos:
\nbutton {\n -webkit-app-region: no-drag;\n}\nSi sólo está configurando una barra de títulos personalizada como arrastrable, también necesita hacer todos los botones en la barra de título no arrastrable.
\nEn una ventana sin marco el comportamiento de arrastrar puede causar conflicto con la selección de texto. Por ejemplo, cuando se arrastra la barra de título, accidentalmente se podría seleccionar el texto sobre la barra de título. Para evitar esto, es necesario deshabilitar la selección de texto dentro de un área desplazable como:
\n.titlebar {\n -webkit-user-select: none;\n -webkit-app-region: drag;\n}\nEn algunas plataformas, el área desplazable puede ser considerada como un borde que no forma parte del cliente, de esta manera cuando se haga clic sobre él, aparecerá un menú del sistema. Para que el menú de contexto se comporte correctamente en todas las plataformas, nunca debe usarse un menú de contexto personalizado en áreas desplazables.
", "title": "Ventanas sin bordes", "description": "Abrir una ventana sin barras de herramientas, bordes u otro \"chrome\" gráfico." }, "/docs/tutorial/fuses": { "locale": "es-ES", "slug": "fuses", "href": "/docs/tutorial/fuses", "crowdinFileId": "256201", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/fuses.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nAlterna característica en tiempo de empaquetado
\n
Para un subconjunto de funcionalidad de Electron tiene sentido deshabilitar ciertas características para una aplicación entera. Por ejemplo, el 99% de las aplicaciones no hacen uso de ELECTRON_RUN_AS_NODE, estas aplicaciones quiere ser capaz de enviar un binario que sea incapaz de usar esa característica. Además no queremos que los consumidores de Electron construyan Electron a partir de la fuente, ya que ese es un desafío técnico masivo y tiene un alto costo tanto en tiempo como en dinero.
Los fusibles son la solución a este problema, en un alto nivel son \"bits mágicos\" en el binario de Electron que se pueden voltear cuando empaca su aplicación Electron para habilitar / deshabilitar ciertas características / restricciones. Debido a que son volteados en tiempo de empaquetado antes de que el código firme la aplicación, el sistema operativo se hace responsable de asegurar que esos bits no son volteados de nuevo a través de la validación de firma de código a nivel de sistema operativo (Gatekeeper / App Locker).
\nHemos hecho un módulo práctico @electron/fuses para hacer que voltear estos fusibles sea fácil. Revisa el README del módulo para más detalles sobre uso y los casos de errores potenciales.
require('@electron/fuses').flipFuses(\n // Path to electron\n require('electron'),\n // Fuses to flip\n {\n runAsNode: false\n }\n)\nPara voltear los fusibles manualmente, es necesario editar el binario de Electron y modificar el cable del fusible para que sea la secuencia de bytes que represente el estado de los fusibles que desea.
\nEn algún lugar en el binario de Electron habrá una secuencia de bytes que se verán así:
\n| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |\nsentinel_bytes siempre es esta cadena exacta dL7pKGdnNz796PbbjQWNKmHXBZaB9tsXfuse_version es un solo byte cuyo valor entero sin signo representa la versión del esquema de fusiblefuse_wire_length es un solo byte cuyo valor entero sin signo representa el numero de fusibles en el siguiente cable de fusiblefuse_wire es una secuencia de N bytes, cada byte representa un solo fusible y su estado.Para voltear un fusible busque su posición en el cable del fusible y cámbielo a \"0\" o \"1\" dependiendo del estado que desee.
\nPuede ver el esquema actual aquí.
", "title": "Electron Fuses", "description": "Alterna característica en tiempo de empaquetado" }, "/docs/api/global-shortcut": { "locale": "es-ES", "slug": "global-shortcut", "href": "/docs/api/global-shortcut", "crowdinFileId": "256323", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/global-shortcut.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nDetecta los eventos del teclado cuando la aplicación no tiene el enfoque en el teclado.
\n
Proceso: principal</0>
\nEl módulo globalShortcut puede registrar o quitar un atajo del teclado global con el sistema operativo para que se puedan personalizar las operaciones para varios atajos.
Nota: El atajo es global; funcionará incluso si la aplicación no tiene enfocado el teclado. This module cannot be used before the ready event of the app module is emitted.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+X' shortcut listener.\n const ret = globalShortcut.register('CommandOrControl+X', () => {\n console.log('CommandOrControl+X is pressed')\n })\n\n if (!ret) {\n console.log('registration failed')\n }\n\n // Check whether a shortcut is registered.\n console.log(globalShortcut.isRegistered('CommandOrControl+X'))\n})\n\napp.on('will-quit', () => {\n // Unregister a shortcut.\n globalShortcut.unregister('CommandOrControl+X')\n\n // Unregister all shortcuts.\n globalShortcut.unregisterAll()\n})\nEl módulo globalShortcut tiene los siguientes métodos:
globalShortcut.register(accelerator, callback)accelerator Acceleratorcallback FunciónDevuelve Boolean - Si el acceso fue registrado con éxito.
Registra un atajo global del acelerador. El callback es llamado cuando el atajo registrado es presionado por el usuario.
Cuando el acelerador ha sido tomado por otras aplicaciones, esta llamada fallará silenciosamente. Este comportamiento está diseñado por los sistemas operativos, debido a que no desean que las aplicaciones tengan conflictos por los atajos globales.
\nLos siguientes aceleradores no serán registrados con correctamente en macOS 10.14 a menos que la aplicación haya sido autorizada como trusted accessibility client:
\nglobalShortcut.registerAll(accelerators, callback)accelerators String[] - un array de Accelerators.callback FunciónRegistra un atajo global de todos los elementos acelerador en aceleradores. callback es llamado cuando el usuario presiona alguno de los atajos registrados.
Cuando el acelerador ya ha sido tomado por otras aplicaciones, esta llamada fallará silenciosamente. Este comportamiento está diseñado por los sistemas operativos, debido a que no desean que las aplicaciones tengan conflictos por los atajos globales.
\nLos siguientes aceleradores no serán registrados con correctamente en macOS 10.14 a menos que la aplicación haya sido autorizada como trusted accessibility client:
\nglobalShortcut.isRegistered(accelerator)accelerator AcceleratorDevuelve Boolean - Si esta aplicación tiene registrado accelerator.
Cuando el acelerador ha sido tomado por otras aplicaciones, esta llamada aun devolverá false. Este comportamiento está diseñado por los sistemas operativos, debido a que no desean que las aplicaciones tengan conflictos por los atajos globales.
globalShortcut.unregister(accelerator)accelerator AcceleratorAnula el registro del atajo del accelerator.
globalShortcut.unregisterAll()Anula el registro todos los atajos globales.
", "title": "globalShortcut", "description": "Detecta los eventos del teclado cuando la aplicación no tiene el enfoque en el teclado." }, "/docs/glossary": { "locale": "es-ES", "slug": "glossary", "href": "/docs/glossary", "crowdinFileId": "256123", "githubUrl": "https://github.com/electron/electron/tree/main/docs/glossary.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Esta página define algunos términos que comúnmente se utilizan en el desarrollo de Electron.
\nASAR significa formato de archivo de Shell de Atom. Un archivo de asar es un simple formato tipo tar que concatena archivos en un solo archivo. Electron puede leer archivos arbitrarios de él sin desempacar el archivo entero.
El formato ASAR fue creado principalmente para mejorar el rendimiento en Windows cuando se cargan grandes cantidades de archivos pequeños (p.e. al cargar el árbol de dependencia JavaScript de tu aplicación desde node_modules).
La firma de código es un proceso donde un desarrollador de aplicación firma digitalmente su código para asegurarse que el código no haya sido manipulado después del empaquetado. Tanto Windows y macOS implementan su propia versión de la firma de código. Como desarrollar de aplicaciones de escritorio, es importante que firmes tu código si planeas distribuirlo al publico en general.
\nPara más información, consulta el tutorial Code Signing.
\nEl aislamiento de contexto es una medida de seguridad en Electro que asegura que tu script de precarga no pueda filtrar las APIs privilegiadas de Electron o Node.js a los contenidos web en tu renderer process. Con el aislamiento de contexto activado, la única manera de exponer las APIs, desde tu scrip de precarga es a través de la API contextBridge.
Para más información, consulta el tutorial Context Isolation.
\nVer también: preload script, renderer process
\nLa biblioteca de Run-time C (CRT) es la parte de la biblioteca estándar de C++ que incorpora la biblioteca estándar de ISO C99. Las librerías de Visual C++ que implementan el apoyo CRT desarrollo de código nativo, y tanto código mixto nativo y como código administrado, y puro código administrado para el desarrollo .NET.
\nUna imagen de disco de Apple es un formato de empaquetado utilizado por macOS. Los archivos DMG se utilizan comúnmente para la distribución de aplicaciones \"instaladores\".
\nMétodo de entrada del editor. Un programa que permite a los usuarios introducir caracteres y símbolos no encontrados en su teclado. Por ejemplo, esto permite a los usuarios de teclados de latín introducir caracteres chinos, japoneses, coreanos e indios.
\nLenguaje de descripción de interfaz. Escribe firmas de funciones y tipos de datos en un formato que se puede utilizar para generar interfaces en Java, C++, JavaScript, etc.
\nIPC se refiere a la comunicación entre procesos. Electron utiliza IPC para enviar mensajes JSON serializados entre el proceso principal y los procesos renderizadores.
\nvéase también: proceso principal, proceso de renderizado
\nThe main process, commonly a file named main.js, is the entry point to every Electron app. Controla la vida de la aplicación, de abierto a cerrado. También maneja elementos nativos como el menú, barra de menú, bandeja, etc. The main process is responsible for creating each new renderer process in the app. La API completa de Node está integrada.
El archivo de proceso principal de cada aplicación se especifica en la propiedad main en package.json. Así es como electron sabe qué archivo ejecutar al inicio.
En Chromium, este proceso se denomina \"proceso del navegador\". Se renombró en Electron para evitar confusiones con los procesos del renderizador (browser process).
\nVéase también: proceso, proceso de renderizado
\nAcrónimo para la App Store de Apple. Para más detalles sobre el envío de su aplicación al MAS, consulte la Guía de envíos de Mac App Store.
\nUn sistema IPC para comunicarse dentro o entre procesos, y eso es importante porque Chrome está interesado en poder dividir su trabajo en procesos separados o no, dependiendo de las presiones de la memoria, etc.
\nVer https://chromium.googlesource.com/chromium/src/+/master/mojo/README.md
\nVer también: IPC
\nEn Windows, los paquetes MSI son usados por el servicio Windows Installer (también conocido como Microsoft Installer) para instalar y configurar aplicaciones.
\nPuede encontrar más información en Microsoft's documentation.
\nLos módulos nativos (también llamados addons en Node.js) son módulos escritos en C o C++ que pueden ser cargados en Node.js o Electron mediante la función require() y utilizarlos como si fueran un módulo ordinario de Node.js. Son usados principalmente para ofrecer una interfaz entre JavaScript corriendo en Node.js y las librerías C/C++.
\nNativo nodo módulos están soportados por el Electron, pero puesto que el Electron es muy probable que utilice una versión V8 del nodo binario instalada en su sistema, usted tiene que especificar manualmente la ubicación de cabeceras del Electron al compilar los módulos nativos.
\nPara más información, lea el tutorial [Native Node Modules].
\nLa notarización es un proceso específico de macOS en el que un desarrollador puede enviar una aplicación firmada con código a los servidores de Apple para verificar la presencia de componentes maliciosos a través de un servicio automatizado.
\nVer también: code signing
\nOSR (representación fuera de pantalla) puede ser usado para cargar una página pesada en segundo plano y luego mostrarla después (será mucho más rápido). It allows you to render page without showing it on screen.
\nPara más información, lea el tutorial Offscreen Rendering[osr].
\nLos scripts de precarga contienen el código que se ejecuta en un proceso de renderizado antes de que su contenido web comience a cargar. Estos scripts se ejecutan dentro del contexto del renderizador, pero tienen más privilegios al tener acceso a las APIs de Node.js.
\nVer también: renderer process, context isolation
\nUn proceso es una instancia en un programa de computadora que está siendo ejecutado. Aplicaciones de Electron que hacen usan de la main y uno o muchos procesos renderer están ejecutando varios programas simultáneamente.
\nEn Node.js y Electron, cada proceso en ejecución tiene un objeto de process. Este objeto es un global que proporciona información sobre, y control sobre, el proceso actual. Como un global, siempre está disponible para aplicaciones sin utilizar require().
Véase también: proceso principal, proceso de renderizado
\nEl renderer process es una ventana de navegador en tu aplicación. Unlike the main process, there can be multiple of these and each is run in a separate process. También pueden ocultarse.
\nVéase también: proceso, proceso principal
\nEl sandbox es una característica de seguridad heredada de Chromium que restringe tus procesos de rederizados a u conjunto limitado de permisos.
\nPara más información, lea el tutorial Process Sandboxing.
\nVer también: process
\nSquirrel es un marco de código abierto que permite a aplicaciones de Electron actualizar automáticamente como se liberan nuevas versiones. Ver el autoUpdater API para información sobre cómo empezar con Squirrel.
\nEste término que se originó en la comunidad Unix, donde \"userland\" o \"userspace\" se refiere a programas que se ejecutan afuera del kernel del sistema operativo. Más recientemente, el término se ha popularizado en la comunidad Node y npm para distinguir entre las características disponibles en el \"núcleo Node\" versus los paqutes publicados por el registro npm por la comunidad de \"usuarios\" mucho más grande.
\nComo Node, Electron se centra en tener un pequeño conjunto de APIs que proporcionan a todas las primitivas necesarias para el desarrollo de aplicaciones de escritorio multiplataformas. Esta filosofía de diseño permite Electron a seguir siendo una herramienta flexible sin ser excesivamente prescriptivas sobre cómo deben utilizarse. Userland permite a los usuarios crear y compartir herramientas que proporcionen funcionalidad adicional además de lo que está disponible en el \"núcleo\".
\nV8 es el motor JavaScript de código abierto de Google. Está escrito en C++ y es usado en Google Chrome. V8 puede ejecutarse de independiente o puede incrustarse en cualquier aplicación de C++.
\nElectrón forma V8 como parte de Chromium y luego apunta el Nodo ese V8 cuando lo está formando.
\nLos números de versión V8's siempre se corresponden con los de Google Chrome. Chrome 59 incluye V8 5.9, Chrome 58 incluye V8 5.8, etc.
\n\nwebview tags are used to embed 'guest' content (such as external web pages) in your Electron app. They are similar to iframes, but differ in that each webview runs in a separate process. No tiene los mismos permisos que su página web y todas las interacciones entre tu aplicación y el contenido incluido serán asincrónicas. Esto mantiene a tu aplicación protegida de contenido incluido.
\n\nGoma es un servicio de compilador distribuido para proyectos open-source tales como Chromium and Android.
\n
Electron tiene un despliegue de un Goma Backend personalizado que hacemos disponible para todos los Maintainers de Electron. Ve la sección de Acceso abajo para los detalles de autenticación. También hay un cache-only Goma endpoint que se usará por defecto si tu no tienes credenciales. Las solicitudes al cache-only Goma no afectarán a nuestro clúster, pero leerá de nuestra caché y debería resultar en tiempos de compilación significativamente más rápidos.
Actualmente la única forma de usar Goma es usar nuestro Build Tools. Goma configuración es automáticamente incluida cuando instalas build-tools.
Si eres un mantenedor y tienes acceso a nuestro cluster, por favor asegúrate de correr e init con --goma=cluster para configurar build-tools para utilizar Goma cluster. Si tienes una configuración existente, puedes establecer \"goma\": \"cluster\" en tu archivo de configuración.
Cuando estás usando Goma, puedes correr ninja con un valor sustancialmente alto de j que normalmente sería soportado por tu máquina.
Por favor no establezca un valor mayor a 200 en Windows o Linux y 50 en macOS. Supervisamos el uso del sistema Goma, y los usuarios que abusan de él con concurrencia irrazonable serán desactivados.
\nninja -C out/Testing electron -j 200\nSi está usando build-tools, los valores apropiados de -j se usarán automáticamente.
Si accedes a http://localhost:8088 en tu máquina local, puedes monitorear los trabajos de compilación como ellos fluyen a través del sistema de Goma.
\nPor razones de seguridad y costos, el acceso al cluster Goma de Electron actualmente está restringido a los Mantenedores de Electron. Si quieres acceder, por favor dirigase a #access-requests en Slack y pregunte a @goma-squad por el acceso. Por favor ten en cuenta que siendo un mantenedor no se concede automáticamente el acceso, y éste es determinado en caso por caso.
Hemos automatizado el monitoreo de nuestro clúster Goma y caché en https://status.notgoma.com
\nNo proporcionamos soporte para el uso de Goma cualquier propuesta planteada pidiendo ayuda / teniendo problemas probablemente se cerrarán sin mucha razón, no tenemos la capacidad para manejar ese tipo de soporte.
", "title": "Goma", "description": "Goma es un servicio de compilador distribuido para proyectos open-source tales como Chromium and Android." }, "/docs/api/structures/gpu-feature-status": { "locale": "es-ES", "slug": "gpu-feature-status", "href": "/docs/api/structures/gpu-feature-status", "crowdinFileId": "256439", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/gpu-feature-status.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "2d_canvas String - Canvas.flash_3d String - Flash.flash_stage3d String - Flash Stage3D.flash_stage3d_baseline String - Flash Stage3D Baseline profile.gpu_compositing String - Compositing.multiple_raster_threads String - Multiple Raster Threads.native_gpu_memory_buffers String - Native GpuMemoryBuffers.rasterization String - Rasterization.video_decode String - Video Decode.video_encode String - Video Encode.vpx_decode String - VPx Video Decode.webgl String - WebGL.webgl2 String - WebGL2.Posibles valores:
\ndisabled_software - Software only. Hardware acceleration disabled (yellow)disabled_off - Disabled (red)disabled_off_ok - Disabled (yellow)unavailable_software - Software only, hardware acceleration unavailable (yellow)unavailable_off - Unavailable (red)unavailable_off_ok - Unavailable (yellow)enabled_readback - Hardware accelerated but at reduced performance (yellow)enabled_force - Hardware accelerated on all pages (green)enabled - Hardware accelerated (green)enabled_on - Enabled (green)enabled_force_on - Force enabled (green)deviceId String - Identificador unico para el dispositivo.name String - Nombre del dispositivo.vendorId Integer - El ID del proveedor USB.productId Integer - El ID del producto USB.serialNumber String (opcional) - El número de serie del dispositivo USB.guid String (optional) - Identificador único para la interface del HID. Un dispositivo puede tener múltiples interfaces HID.\n\nCompras In-app en Mac App Store.
\n
Proceso: principal</0>
\nEl módulo inAppPurchase emite los siguientes eventos:
Emitido cuando una o más transacciones han sido actualizadas.
\nDevuelve:
\neventtransactions Transaction[] - Un array de objetos Transaction.El módulo inAppPurchase tiene los siguientes métodos:
inAppPurchase.purchaseProduct(productID[, quantity])productID String - El identificador del producto a comprar. (El identificador de com.example.app.product1 es product1).quantity Integer (opcional) - El número de ítems que el usuario quiere comprar.Devuelve Promise<Boolean> - Devuelve true si el producto es valido y añadido a la cola de pago.
Usted debería escuchar por el evento transactions-updated tan pronto como sea posible y sin dudas antes de llamar a purchaseProduct.
inAppPurchase.getProducts(productIDs)productIDs String[] - Los identificadores de los productos a obtener.Devuelve Promise<Product[]> - Resuelve con un array de objetos Product.
Recupera las descripciones del producto.
\ninAppPurchase.canMakePayments()Devuelve Boolean - si un usuario puede realizar un pago.
inAppPurchase.restoreCompletedTransactions()Restaura las transacciones finalizadas. This method can be called either to install purchases on additional devices, or to restore purchases for an application that the user deleted and reinstalled.
\nThe payment queue delivers a new transaction for each previously completed transaction that can be restored. Cada transacción incluye una copia de la transacción original.
\ninAppPurchase.getReceiptURL()Devuelve String - la ruta para el recibo.
inAppPurchase.finishAllTransactions()Completa todas las transacciones pendientes.
\ninAppPurchase.finishTransactionByDate(date)date String - La fecha en formato ISO de la transacción para terminar.Completa las pendientes transacciones correspondiendo al día.
", "title": "Compras integradas", "description": "Compras In-app en Mac App Store." }, "/docs/tutorial/in-app-purchases": { "locale": "es-ES", "slug": "in-app-purchases", "href": "/docs/tutorial/in-app-purchases", "crowdinFileId": "256203", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/in-app-purchases.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Si no lo has hecho todavia, tienes que firmar el Acuerdo de Aplicaciones de Pago y configurar tus dados bancarios y fiscales en iTunes Connect.
\nAyuda al desarrollador de iTunes Connect: Resumen de acuerdos, impuestos y bancos
\nDespués, debes configurar tus compras dentro de la App en iTunes Connect, e incluir detalles como nombre, precio, y un descriptivo que destaque las características y funcionalidades de tu compra dentro de la aplicación.
\nAyuda al desarrollador de iTunes Connect: Crear una compra dentro de la App
\nPara testar las compras dentro de la App, tienes que cambiar el CFBundleIdentifier en node_modules/electron/dist/Electron.app/Contents/Info.plist. Tienes que reemplazar com.github.electron por el identificador del paquete de la aplicación que creaste en iTunes Connect.
<key>CFBundleIdentifier</key>\n<string>com.example.app</string>\nAquí hay un ejemplo de como usar las compras dentro de la App en Electron. Tienes que reemplazar las IDs de los productos por los identificadores de los productos creados con iTunes Connect (el identificador de com.example.app.product1 es product1). Nota que tienes que escuchar al evento transactions-updated tan pronto como sea posible en tu App.
// Main process\nconst { inAppPurchase } = require('electron')\nconst PRODUCT_IDS = ['id1', 'id2']\n\n// Listen for transactions as soon as possible.\ninAppPurchase.on('transactions-updated', (event, transactions) => {\n if (!Array.isArray(transactions)) {\n return\n }\n\n // Verifica cada transacción.\n transactions.forEach(function (transaction) {\n const payment = transaction.payment\n\n switch (transaction.transactionState) {\n case 'purchasing':\n console.log(`Purchasing ${payment.productIdentifier}...`)\n break\n\n case 'purchased': {\n console.log(`${payment.productIdentifier} purchased.`)\n\n // Get the receipt url.\n const receiptURL = inAppPurchase.getReceiptURL()\n\n console.log(`Receipt URL: ${receiptURL}`)\n\n // Submit the receipt file to the server and check if it is valid.\n // @see https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html\n // ...\n // Si el recibo es válido, el producto es comprado\n // ...\n\n // Acaba la transacción.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n }\n\n case 'failed':\n\n console.log(`Failed to purchase ${payment.productIdentifier}.`)\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n case 'restored':\n\n console.log(`The purchase of ${payment.productIdentifier} has been restored.`)\n\n break\n case 'deferred':\n\n console.log(`The purchase of ${payment.productIdentifier} has been deferred.`)\n\n break\n default:\n break\n }\n })\n})\n\n// Verifica si el usuario tiene permitido realizar la compra.\nif (!inAppPurchase.canMakePayments()) {\n console.log('The user is not allowed to make in-app purchase.')\n}\n\n// Retrieve and display the product descriptions.\ninAppPurchase.getProducts(PRODUCT_IDS).then(products => {\n // Verificar los parámetros.\n if (!Array.isArray(products) || products.length <= 0) {\n console.log('Unable to retrieve the product informations.')\n return\n }\n\n // Display the name and price of each product.\n products.forEach(product => {\n console.log(`El precio de ${product.localizedTitle} es ${product.formattedPrice}.`)\n })\n\n // Pregunta al usuario cual producto el/ella quiere comprar.\n const selectedProduct = products[0]\n const selectedQuantity = 1\n\n // Purchase the selected product.\n inAppPurchase.purchaseProduct(selectedProduct.productIdentifier, selectedQuantity).then(isProductValid => {\n if (!isProductValid) {\n console.log('The product is not valid.')\n return\n }\n\n console.log('The payment has been added to the payment queue.')\n })\n})\n\n\nManeja las respuestas a las solicitudes HTTP/HTTPS.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
IncomingMessage implementa la interfaz Readable Stream y es por lo tanto un EventEmitter.
Devuelve:
\nchunk Buffer - Un fragmento de la colección de datos de respuesta.El evento data es el método habitual de transferir datos de respuesta en código aplicativo.
Indica que la respuesta del cuerpo ha finalizado. Debe colocarse antes del evento ' Data '.
\nAparece cuando una solicitud ha sido cancelada durante una transacción HTTP en curso.
\nDevuelve:
\nerror Error - Por lo general tiene tiene una cadena de error por la falla de la identificación de la causa raíz.
Aparece cuando se detecta un error mientras se transmiten los eventos de datos de respuesta. Por ejemplo, si el servidor cierra el subyacente mientras que la respuesta todavía se está transfiriendo, un evento data aparecerá como objeto de respuesta y un evento close seguirá posteriormente al objeto de la solicitud.
Una instancia IncomingMessage tiene las siguientes propiedades legibles:
response.statusCodeUn Integer indicando el código de estatus de respuesta HTTP.
response.statusMessageUna String representando el mensaje de estado HTTP.
response.headersUn Record<string, string | string[]> que representa las cabeceras de la respuesta HTTP. El objeto headers tiene el siguiente formato:
age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, server, o user-agent son descartados.set-cookie siempre es un array. Los duplicados son agregados al array.cookie duplicados, los valores se unen con '; '.response.httpVersionUna String que indica el número de versión de protocolo HTTP. Los valores típicos son \"1.0\" o \"1.1\". Adicionalmente httpVersionMajor y httpVersionMinor son dos propiedades legibles de valores enteros que devuelven los números de la versión principal y secundaria de HTTP respectivamente.
response.httpVersionMajorUn Integer que indica el número de la versión principal del protocolo HTTP.
response.httpVersionMinorUn Integer que indica el número de la versión secundaria del protocolo HTTP.
modifiers String - An array of modifiers of the event, can be shift, control, ctrl, alt, meta, command, cmd, isKeypad, isAutoRepeat, leftButtonDown, middleButtonDown, rightButtonDown, capsLock, numLock, left, right.To install prebuilt Electron binaries, use npm. The preferred method is to install Electron as a development dependency in your app:
npm install electron --save-dev\nPor favor, echa un vistazo a Electron versioning doc para información de como manejar version de Electron en tus apps.
\nIf you're in a pinch and would prefer to not use npm install in your local project, you can also run Electron ad-hoc using the npx command runner bundled with npm:
npx electron .\nThe above command will run the current working directory with Electron. Note that any dependencies in your app will not be installed.
\nSi quieres cambiar la arquitectura que será descargada (e.g, ia32 en una máquina x64), puedes usar el flag --arch con npm install o configurar la variable de entorno npm_config_arch:
npm install --arch=ia32 electron\nAdemás de cambiar la arquitectura, también se puede especificar la plataforma (e.g., win32, linux, etc.) utilizando el flag --platform:
npm install --platform=win32 electron\nIf you need to use an HTTP proxy, you need to set the ELECTRON_GET_USE_PROXY variable to any value, plus additional environment variables depending on your host system's Node version:
Durante la instalación, el módulo electron llamara a electron-download para descargar binarios precompilados de Electron para tu plataforma. Lo hará poniéndose en contacto con la página de descarga de versiones de GitHub (https://github.com/electron/electron/releases/tag/v$VERSION, donde $VERSION es la versión exacta de Electron).
Si no puede acceder a GitHub o necesita proporcionar una compilación personalizada, puede hacerlo proporcionando un espejo o un directorio de caché existente.
\nPuede usar variables de entorno para anular la URL base, la ruta en la cual buscar binarios de Electron y el nombre del archivo binario. The URL used by @electron/get is composed as follows:
url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME\nFor instance, to use the China CDN mirror:
\nELECTRON_MIRROR=\"https://cdn.npm.taobao.org/dist/electron/\"\nBy default, ELECTRON_CUSTOM_DIR is set to v$VERSION. To change the format, use the {{ version }} placeholder. For example, version-{{ version }} resolves to version-5.0.0, {{ version }} resolves to 5.0.0, and v{{ version }} is equivalent to the default. As a more concrete example, to use the China non-CDN mirror:
ELECTRON_MIRROR=\"https://npm.taobao.org/mirrors/electron/\"\nELECTRON_CUSTOM_DIR=\"{{ version }}\"\nThe above configuration will download from URLs such as https://npm.taobao.org/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip.
Si tu réplica sirve artefactos con diferentes sumas de verificación al del oficial de Electron, puede que tengas que establecer ELECTRON_USE_REMOTE_CHECKSUMS=1 para forzar a Electron a usar el archivo SHASUMS256.txt para verificar la suma de verificación en lugar de la comprobación incrustada.
Alternativamente, puede anular la memoria caché local. @electron-get almacenará en caché los archivos binarios descargados en un directorio local para no sobrecargar tu red. Puede usar esa carpeta de caché para proporcionar compilaciones personalizadas de Electron o para evitar hacer contacto con la red en absoluto.
$XDG_CACHE_HOME or ~/.cache/electron/~/Library/Caches/electron/$LOCALAPPDATA/electron/Cache or ~/AppData/Local/electron/Cache/En entornos que han estado usando versiones anteriores de Electron, también podrás encontrar la caché en ~/.electron.
También se puede anular la ubicación de almacenamiento en caché local al proporcionar una variable de entorno electron_config_cache.
The cache contains the version's official zip file as well as a checksum, stored as a text file. A typical cache might look like this:
\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9electron-v1.7.9-darwin-x64.zip\n│ └── electron-v1.7.9-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1electron-v1.8.1-darwin-x64.zip\n│ └── electron-v1.8.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1electron-v1.8.2-beta.1-darwin-x64.zip\n│ └── electron-v1.8.2-beta.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2electron-v1.8.2-beta.2-darwin-x64.zip\n│ └── electron-v1.8.2-beta.2-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3electron-v1.8.2-beta.3-darwin-x64.zip\n│ └── electron-v1.8.2-beta.3-darwin-x64.zip\n└── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3SHASUMS256.txt\n └── SHASUMS256.txt\nBajo suyo, la API JavaScript de Electron se une a un binario que contiene sus implementaciones. Because this binary is crucial to the function of any Electron app, it is downloaded by default in the postinstall step every time you install electron from the npm registry.
However, if you want to install your project's dependencies but don't need to use Electron functionality, you can set the ELECTRON_SKIP_BINARY_DOWNLOAD environment variable to prevent the binary from being downloaded. For instance, this feature can be useful in continuous integration environments when running unit tests that mock out the electron module.
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install\nCuando ejecutamos npm install electron, ocasionalmente algunos usuarios encuentran errores en la instalación.
En casi todos los casos, estos errores son resultados de problemas en la red y no de problemas con el paquete npm de electron. Errores como ELIFECYCLE, EAI_AGAIN, ECONNRESET y ETIMEDOUT son indicadores de dichos problemas de red. La mejor solución es tratar de cambiar las redes, o esperar un poco e instalar de nuevo.
You can also attempt to download Electron directly from electron/electron/releases if installing via npm is failing.
If installation fails with an EACCESS error you may need to fix your npm permissions.
If the above error persists, the unsafe-perm flag may need to be set to true:
\nsudo npm install electron --unsafe-perm=true\nEn redes lentas, puede ser aconsejable utilizar la marca --verbose de manera que se muestre el progreso de la descarga:
npm install --verbose electron\nSi necesita forzar que se vuelvan a descargar el recurso y el archivo SHASUM, fije la variable de entorno force_no_cache a true.
Bienvenido a la documentacion de Electron! Si es esta es tu primera vez programando una aplicacion de Electron, lea esta sección de Introducción para familiarizarse con lo esencial. De lo contrario, sientase libre de explorar nuestra guias y documentaciones sobre nuestra API!
\nElectron es un framework para crear aplicaciones de escritorio usando JavaScript, HTML y CSS. Incrustando Chromium y Node.js dentro del mismo, Electron le permite mantener una base de código JavaScript y crear aplicaciones multiplataforma que funcionan en Windows, macOS y Linux, - no requiere experiencia en desarrollo nativo.
\nEstos documentos funcionan bajo el supuesto de que el lector está familiarizado con ambos Node.js y desarrollo web en general. Si necesita sentirse más cómodo con cualquiera de estas áreas, recomendamos los siguientes recursos:
\n\nAdemás, tendrá un mejor momento para comprender cómo funciona Electron si obtiene familiarizado con el modelo de proceso de Chromium. Puede obtener una breve descripción general de Arquitectura de Chrome con el cómic de Chrome , que se lanzó junto Lanzamiento de Chrome en 2008. Aunque ha pasado más de una década desde entonces, el Los principios básicos introducidos en el cómic siguen siendo útiles para comprender a Electron.
\nElectron Fiddle es una sandbox app escrita con Electron y apoyado por Mantenedores de Electron. Recomendamos encarecidamente instalarlo como herramienta de aprendizaje para Experimente con las API de Electron o para crear prototipos de funciones durante el desarrollo.
\nFiddle también se integra muy bien con nuestra documentación. Al navegar a través de ejemplos en nuestros tutoriales, verá con frecuencia un botón \"Abrir en Electron Fiddle\" debajo un bloque de código. Si tiene Fiddle instalado, este botón abrirá un link a fiddle.electronjs.org esto cargará automáticamente el ejemplo en Fiddle, no es necesario copiar y pegar.
¿Te quedas atascado en alguna parte? Aquí hay algunos enlaces a lugares para buscar:
\nelectron. por favor revisa el GitHub issue tracker para ver si algún problema existente coincide con tu problema. Si no, no dudes en rellenar nuestra plantilla de informe de errores y enviar un nuevo problema.readOperationCount Number - The number of I/O read operations.writeOperationCount Number - The number of I/O write operations.otherOperationCount Number - Then number of I/O other operations.readTransferCount Number - The number of I/O read transfers.writeTransferCount Number - The number of I/O write transfers.otherTransferCount Number - Then number of I/O other transfers.\n\nSe comunica de forma asincrónica desde el proceso principal a los procesos de renderizado.
\n
Proceso: principal</0>
\nEl módulo ipcMain es un Event Emitter. Cuando se utiliza en el proceso principal, maneja mensajes asincrónicos y sincrónicos enviados desde el proceso de renderizado (página web). Los mensajes enviados desde el renderizador serán emitidos a este módulo.
También es posible enviar mensajes desde el proceso principal al proceso de renderizado, ver webContents.send para más información.
\nchannel.event.returnValue.event.reply(...). Este método de ayuda automáticamente va a manejar los mensajes entrantes desde frames que no son el frame principal (ejemplo iframes) mientras que event.sender.send(...) siempre enviará al frame principal.Ejemplo de envío y manejo de mensajes entre el proceso de renderizado y el principal:
\n// In main process.\nconst { ipcMain } = require('electron')\nipcMain.on('asynchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.reply('asynchronous-reply', 'pong')\n})\n\nipcMain.on('synchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.returnValue = 'pong'\n})\n// In renderer process (web page).\n// NB. Electron APIs are only accessible from preload, unless contextIsolation is disabled.\n// Vea https://www.electronjs.org/docs/tutorial/process-model#preload-scripts para más detalles.\nconst { ipcRenderer } = require('electron')\nconsole.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // prints \"pong\"\n\nipcRenderer.on('asynchronous-reply', (event, arg) => {\n console.log(arg) // prints \"pong\"\n})\nipcRenderer.send('asynchronous-message', 'ping')\nEl módulo ipcMain tiene el siguiente método para escuchar los eventos:
ipcMain.on(channel, listener)channel Cadenalistener Funciónevent IpcMainEvent...args any[]Escucha al channel. Cuando llega un nuevo mensaje listener es llamado con listener(event, args...).
ipcMain.once(channel, listener)channel Cadenalistener Funciónevent IpcMainEvent...args any[]Adds a one time listener function for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed.
ipcMain.removeListener(channel, listener)channel Cadenalistener Función...args any[]Elimina el listener especificado del arreglo listener para el channel especificado.
ipcMain.removeAllListeners([channel])channel Cadena (opcional)Elimina los oyentes del channel especificado.
ipcMain.handle(channel, listener)channel Cadenalistener Function<Promise\\event IpcMainInvokeEvent...args any[]Adds a handler for an invokeable IPC. This handler will be called whenever a renderer calls ipcRenderer.invoke(channel, ...args).
Si listener devuelve una Promise, el eventual resultado de la promise será devuelto como una respuesta al controlador remoto. De lo contrario, el valor de retorno del listener será usado como el valor de la respuesta.
// Main process\nipcMain.handle('my-invokable-ipc', async (event, ...args) => {\n const result = await somePromise(...args)\n return result\n})\n\n// Renderer process\nasync () => {\n const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)\n // ...\n}\nEl event que es pasado como primer argumento al handler es el mismo que es pasado a un event listener normal. Incluye información sobre cual WebContents es el origen de la solicitud invocada.
Los errores lanzados a través de handle en el main process no son transparentes, ya que se serializan y solo la propiedad message del error original es proveído al renderer process. Por favor, consulte #24427 para más detalles.
ipcMain.handleOnce(channel, listener)channel Cadenalistener Function<Promise\\event IpcMainInvokeEvent...args any[]Maneja un solo invokeable mensaje IPC, luego elimina el listener. See ipcMain.handle(channel, listener).
ipcMain.removeHandler(channel)channel CadenaElimina cualquier controlador para channel, si hay.
La documentación para el objeto event pasado a callback puede ser encontrada en la estructura de documentos de ipc-main-event.
La documentación para el objeto event pasado a handle callbacks puede ser encontrada en la estructura de documentos ipc-main-invoke-event.
EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagereturnValue any - Set this to the value to be returned in a synchronous messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this messageports MessagePortMain[] - A list of MessagePorts that were transferred with this messagereply Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to \"reply\" to the sent message in order to guarantee the reply will go to the correct process and frame.channel String...args any[]EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this message\n\nComunica asincrónicamente desde un proceso de renderizado al proceso principal.
\n
Proceso: Renderer
\nEl módulo ipcRenderer es un EventEmitter. Proporciona un par de métodos para enviar mensajes sincrónicos y asincrónicos desde el proceso de renderizado (página web) al proceso principal. También puede recibir respuestas del proceso principal.
Ver ipcMain para ejemplos de códigos.
\nEl módulo ipcRenderer tiene los siguientes métodos para escuchar los eventos y mensajes enviados:
ipcRenderer.on(channel, listener)channel Cadenalistener Funciónevent IpcRendererEvent...args any[]Escucha al channel. Cuando llega un nuevo mensaje listener es llamado con listener(event, args...).
ipcRenderer.once(channel, listener)channel Cadenalistener Funciónevent IpcRendererEvent...args any[]Adds a one time listener function for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed.
ipcRenderer.removeListener(channel, listener)channel Cadenalistener Función...args any[]Elimina el listener especificado del arreglo listener para el channel especificado.
ipcRenderer.removeAllListeners(channel)channel CadenaElimina todos los oyentes, o aquellos del channel especificado.
ipcRenderer.send(channel, ...args)channel Cadena...args any[]Envía un mensaje asíncrono al main process a través de channel, junto con los argumentos. Los argumentos serán serializados con el Structured CloneAlgorithm, al igual que window.postMessage, así que las cadenas del prototipo no estarán incluidas. El envío de funciones, promesas, símbolos, WeakMaps o WeakSets lanzará una excepción.
\n\nNOTA: Enviar tipos de JavaScript no estándar tales como objetos DOM o objetos especiales de Electron lanzará una excepción.
\nDado que el proceso principal no tiene soporte para objetos DOM tales como
\nImageBitmap,File,DOMMatrixy así sucesivamente, tales objetos no pueden ser enviados sobre el IPC de Eectron al proceso principal, ya que el proceso principal no tendría forma de decodificarlos. Intentar enviar tales objetos sobre el IPC resultará en un error.
El main process maneja esto escuchando por channel con el módulo ipcMain.
If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you want to receive a single response from the main process, like the result of a method call, consider using ipcRenderer.invoke.
ipcRenderer.invoke(channel, ...args)channel Cadena...args any[]Devuelve Promise<any> - Resuelve con la respuesta desde el main process.
Envía un mensaje al main process a través de channel y espera un resultado asíncrono. Los argumentos serán serializados con el Structured CloneAlgorithm, al igual que window.postMessage, así que las cadenas del prototipo no estarán incluidas. El envío de funciones, promesas, símbolos, WeakMaps o WeakSets lanzará una excepción.
\n\nNOTA: Enviar tipos de JavaScript no estándar tales como objetos DOM o objetos especiales de Electron lanzará una excepción.
\nDado que el proceso principal no tiene soporte para objetos DOM tales como
\nImageBitmap,File,DOMMatrixy así sucesivamente, tales objetos no pueden ser enviados sobre el IPC de Eectron al proceso principal, ya que el proceso principal no tendría forma de decodificarlos. Intentar enviar tales objetos sobre el IPC resultará en un error.
El main process debería escuchar por el channel con ipcMain.handle().
Por ejemplo:
\n// Renderer process\nipcRenderer.invoke('some-name', someArgument).then((result) => {\n // ...\n})\n\n// Main process\nipcMain.handle('some-name', async (event, someArgument) => {\n const result = await doSomeWork(someArgument)\n return result\n})\nIf you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you do not need a response to the message, consider using ipcRenderer.send.
ipcRenderer.sendSync(channel, ...args)channel Cadena...args any[]Devuelve any - El valor enviado de vuelta por el controlador ipcMain.
Envía un mensaje al main process a través de channel y expera un resultado sincrónicamente. Los argumentos serán serializados con el Structured CloneAlgorithm, al igual que window.postMessage, así que las cadenas del prototipo no estarán incluidas. El envío de funciones, promesas, símbolos, WeakMaps o WeakSets lanzará una excepción.
\n\nNOTA: Enviar tipos de JavaScript no estándar tales como objetos DOM o objetos especiales de Electron lanzará una excepción.
\nDado que el proceso principal no tiene soporte para objetos DOM tales como
\nImageBitmap,File,DOMMatrixy así sucesivamente, tales objetos no pueden ser enviados sobre el IPC de Eectron al proceso principal, ya que el proceso principal no tendría forma de decodificarlos. Intentar enviar tales objetos sobre el IPC resultará en un error.
El processo principal lo controlo por escuchar channel con el módulo ipcMain, y contesta configurando event.returnValue.
\n\n⚠️ ADVERTENCIA: El envío de un mensaje síncrono bloqueará todo el proceso del renderizador hasta que se reciba la respuesta, así que use este método solo como último recurso. Es mucho mejor usar la versión asincróna
\ninvoke().
ipcRenderer.postMessage(channel, message, [transfer])Send a message to the main process, optionally transferring ownership of zero or more MessagePort objects.
The transferred MessagePort objects will be available in the main process as MessagePortMain objects by accessing the ports property of the emitted event.
Por ejemplo:
\n// Renderer process\nconst { port1, port2 } = new MessageChannel()\nipcRenderer.postMessage('port', { message: 'hello' }, [port1])\n\n// Main process\nipcMain.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nPara más información sobre el uso de MessagePort y MessageChannel, vea la Documentación MDN.
ipcRenderer.sendTo(webContentsId, channel, ...args)webContentsId Numberchannel Cadena...args any[]Envía un mensaje a la ventana con webContentsId a través de channel.
ipcRenderer.sendToHost(channel, ...args)channel Cadena...args any[]Es como ipcRenderer.send pero el evento se enviará al <webview>elemento en la página host en vez de el proceso principal.
La documentación para el objeto event pasado a callback pude ser encontrada en la estructura de documentos de ipc-renderer-event.
Eventsender IpcRenderer - The IpcRenderer instance that emitted the event originallysenderId Integer - The webContents.id that sent the message, you can call event.sender.sendTo(event.senderId, ...) to reply to the message, see ipcRenderer.sendTo for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set event.senderId to 0.ports MessagePort[] - A list of MessagePorts that were transferred with this messagePara cualquier problema, existen fundamentalmente tres maneras en las que un individuo puede contribuir:
\nelectron/electron issue tracker.electron/electron de una manera concreta y susceptible de revisión.\"Finding Support\" tiene una lista de recursos para obtener ayuda de programación, reportar problemas de seguridad, contribuir y más. ¡Por favor, use el gestor de incidencias solo para errores!
\nPara enviar un informe de error:
\nCuando abre una nueva incidencia en el electron/electron issue tracker, los usuarios se les presentará una plantilla que debe ser completada.
If you believe that you have found a bug in Electron, please fill out the template to the best of your ability.
\nLas dos informaciones mas importantes necesarias para evaluar el informe son, la descripción del error y un caso de prueba simple para recrearlo. Es más fácil resolver un problema si este se puede reproducir.
\nVéase Como crear un Mínimo, Completo y Verificable ejemplo.
\nEs común que los problemas abiertos se acompañen con un debate. Algunos contribuyentes pueden tener diferentes opiniones, incluyendo si se comporta como un fallo o una funcionalidad. La discusión es parte del proceso y debe mantenerse centrada, útil y profesional.
\nRespuestas bruscas que no proveen contexto adiciona o detalles de apoyo, no son útiles o profesionales. Para muchos, tales respuestas son molestas y dañinas.
\nLos contribuyentes están animados a resolver problemas de manera colaborativa y ayudarse mutuamente a progresar. Si encuentras un fallo que crees que es inválido o que contiene información errónea, explica por qué crees eso añadiendo contexto adicional y estando dispuesto a convencerse de que puedes estar equivocado. Al hacerlo, podemos a menudo alcanzar la solución correcta de manera rápida.
\nLa mayoría de los problemas son resueltos al abrir un pull request. El proceso para abrir y revisar un pull request es similar a abrir y seguir los problemas, pero conlleva una revisión necesaria y aprobar un workflow que asegure que los cambios propuestos tengan una mínima calidad y criterios funcionales del proyecto Electron.
", "title": "Problemas en Electron", "description": "" }, "/docs/api/structures/jump-list-category": { "locale": "es-ES", "slug": "jump-list-category", "href": "/docs/api/structures/jump-list-category", "crowdinFileId": "256451", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/jump-list-category.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "type String (optional) - One of the following:tasks - Items in this category will be placed into the standard Tasks category. There can be only one such category, and it will always be displayed at the bottom of the Jump List.frequent - Displays a list of files frequently opened by the app, the name of the category and its items are set by Windows.recent - Displays a list of files recently opened by the app, the name of the category and its items are set by Windows. Items may be added to this category indirectly using app.addRecentDocument(path).custom - Displays tasks or file links, name must be set by the app.name String (optional) - Must be set if type is custom, otherwise it should be omitted.items JumpListItem - Array of JumpListItem objects if type is tasks or custom, otherwise it should be omitted.Note: If a JumpListCategory object has neither the type nor the name property set then its type is assumed to be tasks. If the name property is set but the type property is omitted then the type is assumed to be custom.
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
type String (optional) - One of the following:task - A task will launch an app with specific arguments.separator - Can be used to separate items in the standard Tasks category.file - A file link will open a file using the app that created the Jump List, for this to work the app must be registered as a handler for the file type (though it doesn't have to be the default handler).path String (optional) - Path of the file to open, should only be set if type is file.program String (optional) - Path of the program to execute, usually you should specify process.execPath which opens the current program. Should only be set if type is task.args String (optional) - The command line arguments when program is executed. Should only be set if type is task.title String (optional) - The text to be displayed for the item in the Jump List. Should only be set if type is task.description String (optional) - Description of the task (displayed in a tooltip). Should only be set if type is task. Maximum length 260 characters.iconPath String (optional) - The absolute path to an icon to be displayed in a Jump List, which can be an arbitrary resource file that contains an icon (e.g. .ico, .exe, .dll). You can usually specify process.execPath to show the program icon.iconIndex Number (optional) - The index of the icon in the resource file. If a resource file contains multiple icons this value can be used to specify the zero-based index of the icon that should be displayed for this task. If a resource file contains only one icon, this property should be set to zero.workingDirectory String (optional) - The working directory. Default is empty.ctrlKey Boolean (optional) - whether the Control key was used in an accelerator to trigger the EventmetaKey Boolean (optional) - whether a meta key was used in an accelerator to trigger the EventshiftKey Boolean (optional) - whether a Shift key was used in an accelerator to trigger the EventaltKey Boolean (optional) - whether an Alt key was used in an accelerator to trigger the EventtriggeredByAccelerator Boolean (optional) - whether an accelerator was used to trigger the event as opposed to another user gesture like mouse clickInputEventtype String - The type of the event, can be keyDown, keyUp or char.keyCode String - The character that will be sent as the keyboard event. Should only use the valid key codes in Accelerator.Esta característica le permite configurar atajos de teclado loca y global para tu aplicación Electron.
\nLos atajos de teclado locales son activadas sólo cuando la aplicación está enfocada. Para configurar un atajo de teclado local, necesitas especificar una propiedad accelerator al crear un MenuItem dentro de módulo Menu.
Comenzando con una aplicación funcionando desde Guía de Inicio Rápido, actualiza el archivo main.js con las siguiente lineas:
const { Menu, MenuItem } = require('electron')\n\nconst menu = new Menu()\nmenu.append(new MenuItem({\n label: 'Electron',\n submenu: [{\n role: 'help',\n accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Alt+Shift+I',\n click: () => { console.log('Electron rocks!') }\n }]\n}))\n\nMenu.setApplicationMenu(menu)\n\n\nNOTA: En el código anterior, puede ver que el acelerador difiere según el sistema operativo del usuario. Para MacOS, es
\nAlt+Cmd+I, mientras que para Linux y Windows, esAlt+Shift+I.
Después de lanzar la aplicación Electron, deberías ver el menú de la aplicación junto con el el atajo local que acabas de definir:
\n
Si haces click en Help o presionas el acelerador definido y luego abres la terminal con la que corriste tu Aplicación, veras el mensaje que fue generado después de llamar al evento del click: \"Electron rocks!\".
Para configurar un atajo de teclado global, necesita usar el módulo globalShortcut para detecta los eventos del teclado cuando la aplicación no tiene el focus del teclado.
\nComenzando con una aplicación funcionando desde Guía de Inicio Rápido, actualiza el archivo main.js con las siguiente lineas:
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n globalShortcut.register('Alt+CommandOrControl+I', () => {\n console.log('Electron loves global shortcuts!')\n })\n}).then(createWindow)\n\n\nNOTA: En el código anterior, la combinación
\nCommandOrControlusaCommanden macOS yControlen Windows/Linux.
Después de lanzar la aplicación Electron, si presionas la combinación de teclas definida y luego abres la terminar desde la que corriste tu aplicación de Electron, ¡verás como Electron ama los atajos de teclado globales!
\nSi quieres manejar los atajos de teclado dentro de un BrowserWindow, puedes escuchar por los Eventos DOM keyup y keydown dentro del renderer process usando la API addEventListener().
function handleKeyPress(event) {\n // You can put code here to handle the keypress.\n document.getElementById(\"last-keypress\").innerText = event.key;\n console.log(`You pressed ${event.key}`);\n}\n\nwindow.addEventListener('keyup', handleKeyPress, true);\n\n\nNote: the third parameter
\ntrueindicates that the listener will always receive key presses before other listeners so they can't havestopPropagation()called on them.
El Evento antes de la entrada es emitido antes de enviar los eventos flecha hacia arriba y flecha hacia abajo en la página. Puede ser usado para capturar y manejar accesos directos personalizados que no son visibles en el menú.
Comenzando con una aplicación funcionando desde Guía de Inicio Rápido, actualiza el archivo main.js con las siguiente lineas:
const { app, BrowserWindow } = require('electron')\n\napp.whenReady().then(() => {\n const win = new BrowserWindow({ width: 800, height: 600 })\n\n win.loadFile('index.html')\n win.webContents.on('before-input-event', (event, input) => {\n if (input.control && input.key.toLowerCase() === 'i') {\n console.log('Pressed Control+I')\n event.preventDefault()\n }\n })\n})\nDespués de correr tu aplicación, abres la terminal con la que corriste tu aplicación y presionas la combinación de teclas Ctrl+I, veras como ese atajo del teclado fue satisfactoriamente interceptado.
Si no quiere hacer el análisis manual de los atajos hay librerías que hacen detección de teclas avanzadas, como mousetrap. A continuación se muestran ejemplos de uso de mousetrap corriendo en el Renderer process:
Mousetrap.bind('4', () => { console.log('4') })\nMousetrap.bind('?', () => { console.log('show shortcuts!') })\nMousetrap.bind('esc', () => { console.log('escape') }, 'keyup')\n\n// combinations\nMousetrap.bind('command+shift+k', () => { console.log('command shift k') })\n\n// map multiple combinations to the same callback\nMousetrap.bind(['command+k', 'ctrl+k'], () => {\n console.log('command k or control k')\n\n // return false to prevent default behavior and stop event from bubbling\n return false\n})\n\n// gmail style sequences\nMousetrap.bind('g i', () => { console.log('go to inbox') })\nMousetrap.bind('* a', () => { console.log('select all') })\n\n// konami code!\nMousetrap.bind('up up down down left right left right b a enter', () => {\n console.log('konami code')\n})\ntitle: Launching Your Electron App From a URL In Another App\ndescription: This guide will take you through the process of setting your electron app as the default handler for a specific protocol.\nslug: launch-app-from-url-in-another-app
\nThis guide will take you through the process of setting your Electron app as the default handler for a specific protocol.
\nBy the end of this tutorial, we will have set our app to intercept and handle any clicked URLs that start with a specific protocol. In this guide, the protocol we will use will be \"electron-fiddle://\".
First, we will import the required modules from electron. These modules help control our application lifecycle and create a native browser window.
const { app, BrowserWindow, shell } = require('electron')\nconst path = require('path')\nNext, we will proceed to register our application to handle all \"electron-fiddle://\" protocols.
if (process.defaultApp) {\n if (process.argv.length >= 2) {\n app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])\n }\n} else {\n app.setAsDefaultProtocolClient('electron-fiddle')\n}\nWe will now define the function in charge of creating our browser window and load our application's index.html file.
const createWindow = () => {\n // Create the browser window.\n mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n mainWindow.loadFile('index.html')\n}\nIn this next step, we will create our BrowserWindow and tell our application how to handle an event in which an external protocol is clicked.
This code will be different in Windows compared to MacOS and Linux. This is due to Windows requiring additional code in order to open the contents of the protocol link within the same Electron instance. Lea más sobre esto aquí.
\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Alguien trata de correr una segunda instancia, debemos enfocar nuestra ventana.\n if (mainWindow) {\n if (mainWindow.isMinimized()) mainWindow.restore()\n mainWindow.focus()\n }\n })\n\n // Crear mainWindow, cargar el resto de la aplicación, etc...\n app.whenReady().then(() => {\n createWindow()\n })\n\n // Handle the protocol. En este caso, elegimos mostrar una Caja de Error.\n app.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n })\n}\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// Algunas APIs pueden solamente ser usadas despues de que este evento ocurra.\napp.whenReady().then(() => {\n createWindow()\n})\n\n// Handle the protocol. En este caso, elegimos mostrar una Caja de Error.\napp.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n})\nFinally, we will add some additional code to handle when someone closes our application.
\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') app.quit()\n})\nOn macOS and Linux, this feature will only work when your app is packaged. It will not work when you're launching it in development from the command-line. When you package your app you'll need to make sure the macOS Info.plist and the Linux .desktop files for the app are updated to include the new protocol handler. Some of the Electron tools for bundling and distributing apps handle this for you.
If you're using Electron Forge, adjust packagerConfig for macOS support, and the configuration for the appropriate Linux makers for Linux support, in your Forge configuration (please note the following example only shows the bare minimum needed to add the configuration changes):
{\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"protocols\": [\n {\n \"name\": \"Electron Fiddle\",\n \"schemes\": [\"electron-fiddle\"]\n }\n ]\n },\n \"makers\": [\n {\n \"name\": \"@electron-forge/maker-deb\",\n \"config\": {\n \"mimeType\": [\"x-scheme-handler/electron-fiddle\"]\n }\n }\n ]\n }\n }\n}\nFor macOS support:
\nIf you're using Electron Packager's API, adding support for protocol handlers is similar to how Electron Forge is handled, except protocols is part of the Packager options passed to the packager function.
const packager = require('electron-packager')\n\npackager({\n // ...other options...\n protocols: [\n {\n name: 'Electron Fiddle',\n schemes: ['electron-fiddle']\n }\n ]\n\n}).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))\n .catch(err => console.error(`ERROR: ${err.message}`))\nIf you're using Electron Packager's CLI, use the --protocol and --protocol-name flags. For example:
npx electron-packager . --protocol=electron-fiddle --protocol-name=\"Electron Fiddle\"\nAfter you start your Electron app, you can enter in a URL in your browser that contains the custom protocol, for example \"electron-fiddle://open\" and observe that the application will respond and show an error dialog box.
En muchos entornos Linux, puede agregar entradas personalizadas al lanzador del sistema modificando el archivo .desktop. Para la documentación de Unity de Canonical, vea Agregar atajos al Lanzador. Para obtener detalles sobre una implementación más genérica, vea la freedesktop.org Especificación.
\n\nNOTA: La captura de la pantalla anterior es un ejemplo de atajos de lanzador en el reproductor de audio Audacious
\n
Para crear un atajo, necesita proveer las propiedades Name y Exec para la entrada que quieres agregar al atajo del menú. Unity ejecutará el comando definido en el campo Exec después que el usuario pulse en el elemento del menú de acceso directo. Un ejemplo del archivo .desktop puede lucir de la siguiente manera:
Actions=PlayPause;Next;Previous\n\n[Desktop Action PlayPause]\nName=Play-Pause\nExec=audacious -t\nOnlyShowIn=Unity;\n\n[Desktop Action Next]\nName=Next\nExec=audacious -f\nOnlyShowIn=Unity;\n\n[Desktop Action Previous]\nName=Previous\nExec=audacious -r\nOnlyShowIn=Unity;\nLa forma preferida de Unity para instruir a su aplicación sobre qué hacer es usar parámetros. Puedes encontrarlos en tu aplicación en la variable global process.argv.
This guide provides information on:
\nTo sign Electron apps, the following tools must be installed first:
\nYou also have to register an Apple Developer account and join the Apple Developer Program.
\nElectron apps can be distributed through Mac App Store or outside it. Each way requires different ways of signing and testing. This guide focuses on distribution via Mac App Store, but will also mention other methods.
\nThe following steps describe how to get the certificates from Apple, how to sign Electron apps, and how to test them.
\nThe simplest way to get signing certificates is to use Xcode:
\nThe \"Apple Development\" certificate is used to sign apps for development and testing, on machines that have been registered on Apple Developer website. The method of registration will be described in Prepare provisioning profile.
\nApps signed with the \"Apple Development\" certificate cannot be submitted to Mac App Store. For that purpose, apps must be signed with the \"Apple Distribution\" certificate instead. But note that apps signed with the \"Apple Distribution\" certificate cannot run directly, they must be re-signed by Apple to be able to run, which will only be possible after being downloaded from the Mac App Store.
\nYou may notice that there are also other kinds of certificates.
\nThe \"Developer ID Application\" certificate is used to sign apps before distributing them outside the Mac App Store.
\nThe \"Developer ID Installer\" and \"Mac Installer Distribution\" certificates are used to sign the Mac Installer Package instead of the app itself. Most Electron apps do not use Mac Installer Package so they are generally not needed.
\nThe full list of certificate types can be found here.
\nApps signed with \"Apple Development\" and \"Apple Distribution\" certificates can only run under App Sandbox, so they must use the MAS build of Electron. However, the \"Developer ID Application\" certificate does not have this restrictions, so apps signed with it can use either the normal build or the MAS build of Electron.
\nApple has been changing the names of certificates during past years, you might encounter them when reading old documentations, and some utilities are still using one of the old names.
\nIf you want to test your app on your local machine before submitting your app to the Mac App Store, you have to sign the app with the \"Apple Development\" certificate with the provisioning profile embedded in the app bundle.
\nTo create a provisioning profile, you can follow the below steps:
\n/path/to/yourapp.provisionprofile.Apps submitted to the Mac App Store must run under Apple's App Sandbox, and only the MAS build of Electron can run with the App Sandbox. The standard darwin build of Electron will fail to launch when run under App Sandbox.
\nWhen signing the app with electron-osx-sign, it will automatically add the necessary entitlements to your app's entitlements, but if you are using custom entitlements, you must ensure App Sandbox capacity is added:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n </dict>\n</plist>\nelectron-osx-signIf you are signing your app without using electron-osx-sign, you must ensure the app bundle's entitlements have at least following keys:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.application-groups</key>\n <array>\n <string>TEAM_ID.your.bundle.id</string>\n </array>\n </dict>\n</plist>\nThe TEAM_ID should be replaced with your Apple Developer account's Team ID, and the your.bundle.id should be replaced with the App ID of the app.
And the following entitlements must be added to the binaries and helpers in the app's bundle:
\n\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.inherit</key>\n <true/>\n </dict>\n</plist>\nAnd the app bundle's Info.plist must include ElectronTeamID key, which has your Apple Developer account's Team ID as its value:
<plist version=\"1.0\">\n<dict>\n ...\n <key>ElectronTeamID</key>\n <string>TEAM_ID</string>\n</dict>\n</plist>\nWhen using electron-osx-sign the ElectronTeamID key will be added automatically by extracting the Team ID from the certificate's name. You may need to manually add this key if electron-osx-sign could not find the correct Team ID.
To sign an app that can run on your development machine, you must sign it with the \"Apple Development\" certificate and pass the provisioning profile to electron-osx-sign.
electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile\nIf you are signing without electron-osx-sign, you must place the provisioning profile to YourApp.app/Contents/embedded.provisionprofile.
The signed app can only run on the machines that registered by the provisioning profile, and this is the only way to test the signed app before submitting to Mac App Store.
\nTo sign an app that will be submitted to Mac App Store, you must sign it with the \"Apple Distribution\" certificate. Note that apps signed with this certificate will not run anywhere, unless it is downloaded from Mac App Store.
\nelectron-osx-sign YourApp.app --identity='Apple Distribution'\nIf you don't plan to submit the app to Mac App Store, you can sign it the \"Developer ID Application\" certificate. In this way there is no requirement on App Sandbox, and you should use the normal darwin build of Electron if you don't use App Sandbox.
\nelectron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess\nBy passing --no-gatekeeper-assess, the electron-osx-sign will skip the macOS GateKeeper check as your app usually has not been notarized yet by this step.
This guide does not cover App Notarization, but you might want to do it otherwise Apple may prevent users from using your app outside Mac App Store.
\nAfter signing the app with the \"Apple Distribution\" certificate, you can continue to submit it to Mac App Store.
\nHowever, this guide do not ensure your app will be approved by Apple; you still need to read Apple's Submitting Your App guide on how to meet the Mac App Store requirements.
\nThe Application Loader should be used to upload the signed app to iTunes Connect for processing, making sure you have created a record before uploading.
\nIf you are seeing errors like private APIs uses, you should check if the app is using the MAS build of Electron.
\nAfter uploading, you should submit your app for review.
\nCon el fin de satisfacer todos los requerimientos de las aplicaciones en la caja de arena, los siguientes módulos han sido deshabilitados en la estructura del MAS:
\ncrashReporterautoUpdatery los siguientes comportamientos han sido cambiados:
\nIgualmente, dado el uso de las aplicaciones en caja de arena, los recursos que pueden ser accesados por la aplicación son limitados; puede leer App Sandboxing para más información.
\nDepending on which Electron APIs your app uses, you may need to add additional entitlements to your app's entitlements file. Otherwise, the App Sandbox may prevent you from using them.
\nHabilitar conexiones de red salientes para permitir que su aplicación se conecte al servidor:
\n<key>com.apple.security.network.client</key>\n<true/>\nHabilitar conexiones de red entrantes para permitir que su aplicación abra puertos de escucha:
\n<key>com.apple.security.network.server</key>\n<true/>\nVea la Documentación sobre la habilitación del acceso de red para más detalles.
\n<key>com.apple.security.files.user-selected.read-only</key>\n<true/>\nVea la documentación sobre la habilitación del acceso del usuario a archivos seleccionados para más información.
\n<key>com.apple.security.files.user-selected.read-write</key>\n<true/>\nVea la documentación sobre la habilitación del acceso del usuario a archivos seleccionados para más información.
\nDependiendo de los países en los que estás lanzando tu aplicación, puedes ser necesario proporcionar información sobre los algoritmos criptográficos utilizados en tu software. Ver encryption export compliance docs para mas información.
\nElectron usa los siguientes algoritmos criptográficos:
\nElectron tiene APIs para configurar el icono de la aplicación en el Dock de macOS. Solo existe una API macOS para crear menú de dock personalizado, pero Electron además usa el icono de app dock como el punto de entrada para características multiplataforma como recent documents y application progress.
\nLa base de acoplamiento personalizada se utiliza habitualmente para añadir accesos directos a las tareas para las que el usuario no desea abrir toda la ventana de la aplicación.
\nMenú Dock de Terminal.app:
\n
To set your custom dock menu, you need to use the app.dock.setMenu API, which is only available on macOS.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, BrowserWindow, Menu } = require('electron')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n })\n\n win.loadFile('index.html')\n}\n\nconst dockMenu = Menu.buildFromTemplate([\n {\n label: 'New Window',\n click () { console.log('New Window') }\n }, {\n label: 'New Window with Settings',\n submenu: [\n { label: 'Basic' },\n { label: 'Pro' }\n ]\n },\n { label: 'New Command...' }\n])\n\napp.whenReady().then(() => {\n if (process.platform === 'darwin') {\n app.dock.setMenu(dockMenu)\n }\n}).then(createWindow)\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n\nAfter launching the Electron application, right click the application icon. You should see the custom menu you just defined:
\n
workingSetSize Integer - The amount of memory currently pinned to actual physical RAM.peakWorkingSetSize Integer - The maximum amount of memory that has ever been pinned to actual physical RAM.privateBytes Integer (optional) Windows - The amount of memory not shared by other processes, such as JS heap or HTML content.Note that all statistics are reported in Kilobytes.
", "title": "MemoryInfo Object", "description": "" }, "/docs/api/structures/memory-usage-details": { "locale": "es-ES", "slug": "memory-usage-details", "href": "/docs/api/structures/memory-usage-details", "crowdinFileId": "256461", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/memory-usage-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "count Numbersize NumberliveSize Number\n\nCrea menús de aplicaciones nativas y menús contextuales.
\n
Proceso: principal</0>
\nnew Menu()Crea un nuevo menú.
\nLa clase Menu tiene los siguientes métodos estáticos:
Menu.setApplicationMenu(menu)menu Menu | nullEstablece menu como el menú de la aplicación en macOS. En Windows y Linux el menu será establecido como el menú superior de la ventana.
Además en Windows y Linux, puedes usar un & en el nombre del ítem de nivel superior para indicar que letra debe obtener un acelerador generado. Por ejemplo, usando &File para el menú resultaría en un acelerador generado Alt-F que abre el menú asociado. El carácter indicado en la etiqueta del botón entonces aparecerá subrayado, y el carácter & no se mostrará en la etiqueta del botón.
Para poder saltar el carácter & en el nombre de un objeto, usa un & procedural. Por ejemplo, &&Archivo abrirá &Archivo en la etiqueta del botón.
Passing null will suppress the default menu. On Windows and Linux, this has the additional effect of removing the menu bar from the window.
Note: El menú por defecto será creado automáticamente si la aplicación no establece uno. Esto contiene los ítems estándares como File, Edit, View, Window y Help.
Menu.getApplicationMenu()Devuelve Menu | null - El menú de aplicación, si se creó, o null en caso contrario.
Nota: La instancia devuelta Menu no soporta adiciones dinámicas o la eliminación de elementos del menú. Instance properties todavía puede ser modificada dinámicamente.
Menu.sendActionToFirstResponder(action) macOSaction StringEnvía la action al primer respondedor de la aplicación. Esto es usado para emular los comportamientos del menú macOS por defecto. Normalmente usarías el rol propiedad de un MenuItem.
Consulte la macOS Cocoa Event Handling Guide para más información sobre las acciones nativas de macOS.
\nMenu.buildFromTemplate(template)plantilla (MenuItemConstructorOptions | MenuItem)[]Devuelve Menu
Generally, the template is an array of options for constructing a MenuItem. The usage can be referenced above.
Usted puede además adjuntar otros campos al elemento del template y se convierten en propiedades de los items del menú construido.
El objetomenu tiene los siguientes métodos de instancia:
menu.popup([options])options Object (opcional)window BrowserWindow (opcional) - Por defecto es la ventana seleccionada.x Número (opcional) - Default es la posición actual del cursor. Debe ser declarado si y es declarado.y Número (opcional) - Default es la posición actual del cursor. Debe ser declarado si x es declarado.positioningItem Número (opcional) macOS - El índice del elemento del menú que debe ser posicionado debajo del cursor en las coordenadas específicas. El valor predeterminado es -1.callback Function (opcional) - Llamada cuando se cierra el menu.Este menú aparece como un menú contextual en el BrowserWindow.
menu.closePopup([browserWindow])browserWindow BrowserWindow (opcional) - Por defecto es la ventana seleccionada.Cierra el menú de contexto en la browserWindow.
menu.append(menuItem)menuItem MenuItemAnexa el menuItem al menú.
menu.getMenuItemById(id)id CadenaDevuelve MenuItem | null el item con el id especificado
menu.insert(pos, menuItem)pos EnteromenuItem MenuItemInserta el menuItem en la posición pos del menú.
Objetos creados con new Menu o retornados por Menu.buildFromTemplate emiten los siguientes eventos:
Nota: Algunos eventos sólo están disponibles en sistemas operativos específicos y se etiquetan como tal.
\nDevuelve:
\neventEmitido cuando se llama a menu.popup().
Devuelve:
\neventSe emite cuando una ventana emergente se cierra manualmente o con menu.closePopup().
Los objetos menu también tienen las siguientes propiedades:
menu.itemsUn arreglo MenuItem[] contiene los elementos del menú.
Cada Menu se compone de múltiples MenuItem y cada MenuItem tiene un submenú.
Un ejemplo de creación de una menú de la aplicación con el API simple template:
\nconst { app, Menu } = require('electron')\n\nconst isMac = process.platform === 'darwin'\n\nconst template = [\n // { role: 'appMenu' }\n ...(isMac ? [{\n label: app.name,\n submenu: [\n { role: 'about' },\n { type: 'separator' },\n { role: 'services' },\n { type: 'separator' },\n { role: 'hide' },\n { role: 'hideOthers' },\n { role: 'unhide' },\n { type: 'separator' },\n { role: 'quit' }\n ]\n }] : []),\n // { role: 'fileMenu' }\n {\n label: 'File',\n submenu: [\n isMac ? { role: 'close' } : { role: 'quit' }\n ]\n },\n // { role: 'editMenu' }\n {\n label: 'Editar',\n submenu: [\n { role: 'undo' },\n { role: 'redo' },\n { type: 'separator' },\n { role: 'cut' },\n { role: 'copy' },\n { role: 'paste' },\n ...(isMac ? [\n { role: 'pasteAndMatchStyle' },\n { role: 'delete' },\n { role: 'selectAll' },\n { type: 'separator' },\n {\n label: 'Speech',\n submenu: [\n { role: 'startSpeaking' },\n { role: 'stopSpeaking' }\n ]\n }\n ] : [\n { role: 'delete' },\n { type: 'separator' },\n { role: 'selectAll' }\n ])\n ]\n },\n // { role: 'viewMenu' }\n {\n label: 'View',\n submenu: [\n { role: 'reload' },\n { role: 'forceReload' },\n { role: 'toggleDevTools' },\n { type: 'separator' },\n { role: 'resetZoom' },\n { role: 'zoomIn' },\n { role: 'zoomOut' },\n { type: 'separator' },\n { role: 'togglefullscreen' }\n ]\n },\n // { role: 'windowMenu' }\n {\n label: 'Window',\n submenu: [\n { role: 'minimize' },\n { role: 'zoom' },\n ...(isMac ? [\n { type: 'separator' },\n { role: 'front' },\n { type: 'separator' },\n { role: 'window' }\n ] : [\n { role: 'close' }\n ])\n ]\n },\n {\n role: 'help',\n submenu: [\n {\n label: 'Learn More',\n click: async () => {\n const { shell } = require('electron')\n await shell.openExternal('https://electronjs.org')\n }\n }\n ]\n }\n]\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nPara crear menús iniciados por el renderer process, envía la información requerida al main process usando IPC y haz que main process muestre el menú en nombre del renderer.
\nA continuación un ejemplo de mostrar un menú cuando el usuario pulsa el botón derecho en la página:
\n// renderer\nwindow.addEventListener('contextmenu', (e) => {\n e.preventDefault()\n ipcRenderer.send('show-context-menu')\n})\n\nipcRenderer.on('context-menu-command', (e, command) => {\n // ...\n})\n\n// main\nipcMain.on('show-context-menu', (event) => {\n const template = [\n {\n label: 'Menu Item 1',\n click: () => { event.sender.send('context-menu-command', 'menu-item-1') }\n },\n { type: 'separator' },\n { label: 'Menu Item 2', type: 'checkbox', checked: true }\n ]\n const menu = Menu.buildFromTemplate(template)\n menu.popup(BrowserWindow.fromWebContents(event.sender))\n})\nmacOS has a completely different style of application menu from Windows and Linux. Here are some notes on making your app's menu more native-like.
\nEn macOS hay muchos menúes estándares definidos por el sistema, como los menúes Services yWindows. Para hacer que el menú sea un menú estándar, se debe configurar el role del menú a uno de los siguientes y Electron los reconocerá y convertirá en menús estándares:
windowhelpservicesmacOS ha proporcionado acciones estándares para algunos elementos del menú, como About xxx, Hide xxx, y Hide Others. Para establecer la acción de un elemento de menú en una acción estándar, debe establecer el atributo función del elemento del menú.
En macOS, la etiqueta del primer elemento del menú de la aplicación siempre es su nombre de aplicación, sin importar la etiqueta que establezca. Para cambiarlo, modifique el archivo Info.plist file del conjunto de la app. See About Information Property List Files for more information.
El setMenu method de las ventanas del navegador pueden configurar el menú de ciertas ventanas del navegador.
Tú puedes hacer uso de before, after, beforeGroupContaining, afterGroupContaining y id para controlar como el elemento sera colocado cuando un menu sea construido con Menu.buildFromTemplate.
before - Inserta este ítem antes que el ítem con la etiqueta especificada. Si el ítem referenciado no existe se insertara al final del menú. Ademas implica que el ítem del menú en cuestión debe ser colocado en el mismo \"grupo\" como el ítem.after - Inserta este ítem después del ítem con la etiqueta especificada. Si el ítem referenciado no existe se insertara al final del menú. Ademas implica que el ítem del menú en cuestión debe ser colocado en el mismo \"grupo\" como el ítem.beforeGroupContaining - Proporciona una manera que un único menú contextual declare la ubicación de su grupo contenedor antes del grupo contenedor del ítem con la etiqueta especificada.beforeGroupContaining - Proporciona una manera que un único menú contextual declare la ubicación de su grupo contenedor antes del grupo contenedor del ítem con la etiqueta especificada.Por defecto, los elementos se insertarán en el orden en que existen en la plantilla, a menos que se utilice una de las palabras clave de posicionamiento especificadas.
\nPlantilla:
\n[\n { id: '1', label: 'one' },\n { id: '2', label: 'two' },\n { id: '3', label: 'three' },\n { id: '4', label: 'four' }\n]\nMenú:
\n- 1\n- 2\n- 3\n- 4\nPlantilla:
\n[\n { id: '1', label: 'one' },\n { type: 'separator' },\n { id: '3', label: 'three', beforeGroupContaining: ['1'] },\n { id: '4', label: 'four', afterGroupContaining: ['2'] },\n { type: 'separator' },\n { id: '2', label: 'two' }\n]\nMenú:
\n- 3\n- 4\n- ---\n- 1\n- ---\n- 2\nPlantilla:
\n[\n { id: '1', label: 'one', after: ['3'] },\n { id: '2', label: 'two', before: ['1'] },\n { id: '3', label: 'three' }\n]\nMenú:
\n- ---\n- 3\n- 2\n- 1\n\n\nAgregue elementos a los menús y menús de contexto de la aplicación nativa.
\n
Proceso: principal</0>
\nVea Menú para obtener ejemplos.
new MenuItem(options)options Objectclick Función (opcional) - Sera llamada con click(menuItem, browserWindow, event) cuando el elemento del menú sea clickeado.menuItem MenuItembrowserWindow BrowserWindow | undefined - Esto no se definirá si no hay alguna ventana abierta.event KeyboardEventrole String (optional) - Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu - Define the action of the menu item, when specified the click property will be ignored. Ver roles.type String (opcional) - Puede ser normal, separador, submenu, checkbox o radio.label String (opcional)sublabel String (opcional)toolTip String (opcional) macOS - Texto flotante para es elemento del menú.accelerator Accelerator (opcional)icon (NativeImage | String) (opcional)enabled Boolean (opcional) - Si es falso, el elemento de menú será gris y no se podrá hacer click en él.acceleratorWorksWhenHidden Boolean (optional) macOS - default is true, and when false will prevent the accelerator from triggering the item if the item is not visible`.visible Boolean (opcional) - Si es falso, el elemento del menú será totalmente invisible.checked Boolean (opcional) - Solo debe especificarse para elementos del menú tipo checkbox o radio.registerAccelerator Boolean (opcional) Linux Windows - Si es false, el acelerador no se registrará en el sistema, pero seguirá siendo visible. Defaults to true.sharingItem SharingItem (opcional) macOS - el elemento que se compartirá cuando el role es shareMenu.submenu (MenuItemConstructorOptions[] | Menu) (opcional) - Debería especificarse para los items del tipo submenu. Si submenu es especificado, el type: 'submenu' puede ser omitido. Si el valor no es un Menu entonces automáticamente será convertido a uno usando Menu.buildFromTemplate.id String (opcional) - único dentro de un solo menú. Si se define, puede ser usado como referencia a este elemento por el atributo posición.before String - Inserta este ítem antes que el ítem con la etiqueta especificada. Si el ítem referenciado no existe el ítem sera insertado al final del menu. También implica que el ítem del menu en cuestión debería colocarse in el mismo “group” como el ítem.after String - inserta este elemento después de el elemento con la etiqueta especificada. Si el ítem referenciado no existe se insertara al final del menú.beforeGroupContaining String - Proporciona una manera para que un único menú contextual declare la ubicación de su grupo contenedor antes del grupo contenedor del artículo con la etiqueta especificada.afterGroupContaining String - Proporciona una manera para que un único menú contextual declare la ubicación de su grupo contenedor después del grupo contenedor del artículo con la etiqueta especificada.Note: acceleratorWorksWhenHidden es especificado como siendo macOS-solo porque los aceleradores siempre trabajan cuando los items son ocultados en Windows y Linux. La opción esta expuesta a los usuarios para darles a ellos la opción de apagarla, ya que esto es posible el el desarrollo nativo de macOS. Esta propiedad solo es usable en macOS High Sierra 10.13 o más recientes.
Los roles le permiten a los elementos del menú tener comportamientos predeterminados.
\nEs mejor especificar el rol para todos los elementos del menú de tal manera que coincidan con los roles estándar, en vez de tratar de implementar un comportamiento manualmente en una función click. El comportamiento incorporador rol dará la mejor experiencia nativa.
Los valores de etiqueta y acelerador son opcionales mientras se usa un rol y por defecto se apropiarán valores de cada plataforma.
Cada elemento del menu deve tener un role, label, o en el caso de un separador un type.
La propiedad role puede tener los siguientes valores:
deshacerabout - Lanza un panel de \"acerca de\" nativo (Cuadro de diálogo personalizado en ventana, cuando no se proporciona uno).rehacercortarcopiarpegarpasteAndMatchStyleselectAlleliminarminimize - Minimize current window.close - Close current window.quit - Salir de la aplicación.reload - Reload the current window.forceReload - Recargar la ventana actual ignorando la caché.toggleDevTools - Alternar herramientas de desarrollador en la ventana actual.togglefullscreen - Alterna al modo de pantalla completa en la ventana actual.resetZoom - Restablece el nivel de zoom de la página enfocada al tamaño original.zoomIn - Zoom en la página enfocada en un 10%.zoomOut - Aleja la página enfocada en un 10%.toggleSpellChecker - Activar/desactivar el corrector ortográfico incorporado.fileMenu - Todo el menú \"Archivo\" por defecto (Cerrar / Salir)editMenu - Whole default \"Edit\" menu (Undo, Copy, etc.).viewMenu - Todo el menú \"Vista\" por defecto (Recargar, Activar Herramientas del Desarrollador, etc.)windowMenu - Todo el menú \"Ventana\" por defecto (Minimizar, Zoom, etc.).The following additional roles are available on macOS:
\nappMenu - Todo el menú \"App\" por defecto (Acerca de, Servicios, etc.)hide - Map to the hide action.hideothers - Enlace a la acción hideOtherApplications.unhide - Map to the unhideAllApplications action.startspeaking - Enlace a la acción startSpeaking.stopspeaking - Enlace a la acción stopSpeaking.front - Map to the arrangeInFront action.zoom - Map to the performZoom action.toggletabbar - Enlace a la acción toggleTabBar.selectnexttab - Enlace a la acción selectNextTab.selectprevioustab - Enlace a la acción selectPreviousTab.mergeallwindows - Enlace a la acción mergeAllWindows.movetabtonewwindow - Enlace a la acción moveTabToNewWindow.window - El submenú es un menú \"Ventana\".help - El submenú es un menú \"Ayuda\".services - El sub menú es una menú \"Services\". This is only intended for use in the Application Menu and is not the same as the \"Services\" submenu used in context menus in macOS apps, which is not implemented in Electron.recentDocuments - El submenú es un menú \"Abrir reciente\".clearRecentDocuments - Enlace a la acción clearRecentDocuments.shareMenu - El submenú es share menu. La propiedad sharingItem debe establecerse para indicar el elemento a compartir.Al especificar un role en macOS, label y accelerator son las únicas opciones que afectarán el elemento del menú. Todas las demás opciones serán ignoradas. Los role en minúscula, por ejemplo, toggledevtools, todavía son soportados.
Nota Bene: Las propiedades enabled y visibility no están disponibles para los elementos de nivel superior del menú de la bandeja en macOS.
Las siguientes propiedades están disponibles en instancias del menú de elementos:
menuItem.idUn String indicando la etiqueta visible del elemento, esta propiedad puede ser cambiada dinámicamente.
menuItem.labelUn String indicando la etiqueta visible del elemento.
menuItem.clickA Function that is fired when the MenuItem receives a click event. Puede ser llamado con menuItem.click(event, focusedWindow, focusedWebContents).
event KeyboardEventfocusedWindow BrowserWindowfocusedWebContents WebContentsmenuItem.submenuUn Menú (opcional) que contiene el submenú del menú elemento, si está presente.
menuItem.typeUn String indicando el tipo del elemento. Puede ser normal, separator, submenu, checkbox o radio.
menuItem.roleUna String (opcional) indicando el rol del elemento, si está establecido. Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu
menuItem.acceleratorUn Accelerator (opcional) indicando el acelerador del elemento, si está establecido.
menuItem.userAccelerator Readonly macOSUn Accelerator | null indicando el user-assigned accelerator del elemento para el menú del elemento.
Nota: Esta propiedad es solo inicializada después de que MenuItem a sido agregada al Menu. Ya sea a través de Menu.buildFromTemplate o a través de Menu.append()/insert(). Accediendo antes de la inicialización solo devolverá null.
menuItem.iconUna NativeImage | String (opcional) indicando el icono del elemento, si estuviera establecido.
menuItem.sublabelUn String indicando la sub-etiqueta del elemento.
menuItem.toolTip macOSUn String indicando el texto flotante del elemento.
menuItem.enabledUn booleano indicando si el elementos está habilitado, esta propiedad puede ser cambiada dinámicamente.
menuItem.visibleUn booleano indicando si el elemento es visible, esta propiedad puede ser cambiada dinámicamente.
menuItem.checkedUn Booleano indicando si el elemento está verificado, esta propiedad puede ser cambiada dinámicamente.
Un elemento del menú checkbox que cambiará la propiedad verificado en sí y no cuando se selecciona.
Un elemento del menú radio que activará su propiedad verificado cuando se haga click en él, y que desactivará su propiedad para todos los elementos adyacentes en el mismo menú.
Puede añadir la función click para comportamientos adicionales.
menuItem.registerAcceleratorUn Boolean que indica si el acelerador debe ser registrado con el sistema o solo mostrado.
Esta propiedad puede ser cambiada dinámicamente.
\nmenuItem.sharingItem macOSUn SharingItem indicando el elemento a compartir cuando el role es shareMenu.
Esta propiedad puede ser cambiada dinámicamente.
\nmenuItem.commandIdUn Number indicando el id único secuencial de un elemento.
menuItem.menuUn Menu del cual el elemento es parte.
MessageChannelMain is the main-process-side equivalent of the DOM MessageChannel object. Su función singular es crear un par de objetos MessagePortMain conectados.
Ve la documentacion de Channel Messaging API para mas información sobre el uso de channel messaging.
\n\n\nInterfaz para la mensajería de canales del proceso principal.
\n
Proceso: principal</0>
\nEjemplo:
\n// Proceso principal\nconst { MessageChannelMain } = require('electron')\nconst { port1, port2 } = new MessageChannelMain()\nw.webContents.postMessage('port', null, [port2])\nport1.postMessage({ some: 'message' })\n\n// Proceso de renderizado\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('port', (e) => {\n // e.ports es una lista de puertos enviados junto con este mensaje\n e.ports[0].on('message', (messageEvent) => {\n console.log(messageEvent.data)\n })\n})\nchannel.port1Una propiedad MessagePortMain.
channel.port2Una propiedad MessagePortMain.
MessagePortMain is the main-process-side equivalent of the DOM MessagePort object. It behaves similarly to the DOM version, with the exception that it uses the Node.js EventEmitter event system, instead of the DOM EventTarget system. This means you should use port.on('message', ...) to listen for events, instead of port.onmessage = ... or port.addEventListener('message', ...)
Ve la documentacion de Channel Messaging API para mas información sobre el uso de channel messaging.
\nMessagePortMain is an [EventEmitter][event-emitter].
\n\nInterfaz del puerto para la mensajería de canales del proceso principal.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
port.postMessage(message, [transfer])Sends a message from the port, and optionally, transfers ownership of objects to other browsing contexts.
\nport.start()Starts the sending of messages queued on the port. Messages will be queued until this method is called.
\nport.close()Disconnects the port, so it is no longer active.
\nDevuelve:
\nmessageEvent Objectdata anyports MessagePortMain[]Emitted when a MessagePortMain object receives a message.
\nEmitted when the remote end of a MessagePortMain object becomes disconnected.
", "title": "Título 1 Xpath:/h 1", "description": "Interfaz del puerto para la mensajería de canales del proceso principal." }, "/docs/tutorial/message-ports": { "locale": "es-ES", "slug": "message-ports", "href": "/docs/tutorial/message-ports", "crowdinFileId": "256219", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/message-ports.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "MessagePorts son características web que permite pasar mensajes entre diferentes contextos. Es como window.postMessage, pero en diferentes canales. El objetivo de este documente este describir como Electron extiende el modelo de mensajería del canal, y dar algunos ejemplos de como puedes usar MessagePorts en tu aplicación.
Aquí un ejemplo muy breve de que es y como funciona un MessagePort:
\n// renderer.js ///////////////////////////////////////////////////////////////\n// MessagePorts are created in pairs. A connected pair of message ports is\n// called a channel.\nconst channel = new MessageChannel()\n\n// The only difference between port1 and port2 is in how you use them. Messages\n// sent to port1 will be received by port2 and vice-versa.\nconst port1 = channel.port1\nconst port2 = channel.port2\n\n// It's OK to send a message on the channel before the other end has registered\n// a listener. Messages will be queued until a listener is registered.\nport2.postMessage({ answer: 42 })\n\n// Here we send the other end of the channel, port1, to the main process. It's\n// also possible to send MessagePorts to other frames, or to Web Workers, etc.\nipcRenderer.postMessage('port', null, [port1])\n// main.js ///////////////////////////////////////////////////////////////////\n// In the main process, we receive the port.\nipcMain.on('port', (event) => {\n // When we receive a MessagePort in the main process, it becomes a\n // MessagePortMain.\n const port = event.ports[0]\n\n // MessagePortMain uses the Node.js-style events API, rather than the\n // web-style events API. So .on('message', ...) instead of .onmessage = ...\n port.on('message', (event) => {\n // data is { answer: 42 }\n const data = event.data\n })\n\n // MessagePortMain queues messages until the .start() method has been called.\n port.start()\n})\nLa documentación de Channel Messaging API es una gran manera para aprender más acerca de como funciona MessagePorts.
\nEn el renderer, la clase MessagePort se comporta exactamente como lo hace en la web. El main process no es una página web, sin embargo no tiene un integración con Blink por lo tanto no tiene las clases MessagePort o MessageChannel. Para manejar e interactuar con MessagePorts en el main process, Electron agrega dos nuevas clases: MessagePortMain y MessageChannelMain. Estos se comportan se comportan de manera similar a las clases análogas en el renderer.
Los objetos MessagePort pueden ser creados en el renderer o en el main process, y pasar de un lado a otro usando los métodos ipcRenderer.postMessage y WebContents.postMessage. Tenga en cuenta que los métodos usuales de IPC tales como send y invoke no pueden ser usados para transferir los MessagePort, sólo los métodos postMessage pueden transferir los MessagePort.
Al pasar los MessagePort a través del main process, puedes conectar dos páginas que de otra forma no podrían comunicarse (p.ej. debido a restricciones del mismo origen).
closeElectron agrega una característica a MessagePort que no esta presente en la web, para poder hacer a MessagePorts más útil. Ese es el evento close, el cual es emitido cuando el otro extremo del canal está cerrado. Los puertos también pueden ser cerrados implícitamente al ser recolectados por el colector de basura.
En el renderer, puede usar el evento close ya sea asignando a port.onclose o llamando a port.addEventListener('close', ...). En el main process, puedes escuchar por el evento close llamando a port.on('close', ...).
En este ejemplo, tu aplicación tiene un worker process implementado como una ventana oculta. Quieres que la página de la aplicación sea capaz de comunicarse directamente con el worker process, sin la sobrecarga del rendimiento de la retransmisión a través del main process.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, ipcMain, MessageChannelMain } = require('electron')\n\napp.whenReady().then(async () => {\n // The worker process is a hidden BrowserWindow, so that it will have access\n // to a full Blink context (including e.g. <canvas>, audio, fetch(), etc.)\n const worker = new BrowserWindow({\n show: false,\n webPreferences: { nodeIntegration: true }\n })\n await worker.loadFile('worker.html')\n\n // The main window will send work to the worker process and receive results\n // over a MessagePort.\n const mainWindow = new BrowserWindow({\n webPreferences: { nodeIntegration: true }\n })\n mainWindow.loadFile('app.html')\n\n // We can't use ipcMain.handle() here, because the reply needs to transfer a\n // MessagePort.\n ipcMain.on('request-worker-channel', (event) => {\n // For security reasons, let's make sure only the frames we expect can\n // access the worker.\n if (event.senderFrame === mainWindow.webContents.mainFrame) {\n // Create a new channel ...\n const { port1, port2 } = new MessageChannelMain()\n // ... send one end to the worker ...\n worker.webContents.postMessage('new-client', null, [port1])\n // ... and the other end to the main window.\n event.senderFrame.postMessage('provide-worker-channel', null, [port2])\n // Now the main window and the worker can communicate with each other\n // without going through the main process!\n }\n })\n})\n<!-- worker.html ------------------------------------------------------------>\n<script>\nconst { ipcRenderer } = require('electron')\n\nfunction doWork(input) {\n // Something cpu-intensive.\n return input * 2\n}\n\n// We might get multiple clients, for instance if there are multiple windows,\n// or if the main window reloads.\nipcRenderer.on('new-client', (event) => {\n const [ port ] = event.ports\n port.onmessage = (event) => {\n // The event data can be any serializable object (and the event could even\n // carry other MessagePorts with it!)\n const result = doWork(event.data)\n port.postMessage(result)\n }\n})\n</script>\n<!-- app.html --------------------------------------------------------------->\n<script>\nconst { ipcRenderer } = require('electron')\n\n// We request that the main process sends us a channel we can use to\n// communicate with the worker.\nipcRenderer.send('request-worker-channel')\n\nipcRenderer.once('provide-worker-channel', (event) => {\n // Once we receive the reply, we can take the port...\n const [ port ] = event.ports\n // ... register a handler to receive results ...\n port.onmessage = (event) => {\n console.log('received result:', event.data)\n }\n // ... and start sending it work!\n port.postMessage(21)\n})\n</script>\nLos métodos IPC incorporados de Electron sólo soportan dos modos: dispara-y-olvida (p. ej. send), o solicitud-respuesta (p. ej. invoke). Al usar MessageChannels, puedes implementar un \"flujo de respuesta\", donde una simple solicitud se responda con un flujo de datos.
// renderer.js ///////////////////////////////////////////////////////////////\n\nfunction makeStreamingRequest (element, callback) {\n // MessageChannels are lightweight--it's cheap to create a new one for each\n // request.\n const { port1, port2 } = new MessageChannel()\n\n // We send one end of the port to the main process ...\n ipcRenderer.postMessage(\n 'give-me-a-stream',\n { element, count: 10 },\n [port2]\n )\n\n // ... and we hang on to the other end. The main process will send messages\n // to its end of the port, and close it when it's finished.\n port1.onmessage = (event) => {\n callback(event.data)\n }\n port1.onclose = () => {\n console.log('stream ended')\n }\n}\n\nmakeStreamingRequest(42, (data) => {\n console.log('got response data:', event.data)\n})\n// We will see \"got response data: 42\" 10 times.\n// main.js ///////////////////////////////////////////////////////////////////\n\nipcMain.on('give-me-a-stream', (event, msg) => {\n // The renderer has sent us a MessagePort that it wants us to send our\n // response over.\n const [replyPort] = event.ports\n\n // Here we send the messages synchronously, but we could just as easily store\n // the port somewhere and send messages asynchronously.\n for (let i = 0; i < msg.count; i++) {\n replyPort.postMessage(msg.element)\n }\n\n // We close the port when we're done to indicate to the other end that we\n // won't be sending any more messages. This isn't strictly necessary--if we\n // didn't explicitly close the port, it would eventually be garbage\n // collected, which would also trigger the 'close' event in the renderer.\n replyPort.close()\n})\nCuando context isolation está activado, los mensajes IPC desde el main process al renderer son entregados al mundo aislado, en lugar que al mundo principal. Algunas veces quieres entregar mensajes al mundo principal directamente, sin tener que recorrer el mundo aislado.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, MessageChannelMain } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(async () => {\n // Create a BrowserWindow with contextIsolation enabled.\n const bw = new BrowserWindow({\n webPreferences: {\n contextIsolation: true,\n preload: path.join(__dirname, 'preload.js')\n }\n })\n bw.loadURL('index.html')\n\n // We'll be sending one end of this channel to the main world of the\n // context-isolated page.\n const { port1, port2 } = new MessageChannelMain()\n\n // It's OK to send a message on the channel before the other end has\n // registered a listener. Messages will be queued until a listener is\n // registered.\n port2.postMessage({ test: 21 })\n\n // We can also receive messages from the main world of the renderer.\n port2.on('message', (event) => {\n console.log('from renderer main world:', event.data)\n })\n port2.start()\n\n // The preload script will receive this IPC message and transfer the port\n // over to the main world.\n bw.webContents.postMessage('main-world-port', null, [port1])\n})\n// preload.js ////////////////////////////////////////////////////////////////\nconst { ipcRenderer } = require('electron')\n\n// We need to wait until the main world is ready to receive the message before\n// sending the port. We create this promise in the preload so it's guaranteed\n// to register the onload listener before the load event is fired.\nconst windowLoaded = new Promise(resolve => {\n window.onload = resolve\n})\n\nipcRenderer.on('main-world-port', async (event) => {\n await windowLoaded\n // We use regular window.postMessage to transfer the port from the isolated\n // world to the main world.\n window.postMessage('main-world-port', '*', event.ports)\n})\n<!-- index.html ------------------------------------------------------------->\n<script>\nwindow.onmessage = (event) => {\n // event.source === window means the message is coming from the preload\n // script, as opposed to from an <iframe> or other source.\n if (event.source === window && event.data === 'main-world-port') {\n const [ port ] = event.ports\n // Once we have the port, we can communicate directly with the main\n // process.\n port.onmessage = (event) => {\n console.log('from main process:', event.data)\n port.postMessage(event.data * 2)\n }\n }\n}\n</script>\nmimeType String (optional) - MIME type of the buffer.charset String (optional) - Charset of the buffer.data Buffer - The actual Buffer content.InputEventtype String - The type of the event, can be mouseDown, mouseUp, mouseEnter, mouseLeave, contextMenu, mouseWheel or mouseMove.x Integery Integerbutton String (optional) - The button pressed, can be left, middle, right.globalX Integer (optional)globalY Integer (optional)movementX Integer (optional)movementY Integer (optional)clickCount Integer (optional)MouseInputEventtype String - The type of the event, can be mouseWheel.deltaX Integer (optional)deltaY Integer (optional)wheelTicksX Integer (optional)wheelTicksY Integer (optional)accelerationRatioX Integer (optional)accelerationRatioY Integer (optional)hasPreciseScrollingDeltas Boolean (optional)canScroll Boolean (optional)Con los Web Workers, es posible ejecutar JavaScript en threads a nivel de Sistema Operativo.
\nEs posible utilizar las características de Node.js en Electron's Web Workers. Para hacerlo, la opción nodeIntegrationInWorker debe configurarse a true en webPreferences.
const win = new BrowserWindow({\n webPreferences: {\n nodeIntegrationInWorker: true\n }\n})\nEl nodeIntegrationInWorker puede ser utilizado independientemente de nodeIntegration, pero sandbox no debe ser configurado a true.
Todos los módulos incorporados de Node.js son compatibles con Web Workers, y los archivos asar aún se pueden leer con la API de Node.js. Sin embargo, ninguno de los módulos incorporados de Electron puede utilizarse en un entorno multiproceso.
Cualquier módulo nativo Node.js se puede cargar directamente en Web Workers, pero se recomienda encarecidamente no hacerlo. La mayoría de los módulos nativos existentes se han escrito suponiendo un entorno de subproceso único, su uso en Web Workers dará lugar a bloqueos y daños en la memoria.
\nTenga en cuenta que incluso si un módulo nativo de Node.js es un subproceso seguro, aún asi todavia no es seguro cargarlo en una Web Worker porque la función process.dlopen no es un subproceso seguro.
La única forma de cargar un módulo nativo de forma segura por ahora es asegurarse de que la aplicación no carga módulos nativos después de que Web Workers se inicie.
\nprocess.dlopen = () => {\n throw new Error('Load native module is not safe')\n}\nconst worker = new Worker('script.js')\nCiertos tipos de aplicaciones que manipulan archivos podrían querer soportar la función nativa de arrastrar & soltar archivos del sistema operativo. Arrastrar archivos dentro de un web content es común y soportado por muchos sitios web. Adicionalmente Electron soporta arrastre de archivos fuera del web content dentro del mundo del sistema.
\nTo implement this feature in your app, you need to call the webContents.startDrag(item) API in response to the ondragstart event.
An example demonstrating how you can create a file on the fly to be dragged out of the window.
\nIn preload.js use the contextBridge to inject a method window.electron.startDrag(...) that will send an IPC message to the main process.
const { contextBridge, ipcRenderer } = require('electron')\nconst path = require('path')\n\ncontextBridge.exposeInMainWorld('electron', {\n startDrag: (fileName) => {\n ipcRenderer.send('ondragstart', path.join(process.cwd(), fileName))\n }\n})\nAdd a draggable element to index.html, and reference your renderer script:
<div style=\"border:2px solid black;border-radius:3px;padding:5px;display:inline-block\" draggable=\"true\" id=\"drag\">Drag me</div>\n<script src=\"renderer.js\"></script>\nIn renderer.js set up the renderer process to handle drag events by calling the method you added via the contextBridge above.
document.getElementById('drag').ondragstart = (event) => {\n event.preventDefault()\n window.electron.startDrag('drag-and-drop.md')\n}\nIn the Main process (main.js file), expand the received event with a path to the file that is being dragged and an icon:
const { ipcMain } = require('electron')\n\nipcMain.on('ondragstart', (event, filePath) => {\n event.sender.startDrag({\n file: filePath,\n icon: '/path/to/icon.png'\n })\n})\nDespués de lanzar la aplicación Electron, intente arrastrar y soltar el elemento desde el BrowserWindow a su escritorio. In this guide, the item is a Markdown file located in the root of the project:
\n
\n\n\nCrea iconos de bandeja, base y aplicación usando archivos PNG o JPG.
\n
In Electron, for the APIs that take images, you can pass either file paths or NativeImage instances. Una imagen vacía será usada cuando se pase null.
Por ejemplo, cuando se crea una bandeja o se configura un icono de la ventana, se puede pasar una ruta de archivo de imagen como un String:
const { BrowserWindow, Tray } = require('electron')\n\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconst win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })\nconsole.log(appIcon, win)\nO leer la imagen desde el portapapeles, lo cual devuelve un NativeImage:
const { clipboard, Tray } = require('electron')\nconst image = clipboard.readImage()\nconst appIcon = new Tray(image)\nconsole.log(appIcon)\nActualmente los formatos de imágenes PNG y JPEG están soportados. PNG es recomendado por su soporte de transparencia y compresión sin pérdida.
En Windows, puedes leer iconos ICO desde rutas de archivos. For best visual quality, it is recommended to include at least the following sizes in the:
Revise la sección Size requirements en este artículo.
\nEn las plataformas compatibles con altos PPP como las pantallas Apple Retina, se puede anexar @2x luego del nombre del archivo base de la imagen para marcarlo como una imagen de alta resolución.
Por ejemplo, si icon.png es una imagen normal que tiene resolución estándar, entonces icon@2x.png será tratado como una imagen de alta resolución que tiene densidad DPI.
If you want to support displays with different DPI densities at the same time, you can put images with different sizes in the same folder and use the filename without DPI suffixes. Por ejemplo:
\nimages/\n├── icon.png\n├── icon@2x.png\n└── icon@3x.png\nconst { Tray } = require('electron')\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconsole.log(appIcon)\nLos siguientes sufijos para DPI son soportados:
\n@1x@1.25x@1.33x@1.4x@1.5x@1.8x@2x@2.5x@3x@4x@5xTemplate images consist of black and an alpha channel. Las imágenes de plantilla no están destinadas a ser utilizadas como imágenes independientes y son generalmente mezcladas con otro contenido para crear la apariencia final deseada.
\nEl caso mas común es usar imágenes de plantillas para el icono de una barra de menú, así este se puede adaptar a ambas barras de menú clara y oscura.
\nNota: La imagen de plantilla sólo es soportada en macOS.
\nPara marcar una imagen como plantilla, su nombre de archivo debe terminar con la palabra Template. Por ejemplo:
xxxTemplate.pngxxxTemplate@2x.pngEl módulo nativeImage tiene los siguientes métodos, de los cuales todos devuelven una instancia de la clase NativeImage:
nativeImage.createEmpty()Devuelve NativeImage
Crea una instancia vacía NativeImage.
nativeImage.createThumbnailFromPath(path, maxSize) macOS Windowspath String - path to a file that we intend to construct a thumbnail out of.maxSize Size - the maximum width and height (positive numbers) the thumbnail returned can be. The Windows implementation will ignore maxSize.height and scale the height according to maxSize.width.Returns Promise<NativeImage> - fulfilled with the file's thumbnail preview image, which is a NativeImage.
nativeImage.createFromPath(path)path StringDevuelve NativeImage
Crea una instancia NativeImage desde un archivo ubicado en path. Este método devuelve una imagen si la path no existe, o si no puede ser leída o si la imagen no es válida.
const nativeImage = require('electron').nativeImage\n\nconst image = nativeImage.createFromPath('/Users/somebody/images/icon.png')\nconsole.log(image)\nnativeImage.createFromBitmap(buffer, options)buffer Bufferoptions Objectwidth Integeralto IntegerscaleFactor Doble (opcional) -Por defecto es 1.0.Devuelve NativeImage
Creates a new NativeImage instance from buffer that contains the raw bitmap pixel data returned by toBitmap(). The specific format is platform-dependent.
nativeImage.createFromBuffer(buffer[, options])buffer Bufferoptions Object (opcional)width Integer (opcional) - Requerido para búferes de bipmaps.height Entero (opcional) - Necesario para los búferes de mapa de bits.scaleFactor Doble (opcional) -Por defecto es 1.0.Devuelve NativeImage
Crea una nueva instancia NativeImage desde buffer. Tries to decode as PNG or JPEG first.
nativeImage.createFromDataURL(dataURL)dataURL CadenaDevuelve NativeImage
Crea una nueva instancia NativeImage desde dataURL.
nativeImage.createFromNamedImage(imageName[, hslShift]) macOSDevuelve NativeImage
Crea una nueva instancia de NativeImage a partir de NSImage vinculada con el nombre especificado. Vea System Icons para una lista de posibles valores.
El hslShift se aplica a la imagen con las siguientes reglas:
hsl_shift[0] (hue): El valor de hue absoluto para la imagen - 0 y 1 mapea a 0 y 360 en la rueda de color hue (rojo).hsl_shift[1] (saturation): A saturation shift for the image, with the following key values: 0 = remove all color. 0.5 = Dejar sin cambios. 1 = fully saturate the image.hsl_shift[2] (luminosidad): Un cambio en la luminosidad para la imagen, con los siguientes valores claves: 0 = elimina toda la luminosidad (hace que todos los pixeles sean negros). 0.5 = Dejar sin cambios. 1 = Luminosidad total (hace que todos los píxeles sean blancos).Esto significa que [-1, 0, 1] hará la imagen completamente blanca y [-1, 1, 0] la hará completamente negra.
En algunos casos, el NSImageName no coincide con su cadena de representación; un ejemplo de esto es NSFolderImageName, cuya cadena de representación en realidad sería NSFolder. Por lo tanto, necesitar determinar la cadena de representación correcta para su imagen antes de pasarla. Esto puede hacer con lo siguiente:
echo -e '#import <Cocoa/Cocoa.h>\\nint main() { NSLog(@\"%@\", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test
donde SYSTEM_IMAGE_NAME debe ser reemplazado con cualquier valor de this list.
\n\nEnvuelve nativamente imágenes como la bandeja, el muelle y los íconos de las aplicaciones.
\n
Process: Main, Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Los siguientes métodos están disponibles para las distancias de la clase NativeImage:
image.toPNG([options])options Object (opcional)scaleFactor Doble (opcional) -Por defecto es 1.0.Devuelve Buffer - Un Buffer que contiene la información codificada de la imagen PNG.
image.toJPEG(quality)quality Integer - Entre 0 - 100.Devuelve Buffer - Un Bufferque contiene la información codificada de la imagen JPEG.
image.toBitmap([options])options Object (opcional)scaleFactor Doble (opcional) -Por defecto es 1.0.Devuelve Buffer - Un Buffer que contiene una copia de la información sin procesar de pixeles del mapa de bits de la imagen.
image.toDataURL([options])options Object (opcional)scaleFactor Doble (opcional) -Por defecto es 1.0.Devuelve String - El URL de información de la imagen.
image.getBitmap([options])options Object (opcional)scaleFactor Doble (opcional) -Por defecto es 1.0.Devuelve Buffer - Un Buffer que contiene la información sin procesar de pixeles del mapa de bits de la imagen.
La diferencia entre getBitmap() y toBitmap() es que getBitmap() no copia los datos bitmap, por lo que debe utilizar inmediatamente el Búfer devuelto en el ciclo del evento actual; de lo contrario, los datos podrían modificarse o destruirse.
image.getNativeHandle() macOSDevuelve Buffer - Un Buffer que almacena el puntero C en el controlador nativo subyacente de la imagen. En macOS, se devolverá un puntero a la instancia NSImage.
Observe que el puntero devuelto es un puntero debil a la imagen nativa subyacente en lugar de una copia. Por lo tanto, debe asegurarse que la instancia asociada nativeImage se encuentre cerca.
image.isEmpty()Devuelve Boolean - Si la imagen está vacía.
image.getSize([scaleFactor])scaleFactor Doble (opcional) -Por defecto es 1.0.Devuelve Size.
If scaleFactor is passed, this will return the size corresponding to the image representation most closely matching the passed value.
image.setTemplateImage(option)option BooleanoMarca la imagen como una imagen de plantilla.
\nimage.isTemplateImage()Devuelve Boolean - Si la imagen es una imagen de plantilla.
image.crop(rect)rect Rectangle - El área de la imagen para ser recortada.Devuelve NativeImage - La imagen recortada.
image.resize(options)options Objectwidth Integer (opcional) - Por defecto es el ancho de la imagen.height Entero (opcional) - El valor predeterminado es la altura de la imagen.quality String (opcional) - La calidad deseada para el cambio de tamaño de imagen. Los posibles valores soportados son good, better, o best. Por defecto es best. Estos valores expresan una compensación de calidad/velocidad deseada. Son traducidas dentro de un método de algoritmo específico que depende de las capacidades (CPU, GPU) de la plataforma subyacente. It is possible for all three methods to be mapped to the same algorithm on a given platform.Devuelve NativeImage - La imagen redimensionada.
Si solo la height o la width son especificadas, entonces la relación de aspecto actual se conservará en la imagen redimensionada.
image.getAspectRatio([scaleFactor])scaleFactor Doble (opcional) -Por defecto es 1.0.Devuelve Float - La relación de aspecto de la imagen.
If scaleFactor is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value.
image.getScaleFactors()Returns Float[] - An array of all scale factors corresponding to representations for a given nativeImage.
image.addRepresentation(options)options ObjectscaleFactor Double - El factor de escala para agregar a la representación de la imagen.width Entero (opcional) - Por defecto es 0. Required if a bitmap buffer is specified as buffer.height Entero (opcional) - Por defecto es 0. Required if a bitmap buffer is specified as buffer.buffer Buffer (opcional) - El buffer que contiene los datos de la imagen sin procesar.dataURL String (optional) - The data URL containing either a base 64 encoded PNG or JPEG image.Add an image representation for a specific scale factor. This can be used to explicitly add different scale factor representations to an image. This can be called on empty images.
\nnativeImage.isMacTemplateImage macOSUna propiedad Boolean que determina si la imagen es considerada una template image.
Ten en cuenta que esta propiedad solo tiene un efecto en macOS.
", "title": "nativeImage", "description": "Crea iconos de bandeja, base y aplicación usando archivos PNG o JPG." }, "/docs/api/native-theme": { "locale": "es-ES", "slug": "native-theme", "href": "/docs/api/native-theme", "crowdinFileId": "256343", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/native-theme.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nLee y respondo a los cambios en el tema de color nativo de Chromium.
\n
Proceso: principal</0>
\nEl módulo nativo nativeTheme emite los siguientes eventos:
Emitido cuando algo en el NativeTheme subyacente ha cambiado. Esto normalmente significa que le valor de shouldUseDarkColors, shouldUseHighContrastColors o shouldUseInvertedColorScheme ha cambiado. Tendrás que comprobarlos para determinar cual ha cambiado.
El módulo nativeTheme tiene las siguientes propiedades:
nativeTheme.shouldUseDarkColors SoloLecturaUn Boolean para si el OS / Chromium actualmente tiene un modo oscuro activado o está siendo instruido para mostrar una UI de estilo oscuro. Si quieres modificar este valor debes utilizar themeSource acontinuación.
nativeTheme.themeSourceUna propiedad String que puede ser system, light o dark. It is used to override and supersede the value that Chromium has chosen to use internally.
Estableciendo esta propiedad a system eliminará la sobreescritura y todo será restablecido a los valores predeterminados del sistema operativo. Por defecto themeSource es system.
Estableciendo esta propiedad a dark tendrá los siguientes efectos:
nativeTheme.shouldUseDarkColors será true cuando se accedeprefers-color-scheme coincidirá con el modo dark.updated será emitidoEstableciendo esta propiedad a light tendrá los siguientes efectos:
nativeTheme.shouldUseDarkColors será false cuando se accedaprefers-color-scheme coincidirá con el modo light.updated será emitidoEl uso de esta propiedad debe alinearse con una máquina de estado clásica de \"modo oscuro\" en su aplicación, donde el usuario tiene tres opciones.
\nFollow OS --> themeSource = 'system'Dark Mode --> themeSource = 'dark'Light Mode --> themeSource = 'light'Su aplicación debe usar siempre shouldUseDarkColors para determinar que CSS aplicar.
nativeTheme.shouldUseHighContrastColors macOS Windows SoloLecturaA Boolean for if the OS / Chromium currently has high-contrast mode enabled or is being instructed to show a high-contrast UI.
nativeTheme.shouldUseInvertedColorScheme macOS Windows SoloLecturaA Boolean for if the OS / Chromium currently has an inverted color scheme or is being instructed to use an inverted color scheme.
\n\nEmitir solicitudes HTTP/HTTPS usando la biblioteca de red nativa de Chromium
\n
Proceso: principal</0>
\nEl módulo net es un lado del cliente API para tratar pedidos HTTP(S). Si es similar a los módulos HTTP y HTTPS de Node.js pero usa la biblioteca de la red nativa de Chromium en vez de las aplicaciones Node.js, ofreciendo un mejor soporte a los proxies de la web. It also supports checking network status.
La siguiente es una lista no completa de por qué debería considerar usar el módulo net en vez de los módulos nativos Node.js:
Los componentes API (incluyendo clases, métodos, propiedades y nombres de eventos) son similares a esos usados en Node.js.
\nEjemplo de uso:
\nconst { app } = require('electron')\napp.whenReady().then(() => {\n const { net } = require('electron')\n const request = net.request('https://github.com')\n request.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`)\n console.log(`HEADERS: ${JSON.stringify(response.headers)}`)\n response.on('data', (chunk) => {\n console.log(`BODY: ${chunk}`)\n })\n response.on('end', () => {\n console.log('No more data in response.')\n })\n })\n request.end()\n})\nLa API net puede ser utilizada solo después que la aplicación emita el evento ready. Intentar usar el módulo antes del evento ready lanzará un error.
El módulo net tiene los siguientes métodos:
net.request(options)options (ClientRequestConstructorOptions | String) - Las opciones del constructor de ClientRequest.Devuelve ClientRequest
Crea una instancia ClientRequest usando la options proveída la cual son directamente reenviadas al constructor ClientRequest. El método net.request será usado para emitir solicitudes HTTP tanto seguras como inseguras dependiendo de lo especificado en el esquema de protocolo en el objeto options.
net.isOnline()Returns Boolean - Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
net.online SoloLecturaUna propiedad Boolean. Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
\n\nRegistrar eventos de red para una sesión.
\n
Proceso: principal</0>
\nconst { netLog } = require('electron')\n\napp.whenReady().then(async () => {\n await netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nVea --log-net-log para registrar eventos a lo largo del ciclo de vida de la aplicación.
Nota: Todos los métodos salvo los especificados pueden ser usados solo después de que el evento listo del módulo de la aplicación sea emitido.
netLog.startLogging(path[, options])path String - Ruta de archivo para guardar los registros de red.options Object (opcional)captureMode String (opcional) - Que tipos de datos deberían ser capturados. Por defecto, solo metadatos sobre las solicitudes serán capturados. Estableciendo esto a includeSensitive incluirá cookies y datos de autenticación. Estableciéndolo a everything incluirá todos los bytes transferidos en los sockets. Puede ser default, includeSensitive o everything.maxFileSize Number (opcional) - Cunado el registro crece más allá de este tamaño el registro se detendrá automáticamente. Por defecto ilimitado.Devuelve Promise<void> - se resuelve cuando el net log ha comenzado a grabar.
Comienza la agravación de eventos de red en path.
netLog.stopLogging()Devuelve Promise<void> - se resuelve cuando el net log se ha descargado en el disco.
Parar la grabación de eventos de red. Si no se llama, el registro de red automáticamente terminara cuando la aplicación se cierre.
\nnetLog.currentlyLogging SoloLecturaUna propiedad Boolean que indica si los registros de red están siendo grabados actualmente.
EventnewGuest BrowserWindow (optional)\n\nCrea las notificaciones de escritorio del sistema operativo
\n
Proceso: principal</0>
\nSi quieres mostrar notificaciones desde un proceso de renderizado se debe utilizar HTML5 Notification API
\n\n\nCrea las notificaciones de escritorio del sistema operativo
\n
Proceso: principal</0>
\nNotification es un EventEmitter.
Crea una nueva Notification con propiedades nativas como las configuradas por options.
La clase Notification tiene los siguientes métodos estáticos:
Notification.isSupported()Devuelve Boolean - Si las notificaciones de escritorio son soportadas o no en el sistema actual
new Notification([options])options Object (opcional)title String (opcional) - Un título para la notificación, el cual será mostrado en la parte superior de la ventana de notificación cuando sea mostrado.subtitle String (opcional) macOS - Un subtítulo para la notificación, la cual aparecerá debajo del título.body String (opcional) - El texto del cuerpo de la notificación, el cual será mostrado debajo del título o del subtítulo.silent Boolean (opcional) - Si se emite o no un sonido de notificación del sistema operativo cuando aparece la notificación.icon (String | NativeImage) (opcional) - Icono para usar en la notificación.hasReply Boolean (opcional) macOS - Si se agrega o no una opción de respuesta insertada en la notificación.timeoutType String (opcional) Linux Windows - La duración del tiempo de espera de la notificación. Puede ser 'default' o 'never'.replyPlaceholder String (opcional) macOS - El marcador de posición para escribir en el campo insertado de entrada de respuesta.sound String (opcional) macOS - El nombre del archivo de sonido que se reproduce cuando se muestra la notificación.urgency String (opcional) Linux - El nivel de urgencia de la notificación. Puede ser 'normal', 'critical', o 'low'.actions NotificationAction[] (opcional) macOS - Las acciones que se añaden a la notificación. Por favor lea las acciones disponibles y limitaciones en la documentación de NotificationAction.closeButtonText String (opcional) macOS - Un título personalizado para el botón cerrar de una alerta. Una cadena vacía hará que se utilice el texto localizado predeterminado.toastXml String (opcional) Windows - Una descripción personalizada de la notificación en Windows sustituyendo todas las propiedades anteriores. Ofrece una personalización completa del diseño y el comportamiento de la notificación.Los objetos creados con new Notification emite los siguientes eventos:
Nota: Algunos eventos sólo están disponibles en sistemas operativos específicos y se etiquetan como tal.
\nDevuelve:
\neventSe emite cuando la notificación se muestra al usuario. Tenga en cuenta que este puede emitirse tantas veces como se muestre la notificación a través del método show().
Devuelve:
\neventSe emite cuando el usuario hace clic en la notificación.
\nDevuelve:
\neventSe emite cuando se cierra la notificación por medio de la intervención manual del usuario.
\nNo se garantiza que este evento se emita en todos los casos donde se cierre la notificación.
\nDevuelve:
\neventreply String - La cadena que ingreso el usuario dentro del campo de respuesta insertado.Se emite cuando el usuario hace clic en el botón \"Reply\" en una notificación con hasReply: true.
Devuelve:
\neventindex Númerp - El indice de la acción que fue activado.Devuelve:
\neventerror String - El error encontrado durante la ejecución del método show().Se emite cuando un error ocurre mientras se esta creando y mostrando una notificación nativa.
\nLos objetos creados con new Notification tienen los siguientes métodos de instancia:
notification.show()Muestra inmediatamente la notificación al usuario, por favor tenga en cuenta, esto quiere decir que a diferencia de la implementación de notificación de HTML5, iniciando una new Notificación no se mostrará inmediatamente al usuario, usted necesita llamar este método antes que el sistema operativo lo muestre.
Si la notificación ha sido mostrada con anterioridad, este método descartará la notificación previa y creará una nueva con propiedades idénticas.
\nnotification.close()Descarta la notificación.
\nnotification.titleUna propiedad String que representa el título de la notificación.
notification.subtitleUna propiedad String que representa el subtítulo de la notificación.
notification.bodyUna propiedad String que representa el cuerpo de la notificación.
notification.replyPlaceholderUna propiedad String que representa el marcador de respuesta de la notificación.
notification.soundUna propiedad String que representa el sonido de la notificación.
notification.closeButtonTextUna propiedad String que representa el texto del botón cerrar en la notificación.
notification.silentUna propiedad Boolean que representa si la notificación es silenciosa.
notification.hasReplyUna propiedad Boolean que representa si al notificación tiene a una acción de respuesta.
notification.urgency LinuxUn propiedad String que representa el nivel de prioridad de la notificación. Puede ser 'normal', 'critical', o 'low'.
Por defecto es 'low' - vea NotifyUrgency para más información.
\nnotification.timeoutType Linux WindowsUna propiedad String que representa el tipo de tiempo de espera para la notificación. Puede ser 'default' o 'never'.
Si timeoutType es especificado como 'never', la notificación nunca expirará. Se queda abierta hasta que se cierra por el llamado de la API o del usuario.
notification.actionsUna propiedad NotificationAction[] que representa las acciones de la notificación.
notification.toastXml WindowsUna propiedad String que representa el Toast XML de la notificación.
En macOS, se puede especificar el nombre del sonido que se desee reproducir cuando se muestre la notificación. Cualquier sonido por defecto (en Preferencias del sistema > Sonido) pueden ser usados en adición a los sonidos personalizados del sistema. Asegúrese de que el archivo de sonido sea copiado en el paquete de la aplicación (por ejemplo, YourApp.app/Contents/Resources), o uno de los siguientes direcciones:
~/Library/Sounds/Library/Sounds/Network/Library/Sounds/System/Library/SoundsVer la documentación NSSound para más información.
type String - The type of action, can be button.text String (optional) - The label for the given action.| Action Type | Platform Support | Usage of text | Default text | Limitations |
|---|---|---|---|---|
button | macOS | Used as the label for the button | \"Show\" (or a localized string by system default if first of such button, otherwise empty) | Only the first one is used. If multiple are provided, those beyond the first will be listed as additional actions (displayed when mouse active over the action button). Any such action also is incompatible with hasReply and will be ignored if hasReply is true. |
In order for extra notification buttons to work on macOS your app must meet the following criteria.
\nNSUserNotificationAlertStyle set to alert in the Info.plist.If either of these requirements are not met the button won't appear.
", "title": "NotificationAction Object", "description": "" }, "/docs/api/structures/notification-response": { "locale": "es-ES", "slug": "notification-response", "href": "/docs/api/structures/notification-response", "crowdinFileId": "256473", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/notification-response.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "actionIdentifier String - The identifier string of the action that the user selected.date Number - The delivery date of the notification.identifier String - The unique identifier for this notification request.userInfo Record<String, any> - A dictionary of custom information associated with the notification.userText String (optional) - The text entered or chosen by the user.All three operating systems provide means for applications to send notifications to the user. The technique of showing notifications is different for the Main and Renderer processes.
\nFor the Renderer process, Electron conveniently allows developers to send notifications with the HTML5 Notification API, using the currently running operating system's native notification APIs to display it.
\nTo show notifications in the Main process, you need to use the Notification module.
\nStarting with a working application from the Quick Start Guide, add the following line to the index.html file before the closing </body> tag:
<script src=\"renderer.js\"></script>\n...y agregar el archivo renderer.js:
const NOTIFICATION_TITLE = 'Título'\nconst NOTIFICATION_BODY = 'Notificación del proceso de renderizado. Haga clic para registrar en consola.'\nconst CLICK_MESSAGE = 'Notification cliced'\n\nnew Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY })\n .onclick = () => console.log(CLICK_MESSAGE)\nAfter launching the Electron application, you should see the notification:
\n
Additionally, if you click on the notification, the DOM will update to show \"Notification clicked!\".
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { Notification } = require('electron')\n\nconst NOTIFICATION_TITLE = 'Basic Notification'\nconst NOTIFICATION_BODY = 'Notification from the Main process'\n\nfunction showNotification () {\n new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()\n}\n\napp.whenReady().then(createWindow).then(showNotification)\nAfter launching the Electron application, you should see the system notification:
\n
Si bien el código y la experiencia del usuario en los sistemas operativos son similares, existen diferencias sutiles.
\nnode_modules\\electron\\dist\\electron.exe to your Start Menu also does the trick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'. You will then need to add the line app.setAppUserModelId(process.execPath) to your main process to see notifications.Electron intenta automatizar el trabajo en torno de la Application User Model ID. Cuando Electron es usado junto con el framework de instalación y actualización Squirrel shortcuts will automatically be set correctly. Además, Electron detectará que Squirrel fue usada y automáticamente llamará a app.setAppUserModelId() con el valor correcto. Durante el desarrollo, puede tener que llamar por ti mismo a app.setAppUserModelId().
Además, en Windows 8, la longitud máxima para el cuerpo de la notificación es de 250 caracteres, y el equipo de Windows recomienda que las notificaciones se mantengan en 200 caracteres. Dicho eso, esa limitación se eliminó en Windows 10, y el equipo de Windows les pidió a los desarrolladores que fuesen razonables. Intentar enviar cantidades gigantescas de texto a la API (miles de caracteres) puede provocar inestabilidad.
\nLas versiones posteriores de Windows permiten notificaciones avanzadas, con plantillas personalizadas, imágenes y otros elementos flexibles. Para enviar esas notificaciones (ya sea desde el proceso principal o desde el procesador), use el módulo de usuario electron-windows-notificaciones, que usa complementos de nodo nativos para enviar ToastNotification y objetos TileNotification.
While notifications including buttons work with electron-windows-notifications, handling replies requires the use of electron-windows-interactive-notifications, which helps with registering the required COM components and calling your Electron app with the entered user data.
To detect whether or not you're allowed to send a notification, use the userland module electron-notification-state.
\nThis allows you to determine ahead of time whether or not Windows will silently throw the notification away.
\nLas notificaciones son directas en macOS, pero usted debe ser conciente de Apple's Human Interface guidelines regarding notifications.
\nTenga en cuenta que las notificaciones están limitadas a 256 bytes de tamaño y se truncarán si supera ese límite.
\nPara detectar si se le permite o no enviar una notificación, use el módulo de usuario electron-notification-state.
\nEsto le permitirá detectar con anticipación si la notificación se mostrará o no.
\nLas notificaciones se envían utilizando libnotify que puede mostrar notificaciones en cualquier entorno de escritorio que siga la Especificación de Notificaciones de Escritorio, incluidos Cinnamon, Enlightenment, Unity, GNOME, KDE.
Offscreen rendering te permite obtener el contenido de un BrowserWindow en un bitmap, así puede renderizarlo en cualquier lugar, por ejemplo, en una textura de una escena 3D. El offscreen rendering en Electron utiliza un enfoque similar al del proyecto Chromium Embedded Framework.
Notas:
\npaint para ser más eficiente.La renderización acelerada por GPU significa que la GPU se usa para la composición. Por eso, el frame ha de ser copiado desde la GPU lo cual requiere mas recursos, por lo tanto este modo es mas lento que el dispositivo de salida de Software. The benefit of this mode is that WebGL and 3D CSS animations are supported.
\nEste modo usa un dispositivo de salida por Software para renderizar en la CPU, asi que la generación del frame es mucho más rápida. Como resultado, este modo es preferido sobre el GPU acelerado.
\nPara habilitar este modo, la aceleración de la GPU ha de ser deshabilitada llamando a la API app.disableHardwareAcceleration().
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\n\napp.disableHardwareAcceleration()\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ webPreferences: { offscreen: true } })\n\n win.loadURL('https://github.com')\n win.webContents.on('paint', (event, dirty, image) => {\n fs.writeFileSync('ex.png', image.toPNG())\n })\n win.webContents.setFrameRate(60)\n})\nAfter launching the Electron application, navigate to your application's working folder, where you'll find the rendered image.
", "title": "Representación fuera de la pantalla", "description": "" }, "/docs/tutorial/online-offline-events": { "locale": "es-ES", "slug": "online-offline-events", "href": "/docs/tutorial/online-offline-events", "crowdinFileId": "256229", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/online-offline-events.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "La detección de Evento en línea y fuera de líena puede ser implementado en el Renderer process usando el atributo navigator.onLine, parte de la API HTML5 estándar.
El atributo navigator.onLine devuelve:
false si todas la solicitudes de red están garantizada para fallar (p.ej. cuando se desconecta de la red).true en todo los otros casos.Since many cases return true, you should treat with care situations of getting false positives, as we cannot always assume that true value means that Electron can access the Internet. Por ejemplo, en casos cuando la computadora esta corriendo un programa de virtualización que tiene un adaptador Ethernet virtual en estado \"siempre conectado\". Por lo tanto, si quieres determinar el estado de la conexión a Internet de Electron, deberías desarrollar una manera adicional para comprobar esto.
Starting with an HTML file index.html, this example will demonstrate how the navigator.onLine API can be used to build a connection status indicator.
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n</head>\n<body>\n <h1>Connection status: <strong id='status'></strong></h1>\n <script src=\"renderer.js\"></script>\n</body>\n</html>\nIn order to mutate the DOM, create a renderer.js file that adds event listeners to the 'online' and 'offline' window events. The event handler sets the content of the <strong id='status'> element depending on the result of navigator.onLine.
function updateOnlineStatus () {\n document.getElementById('status').innerHTML = navigator.onLine ? 'online' : 'offline'\n}\n\nwindow.addEventListener('online', updateOnlineStatus)\nwindow.addEventListener('offline', updateOnlineStatus)\n\nupdateOnlineStatus()\nFinally, create a main.js file for main process that creates the window.
const { app, BrowserWindow } = require('electron')\n\nfunction createWindow () {\n const onlineStatusWindow = new BrowserWindow({\n width: 400,\n height: 100\n })\n\n onlineStatusWindow.loadFile('index.html')\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nAfter launching the Electron application, you should see the notification:
\n
\n", "title": "Tarjeta de crédito", "description": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API." }, "/docs/development/patches": { "locale": "es-ES", "slug": "patches", "href": "/docs/development/patches", "crowdinFileId": "256161", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/patches.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API.
\n
Electron está construido sobre dos grandes proyectos principales: Chromium y Node.js. Cada uno de estos proyectos tienen también varias de sus propias dependencias. Hacemos todo lo posible para utilizar estas dependencias exactamente como están, pero a veces no podemos lograr nuestros objetivos sin parchear esas dependencias en upstream para que se ajusten a nuestros casos de uso.
\nCada parche en Electron es una carga de mantenimiento. Cuando el código original cambia, los parches pueden romperse, a veces incluso sin conflicto de parches o error de compilación. Es un esfuerzo continuo para mantener nuestro parche actualizado y efectivo. Así que nos esforzamos por mantener el número de parches como mínimo. Para ello, cada parche debe describir su razón de existencia en su mensaje de commit. Esa razón debe ser unas de las siguientes:
\nProfile Chrome). Incluye razonamiento sobre por qué el cambio no se puede implementar sin un parche (por ejemplo, subclasificar o copiar el código).In general, all the upstream projects we work with are friendly folks and are often happy to accept refactorings that allow the code in question to be compatible with both Electron and the upstream project. (See e.g. this change in Chromium, which allowed us to remove a patch that did the same thing, or this change in Node, which was a no-op for Node but fixed a bug in Electron.) Deberíamos enfocarnos en los cambios siempre que podamos y evitar los parches de duración indefinida.
\nIf you find yourself in the unfortunate position of having to make a change which can only be made through patching an upstream project, you'll need to know how to manage patches in Electron.
\nTodos los parches a los proyectos upstream en Electron están contenidos en el directorio patches/. Cada subdirectorio de patches/ contiene varios archivos de parche, junto con un archivo .patches el cual lista el orden en el cual los parches deberían ser aplicados. Think of these files as making up a series of git commits that are applied on top of the upstream project after we check it out.
patches\n├── config.json <-- this describes which patchset directory is applied to what project\n├── chromium\n│ ├── .patches\n│ ├── accelerator.patch\n│ ├── add_contentgpuclient_precreatemessageloop_callback.patch\n│ ⋮\n├── node\n│ ├── .patches\n│ ├── add_openssl_is_boringssl_guard_to_oaep_hash_check.patch\n│ ├── build_add_gn_build_files.patch\n│ ⋮\n⋮\n\nPara ayudar a manejar estos conjuntos de parches, proporcionamos dos herramientas: git-import-patches y git-export-patches. git-import-patches importa un conjunto de archivos de parche en un repositorio git aplicando cada parche en el orden correcto y creando un commit para cada parche. git-export-patches hace el reverso; exporta una serie de commits git en un repositorio a un conjunto de ficheros en un directorio y un arvhivo .patches adjunto.
\n\nNota al margen: la razón por la que usamos un archivo
\n.patchespara mantener el orden de los parches aplicados, en lugar de anteponer un número como001-a cada archivo, es porque reduce los conflictos relacionados al orden de parches. It prevents the situation where two PRs both add a patch at the end of the series with the same numbering and end up both getting merged resulting in a duplicate identifier, and it also reduces churn when a patch is added or deleted in the middle of the series.
$ cd src/third_party/electron_node\n$ vim some/code/file.cc\n$ git commit\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\n\n\nNOTA:
\ngit-export-patchesignora cualquier archivo sin confirmar, así que debes crear un commit si quieres que tus cambios sean exportados. La línea de asunto del mensaje de confirmación se utilizará para derivar el nombre del archivo del parche, y el cuerpo del mensaje de confirmación debe incluir la razón de la existencia del parche.
La reexportación de parches ocasionalmente causará que cambien los shasums en parches no relacionados. Esto es generalmente inofensivo y puede ser ignorado (pero sigue adelante y agrega esos cambios a tu PR, esto evitará que aparezcan para otras personas).
\n$ cd src/v8\n$ vim some/code/file.cc\n$ git log\n# Find the commit sha of the patch you want to edit.\n$ git commit --fixup [COMMIT_SHA]\n$ git rebase --autosquash -i [COMMIT_SHA]^\n$ ../electron/script/git-export-patches -o ../electron/patches/v8\n$ vim src/electron/patches/node/.patches\n# Delete the line with the name of the patch you want to remove\n$ cd src/third_party/electron_node\n$ git reset --hard refs/patches/upstream-head\n$ ../../electron/script/git-import-patches ../../electron/patches/node\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\nTenga en cuenta que git-import-patches marcará el commit que fue HEAD cundo este haya corrido como refs/patches/upstream-head. Esto te permite hacer un seguimiento de que commits son parches de Electron (aquellos que vienen después de refs/patches/upstream-head) y cuales commits están en upstream (aquellos antes refs/patches/upstream-head).
Cuando se actualiza una dependencia upstream, es posible que los parches fallen al aplicar limpiamente. A menudo, el conflicto puede ser resolvido automáticamente mediante git con un fusión de tres vías. Puedes indicar a git-import-patches que use el algoritmo de fusión de 3 vías pasando el argumento -3:
$ cd src/third_party/electron_node\n# If the patch application failed midway through, you can reset it with:\n$ git am --abort\n# And then retry with 3-way merge:\n$ ../../electron/script/git-import-patches -3 ../../electron/patches/node\nSi git-import-patches -3 encuentra un merge conflict que no puede resolver automáticamente, se pausará y te permitirá resolver el conflicto manualmente. Una vez que has resuelto el conflicto,git add los archivos resueltos y continua aplicando el resto de los parches ejecutando git am --continue.
Los desarrolladores preguntan frecuentemente sobre estrategias para optimizar el rendimiento de aplicaciones de Electron. Los ingenieros de software, los consumidores y los desarrolladores de framework no siempre están de acuerdo en una sola definición de lo que significa \"rendimiento\". Este documento describe algunas de las formas favoritas de los desarrolladores de Electron para reducir el uso de recursos de memoria, CPU y disco asegurando a su vez que tu app sea responsiva a las entradas del usuario y complete operaciones tan rápidamente como sea posible. De hecho, queremos que todas las estrategias para asegurar el rendimiento mantengan un alto estándar para la seguridad de tu aplicación.
\nWisdom and information about how to build performant websites with JavaScript generally applies to Electron apps, too. To a certain extent, resources discussing how to build performant Node.js applications also apply, but be careful to understand that the term \"performance\" means different things for a Node.js backend than it does for an application running on a client.
\nThis list is provided for your convenience – and is, much like our security checklist – not meant to exhaustive. It is probably possible to build a slow Electron app that follows all the steps outlined below. Electron is a powerful development platform that enables you, the developer, to do more or less whatever you want. All that freedom means that performance is largely your responsibility.
\nThe list below contains a number of steps that are fairly straightforward and easy to implement. However, building the most performant version of your app will require you to go beyond a number of steps. Instead, you will have to closely examine all the code running in your app by carefully profiling and measuring. Where are the bottlenecks? When the user clicks a button, what operations take up the brunt of the time? While the app is simply idling, which objects take up the most memory?
\nTime and time again, we have seen that the most successful strategy for building a performant Electron app is to profile the running code, find the most resource-hungry piece of it, and to optimize it. Repeating this seemingly laborious process over and over again will dramatically increase your app's performance. Experience from working with major apps like Visual Studio Code or Slack has shown that this practice is by far the most reliable strategy to improve performance.
\nTo learn more about how to profile your app's code, familiarize yourself with the Chrome Developer Tools. For advanced analysis looking at multiple processes at once, consider the Chrome Tracing tool.
\nChances are that your app could be a little leaner, faster, and generally less resource-hungry if you attempt these steps.
\nAntes de agregar un módulo Node.js a su aplicación, examine dicho módulo. ¿Cuántas dependencias ese módulo incluye? ¿Qué tipo de recursos necesita para simplemente ejecutar la sentencia require()? Podría encontrar que el módulo con más descargas en el registro de paquetes NPM o la mayoría de estrellas en GitHub no es de hecho el más simple o el más pequeño disponible.
El razonamiento detrás de esta recomendación es mejor ilustrado con un ejemplo de mundo real. Durante los primeros días del Electron, la detección fiable de la conectividad de la red fue un problema, resultando en que muchas aplicaciones usaran un módulo que expone un simple método isOnline().
Ese módulo detectaba la conectividad de su red al intentar comunicarse con un número de endpoints conocidos. Para la lista de esos endpoints, dependía de un módulo diferente, que también contenía un lista conocida de puertos. Esta dependencia se basaba en un módulo que contenía información sobre los puertos, que venía en forma de un archivo JSON con más de 100.000 líneas de contenido. Siempre que el modulo era cargado (usualmente en una sentencia require('module')) este debía cargar todas sus dependencias y eventualmente parsear este archivo JSON. El análisis de miles de líneas JSON es una operación muy costosa. En una máquina lenta esto puede tomar segundos enteros de tiempo.
En muchos contextos de servidor, el tiempo de inicio es prácticamente irrelevante. Un servidor Node.js que requiere información sobre todos los puertos es probable que sea \"más eficiente\" si carga toda la memoria requerida en la memoria cada vez que el servidor inicia con la ventaja de servir peticiones mas rápido. El módulo discutido en este ejemplo no es un \"mal\" módulo. Electron apps, however, should not be loading, parsing, and storing in memory information that it does not actually need.
\nIn short, a seemingly excellent module written primarily for Node.js servers running Linux might be bad news for your app's performance. In this particular example, the correct solution was to use no module at all, and to instead use connectivity checks included in later versions of Chromium.
\nWhen considering a module, we recommend that you check:
\nrequire())Generating a CPU profile and a heap memory profile for loading a module can be done with a single command on the command line. In the example below, we're looking at the popular module request.
node --cpu-prof --heap-prof -e \"require('request')\"\nExecuting this command results in a .cpuprofile file and a .heapprofile file in the directory you executed it in. Both files can be analyzed using the Chrome Developer Tools, using the Performance and Memory tabs respectively.
In this example, on the author's machine, we saw that loading request took almost half a second, whereas node-fetch took dramatically less memory and less than 50ms.
If you have expensive setup operations, consider deferring those. Inspect all the work being executed right after the application starts. Instead of firing off all operations right away, consider staggering them in a sequence more closely aligned with the user's journey.
\nIn traditional Node.js development, we're used to putting all our require() statements at the top. If you're currently writing your Electron application using the same strategy and are using sizable modules that you do not immediately need, apply the same strategy and defer loading to a more opportune time.
Loading modules is a surprisingly expensive operation, especially on Windows. When your app starts, it should not make users wait for operations that are currently not necessary.
\nThis might seem obvious, but many applications tend to do a large amount of work immediately after the app has launched - like checking for updates, downloading content used in a later flow, or performing heavy disk I/O operations.
\nVamos a considerar Visual Studio Code como un ejemplo. When you open a file, it will immediately display the file to you without any code highlighting, prioritizing your ability to interact with the text. Once it has done that work, it will move on to code highlighting.
\nLet's consider an example and assume that your application is parsing files in the fictitious .foo format. In order to do that, it relies on the equally fictitious foo-parser module. In traditional Node.js development, you might write code that eagerly loads dependencies:
const fs = require('fs')\nconst fooParser = require('foo-parser')\n\nclass Parser {\n constructor () {\n this.files = fs.readdirSync('.')\n }\n\n getParsedFiles () {\n return fooParser.parse(this.files)\n }\n}\n\nconst parser = new Parser()\n\nmodule.exports = { parser }\nIn the above example, we're doing a lot of work that's being executed as soon as the file is loaded. Do we need to get parsed files right away? Could we do this work a little later, when getParsedFiles() is actually called?
// \"fs\" is likely already being loaded, so the `require()` call is cheap\nconst fs = require('fs')\n\nclass Parser {\n async getFiles () {\n // Touch the disk as soon as `getFiles` is called, not sooner.\n // Also, ensure that we're not blocking other operations by using\n // the asynchronous version.\n this.files = this.files || await fs.readdir('.')\n\n return this.files\n }\n\n async getParsedFiles () {\n // Our fictitious foo-parser is a big and expensive module to load, so\n // defer that work until we actually need to parse files.\n // Since `require()` comes with a module cache, the `require()` call\n // will only be expensive once - subsequent calls of `getParsedFiles()`\n // will be faster.\n const fooParser = require('foo-parser')\n const files = await this.getFiles()\n\n return fooParser.parse(files)\n }\n}\n\n// This operation is now a lot cheaper than in our previous example\nconst parser = new Parser()\n\nmodule.exports = { parser }\nIn short, allocate resources \"just in time\" rather than allocating them all when your app starts.
\nElectron's main process (sometimes called \"browser process\") is special: It is the parent process to all your app's other processes and the primary process the operating system interacts with. It handles windows, interactions, and the communication between various components inside your app. It also houses the UI thread.
\nUnder no circumstances should you block this process and the UI thread with long-running operations. Blocking the UI thread means that your entire app will freeze until the main process is ready to continue processing.
\nThe main process and its UI thread are essentially the control tower for major operations inside your app. When the operating system tells your app about a mouse click, it'll go through the main process before it reaches your window. If your window is rendering a buttery-smooth animation, it'll need to talk to the GPU process about that – once again going through the main process.
\nElectron and Chromium are careful to put heavy disk I/O and CPU-bound operations onto new threads to avoid blocking the UI thread. Deberías hacer lo mismo.
\nElectron's powerful multi-process architecture stands ready to assist you with your long-running tasks, but also includes a small number of performance traps.
\n1) Para tareas pesadas de la CPU, utilice worker threads, considere moverlos a BrowserWindow, o (como último recurso) genere un proceso dedicado.
\n2) Avoid using the synchronous IPC and the remote module as much as possible. While there are legitimate use cases, it is far too easy to unknowingly block the UI thread using the remote module.
3) Avoid using blocking I/O operations in the main process. In short, whenever core Node.js modules (like fs or child_process) offer a synchronous or an asynchronous version, you should prefer the asynchronous and non-blocking variant.
Dado que Electron se envía con una versión actual de Chrome, puede hacer uso de las últimas y mejores funciones que ofrece la plataforma web para aplazar o descargar operaciones pesadas de una manera que mantenga su aplicación fluida y receptiva.
\nYour app probably has a lot of JavaScript to run in the renderer process. The trick is to execute operations as quickly as possible without taking away resources needed to keep scrolling smooth, respond to user input, or animations at 60fps.
\nOrchestrating the flow of operations in your renderer's code is particularly useful if users complain about your app sometimes \"stuttering\".
\nGenerally speaking, all advice for building performant web apps for modern browsers apply to Electron's renderers, too. Las dos herramientas principales a su disposición actualmente son requestIdleCallback() para pequeñas operaciones y Web Workers para operaciones de ejecución prolongada.
requestIdleCallback() allows developers to queue up a function to be executed as soon as the process is entering an idle period. It enables you to perform low-priority or background work without impacting the user experience. Para más información sobre como usarlo, revise su documentación en MDN.
Web Workers son una herramienta poderosa para correr código en un hilo separado. Hay algunas advertencias a considerar - consulte la documentación de multihilos y la documentación de MDN para trabajadores Web de Electron. They're an ideal solution for any operation that requires a lot of CPU power for an extended period of time.
\nOne of Electron's great benefits is that you know exactly which engine will parse your JavaScript, HTML, and CSS. If you're re-purposing code that was written for the web at large, make sure to not polyfill features included in Electron.
\nWhen building a web application for today's Internet, the oldest environments dictate what features you can and cannot use. Even though Electron supports well-performing CSS filters and animations, an older browser might not. Where you could use WebGL, your developers may have chosen a more resource-hungry solution to support older phones.
\nWhen it comes to JavaScript, you may have included toolkit libraries like jQuery for DOM selectors or polyfills like the regenerator-runtime to support async/await.
It is rare for a JavaScript-based polyfill to be faster than the equivalent native feature in Electron. Do not slow down your Electron app by shipping your own version of standard web platform features.
\nOperate under the assumption that polyfills in current versions of Electron are unnecessary. If you have doubts, check caniuse.com and check if the version of Chromium used in your Electron version supports the feature you desire.
\nIn addition, carefully examine the libraries you use. ¿Son realmente necesarias? jQuery, por ejemplo, fue un éxito tal que muchas de sus característica ahora son partes del standard JavaScript feature set available.
If you're using a transpiler/compiler like TypeScript, examine its configuration and ensure that you're targeting the latest ECMAScript version supported by Electron.
\nAvoid fetching rarely changing resources from the internet if they could easily be bundled with your application.
\nMany users of Electron start with an entirely web-based app that they're turning into a desktop application. As web developers, we are used to loading resources from a variety of content delivery networks. Now that you are shipping a proper desktop application, attempt to \"cut the cord\" where possible and avoid letting your users wait for resources that never change and could easily be included in your app.
\nA typical example is Google Fonts. Many developers make use of Google's impressive collection of free fonts, which comes with a content delivery network. The pitch is straightforward: Include a few lines of CSS and Google will take care of the rest.
\nWhen building an Electron app, your users are better served if you download the fonts and include them in your app's bundle.
\nIn an ideal world, your application wouldn't need the network to operate at all. To get there, you must understand what resources your app is downloading - and how large those resources are.
\nTo do so, open up the developer tools. Navigate to the Network tab and check the Disable cache option. Then, reload your renderer. Unless your app prohibits such reloads, you can usually trigger a reload by hitting Cmd + R or Ctrl + R with the developer tools in focus.
The tools will now meticulously record all network requests. In a first pass, take stock of all the resources being downloaded, focusing on the larger files first. Are any of them images, fonts, or media files that don't change and could be included with your bundle? If so, include them.
\nAs a next step, enable Network Throttling. Find the drop-down that currently reads Online and select a slower speed such as Fast 3G. Reload your renderer and see if there are any resources that your app is unnecessarily waiting for. In many cases, an app will wait for a network request to complete despite not actually needing the involved resource.
As a tip, loading resources from the Internet that you might want to change without shipping an application update is a powerful strategy. Para un control avanzado sobre como los recursos se cargan, considere invertir en Service Workers.
\nAs already pointed out in \"Loading and running code too soon\", calling require() is an expensive operation. If you are able to do so, bundle your application's code into a single file.
Modern JavaScript development usually involves many files and modules. While that's perfectly fine for developing with Electron, we heavily recommend that you bundle all your code into one single file to ensure that the overhead included in calling require() is only paid once when your application loads.
There are numerous JavaScript bundlers out there and we know better than to anger the community by recommending one tool over another. We do however recommend that you use a bundler that is able to handle Electron's unique environment that needs to handle both Node.js and browser environments.
\nAl escribir este artículo, las opciones populares incluyen Webpack, Parcel y rollup.js.
", "title": "Rendimiento", "description": "" }, "/docs/api/structures/point": { "locale": "es-ES", "slug": "point", "href": "/docs/api/structures/point", "crowdinFileId": "256475", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/point.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "x Numbery NumberNote: Both x and y must be whole integers, when providing a point object as input to an Electron API we will automatically round your x and y values to the nearest whole integer.
data (UploadRawData | UploadFile)[] - The post data to be sent to the new window.contentType String - The content-type header used for the data. One of application/x-www-form-urlencoded or multipart/form-data. Corresponds to the enctype attribute of the submitted HTML form.boundary String (optional) - The boundary used to separate multiple parts of the message. Only valid when contentType is multipart/form-data.Note that keys starting with -- are not currently supported. For example, this will errantly submit as multipart/form-data when nativeWindowOpen is set to false in webPreferences:
<form\n target=\"_blank\"\n method=\"POST\"\n enctype=\"application/x-www-form-urlencoded\"\n action=\"https://postman-echo.com/post\"\n>\n <input type=\"text\" name=\"--theKey\">\n <input type=\"submit\">\n</form>\n\n\nMonitorea los cambios de estado de energía.
\n
Proceso: principal</0>
\nEl módulo powerMonitor emite los siguientes eventos:
Se emite cuando se suspende el sistema.
\nSe emite cuando se reanuda el sistema.
\nSe emite cuando el sistema se cambia a la corriente alterna.
\nSe emite cuando el sistema se cambia a la energía de batería.
\nSe emite cuando el sistema está a punto de reiniciarse o apagarse. Si el controlador de eventos invocó e.preventDefault(), Electron intentará retrasar el apagado del sistema para que la aplicación salga limpiamente. Si se llama a e.preventDefault(), la aplicación debe salir tan pronto como sea posible llamando a algo como app.quit().
Emitido cuando el sistema está a punto de bloquear la pantalla.
\nEmitido tan pronto como el sistema desbloquea la pantalla.
\nEmitted when a login session is activated. See documentation for more information.
\nEmitted when a login session is deactivated. See documentation for more information.
\nEl modulo powerMonitor tiene los siguientes métodos:
powerMonitor.getSystemIdleState(idleThreshold)idleThreshold IntegerReturns String - The system's current state. Puede ser active, idle, locked o unknown.
Calcule el estado de reposo del sistema. idleThreshold es la cantidad de tiempo (en segundos) antes de considerar inactivo. locked is available on supported systems only.
powerMonitor.getSystemIdleTime()Devuelve Integer - Tiempo inactivo en segundos
Calcular tiempo inactivo del sistema en segundos.
\npowerMonitor.isOnBatteryPower()Returns Boolean - Whether the system is on battery power.
To monitor for changes in this property, use the on-battery and on-ac events.
powerMonitor.onBatteryPowerUna propiedad Boolean. True if the system is on battery power.
See powerMonitor.isOnBatteryPower().
\n\nBloquea al sistema para evitar que entre en el modo de bajo consumo (suspensión).
\n
Proceso: principal</0>
\nPor ejemplo:
\nconst { powerSaveBlocker } = require('electron')\n\nconst id = powerSaveBlocker.start('prevent-display-sleep')\nconsole.log(powerSaveBlocker.isStarted(id))\n\npowerSaveBlocker.stop(id)\nEl módulo powerSaveBlocker tiene los siguientes métodos:
powerSaveBlocker.start(type)type String - Power save blocker type.prevent-app-suspension - Evita que la aplicación sea suspendida. Mantiene el sistema activo pero permite apagar la pantalla. Ejemplo de casos de uso: descargar un archivo o reproducir audio.prevent-display-sleep - Evita que la pantalla quede inactiva. Mantiene el sistema y la pantalla activos. Ejemplo de caso de uso: reproducción de video.Devuelve Integer - El ID bloqueador que se asigna al bloqueador de energía.
Inicia evitando que el sistema entre en modo de bajo consumo. Devuelve un entero que identifica el bloqueador de ahorro de energía.
\nNota: prevent-display-sleep tiene mayor prioridad sobre prevent-app-suspension. Solo el tipo de mayor prioridad tiene efecto. En otras palabras, prevent-display-sleep tiene mayor prioridad sobre prevent-app-suspension.
Por ejemplo, una API llamada A solicita a prevent-app-suspension, y otra llamada B solicita a prevent-display-sleep. Se utilizará prevent-display-sleep hasta que B detenga su solicitud. Luego de eso, se utilizará prevent-app-suspension.
powerSaveBlocker.stop(id)id Entero - El id de bloqueo de ahorro de energía devuelto por powerSaveBlocker.start.Detiene el bloqueador de ahorro de energía especificado.
\npowerSaveBlocker.isStarted(id)id Entero - El id de bloqueo de ahorro de energía devuelto por powerSaveBlocker.start.Devuelve Boolean - Si ha iniciado el powerSaveBlocker correspondiente.
name String - the name of the printer as understood by the OS.displayName String - the name of the printer as shown in Print Preview.description String - a longer description of the printer's type.status Number - the current status of the printer.isDefault Boolean - whether or not a given printer is set as the default printer on the OS.options Object - an object containing a variable number of platform-specific printer information.The number represented by status means different things on different platforms: on Windows its potential values can be found here, and on Linux and macOS they can be found here.
Below is an example of some of the additional options that may be set which may be different on each platform.
\n{\n name: 'Austin_4th_Floor_Printer___C02XK13BJHD4',\n displayName: 'Austin 4th Floor Printer @ C02XK13BJHD4',\n description: 'TOSHIBA ColorMFP',\n status: 3,\n isDefault: false,\n options: {\n copies: '1',\n 'device-uri': 'dnssd://Austin%204th%20Floor%20Printer%20%40%20C02XK13BJHD4._ipps._tcp.local./?uuid=71687f1e-1147-3274-6674-22de61b110bd',\n finishings: '3',\n 'job-cancel-after': '10800',\n 'job-hold-until': 'no-hold',\n 'job-priority': '50',\n 'job-sheets': 'none,none',\n 'marker-change-time': '0',\n 'number-up': '1',\n 'printer-commands': 'ReportLevels,PrintSelfTestPage,com.toshiba.ColourProfiles.update,com.toshiba.EFiling.update,com.toshiba.EFiling.checkPassword',\n 'printer-info': 'Austin 4th Floor Printer @ C02XK13BJHD4',\n 'printer-is-accepting-jobs': 'true',\n 'printer-is-shared': 'false',\n 'printer-is-temporary': 'false',\n 'printer-location': '',\n 'printer-make-and-model': 'TOSHIBA ColorMFP',\n 'printer-state': '3',\n 'printer-state-change-time': '1573472937',\n 'printer-state-reasons': 'offline-report,com.toshiba.snmp.failed',\n 'printer-type': '10531038',\n 'printer-uri-supported': 'ipp://localhost/printers/Austin_4th_Floor_Printer___C02XK13BJHD4',\n system_driverinfo: 'T'\n }\n}\n\n\n\nExtensiones para el objeto process.
\n
El objeto process de Electron es heredado del objeto process de Node.js. Este agrega los siguientes eventos, propiedades y métodos:
En el procesor renderer en sandbox el objeto process sólo contiene un subconjunto de las APIs:
crash()hang()getCreationTime()getHeapStatistics()getBlinkMemoryInfo()getProcessMemoryInfo()getSystemMemoryInfo()getSystemVersion()getCPUUsage()getIOCounters()uptime()argvexecPathenvpidarchplatformsandboxedcontextIsolatedtypeversionversionsmaswindowsStorecontextIdEmitido cuando Electron ha cargado su script de inicialización interno y está empezando a carga la página web o el script principal.
\nprocess.defaultApp Solo lecturaUn Boolean. When app is started by being passed as parameter to the default app, this property is true in the main process, otherwise it is undefined.
process.isMainFrame Solo lecturaUn Boolean, true cuando el contexto actual del renderer es \"main\" renderer frame. Si quieres el ID del frame actual deberías usar webFrame.routingId.
process.mas Solo lecturaUn Boolean. Para compilaciones de Mac App Store, esta propiedad es true, para otras compilaciones es undefined.
proceso.noAsarUn Boolean que controla el soporte ASAR dentro de tu aplicación. Establecer esto a true desactivará el soporte para archivos asar en los módulos integrados de Node.
process.noDeprecationUn Boolean que controla si las advertencias de deprecación se imprimen o no a stderr. Modificar esta propiedad a true silenciará las advertencias de depreciación. Esta propiedad es usada en lugar de la linea de comando --no-deprecation.
process.resourcesPath Solo lecturaUn string que representa la ruta de acceso al directorio de recursos.
process.sandboxed Solo lecturaUn Boolean. When the renderer process is sandboxed, this property is true, otherwise it is undefined.
process.contextIsolated SoloLecturaUn Boolean que indica si el renderer context acutal tiene el contextIsolation activado. Es undefined en el main process.
proceso.desechoDegradaciónUn Booleano que controla si las advertencias de degradación son consideradas como excepción. Ajustando este como verdad se producirán errores por degradación. Esta propiedad es usada en vez de la linea de comando --throw-deprecation.
proceso.ubicarDegradaciónUn Booleano que controla si las degradaciones son enviadas a stderr incluyen su proceso de ubicación. Ajustando este como true se enviarán ubicaciones de pila por degradaciones. Esta propiedad es en vez de la linea de comando --trace-deprecation.
proceso.ubicarAdvertenciasdeProcesosUn Booleano que controla si las advertencias de procesos son enviadas a stderr incluyen su proceso de ubicación. Ajustando este como verdad se enviarán ubicaciones de pila para advertencias de procesos (incluyendo degradaciones). Esta propiedad es en vez de la línea de comando --trace-warnings.
process.type Solo lecturaUn String que representa el tipo de proceso actual, puede ser:
browser - El main processrenderer - Un renderer processworker - En un web workerprocess.versions.chrome Solo lecturaUna cadena representando la versión de cadena de Chrome.
process.versions.electron Solo lecturaUna cadena representando la versión de cadena de Electron.
process.windowsStore Solo lecturaUn Boolean. If the app is running as a Windows Store app (appx), this property is true, for otherwise it is undefined.
process.contextId SoloLecturaUn String (opcional) que representa un único global ID del contexto JavaScript actual. Cada frame tiene su propio contexto JavaScript. Cuando el contextIsolation está activado, el isolated world además tiene un contexto JavaScript separado. Esta propiedad solo está disponible en el renderer process.
El objeto proceso tiene los siguientes métodos:
proceso.crash()Hace que el hilo principal del proceso actual se detenga.
\nprocess.getCreationTime()Devuelve Number | null - El numero de mili-segundos desde la época o null si la información no esta disponible
Indicates the creation time of the application. El tiempo es representado como número de milisegundos desde la época. Devuelve null si no es capaz de obtener el tiempo de creación del proceso.
\nprocess.getCPUUsage()Devuelve CPUUsage
process.getIOCounters() Windows LinuxDevuelve IOCounters
process.getHeapStatistics()Devuelve Objeto:
totalHeapSize IntegertotalHeapSizeExecutable IntegertotalPhysicalSize IntegertotalAvailableSize IntegerusedHeapSize IntegerheapSizeLimit IntegermallocedMemory IntegerpeakMallocedMemory IntegerdoesZapGarbage BooleanDevuelve un objeto con estadísticas de la pila V8. Tome en cuenta que todas las estadísticas son reportadas en Kilobytes.
\nprocess.getBlinkMemoryInfo()Devuelve Objeto:
allocated Integer - Tamaño de todos los objetos asignados en Kilobytes.marked Integer - Tamaño de todos los objetos marcados en Kilobytes.total Integer - Espacio total asignado en Kilobytes.Returns an object with Blink memory information. It can be useful for debugging rendering / DOM related memory issues. Note that all values are reported in Kilobytes.
\nprocess.getProcessMemoryInfo()Devuelve Promise<ProcessMemoryInfo> - Resuelve con un ProcessMemoryInfo
Returns an object giving memory usage statistics about the current process. Note that all statistics are reported in Kilobytes. This api should be called after app ready.
\nChromium no provee el valor residentSet para macOS. Esto es porque macOS realiza compresión en memoria que no han sido utilizadas recientemente. Como resultado, el valor del tamaño del conjunto de residentes no es lo que uno esperaría. Memoria private es más representativo del uso real de la memoria de precompresión del proceso en macOS.
process.getSystemMemoryInfo()Devuelve Objeto:
total Entero - La cantidad total de memoria física en kilobytes de la que dispone el sistema.libre entero - La cantidad de memoria que no está siendo usada por aplicaciones o caché de disco.swapTotal Integer Windows Linux - La cantidad total de memoria de swap en Kilobytes disponible para el sistema.swapFree Integer Windows Linux - La cantidad libre de memoria de swap en Kilobytes disponible para el sistema.Returns an object giving memory usage statistics about the entire system. Note that all statistics are reported in Kilobytes.
\nprocess.getSystemVersion()Devuelve String - La versión de sistema operativo del host.
Ejemplo:
\nconst version = process.getSystemVersion()\nconsole.log(version)\n// En macOS -> '10.13.6'\n// En Windows -> '10.0.17763'\n// En Linux -> '4.15.0-45-generic'\nNote: Devuelve la versión actual del sistema en lugar de la versión del kernel en macOS deferente a os.release().
process.takeHeapSnapshot(filePath)filePath String - Ruta al archivo de salida.Devuelve Boolean - Indica si la instantánea ha sido creada correctamente.
Toma una instantánea de la pila V8 y la guarda en filePath.
process.hang()Hace que el hilo principal del proceso actual se caiga.
\nprocess.setFdLimit(maxDescriptors) macOS LinuxmaxDescriptors EnteroAjusta el limite suave del descriptor del documento a maxDescriptors o el límite duro OS, cual sea menor para el proceso actual.
residentSet Integer Linux Windows - The amount of memory currently pinned to actual physical RAM in Kilobytes.private Integer - The amount of memory not shared by other processes, such as JS heap or HTML content in Kilobytes.shared Integer - The amount of memory shared between processes, typically memory consumed by the Electron code itself in Kilobytes.pid Integer - Process id of the process.type String - Tipo de proceso. Uno de los siguiente valores:BrowserTabUtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownserviceName String (opcional) - El nombre no localizado del proceso.name String (opcional) - El nombre del proceso. Examples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.cpu CPUUsage - CPU usage of the process.creationTime Number - Creation time for this process. The time is represented as number of milliseconds since epoch. Since the pid can be reused after a process dies, it is useful to use both the pid and the creationTime to uniquely identify a process.memory MemoryInfo - Memory information for the process.sandboxed Boolean (optional) macOS Windows - Whether the process is sandboxed on OS level.integrityLevel String (optional) Windows - One of the following values:untrustedlowmediumhighunknownElectron hereda su arquitectura multiprocesos de Chromium, lo que hace que la arquitectura del framework sea muy similar a la de un navegador web moderno. En esta guía, expondremos el conocimiento conceptual de Electron que aplicamos en el tutorial quick-start-app.
\nLos navegadores web son aplicaciones increíblemente complejas. Aparte de su capacidad principal para mostrar el contenido Web, tienen muchas responsabilidades secundarias, como administrar múltiples ventanas (o pestañas) y cargar extensiones de terceros.
\nEn los comienzos, los navegadores usaban un solo proceso para todas estas funcionalidades. A pesar de que este patrón significaba menos sobrecarga para cada pestaña que estaba abierta, también significaba que un sitio web que se colgaba o dejaba de funcionar afectaba a todo el navegador.
\nPara resolver este problema, el equipo de Chrome decidió que cada pestaña se renderizaría en su propio proceso, limitando el daño que código malicioso o con errores de una página web puede causar a la aplicación en su conjunto. Un único proceso de navegador controla estos procesos, así como el ciclo de vida de la aplicación en su conjunto. El siguiente diagrama de Chrome Comic representa este modelo:
\n
Las aplicaciones que usan Electron están estructuradas de forma muy similar. Como programador de una App, controlas dos tipos de procesos: principal y renderizador. Estos son análogos al propio navegador de Chrome y a los procesos descritos anteriormente.
\nEach Electron app has a single main process, which acts as the application's entry point. The main process runs in a Node.js environment, meaning it has the ability to require modules and use all of Node.js APIs.
The main process' primary purpose is to create and manage application windows with the BrowserWindow module.
Each instance of the BrowserWindow class creates an application window that loads a web page in a separate renderer process. You can interact with this web content from the main process using the window's webContents object.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\n\n\nNote: A renderer process is also created for web embeds such as the
\nBrowserViewmodule. ThewebContentsobject is also accessible for embedded web content.
Because the BrowserWindow module is an EventEmitter, you can also add handlers for various user events (for example, minimizing or maximizing your window).
When a BrowserWindow instance is destroyed, its corresponding renderer process gets terminated as well.
The main process also controls your application's lifecycle through Electron's app module. This module provides a large set of events and methods that you can use to add custom application behaviour (for instance, programatically quitting your application, modifying the application dock, or showing an About panel).
As a practical example, the app shown in the quick start guide uses app APIs to create a more native application window experience.
// quitting the app when no windows are open on non-macOS platforms\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nTo extend Electron's features beyond being a Chromium wrapper for web contents, the main process also adds custom APIs to interact with the user's operating system. Electron exposes various modules that control native desktop functionality, such as menus, dialogs, and tray icons.
\nFor a full list of Electron's main process modules, check out our API documentation.
\nEach Electron app spawns a separate renderer process for each open BrowserWindow (and each web embed). As its name implies, a renderer is responsible for rendering web content. For all intents and purposes, code ran in renderer processes should behave according to web standards (insofar as Chromium does, at least).
Therefore, all user interfaces and app functionality within a single browser window should be written with the same tools and paradigms that you use on the web.
\nAlthough explaining every web spec is out of scope for this guide, the bare minimum to understand is:
\n<script> elements.Moreover, this also means that the renderer has no direct access to require or other Node.js APIs. In order to directly include NPM modules in the renderer, you must use the same bundler toolchains (for example, webpack or parcel) that you use on the web.
\n\nNote: Renderer processes can be spawned with a full Node.js environment for ease of development. Historically, this used to be the default, but this feature was disabled for security reasons.
\n
At this point, you might be wondering how your renderer process user interfaces can interact with Node.js and Electron's native desktop functionality if these features are only accessible from the main process. In fact, there is no direct way to import Electron's content scripts.
\nA preload script can be attached to the main process in the BrowserWindow constructor's webPreferences option.
const { BrowserWindow } = require('electron')\n//...\nconst win = new BrowserWindow({\n webPreferences: {\n preload: 'path/to/preload.js'\n }\n})\n//...\nBecause the preload script shares a global Window interface with the renderers and can access Node.js APIs, it serves to enhance your renderer by exposing arbitrary APIs in the window global that your web contents can then consume.
Although preload scripts share a window global with the renderer they're attached to, you cannot directly attach any variables from the preload script to window because of the contextIsolation default.
window.myAPI = {\n desktop: true\n}\nconsole.log(window.myAPI)\n// => undefined\nContext Isolation means that preload scripts are isolated from the renderer's main world to avoid leaking any privileged APIs into your web content's code.
\nInstead, use the contextBridge module to accomplish this securely:
const { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n desktop: true\n})\nconsole.log(window.myAPI)\n// => { desktop: true }\nThis feature is incredibly useful for two main purposes:
\nipcRenderer helpers to the renderer, you can use inter-process communication (IPC) to trigger main process tasks from the renderer (and vice-versa).window global that can be used for desktop-only logic on the web client's side.productIdentifier String - The string that identifies the product to the Apple App Store.localizedDescription String - A description of the product.localizedTitle String - The name of the product.contentVersion String - A string that identifies the version of the content.contentLengths Number[] - The total size of the content, in bytes.price Number - The cost of the product in the local currency.formattedPrice String - The locale formatted price of the product.currencyCode String - 3 character code presenting a product's currency based on the ISO 4217 standard.isDownloadable Boolean - A Boolean value that indicates whether the App Store has downloadable content for this product. true if at least one file has been associated with the product.Un progress bar le permite a una ventana proveer información de progreso al usuario sin necesidad de cambiar a la propia ventana.
\nEn Windows puede usar un taskbar button para mostrar un progress bar.
\n![Barra de Progreso de Windows][https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png\\]
\nEn macOS, el progress bar será mostrado como parte del dock icon.
\n
En Linux, la interfaz gráfica Unity además tiene una característica similar que le permite especificar el progress bar en en el lanzador.
\n
\n\nNOTA: en Windows, cada ventana tiene su propio progress bar, mientras que en macOS y Linux(Unity) puede haber un solo progress bar para la aplicación.
\n
Los tres casos son cubiertos por la misma API - el método setProgressBar() disponible en una instancia de BrowserWindow. Para indicar tu progreso, invoca este método con un número entre 0 y 1. Por ejemplo, si tiene una tarea de larga ejecución que actualmente esta al 63% para completar, debería llamarlo como setProgressBar(0.63).
Setting the parameter to negative values (e.g. -1) will remove the progress bar. Setting it to a value greater than 1 will indicate an indeterminate progress bar in Windows or clamp to 100% in other operating systems. Una barra de progreso indeterminada permanece activa pero no muestra un porcentaje real, y se utiliza para situaciones cuando no sabe cuánto tardará una operación en completarse.
Ver el API documentation for more options and modes.
\nIn this example, we add a progress bar to the main window that increments over time using Node.js timers.
\nconst { app, BrowserWindow } = require('electron')\n\nlet progressInterval\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n\n const INCREMENT = 0.03\n const INTERVAL_DELAY = 100 // ms\n\n let c = 0\n progressInterval = setInterval(() => {\n // update progress bar to next value\n // values between 0 and 1 will show progress, >1 will show indeterminate or stick at 100%\n win.setProgressBar(c)\n\n // increment or reset progress bar\n if (c < 2) c += INCREMENT\n else c = 0\n }, INTERVAL_DELAY)\n}\n\napp.whenReady().then(createWindow)\n\n// before the app is terminated, clear both timers\napp.on('before-quit', () => {\n clearInterval(progressInterval)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nDespués de lanzar la aplicación Electron, el Dock (macOS) o la barra de tareas (Windows, Unity) deben mostrar una barra de progreso que comience en cero y progrese hasta el 100% hasta completarse. Luego debe mostrar indeterminado (Windows) o anclar a 100% (otros sistemas operativos) brevemente y luego bucle.
\n
Para macOS, el progress bar también será indicado para su aplicación cuando utilice Mission Control:
\n
\n\nRegistrar un protocolo personalizado e interceptar las peticiones de protocolo existentes.
\n
Proceso: principal</0>
\nUn ejemplo de la implementación de un protocolo que tiene el mismo efecto que el protocolo file://:
const { app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n})\nNota: Todos los métodos salvo los especificados pueden ser usados solo después de que el evento listo del módulo de la aplicación sea emitido.
protocol con una partition o session personalizadaUn protocolo está registrado en un objeto session específico de Electron. Si no especificas una sesión, entonces tu protocol será aplicado a la sesión por defecto que Electron. Sin embargo, si defines un partition o session en tu webPreferences del browserWindow, luego esa ventana usará una sesión diferente y tu protocolo personalizado no funcionará si solo usas electron.protocol.XXX.
Para tener su protocolo personalizado trabajando con una sesión personalizada, necesitas registrarlo a esa sesión explícitamente.
\nconst { session, app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const partition = 'persist:example'\n const ses = session.fromPartition(partition)\n\n ses.protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n\n mainWindow = new BrowserWindow({ webPreferences: { partition } })\n})\nEl módulo protocolo tiene los siguientes métodos:
protocol.registerSchemesAsPrivileged(customSchemes)customSchemes CustomScheme[]Note: Este método solo puede ser usado antes de que el evento ready del modulo app sea emitido y solo puede ser llamado una vez.
Registers the scheme as standard, secure, bypasses content security policy for resources, allows registering ServiceWorker, supports fetch API, and streaming video/audio. Specify a privilege with the value of true to enable the capability.
Un ejemplo de registro de un esquema privilegiado, que elude la Política de Seguridad Contenido:
\nconst { protocol } = require('electron')\nprotocol.registerSchemesAsPrivileged([\n { scheme: 'foo', privileges: { bypassCSP: true } }\n])\nUn esquema estandar se adhiere a lo que el RFC3986 llama Sintaxis URI genérica. Por ejemplo http y https son esquemas estándar, mientras archivo no lo es.
Registrar un esquema como estándar, permite a recursos relativos y absolutos ser resueltos correctamente cuando son servidos. De otra manera el esquema se comportaría como el protocolo archivo, pero sin la habilidad de resolver URLs relativas.
Por ejemplo cuando usted carga la siguiente carga con un protocolo personalizado sin registrar como un esquema estándar, esta imagen no será cargada debido a que un esquema que no es estandar puede no reconocer URLs relativas:
\n<body>\n <img src='test.png'>\n</body>\nRegistrar un esquema como estándar puede permitir el acceso a los archivos a travésAPI FileSystem. De otra manera el renderizador arrojará un error de seguridad en el sistema.
\nPor defecto las apis de web storage (localStorage, sessionStorage, webSQL, indexedDB, cookies) están deshabilitadas para esquemas no estándares. Así que en general, si quieres registrar un protocolo personalizado para reemplazar el protocolo http, tienes que registrarlo como un esquema estándar.
Protocols that use streams (http and stream protocols) should set stream: true. The <video> and <audio> HTML elements expect protocols to buffer their responses by default. The stream flag configures those elements to correctly expect streaming responses.
protocol.registerFileProtocol(scheme, handler)scheme Stringhandler Funciónrequest ProtocolRequestcallback Funciónresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registra un protocolo de scheme que enviará un archivo como repuesta. El handler será llamado con request y callback donde request es una solicitud entrante para el scheme.
Para controlar la solicitud, la retrollamada debe ser llamada con la ruta al archivo o un objeto que tiene una propiedad ruta, ejemplo callback(filePath) o callback({ path: filePath }). El filePath debe ser una ruta absoluta.
Por defecto el scheme es tratado como http:, que es analizado de forma diferente que los protocolos que siguen la \"generic URI syntax\" como file:.
protocol.registerBufferProtocol(scheme, handler)scheme Stringhandler Funciónrequest ProtocolRequestcallback Funciónresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registra un protocolo de esquema que enviará un Buffer como respuesta.
El uso es el mismo con registerFileProtocol, excepto que el callback debería ser llamado con un objeto Buffer o un objeto que tiene la propiedad data.
Ejemplo:
\nprotocol.registerBufferProtocol('atom', (request, callback) => {\n callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })\n})\nprotocol.registerStringProtocol(scheme, handler)scheme Stringhandler Funciónrequest ProtocolRequestcallback Funciónresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registra un protocolo de esquema que enviará una cadena como respuesta.
El uso es el mismo con registerFileProtocol, excepto que el callback debería ser llamado con un objeto String o un objeto que tiene la propiedad data.
protocol.registerHttpProtocol(scheme, handler)scheme Stringhandler Funciónrequest ProtocolRequestcallback Funciónresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully registered
Registra un protocolo de esquema que enviará una solicitud HTTP como respuesta.
El uso es el mismo con registerFileProtocol, excepto que el callback debería ser llamado con un objeto que tiene la propiedad url.
protocol.registerStreamProtocol(scheme, handler)scheme Stringhandler Funciónrequest ProtocolRequestcallback Funciónresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registra un protocolo de scheme que enviará un stream como respuesta.
El uso es el mismo con registerFileProtocol, excepto que el callback debería ser llamado con un objeto ReadableStream o un objeto que tiene la propiedad data.
Ejemplo:
\nconst { protocol } = require('electron')\nconst { PassThrough } = require('stream')\n\nfunction createStream (text) {\n const rv = new PassThrough() // PassThrough is also a Readable stream\n rv.push(text)\n rv.push(null)\n return rv\n}\n\nprotocol.registerStreamProtocol('atom', (request, callback) => {\n callback({\n statusCode: 200,\n headers: {\n 'content-type': 'text/html'\n },\n data: createStream('<h5>Response</h5>')\n })\n})\nEs posible pasar cualquier objeto que implementa la API readable stream (emite los eventos data/end/error). Por ejemplo, aquí está como puede devolver un archivo:
protocol.registerStreamProtocol('atom', (request, callback) => {\n callback(fs.createReadStream('index.html'))\n})\nprotocol.unregisterProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unregistered
Anula el registro del protocolo predeterminado de esquema.
protocol.isProtocolRegistered(scheme)scheme StringDevuelve Boolean - Si el scheme ya está registrado.
protocol.interceptFileProtocol(scheme, handler)scheme Stringhandler Funciónrequest ProtocolRequestcallback Funciónresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepta el protocolo esquema y usa controlador como el controlador del nuevo protocolo lo cual enviará un archivo como respuesta.
protocol.interceptStringProtocol(scheme, handler)scheme Stringhandler Funciónrequest ProtocolRequestcallback Funciónresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepta el protocolo esquema y usa controlador como el nuevo controlador de protocolo, lo cual envía una Cadena como respuesta.
protocol.interceptBufferProtocol(scheme, handler)scheme Stringhandler Funciónrequest ProtocolRequestcallback Funciónresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepta el protocolo de scheme y usa el handler como el nuevo manejador del protocolo, el cual envía un Buffer como respuesta.
protocol.interceptHttpProtocol(scheme, handler)scheme Stringhandler Funciónrequest ProtocolRequestcallback Funciónresponse Respuesta de ProtocoloReturns Boolean - Whether the protocol was successfully intercepted
Intercepta el protocolo scheme y utiliza el handler como el nuevo controlador del protocolo, el cual envía una nueva solicitud HTTP como respuesta.
protocol.interceptStreamProtocol(scheme, handler)scheme Stringhandler Funciónrequest ProtocolRequestcallback Funciónresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Mismo que protocol.registerStreamProtocol, excepto que reemplaza un manejador de protocolo existente.
protocol.uninterceptProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unintercepted
Elimina el interceptor instalado para el scheme y restaura su controlador original.
protocol.isProtocolIntercepted(scheme)scheme StringDevuelve Boolean - Si el scheme ya está interceptado.
url Stringreferrer Stringmethod StringuploadData UploadData[] (optional)headers Record<String, String>error Integer (optional) - When assigned, the request will fail with the error number . For the available error numbers you can use, please see the net error list.statusCode Number (optional) - The HTTP response code, default is 200.charset String (optional) - The charset of response body, default is \"utf-8\".mimeType String (optional) - The MIME type of response body, default is \"text/html\". Setting mimeType would implicitly set the content-type header in response, but if content-type is already set in headers, the mimeType would be ignored.headers Record<string, string | string[]> (optional) - An object containing the response headers. The keys must be String, and values must be either String or Array of String.data (Buffer | String | ReadableStream) (optional) - The response body. When returning stream as response, this is a Node.js readable stream representing the response body. When returning Buffer as response, this is a Buffer. When returning String as response, this is a String. This is ignored for other types of responses.path String (optional) - Path to the file which would be sent as response body. This is only used for file responses.url String (optional) - Download the url and pipe the result as response body. This is only used for URL responses.referrer String (optional) - The referrer URL. This is only used for file and URL responses.method String (optional) - The HTTP method. This is only used for file and URL responses.session Session (optional) - The session used for requesting URL, by default the HTTP request will reuse the current session. Setting session to null would use a random independent session. This is only used for URL responses.uploadData ProtocolResponseUploadData (optional) - The data used as upload data. This is only used for URL responses when method is \"POST\".contentType String - MIME type of the content.data String | Buffer - Content to be sent.Haga Fork del proyecto on GitHub y clone su fork localmente.
\n$ git clone git@github.com:username/electron.git\n$ cd electron\n$ git remote add upstream https://github.com/electron/electron.git\n$ git fetch upstream\nPasos de compilado y dependencias difieren ligeramente dependiendo de su sistema operativo. Ver estas guías detalladas en compilacion local de Electron:
\n\nUna vez que has compilado el proyecto localmente, ¡Estas listo para empezar a hacer cambios!
\nPara mantener tu entorno de desarrollo organizado, crea ramas locales para retener tu trabajo. Estos deben ser ramificados directamente de la rama main.
$ git checkout -b mi-rama -t upstream/main\nLa mayoría de los pull requests abiertos contra el repositorio electron/electron incluyen cambios al código C/C++ ne la carpeta shell/, el código JavaScript en la carpeta lib/, la documentación en docs/api/ o a los tests en la carpeta spec/.
Por favor asegúrate de correr npm run lint de vez en cuando en cualquier cambio de código para asegurar que estos siguen el estilo de código del proyecto.
Ver estilo de codificación para mas información acerca de la mejor práctica cuando se esta modificando el código en diferentes partes del proyecto.
\nSe le recomienda mantener sus cambios agrupados lógicamente dentro de commits individuales. Muchos contribuyentes encuentras mas fácil el revisar los cambios que son divididos entre multiples commits. No hay límite en el número de commits en un pull request.
\n$ git add my/changed/files\n$ git commit\nTenga en cuenta que multiples commits a menudo colisionan cuando son ejecutadas.
\nUn buen mensaje de commit debe describir que ha cambiado y por qué. El proyecto Electron usa semantic commit messages para racionalizar el proceso de lanzamiento.
\nAntes de que una solicitud de pull pueda ser fusionada, debe tener un título de pull request con un prefijo semántico.
\nEjemplos de mensajes de confirmación con prefijos semánticos:
\nfix: don't overwrite prevent_default if default wasn't preventedfeat: add app.isPackaged() methoddocs: app.isDefaultProtocolClient is now available on LinuxPrefijos usuales:
\nOtras cosas para tener en mente cuando se escribe un mensaje de commit:
\nUn commit que tiene el texto BREAKING CHANGE: al principio de su sección opcional de cuerpo o pie de página introduce un cambio de ruptura en el API (correlacionando con el Major en versionado semántico). Un cambio de ruptura puede ser parte de los commits de cualquier tipo. ejemplo, los tipos fix:, feat: & chore: serían válidos, ademas de cualquier otro tipo.
Vea conventionalcommits.org para más detalles.
\nUna vez hayas asignado tus cambios, es una buena idea el usar git rebase (no git merge) para sincronizar tu trabajo con el repositorio principal.
$ git fetch upstream\n$ git rebase upstream/main\nEsto asegura que tu rama de trabajo tiene los últimos cambios de la rama principal electron/electron.
Las características y reparaciones de un error deben siempre ser dadas con pruebas. Una guía de prueba ha sido proporcionado para facilitar el proceso. Mirar otras pruebas para ver como deberían ser estructuradas también puede ayudar.
\nAntes de enviar tus cambios en una pull request, siempre ejecute el paquete completo de pruebas. Para ejecutar las pruebas:
\n$ npm run test\nAsegúrese de que el linter no reporta ningún inconveniente y que pasa todas pruebas. Por favor no envíe parches que fallan en cualquiera de las verificaciones.
\nSi usted esta actualizando pruebas y quiere correr un simple especificación para probarlas:
\n$ npm run test -match=menu\nLo anterior solo podrá ejecutar módulos específicos coincidentes menu, el cual es útil para cualquiera que esta trabajando en pruebas que podrían de lo contrario estar al final de un ciclo de prueba.
Una vez que tus commits están listos -- ya pasadas las pruebas y el linting -- comienza el proceso de apertura de un pull request haciendo un push de tu rama de trabajo a tu fork en GitHub.
\n$ git push origin my-branch\nDesde dentro de GitHub, abrir una nueva pull request te presentará con una plantilla que debe ser llenada:
\n<!--\nThank you for your pull request. Please provide a description above and review\nthe requirements below.\n\nBug fixes and new features should include tests and possibly benchmarks.\n\nContributors guide: https://github.com/electron/electron/blob/main/CONTRIBUTING.md\n-->\nProbablemente recibirás críticas o peticiones de cambios a tu pull request. ¡Esta es una gran parte del proceso de envío así que no te desanimes! Algunos contribuyentes pueden inmediatamente desistir del pull request. Otros pueden tener comentarios o críticas detalladas. Esto es una parte necesaria del proceso con el fin de evaluar si los cambios son correctos y necesarios.
\nPara realizar cambios a un pull request existente, realiza los cambios a tu rama loca, añade una nuevo commit con esos cambios, y haz a este nuevo commit un push hacia tu fork. GitHub actualizará automáticamente el pull request.
\n$ git add my/changed/files\n$ git commit\n$ git push origin my-branch\nExiste un número de mecanismos mas avanzados para gestionar commits usando git rebase que puede ser usado, pero esta mas allá del alcance de esta guía.
Siéntete libre de postear un comentario en el pull request para avisar a los críticos si estas esperando una respuesta en algo. Si encuentras palabras o acrónimos que parecen desconocidas, consulte este glosario.
\nTodas las pull requests requieren de aprobación por parte de un Propietario de Códico del área que modificaste para aterrizar. Cada vez que un mantenedor revisa un pull request ellos pueden solicitar cambios. Estos pueden ser pequeños, tales como corregir un error tipográfico o puede implicar cambios sustanciales. Se espera que sean útiles, pero puede que a veces no lo sean, especialmente si no incluyen sugerencias concretas sobre cómo cambiarlas.
\nTrata de no estar desmotivado. Si tu sientes que una crítica es injusta, confórmate o busca la entrada de otro contribuyente del proyecto. A menudo ese tipo de comentarios son el resultado de un crítico que no toma el suficiente tiempo para revisar y no son mal intencionados. Estas dificultades a menudo pueden ser resueltas con un poco de paciencia. Dicho esto, se espera que los revisores ofrezcan una crítica útil.
\nCon el fin de ejecutar, un pull request necesita se revisado y aprobado por al menos un Propietario de Código Electron y tarjeta CI. Después de eso, si no hay objeciones de otro contribuyentes, el pull request puede ser combinado.
\n¡Felicitaciones y gracias por tu contribución!
\nCada pull request se prueva en el sistema de Integracion Continua (CI) para confirmar que funciona en plataformas compatibles con Electron.
\nIdealmente, el pull request pasara(\"ser verde\") en todas las plataformas de CI. Esto quiere decir que pasa todas las pruebas y no hay errores linting. Sin embargo, no es infrecuente para la infraestructura de CI el fallar en plataformas específicas o como son llamadas pruebas \"escamosas\" a fallar (\"be red\"). Cada falla de CI debe ser inspeccionada manualmente para determinar la causa.
\nCI inicia automáticamente cuando abres una pull request, pero solo los mantenedores principales puede reiniciar una ejecución CI. Si crees que el CI está dando un falso negativo, pida a un mantenedor que reinicie las pruebas.
", "title": "Pull Requests", "description": "" }, "/docs/tutorial/quick-start": { "locale": "es-ES", "slug": "quick-start", "href": "/docs/tutorial/quick-start", "crowdinFileId": "256237", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/quick-start.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "This guide will step you through the process of creating a barebones Hello World app in Electron, similar to electron/electron-quick-start.
By the end of this tutorial, your app will open a browser window that displays a web page with information about which Chromium, Node.js, and Electron versions are running.
\nTo use Electron, you need to install Node.js. We recommend that you use the latest LTS version available.
\n\nPlease install Node.js using pre-built installers for your platform. You may encounter incompatibility issues with different development tools otherwise.
\n
To check that Node.js was installed correctly, type the following commands in your terminal client:
\nnode -v\nnpm -v\nThe commands should print the versions of Node.js and npm accordingly.
\nNote: Since Electron embeds Node.js into its binary, the version of Node.js running your code is unrelated to the version running on your system.
\nElectron apps follow the same general structure as other Node.js projects. Start by creating a folder and initializing an npm package.
\nmkdir my-electron-app && cd my-electron-app\nnpm init\nThe interactive init command will prompt you to set some fields in your config. There are a few rules to follow for the purposes of this tutorial:
entry point should be main.js.author and description can be any value, but are necessary for app packaging.Your package.json file should look something like this:
{\n \"name\": \"my-electron-app\",\n \"version\": \"1.0.0\",\n \"description\": \"Hello World!\",\n \"main\": \"main.js\",\n \"author\": \"Jane Doe\",\n \"license\": \"MIT\"\n}\nThen, install the electron package into your app's devDependencies.
$ npm install --save-dev electron\n\n\nNote: If you're encountering any issues with installing Electron, please refer to the Advanced Installation guide.
\n
Finally, you want to be able to execute Electron. In the scripts field of your package.json config, add a start command like so:
{\n \"scripts\": {\n \"start\": \"electron .\"\n }\n}\nThis start command will let you open your app in development mode.
npm start\n\n\nNote: This script tells Electron to run on your project's root folder. At this stage, your app will immediately throw an error telling you that it cannot find an app to run.
\n
The entry point of any Electron application is its main script. This script controls the main process, which runs in a full Node.js environment and is responsible for controlling your app's lifecycle, displaying native interfaces, performing privileged operations, and managing renderer processes (more on that later).
During execution, Electron will look for this script in the main field of the app's package.json config, which you should have configured during the app scaffolding step.
To initialize the main script, create an empty file named main.js in the root folder of your project.
\n\nNote: If you run the
\nstartscript again at this point, your app will no longer throw any errors! However, it won't do anything yet because we haven't added any code intomain.js.
Before we can create a window for our application, we need to create the content that will be loaded into it. In Electron, each window displays web contents that can be loaded from either from a local HTML file or a remote URL.
\nFor this tutorial, you will be doing the former. Create an index.html file in the root folder of your project:
\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n </body>\n</html>\n\n\nNote: Looking at this HTML document, you can observe that the version numbers are missing from the body text. We'll manually insert them later using JavaScript.
\n
Now that you have a web page, load it into an application window. To do so, you'll need two Electron modules:
\napp module, which controls your application's event lifecycle.BrowserWindow module, which creates and manages application windows.Because the main process runs Node.js, you can import these as CommonJS modules at the top of your file:
\nconst { app, BrowserWindow } = require('electron')\nThen, add a createWindow() function that loads index.html into a new BrowserWindow instance.
function createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\nNext, call this createWindow() function to open your window.
In Electron, browser windows can only be created after the app module's ready event is fired. You can wait for this event by using the app.whenReady() API. Call createWindow() after whenReady() resolves its Promise.
app.whenReady().then(() => {\n createWindow()\n})\n\n\nNote: At this point, your Electron application should successfully open a window that displays your web page!
\n
Although you can now open a browser window, you'll need some additional boilerplate code to make it feel more native to each platform. Application windows behave differently on each OS, and Electron puts the responsibility on developers to implement these conventions in their app.
\nIn general, you can use the process global's platform attribute to run code specifically for certain operating systems.
On Windows and Linux, exiting all windows generally quits an application entirely.
\nTo implement this, listen for the app module's 'window-all-closed' event, and call app.quit() if the user is not on macOS (darwin).
app.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nWhereas Linux and Windows apps quit when they have no windows open, macOS apps generally continue running even without any windows open, and activating the app when no windows are available should open a new one.
\nTo implement this feature, listen for the app module's activate event, and call your existing createWindow() method if no browser windows are open.
Because windows cannot be created before the ready event, you should only listen for activate events after your app is initialized. Do this by attaching your event listener from within your existing whenReady() callback.
app.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n\nNote: At this point, your window controls should be fully functional!
\n
Now, the last thing to do is print out the version numbers for Electron and its dependencies onto your web page.
\nAccessing this information is trivial to do in the main process through Node's global process object. However, you can't just edit the DOM from the main process because it has no access to the renderer's document context. They're in entirely different processes!
\n\nNote: If you need a more in-depth look at Electron processes, see the Process Model document.
\n
This is where attaching a preload script to your renderer comes in handy. A preload script runs before the renderer process is loaded, and has access to both renderer globals (e.g. window and document) and a Node.js environment.
Create a new script named preload.js as such:
window.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\nThe above code accesses the Node.js process.versions object and runs a basic replaceText helper function to insert the version numbers into the HTML document.
To attach this script to your renderer process, pass in the path to your preload script to the webPreferences.preload option in your existing BrowserWindow constructor.
// include the Node.js 'path' module at the top of your file\nconst path = require('path')\n\n// modify your existing createWindow() function\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n}\n// ...\nThere are two Node.js concepts that are used here:
\n__dirname string points to the path of the currently executing script (in this case, your project's root folder).path.join API joins multiple path segments together, creating a combined path string that works across all platforms.We use a path relative to the currently executing JavaScript file so that your relative path will work in both development and packaged mode.
\nAt this point, you might be wondering how to add more functionality to your application.
\nFor any interactions with your web contents, you want to add scripts to your renderer process. Because the renderer runs in a normal web environment, you can add a <script> tag right before your index.html file's closing </body> tag to include any arbitrary scripts you want:
<script src=\"./renderer.js\"></script>\nThe code contained in renderer.js can then use the same JavaScript APIs and tooling you use for typical front-end development, such as using webpack to bundle and minify your code or React to manage your user interfaces.
After following the above steps, you should have a fully functional Electron application that looks like this:
\n
The full code is available below:
\n// main.js\n\n// Modules to control application life and create native browser window\nconst { app, BrowserWindow } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n // Create the browser window.\n const mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n // and load the index.html of the app.\n mainWindow.loadFile('index.html')\n\n // Open the DevTools.\n // mainWindow.webContents.openDevTools()\n}\n\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// Algunas APIs pueden solamente ser usadas despues de que este evento ocurra.\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n // On macOS it's common to re-create a window in the app when the\n // dock icon is clicked and there are no other windows open.\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\n\n// In this file you can include the rest of your app's specific main process\n// code. Tu también puedes ponerlos en archivos separados y requerirlos aquí.\n// preload.js\n\n// All of the Node.js APIs are available in the preload process.\n// It has the same sandbox as a Chrome extension.\nwindow.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\n<!--index.html-->\n\n\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n\n <!-- You can also require other files to run in this process -->\n <script src=\"./renderer.js\"></script>\n </body>\n</html>\nTo summarize all the steps we've done:
\nWe bootstrapped a Node.js application and added Electron as a dependency.
\nWe created a main.js script that runs our main process, which controls our app\nand runs in a Node.js environment. In this script, we used Electron's app and\nBrowserWindow modules to create a browser window that displays web content\nin a separate process (the renderer).
In order to access certain Node.js functionality in the renderer, we attached\na preload script to our BrowserWindow constructor.
The fastest way to distribute your newly created app is using\nElectron Forge.
\nAdd Electron Forge as a development dependency of your app, and use its import command to set up\nForge's scaffolding:
```sh npm2yarn\nnpm install --save-dev @electron-forge/cli\nnpx electron-forge import\n\n✔ Checking your system\n✔ Initializing Git Repository\n✔ Writing modified package.json file\n✔ Installing dependencies\n✔ Writing modified package.json file\n✔ Fixing .gitignore\n\nWe have ATTEMPTED to convert your app to be in a format that electron-forge understands.\n\nThanks for using \"electron-forge\"!!!\n```\nCreate a distributable using Forge's make command:
npm run make\n\n> my-electron-app@1.0.0 make /my-electron-app\n> electron-forge make\n\n✔ Checking your system\n✔ Resolving Forge Config\nWe need to package your application before we can make it\n✔ Preparing to Package Application for arch: x64\n✔ Preparing native dependencies\n✔ Packaging Application\nMaking for the following targets: zip\n✔ Making for target: zip - On platform: darwin - For arch: x64\nElectron Forge creates the out folder where your package will be located:
// Example for macOS\nout/\n├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip\n├── ...\n└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app\nPor favor, asegúrese de utilizar los documentos que correspondan con la versión de Electron que esta buscando. El número de versión debe estar incluido en la URL de la página. De no ser así, probablemente está utilizando la documentación de una rama de desarrollo, la cual puede contener cambios en la API que no sean compatibles con su versión de Electron. Para ver la documentación de las versiones pasadas desde GitHub usted puede navegar usando las etiquetas al abrir el cuadro de selección \"Switch branches/tags\" y seleccionar la versión que coincida con la suya.
\nHay preguntas que se hacen bastante a menudo. Comprueba esto antes de crear un tema:
\n\nEstos tutoriales individuales amplían los temas tratados en la guía anterior.
\nEstas guías están pensadas para gente que trabaja en el proyecto Electron. Para guías sobre el desarrollo de aplicaciones Electron, visita /docs/README.md.
\nWindows y macOS proveen acceso a una lista de documentos recientes abierto por la aplicación a través de JumpList or dock menu, respectivamente.
\nJumpList:
\n
Menú de Aplicaciones:
\n
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\n\nconst fileName = 'recently-used.md'\nfs.writeFile(fileName, 'Lorem Ipsum', () => {\n app.addRecentDocument(path.join(__dirname, fileName))\n})\n\napp.whenReady().then(createWindow)\n\napp.on('window-all-closed', () => {\n app.clearRecentDocuments()\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nTo add a file to recent documents, use the app.addRecentDocument API.
\nAfter launching the Electron application, right click the application icon. In this guide, the item is a Markdown file located in the root of the project. You should see recently-used.md added to the list of recent files:
To clear the list of recent documents, use the app.clearRecentDocuments API. In this guide, the list of documents is cleared once all windows have been closed.
\nTo use this feature on Windows, your application has to be registered as a handler of the file type of the document, otherwise the file won't appear in JumpList even after you have added it. You can find everything on registering your application in Application Registration.
\nCuando un usuario hace clic en un archivo de JumpList, una nueva instancia de su aplicación se iniciará con la ruta del archivo agregado como un argumento de línea de comando.
\nYou can add menu items to access and clear recent documents by adding the following code snippet to your menu template:
\n{\n \"submenu\":[\n {\n \"label\":\"Open Recent\",\n \"role\":\"recentdocuments\",\n \"submenu\":[\n {\n \"label\":\"Clear Recent\",\n \"role\":\"clearrecentdocuments\"\n }\n ]\n }\n ]\n}\nMake sure the application menu is added after the 'ready' event and not before, or the menu item will be disabled:
const { app, Menu } = require('electron')\n\nconst template = [\n // Menu template here\n]\nconst menu = Menu.buildFromTemplate(template)\n\napp.whenReady().then(() => {\n Menu.setApplicationMenu(menu)\n})\n
Cuando se solicita un archivo del menú de documentos recientes, el evento archivo abierto de aplicación se emitirá para él.
x Number - The x coordinate of the origin of the rectangle (must be an integer).y Number - The y coordinate of the origin of the rectangle (must be an integer).width Number - The width of the rectangle (must be an integer).height Number - The height of the rectangle (must be an integer).url String - HTTP Referrer URL.policy String - Can be default, unsafe-url, no-referrer-when-downgrade, no-referrer, origin, strict-origin-when-cross-origin, same-origin or strict-origin. See the Referrer-Policy spec for more details on the meaning of these values.قراءة-تقييم-طباعة-حلقة (REPL) هي بيئة برمجة كمبيوتر تفاعلية بسيطة تتطلب مستخدمًا واحدًا المدخلات (أي التعبيرات الفردية) ، وتقييمها ، وإرجاع النتيجة إلى المستخدم.
\nElectron expone el módulo Node.js repl a través de la bandera de CLI --interactiva. Assuming you have electron installed as a local project dependency, you should be able to access the REPL with the following command:
./node_modules/.bin/electron --interactive\nNota: electron --interactive no está disponible para Windows (consulta electron/electron#5776 para más detalles).
You can use the DevTools Console tab to get a REPL for any renderer process. Para obtener más información, consulta la documentación de Chrome.
", "title": "REPL", "description": "" }, "/docs/tutorial/represented-file": { "locale": "es-ES", "slug": "represented-file", "href": "/docs/tutorial/represented-file", "crowdinFileId": "256243", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/represented-file.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "En macOS, puede establecer un archivo representado para cualquier ventana en tu aplicación. El icono del archivo representado será mostrado en la barra de título, y cuando los usuarios Command-Click o Control-Click en una ventana emergente con una ruta al archivo será mostrada.
\n\nNOTA: La captura de pantalla anterior es un ejemplo donde esta característica es usada para indicar el archivo abierto actualmente en el editor de texto Atom.
\n
También puede establecer el estado editado de una ventana para que el ícono del archivo pueda indicar si el documento en esta ventana ha sido modificado.
\nPara configurar el archivo representado de la ventana, puede utilizarse las APIs BrowserWindow.setRepresentedFilename y BrowserWindow.setDocumentEdited APIs.
\nconst { app, BrowserWindow } = require('electron')\nconst os = require('os');\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n}\n\napp.whenReady().then(() => {\n const win = new BrowserWindow()\n\n win.setRepresentedFilename(os.homedir())\n win.setDocumentEdited(true)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nDespués de lanzar la aplicación Electron, pulse en el título con la tecla Command o Control presionada. Deberías ver una ventana emergente con el archivo representado en la parte superior. En esta guía, este es el directorio principal del usuario actual:
\n\nAllows access to simple encryption and decryption of strings for storage on the local machine.
\n
Proceso: principal</0>
\nThis module protects data stored on disk from being accessed by other applications or users with full disk access.
\nNote that on Mac, access to the system Keychain is required and these calls can block the current thread to collect user input. The same is true for Linux, if a password management tool is available.
\nEl módulo safeStorage tiene los siguientes métodos:
safeStorage.isEncryptionAvailable()Returns Boolean - Whether encryption is available.
On Linux, returns true if the secret key is available. On MacOS, returns true if Keychain is available. On Windows, returns true with no other preconditions.
\nsafeStorage.encryptString(plainText)plainText StringReturns Buffer - An array of bytes representing the encrypted string.
This function will throw an error if encryption fails.
\nsafeStorage.decryptString(encrypted)encrypted BufferReturns String - the decrypted string. Decrypts the encrypted buffer obtained with safeStorage.encryptString back into a string.
This function will throw an error if decryption fails.
", "title": "safeStorage", "description": "Allows access to simple encryption and decryption of strings for storage on the local machine." }, "/docs/tutorial/sandbox": { "locale": "es-ES", "slug": "sandbox", "href": "/docs/tutorial/sandbox", "crowdinFileId": "256245", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/sandbox.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "One key security feature in Chromium is that processes can be executed within a sandbox. The sandbox limits the harm that malicious code can cause by limiting access to most system resources — sandboxed processes can only freely use CPU cycles and memory. In order to perform operations requiring additional privilege, sandboxed processes use dedicated communication channels to delegate tasks to more privileged processes.
\nIn Chromium, sandboxing is applied to most processes other than the main process. This includes renderer processes, as well as utility processes such as the audio service, the GPU service and the network service.
\nSee Chromium's Sandbox design document for more information.
\nElectron comes with a mixed sandbox environment, meaning sandboxed processes can run alongside privileged ones. By default, renderer processes are not sandboxed, but utility processes are. Note that as in Chromium, the main (browser) process is privileged and cannot be sandboxed.
\nHistorically, this mixed sandbox approach was established because having Node.js available in the renderer is an extremely powerful tool for app developers. Unfortunately, this feature is also an equally massive security vulnerability.
\nTheoretically, unsandboxed renderers are not a problem for desktop applications that only display trusted code, but they make Electron less secure than Chromium for displaying untrusted web content. However, even purportedly trusted code may be dangerous — there are countless attack vectors that malicious actors can use, from cross-site scripting to content injection to man-in-the-middle attacks on remotely loaded websites, just to name a few. For this reason, we recommend enabling renderer sandboxing for the vast majority of cases under an abundance of caution.
\n\nNote that there is an active discussion in the issue tracker to enable renderer sandboxing by default. See #28466) for details.
\nSandboxed processes in Electron behave mostly in the same way as Chromium's do, but Electron has a few additional concepts to consider because it interfaces with Node.js.
\nWhen renderer processes in Electron are sandboxed, they behave in the same way as a regular Chrome renderer would. A sandboxed renderer won't have a Node.js environment initialized.
\n\nTherefore, when the sandbox is enabled, renderer processes can only perform privileged tasks (such as interacting with the filesystem, making changes to the system, or spawning subprocesses) by delegating these tasks to the main process via inter-process communication (IPC).
\nIn order to allow renderer processes to communicate with the main process, preload scripts attached to sandboxed renderers will still have a polyfilled subset of Node.js APIs available. A require function similar to Node's require module is exposed, but can only import a subset of Electron and Node's built-in modules:
electron (only renderer process modules)eventscontadoresurlIn addition, the preload script also polyfills certain Node.js primitives as globals:
\nBufferprocessclearImmediatesetImmediateBecause the require function is a polyfill with limited functionality, you will not be able to use CommonJS modules to separate your preload script into multiple files. If you need to split your preload code, use a bundler such as webpack or Parcel.
Tenga en cuenta que debido a que el entorno presentado al script preload es sustancialmente más privilegiado que el de un renderizador con espacio de prueba, todavía es posible filtrar API privilegiadas a código no confiable ejecutándose en el proceso de renderizado a menos que contextIsolation esté habilitado.
In Electron, renderer sandboxing can be enabled on a per-process basis with the sandbox: true preference in the BrowserWindow constructor.
// main.js\napp.whenReady().then(() => {\n const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n })\n win.loadURL('https://google.com')\n})\nIf you want to force sandboxing for all renderers, you can also use the app.enableSandbox API. Note that this API has to be called before the app's ready event.
// main.js\napp.enableSandbox()\napp.whenReady().then(() => {\n // no need to pass `sandbox: true` since `app.enableSandbox()` was called.\n const win = new BrowserWindow()\n win.loadURL('https://google.com')\n})\nYou can also disable Chromium's sandbox entirely with the --no-sandbox CLI flag, which will disable the sandbox for all processes (including utility processes). We highly recommend that you only use this flag for testing purposes, and never in production.
Note that the sandbox: true option will still disable the renderer's Node.js environment.
Rendering untrusted content in Electron is still somewhat uncharted territory, though some apps are finding success (e.g. Beaker Browser). Our goal is to get as close to Chrome as we can in terms of the security of sandboxed content, but ultimately we will always be behind due to a few fundamental issues:
\nWhile we make our best effort to backport Chromium security fixes to older versions of Electron, we do not make a guarantee that every fix will be backported. Your best chance at staying secure is to be on the latest stable version of Electron.
", "title": "Proceso Sandboxing", "description": "" }, "/docs/api/screen": { "locale": "es-ES", "slug": "screen", "href": "/docs/api/screen", "crowdinFileId": "256361", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/screen.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRecuperar información acerca del tamaño de la pantalla, posiciones del cursor, posiciones, etc.
\n
Proceso: principal</0>
\nEste módulo no puede ser usado hasta que el evento ready del módulo app es emitido.
screen es un EventEmitter.
Nota: En el renderer / DevTools, window.screen propiedad reservada DOM, así que escribir let { screen } = require('electron') no funcionará.
Un ejemplo de crear una ventana que llene toda la pantalla:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\napp.whenReady().then(() => {\n const { width, height } = screen.getPrimaryDisplay().workAreaSize\n win = new BrowserWindow({ width, height })\n win.loadURL('https://github.com')\n})\nOtro ejemplo de crear una ventana el display externo es:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n const displays = screen.getAllDisplays()\n const externalDisplay = displays.find((display) => {\n return display.bounds.x !== 0 || display.bounds.y !== 0\n })\n\n if (externalDisplay) {\n win = new BrowserWindow({\n x: externalDisplay.bounds.x + 50,\n y: externalDisplay.bounds.y + 50\n })\n win.loadURL('https://github.com')\n }\n})\nEl módulo screen emite los siguientes eventos:
Devuelve:
\neventnewDisplay DisplayEmitido cuando newDisplay ha sido añadido.
Devuelve:
\neventoldDisplay DisplayEmitido cuando oldDisplay ha sido eliminado.
Devuelve:
\neventdisplay DisplaychangedMetrics Cadena[]Emitido cuando o más métricos cambian en un display. El changedMetrics es un arreglo de cadenas que describen los cambios. Posibles cambios son bounds, workArea, scaleFactor y rotation.
El módulo screen tiene los siguientes métodos:
screen.getCursorScreenPoint()Devuelve Point
La actual y absoluta posición del cursor del mouse.
\nNota: El valor devuelto es un punto DIP, no una punto físico de la pantalla.
\nscreen.getPrimaryDisplay()Devuelve Display - La muestra primaria.
screen.getAllDisplays()Devuelve Display[] - Un arreglo de muestras que son actualmente disponibles.
screen.getDisplayNearestPoint(point)point PointDevuelve Display - La muestra más cerca del punto especificado.
screen.getDisplayMatching(rect)rect RectangleDevuelve Display - La muestra que es más cercana intersecta a las bandas dadas.
screen.screenToDipPoint(point) Windowspoint PointDevuelve Point
Convierte un punto físico en la pantalla a un punto DIP de la pantalla. La escala DPI se realiza en relación a la pantalla que contiene el punto físico.
\nscreen.dipToScreenPoint(point) Windowspoint PointDevuelve Point
Convierte un punto DIP de pantalla a un punto físico de la pantalla. La escala DPI se realiza en relación a la pantalla que contiene el punto DIP.
\nscreen.screenToDipRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleDevuelve Rectangle
Convierte una rect física de pantalla a una rect DIP de pantalla. La escala DPI se realiza en relación a la pantalla más cercana a window. Si window es nulo, el escalamiento se realizará a la pantalla mas cercana a rect.
screen.dipToScreenRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleDevuelve Rectangle
Convierte una pantalla DIP rect a una rect física de pantalla. La escala DPI se realiza en relación a la pantalla más cercana a window. Si window es nulo, el escalamiento se realizará a la pantalla mas cercana a rect.
label String (optional) - The text to appear in this item.icon NativeImage (optional) - The image to appear in this item.Como desarrolladores web, usualmente disfrutamos la seguridad fuerte de la red del buscador - los riesgos asociados con el código que escribimos son relativamente bajos. A nuestras páginas web se les concede poderes limitados en un sandbox, y confiamos en que nuestros usuarios disfrutan un buscador construido por un gran equipo de ingenieros que es capaz de responder rápidamente a recientes amenazas de seguridad descubiertas.
\nCuando se trabaje con Electron, es importante entender que Electron no es un navegador web. Te permite construir aplicaciones de escritorio llenas de utilidades con tecnologías web familiares, pero tu código tiene mucho más poder. JavaScript puede acceder a los archivos del sistema, actividades del usuario y más. Esto permite que construyas aplicaciones nativas de alta calidad, pero los riesgos inherentes de seguridad escalan con el poder adicional concedido a tu código.
\nCon eso en mente, ten en cuenta que mostrar contenido arbitrario proveniente de fuentes poco confiables viene con un riesgo severo que Electron no está diseñado para manejar. De hecho, las aplicaciones de electron más populares (Atom, Slack, Visual Studio Code, etc) muestran contenido local primero (o confiable, asegurado contenido remoto sin integración nodal) - si tu aplicación ejecuta código de una fuente online es tu responsabilidad asegurar que el código no es malicioso.
\nPara información sobre cómo revelar las vulnerabilidad de Electrón dirigirse a SECURITY.md
\nElectron keeps up to date with alternating Chromium releases. For more information, see the Electron Release Cadence blog post.
\nEs importante recordar que la seguridad de tu aplicación Electron es el resultado de la seguridad general de la base de framework (Chromium, Node.js), Electron mismo, todas las dependencias NPM y tu código. Por tanto, es tu responsabilidad seguir algunas importantes mejores prácticas:
\nMantenga su aplicación actualizada con la última versión liberada de Electron. Cuando libere su producto, también está compartiendo un conjunto compuesto de Electron, librerías compartidas de Chromium y Node.js. Vulnerabilidades afectando a estos componentes pueden impactar en la seguridad de su aplicación. Actualizando Electron a la última versión, asegura que las vulnerabilidades críticas (tales como nodeIntegration bypasses) ya estén reparadas y no puedan ser explotadas en su aplicación. Para más informacón, vea \"Use a current version of Electron\".
\nEvalue sus dependencias.Mientras NPM provee más de medio millón de paquetes reusables, es su responsabilidad la elección de librerías confiables de terceros. Si utiliza librerías desactualizadas afectadas por vulnerabilidades conocidas o basado en código escasamente mantenido, la seguridad de su aplicación puede estar en peligro.
\nAdopte prácticas de programación segura. La primera línea de defensa de su aplicación es su propio código. Vulnerabilidades usuales, tales como Cross-Site Scripting (XSS), tienen un alto impacto en la seguridad en las aplicaciones Electron así es altamente recomendable adoptar políticas confiables de buenas prácticas en el desarrollo de software y realizar pruebas de seguridad.
\nUn problema de seguridad existe siempre que recibes código de un lugar no confiable (e.g. un servidor remoto) y lo ejecutas localmente. Como un ejemplo, considera una página web remota siendo mostrada dentro de un default BrowserWindow. Si un atacante de algún modo se las arregla para cambiar dicho contenido (bien sea atacando la fuente directamente, o interviniendo entre su aplicación y el destino real), será capaz de ejecutar códigos nativos en la máquina del usuario.
\n\n⚠️ bajo ninguna circunstancia deberías cargar y ejecutar código remoto con la integración Node.js activada. En vez de eso, usa solo archivos locales (empaquetados juntos con tu aplicación) para ejecutar el código Node.js. Para mostrar contenido remoto, use la etiqueta
\n<webview>oBrowserView, asegúrese de deshabilitar elnodeIntegrationy habilitarcontextIsolation.
Desde Electron 2.0, los desarrolladores verán advertencias y recomendaciones impresas en la consola de desarrolladores. Estos solo se muestran cuando el nombre del binario es Electron, indicando que un desarrollador está mirando la consola.
\nUsted puede activar o desactivar estas advertencias forzosamente configurando ELECTRON_ENABLE_SECURITY_WARNINGS o ELECTRON_DISABLE_SECURITY_WARNINGS ya sea en process.env o en el objeto window.
Al menos debes seguir los siguientes pasos para mejorar la seguridad de su aplicación:
\nses.setPermissionRequestHandler() en todas las sesiones que cargan contenido remotowebSecurityContent-Security-Policy y usa reglas estrictas (i.e. script-src 'self')allowRunningInsecureContent a trueenableBlinkFeatures<webview>: No useallowpopups<webview>: Verificar opciones y parámetrosopenExternal con contenido no confiablePara automatizar la detección de configuraciones erróneas y de modelos inseguros, es posible usar electronegativity. Para detalles adicionales sobre potenciales debilidades y errores en la implementación durante el desarrollo de aplicaciones usando Electron, consulte guía para desarrolladores y auditores
\nCualquier recurso no incluido con tu aplicación debería ser cargado usando un protocolo de seguridad como HTTPS. En otras palabras, no uses protocolos inseguros como HTTP. De manera similar, recomendamos el uso de WSS antes de WS, FTPS antes de FTP, y así.
HTTPS tiene tres beneficios principales:
1) Autentica el servidor remoto, asegurando que tu aplicación conecte al anfitrión correcto en vez de un falsificador. 2) Asegura integridad de data, afirmando que la data no fue modificada mientras estaba en tránsito entre tu aplicación y el anfitrión. 3) Encripta el tráfico entre tu usuario y el anfitrión destinatario, haciéndolo más difícil escuchar a escondidas las información establecida entre tu aplicación y el anfitrión.
\n// Bad\nbrowserWindow.loadURL('http://example.com')\n\n// Good\nbrowserWindow.loadURL('https://example.com')\n<!-- Bad -->\n<script crossorigin src=\"http://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"http://example.com/style.css\">\n\n<!-- Good -->\n<script crossorigin src=\"https://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"https://example.com/style.css\">\nEsta recomendación es el comportamiento por defecto desde Electron 5.0.0.
\nEs primordial que no active la integración Node.js en ningún renderizador (BrowserWindow, BrowserView, o <webview>) que carga contenido remote. La meta es limitar los poderes que concedes al contenido remoto, aunque lo hace dramáticamente más difícil para un atacante lastimar a tus usuarios, ellos deberían ganar la habilidad de ejecutar JavaScript en tu página web.
Luego de esto, puedes conceder permisos adicionales para anfitriones específicos. For example, if you are opening a BrowserWindow pointed at https://example.com/, you can give that website exactly the abilities it needs, but no more.
Un ataque cross-site-scripting (XSS) es más peligroso si un atacante puede altar fuera del proceso de renderizado y ejecutar el código en la computadora del usuario. Ataques cross-site-scripting son muy comunes - y durante un problema, su poder es usualmente limitado a molestar a la página en dónde los están ejecutando. Desactivar la integración Node.js ayuda a prevenir un XSS de ser escalado en un llamado ataque de \"Ejecución de Código Remoto\".
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n nodeIntegration: true,\n nodeIntegrationInWorker: true\n }\n})\n\nmainWindow.loadURL('https://example.com')\n// Good\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n preload: path.join(app.getAppPath(), 'preload.js')\n }\n})\n\nmainWindow.loadURL('https://example.com')\n<!-- Incorrecto -->\n<webview nodeIntegration src=\"page.html\"></webview>\n\n<!-- Correcto -->\n<webview src=\"page.html\"></webview>\nCuando desactivas la integración Node.js, todavía puedes exponer APIs a tu página web que consume módulos Node.js o características. Guiones precargados continúan teniendo acceso a require y otras características de Node.js, permitiendo que los desarrolladores expongan un API personalizado para cargar contenido de manera remota.
En el siguiente ejemplo de un guión pre cargado, la página web cargada más adelante tendrá acceso a el método window.readConfig(), pero ninguna característica de Node.js.
const { readFileSync } = require('fs')\n\nwindow.readConfig = function () {\n const data = readFileSync('./config.json')\n return data\n}\nContext isolation es un ajuste de Electron que permite a los desarrolladores ejecutar códigos en guiones de pre carga y en APIs de Electron en un contexto dedicado de JavaScript. En práctica, eso significa que los objetos globales como Array.prototype.push o JSON.parse no puede ser modificado por guiones por guiones ejecutándose en el proceso de renderizado.
Electron usa la misma tecnología que los Content Scripts de Chromium para activar este comportamiento.
\nEven when nodeIntegration: false is used, to truly enforce strong isolation and prevent the use of Node primitives contextIsolation must also be used.
For more information on what contextIsolation is and how to enable it please see our dedicated Context Isolation document.
Sandboxing is a Chromium feature that uses the operating system to significantly limit what renderer processes have access to. You should enable the sandbox in all renderers. Loading, reading or processing any untrusted content in an unsandboxed process, including the main process, is not advised.
\nWhen creating a window, pass the sandbox: true option in webPreferences:
const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n})\nTu puedes haber visto pedidos de permiso mientras usas Chrome: Ellos avisan lo que sea que la página intente usar como una característica que el usuario tiene que aprobar manualmente (como notificaciones).
\nLa API está basada en los Chromium permissions API e implementa el mismo tipo de permisos.
\nPor defecto, Electron aprobará automáticamente todos los pedidos de permiso a menos que el desarrollador haya configurado manualmente un comerciante personalizado. Aunque es un sólido ajuste automático, los desarrolladores conscientes de la seguridad pueden querer asumir lo contrario.
\nconst { session } = require('electron')\n\nsession\n .fromPartition('some-partition')\n .setPermissionRequestHandler((webContents, permission, callback) => {\n const url = webContents.getURL()\n\n if (permission === 'notifications') {\n // Approves the permissions request\n callback(true)\n }\n\n // Verify URL\n if (!url.startsWith('https://example.com/')) {\n // Denies the permissions request\n return callback(false)\n }\n })\nLa recomendación por defecto es Electrón
\nPuede que haya adivinado que deshabilitando la propiedad webSecurity en un render process (BrowserWindow, BrowserView, or <webview>) desactiva características de seguridad cruciales.
No deshabilite webSecurity en aplicaciones de producción.
Desactivar webSecurity deshabilitará la política de mismo-origen y establecer la propiedad allowRunningInsecureContent a true. En otras palabras, permite la ejecución de código inseguro desde diferentes dominios.
// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n webSecurity: false\n }\n})\n// Good\nconst mainWindow = new BrowserWindow()\n<!-- Bad -->\n<webview disablewebsecurity src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nUn Contenido de Política de Seguridad (CSP) es una capa adicional de protección contra los ataques cross-site-scripting attacks y ataques de inyecciones de data. Recomendamos que ellos estén activados por cualquier página web cargada dentro de Electron.
\nCSP permite que el servidor dando contenido pueda restringir y controlar los recursos que Electron puede cargar para esa página web dada. https://example.com debería estar permitido para guiones de pre carga de los orígenes que definiste mientras que los guiones de https://evil.attacker.com no debería tener permitido ejecutarse. Definir un CSP es una manera fácil de mejorar la seguridad de tus aplicaciones.
El siguiente CSP permitirá que Electron ejecute guiones desde la página web actual y desde apis.example.com.
// Bad\nContent-Security-Policy: '*'\n\n// Good\nContent-Security-Policy: script-src 'self' https://apis.example.com\nElectron respeta el Content-Security-Policy HTTP header que puede ser establecido usando el manejador webRequest.onHeadersReceived de Electron:
const { session } = require('electron')\n\nsession.defaultSession.webRequest.onHeadersReceived((details, callback) => {\n callback({\n responseHeaders: {\n ...details.responseHeaders,\n 'Content-Security-Policy': ['default-src \\'none\\'']\n }\n })\n})\nEl mecanismo de entrega preferido de CSP es una cabecera HTTP, sin embargo no es posible usar este método al cargar un recurso usando el protocolo file://. Puede ser útil en algunos casos, como usar el protocolo file://, para establecer una política en un página directamente en el markup usando un tag <meta>:
<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'\">\nallowRunningInsecureContent a trueLa recomendación por defecto es Electrón
\nPor defecto, Electron no permitirá sitios webs cargados sobre HTTPS para cargar y ejecutar scripts, CSS, o plugins desde orígenes inseguros (HTTP). Establecer la propiedad allowRunningInsecureContent a true deshabilita esa protección.
Descargar la inicial HTML de un sitio web mediante HTTPS e intentar descargar recursos subsecuentes mediante HTTP es también conocido como \"contenido mixto\".
Cargando contenido sobre HTTPS se asegura la autenticidad y la integridad de los recursos cargados mientras se cifra el trafico en si mismo. Ver la sección en only displaying secure content para más detalles.
// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n allowRunningInsecureContent: true\n }\n})\n// Good\nconst mainWindow = new BrowserWindow({})\nLa recomendación por defecto es Electrón
\nUsuarios avanzados de Electron pueden habilitar las características experimentales de Chromium usando la propiedad experimentalFeatures.
Experimental features are, as the name suggests, experimental and have not been enabled for all Chromium users. Furthermore, their impact on Electron as a whole has likely not been tested.
\nCasos de uso legítimo existen, pero excepto que usted sepa lo que está haciendo, usted no debería habilitar esta propiedad.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n experimentalFeatures: true\n }\n})\n// Good\nconst mainWindow = new BrowserWindow({})\nenableBlinkFeaturesLa recomendación por defecto es Electrón
\nBlink es el nombre del motor de renderizado detrás de Chromium. Como con la propiedad experimentalFeatures, la propiedad enableBlinkFeatures permite a los desarrolladores habilitar características que han sido deshabilitada por defecto.
En general, probablemente hay buenas razones si una función no fue habilitada por defecto. Casos de uso legítimo para habilitar funciones especificas existen. Como un desarrollador, usted debería saber exactamente por qué usted necesita habilitar una función, cuales son las ramificaciones, y como impacta las seguridad de su aplicación. Usted no debería habilitar funciones de forma especulativa bajo ninguna circunstancia.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n enableBlinkFeatures: 'ExecCommandInJavaScript'\n }\n})\n// Good\nconst mainWindow = new BrowserWindow()\nallowpopupsLa recomendación por defecto es Electrón
\nSi estas usando <webview>, puede que necesites las paginas y los scripts cargados en tu tag <webview> par abrir nuevas ventanas. El atributo allowpopups les permite crear nuevas BrowserWindows usando el método window.open(). tags <webview> de otra manera no se permite crear nuevas ventanas.
Si usted no necesita ventanas emergentes, le conviene no permitir la creación de nuevos BrowserWindows por defecto. Esto sigue el principio de acceso de mínimamente requerido: No permita que un sitio web cree nuevas ventanas excepto usted sepa que se necesita esa función.
<!-- Bad -->\n<webview allowpopups src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nUn WebView creado en un proceso de renderizado que no contenga integración habilitada de Node.js no será capaz de habilitar integración por sí mismo. Sin embargo, a WebView siempre creará un proco de renderizado independiente con su propio webPreferences.
Es una buena ida controlar la creación de nuevas etiquetas <webview> desde el proceso principal y verificar que su webPreferences no deshabilitan características de seguridad.
Puesto que <webview> vive en el DOM, ellos pueden ser creados por un script corriendo en tu sitio web incluso si la integración con Node.js está descativada.
Electron habilita a desarrolladores a inhabilitar varias funciones de seguridad que controlan un proceso de renderizado. En la mayoría de los casos, los desarrolladores no necesitan desactivar ninguna de esas características - y por lo tanto no deberías permitir diferentes configuraciones para las etiquetas <webview> recién creados.
Antes que la etiqueta <webview> sea adjuntada, Electron va a disparar el evento will-attach-webview en el webContents hosting. Use el evento para evitar la creación de webViews con posibles opciones inseguras.
app.on('web-contents-created', (event, contents) => {\n contents.on('will-attach-webview', (event, webPreferences, params) => {\n // Strip away preload scripts if unused or verify their location is legitimate\n delete webPreferences.preload\n delete webPreferences.preloadURL\n\n // Disable Node.js integration\n webPreferences.nodeIntegration = false\n\n // Verify URL being loaded\n if (!params.src.startsWith('https://example.com/')) {\n event.preventDefault()\n }\n })\n})\nUna vez más, esta lista simplemente minimiza el riesgo, no lo elimina. If your goal is to display a website, a browser will be a more secure option.
\nSi tu aplicación no tiene la necesidad de navegar o sólo necesita navegar a páginas conocidas, es una buena idea limitar la navegación directamente a ese alcance conocido, inhabilitando cualquier otro tipo de navegación.
\nLa navegación es un vector de ataque común. Si un atacante puede convencer a su aplicación para que navegue lejos de su página actual, posiblemente puede forzar a tu aplicación a abrir sitios web en Internet. Incluso si tu webContents están configurados para ser más seguros (como tener nodeIntegration deshabilitado o contextIsolation habilitado), conseguir que tu aplicación abra un sitio web aleatorio hará que el trabajo de explotar tu aplicación sea mucho mas fácil.
Un patrón común de ataque es que el atacante convence a los usuarios de tu aplicación a interactuar con la aplicación de tal manera que navegue a una de las páginas del atacante. Esto usualmente se hace vía links, plugins u otro contenido generado por el usuario.
\nSi tu aplicación no tiene necesidad de navegación, puedes llamar a event.preventDefault() en un manejador will-navigate. Si sabes a que páginas tu aplicación puede navegar, revisa la URL en el manejador de evento y solo deja que ocurra la navegación si coincide con las URL que estás esperando.
Recomendamos que uses el parser para URLs de Node. Comparaciones simples de cadenas puede a veces engañar - una prueba startsWith('https://example.com') podría dejar pasar https://example.com.attacker.com.
const URL = require('url').URL\n\napp.on('web-contents-created', (event, contents) => {\n contents.on('will-navigate', (event, navigationUrl) => {\n const parsedUrl = new URL(navigationUrl)\n\n if (parsedUrl.origin !== 'https://example.com') {\n event.preventDefault()\n }\n })\n})\nSi tienes un conjunto de ventanas conocido, es una buena idea limitar la creación de ventanas adicionales en tu aplicación.
\nAl igual que la navegación, la creación de nuevo webContents en un vector de ataque común. Los atacantes intentar convencer a tu aplicación a crear nuevas ventanas, frames u otros procesos renderer con más privilegios de lo que antes tenían; o con páginas abiertas que antes no pudieron abrir.
Si no tienes la necesidad de crear ventanas adicionales de la que sabes que tendrás que crear, desactivando la creación te compra un poco de seguridad extra sin costo alguno. Este comúnmente el caso de las aplicaciones que abre un BrowserWindow y no necesita abrir un número arbitrario de ventanas adicionales en tiempo de ejecución.
webContents delegará a su controlado de venta abierta antes de crear nuevas ventanas. The handler will receive, amongst other parameters, the url the window was requested to open and the options used to create it. We recommend that you register a handler to monitor the creation of windows, and deny any unexpected window creation.
const { shell } = require('electron')\n\napp.on('web-contents-created', (event, contents) => {\n contents.setWindowOpenHandler(({ url }) => {\n // In this example, we'll ask the operating system\n // to open this event's url in the default browser.\n //\n // See the following item for considerations regarding what\n // URLs should be allowed through to shell.openExternal.\n if (isSafeForExternalOpen(url)) {\n setImmediate(() => {\n shell.openExternal(url)\n })\n }\n\n return { action: 'deny' }\n })\n})\nopenExternal con contenido no confiableEl openExternal de Shell permite abrir un protocolo URI dado con las utilidades nativas del escritorio. En macOS, a modo de ejemplo, esta función es similar a la utilidad de comando de terminal open y abrirá la aplicación especifica basado en la URI y en el tipo de archivo asociado.
El uso indebido de openExternal puede ser apalancado para comprometer el host del usuario. Cuando openExternal se usa con contenido no confiable, puede ser apalancado para ejecutar comandos arbitrarios.
// Bad\nconst { shell } = require('electron')\nshell.openExternal(USER_CONTROLLED_DATA_HERE)\n// Good\nconst { shell } = require('electron')\nshell.openExternal('https://example.com/index.html')\nYou should strive for always using the latest available version of Electron. Whenever a new major version is released, you should attempt to update your app as quickly as possible.
\nUna aplicación construida con una versión anterior de Electron, Chromium y Node.js es un objetivo más fácil que una aplicación que está usando versiones más recientes de esos componentes. Generalmente hablando, los problemas de seguridad y exploits para viejas verciones de Chromium y Node.js están más ampliamente disponibles.
\nAmbos Chomium y Node.js impresionantes son impresionantes hazañas de ingeniería construidas por miles de talentosos desarrolladores. Dada su popularidad, su seguridad es cuidadosamente probada y analizada por investigadores de seguridad igualmente calificados. Muchos de esos investigadores disclose vulnerabilities responsibly, lo que generalmente quiere decir que los investigadores darán a Chromium y Node.js algo de tiempo para solucionar los problemas antes de publicarlos. Tu aplicación será más segura si está ejecutando una versión reciente de Electron (y por tanto, Chromium y Node.js) para los cuales problemas de seguridad potenciales no son tan conocidos.
", "title": "Seguridad, capacidades nativas y su responsabilidad", "description": "⚠️ bajo ninguna circunstancia deberías cargar y ejecutar código remoto con la integración Node.js activada. En vez de eso, usa solo archivos locales (empaquetados juntos con tu aplicación) para ejecutar el código Node.js. Para mostrar contenido remoto, use la etiquetalabel String (optional) - The text to appear in this segment.icon NativeImage (optional) - The image to appear in this segment.enabled Boolean (optional) - Whether this segment is selectable. Default: true.portId String - Unique identifier for the port.portName String - Name of the port.displayName String - A string suitable for display to the user for describing this device.vendorId String - Optional USB vendor ID.productId String - Optional USB product ID.serialNumber String - The USB device serial number.usbDriverName String (optional) - Represents a single serial port on macOS can be enumerated by multiple drivers.deviceInstanceId String (optional) - A stable identifier on Windows that can be used for device permissions.scriptUrl String - The full URL to the script that this service worker runsscope String - The base URL that this service worker is active for.renderProcessId Number - The virtual ID of the process that this service worker is running in. This is not an OS level PID. This aligns with the ID set used for webContents.getProcessId().\n\nQuery and receive events from a sessions active service workers.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Las instancias de la clase ServiceWorkers son accedidas utilizado la propiedad serviceWorkers de una Session.
Por ejemplo:
\nconst { session } = require('electron')\n\n// Get all service workers.\nconsole.log(session.defaultSession.serviceWorkers.getAllRunning())\n\n// Handle logs and get service worker info\nsession.defaultSession.serviceWorkers.on('console-message', (event, messageDetails) => {\n console.log(\n 'Got service worker message',\n messageDetails,\n 'from',\n session.defaultSession.serviceWorkers.getFromVersionID(messageDetails.versionId)\n )\n})\nLos siguientes eventos están disponibles en instancias de ServiceWorkers:
Devuelve:
\neventmessageDetails Object - Information about the console messagemessage String - The actual console messageversionId Number - The version ID of the service worker that sent the log messagesource String - The type of source for this message. Can be javascript, xml, network, console-api, storage, app-cache, rendering, security, deprecation, worker, violation, intervention, recommendation or other.level Number - The log level, from 0 to 3. In order it matches verbose, info, warning and error.sourceUrl String - The URL the message came fromlineNumber Number - The line number of the source that triggered this console messageEmitted when a service worker logs something to the console.
\nDevuelve:
\neventdetails Object - Información sobre el service worker registradoscope String - La URL base para la que un service worker está registradaEmitido cuando un service worker ha sido registrado. Puede ocurrir después de una llama a navigator.serviceWorker.register('/sw.js') se resuelve con éxito o cuando una extensión de Chrome es cargada.
Lo siguientes métodos están disponibles en instancias de ServiceWorkers:
serviceWorkers.getAllRunning()Returns Record<Number, ServiceWorkerInfo> - A ServiceWorkerInfo object where the keys are the service worker version ID and the values are the information about that service worker.
serviceWorserviceWorkers.getFromVersionID(versionId)versionId NumberReturns ServiceWorkerInfo - Information about this service worker
If the service worker does not exist or is not running this method will throw an exception.
", "title": "Clase: ServiceWorkers", "description": "Query and receive events from a sessions active service workers." }, "/docs/api/session": { "locale": "es-ES", "slug": "session", "href": "/docs/api/session", "crowdinFileId": "256365", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/session.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nAdministra las sesiones del navegador, cookies, cache, configuración del proxy, etc.
\n
Proceso: principal</0>
\nEl módulo session puede ser usado para crear nuevos objetos session.
También puede acceder el session de las páginas existentes utilizando la propiedad session de WebContents, o desde el módulo session.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nconst ses = win.webContents.session\nconsole.log(ses.getUserAgent())\nEl módulo session tiene los siguientes métodos:
session.fromPartition(partition[, options])partition Stringoptions Object (opcional)cache Boolean - En el caso de activar la memoria cache.Regresa Session - Una instancia de session de la cadena partition. Cuando hay una Session existente con la misma partition, se devolverá la misma; de otra manera, una nueva instancia Session será creada con options.
Si la partition comienza con persist:, la página usará una sesión persistente disponible a todas las páginas en la aplicación con la misma partition. si no hay un prefijo persist:, la página usará una sesión en memoria. Si la partition está vacía entonces la sesión de la aplicación será usada por defecto.
Al crear una Session con options, tiene que asegurar que la Session con la partition nunca ha sido usada antes. No hay manera de cambiar las options de un objeto Session existente.
El módulo session tiene las siguientes propiedades:
session.defaultSessionUn objeto Session, es el objeto de session de la aplicación por defecto.
\n\nObtener y configurar las propiedades de una sesión.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Puede crear un objeto Session en el módulo session:
const { session } = require('electron')\nconst ses = session.fromPartition('persist:name')\nconsole.log(ses.getUserAgent())\nLos siguientes eventos están disponibles en instancias de Session:
Devuelve:
\neventitem DownloadItemwebContents WebContentsEmitido cuando Electron está por descargar un elemento en Contenido web.
Llamando event.preventDefault() Se cancelará la descarga y el elemento no estará disponible para el siguiente tick del proceso.
const { session } = require('electron')\nsession.defaultSession.on('will-download', (event, item, webContents) => {\n event.preventDefault()\n require('got')(item.getURL()).then((response) => {\n require('fs').writeFileSync('/somewhere', response.body)\n })\n})\nDevuelve:
\neventextension ExtensionEmitted after an extension is loaded. This occurs whenever an extension is added to the \"enabled\" set of extensions. Esto incluye:
\nSession.loadExtension.chrome.runtime.reload()).Devuelve:
\neventextension ExtensionEmitted after an extension is unloaded. This occurs when Session.removeExtension is called.
Devuelve:
\neventextension ExtensionEmitted after an extension is loaded and all necessary browser state is initialized to support the start of the extension's background page.
\nDevuelve:
\neventpreconnectUrl String - La URL que esta siendo solicitada para preconexión por el renderer.allowCredentials Boolean - True si el renderer está solicitando que la conexión incluya las credenciales (vea el especificación para más detalles.)Emitido cuando un render process solicita preconexión a una URL, generalmente debido a resource hint.
\nDevuelve:
\neventlanguageCode String - El código de idioma del archivo de diccionarioEmitted when a hunspell dictionary file has been successfully initialized. This occurs after the file has been downloaded.
\nDevuelve:
\neventlanguageCode String - El código de idioma del archivo de diccionarioEmitido cuando un archivo de diccionario hunspell se comienza a descargar
\nDevuelve:
\neventlanguageCode String - El código de idioma del archivo de diccionarioEmitido cuando un archivo de diccionario hunspell se ha descargado correctamente
\nDevuelve:
\neventlanguageCode String - El código de idioma del archivo de diccionarioEmitted when a hunspell dictionary file download fails. For details on the failure you should collect a netlog and inspect the download request.
\nDevuelve:
\neventdetails ObjectdeviceList HIDDevice[]frame WebFrameMaincallback FuncióndeviceId String | null (opcional)Emitido cuando un dispositivo HID necesita ser seleccionado cuando se realizó una llamada a navigator.hid.requestDevice. callback debería ser llamada con el deviceId a ser seleccionado; al no pasar argumentos a callback se cancelará la solicitud. Adicionalmente, los permisos en navigator.hid pueden ser administrados aún más usando ses.setPermissionCheckHandler(handler) y ses.setDevicePermissionHandler(handler)`.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Agregue la lógica aquí para determinar si el permiso debería ser dado para permitir la selección HID \n return true\n }\n return false\n })\n\n // Opcionalmente, recupere los dispositivos persistentes anteriormente de un almacén persistente \n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Siempre permite este tipo de dispositivo (esto permite saltar la primera llamada a `navigator.hid.requestDevice`)\n return true\n }\n\n // Busque a través de la lista de dispositivos a los que anteriormente se le han otorgado permiso\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nDevuelve:
\neventdetails Objectdevice HIDDevice[]frame WebFrameMainEmitido cuando un nuevo dispositivo HID está disponible. Por ejemplo, cuando un nuevo dispositivo USB se conecta.
\nEste evento sólo se emitirá después de que navigator.hid.requestDevice haya sido llamado y select-hid-device haya sido disparado.
Devuelve:
\neventdetails Objectdevice HIDDevice[]frame WebFrameMainEmitido cuando un dispositivo HID ha sido eliminado. For example, this event will fire when a USB device is unplugged.
\nEste evento sólo se emitirá después de que navigator.hid.requestDevice haya sido llamado y select-hid-device haya sido disparado.
Devuelve:
\neventportList SerialPort[]webContents WebContentscallback FunciónportId StringEmitted when a serial port needs to be selected when a call to navigator.serial.requestPort is made. callback should be called with portId to be selected, passing an empty string to callback will cancel the request. Additionally, permissioning on navigator.serial can be managed by using ses.setPermissionCheckHandler(handler) with the serial permission.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({\n width: 800,\n height: 600\n })\n win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {\n event.preventDefault()\n const selectedPort = portList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n if (!selectedPort) {\n callback('')\n } else {\n callback(selectedPort.portId)\n }\n })\n})\nDevuelve:
\neventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a new serial port becomes available. For example, this event will fire when a new USB device is plugged in.
Devuelve:
\neventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a serial port has been removed. For example, this event will fire when a USB device is unplugged.
Los siguientes métodos están disponibles para instancias de Sesión:
ses.getCacheSize()Devuelve Promise<Integer> - El tamaño de cache de la sesión actual, en bytes.
ses.clearCache()Devuelve Promise<void> - Se resuelve cuando la operación de limpieza de cache es completada.
Borra la memoria caché del HTTP de la sesión.
\nses.clearStorageData([options])options Object (opcional)origin String (opcional) - Debe seguir la representación de window.location.origin scheme://host:port.storages String - Los tipos de almacenamientos para limpiar, puede contener: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage. If not specified, clear all storage types.quotas String - El tipo de cuotas a limpiar, puede contener: temporary, persistent, syncable. If not specified, clear all quotas.Devuelve Promise<void> - Se resuelve cuando los datos del almacenamiento ha sido borrado.
ses.flushStorageData()Escribe cualquier dato DOMStorage que no lo haya sido en disco.
\nses.setProxy(config)config Objectmode String (optional) - The proxy mode. Should be one of direct, auto_detect, pac_script, fixed_servers or system. If it's unspecified, it will be automatically determined based on other specified options.direct In direct mode all connections are created directly, without any proxy involved.auto_detect In auto_detect mode the proxy configuration is determined by a PAC script that can be downloaded at http://wpad/wpad.dat.pac_script In pac_script mode the proxy configuration is determined by a PAC script that is retrieved from the URL specified in the pacScript. This is the default mode if pacScript is specified.fixed_servers In fixed_servers mode the proxy configuration is specified in proxyRules. This is the default mode if proxyRules is specified.system In system mode the proxy configuration is taken from the operating system. Note that the system mode is different from setting no proxy configuration. In the latter case, Electron falls back to the system settings only if no command-line options influence the proxy configuration.pacScript String (opcional) - La URL asociada con el archivo PAC.proxyRules String (opcional) - Reglas indicando cuales proxies usar.proxyBypassRules String (opcional) - Reglas indicando que URLs deberían ser omitidas por la configuración del proxy.Devuelve Promise<void> - Se resuelve cuando el proceso de configuración del proxy está completo.
Configurar proxy.
\nWhen mode is unspecified, pacScript and proxyRules are provided together, the proxyRules option is ignored and pacScript configuration is applied.
You may need ses.closeAllConnections to close currently in flight connections to prevent pooled sockets using previous proxy from being reused by future requests.
Las proxyRules tienen las siguientes reglas abajo:
proxyRules = schemeProxies[\";\"<schemeProxies>]\nschemeProxies = [<urlScheme>\"=\"]<proxyURIList>\nurlScheme = \"http\" | \"https\" | \"ftp\" | \"socks\"\nproxyURIList = <proxyURL>[\",\"<proxyURIList>]\nproxyURL = [<proxyScheme>\"://\"]<proxyHost>[\":\"<proxyPort>]\nPor ejemplo:
\nhttp=foopy:80;ftp=foopy2 - Usa proxy HTTP foopy:80 para URL http://, HTTP proxy foopy2:80 para URL ftp://.foopy:80 - Usa Proxy HTTP foopy:80 para todas las URLs.foopy:80,bar,direct:// - Usa proxy HTTP foopy:80 para todas las URLs, no sobre bar sifoopy:80 no está disponible, y después de eso no usar ningún proxy.socks4://foopy - Usa SOCKS v4 proxy foopy:1080 para todas las URLs.http=foopy,socks5://bar.com - Usa HTTP proxy foopy para las URLs http, y falla para el proxy SOCKS5 bar.com si foopy no está disponible.http=foopy,direct:// - Usa el proxy HTTP foopy para URLs http, y no usa el proxy si foopy no está disponible.http=foopy;socks=foopy2 - Usa el proxy HTTP foopy para URLs HTTP, y usa socks4://foopy2 para el resto de URLs.El proxyBypassRules es una lista separada por comas de las reglasa que se describen a continuación:
[ URL_SCHEME \"://\" ] HOSTNAME_PATTERN [ \":\" <port> ]
Une todos los nombres que coinciden con el patrón HOSTNAME_PATTERN.
\nExamples: \"foobar.com\", \"foobar.com\", \".foobar.com\", \"foobar.com:99\", \"https://x..y.com:99\"
\n\".\" HOSTNAME_SUFFIX_PATTERN [ \":\" PORT ]
Une sufijos de dominios particulares.
\nExamples: \".google.com\", \".com\", \"http://.google.com\"
\n[ SCHEME \"://\" ] IP_LITERAL [ \":\" PORT ]
Une URLs que son literales de dirección IP.
\nEjemplos: \"127.0.1\", \"[0:0::1]\", \"[::1]\", \"http://[::1]:99\"
\nIP_LITERAL \"/\" PREFIX_LENGTH_IN_BITS
Match any URL that is to an IP literal that falls between the given range. IP range is specified using CIDR notation.
\nEjemplos: \"192.168.1.1/16\", \"fefe:13::abc/33\".
\n<local>
Match local addresses. The meaning of <local> is whether the host matches one of: \"127.0.0.1\", \"::1\", \"localhost\".
ses.resolveProxy(url)url URLReturns Promise<String> - Resolves with the proxy information for url.
ses.forceReloadProxyConfig()Returns Promise<void> - Resolves when the all internal states of proxy service is reset and the latest proxy configuration is reapplied if it's already available. The pac script will be fetched from pacScript again if the proxy mode is pac_script.
ses.setDownloadPath(path)path String - The download location.Sets download saving directory. By default, the download directory will be the Downloads under the respective app folder.
ses.enableNetworkEmulation(options)options Objectoffline Boolean (optional) - Whether to emulate network outage. Defaults to false.latency Double (optional) - RTT in ms. Defaults to 0 which will disable latency throttling.downloadThroughput Double (optional) - Download rate in Bps. Defaults to 0 which will disable download throttling.uploadThroughput Double (optional) - Upload rate in Bps. Defaults to 0 which will disable upload throttling.Emula la red con la configuración dada por la sesión.
Para emular la conexión GPRS con rendimiento de 50kbps y latencia de 500ms.\nwindow.webContents.session.enableNetworkEmulation({\n latency: 500,\n downloadThroughput: 6400,\n uploadThroughput: 6400\n})\n\n// Para emular la caída de la red.\nwindow.webContents.session.enableNetworkEmulation({ offline: true })\nses.preconnect(options)options Objecturl String - URL for preconnect. Only the origin is relevant for opening the socket.numSockets Number (optional) - number of sockets to preconnect. Must be between 1 and 6. Defaults to 1.Preconecta el número dado de sockets a un origen.
\nses.closeAllConnections()Returns Promise<void> - Resolves when all connections are closed.
Note: It will terminate / fail all requests currently in flight.
\nses.disableNetworkEmulation()Disables any network emulation already active for the session. Resets to the original network configuration.
ses.setCertificateVerifyProc(proc)proc Function | nullrequesthostname Stringcertificate certificatevalidatedCertificate CertificateverificationResult String - Resultado de la verificación de chromium.errorCode Integer - Código de error.callback FunciónverificationResult Integer - Value can be one of certificate error codes from here. Apart from the certificate error codes, the following special codes can be used.0 - Indica éxito y deshabilita la verificación Certificate Transparency.-2 - Indica falla.-3 - Usa el resultado de verificación de chromium.Establece el certificado de verificar proc de la sesión, el proc será cancelada con proc(request, callback) cuando sea solicitado una verificación del certificado del servidor. Llamando callback(0) se acepta el certificado, llamando callback(-2) se rechaza.
Llamando setCertificateVerifyProc(null) se reveritrá la verificación de certificado por defecto.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.webContents.session.setCertificateVerifyProc((request, callback) => {\n const { hostname } = request\n if (hostname === 'github.com') {\n callback(0)\n } else {\n callback(-2)\n }\n})\n\n\nNOTE: The result of this procedure is cached by the network service.
\n
ses.setPermissionRequestHandler(handler)handler Function | nullcontenido web contenido web - contenido web solicitando el permiso. Por favor, tenga en cuenta que si la solicitud viene de un subframe debe utilizar requestUrl para comprobar el origen de la solicitud.permission String - The type of requested permission.clipboard-read - Request access to read from the clipboard.media - Request access to media devices such as camera, microphone and speakers.display-capture - Solicita acceso para capturar la pantalla.mediaKeySystem - Request access to DRM protected content.geolocation - Request access to user's current location.notifications - Request notification creation and the ability to display them in the user's system tray.midi - Request MIDI access in the webmidi API.midiSysex - Request the use of system exclusive messages in the webmidi API.pointerLock - Request to directly interpret mouse movements as an input method. Pulse aquí para saber más.fullscreen - Request for the app to enter fullscreen mode.openExternal - Request to open links in external applications.unknown - Una solicitud de premiso no reconocidacallback Funciónpermiso concedido Booleano - Permiso o denegado de permiso.details Object - Some properties are only available on certain permission types.externalURL String (opcional) - La url de la petición openExternal.mediaTypes String - Los tipos de medios que son solicitados para acceso, los elementos pueden ser video o audiorequestingUrl String - La ultima URL que el frame solicitante cargoisMainFrame Boolean - Si el marco que realiza la solicitud es el marco principalConfigurar el controlador que será usado para responder las peticiones de permisos para la sesión. Llamando callback(true) se permitirá el permiso y callback(false) se rechazará. Para limpiar el manejador, llamar a setPermissionRequestHandler(null). Por favor, tenga en cuenta que debe implementar también setPermissionCheckHandler para obtener el manejo completo de los permisos. La mayoría de las APIs web hacen una verificación de permiso y luego hacen una solicitud de permiso si la verificación es denegada.
const { session } = require('electron')\nsession.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {\n if (webContents.getURL() === 'some-host' && permission === 'notifications') {\n return callback(false) // denied.\n }\n\n callback(true)\n})\nses.setPermissionCheckHandler(handler)handler Función\\webContents (WebContents | null) - WebContents verificando el permiso. Por favor, tenga en cuenta que si la solicitud viene de un subframe debe utilizar requestUrl para comprobar el origen de la solicitud. Todos los sub frames de origen cruzado que realizan comprobaciones de permisos pasarán un webContents null a este controlador, mientras que otras comprobaciones de permisos, como notifications siempre pasarán null. Debería usar embeddingOrigin y requestingOrigin para determinar que origen se encuentra en el marco propietario y en el marco solicitante respectivamente.permission String - Type of permission check. Los valores válidos son midiSysex, notifications, geolocation, media,mediaKeySystem,midi, pointerLock, fullscreen, openExternal, hid, o serial.requestingOrigin String - La URL de origen para la comprobación de permisosdetails Object - Some properties are only available on certain permission types.embeddingOrigin String (opcional) - El origen del marco que incrusta el marco que hizo la verificación de permisos. Sólo se establece cross-origin submarcos haciendo comprobaciones de permisos.securityOrigin String (opcional) - El origen de seguridad de la comprobación media.mediaType String (opcional) - El tipo de acceso a los medios que se solicita puede ser video, audio o unknownrequestingUrl String (opcional) - La última URL que representa el marco cargado. Esto no es proveído para cross-origin submarcos haciendo comprobaciones de permiso.isMainFrame Boolean - Si el marco que realiza la solicitud es el marco principalEstablece el manejador que puede ser usado para responder a las comprobaciones para session. Retornando true permitirá el permiso y false lo rechará. Por favor, tenga en cuenta que debe implementar también setPermissionRequestHandler para obtener el manejo completo de los permisos. La mayoría de las APIs web hacen una verificación de permiso y luego hacen una solicitud de permiso si la verificación es denegada. Para borrar el manejador, llame setPermissionCheckHandler(null).
const { session } = require('electron')\nconst url = require('url')\nsession.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {\n return true // concedido\n }\n\n return false // denegado\n})\nses.setDevicePermissionHandler(handler)handler Función\\details ObjectdeviceType String - El tipo de dispositivo para el que se esta solicitando el permiso, puede ser hid.origin String - La URL de origen de verificación del permiso del dispositivo.device HIDDevice - El dispositivo para el que se está solicitando el permiso.frame WebFrameMain - WebFrameMain comprobando el permiso del dispositivo.Establece el manejador que puede ser usado para responder a las comprobaciones de permiso para la session. Devolver true permitirá que el dispositivo se permitido y false lo rechazará. Para borrar el manejador, llame a setDevicePermissionHandler(null). Este manejador puede ser usado para proveer permisos por defecto a dispositivos sin solicitar primero el permiso a dispositivos (por ejemplo a través de navigator.hid.requestDevice). Si este manejador no esta difinido, los permisos por defecto para el dispositivos serán otorgados a través de la selección de dispositivo (por ejemplo a través de navigator.hid.requestDevice). Adicionalmente, el comportamiento por defecto de Electron es almacenar los permisos otorgados a dispositivos a través de toda la vida del correspondiente WebContents. Si se es necesario almacenarlo a más largo plazo, un desarrollador puede almacenar los permisos otorgados (por ejemplo, cuando se maneja el evento select-hid-device) y luego leerlo desde ese almacenamiento con setDevicePermissionHandler.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Agregue la lógica aquí para determinar si el permiso debería ser dado para permitir la selección HID \n return true\n }\n return false\n })\n\n // Opcionalmente, recupere los dispositivos persistentes anteriormente de un almacén persistente \n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Siempre permite este tipo de dispositivo (esto permite saltar la primera llamada a `navigator.hid.requestDevice`)\n return true\n }\n\n // Busque a través de la lista de dispositivos a los que anteriormente se le han otorgado permiso\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nses.clearHostResolverCache()Devuelve Promise<void> - Se resuelve cuando la operación es completada.
Borra la caché de resolución de host.
\nses.allowNTLMCredentialsForDomains(domains)dominio Cadena - Una lista separada por coma de servidores para los cuales la autenticación integrada está habilitada.Configura dinámicamente cada vez que se envíen credenciales para HTTP NTLM o negociaciones de autenticación.
\nconst { session } = require('electron')\n// consider any url ending with `example.com`, `foobar.com`, `baz`\n// for integrated authentication.\nsession.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')\n\n// consider all urls for integrated authentication.\nsession.defaultSession.allowNTLMCredentialsForDomains('*')\nses.setUserAgent(userAgent[, acceptLanguages])userAgent cadenalenguajes aceptados Cadena (opcional)Reemplaza el userAgent y los lenguajes aceptados para esta sesión.
Los lenguajes aceptados deben estar ordenados en una lista separada por coma de códigos de lenguaje, por ejemplo \"en-US,fr,de,ko,zh-CN,ja\".
Esto no afecta el contenido web existente, y cada contenido web puede usar webContents.setUserAgent para sobreescribir el agente de sesión de usuario.
ses.isPersistent()Devuelve Boolean - Si la sesión es persistente o no. The default webContents session of a BrowserWindow is persistent. When creating a session from a partition, session prefixed with persist: will be persistent, while others will be temporary.
ses.getUserAgent()Devuelve Cadena - El agente usuario para esta sesión.
ses.setSSLConfig(config)config ObjectminVersion String (opcional) - Puede ser tls1, tls1.1, tls1.2 o tls1.3. The minimum SSL version to allow when connecting to remote servers. Por defecto a tls1.maxVersion String (opcional) - Puede ser tls1.2 o tls1.3. The maximum SSL version to allow when connecting to remote servers. Por defecto es tls1.3.disabledCipherSuites Integer - List of cipher suites which should be explicitly prevented from being used in addition to those disabled by the net built-in policy. Supported literal forms: 0xAABB, where AA is cipher_suite[0] and BB is cipher_suite[1], as defined in RFC 2246, Section 7.4.1.2. Unrecognized but parsable cipher suites in this form will not return an error. Ex: To disable TLS_RSA_WITH_RC4_128_MD5, specify 0x0004, while to disable TLS_ECDH_ECDSA_WITH_RC4_128_SHA, specify 0xC002. Note that TLSv1.3 ciphers cannot be disabled using this mechanism.Sets the SSL configuration for the session. All subsequent network requests will use the new configuration. Existing network connections (such as WebSocket connections) will not be terminated, but old sockets in the pool will not be reused for new connections.
\nses.getBlobData(identifier)identificador Cadena - UUID válido.Devuelve Promise<Buffer> - Se resuelve con datos blob.
ses.downloadURL(url)url StringInicia una descargar del recurso en url. La API generará un DownloadItem que puede ser accedido con el evento will-download.
Note: Esto no realiza ninguna comprobación de seguridad relacionada con la pagina de origen a diferencia de webContents.downloadURL.
ses.createInterruptedDownload(options)options Objectruta Cadena - ruta de acceso absoluta de la descarga.Cadeba URL Cadena[] - Cadena de URL completa para la descarga.mimeType Cadena (opcional)offset Entero - rango de inicio para la descarga.longitud Entero - longitud total de la descarga.lastModified String (opcional) - Último valor del encabezado modificado.eTag String (opcional) - Valor ETag del encabezado.Tiempo de inicio Doble (opcional) - Tiempo en que se inició la descarga en números de segundo desde epoch de UNIX.Permite cancelar o interrumpir descargas de una Sesión previa. La API generará un elemento de descarga que puede ser accesado con el evento se descargará. El Elemento de descarga no tendrá ningún contenido web asociado con el y el estado inicial será interrumpido. La descarga empezará solo cuando la reanudación de la API sea llamada en el elemento descargado.
ses.clearAuthCache()Devuelve Promise<void> - resuelve cuando se ha borrado el caché de autenticación HTTP de la sesión.
ses.setPreloads(preloads)preloads String[] - Un array de ruta absoluta para precargar scriptsAgrega scripts que se ejecutarán en TODOS los contenidos web que están asociados con esta sesión justo antes de que se ejecuten los scripts de preload normales.
ses.getPreloads()Devuelve un array de rutas String[] para precargar guiones que han sido registrado.
ses.setSpellCheckerEnabled(enable)enable BooleanSets whether to enable the builtin spell checker.
\nses.isSpellCheckerEnabled()Returns Boolean - Whether the builtin spell checker is enabled.
ses.setSpellCheckerLanguages(languages)languages String[] - Un array de códigos de idiomas para habilitar corrector ortográfico.El corrector ortográfico integrado no detecta automáticamente en que idioma un usuario esta escribiendo. Para que el corrector ortográfico compruebe correctamente sus palabras, usted debe llamar a esta API con un array de códigos de idiomas. Usted puede obtener la lista de los códigos de idiomas soportados con la propiedad ses.availableSpellCheckerLanguages.
Note: On macOS the OS spellchecker is used and will detect your language automatically. This API is a no-op on macOS.
\nses.getSpellCheckerLanguages()Devuelve String[] - Un array de códigos de idiomas para los que el corrector ortográfico esta habilitado. Si esta lista está vacía, el corrector ortográfico volverá a usar en-US. Por defecto al iniciar si esta lista de opción es una lista vacía Electron tratará de llenar esta opción con el locale actual del sistema operativo. Este configuración es persistente entre reinicios.
Note: On macOS the OS spellchecker is used and has its own list of languages. This API is a no-op on macOS.
\nses.setSpellCheckerDictionaryDownloadURL(url)url String - Una URL base para Electron desde donde descargar los diccionarios hunspell.Por defecto Electron descargará diccionarios hunspell desde la CDN de Chromium. Si usted quiere sobrescribir este comportamiento puede usar esta API para apuntar el descargador de diccionarios a su propia versión alojada de diccionarios hunspell. Nosotros publicamos un archivo hunspell_dictionaries.zip con cada versión el cual contiene los archivos que necesitas para alojar aquí, el servidor de archivos debe ser case insensitive, debe cargar cada archivo dos veces, una como tiene este archivo ZIP y otra con el nombre del archivo todo con minúsculas.
Si los archivos presentes en hunspell_dictionaries.zip están disponible en https://example.com/dictionaries/language-code.bdic entonces entonces debería llamar esta api con ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Por favor, tenga en cuenta la barra final. La URL a los diccionarios esta formada como ${url}${filename}.
Note: On macOS the OS spellchecker is used and therefore we do not download any dictionary files. This API is a no-op on macOS.
\nses.listWordsInSpellCheckerDictionary()Devuelve Promise<String[]> - Un array de todas las palabras en el diccionario personalizado de la aplicación. Resolves when the full dictionary is loaded from disk.
ses.addWordToSpellCheckerDictionary(word)word String - La palabra que desea agregar al diccionarioDevuelve Boolean - Si la palabra fue correctamente escrita al diccionario personalizado. Esta API no funcionará en sesiones no persistentes (en-memoría).
Note: En macOS y Windows 10 esta palabra será escrita al diccionario personalizado del sistema operativo también
\nses.removeWordFromSpellCheckerDictionary(word)word String - The word you want to remove from the dictionaryDevuelve Boolean - Si la palabra fue eliminada con éxito del diccionario personalizado. Esta API no funcionará en sesiones no persistentes (en-memoría).
Note: On macOS and Windows 10 this word will be removed from the OS custom dictionary as well
\nses.loadExtension(path[, options])path String - Path to a directory containing an unpacked Chrome extensionoptions Object (opcional)allowFileAccess Boolean - Si permitir que la extensión lea los archivos locales sobre el protocolo file:// e inyecte scripts contenido dentro de las páginas file://. Esto es necesario por ejemplo para cargar las extensiones devtools en las URLs file://. Por defecto es falso.Devuelve Promise<Extension> - se resuelve cuando la extensión está cargada.
This method will raise an exception if the extension could not be loaded. If there are warnings when installing the extension (e.g. if the extension requests an API that Electron does not support) then they will be logged to the console.
\nNote that Electron does not support the full range of Chrome extensions APIs. Vea el APIs de extensiones soportadas para más detalles sobre que es soportado.
\nNote that in previous versions of Electron, extensions that were loaded would be remembered for future runs of the application. This is no longer the case: loadExtension must be called on every boot of your app if you want the extension to be loaded.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.on('ready', async () => {\n await session.defaultSession.loadExtension(\n path.join(__dirname, 'react-devtools'),\n // allowFileAccess is required to load the devtools extension on file:// URLs.\n { allowFileAccess: true }\n )\n // Note that in order to use the React DevTools extension, you'll need to\n // download and unzip a copy of the extension.\n})\nThis API does not support loading packed (.crx) extensions.
\nNota: Esta API no puede ser llamada antes de que el evento ready del módulo de app sea emitido.
Note: Loading extensions into in-memory (non-persistent) sessions is not supported and will throw an error.
\nses.removeExtension(extensionId)extensionId String - ID of extension to removeUnloads an extension.
\nNota: Esta API no puede ser llamada antes de que el evento ready del módulo de app sea emitido.
ses.getExtension(extensionId)extensionId String - ID of extension to queryDevuelve Extension | null - La extensión cargada con el ID dado.
Nota: Esta API no puede ser llamada antes de que el evento ready del módulo de app sea emitido.
ses.getAllExtensions()Devuelve Extension[] - Una lista de todas las extensiones cargadas.
Nota: Esta API no puede ser llamada antes de que el evento ready del módulo de app sea emitido.
ses.getStoragePath()A String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
Las siguientes propiedades están disponibles en instancias de Sesión:
ses.availableSpellCheckerLanguages ReadonlyUn array String[] que consiste en todos los idiomas conocidos disponibles para el corrector ortográfico. Proporcionar un código de lenguaje a la API setSpellCheckerLanguages que no este en este array resultará en un error.
ses.spellCheckerEnabledA Boolean indicating whether builtin spell checker is enabled.
ses.storagePath SoloLecturaA String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
ses.cookies ReadonlyUn objeto Cookies para esta sesión.
ses.serviceWorkers SoloLecturaUn objeto ServiceWorkers para esta sesión.
ses.webRequest ReadonlyUn objeto WebRequest para esta sesión.
ses.protocol ReadonlyUn objeto Protocol para esta sesión.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const protocol = session.fromPartition('some-partition').protocol\n if (!protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })) {\n console.error('Failed to register protocol')\n }\n})\nses.netLog ReadonlyUn objeto NetLog para esta sesión.
const { app, session } = require('electron')\n\napp.whenReady().then(async () => {\n const netLog = session.fromPartition('some-partition').netLog\n netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nLos símbolos de depuración le permiten tener mejores sesiones de depuración. Ellos tienen información acerca de las funciones contenidas en ejecutables y bibliotecas dinámicas y le proporciona información para obtener pilas de llamadas limpias. Un servidor de símbolos permite al depurador cargar los símbolos, binarios y fuentes correctas automáticamente sin obligar a los usuarios a descargar grandes archivos de depuración. El servidor funciona como Microsoft's symbol server por lo que la documentación de allí puede ser útil.
\nTenga en cuenta que debido a que las compilaciones de Electron liberadas están muy optimizadas, la depuración no siempre es fácil. El depurador no podrá mostrarle el contenido de todas las variables y la ruta de ejecución puede parecer extraña debido a la alineación, las llamadas de cola y otras optimizaciones del compilador. La única solución es compilar una versión local no optimizada.
\nEl URL oficial del servidor de símbolos para Electron es https://symbols.electronjs.org. No puede visitar esta URL directamente, debe agregarla a la ruta del símbolo de su herramienta de depuración. En los ejemplos a continuación, se usa un directorio de caché local para evitar obtener repetidamente el PDB desde el servidor. Reemplace c:\\code\\symbols con un directorio de cache apropiado en su máquina.
La ruta del símbolo de Windbg se configura con un valor de cadena delimitado con caracteres de asterisco. Para utilizar solo el servidor de símbolos de Electron, añada la siguiente entrada a la ruta de símbolo (Nota: puede reemplazar c:\\code\\symbols con cualquier directorio de escritura en el computador, si se prefiere una ubicación distinta para los símbolos descargados):
SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\nConfigure esta cadena como _NT_SYMBOL_PATH en el entorno, utilizando los menús Windbg o escribiendo el comando .sympath. Si también desea obtener símbolos de el servidor de símbolos de Microsoft, debería enumerarlos primero:
SRV*c:\\code\\symbols\\*https://msdl.microsoft.com/download/symbols;SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\n
Escriba los siguientes comandos en Windbg para imprimir por qué los símbolos no se están cargando:
\n> !sym noisy\n> .reload /f electron.exe\nLa clase ShareMenu crea Share Menu en macOS, que puede usarse para compartir información desde el contexto actual a las apps, cuentas de redes sociales y otros servicios.
Para incluir el menú compartido como submenú de otros, por favor usa el rol shareMenu de MenuItem.
\n\nCreate share menu on macOS.
\n
Proceso: principal</0>
\nnew ShareMenu(sharingItem)sharingItem SharingItem - The item to share.Creates a new share menu.
\nEl objeto shareMenu tiene los siguientes métodos de instancia:
shareMenu.popup([options])options PopupOptions (optional)browserWindow BrowserWindow (opcional) - Por defecto es la ventana seleccionada.x Número (opcional) - Default es la posición actual del cursor. Debe ser declarado si y es declarado.y Número (opcional) - Default es la posición actual del cursor. Debe ser declarado si x es declarado.positioningItem Número (opcional) macOS - El índice del elemento del menú que debe ser posicionado debajo del cursor en las coordenadas específicas. El valor predeterminado es -1.callback Function (opcional) - Llamada cuando se cierra el menu.Este menú aparece como un menú contextual en el BrowserWindow.
shareMenu.closePopup([browserWindow])browserWindow BrowserWindow (opcional) - Por defecto es la ventana seleccionada.Cierra el menú de contexto en la browserWindow.
id String - The unique id of the shared worker.url String - The url of the shared worker.texts String - An array of text to share.filePaths String - An array of files to share.urls String - An array of URLs to share.\n\nAdministra los archivos y los URLs utilizando las aplicaciones por defecto.
\n
Process: Main, Renderer (non-sandboxed only)
\nEl módulo shell proporciona las funciones relacionadas con la integración de escritorio.
Ejemplo de cómo abrir un URL en el navegador por defecto del usuario:
\nconst { shell } = require('electron')\n\nshell.openExternal('https://github.com')\nNote: While the shell module can be used in the renderer process, it will not function in a sandboxed renderer.
El módulo shell tiene los siguientes métodos:
shell.showItemInFolder(fullPath)fullPath CadenaMuestra el archivo dado en un gestor de archivos. Si es posible, seleccione el archivo.
\nshell.openPath(path)path StringReturns Promise<String> - Resolves with a string containing the error message corresponding to the failure if a failure occurred, otherwise \"\".
Abre el archivo determinado en el escritorio por defecto.
\nshell.openExternal(url[, options])url String - Máximo 2081 caracteres en windows.options Object (opcional)activate Boolean (opcional) macOs - true para llevar la aplicación abierta al primer plano. El valor por defecto es true.workingDirectory String (opcional) Windows - El directorio de trabajo.Devuelve Promise<void>
Abre el protocolo URL externo dado de manera predeterminada en el escritorio. (Por ejemplo, mailto: URLs en el agente de correo predeterminado del usuario).
\nshell.trashItem(path)path String - path to the item to be moved to the trash.Returns Promise<void> - Resolves when the operation has been completed. Rejects if there was an error while deleting the requested item.
This moves a path to the OS-specific trash location (Trash on macOS, Recycle Bin on Windows, and a desktop-environment-specific location on Linux).
\nshell.beep()Reproduce el sonido bip.
\nshell.writeShortcutLink(shortcutPath[, operation], options) WindowsshortcutPath Stringoperation String (opcional) - El valor por defecto es create; puede ser uno de los siguientes:create - Crea un nuevo acceso directo, sobrescribiendo si es necesario.update - Actualiza las propiedades especificadas solo en un acceso directo existente.replace - Sobrescribe un acceso directo existente. Y falla si el acceso directo no existe.options ShortcutDetailsDevuelve Boolean - Si el acceso directo fue creado con éxito.
Crea o actualiza un enlace de acceso directo a shortcutPath.
shell.readShortcutLink(shortcutPath) WindowsshortcutPath StringDevuelve ShortcutDetails
Resuelve el enlace de acceso directo a shortcutPath.
Aparecerá una excepción cuando ocurre cualquier error.
", "title": "shell", "description": "Administra los archivos y los URLs utilizando las aplicaciones por defecto." }, "/docs/api/structures/shortcut-details": { "locale": "es-ES", "slug": "shortcut-details", "href": "/docs/api/structures/shortcut-details", "crowdinFileId": "256509", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/shortcut-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "target String - The target to launch from this shortcut.cwd String (optional) - The working directory. Default is empty.args String (optional) - The arguments to be applied to target when launching from this shortcut. Default is empty.description String (optional) - The description of the shortcut. Default is empty.icon String (optional) - The path to the icon, can be a DLL or EXE. icon and iconIndex have to be set together. Default is empty, which uses the target's icon.iconIndex Number (optional) - The resource ID of icon when icon is a DLL or EXE. Default is 0.appUserModelId String (optional) - The Application User Model ID. Default is empty.toastActivatorClsid String (optional) - The Application Toast Activator CLSID. Needed for participating in Action Center.width Numberheight NumberEsta guía provee información sobre cómo empacar you aplicación en Electron para cualquier ambiente en Snapcraft, incluyendo el Centro de Software de Ubuntu.
\nJuntos con las amplia comunidad de Linux, Canonical busca arreglar algunos de los problemas comúnes de instalación de software con snapcraft. Snaps son paquetes contenerizados de software que incluyen dependencias requeridas, auto-actualizaciones, y funcionan en las mayores distribuciones de Linux sin modificaciones del sistema.
Hay tres maneras de crear un archivo .snap:
1) Usando electron-forge o electron-builder, ambas herramientas que vienen con soporte para snap incluido. Esta es la opción más fácil. 2) Usando electron-installer-snap, que toma el resultado de electron-packager. 3) Usando un paquete .deb ya creado.
En algunos casos, deberás tener instalada la herramienta Snapcraft. Instructions to install snapcraft for your particular distribution are available here.
electron-installer-snapEl módulo trabaja como electron-winstaller y módulos similares en este ámbito está limitado para construir paquetes snap. Puede instalarlo con:
npm install --save-dev electron-installer-snap\nEmpaquetar la aplicación usando electron-packager (o una herramienta similar). Asegúrese de eliminar los node_modules que no necesita en su aplicación final, ya que cualquier módulo que actualmente no necesite aumentará el tamaño de su aplicación.
La salida debería verse más o menos de esta forma:
\n.\n└── dist\n └── app-linux-x64\n ├── LICENSE\n ├── LICENSES.chromium.html\n ├── content_shell.pak\n ├── app\n ├── icudtl.dat\n ├── libgcrypt.so.11\n ├── libnode.so\n ├── locales\n ├── resources\n ├── v8_context_snapshot.bin\n └── version\nelectron-installer-snapDesde una terminal que tenga snapcraft en su PATH, ejecute electron-installer-snap solo con el parámetro requerido --src, el cual es la ubicación de su aplicación empaquetada Electron que se creo en el primer paso.
npx electron-installer-snap --src=out/myappname-linux-x64\nSi tiene un pipeline de construcción existente, puede usar electron-installer-snap programáticamente. Para más información, ver el Snapcraft API docs.
const snap = require('electron-installer-snap')\n\nsnap(options)\n .then(snapPath => console.log(`Created snap at ${snapPath}!`))\nsnapcraft con electron-packagerCrea el directorio de tu proyecto y agrega lo siguiente al snap/snapcraft.yaml:
name: electron-packager-hello-world\nversion: '0.1'\nsummary: Hello World Electron app\ndescription: |\n Simple Hello World Electron app as an example\nbase: core18\nconfinement: strict\ngrade: stable\n\napps:\n electron-packager-hello-world:\n command: electron-quick-start/electron-quick-start --no-sandbox\n extensions: [gnome-3-34]\n plugs:\n - browser-support\n - network\n - network-bind\n environment:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n TMPDIR: $XDG_RUNTIME_DIR\n\nparts:\n electron-quick-start:\n plugin: nil\n source: https://github.com/electron/electron-quick-start.git\n override-build: |\n npm install electron electron-packager\n npx electron-packager . --overwrite --platform=linux --output=release-build --prune=true\n cp -rv ./electron-quick-start-linux-* $SNAPCRAFT_PART_INSTALL/electron-quick-start\n build-snaps:\n - node/14/stable\n build-packages:\n - unzip\n stage-packages:\n - libnss3\n - libnspr4\nSi quiere aplicar este ejemplo a un proyecto existente:
\nsource: https://github.com/electron/electron-quick-start.git con source: ..electron-quick-start con el nombre de su proyecto.$ snapcraft\n\n<output snipped>\nSnapped electron-packager-hello-world_0.1_amd64.snap\nsudo snap install electron-packager-hello-world_0.1_amd64.snap --dangerous\nelectron-packager-hello-world\nSnapcraft es capaz de tomar un archivo .deb existente y convertirlo en un archivo .snap. La creación de un a snap es configurado usando un archivo snapcraft.yaml que describe las fuentes, dependencias, descripción y otros bloques de construcción.
Si aún no tienes listo un paquete .deb, usando electron-installer-snap podría ser una forma más fácil para crear el paquete instantáneo. However, multiple solutions for creating Debian packages exist, including electron-forge, electron-builder or electron-installer-debian.
For more information on the available configuration options, see the documentation on the snapcraft syntax. Veamos un ejemplo:
\nname: myApp\nversion: '2.0.0'\nsummary: A little description for the app.\ndescription: |\n You know what? This app is amazing! It does all the things\n for you. Some say it keeps you young, maybe even happy.\n\ngrade: stable\nconfinement: classic\n\nparts:\n slack:\n plugin: dump\n source: my-deb.deb\n source-type: deb\n after:\n - desktop-gtk3\n stage-packages:\n - libasound2\n - libnotify4\n - libnspr4\n - libnss3\n - libpcre3\n - libpulse0\n - libxss1\n - libxtst6\n electron-launch:\n plugin: dump\n source: files/\n prepare: |\n chmod +x bin/electron-launch\n\napps:\n myApp:\n command: bin/electron-launch $SNAP/usr/lib/myApp/myApp\n desktop: usr/share/applications/myApp.desktop\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n environment:\n TMPDIR: $XDG_RUNTIME_DIR\nAs you can see, the snapcraft.yaml instructs the system to launch a file called electron-launch. In this example, it passes information on to the app's binary:
\nexec \"$@\" --executed-from=\"$(pwd)\" --pid=$$ > /dev/null 2>&1 &\nAlternativamente, si esta construyendo su snap con aislamiento strict, puede usar el comando desktop-launch:
apps:\n myApp:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n command: env TMPDIR=$XDG_RUNTIME_DIR PATH=/usr/local/bin:${PATH} ${SNAP}/bin/desktop-launch $SNAP/myApp/desktop\n desktop: usr/share/applications/desktop.desktop\nEl código fuente de Electron está separado en unas pocas partes, la mayoría siguiendo a Chromium en las convenciones de separación.
\nNecesitará familiarizarse con la arquitectura multiprocesos de Chromium para entender mejor el código fuente.
\nElectron\n├── build/ - Archivos de configuración necesarios para compilar con GN.\n├── buildflags/ - Determina el conjunto de características que pueden ser compiladas condicionalmente.\n├── chromium_src/ - Código fuente copiado desde Chromium que no es parte de la capa de contenido.\n├── default_app/ - Una aplicación predeterminada se ejecuta cuando se inicia Electron sin proveer \n| una aplicación de consumo.\n├── docs/ - Documentación de Electron.\n| ├── api/ - Documentación para modulos y APIs externas.\n| ├── development/ - Documentación para ayudar en el desarrollo para y con Electron.\n| ├── fiddles/ - Un conjunto de fragmento de codigo que pueden ejecutarse en Electron Fiddle.\n| ├── images/ - Imágenes usadas en la documentación.\n| └── tutorial/ - Documentos tutoriales para diversos aspectos de Electron.\n├── lib/ - Código fuente JavaScript/TypeScript.\n| ├── browser/ - Código de inicialización del proceso principal.\n| | ├── api/ - API de implementación para los módulos del proceso principal.\n| | └── remote/ - Código relacionado con el modulo remote como es usado en el proceso principal.\n| ├── common/ - Relacionado con la logica necesario por ambos procesos el main y el renderer.\n| | └── api/ - Implementación de API para módulos que pueden \n| | ser usadas en ambos procesos main y renderer\n| ├── isolated_renderer/ - Maneja la creación de procesos renderer isolados cuando\n| | contextIsolation esta habilitado.\n| ├── renderer/ - Código de inicialización del proceso renderer.\n| | ├── api/ - Implementación de la API para los módulos del proceso renderer.\n| | ├── extension/ - Código relacionado con el uso de las Extenciones de Chrome\n| | | en el proceso renderer de Electron.\n| | ├── remote/ - Logic that handles use of the remote module in\n| | | the main process.\n| | └── web-view/ - Lógica que maneja el uso de los webviews en el \n| | proceso renderer.\n| ├── sandboxed_renderer/ - Lógica que maneja la creación de procesos \n| | | renderer sandboxed.\n| | └── api/ - Implementación para procesos renderer sandboxed.\n| └── worker/ - Lógica que maneja la correcta funcionalidad de Node.js\n| en los entornos Web Workers.\n├── patches/ - Parches aplicados encima de las dependencias core \n| | de Electron para manejar las diferencias ente nuestro casos de uso \n| | y la configuración por defecto.\n| ├── boringssl/ - Parches aplicados a los forks de Google OpenSSL, BoringSSL.\n| ├── chromium/ - Parches aplicados a Chromium.\n| ├── node/ - Parches aplicados encima de Node.js.\n| └── v8/ - Parches aplicados encima del motor V8 de Google.\n├── shell/ - Código fuente C++.\n| ├── app/ - System entry code.\n| ├── browser/ - The frontend including the main window, UI, and all of the\n| | | main process things. This talks to the renderer to manage web\n| | | pages.\n| | ├── ui/ - Implementation of UI stuff for different platforms.\n| | | ├── cocoa/ - Cocoa specific source code.\n| | | ├── win/ - Windows GUI specific source code.\n| | | └── x/ - X11 specific source code.\n| | ├── api/ - The implementation of the main process APIs.\n| | ├── net/ - Network related code.\n| | ├── mac/ - Mac specific Objective-C source code.\n| | └── resources/ - Icons, platform-dependent files, etc.\n| ├── renderer/ - Code that runs in renderer process.\n| | └── api/ - The implementation of renderer process APIs.\n| └── common/ - Código que se usa por ambos procesos, main y el renderer, incluye algunos funciones útiles\n| | y código para integrar el bucle de mensaje de node dentro de bucle de mensaje de Chromium.\n| └── api/ - La implementación de las APIs comunes y las bases de los módulos integrados de Electron.\n├── spec/ - Componentes de la suite de pruebas de Electron se ejecutan en el proceso de renderizado.\n├── spec-main/ - Componentes de la suite de pruebas de Electron se ejecutan en el proceso main.\n└── BUILD.gn - Building rules of Electron.\nscript/create-dist.py cuando se crea una distribución.ninja.script/ - El conjunto de todo los scripts que Electron ejecuta para una variedad de propósitos.\n├── codesign/ - Falsifica la firma de código para aplicaciones Electron; usado para pruebas.\n├── lib/ - Varios scripts de utilidad de python.\n└── release/ - Scripts que se ejecutan durante el proceso de lanzamiento de Electron.\n ├── notes/ - Genera notas de lanzamiento para las nuevas versiones de Electron.\n └── uploaders/ - Sube varios archivos relacionados con la nueva versión durante el lanzamiento.\nElectron has built-in support for Chromium's spellchecker since Electron 8. On Windows and Linux this is powered by Hunspell dictionaries, and on macOS it makes use of the native spellchecker APIs.
\nFor Electron 9 and higher the spellchecker is enabled by default. For Electron 8 you need to enable it in webPreferences.
const myWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: true\n }\n})\nOn macOS as we use the native APIs there is no way to set the language that the spellchecker uses. By default on macOS the native spellchecker will automatically detect the language being used for you.
\nFor Windows and Linux there are a few Electron APIs you should use to set the languages for the spellchecker.
\n// Sets the spellchecker to check English US and French\nmyWindow.session.setSpellCheckerLanguages(['en-US', 'fr'])\n\n// An array of all available language codes\nconst possibleLanguages = myWindow.session.availableSpellCheckerLanguages\nBy default the spellchecker will enable the language matching the current OS locale.
\nAll the required information to generate a context menu is provided in the context-menu event on each webContents instance. A small example of how to make a context menu with this information is provided below.
const { Menu, MenuItem } = require('electron')\n\nmyWindow.webContents.on('context-menu', (event, params) => {\n const menu = new Menu()\n\n // Add each spelling suggestion\n for (const suggestion of params.dictionarySuggestions) {\n menu.append(new MenuItem({\n label: suggestion,\n click: () => mainWindow.webContents.replaceMisspelling(suggestion)\n }))\n }\n\n // Allow users to add the misspelled word to the dictionary\n if (params.misspelledWord) {\n menu.append(\n new MenuItem({\n label: 'Add to dictionary',\n click: () => mainWindow.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord)\n })\n )\n }\n\n menu.popup()\n})\nAlthough the spellchecker itself does not send any typings, words or user input to Google services the hunspell dictionary files are downloaded from a Google CDN by default. If you want to avoid this you can provide an alternative URL to download the dictionaries from.
\nmyWindow.session.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/')\nRevisa la documentación para session.setSpellCheckerDictionaryDownloadURL para más información sobre dónde obtener los archivos de diccionario y como necesitas alojarlos.
Estas son las directrices para escribir documentación de Electron.
\n# al principio.##.# en el encabezado de acuerdo al su profundidad de anidamiento.Usando Quick Start como ejemplo:
# Inicio rápido\n\n...\n\n## Proceso principal\n\n...\n\n## Proceso Renderer\n\n...\n\n## Ejecuta tu aplicación\n\n...\n\n### Ejecuta como una distribución\n\n...\n\n### Binario Electron descargado manualmente\n\n...\nPara referencias API, hay excepciones para esta regla.
\nThis repository uses the markdownlint package to enforce consistent Markdown styling. For the exact rules, see the .markdownlint.json file in the root folder.
There are a few style guidelines that aren't covered by the linter rules:
\n\nsh en vez de cmd en code blocks (debido al resaltador de sintaxis).js y javascript están analizados con standard-markdown.Las siguientes reglas sólo se aplican a la documentación de APIs.
\nEach module's API doc must use the actual object name returned by require('electron') as its title (such as BrowserWindow, autoUpdater, and session).
Directly under the page title, add a one-line description of the module as a markdown quote (beginning with >).
Using the session module as an example:
# session\n\n> Administra sesiones de navegador, cookies, caché, configuración del proxy, etc.\nPara módulos que no son clases, sus métodos y los eventos deben esar listados bajo los capítulos ## Métodos y ## Eventos.
Usando autoUpdater como ejemplo:
# autoUpdater\n\n## Eventos\n\n### Evento: 'error'\n\n## Métodos\n\n### `autoUpdater.setFeedURL(url[, requestHeaders])`\n## clase: TheClassName.###-level headings.### Static Methods chapter.### Instance Methods chapter.[TYPE] - [Return description]\"Object, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.### Eventos de Instancia.### Instance Properties.Usando las clases Session y Cookies como ejemplo:
# session\n\n## Methods\n\n### session.fromPartition(partition)\n\n## Static Properties\n\n### session.defaultSession\n\n## Class: Session\n\n### Instance Events\n\n#### Event: 'will-download'\n\n### Instance Methods\n\n#### `ses.getCacheSize()`\n\n### Instance Properties\n\n#### `ses.cookies`\n\n## Class: Cookies\n\n### Instance Methods\n\n#### `cookies.get(filter, callback)`\nEl capítulo de métodos debe estar de la siguiente forma:
\n### `nombreDeObjeto.nombreDeMetodo(required[, opcional]))`\n\n* `required` String - Una descripción del parámetro.\n* `opcional` Integer (opcional) - Otra descripción del parámetro.\n\n...\nThe heading can be ### or ####-levels depending on whether the method belongs to a module or a class.
Para módulos, el objectName es el nombre del módulo. Para las clases debe ser el nombre de la instancia de la clase y no debe ser el mismo nombre del módulo.
Por ejemplo, los métodos de la clase Session bajo el módulo session deben usar ses como el objectName.
Optional arguments are notated by square brackets [] surrounding the optional argument as well as the comma required if this optional argument follows another argument:
requerido[, opcional]\nMore detailed information on each of the arguments is noted in an unordered list below the method. The type of argument is notated by either JavaScript primitives (e.g. String, Promise, or Object), a custom API structure like Electron's Cookie, or the wildcard any.
If the argument is of type Array, use [] shorthand with the type of value inside the array (for example,any[] or String[]).
If the argument is of type Promise, parametrize the type with what the promise resolves to (for example, Promise<void> or Promise<String>).
If an argument can be of multiple types, separate the types with |.
La descripción para los argumentos de tipo Function deben dejar en claro cómo podrían ser llamados y la lista de tipos de parámetros que se le serán pasados.
Si un argumento o un método es único para ciertas plataformas, esas plataformas son denotadas usando una lista con espacio delimitado y en cursiva siguiendo el tipo de data. Los valores pueden ser macOS, Windows, o Linux.
* `animate` Booleano (opcional) _macOS_ _Windows_ - Anima la cosa.\nEl capítulo de eventos debe estar de la siguiente forma:
\n### Evento: 'wake-up'\n\nDevuelve:\n\n* `time` String\n\n...\nThe heading can be ### or ####-levels depending on whether the event belongs to a module or a class.
Los argumentos de un evento siguen las mismas reglas que los métodos.
\nEl capítulo de propiedades debe estar de la siguiente forma:
\n### session.defaultSession\n\n...\nThe heading can be ### or ####-levels depending on whether the property belongs to a module or a class.
Si tiene un problema de seguridad, consulte el documento de seguridad.
\nSi busca ayuda con la programación, respuestas a preguntas o conversaciones con otros desarrolladores que usan Electron, puede interactuar con la comunidad en estos lugares:
\nElectron's Discord tiene canales para:electron en los foros de Atom#electron canal en Atom's Slackelectron-ru (Ruso)electron-br (Portugués Brasileño)electron-kr (Coreano)electron-jp (Japonés)electron-tr (Turco)electron-id (Indonesio)electron-pl (Polaco)Si desea contribuir a Electron, consulte el documento contribuyente.
\nSi has encontrado un error en una versión soportada de Electron, infórmalo con el rastreador de problemas.
\nawesome-electron es una lista mantenida por la comunidad de útiles ejemplos de aplicaciones, herramientas y recursos.
\nNote: Beginning in September 2021 with Electron 15, the Electron team will temporarily support the latest four stable major versions. This extended support is intended to help Electron developers transition to the new eight week release cadence, and will continue until May 2022, with the release of Electron 19. At that time, the Electron team will drop support back to the latest three stable major versions.
\nLas últimas tres versiones stable son soportadas por el equipo Electron. Por ejemplo, si la última versión es 6.1.x, entonces la 5.0.x así como la series 4.2.x son soportadas. Solo soportamos la última versión minor por cada versión estable. Esto quiere decir que en el caso de una corrección de seguridad 6.1.x recibirá la corrección, pero no lanzaremos una nueva versión de 6.0.x.
\nLa última versión estable recibe unilateralmente todas las correcciones de main, y la versión anterior recibe la gran mayoría de esas correcciones como el tiempo y el ancho de banda lo permite. Las versiones más antiguas soportadas solamente van a recibir correcciones de seguridad directamente.
Todas las versiones soportadas aceptarán peticiones de pull requests externas a backport correcciones previamente fusionadas en main, aunque esto puede ser caso por caso para algunas versiones mas antiguas. Todas las decisiones impugnadas entorno a la liberación de la versión de backports serán resueltas por el Releases Working Group como un elemento de agenda en su reunión semanal la semana que se levanta el PR backport.
Cuando una API es cambiada o eliminada de alguna manera eso rompe la funcionalidad existente, la funcionalidad anterior será mantenida por mínimo dos versiones principales cuando sea posible antes de eliminarla. For example, if a function takes three arguments, and that number is reduced to two in major version 10, the three-argument version would continue to work until, at minimum, major version 12. Past the minimum two-version threshold, we will attempt to support backwards compatibility beyond two versions until the maintainers feel the maintenance burden is too high to continue doing so.
\nCuando una rama de lanzamiento llega al final de su ciclo de soporte, la serie quedará obsoleta en NPM y se realizará una versión final de fin de soporte. Este lanzamiento agregará una advertencia para informar que una versión no soportada de Electron está en uso.
\nEstos pasos son para ayudar a los desarrolladores de aplicaciones a saber cuándo una rama que están utilizando no recibe soporte, pero sin ser excesivamente intrusiva para los usuarios finales.
\nSi una aplicación tiene circunstancias excepcionales y necesita permanecer en una serie de Electron no admitida, los desarrolladores pueden silenciar la advertencia de fin de soporte al omitir la versión final de package.json devDependencies de la aplicación. Por ejemplo, dado que la serie 1-6-x finalizó con una versión 1.6.18 de fin de soporte, los desarrolladores podrían optar por permanecer en la serie 1-6-x sin advertencias con un devDependency de \"electron\": 1.6.0 - 1.6.17.
Las siguientes plataformas son apoyadas por Electron:
\nOnly 64bit binaries are provided for macOS, and the minimum macOS version supported is macOS 10.11 (El Capitan).
\nEl soporte nativo para dispositivos Apple Silicon (arm64) fue agregado en Electron 11.0.0.
Windows 7 y posteriores son soportados, sistemas operativos más viejos no lo son (y no funcionan).
\nAmbos binarios ia32 (x86) y x64 (amd64) se proporcionan para Windows. Soporte nativo para Windows en dispositivos Arm (arm64) fue agregado a Electron 6.0.8.. Running apps packaged with previous versions is possible using the ia32 binary.
Los binarios preconstruido de Electron están construidos en Ubuntu 18.04.
\nSi el compilado binario puede correr en una distribución depende de que la distribución incluye las librerías a las que está ligada Electron en la plataforma construida, así que solo hay garantía de que Ubuntu 18.04 trabaje, pero las siguientes plataformas también están verificadas para correr el precompilado binario de Electron:
\n\n\nComo utilizar Node.js y los APIs de Electrón.
\n
Todos los módulos incorporados de Node.js está disponibles en Electrón y los nodos de terceros también son completamente compatibles (incluyendo a los módulos nativos).
\nElectrón además provee algunos módulos incorporados extra para desarrollar aplicaciones de escritorio nativas. Some modules are only available in the main process, some are only available in the renderer process (web page), and some can be used in either process type.
\nLa regla básica es: si un módulo es GUI o relacionado a sistemas de bajo nivel, entonces solo puede estar disponible en el proceso principal. You need to be familiar with the concept of main process vs. renderer process scripts to be able to use those modules.
\nEl scrip del proceso principal es como un script normal de Node.js:
\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL('https://github.com')\n})\nEl renderer process no es diferente a una página web normal, excepto por la habilidad extra de usar módulos node si nodeIntegration está activada:
\n<html>\n<body>\n<script>\n const fs = require('fs')\n console.log(fs.readFileSync(__filename, 'utf8'))\n</script>\n</body>\n</html>\nRespecto al 0.37, puedes usar asignación de desestruturación para hacer más fácil el uso de los módulos incorporados.
\nconst { app, BrowserWindow } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nSi necesitas el módulo electron completo, puedes requerirlo y luego usar la desestructuración para acceder a los módulos individuales desde electron.
const electron = require('electron')\nconst { app, BrowserWindow } = electron\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nEste es equivalente al siguiente código:
\nconst electron = require('electron')\nconst app = electron.app\nconst BrowserWindow = electron.BrowserWindow\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\n\n\nObtener las preferencias del sistema.
\n
Proceso: principal</0>
\nconst { systemPreferences } = require('electron')\nconsole.log(systemPreferences.isDarkMode())\nEl objeto de lossistemasdePreferenciasemiten los siguietes eventos:
Devuelve:
\neventnuevoColor String - El nuevo color RGBA que el usuario asignó para ser su color de acento del sistema.Devuelve:
\neventDevuelve:
\neventinvertedColorScheme Boolean - true si un esquema de color invertido (un esquema de color de alto contraste con texto claro y fondos oscuros) se esta usando, de otra manera false.Obsoleto: Debería usar el nuevo evento updated en el módulo nativeTheme.
Devuelve:
\neventhighContrastColorScheme Boolean - true si un tema de alto contraste es esta empezando a usar, de otra manera false.Obsoleto: Debería usar el nuevo evento updated en el módulo nativeTheme.
systemPreferences.isDarkMode() macOS Windows DeprecatedDevuelve Boolean - Aunque el sistema esté en modo oscuro.
Obsoleto: Debería usar la nueva API nativeTheme.shouldUseDarkColors.
systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOSDevuelve Boolean - Aunque el ajuste de cambio entre páginas esté activado.
systemPreferences.postNotification(event, userInfo) macOSevento CadenauserInfo<String, any>deliverImmediately Boolean (Opcional) - true para publicar inmediatamente incluso cuando la aplicación esta inactiva.Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postLocalNotification(event, userInfo) macOSevento CadenauserInfo<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postWorkspaceNotification(event, userInfo) macOSevento CadenauserInfo<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.subscribeNotification(event, callback) macOSevento Cadenacallback Funciónevento CadenauserInfo<String, unknown>objectDevuelve Number - El ID de la suscripción
Subscriptores a notificaciones nativas de macOS, callback serán llamados con callback(evento, userinfo) cuando el evento correspondiente suceda. El userInfo es un Objeto que contiene el diccionario de la información de usuario enviado junto a las notificaciones. El object es el remitente de la notificación y solo soporta valores NSString por ahora.
El id del subscriptor es devuelto, el cual puede ser usado para desuscribir el evento.
Bajo de la capucha este API subscribe a NSDistributedNotificationCenter, valores de ejemplo de evento son:
AppleInterfaceThemeChangedNotificationAppleAquaColorVariantChangedAppleColorPreferencesChangedNotificationAppleShowScrollBarsSettingChangedsystemPreferences.subscribeLocalNotification(event, callback) macOSevento Cadenacallback Funciónevento CadenauserInfo<String, unknown>objectDevuelve Number - El ID de la suscripción
Same as subscribeNotification, but uses NSNotificationCenter for local defaults. Esto es necesario para eventos como NSUserDefaultsDidChangeNotification.
systemPreferences.subscribeWorkspaceNotification(event, callback) macOSevento Cadenacallback Funciónevento CadenauserInfo<String, unknown>objectDevuelve Number - El ID de la suscripción
Igual que subscribeNotification, pero utiliza NSWorkspace.sharedWorkspace.notificationCenter. Esto es necesario para eventos como NSWorkspaceDidActivateApplicationNotification.
systemPreferences.unsubscribeNotification(id) macOSid ÍntegroRemueve el subscriptor con el id.
systemPreferences.unsubscribeLocalNotification(id) macOSid ÍntegroAl igual que unsubscribeNotification, pero remueveal subscritor de NSNotificationCenter.
systemPreferences.unsubscribeWorkspaceNotification(id) macOSid ÍntegroIgual que unsubscribeNotification, pero remueve el subscriptor desde NSWorkspace.sharedWorkspace.notificationCenter.
systemPreferences.registerDefaults(defaults) macOSdefaults Record<String, String | Boolean | Number> - un diccionario de valores por de defectos del usuario (key: value)Agregue los valores predeterminados especificados a NSUserDefaults de su aplicación.
systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOSllave Cadenatype Type - Can be string, boolean, integer, float, double, url, array or dictionary.Returns UserDefaultTypes[Type] - The value of key in NSUserDefaults.
Algún key y types populares:
AppleInterfaceStyle: stringAppleAquaColorVariant: integerAppleHighlightColor: stringAppleShowScrollBars: stringNSNavRecentPlaces: arrayNSPreferredWebServices: dictionaryNSUserDictionaryReplacementItems: arraysystemPreferences.setUserDefault(key, type, value) macOSllave Cadenatype String - Can be string, boolean, integer, float, double, url, array or dictionary.value CadenaEstablece el valor de key en NSUserDefaults.
Note that type should match actual type of value. An exception is thrown if they don't.
Algún key y types populares:
ApplePressAndHoldEnabled: booleansystemPreferences.removeUserDefault(key) macOSllave CadenaElimina el key en NSUserDefaults. This can be used to restore the default or global value of a key previously set with setUserDefault.
systemPreferences.isAeroGlassEnabled() WindowsDevuelve Boolean - true si DWM composition (Aero Glass) está habilitada, y false de lo contrario.
Un ejemplo de usarlo para determinar si deberías crear una ventana transparente o no (las ventanas transparentes no funcionarán correctamente cuando la composición de DWM está deshabilitada):
\nconst { BrowserWindow, systemPreferences } = require('electron')\nconst browserOptions = { width: 1000, height: 800 }\n\n// Make the window transparent only if the platform supports it.\nif (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {\n browserOptions.transparent = true\n browserOptions.frame = false\n}\n\n// Create the window.\nconst win = new BrowserWindow(browserOptions)\n\n// Navigate.\nif (browserOptions.transparent) {\n win.loadURL(`file://${__dirname}/index.html`)\n} else {\n // No transparency, so we load a fallback that uses basic styles.\n win.loadURL(`file://${__dirname}/fallback.html`)\n}\nsystemPreferences.getAccentColor() Windows macOSDevuelve Cadena - El sistema actual de usuarios amplía el acento del color de preferencia en la forma hexadecimal de RGBA.
const color = systemPreferences.getAccentColor() // `\"aabbccdd\"`\nconst red = color.substr(0, 2) // \"aa\"\nconst green = color.substr(2, 2) // \"bb\"\nconst blue = color.substr(4, 2) // \"cc\"\nconst alpha = color.substr(6, 2) // \"dd\"\nEsta API solo esta disponible desde macOS 10.15 Mojave or posteriores.
\nsystemPreferences.getColor(color) Windows macOScolor String - One of the following values:3d-dark-shadow - Sombra oscura para elementos de tres dimensiones mostrados.3d-face - Color facial para elementos de tres dimensiones mostrados y para cuadro de fondos de las caja de diálogo.3d-highlight - Resalta color para elementos de tres dimensiones mostrados.3d-light - Color claro para elementos de tres dimensiones mostrados.3d-shadow - Color oscuro para elementos de tres dimensiones mostrados.active-border - Borde de ventana activo.active-caption - Active window title bar. Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.active-caption-gradient - El color del lado derecho en el tono del color de un título de barra de una ventana activa.app-workspace - Color de fondo de múltiples documentos de aplicaciones de interfase.button-text - Texto en los botones de presión.caption-text - Textos en subtítulos, tamaño de la caja y la barra de desplazamiento de la caja de flecha.desktop - Color de fondo del escritorio.disabled-text - Gris (desactivado) texto.highlight - objeto(s) seleccionados en un control.highlight-text - Texto de objeto(s) seleccionados en un control.hotlight - Color para un hiperlink o un muy rastreado objeto.inactive-border - Borde de ventana inactivo.inactive-caption - Inactive window caption. Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.inactive-caption-gradient - Color del lado derecho en el tono de color de un título de barra de una ventana inactiva.inactive-caption-text - Color del texto en un subtítulo inactivo.info-background - Color de fondo para control de información de herramientas.info-text - Color de texto para controles de información de herramientas.menu - Fondo del menú.menu-highlight - El color usado para resaltar los objetos del menú cuando el menú aparece como un menú plano.menubar - El color de fondo para la barra del menú cuando los menús aparecen como menús planos.menu-text - Textos en menús.scrollbar - Desplazar la barra en el área gris.window - Fondo de la ventana.window-frame - Cuadro de ventana.window-text - Texto en ventanas.alternate-selected-control-text - Texto en una superficie selecciona, en una lista o en una tabla. deprecatedcontrol-background - El fondo de un elemento de interfaz grande, tal como un navegador o tablet.control - La superficie de un control.control-text - El texto de un control que no está deshabilitado.disabled-control-text - El texto de un control que esta deshabilitado.find-highlight - El color de un indicador de búsqueda.grid - Las líneas de cuadrículas de un elemento de interfaz como una tabla.header-text - El texto de una celda de cabecera en una tabla.highlight - La fuente de luz virtual en la pantalla.keyboard-focus-indicator - El anillo que aparece alrededor del control actualmente enfocado cuando se usa el teclado para la nevagación por la interface.label - El texto de una etiqueta que contiene el contenido primario.link - Un enlace a otro contenido.placeholder-text - Una cadena de marcador de posición en una vista de control o texto.quaternary-label - El texto de una etiqueta de menor importancia que una etiqueta terciaria como el texto de la marca de agua.scrubber-textured-background - El fonfo de un depurado en el Touch Bar.secondary-label - El texto de una etiqueta de menor importancia que una etiqueta normal como el usado para representar un subtítulo o información adicional.selected-content-background - El fondo para el contenido seleccionado en una ventana clave o en una vista.selected-control - La superficie de un control seleccionado.selected-control-text - El texto un control seleccionado.selected-menu-item-text - El texto del menú seleccionado.selected-text-background - El fondo de un texto seleccionado.selected-text - Texto seleccionado.separator - Un separado entre las diferentes secciones del contenido.shadow - La sombra virtual proyectada por un objeto en la pantalla.tertiary-label - El texto para una etiqueta de menor importancia que una etiqueta secundaria como una etiqueta que se usa para representar texto deshabilidato.text-background - Texto de fondo.text - Texto en un documento.under-page-background - El fondo detrás del contenido de un documento.unemphasized-selected-content-background - El contenido seleccionado en una ventana o vista no-clave.unemphasized-selected-text-background - Un fondo para el texto seleccionado en una ventana o vista no clave.unemphasized-selected-text-background - Texto seleccionado en una ventana o vista no clave.window-background - El fondo de una ventana.window-frame-text - El texto en la area de la barra de título de la ventana.Devuelve String - El color del sistema ajustando en la forma hexadecimal de RGB (#ABCDEF). Vea el Windows docs y el macOS docs para más detalles.
Los siguientes colores solo están disponibles en macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, y unemphasized-selected-text.
systemPreferences.getSystemColor(color) macOScolor String - One of the following values:azulmarróngrisverdenaranjarosapúrpurarojoamarilloDevuelve String - El sistema de color estándar formateado como #RRGGBBAA.
Devuelve uno de los varios colores estándar del sistema que se adaptan automáticamente a la vibración y los cambios en los ajustes de accesibilidad como \"Aumentar contraste\" y \"reducir transparencia\". Ver Apple Documentation para mas detalles.
\nsystemPreferences.isInvertedColorScheme() Windows DeprecatedReturns Boolean - true si un esquema de color invertido (un esquema de color de alto contraste con texto claro y fondo oscuro) está activo. De otra manera false.
Obsoleto: Debería usar la nueva API nativeTheme.shouldUseInvertedColorScheme.
systemPreferences.isHighContrastColorScheme() macOS Windows DeprecatedDevuelve Boolean - true si un tema de alto contraste está activo, si no false.
Deprecated: Use la nueva API de nativeTheme.shouldUseHighContrastColors.
systemPreferences.getEffectiveAppearance() macOSDevuelve String - Puede ser dark, light o unknown.
Obtiene confiración de la apariencia de macOS que está actulemente aplicada, mapea a NSApplication.effectiveAppearance
\nsystemPreferences.getAppLevelAppearance() macOS DeprecatedDevuelveString | null - Puede ser dark, light o unknown.
Obtiene la configuración de apariencia de macOS que has declarado que desea para su aplicación, mapea a NSApplication.appearance. Puedes usar la API setAppLevelAppearance para establecer este valor.
systemPreferences.setAppLevelAppearance(appearance) macOS Deprecatedappearance String | null - Puede ser dark o lightEstablece la configuración por defecto para su aplicación, esto debe sobrescribir el valor predeterminado del sistema y sobrescribir el valor de getEffectiveAppearance.
systemPreferences.canPromptTouchID() macOSDevuelve Boolean - si este dispositivo tiene la habilidad para usar Touch ID.
NOTE: Esta API retornará false en sistemas macOS mas viejos que Sierra 10.12.2.
systemPreferences.promptTouchID(reason) macOSreason String - La razón por la que estás pidiendo por la autenticación Touch IDDevuelve Promise<void> - Se resuelve si el usuario se ha autenticado con éxito con Touch ID.
const { systemPreferences } = require('electron')\n\nsystemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {\n console.log('You have successfully authenticated with Touch ID!')\n}).catch(err => {\n console.log(err)\n})\nEsta API en si misma no va a proteger sus datos de usuario, más bien, es un mecanismo para permitirle hacerlo. Native apps will need to set Access Control Constants like kSecAccessControlUserPresence on their keychain entry so that reading it would auto-prompt for Touch ID biometric consent. Esto se podría hacer con node-keytar, de tal manera que se almacenaría una clave de cifrado con node-keytar u sólo se obtendría si promptTouchID() se resuelve.
NOTE: Esta API retornara una promesa rechazada en sistemas macOS más viejos que Sierra 10.12.2.
\nsystemPreferences.isTrustedAccessibilityClient(prompt) macOSprompt Boolean - Si el usuario será informado o no vía prompt si el proceso actual no es confiable.Devuelve Boolean - true si el proceso actual es un cliente de accesibilidad de confianza y false si no lo es.
systemPreferences.getMediaAccessStatus(mediaType) Windows macOSmediaType String - Puede ser microphone, camera o screen.Devuelve String - Puede ser not-determined, granted, denied, restricted o unknown.
Este consentimiento de usuario no fue requerido en macOS 10.13 High Sierra o anteriores por lo tanto este método siempre devolverá granted. macOS 10.14 Mojave o superior requiere consentimiento para acceso a microphone y camera. macOS 10.15 Catalina o superior requiere consentimiento para acceso a screen.
Windows 10 has a global setting controlling microphone and camera access for all win32 applications. It will always return granted for screen and for all media types on older versions of Windows.
systemPreferences.askForMediaAccess(mediaType) macOSmediaType String - el tipo de medio que se solicita; puede ser microphone, camera.Devuelve Promise<Boolean> - Una promesa que resuelve con true se fue concedido el consentimiento y false si fue denegado. Si un mediaType invalido es pasado, la promesa será rechazada. Si se negó una solicitud de acceso y después se cambia a través del panel de Preferencias del Sistema, se requerirá un reinicio de la aplicación para que los nuevos permisos surtan efecto. Si el acceso ya ha sido solicitado y denegado, must ser cambiado a través del panel de preferencias; una alerta no aparecerá y la promesa resolverá con el estado de acceso existente.
Important: Para poder aprovechar correctamente esta API, debes must set las cadenas NSMicrophoneUsageDescription y NSCameraUsageDescription en el archivo Info.plist de tu aplicación. Los valores para estas claves se utilizarán para rellenar los diálogos de permisos para que el usuario sea informado correctamente sobre el propósito de la solicitud de permiso. Mira Electron Application Distribution para más información acerca de como establecer estos en el contexto de Electron.
Este consentimiento de usuario no fue requerido hasta macOS 10.14 Mojave, por lo que este método siempre devolverá true si su sistema está ejecutando 10.13 High Sierra o inferior.
systemPreferences.getAnimationSettings()Devuelve Objeto:
shouldRenderRichAnimation Boolean - Devuelve verdadero is animaciones ricas deben ser renderizadas. Se observa en el tipo de sesión (por ejemplo, escritorio remoto) y ajustes de accesibilidad para dar orientación a animaciones pesadas.scrollAnimationsEnabledBySystem Boolean - Determina sobre una base por plataforma si las animaciones de desplazamiento (por ejemplo, producidas por la clave home/end) deben estar habilitadas.prefiere ReducdMotion Boolean - Determina si el usuario desea un movimiento reducido basado en APIs de la plataforma.Devuelve un objeto con las configuraciones del sistema de animación.
\nsystemPreferences.appLevelAppearance macOSUna propiedad String que puede ser dark, light o unknown. Determina la configuración de apariencia de macOS para tu aplicación. Esto mapea a valores en NSApplication.appearance. Establecer esto sobrescribirá el valor por defecto de sistema así como el valor de getEffectiveAppearance.
Posibles valores que se pueden configurar son dark y light y posibles valores de retorno son dark, light y unknown.
Esta propiedad solo está disponible en macOS 10.14 Mojave o posteriores.
\nsystemPreferences.effectiveAppearance macOS SoloLecturaUna propiedad String que puede ser dark, light o unknown.
Devuelve la configuración de apariencia de macOS que esta aplicada actualmente a tu aplicación mapea a NSApplication.effectiveAppearance
", "title": "systemPreferences", "description": "Obtener las preferencias del sistema." }, "/docs/api/structures/task": { "locale": "es-ES", "slug": "task", "href": "/docs/api/structures/task", "crowdinFileId": "256513", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/task.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "program String - Path of the program to execute, usually you should specify process.execPath which opens the current program.arguments String - The command line arguments when program is executed.title String - The string to be displayed in a JumpList.description String - Description of this task.iconPath String - The absolute path to an icon to be displayed in a JumpList, which can be an arbitrary resource file that contains an icon. You can usually specify process.execPath to show the icon of the program.iconIndex Number - The icon index in the icon file. If an icon file consists of two or more icons, set this value to identify the icon. If an icon file consists of one icon, this value is 0.workingDirectory String (optional) - The working directory. Default is empty.Nuestro objetivo es mantener la cobertura de código de electrón alto. Pedimos que todas la solicitudes de extracción requeridas no solo pasen todas las pruebas existentes, lo ideal seria añadir nuevas pruebas para cubrir los cambios en el código y nuevos escenarios. Asegurando que capturamos muchas rutas de código y casos de uso de Electrón es posible asegurar que todas las aplicaciones tengan menos errores.
\nEste repositorio viene con reglas de borrado tanto para JavaScript como para C++ – así como pruebas de unidad e integración. Para aprender más sobre el estilo de código de Electron, por favor vea el documento coding-style.
\nAsegúrese de que su JavaScript cumpla con la codificación de Electron estilo, run npm run lint-js, que se ejecutara standard contra ambos tanto el propio electrón, así como las pruebas unitarias. Si estás usando un editor con un sistema de plugin/addon, es posible que desees utilizar uno de los muchos Complementos de StandardJS , para estar informado de violaciones de estilo de codificación antes de comprometerlas.
Para ejecutar estándar con parámetros, ejecute npm run lint-js -- seguido de los argumentos que quieras pasar a estándar.
Para garantizar que tu C ++ cumpla con el estilo de codificación de electrones, ejecuta npm run lint-cpp, que ejecuta un script cpplint. Le recomendamos que utilice el Formato clang y se prepare con un breve tutorial.
No hay mucho de Python en este repositorio, pero también se rige por las reglas de estilo de código. npm run lint-py comprobará todo el Python, usando pylint para hacerlo.
Si no está usando build-tools, asegúrese de que el nombre que ha configurado para su compulación local de Electron is uno de Testing, Release, Default, Debug, o ha establecido process.env.ELECTRON_OUT_DIR. Sin estos conjuntos, Electron fallará al realizar algunos pasos previos a la prueba.
Para ejecutar todas las pruebas de unidad, ejecute npm run test. Las pruebas de unidad son una aplicación de Electrón(¡sorpresa!) que puede encontrarse en la carpeta de spec. Tenga en cuenta que tiene su propio package.json y que sus dependencias por lo tanto no se definen en el nivel superior package.json.
Para correr solo pruebas especificas que coincidan con un patrón, corra npm run test -- -g=PATTERN, reempleazando el PATTERN con una expresión regular que coinciden con los test que le gustaría correr. Como un ejemplo: Si solo quiere correr pruebas IPC, usted debería correr npm run test -- -g ipc.
Visual Studio 2019 debe estar instalado.
\nLas cabeceras de Node han de estar compiladas para tu configuración.
\nninja -C out\\Testing third_party\\electron_node:headers\nEl electron.lib ha de ser copiada como node.lib.
\ncd out\\Testing\nmkdir gen\\node_headers\\Release\ncopy electron.lib gen\\node_headers\\Release\\node.lib\nAlgunos dispositivos Windows 10 no se incluye la fuente Meiryo instalada, lo que puede causar que falle una prueba. Para instalar Meiryo:
\nAlgunas pruebas que dependen de medidas precisas a nivel de píxel pueden no funcionar correctamente en dispositivos con ajustes de pantalla Hi-DPI debido a errores de precisión de puntos flotantes. Para ejecutar correctamente estas pruebas, asegúrese de que el dispositivo está fijado para escalar el 100%.
\nPara configurar el escalamiento de pantalla:
\nAl estar basado en Chromium, Electron requiere un controlador para funcionar. Si chromium no puede encontrar un controlador de pantalla, Electron no se lanzará y por lo tanto no ejecuta ningunas de sus pruebas, independientemente de como usted las está corriendo. Probar aplicaciones basadas en Electron en Travis, Circle, Jenkins o sistemas similares requiere un poco de configuración. En esencia, necesitamos un controlador de pantalla virtual.
\nPrimero, instala Xvfb. Es un framebuffer virtual, implementando el protocolo de servidor de pantalla X11 - realiza todas las operaciones gráficas en la memoria sin mostrar nada en el monitor, que es exactamente lo que necesitamos.
\nEntonces, crea una pantalla virtual Xvfb y exporta una variable de entorno llamada DISPLAY que apunta a ella. Chromium en electron buscará automáticamente por $DISPLAY, así que su aplicación no requerirá más configuraciones. Este paso puede ser automatizado con Anaïs Betts' xvfb-maybe: prepara tus pruebas de comandos con xvfb-maybe y la pequeña herramienta automáticamente configurará Xvfb, si es requerido por el sistema actual. En Windows o macOS, no hará nada.
## En Windows o macOS, esto invoca electron-mocha\n## En Linux, si estamos en un entorno sin cabeza, esto será equivalente\n## a xvfb-run electron-mocha ./test/*.js\nxvfb-maybe electron-mocha ./test/*.js\nEn Travis, su . travis.yml debería verse más o menos así:
addons:\n apt:\n packages:\n - xvfb\n\ninstall:\n - export DISPLAY=':99.0'\n - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &\nPara Jenkins, un plugin de Xvfb está disponible.
\nCircle CI es impresionante y tiene xvfb y $DISPLAY ya configurados, por lo que no es necesaria ninguna configuración adicional.
AppVeyor corre en Windows, soportando Selenium, Chromium, electron y herramientas fuera de la caja similares - no se requiere configuración.
", "title": "Pruebas de sistemas de CI sin cabeceras (Travis CI, Jenkins)", "description": "" }, "/docs/tutorial/testing-widevine-cdm": { "locale": "es-ES", "slug": "testing-widevine-cdm", "href": "/docs/tutorial/testing-widevine-cdm", "crowdinFileId": "256257", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/testing-widevine-cdm.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "En Electron usted puede usar la librería de Widevine CDM conectado con el navegador Chrome.
\nWidevine Content Decryption Modules (CDMs) es la forma en que los servicios de streaming protegen el contenido utilizando vídeo HTML5 en los navegadores web sin depender de un plugin NPAPI como Flash o Silverlight. El soporte Widevine es un solución alternativa para los servicios de streaming que actualmente depende de Silverlight para la reproducción contenido de video protegidos por DRM. Esto permitirá a sitios web mostrar contenido de video protegidos con DRM en Firefox sin el uso de plugins NPAPI. El Widevine CDM corre en un sandbox open-source que proporciona mejor seguridad que los plugins NPAPI.
\nA partir de Electron v1.8.0 (Chrome v59), los siguientes pasos pueden ser sólo algunos de los pasos necesarios para habilitar Widevine; cualquier aplicación en o después de esa versión que pretenda usar el Widevine CDM puede necesitar firmarse utilizando una licencia obtenida de Widevine en sí mismo.
Por Widevine:
\n\n\nChrome 59 (y superiores) incluyen soporte para Verified Media Path (VMP). VMP proporciona un método para verificar la autenticidad de una plataforma de dispositivos. Para las implementaciones de navegadores, esto proporcionará una señal adicional para determinar si una implementación basada en navegador es fiable y segura.
\nLa guía de integración del proxy ha sido actualizada con información acerca de VMP y como y cómo emitir licencias.
\nWidevine recomienda que nuestras integraciones basadas en el navegador (vendedores y aplicaciones basadas en el navegador) añadan soporte para VMP.
\n
Para habilitar la reproducción de video con esta nueva restricción, ha sido creado castLabs un fork que tiene implementado los cambios necesarios para habilitar Wedevine para ser reproducido en una aplicación Electron si uno ha obtenida las licencias necesarias desde widevine.
\nAbre chrome://components/ en el navegador Chrome, encuentra Widevine Content Decryption Module y asegúrese de que esté actualizado, luego puede encontrar los archivos de la biblioteca desde el directorio de la aplicación.
El archivo de la librería widevinecdm.dll estará en el directorio Program Files(x86)/Google/Chrome/Application/VERSIÓN_DE_CHROME/WidevineCdm/_platform_specific/win_(x86|x64)/.
El archivo de la librería libwidevinecdm.dylib estará en el directorio /Applications/Google Chrome.app/Contents/Versions/VERSIÓN_DE_CHROME/Google Chrome Framework.framework/Versions/A/Libraries/WidevineCdm/_platform_specific/mac_(x86|x64)/.
Nota: Asegúrese de que la versión de Chrome utilizada por Electron sea mayor o igual que el valor min_chrome_version del componente Widevine CDM de Chrome. El valor puede ser encontrado en manifest.json en el directorio WidevineCdm.
Después de obtener los archivos de la librería, usted debe pasar la ruta del archivo con el comando --widevine-cdm-path y la versión de la librería con --widevine-cdm-version. Los comandos deben ser pasados antes de que se emita el evento ready del módulo app.
Código de ejemplo:
\nconst { app, BrowserWindow } = require('electron')\n\n// Tienes que pasar el directorio que contiene la biblioteca de widevine aquí, es\n// * `libwidevinecdm.dylib` en macOS,\n// * `widevinecdm.dll` en Windows.\napp.commandLine.appendSwitch('widevine-cdm-path', '/path/to/widevine_library')\n// La versión del plugin puede ser obtenida desde la pagina `chrome://components` en Chrome.\napp.commandLine.appendSwitch('widevine-cdm-version', '1.4.8.866')\n\nlet win = null\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.show()\n})\nPara verificar si Widevine funciona, puede usar los siguientes métodos:
\nWidevine.bitdash usa Widevine en su navegador, luego reproducir el video.icon NativeImage - The icon showing in thumbnail toolbar.click Functiontooltip String (optional) - The text of the button's tooltip.flags String - Control specific states and behaviors of the button. By default, it is ['enabled'].The flags is an array that can include following Strings:
enabled - The button is active and available to the user.disabled - The button is disabled. It is present, but has a visual state indicating it will not respond to user action.dismissonclick - When the button is clicked, the thumbnail window closes immediately.nobackground - Do not draw a button border, use only the image.hidden - The button is not shown to the user.noninteractive - The button is enabled but not interactive; no pressed button state is drawn. This value is intended for instances where the button is used in a notification.\n\nCrea los diseños de la barra táctil para aplicaciones nativas de macOS
\n
Proceso: principal</0>
\nnew TouchBar(options)options Objectitems (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer)escapeItem (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer | null) (opcional)Crea una nueva barra táctil con los elementos especificados. Use BrowserWindow.setTouchBar para agregar la TouchBar a una ventana.
Nota: La API TouchBar API actualmente es experimental y puede cambiar o ser eliminada en futuras versiones de Electron.
\nTip: If you don't have a MacBook with Touch Bar, you can use Touch Bar Simulator to test Touch Bar usage in your app.
\nTouchBarButtonUn typeof TouchBarButton referencia a la clase TouchBarButton.
TouchBarColorPickerUn typeof TouchBarColorPicker referencia a la clase TouchBarColorPicker.
TouchBarGroupUn typeof TouchBarGroup referencia a la clase TouchBarGroup.
TouchBarLabelUn typeof TouchBarLabel referencia a la clase TouchBarLabel.
TouchBarPopoverUn typeof TouchBarPopover referencia a la clase TouchBarPopover.
TouchBarScrubberUn typeof TouchBarScrubber referencia a la clase TouchBarScrubber.
TouchBarSegmentedControlUn typeof TouchBarSegmentedControl referencia a la clase TouchBarSegmentedControl.
TouchBarSliderUn typeof TouchBarSlider referencia a la clase TouchBarSlider.
TouchBarSpacerUn typeof TouchBarSpacer referencia a la clase TouchBarSpacer.
TouchBarOtherItemsProxyUn typeof TouchBarOtherItemsProxy referencia a la clase TouchBarOtherItemsProxy.
Las siguientes propiedades están disponibles en instancias de TouchBar:
touchBar.escapeItemUn TouchBarItem que reemplazará el botón \"esc\" en la barra táctil cuando se configure. Establecer a null restaura el botón \"esc\" por defecto. Cambiar este valor actualiza inmediatamente el elemento escape en la barra táctil.
A continuación hay un ejemplo de un juego simple de máquina tragaperras con un botón y algunas etiquetas.
\nconst { app, BrowserWindow, TouchBar } = require('electron')\n\nconst { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar\n\nlet spinning = false\n\n// Reel labels\nconst reel1 = new TouchBarLabel()\nconst reel2 = new TouchBarLabel()\nconst reel3 = new TouchBarLabel()\n\n// Spin result label\nconst result = new TouchBarLabel()\n\n// Spin button\nconst spin = new TouchBarButton({\n label: '🎰 Spin',\n backgroundColor: '#7851A9',\n click: () => {\n // Ignore clicks if already spinning\n if (spinning) {\n return\n }\n\n spinning = true\n result.label = ''\n\n let timeout = 10\n const spinLength = 4 * 1000 // 4 seconds\n const startTime = Date.now()\n\n const spinReels = () => {\n updateReels()\n\n if ((Date.now() - startTime) >= spinLength) {\n finishSpin()\n } else {\n // Slow down a bit on each spin\n timeout *= 1.1\n setTimeout(spinReels, timeout)\n }\n }\n\n spinReels()\n }\n})\n\nconst getRandomValue = () => {\n const values = ['🍒', '💎', '7️⃣', '🍊', '🔔', '⭐', '🍇', '🍀']\n return values[Math.floor(Math.random() * values.length)]\n}\n\nconst updateReels = () => {\n reel1.label = getRandomValue()\n reel2.label = getRandomValue()\n reel3.label = getRandomValue()\n}\n\nconst finishSpin = () => {\n const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size\n if (uniqueValues === 1) {\n // All 3 values are the same\n result.label = '💰 Jackpot!'\n result.textColor = '#FDFF00'\n } else if (uniqueValues === 2) {\n // 2 values are the same\n result.label = '😍 Winner!'\n result.textColor = '#FDFF00'\n } else {\n // No values are the same\n result.label = '🙁 Spin Again'\n result.textColor = null\n }\n spinning = false\n}\n\nconst touchBar = new TouchBar({\n items: [\n spin,\n new TouchBarSpacer({ size: 'large' }),\n reel1,\n new TouchBarSpacer({ size: 'small' }),\n reel2,\n new TouchBarSpacer({ size: 'small' }),\n reel3,\n new TouchBarSpacer({ size: 'large' }),\n result\n ]\n})\n\nlet window\n\napp.whenReady().then(() => {\n window = new BrowserWindow({\n frame: false,\n titleBarStyle: 'hiddenInset',\n width: 200,\n height: 200,\n backgroundColor: '#000'\n })\n window.loadURL('about:blank')\n window.setTouchBar(touchBar)\n})\nPara ejecutar el ejemplo anterior, se necesita (asumiendo que la terminal está abierta en el directorio en donde se desea ejecutar el ejemplo):
\ntouchbar.jsnpm install electron./node_modules/.bin/electron touchbar.jsEntonces aparecerá una nueva ventana de Electron y la aplicación se ejecutará en la barra táctil (o en el emulador de la barra táctil).
", "title": "Barra táctil", "description": "Crea los diseños de la barra táctil para aplicaciones nativas de macOS" }, "/docs/api/touch-bar-button": { "locale": "es-ES", "slug": "touch-bar-button", "href": "/docs/api/touch-bar-button", "crowdinFileId": "256375", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/touch-bar-button.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCrea un botón en la barra táctil para aplicaciones macOS nativas
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarButton(options)options ObjectEtiqueta cadena (opcional) - Texto del fondo.accessibilityLabel String (opcional) - Una breve descripción del botón para su uso por lectores de pantalla como VoiceOver.Color del fondo Cadena (opcional) - Color del fondo en formato hex, ejemplo: #ABCDEF.icon NativeImage | String (opcional) - Icono del botón.posición del ícono Cadena (opcional) - Puede ser izquierda, derecha o superpuesto. Por defecto es overlay.click Función (opcional) - Función a llamar cuando se hace click en el fondo.enabled Boolean (optional) - Whether the button is in an enabled state. Por defecto es true.Al definir accessibilityLabel, asegúrese de que ha considerado las mejores prácticas de macOS.
Las siguientes propiedades están disponibles en las instancias de TouchBarButton:
touchBarButton.accessibilityLabelA String representing the description of the button to be read by a screen reader. Will only be read by screen readers if no label is set.
touchBarButton.labelA String representing the button's current text. Changing this value immediately updates the button in the touch bar.
touchBarButton.backgroundColorA String hex code representing the button's current background color. Changing this value immediately updates the button in the touch bar.
touchBarButton.iconUn NativeImage que representa el icono del botón actual. Changing this value immediately updates the button in the touch bar.
touchBarButton.iconPositionA String - Can be left, right or overlay. Por defecto es overlay.
touchBarButton.enabledA Boolean representing whether the button is in an enabled state.
\n\nCrea un seleccionador de color en la barra táctil para aplicaciones nativas de macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarColorPicker(options)options ObjectColores disponibles Cadena - arreglo de códigos hexadecimales de los colores a aparecer como colores posibles a seleccionar.Color seleccionado Cadena (opcional) - El código de color hexadecimal en el seleccionador, ejemplo #ABCDEF.change Function (optional) - Function to call when a color is selected.color Cadena - El color que el usuario seleccionó de entre las opciones.Las siguientes propiedades están disponibles en instancias de Seleccionador de color de la barra táctil:
touchBarColorPicker.availableColorsUn String[] array que representa los colores disponibles del selector de color para seleccionar. Changing this value immediately updates the color picker in the touch bar.
touchBarColorPicker.selectedColorA String hex code representing the color picker's currently selected color. Changing this value immediately updates the color picker in the touch bar.
\n\nCrea un grupo en la barra táctil para aplicaciones nativas de macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarGroup(options)options Objectitems TouchBar - Los elementos que se muestran como un grupo.\n\nCrea una etiqueta en la barra táctil para aplicaciones nativas a macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarLabel(options)options Objectetiqueta Cadena (opcional) - texto a mostrar.accessibilityLabel String (opcional) - Una breve descripción del botón para su uso por lectores de pantalla como VoiceOver.Color del texto cadena (opcional) - color del texto en hex, ejemplo #ABCDEF.Al definir accessibilityLabel, asegúrese de que ha considerado las mejores prácticas de macOS.
Las siguientes propiedades están disponibles en instancias de etiqueta de barra táctil:
touchBarLabel.labelUn String que representa el texto actual de la etiqueta. Changing this value immediately updates the label in the touch bar.
touchBarLabel.accessibilityLabelUn String que representa la descripción de la etiqueta a ser leído por un lector de pantalla.
touchBarLabel.textColorA String hex code representing the label's current text color. Changing this value immediately updates the label in the touch bar.
\n\nInstantiates a special \"other items proxy\", which nests TouchBar elements inherited from Chromium at the space indicated by the proxy. By default, this proxy is added to each TouchBar at the end of the input. For more information, see the AppKit docs on NSTouchBarItemIdentifierOtherItemsProxy
\nNota: Sólo una instancia de esta clase puede ser agregada por TouchBar.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarOtherItemsProxy()\n\nCrea una notificación en la barra táctil para aplicaciones nativas macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarPopover(options)options ObjectEtiqueta Cadena (opcional) - tecto del botón en la notificación.ícono imagen nativa (opcional) - ícono del botón de la notificación.items TouchBar - Elementos a mostrar en el popover.showCloseButton Boolean (opcional) - true para mostrar un botón cerrar en la izquierda de notificación, false para no mostrar. Por defecto es true.Las siguiente propiedades están disponibles en instancias de notificaciones de la barra táctil:
touchBarPopover.labelUn String que representa el texto del botón actual de la ventana emergente. Changing this value immediately updates the popover in the touch bar.
touchBarPopover.iconUn NativeImage que representa el icono del botón actual de la notificación. Changing this value immediately updates the popover in the touch bar.
\n\nCrear un depurador (un selector de desplazamiento)
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarScrubber(options)options Objectelementos elemento a depurar[] - Un arreglo de elementos a depurar.select Function (optional) - Called when the user taps an item that was not the last tapped item.seleccionar índice Entero - El índice del elemento que el usuario seleccionó.highlight Function (optional) - Called when the user taps any item.índice destacado Entero - El índice del elemento que el usuario tocó.selectedStyle String (opcional) - Estilo de elemento seleccionado. Puede ser background, outline o none. Por defecto es none.overlayStyle String (opcional) - Estilo de elemento de superposición seleccionado. Puede ser background, outline o none. Por defecto es none.showArrowButtons Boolean (optional) - Whether to show arrow buttons. Defaults to false and is only shown if items is non-empty.mode String (opcional) - Puede ser fixed o free. Por defecto es free.continuous Boolean (opcional) - Por defecto a true.Las siguientes propiedades está disponibles en instancias del depurador de barra tactil:
touchBarScrubber.itemsUn array de ScrubberItem[] representando los elementos en este depurador. Actualiza este valor inmediatamente actualiza el control de la barra táctil. Mientras se actualicen las propiedades profundas dentro de este arreglo no se actualiza la barra táctil.
touchBarScrubber.selectedStyleUna Cadena que representa el estilo que deben tener los elementos seleccionados por el depurador. Actualiza este valor inmediatamente actualiza el control de la barra táctil. Posibles valores:
background - Mapa a [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Mapa a [NSScrubberSelectionStyle outlineOverlayStyle].none - Elimina todos los estilos.touchBarScrubber.overlayStyleUna Cadena que representa el estilo que deben tener los elementos seleccionados por el depurador. Este estilo es cubierto en la parte superior del elemento depurador en vez de posicionarse detrás de él. Actualizar este valor inmediatamente actualiza el control en la barra de herramientas. Posibles valores:
background - Mapa a [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Mapa a [NSScrubberSelectionStyle outlineOverlayStyle].none - Elimina todos los estilos.touchBarScrubber.showArrowButtonsA Boolean representing whether to show the left / right selection arrows in this scrubber. Actualizar este valor inmediatamente actualiza el control en el touch bar.
touchBarScrubber.modeUn String que representa el modo de este depurador. Actualiza este valor inmediatamente actualiza el control de la barra táctil. Posibles valores:
fijo - Mapa a NSScrubberModeFixed.libre - Mapa a NSScrubberModeFree.touchBarScrubber.continuousUn Boolean que representa si este depurador es continuo o no. Actualiza este valor inmediatamente actualiza el control de la barra táctil.
\n\nCrea un control segmentado (un conjunto de botones) donde un botón tiene un estado seleccionado
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSegmentedControl(options)options ObjectsegmentStyle String (opcional) - Estilo de los segmentos:automatic - Predeterminado. La apariencia del control segmentado es determinada de forma automática basados en el tipo de ventana en el cual el control es mostrado y la posición dentro de la ventana. Se mapea a NSSegmentStyleAutomatic.rounded - El control se muestra utilizando el estilo redondeado. Mapea a NSSegmentStyleRounded.textured-rounded - El control se muestra utilizando el estilo de textura redondeado. Mapea a NSSegmentStyleTexturedRounded.round-rect - Los controles se muestran utilizando el estilo rectángulo redondeado. Mapea a NSSegmentStyleRoundRect.textured-square - El control se muestra utilizando el estilo de textura cuadrado. Mapea a NSSegmentStyleTexturedSquare.capsule - El control se muestra utilizando el estilo de cápsula. Mapea a NSSegmentStyleCapsule.small-square - El control se muestra utilizando el estilo de cuadrado pequeño. Mapea a NSSegmentStyleSmallSquare.separated - Los segmentos en el control se muestran muy cerca del otro pero sin llegar a tocarse. Mapea a NSSegmentStyleSeparated.mode String (opcional) - El modo de selección del control:single - Predeterminado. Un elemento seleccionado a la vez, seleccionando uno deselecciona el elemento seleccionado anteriormente. Mapea a NSSegmentSwitchTrackingSelectOne.multiple - Elementos múltiples pueden ser seleccionados a la vez. Mapea a NSSegmentSwitchTrackingSelectAny.buttons - Hace que los segmentos actúen como botones. Cada segmento puede ser presionado y liberado pero nunca ser marcado como activo. Mapea a NSSegmentSwitchTrackingMomentary.segments SegmentedControlSegment[] - Un arreglo de elementos para colocar en este control.selectedIndex Integer (opcional) - El índice del segmento actual seleccionado, se actualizará automáticamente con la interacción del usuario. Cuando el modo es multiple será el último elemento seleccionado.change Function (optional) - Called when the user selects a new segment.selectedIndex Integer - El índice del elemento seleccionado por el usuario.isSelected Boolean - Si el elemento es seleccionado o no como resultado de la selección del usuario.Las siguientes propiedades están disponibles en instancias de TouchBarSegmentedControl:
touchBarSegmentedControl.segmentStyleUn String que representa el estilo del segmento actual de los controles. Actualizar este valor inmediatamente actualiza el control en la barra de herramientas.
touchBarSegmentedControl.segmentsUn arreglo SegmentedControlSegment[] que representa los segmentos en este control. Actualiza este valor inmediatamente actualiza el control de la barra táctil. Mientras se actualicen las propiedades profundas dentro de este arreglo no se actualiza la barra táctil.
touchBarSegmentedControl.selectedIndexUn entero que representa el segmento seleccionado actual. Cambiar este valor actualiza inmediatamente el control en la barra táctil. La interacción del usuario con la barra táctil actualizará este valor automáticamente.
touchBarSegmentedControl.modeA String representing the current selection mode of the control. Puede ser single, multiple o buttons.
\n\nCrea un control deslizante en la barra táctil para aplicaciones nativas de macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSlider(options)options Objectlabel String (opcional) - Texto de etiqueta.value Integer (opcional) - Valor seleccionado.minValue Integer (opcional) - Valor mínimo.maxValue Integer (opcional) - Valor máximo.change Function (optional) - Function to call when the slider is changed.newValue Number - El valor que el usuario seleccionó en el control deslizante.Las siguientes propiedades está disponibles en instancias de TouchBarSlider:
touchBarSlider.labelUn String que representa el texto actual del deslizador. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.valueUn Number que representa el valor actual del deslizador. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.minValueUn Number que representa el valor mínimo actual del deslizador. Cambiar este valor inmediatamente actualiza el deslizador en el touch bar.
touchBarSlider.maxValueUn Number que representa el valor máximo actual del deslizador. Cambiar este valor inmediatamente actualiza el deslizador en el touch bar.
\n\nCrea un espaciador entre dos elementos en la barra táctil para aplicaciones nativas de macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSpacer(options)options Objectsize String (optional) - Size of spacer, possible values are:small - Espacio pequeño entre los elementos. Mapea a NSTouchBarItemIdentifierFixedSpaceSmall. Este es el valor predeterminado.large - Espacio grande entre los elementos. Mapea a NSTouchBarItemIdentifierFixedSpaceLarge.flexible - Ocupa todo el espacio disponible. Mapea a NSTouchBarItemIdentifierFlexibleSpace.Las siguientes propiedades están disponibles en las instancias de TouchBarSpacer:
touchBarSpacer.sizeA String representing the size of the spacer. Puede ser small, large o flexible.
categoryFilter String - A filter to control what category groups should be traced. A filter can have an optional '-' prefix to exclude category groups that contain a matching category. Having both included and excluded category patterns in the same list is not supported. Examples: test_MyTest*, test_MyTest*,test_OtherStuff, -excluded_category1,-excluded_category2.traceOptions String - Controls what kind of tracing is enabled, it is a comma-delimited sequence of the following strings: record-until-full, record-continuously, trace-to-console, enable-sampling, enable-systrace, e.g. 'record-until-full,enable-sampling'. The first 3 options are trace recording modes and hence mutually exclusive. If more than one trace recording modes appear in the traceOptions string, the last one takes precedence. If none of the trace recording modes are specified, recording mode is record-until-full. The trace option will first be reset to the default option (record_mode set to record-until-full, enable_sampling and enable_systrace set to false) before options parsed from traceOptions are applied on it.recording_mode String (optional) - Can be record-until-full, record-continuously, record-as-much-as-possible or trace-to-console. Defaults to record-until-full.trace_buffer_size_in_kb number (optional) - maximum size of the trace recording buffer in kilobytes. Defaults to 100MB.trace_buffer_size_in_events number (optional) - maximum size of the trace recording buffer in events.enable_argument_filter boolean (optional) - if true, filter event data according to a specific list of events that have been manually vetted to not include any PII. See the implementation in Chromium for specifics.included_categories String - a list of tracing categories to include. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.excluded_categories String - a list of tracing categories to exclude. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.included_process_ids number - a list of process IDs to include in the trace. If not specified, trace all processes.histogram_names String - a list of histogram names to report with the trace.memory_dump_config Record<String, any> (optional) - if the disabled-by-default-memory-infra category is enabled, this contains optional additional configuration for data collection. See the Chromium memory-infra docs for more information.An example TraceConfig that roughly matches what Chrome DevTools records:
\n{\n recording_mode: 'record-until-full',\n included_categories: [\n 'devtools.timeline',\n 'disabled-by-default-devtools.timeline',\n 'disabled-by-default-devtools.timeline.frame',\n 'disabled-by-default-devtools.timeline.stack',\n 'v8.execute',\n 'blink.console',\n 'blink.user_timing',\n 'latencyInfo',\n 'disabled-by-default-v8.cpu_profiler',\n 'disabled-by-default-v8.cpu_profiler.hires'\n ],\n excluded_categories: ['*']\n}\ntransactionIdentifier String - A string that uniquely identifies a successful payment transaction.transactionDate String - The date the transaction was added to the App Store’s payment queue.originalTransactionIdentifier String - The identifier of the restored transaction by the App Store.transactionState String - The transaction state, can be purchasing, purchased, failed, restored or deferred.errorCode Integer - The error code if an error occurred while processing the transaction.errorMessage String - The error message if an error occurred while processing the transaction.payment ObjectproductIdentifier String - The identifier of the purchased product.quantity Integer - The quantity purchased.\n\nAñadir los iconos y menús contextuales al área de notificación del sistema.
\n
Proceso: principal</0>
\nTray es un EventEmitter.
const { app, Menu, Tray } = require('electron')\n\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n ])\n tray.setToolTip('This is my application.')\n tray.setContextMenu(contextMenu)\n})\nLimitaciones de la plataforma:
\nGtkStatusIcon se utilizará en su lugar.libappindicator1 para que funcione el icono.click es ignorado.MenuItem individuales hagan efecto, tienes que llamar otra vez a setContextMenu. Por ejemplo:const { app, Menu, Tray } = require('electron')\n\nlet appIcon = null\napp.whenReady().then(() => {\n appIcon = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' }\n ])\n\n // Make a change to the context menu\n contextMenu.items[1].checked = false\n\n // Call this again for Linux because we modified the context menu\n appIcon.setContextMenu(contextMenu)\n})\nICO para obtener mejores efectos visuales.Si se quiere mantener los mismos comportamientos en todas las plataformas, no se debe confiar en el evento click y siempre hay que adjuntar el menú de contexto al icono de bandeja.
new Tray(image, [guid])image (NativeImage | String)guid String (opcional) Windows - Asigna un GUID al icono de la bandeja. If the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. OS level settings like the position of the tray icon in the system tray will persist even if the path to the executable changes. If the executable is not code-signed then the GUID is permanently associated with the path to the executable. Changing the path to the executable will break the creation of the tray icon and a new GUID must be used. However, it is highly recommended to use the GUID parameter only in conjunction with code-signed executable. If an App defines multiple tray icons then each icon must use a separate GUID.Crea un nuevo icono de bandeja asociado con la image.
El módulo Tray emite los siguientes eventos:
Devuelve:
\nevent KeyboardEventbounds Rectangle - Los límites del icono de bandeja.position Point - La posición del evento.Emitido cuando se hace clic en el icono de bandeja.
\nDevuelve:
\nevent KeyboardEventbounds Rectangle - Los límites del icono de bandeja.Emitido cuando se hace clic derecho en el icono de bandeja.
\nDevuelve:
\nevent KeyboardEventbounds Rectangle - Los límites del icono de bandeja.Emitido cuando se hace doble clic en el icono de bandeja.
\nEmitido cuando se muestra el globo de bandeja.
\nEmitido cuando se hace clic en el globo de bandeja.
\nEmitido cuando se cierra el globo de bandeja debido al tiempo de expiración o cuando el usuario lo cierra manualmente.
\nEmitido cuando cualquier elemento arrastrado es dejado en el icono de bandeja.
\nDevuelve:
\neventfiles String[] - Las rutas de los archivos dejados en la bandeja.Emitido cuando los archivos arrastrados son dejados en el icono de la bandeja.
\nDevuelve:
\neventtext Cadena - la cadena del texto dejado.Emitido cuando el texto arrastrado es arrojado en el icono de bandeja.
\nEmitido cuando una operación de arrastre entra al icono de bandeja.
\nEmitido cuando una operación de arrastre sale del icono de bandeja.
\nEmitido cuando termina una operación de arrastre en la bandeja o termina en otra ubicación.
\nDevuelve:
\nevent KeyboardEventposition Point - La posición del evento.Emitted when the mouse is released from clicking the tray icon.
\nNote: This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.
Devuelve:
\nevent KeyboardEventposition Point - La posición del evento.Emitted when the mouse clicks the tray icon.
\nDevuelve:
\nevent KeyboardEventposition Point - La posición del evento.Emitido cuando el ratón entra en el icono de la bandeja.
\nDevuelve:
\nevent KeyboardEventposition Point - La posición del evento.Emitido cuando el ratón sale del icono de la bandeja.
\nDevuelve:
\nevent KeyboardEventposition Point - La posición del evento.Se emite cuando el ratón se mueve sobre el icono de la bandeja del sistema.
\nLa clase Tray tiene los siguientes métodos:
tray.destroy()Destruye inmediatamente el icono de la bandeja.
\ntray.setImage(image)image (NativeImage | String)Configura la image asociada con este icono de bandeja.
tray.setPressedImage(image) macOSimage (NativeImage | String)En macOS, configura la image asociada con este icono de bandeja cuando se presiona.
tray.setToolTip(toolTip)toolTip StringConfigura la activación de texto para este icono de bandeja.
\ntray.setTitle(title[, options]) macOStitle Stringoptions Object (opcional)fontType String (optional) - The font family variant to display, can be monospaced or monospacedDigit. monospaced is available in macOS 10.15+ and monospacedDigit is available in macOS 10.11+. When left blank, the title uses the default system font.Establece el título mostrado al lado de la bandeja de icono en la barra de estado (Soporta colores ANSI).
\ntray.getTitle() macOSDevuelve String - el título mostrado junto al icono de la bandeja en la barra de estado
tray.setIgnoreDoubleClickEvents(ignore) macOSignore BooleanSets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.
\nEste valor se establece en falso por defecto.
\ntray.getIgnoreDoubleClickEvents() macOSDevuelve Boolean - Si los eventos de doble click serán ignorados.
tray.displayBalloon(options) Windowsoptions Objecticon (NativeImage | String) (opcional) - Icono a usar cuando iconType es custom.iconType String (optional) - Can be none, info, warning, error or custom. Predeterminadamente, es custom.title Stringcontent StringlargeIcon Boolean (opcional) - La versión grande del icono debe ser usada. Por defecto es true. Mapea a NIIF_LARGE_ICON.noSound Boolean (opcional) - No reproducir el sonido asociado. Por defecto es false. Mapea a NIIF_NOSOUND.respectQuietTime Boolean (opcional) - No mostrar el globo de notificación si el usuario actual esta en \"tiempo de silencio\". Por defecto es false. Mapea a NIIF_RESPECT_QUIET_TIME.Muestra un globo de la bandeja.
\ntray.removeBalloon() WindowsElimina un globo de la bandeja.
\ntray.focus() WindowsDevuelve el foco al área de notificación de la barra de tarea. Los iconos del área de notificación deben usar este mensaje cuando hayan completado su operación UI. Por ejemplo, si el icono muestra un menú de acceso directo, pero el usuario presiona ESC para cancelarlo, use tray.focus() para devolver el focus a la área de notificación.
tray.popUpContextMenu([menu, position]) macOS Windowsmenu Menu (opcional)position Point (optional) - La posición del elemento emergente.Pops up the context menu of the tray icon. When menu is passed, the menu will be shown instead of the tray icon's context menu.
La position solo está disponible en Windows, y por defecto es (0, 0).
tray.closeContextMenu() macOS WindowsCloses an open context menu, as set by tray.setContextMenu().
tray.setContextMenu(menu)menu Menu | nullConfigura el menú de contexto para este icono.
\ntray.getBounds() macOS WindowsDevuelve Rectangle
Los bounds de este icono de la bandeja como Object.
tray.isDestroyed()Devuelve Boolean - Si el icono de la bandeja es destruido o no.
title: Tray\ndescription: This guide will take you through the process of creating a Tray icon with its own context menu to the system's notification area.\nslug: tray
\nEsta guía le llevará a través del proceso de creación de un icono de bandeja con su propio menú contextual en el área de notificación del sistema.
\nEn MacOS y Ubuntu, la bandeja se ubicará en la parte superior esquina derecha de tu pantalla, adyacente a tu batería y a los íconos WiFi. En Windows, la bandeja se ubicará normalmente en la esquina inferior derecha.
\nFirst we must import app, Tray, Menu, nativeImage from electron.
const { app, Tray, Menu, nativeImage } = require('electron')\nA continuación crearemos nuestra bandeja. To do this, we will use a NativeImage icon, which can be created through any one of these methods. Note that we wrap our Tray creation code within an app.whenReady as we will need to wait for our electron app to finish initializing.
let tray\n\napp.whenReady().then(() => {\n const icon = nativeImage.createFromPath('path/to/asset. ng')\n bandeja = new Tray(icon)\n\n // Nota: su código contextMenu, Tooltip y Title ¡irá aquí!\n})\n¡Genial! Ahora podemos empezar a adjuntar un menú contextual a nuestra bandeja, así:
\nconst contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n])\n\ntray.setContextMenu(contextMenu)\nEl código anterior creará 4 elementos de tipo radio separados en el menú contextual. Para leer más sobre la construcción de menús nativos, haz clic en aquí.
\nPor último, démosle a nuestra bandeja una información sobre herramientas y un título.
\ntray.setToolTip('Esta es mi aplicación')\ntray.setTitle('Este es mi título')\nDespués de iniciar la aplicación Electron, deberías ver la bandeja residiendo en la parte superior o inferior derecha de la pantalla, dependiendo de tu sistema operativo.\nfiddle docs/fiddles/native-ui/tray
Hay muchas manera de actualizar la aplicación Electron. La manera más fácil y apoyada oficialmente es aprovechar el marco de trabajo incorporado Squirrel y el módulo autoUpdater de Electron.
\nupdate.electronjs.orgEl equipo de Electron mantiene update.electronjs.org, un webservice gratis y open-source que las aplicaciones Electron puede usar para auto-actualizarse. El servicio está diseñado para aplicaciones de Electron que cumplen con los siguientes criterios:
\nLa forma más fácil de usar este servicio es instalando update-electron-app, un módulo de Node.js preconfigurado para usarse con update.electronjs.org.
\nInstala el módulo:
\nnpm install update-electron-app\nInvoque el actualizador de archivos de los principales procesos de su aplicacion Electrón:
\nrequire('update-electron-app')()\nDe manera predeterminada, este módulo verificará si existen actualizaciones en el inicio de la aplicación y luego cada diez minutos. Cuando se encuentra una actualización, esta se descargará automáticamente en segundo plano. Cuando se completa la descarga, se muestra un cuadro de diálogo que le permite al usuario reiniciar su aplicación.
\nSi necesita personalizar su configuración, puede usar la opción de update-electron-app o usar el servicio de actualización directo.
Si está desarrollando una aplicación privada de Electrón, o si no está publicando lanzamientos en GitHub, tal vez pueda considerar poseer su propio servidor de actualizaciones.
\nDependiendo de sus necesidades, puede escoger una de esta:
\nUna vez que haya implementado su servidor de actualización, continúe con la importación de los módulos requeridos en su código. El siguiente código podría variar en diferentes servidores de software, pero funciona como está descrito cuando se utiliza Hazel.
\nImportantante: por favor asegurate de que el siguiente código solo se ejecutara en su paquete de aplicaciones, y no en desarrollo. Puedes usar electron-is-dev para chequear el tipo de ambiente.
\nconst { app, autoUpdater, dialog } = require('electron')\nA continuación, construya la URL de uno de los servidores de actualizaciones, de la siguiente manera: autoUpdater:
\nconst server = 'https://your-deployment-url.com'\nconst url = `${server}/update/${process.platform}/${app.getVersion()}`\n\nautoUpdater.setFeedURL({ url })\nAs the final step, check for updates. The example below will check every minute:
\nsetInterval(() => {\n autoUpdater.checkForUpdates()\n}, 60000)\nUna vez que su aplicacion es empaquetada, usted recibirá una actualización para cada nuevo Lanzamiento de GitHub que usted publique.
\nAhora que ha configurado el mecanismo de actualización básico para su aplicación, debe asegurarse de que el usuario reciba una notificación cuando haya una actualización. Esto se puede lograr utilzando la API de autoUpdater events:
\nautoUpdater.on('update-downloaded', (event, releaseNotes, releaseName) => {\n const dialogOpts = {\n type: 'info',\n buttons: ['Restart', 'Later'],\n title: 'Application Update',\n message: process.platform === 'win32' ? releaseNotes : releaseName,\n detail: 'A new version has been downloaded. Restart the application to apply the updates.'\n }\n\n dialog.showMessageBox(dialogOpts).then((returnValue) => {\n if (returnValue.response === 0) autoUpdater.quitAndInstall()\n })\n})\nAlso make sure that errors are being handled. Here's an example for logging them to stderr:
autoUpdater.on('error', message => {\n console.error('There was a problem updating the application')\n console.error(message)\n})\nBecause the requests made by Auto Update aren't under your direct control, you may find situations that are difficult to handle (such as if the update server is behind authentication). The url field does support files, which means that with some effort, you can sidestep the server-communication aspect of the process. Here's an example of how this could work.
bytes Buffer - Content being sent.file String (optional) - Path of file being uploaded.blobUUID String (optional) - UUID of blob data. Use ses.getBlobData method to retrieve the data.type 'file' - file.filePath String - Path of file to be uploaded.offset Integer - Defaults to 0.length Integer - Number of bytes to read from offset. Defaults to 0.modificationTime Double - Last Modification time in number of seconds since the UNIX epoch.type 'rawData' - rawData.bytes Buffer - Data to be uploaded.string Stringboolean Booleaninteger Numberfloat Numberdouble Numberurl Stringarray Arreglo\\dictionary Record\\<string, unknown>This type is a helper alias, no object will never exist of this type.
", "title": "UserDefaultTypes Object", "description": "" }, "/docs/tutorial/using-native-node-modules": { "locale": "es-ES", "slug": "using-native-node-modules", "href": "/docs/tutorial/using-native-node-modules", "crowdinFileId": "256263", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-native-node-modules.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Los módulos nativos de Node.js están soportados por Electron, pero dado que Electron tiene una diferente interfaz binaria de aplicación (ABI) de un binario Node.js dado (debido a diferencias tales como usar BoringSSL de Chromium en lugar de OpenSSL), los módulos nativos que use necesitarán ser recompilados para Electron. De lo contrario, obtendrá la siguiente clase de error cuando intente ejecutar su aplicación:
\nError: The module '/path/to/native/module.node'\nwas compiled against a different Node.js version using\nNODE_MODULE_VERSION $XYZ. This version of Node.js requires\nNODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing\nthe module (for instance, using `npm rebuild` or `npm install`).\nHay varias formas diferentes de instalar los módulos nativos:
\nPuedes instalar los módulos como otro proyecto Node, luego reconstruir el modulo para Electron con el paquete electron-rebuild. Este módulo puede determinar automáticamente la versión de Electron y manejar los pasos manuales de descargar las cabeceras y reconstruir los módulos nativos para tu app. Si está usando Electron Forge, esta herramienta se utiliza automáticamente tanto en desarrollo como al hacer distribuibles.
Por ejemplo, para instalar la herramienta independiente electron-rebuild y recompilar los módulos con este a través de la linea de comando:
npm install --save-dev electron-rebuild\n\n# Every time you run \"npm install\", run this:\n./node_modules/.bin/electron-rebuild\n\n# If you have trouble on Windows, try:\n.\\node_modules\\.bin\\electron-rebuild.cmd\nPara más información sobre el uso y la integración con otras herramientas como Electron Packager, consulte el README del proyecto.
\nnpmAl establecer algunas variables del entorno, puede usar npm para instalar módulos directamente.
Por ejemplo, para instalar todas las dependencias para Electron:
\n# Electron's version.\nexport npm_config_target=1.2.3\n# The architecture of Electron, see https://electronjs.org/docs/tutorial/support#supported-platforms\n# for supported architectures.\nexport npm_config_arch=x64\nexport npm_config_target_arch=x64\n# Download headers for Electron.\nexport npm_config_disturl=https://electronjs.org/headers\n# Tell node-pre-gyp that we are building for Electron.\nexport npm_config_runtime=electron\n# Tell node-pre-gyp to build module from source code.\nexport npm_config_build_from_source=true\n# Install all dependencies, and store cache to ~/.electron-gyp.\nHOME=~/.electron-gyp npm install\nSi usted es un desarrollador que está desarrollando un módulo nativo y desea probarlo con Electron, es posible que desee reconstruir el módulo para Electron manualmente. Puedes usar node-gyp directamente para construir para Electron:
cd /path-to-module/\nHOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://electronjs.org/headers\nHOME=~/.electron-gyp cambie para encontrar las cabeceras de desarrollo.--target=1.2.3 es la versión de Electron.--dist-url=... especifique de donde descargar las cabeceras.--arch=x64 dice que el modulo es construido para un sistema de 64-bit.Para compilar Módulos Nativos de Node contra una compilación personalizada de Electron que no coincide con una version pública, indique a npm que use la versión de Node que ha incluido en su versión personalizada.
npm rebuild --nodedir=/path/to/src/out/Default/gen/node_headers\nSi ha instalado un módulo nativo y este no funciona, necesitas verificar las siguientes cosas:
\nelectron-rebuild primero.win_delay_load_hook no esta configurado como false en el módulo binding.gyp.win_delay_load_hookEn Windows, por defecto node-gyp enlaza los módulos nativos contra node.dll. Sin embargo, en Electron 4.x y superiores, los symbols que necesitan los módulos nativos son exportados por electron.exe, y no ahí node.dll. Para poder cargar módulos nativos en Windows, node-gyp instala un delay_load_hook que es lanzado cuando el módulo nativo es cargado, y redirige las referencias de node.dll para usar el ejecutable de carga en lugar de buscar por node.dll en la ruta de la libreria (el cual no daría nada). Como tal, en Electron 4.x y superiores 'win_delay_load_hook': 'true' es necesario para cargar módulos nativos.
Si se obtiene un error como Módulo no se auto-registró, o El procedimiento especificado no se pudo encontrar, puede significar que el módulo que está intentando usar no incluyó correctamente el delay-load hook. Si el módulo esta construido con node-gyp, asegurese de que la variable win_delay_load_hook esta configurada a true en el archivo binding.gyp, y que no esta siendo sobrescrita en ningún lado. Si el módulo esta siendo construido con otro sistema, necesitarás asegurarte que construye con un delay-load hook instalado en el archivo .node principal. Su invocación link.exe debe parecerce a esto:
link.exe /OUT:\"foo.node\" \"...\\node.lib\" delayimp.lib /DELAYLOAD:node.exe /DLL\n \"my_addon.obj\" \"win_delay_load_hook.obj\"\nEn particular, es importante que:
\nnode.lib from Electron and not Node. If you link against the wrong node.lib you will get load-time errors when you require the module in Electron./DELAYLOAD:node.exe. Si el enlace a node.exe no se retrasa, el delay-load hook no tendra la oportunidad de disparar y el símbolo a node no será resulto correctamente.win_delay_load_hook.obj is linked directly into the final DLL. If the hook is set up in a dependent DLL, it won't fire at the right time.Mire node-gyp para un ejemplo de delay-load si estas implementando el tuyo propio.
prebuildprebuild proporciona una forma de publicar módulos nativos de Node con binarios precompilados para multiples versiones de Node y Electron.
Si el módulo prebuild-powered provee binarios para el uso en Electron, asegúrate de omitir --build-from-source y la variable de entorno npm_config_build_from_source para aprovechar el máximo de los binarios preconstruidos.
node-pre-gypLa herramienta node-pre-gyp proporciona una forma de implementar módulos de nodo nativos con binarios precompilados, y muchos módulos populares lo están usando.
Algunas veces esos módulos funcionan bien bajo Electron, pero cuando no hay disponibles binarios específico para Electron necesitarás construirlos desde el código fuente. Por esto, es recomendable usar electron-rebuild para estos módulos.
Si estás siguiendo la forma de npm de instalar módulos, necesitarás pasar --build-from-source a npm, o establecer la variable de entorno npm_config_build_from_source.
Electron no longer supports the Pepper Flash plugin, as Chrome has removed support.
\nSee Chromium's Flash Roadmap for more details.
", "title": "Pepper Flash Plugin", "description": "" }, "/docs/tutorial/using-selenium-and-webdriver": { "locale": "es-ES", "slug": "using-selenium-and-webdriver", "href": "/docs/tutorial/using-selenium-and-webdriver", "crowdinFileId": "256267", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-selenium-and-webdriver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Para ChromeDriver - WebDriver para Chrome:
\n\n\nWebDriver es una herramienta de código abierto para pruebas automatizadas de aplicaciones web en varios navegadores. Provee la capacidad de navegar por páginas web, sistema de usuarios, ejecución de JavaScript, y más. ChromeDriver es un servidor independiente que implementa el protocolo de cable de WebDriver para Chromium. Ha sido desarrollado por miembros de los equipos de Chromium y WebDriver.
\n
Spectron es el sistema de pruebas de Electron, apoyado oficialmente por ChromeDriver. Se construyó sobre WebdriverIO y tiene ayudantes para acceder a la API de Electron en su prueba y paquetes ChromeDriver.
\n$ npm install --save-dev spectron\n// A simple test to verify a visible window is opened with a title\nconst Application = require('spectron').Application\nconst assert = require('assert')\n\nconst myApp = new Application({\n path: '/Applications/MyApp.app/Contents/MacOS/MyApp'\n})\n\nconst verifyWindowIsVisibleWithTitle = async (app) => {\n await app.start()\n try {\n // Check if the window is visible\n const isVisible = await app.browserWindow.isVisible()\n // Verify the window is visible\n assert.strictEqual(isVisible, true)\n // Get the window's title\n const title = await app.client.getTitle()\n // Verify the window's title\n assert.strictEqual(title, 'My App')\n } catch (error) {\n // Log any failures\n console.error('Test failed', error.message)\n }\n // Stop the application\n await app.stop()\n}\n\nverifyWindowIsVisibleWithTitle(myApp)\nWebDriverJs provides a Node package for testing with web driver, we will use it as an example.
\nPrimero usted necesita descargar el chromedriver binario, y ejecutarlo:
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver\nIniciar ChromeDriver (v2.10.291558) en puerto 9515\nSolo conexiones locales permitidas.\nRecuerde el puerto número 9515, que usaremos más adelante
$ npm install selenium-webdriver\nEl uso de selenium-webdriver con Electron es el mismo con upstream, excepto que usted tiene que especificar manualmente como conectar chrome driver y donde se encuentra el binario de Electron:
const webdriver = require('selenium-webdriver')\n\nconst driver = new webdriver.Builder()\n // The \"9515\" is the port opened by chrome driver.\n .usingServer('http://localhost:9515')\n .withCapabilities({\n 'goog:chromeOptions': {\n // Here is the path to your Electron binary.\n binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'\n }\n })\n .forBrowser('chrome') // note: use .forBrowser('electron') for selenium-webdriver <= 3.6.0\n .build()\n\ndriver.get('http://www.google.com')\ndriver.findElement(webdriver.By.name('q')).sendKeys('webdriver')\ndriver.findElement(webdriver.By.name('btnG')).click()\ndriver.wait(() => {\n return driver.getTitle().then((title) => {\n return title === 'webdriver - Google Search'\n })\n}, 1000)\n\ndriver.quit()\nWebdriverIO provides a Node package for testing with web driver.
\nPrimero usted necesita descargar el chromedriver binario, y ejecutarlo:
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver --url-base=wd/hub --port=9515\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\nRecuerde el puerto número 9515, que usaremos más adelante
$ npm install webdriverio\nconst webdriverio = require('webdriverio')\nconst options = {\n host: 'localhost', // Use localhost as chrome driver server\n port: 9515, // \"9515\" is the port opened by chrome driver.\n desiredCapabilities: {\n browserName: 'chrome',\n 'goog:chromeOptions': {\n binary: '/Path-to-Your-App/electron', // Path to your Electron binary.\n args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/\n }\n }\n}\n\nconst client = webdriverio.remote(options)\n\nclient\n .init()\n .url('http://google.com')\n .setValue('#q', 'webdriverio')\n .click('#btnG')\n .getTitle().then((title) => {\n console.log('Title was: ' + title)\n })\n .end()\nPara probar su aplicación sin reconstruir Electron, place el fuente de su aplicación en el directorio de recursos de Electron.
\nAlternatively, 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.
", "title": "Selenium and WebDriver", "description": "WebDriver es una herramienta de código abierto para pruebas automatizadas de aplicaciones web en varios navegadores. Provee la capacidad de navegar por páginas web, sistema de usuarios, ejecución de JavaScript, y más. ChromeDriver es un servidor independiente que implementa el protocolo de cable de WebDriver para Chromium. Ha sido desarrollado por miembros de los equipos de Chromium y WebDriver." }, "/docs/development/v8-development": { "locale": "es-ES", "slug": "v8-development", "href": "/docs/development/v8-development", "crowdinFileId": "256171", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/v8-development.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "\n\nUna colección de recursos para aprender y usar V8
\n
--prof, --trace-ic, --trace-opt, --trace-deopt, --print-bytecode, --print-opt-codeVea también Chromium Development
", "title": "Desarrollo de V8", "description": "Una colección de recursos para aprender y usar V8" }, "/docs/api/web-contents": { "locale": "es-ES", "slug": "web-contents", "href": "/docs/api/web-contents", "crowdinFileId": "256399", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-contents.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nProcesamiento y control de páginas webs.
\n
Proceso: principal</0>
\nwebContents es un EventEmitter. Es responsable de renderizar y controlar una página web y es una propiedad del objeto BrowserWindow. Un ejemplo de acceso al objeto webContents:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('http://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\nSe pueden acceder a estos métodos desde el módulo webContents:
const { webContents } = require('electron')\nconsole.log(webContents)\nwebContents.getAllWebContents()Volver WebContents[] a la matriz de todo el caso WebContents. Esto incluirá contenido web para todos los windows, páginas web, devtools abiertos y extensión de páginas de origen devtools.
webContents.getFocusedWebContents()Volver WebContents - El contenido web que se centra en esta aplicación, de lo contrario regresa null.
webContents.fromId(id)id ÍntegroDevuelve WebContents | undefined - Una instancia de WebContents con el ID dado, o undefined si no hay WebContents asociados con ID dado.
webContents.fromDevToolsTargetId(targetId)targetId String - The Chrome DevTools Protocol TargetID associated with the WebContents instance.Returns WebContents | undefined - A WebContents instance with the given TargetID, or undefined if there is no WebContents associated with the given TargetID.
When communicating with the Chrome DevTools Protocol, it can be useful to lookup a WebContents instance based on its assigned TargetID.
\nasync function lookupTargetId (browserWindow) {\n const wc = browserWindow.webContents\n await wc.debugger.attach('1.3')\n const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')\n const { targetId } = targetInfo\n const targetWebContents = await webContents.fromDevToolsTargetId(targetId)\n}\n\n\nRenderice y controle el contenido de una instancia de BrowserWindow.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emite cuando la navegación está hecha, i.e.
\nDevuelve:
\neventerrorCode IntegererrorDescription StringvalidatedURL StringEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEste evento es como did-finish-load pero emitido cuando falló la carga. La lista completa de los códigos de error y su significado está disponible aquí.
Devuelve:
\neventerrorCode IntegererrorDescription StringvalidatedURL StringEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEste evento es como did-fail-load pero emitido cuando la carga fue cancelada (p. e. fue invocado window.stop()).
Devuelve:
\neventEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEmite cuando un frame ha terminado la navegación.
\nCorresponde a los puntos en el tiempo cuando el girador de la pestaña comenzó a girar.
\nCorresponde a los puntos en tiempo cuando el girador del tabulador terminó de girar.
\nDevuelve:
\neventEmitido cuando el documento el el nivel superior está cargado.
\nDevuelve:
\neventtitle StringexplicitSet BoolenDisparado cuando el título de la página se configura durante la navegación. explicitSet es false cuando el título es sincronizado desde el archivo url.
Devuelve:
\neventfavicons Cadena[] - Arreglo para URLs.Emite cuando la página recibe urls de favicon.
\nDevuelve:
\nevent NewWindowWebContentsEventurl StringframeName Stringdisposition String - Puede ser default, foreground-tab, background-tab, new-window, save-to-disk and other.options BrowserWindowConstructorOptions - Las opciones que serán usadas para crear la nueva BrowserWindow.additionalFeatures String[] - Las características no estándar (características no manejadas por Chromium o Electron) pasadas a window.open(). Deprecated, and will now always be the empty array [].referrer Referrer - El remitente que será pasado a la nueva ventana. Puede resultar o no en la cabecera Referer siendo enviado, dependiendo de la política de referencia.postBody PostBody (opcional) - Los datos que serán enviados a la nueva ventana, junto con las cabeceras apropiadas que se establecerán. Si no hay datos para enviar, el valor será null. Solo se define cuando la ventana está siendo creada por un formulario que establece target=_blank.Obsoleto a favor de webContents.setWindowOpenHandler.
Emitido cuando la página solicita abrir una nueva ventana para una url. Puede ser requerido por window.open o un link externo como <a target='_blank'>.
Por defecto se creará un nuevo BrowserWindow para la dirección url.
Ejecutar event.preventDefault() evitará que Electron cree automáticamente un nuevo BrowserWindow. Si se llama a event.preventDefault() y se crea manualmente un nuevo BrowserWindow entonces se debe activar event.newGuest para referenciar a la nueva instancia de BrowserWindow, no hacerlo puede causar un comportamiento inesperado. Por ejemplo:
myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {\n event.preventDefault()\n const win = new BrowserWindow({\n webContents: options.webContents, // use existing webContents if provided\n show: false\n })\n win.once('ready-to-show', () => win.show())\n if (!options.webContents) {\n const loadOptions = {\n httpReferrer: referrer\n }\n if (postBody != null) {\n const { data, contentType, boundary } = postBody\n loadOptions.postData = postBody.data\n loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`\n }\n\n win.loadURL(url, loadOptions) // existing webContents will be navigated automatically\n }\n event.newGuest = win\n})\nDevuelve:
\nwindow Navegador Windowsdetails Objecturl String - URL de la ventana creada.frameName String - Nombre dado a la ventana creada en la llamada window.open().options BrowserWindowConstructorOptions - Las opciones utilizadas para crear el BrowserWindow. They are merged in increasing precedence: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Las opciones no reconocidas no están filtradas.referrer Referrer - El remitente que será pasado a la nueva ventana. Puede resultar o no en la cabecera Referer siendo enviado, dependiendo de la política de referencia.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. Si no hay datos para enviar, el valor será null. Only defined when the window is being created by a form that set target=_blank.disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.Emitted after successful creation of a window via window.open in the renderer. No emitido si la creación de la ventana es cancelada desde webContents.setWindowOpenHandler.
See window.open() for more details and how to use this in conjunction with webContents.setWindowOpenHandler.
Devuelve:
\neventurl StringEmitido cuando un usuario o l página quiere empezar la navegación. Puede ocurrir cuando el objeto window.location se cambia o un usuario hace clic en un enlace en la página.
Este evento no se emitirá cuando la navegación es iniciada con programación con APIs como webContents.loadURL y webContents.back.
It is also not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Llamando event.preventDefault() evitará la navegación.
Devuelve:
\neventurl StringisInPlace BooleanEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEmitido cuando cualquier frame (incluyendo el principal) comienza la navegación. isInPlace will be true for in-page navigations.
Devuelve:
\neventurl StringisInPlace BooleanEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEmitted as a server side redirect occurs during navigation. For example a 302 redirect.
\nEste evento sera emitido después de did-start-navigation y siempre antes del evento did-redirect-navigation para la misma navegación.
Llamar a event.preventDefault() evitará la navegación (no solo la redirección).
Devuelve:
\neventurl StringisInPlace BooleanEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nEste evento no puede ser prevenir. Si quieres prevenir redirecciones deber ver el evento will-redirect arriba.
Devuelve:
\neventurl StringhttpResponseCode Integer - -1 para navegaciones no HTTPhttpStatusText String - vacío para navegaciones no HTTPEmitido cuando se realizo un navegación del frame principal.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Devuelve:
\neventurl StringhttpResponseCode Integer - -1 para navegaciones no HTTPhttpStatusText String - vacío para navegaciones no HTTPEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEmitido cuando se ha realizado un navegación de algun frame.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Devuelve:
\neventurl StringEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEmitido cuando se produjo una navegación en la página en cualquier frame.
\nCuando una navegación dentro de la página sucede, el URL de la página cambia, pero no causa una navegación fuera de la página. Ejemplos de ésto ocurriendo son cuando los links son clickeados o cuando el evento DOM hashchange es activado.
Devuelve:
\neventEmite cuando un controlador de eventos beforeunload está tratando de cancelar una descarga de la página.
Llamando a event.preventDefault() ignorará el controlador de eventos beforeunload y permite que la página sea descargada.
const { BrowserWindow, dialog } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.webContents.on('will-prevent-unload', (event) => {\n const choice = dialog.showMessageBoxSync(win, {\n type: 'question',\n buttons: ['Leave', 'Stay'],\n title: 'Do you want to leave this site?',\n message: 'Changes you made may not be saved.',\n defaultId: 0,\n cancelId: 1\n })\n const leave = (choice === 0)\n if (leave) {\n event.preventDefault()\n }\n})\nNote: This will be emitted for BrowserViews but will not be respected - this is because we have chosen not to tie the BrowserView lifecycle to its owning BrowserWindow should one exist per the specification.
Devuelve:
\neventkilled BooleanoEmitido cuando el proceso se crashea o es terminado.
\nObsoleto: Este evento es reemplazado por el evento render-process-gone el cual contiene más información acerca de porque desapareció el renderer process. No siempre se debe a que haya dejado de funcionar. El booleano killed puede ser reemplazado al comprobar que reason === 'killed' cuando se cambie a ese evento.
Devuelve:
\neventdetails Objectreason String - La razón por la que finalizo el proceso. Posibles valores:clean-exit -El proceso ha finalizado con un exit code de ceroabnormal-exit - El proceso a finalizado con un exit code distinto de cerokilled - El proceso a enviado un SIGTERM o se a finalizado externamentecrashed - El proceso crasheooom - El proceso se quedo sin memorialaunch-failed - El proceso nunca se ha ejecutado correctamenteintegrity-failure - las verificaciones de integridad de código de Windows fallaronexitCode Integer - El código de salida del proceso, a menos que reason sea launch-failed, en cuyo caso exitCode será un código de error de ejecución especifico de la plataforma.Emitido cuando el renderer process desaparece inesperadamente. Esto se debe comúnmente porque se crasheo o cerro.
\nAparece cuando la página web deja de responder.
\nAparece cuando la página web que no responde vuelve a responder.
\nDevuelve:
\neventname Stringversion CadenaEmitido cuando el proceso de enchufe se ha caído.
\nEmitido cuando webContents es destruido.
Devuelve:
\neventinput Object - Input properties.type String - Either keyUp or keyDown.key String - Es igual a KeyboardEvent.key.code String - Es igual a KeyboardEvent.code.isAutoRepeat Boolean - Es igual a KeyboardEvent.repeat.isComposing Boolean - Equivalente a KeyboardEvent.isComposing.shift Boolean - Es igual a KeyboardEvent.shiftKey.control Boolean - Es igual a KeyboardEvent.controlKey.alt Boolean - Es igual a KeyboardEvent.altKey.meta Boolean - Es igual a KeyboardEvent.metaKey.location Number - Equivalente a KeyboardEvent.location.modifiers String[] - Ver InputEvent.modifiers.Emitido antes de enviar los eventos keydown y keyup en la página. Llamando a event.preventDefault evitará la página keydown/ eventos keyup y los accesos rápidos al menú.
To only prevent the menu shortcuts, use setIgnoreMenuShortcuts:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nwin.webContents.on('before-input-event', (event, input) => {\n // For example, only enable application menu keyboard shortcuts when\n // Ctrl/Cmd are down.\n win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)\n})\nAparece cuando la ventana entra en un estado pantalla completa activado por la API HTML.
\nAparece cuando la ventana sale de un estado pantalla completa activado por la API HTML.
\nDevuelve:
\neventzoomDirection String - Puede ser in o out.Emitido cuando es usuario esta solicitando cambiar el nivel del zoom usando la rueda del ratón.
\nEmitido cuando DevTools es abierto.
\nEmitido cuando Devtools es cerrado.
\nEmitido cuando DevTools es centrado o abierto.
\nDevuelve:
\neventurl Stringerror String - The error code.certificate certificatecallback FunciónisTrusted Boolean - Indicates whether the certificate can be considered trusted.EsElFramePrincipal BooleanEmitido cuando no se pudo verificar el certificate for url.
El uso es el mismo con the certificate-error evento de app.
Devuelve:
\neventurl URLcertificateListCertificate[]callback Funcióncertificate Certificate - Must be a certificate from the given list.Emitido cuando el certificado de un cliente es requerido.
\nEl uso es el mismo con the select-client-certificate evento de app.
Devuelve:
\neventauthenticationResponseDetails Objecturl URLauthInfo ObjectisProxy Booleanscheme Stringanfitrión Cadenapuerto Íntegrorealm Cadenacallback Funciónusername String (opcional)password String (opcional)Emitido cuando webContents quiere hacer una autenticación básica.
El uso es lo mismo que con el evento the login de la app.
Devuelve:
\neventresult ObjectrequestId ÍntegroactiveMatchOrdinal Integer - Posición de la coincidencia activa.matches Integer - Número de coincidencias.selectionArea Rectangle - Coordenadas de la primera región de coincidencia.finalUpdate BooleanEmitido cuando un resultado está disponible para la petición de [webContents.findInPage].
Emitido cuando la media empieza a reproducirse.
\nEmitido cuando la media es pausada o ha terminado de reproducirse.
\nDevuelve:
\neventcolor (String | null) - Theme color is in format of '#rrggbb'. It is null when no theme color is set.Emitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nDevuelve:
\neventurl StringEmitido cuando el mouse se mueve sobre un link o el teclado se mueve el concentrado a un link.
\nDevuelve:
\neventtype Stringimage NativeImage (opcional)scale Float (optional) - scaling factor for the custom cursor.size Size (optional) - the size of the image.hotspot Point (optional) - coordinates of the custom cursor's hotspot.Emitido cuando el tipo del cursor cambia. El parámetro type puede ser default, crosshair, pointer, text, wait, help, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ns-resize, ew-resize, nesw-resize, nwse-resize, col-resize, row-resize, m-panning, e-panning, n-panning, ne-panning, nw-panning, s-panning, se-panning, sw-panning, w-panning, move, vertical-text, cell, context-menu, alias, progress, nodrop, copy, none, not-allowed, zoom-in, zoom-out, grab, grabbing o custom.
Si el parámetro type es custom, el parámetro de la image mantendrá la imagen del cursor personalizado en un NativeImage, scale y size, hotpost mantendrá información adicional sobre el cursor personalizado.
Devuelve:
\neventparams Objectx Integer - x coordinate.y Integer - y coordinate.frame WebFrameMain - Frame desde el cual se invocó el menú contextual.linkURL String - URL del enlace que incluye el nodo del menú contextual que fue invocado.linkText String - Text associated with the link. May be an empty string if the contents of the link are an image.pageURL String - URL de la parte superior del nivel de la página que se invocó en el menú del contexto.framseURL String - URL de la parte inferior del marco que se invocó en el menú del contexto.srcURL String - Source URL for the element that the context menu was invoked on. Elements with source URLs are images, audio and video.mediaTipo String - Tipo de nodo que el menú del contexto fue invocado. Puede ser none, image, audio, video, canvas, file o plugin.<0>tieneImagenContenido Boolean - si el menú del contexto fue invocado en una imagen la cual tiene contenido no vacío.esEditable Boolean - Si el contexto es editable.selectrionText String. Texto de la selección la cual el menú del contexto fue invocado.titleText String - Ttexto del título de la selección en la que se invocó el menú contextual.altText String - Texto alternativo de la selección en la que se invocó el menú contextual.suggestedFilename String - Nombre de archivo sugerido para ser usado cuando se guarde el archivo a través de la opción 'Guarde Enlace Como' del menú contextual.selectionRect Rectángulo - Rectángulo que representa las coordenadas en el espacio del documento de la selección.SelectionStartOffset Number - Posición inicial del texto de selección.referrerPolicy Referrer - La política de referencia del frame en el cual el menú es invocado.misspelledWord String - La palabra mal escrita bajo el cursor, si cualquiera.dictionarySuggestions String[] - Un array de palabras sugeridas para mostrar al usuario para remplazar el misspelledWord. Solo disponible si hay una palabra mal escrita y el corrector está habilitado.frameCharset String - La codificación de carácteres de la estructura la cual el menú fue invocado.inputFieldType Cadena - Si se invoca el menú de contexto en un campo de entrada, el tipo de ese campo. Los valores posibles son none, plainText, password, other.spellcheckEnabled Boolean - Si el contexto es editable, si el corrector ortográfico está habilitado o no.menuSourceType String - Input source that invoked the context menu. Puede ser none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, o adjustSelectionReset.mediaFlags Object - The flags for the media element the context menu was invoked on.enError Boolean - Si el elemento multimedia se ha dañado.estáPausado Boolean - Si el elemento multimedia está pausado.estáSilenciado Boolean - Si el elemento multimedia está silenciado.tieneAudio Boolean - Si el elemento multimedia tiene audio.estáLooping Boolean - Si el elemento multimedia está enredado.esControlVisible Boolean - Si los controles del elemento multimedia son visibles.puedeToggleControles Boolean - Si los controles de los elementos multimedia son toggleable.canPrint Boolean - Si el elemento multimedia puede ser impreso.canSave Boolean - Si el elemento multimedia puede ser descargado o no.canShowPictureInPicture Boolean - Si el elemento multimedia puede ser mostrado en picture-in-picture.isShowingPictureInPicture Boolean - Si el elemento multimedia está siendo actualmente mostrado en picture-in-picture.puedeRotar Boolean - Si el elemento multimedia puede ser rotado.canLoop Boolean - Si el elemento multimedia puede hacer un loop.editFlags Object - These flags indicate whether the renderer believes it is able to perform the corresponding action.canUndo Boolean - Si cree que el procesador puede deshacer.canRedo Boolean - Si cree que el procesador pueda rehacer.canCut Boolean - Si cree que el procesador puede cortar.canCopy Boolean - Si cree que el procesador puede copiar.canPaste Boolean - Si cree que el procesador puede pegar.canDelete Boolean - Si cree que el procesador puede borrar.canSelectAll Boolean - Si cree que el procesador puede seleccionar todo.canEditRichly Boolean - Si el renderer cree que puede editar texto de forma enriquecedora.Emitido cuando hay un nuevo menú de contexto que debe ser manejado.
\nDevuelve:
\neventdevices BluetoothDevice[]callback FuncióndeviceId StringEmite cuando el dispositivo bluetooth necesita ser seleccionado en la llamada navigator.bluetooth.requestDevice. Para usar navigator.bluetooth api webBluetooth debe ser activada. Si no se llama event.preventDefault el primer dispositivo disponible será seleccionado. callback puede ser llamado con deviceId ser seleccionado,.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\napp.commandLine.appendSwitch('enable-experimental-web-platform-features')\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {\n event.preventDefault()\n const result = deviceList.find((device) => {\n return device.deviceName === 'test'\n })\n if (!result) {\n callback('')\n } else {\n callback(result.deviceId)\n }\n })\n})\nDevuelve:
\neventdirtyRect Rectangleimage NativeImage - La información de la imagen de todo el fotograma.Emitted when a new frame is generated. Only the dirty area is passed in the buffer.
\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ webPreferences: { offscreen: true } })\nwin.webContents.on('paint', (event, dirty, image) => {\n // updateBitmap(dirty, image.getBitmap())\n})\nwin.loadURL('http://github.com')\nEmitido cuando la ventana devtools instruya la webContents para recargar
\nDevuelve:
\neventwebPreferences WebPreferences - The web preferences that will be used by the guest page. This object can be modified to adjust the preferences for the guest page.params Record<string, string> - The other <webview> parameters such as the src URL. This object can be modified to adjust the parameters of the guest page.Emitted when a <webview>'s web contents is being attached to this web contents. Calling event.preventDefault() will destroy the guest page.
Este evento puede utilizarse para configurar webPreferences para la webContents de un <webview>antes de que se carga y proporciona la capacidad de configuración que no se puede establecer a través de atributos <webview>.
Nota: La opción específica de preload aparecerá como preloadURL (no preload) en el objeto webPreferences emitido con este evento.
Devuelve:
\neventwebContents WebContents - El contenido de la página web invitada que será usado por <webview>.Emitido cuando se ha adjuntado un <webview> a este contenido web.
Devuelve:
\neventlevel Entero - El nivel de registro, desde 0 hasta 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Entero - El número de línea de la fuente que activó este mensaje de consolasourceId CadenaEmitido cuando la ventana asociada registra un mensaje de consola.
\nDevuelve:
\neventpreloadPath Stringerror ErrorEmitido cuando el script de preload preloadPathlanza una excepción no manejada error.
Devuelve:
\neventchannel Cadena...args any[]Emitido cuando el proceso de renderizado enviá un mensaje asíncrono a través de ipcRenderer.send().
Devuelve:
\neventchannel Cadena...args any[]Emitido cuando el proceso de renderizado envía un mensaje sincronídico a través de ipcRenderer.sendSync().
Devuelve:
\neventEmitted when desktopCapturer.getSources() is called in the renderer process. Llamando a event.preventDefault() hará que devuelva fuentes vacías.
Devuelve:
\neventpreferredSize Size - The minimum size needed to contain the layout of the document—without requiring scrolling.Emitted when the WebContents preferred size has changed.
This event will only be emitted when enablePreferredSizeMode is set to true in webPreferences.
Devuelve:
\neventdetails Objectframe WebFrameMainEmitido cuando el mainFrame, un <iframe>, o un anidado <iframe> es cargado dentro de la página.
contents.loadURL(url[, options])url Stringoptions Object (opcional)httpReferrer (String | Referrer) (opcional) - Una url HTTP Referencia.userAgent Cadena (opcional) - Un agente de usuario originando el pedido.extraHeaders String (optional) - Extra headers separated by \"\\n\".postData (UploadRawData | UploadFile)baseURLForDataURL String (opcional) - Url base (con separadores de ruta arrastrables) para archivos que se cargan por el url de datos. Esto es necesario únicamente si el url especificado es un url de datos y necesita cargar otros archivos.Devuelve Promise<void> - la promesa se resolverá cuando la página ha finalizado de cargar (mira did-finish-load), y rechaza si la página falla al cargar (miradid-fail-load). Un manejador de rechazo noop ya esta adjunto, el cual evita errores de rechazo no controlados.
Carga el url en la ventana. El url debe contener el prefijo de protocolo. Por ejemplo http:// o file://. Si la carga debe omitir el caché http entonces hay que utilizar el encabezado pragma para lograrlo.
const { webContents } = require('electron')\nconst options = { extraHeaders: 'pragma: no-cache\\n' }\nwebContents.loadURL('https://github.com', options)\ncontents.loadFile(filePath[, options])filePath Stringoptions Object (opcional)query Record<String, String> (opcional) - Pasado a url.format().search String (opcional) - Pasado a url.format().hash String (opcional) - Pasado a url.format().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).
Loads the given file in the window, filePath should be a path to an HTML file relative to the root of your application. For instance an app structure like this:
| root\n| - package.json\n| - src\n| - main.js\n| - index.html\nRequeriría un código como este
\nwin.loadFile('src/index.html')\ncontents.downloadURL(url)url StringInicia una descarga del recurso en url sin navegar. The will-download event of session will be triggered.
contents.getURL()Devuelve String - El URL de la página web actual.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com').then(() => {\n const currentURL = win.webContents.getURL()\n console.log(currentURL)\n})\ncontents.getTitle()Devuelve String - El título de la página web actual.
contents.isDestroyed()Devuelve Boolean - Si la página web fue destruida o no.
contents.focus()Enfoca la página web.
\ncontents.isFocused()Devuelve Boolean - Si se enfocó o no la página web.
contents.isLoading()Devuelve Boolean - Si todavía la página web está cargando recursos.
contents.isLoadingMainFrame()Devuelve Boolean - Si el marco principal (y no sólo iframes o frames dentro de él) todavía está cargando.
contents.isWaitingForResponse()Devuelve Boolean - Si la página web espera una primera respuesta desde el recurso principal de la página.
contents.stop()Detiene cualquier navegación pendiente.
\ncontents.reload()Recarga la página web actual.
\ncontents.reloadIgnoringCache()Recarga la página actual e ignora el caché.
\ncontents.canGoBack()Devuelve Boolean - Si el navegador puede volver a la página web anterior.
contents.canGoForward()Devuelve Boolean - Si el navegador puede avanzar a la siguiente página web.
contents.canGoToOffset(offset)offset ÍntegroDevuelve Boolean - Si la página web puede ir a offset.
contents.clearHistory()Borra el historial de navegación.
\ncontents.goBack()Hace que el navegador regrese a una página web.
\ncontents.goForward()Hace que el navegador avance a una página web.
\ncontents.goToIndex(index)index ÍntegroNavega al índice de página web absoluta especificado.
\ncontents.goToOffset(offset)offset ÍntegroNavega hacia el offset especificado desde \"la entrada actual\".
\ncontents.isCrashed()Devuelve Boolean - Si el proceso de renderizado ha fallado.
contents.forcefullyCrashRenderer()Forzosamente termina el renderer process que actualmente aloja este webContents. Esto hará que sea emitido el evento render-process-gone con el reason=killed || reason=crashed. Tenga en cuenta que algunos webContents comparten el renderer process y por lo tanto llamar a este método puede causar que se bloque el proceso también para otros wevContents.
Llamar a reload() inmediatamente después de llamar a este método forzará que la recarga ocurra en un nuevo proceso. Esto debería ser usado cuando el proceso es inestable o inutilizable, por ejemplo parar recuperar del evento unresponsive.
contents.on('unresponsive', async () => {\n const { response } = await dialog.showMessageBox({\n message: 'App X has become unresponsive',\n title: 'Do you want to try forcefully reloading the app?',\n buttons: ['OK', 'Cancel'],\n cancelId: 1\n })\n if (response === 0) {\n contents.forcefullyCrashRenderer()\n contents.reload()\n }\n})\ncontents.setUserAgent(userAgent)userAgent cadenaAnula el agente usuario para esta página web.
\ncontents.getUserAgent()Devuelve String - El agente usuario para esta página web.
contents.insertCSS(css[, options])css Cadenaoptions Object (opcional)cssOrigin String (optional) - Can be either 'user' or 'author'; Specifying 'user' enables you to prevent websites from overriding the CSS you insert. Default is 'author'.Devuelve Promise<String> - Una promesa que resuelve con una llave para el CSS insertado que puede ser utilizado más tarde para eliminar el CSS a través contents.removeInsertedCSS(key).
Inyecta CSS en la página web actual y devuelve un identificador único para la hoja de estilo insertada.
\ncontents.on('did-finish-load', () => {\n contents.insertCSS('html, body { background-color: #f00; }')\n})\ncontents.removeInsertedCSS(key)llave CadenaDevuelve Promise<void> - Resuelve si la eliminación fue exitosa.
Elimina el CSS insertado desde la página web actual. La hoja de estilos se identifica por su clave, el cual es devuelto desde contents.insertCSS(css).
contents.on('did-finish-load', async () => {\n const key = await contents.insertCSS('html, body { background-color: #f00; }')\n contents.removeInsertedCSS(key)\n})\ncontents.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (opcional) - Predeterminado es falso.Devuelve Promise<any> - Una promesa que resuelve con el resultado de la ejecución del código o es rechazada si el resultado del código es una promesa rechazada.
Evalúa el código en la página.
En la ventana del navegador, algunas API HTML como requestFullScreen solo pueden invocarse con un gesto del usuario. Establecer userGesture a true eliminará esta limitación.
La ejecución de código se suspenderá hasta que la pagina pare de cargarse.
\ncontents.executeJavaScript('fetch(\"https://jsonplaceholder.typicode.com/users/1\").then(resp => resp.json())', true)\n .then((result) => {\n console.log(result) // Will be the JSON object from the fetch call\n })\ncontents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])worldId Integer - El ID de la palabra para correr javascript en, 0 es el mundo por defecto, 999 es el mundo usado por la característica contextIsolation de Electron. Aquí puede suministrar cualquier entero.scripts WebSource[]userGesture Boolean (opcional) - Predeterminado es falso.Devuelve Promise<any> - Una promesa que resuelve con el resultado de la ejecución del código o es rechazada si el resultado del código es una promesa rechazada.
Funciona como executeJavaScript pero evaluá scripts en un contexto aislado.
contents.setIgnoreMenuShortcuts(ignore)ignore BooleanIgnora los accesos directos del menú de la aplicación mientras se enfoca los contenidos de la web.
\ncontents.setWindowOpenHandler(handler)handler Función<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>
details Objecturl String - La versión resuelta de la URL pasada a window.open(). por ejemplo una ventana con window.open('foo') producirá algo como https://the-origin/the/current/path/foo.frameName String - Nombre de la ventana proporcionado en window.open()features String - Lista separada por coma de la características de ventana proporcionada a window.open().disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk or other.referrer Referrer - El remitente que será pasado a la nueva ventana. Puede resultar o no en la cabecera Referer siendo enviado, dependiendo de la política de referencia.postBody PostBody (opcional) - Los datos que serán enviados a la nueva ventana, junto con las cabeceras apropiadas que se establecerán. Si no hay datos para enviar, el valor será null. Solo se define cuando la ventana está siendo creada por un formulario que establece target=_blank.Devuelve {action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny cancela la creación de la nueva ventana. allow permitirá la que se cree la nueva ventana. Especificando overrideBrowserWindowOptions permite la personalización de la ventana creada. Devolver un valor no reconocido como un null, undefined o un objeto sin una 'action' reconocida resultará en un error de consola tiene el mismo efecto que devolver {action: 'deny'}.
Llamado antes de crear una ventana un solicitud de nueva ventana es solicitada por el renderer, p.e. por window.open(), un enlace con target=\"_blank\", shift+pulsando en un enlace, o enviando un formulario con <form target=\"_blank\">. Ver window.open() Para más detalles y como usar esto en conjunción con did-create-window.
contents.setAudioMuted(muted)muted BooleanSilencia el audio la página web actual.
\ncontents.isAudioMuted()Devuelve Boolean - Si esta página ha sido silenciada.
contents.isCurrentlyAudible()Devuelve Boolean - Si el audio se esta reproduciendo actualmente.
contents.setZoomFactor(factor)factor Double - Factor de zoom; por defecto es 1.0.Cambia el nivel de zoom al nivel especificado. Factor de zoom es porcentaje de zoom dividido entre 100, así que 300% = 3.0.
\nEl factor debe ser mayor que 0.0.
\ncontents.getZoomFactor()Devuelve Number - el factor de zoom actual.
contents.setZoomLevel(level)nivel Número - Nivel de Zoom.Cambia el nivel de zoom al nivel especificado. El tamaño original es 0 y cada incremento por encima o por debajo representa un zoom del 20% mayor o menor a los límites predeterminados de 300% y 50% del tamaño original, respectivamente. La fórmula para esto es scale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
contents.getZoomLevel()Devuelve Number - el nivel de zoom actual.
contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NúmeromaximumLevel NúmeroDevuelve Promise<void>
Establecer el nivel de máximo y mínimo pizca de zoom.
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\ncontents.setVisualZoomLevelLimits(1, 3)\n
contents.undo()Ejecuta el comando de edición undo en la página web.
contents.redo()Ejecuta el comando de edición redo en la página web.
contents.cut()Ejecuta el comando de edición cut en la página web.
contents.copy()Ejecuta el comando de edición copy en la página web.
contents.copyImageAt(x, y)x Integery IntegerCopia la imagen en la posición determinada al portapapeles.
\ncontents.paste()Ejecuta el comando de edición paste en la página web.
contents.pasteAndMatchStyle()Ejecuta el comando de edición pasteAndMatchStyle en la página web.
contents.delete()Ejecuta el comando de edición delete en la página web.
contents.selectAll()Ejecuta el comando de edición selectAll en la página web.
contents.unselect()Ejecuta el comando de edición unselect en la página web.
contents.replace(text)texto CadenaEjecuta el comando de edición replace en la página web.
contents.replaceMisspelling(text)texto CadenaEjecuta el comando de edición replaceMisspelling en página web.
contents.insertText(text)texto CadenaDevuelve Promise<void>
Inserta texto en el elemento enfocado.
contents.findInPage(text[, options])text String - El contenido para ser buscado, no debe quedar en blanco.options Object (opcional)forward Boolean (opcional) - Ya sea para buscar hacia adelante o hacia atrás, el valor predeterminado es true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Por defecto es false.matchCase Boolean (opcional) - Si la busqueda debe ser sensible a mayúsculas, por defecto es false.Devuelve Integer - El id de la solicitud usado para la solicitud.
Empieza una solicitud para encontrar todas las coincidencias para el text en la página web. El resultado de la solicitud puede ser obtenida suscribiendote al evento found-in-page.
contents.stopFindInPage(action)action String - Specifies the action to take place when ending [webContents.findInPage] request.clearSelection - Borrar la selección.keepSelection - Traduce la selección en una selección normal.activateSelection - Enfoca y hace clic en el nodo de selección.Detiene cualquier solicitud findInPage para el webContents con la action proporcionada.
const { webContents } = require('electron')\nwebContents.on('found-in-page', (event, result) => {\n if (result.finalUpdate) webContents.stopFindInPage('clearSelection')\n})\n\nconst requestId = webContents.findInPage('api')\nconsole.log(requestId)\ncontents.capturePage([rect])rect Rectangle (opcional) - El área de la página para ser capturada.Devuelve Promise<NativeImage> - Resuelve con el un NativeImage
Captura una foto instantánea de la página dentro de rect. Omitiendo rect capturará toda la página visible.
contents.isBeingCaptured()Devuelve Boolean - Si esta página está siendo capturada. Devuelve true cuando el recuento de capturadores es mas grande que 0.
contents.incrementCapturerCount([size, stayHidden, stayAwake])size Tamaño (opcional) - El tamaño preferido para el capturador.stayHidden Boolean (opcional) - Mantiene la página oculta en lugar de visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Incrementa el contador de captura en uno. La página es considerada visible cuando su ventana de navegador está oculta y el recuento del capturador no es cero. Si le gustaría que la página permanezca oculta, debería asegurarse que stayHidden está establecido a true.
Esto también afecta a la API de visibilidad de la página.
\ncontents.decrementCapturerCount([stayHidden, stayAwake])stayHidden Boolean (opcional) - Mantiene la página en estado oculto en lugar de visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Disminuye el recuento del capturador en uno. La página se establecerá en el estado oculto u ocluido cuando la ventana del navegador esté oculta u ocluida y el recuento del capturador llegue a cero. Si quiere disminuir el contador del caputador en su lugar debería establecer stayHidden a true.
contents.getPrinters()Obtiene la lista de impresora del sistema.
\nDevuelve PrinterInfo[]
contents.print([options], [callback])options Object (opcional)silent Boolean (optional) - Don't ask user for print settings. Por defecto es false.printBackground Boolean (optional) - Prints the background color and image of the web page. Por defecto es false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. Por defecto es true.margins Object (opcional)marginType String (opcional) - Puede ser default, none, printableArea, o custom. Si custom es elegido, además necesitar especificar top, bottom, left, y right.top Number (opcional) - El margen superior de la página web impresa, en píxeles.bottom Number (opcional) - El margen inferior de la página web impresa, en píxeles.left Number (opcional) - El margen izquierdo de la página web impresa, en píxeles.right Number (opcional) - El margen derecho de la página web impresa, en píxeles.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. Por defecto es false.scaleFactor Number (opcional) - El factor de escalado de la página web.pagesPerSheet Number (opcional) - El número de páginas a imprimir por hoja de página.collate Boolean (opcional) - Si la página web debe ser intercalada.copies Number (opcional) - El número de copias de la página web a imprimir.pageRanges Object - The page range to print. On macOS, only one range is honored.from Number - Index of the first page to print (0-based).to Number - Índice de la última página a imprimir (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Puede ser simplex, shortEdge, o longEdge.dpi Record<string, number> (opcional)horizontal Number (opcional) - El dpi horizontal.vertical Number (opcional) - El dpi vertical.header String (opcional) - Cadena a ser impresa como cabecera de la página.footer String (opcional) - Cadena a ser impresa como pie de página.pageSize String | Tamaño (opcional) - Especifique el tamaño de página del documento impreso. Puede ser A3, A4, A5, Legal, Letter, Tabloid o un objeto que contenga height.retrocallback Funcion (opcional)success Boolean - Indica el éxito de la llamada impresa.failureReason String - Descripción del error llamada de nuevo si la impresión falla.Cuando es pasado un pageSize personalizado, Chromium intenta validar los valores mínimos específicos de la plataforma para width_microns y height_microns. Ambos anchura y altura deben ser mínimamente 353 microns, pero puede ser más grande en algunos sistemas operativos.
Imprime la página web de la ventana. Cuando silent está establecido a true, Electron tomará la impresora predeterminada del sistema si deviceName está vacío y las configuraciones por defecto para imprimir.
Utilizar el estilo CCS page-break-before: always; para imprimir a la fuerza una página nueva.
Ejemplo de uso:
\nconst options = {\n silent: true,\n deviceName: 'My-Printer',\n pageRanges: [{\n from: 0,\n to: 1\n }]\n}\nwin.webContents.print(options, (success, errorType) => {\n if (!success) console.log(errorType)\n})\ncontents.printToPDF(options)options ObjectheaderFooter Record<string, string> (opcional) - el encabezado y el pie de página para el PDF.title String - El título para el encabezado PDF.url String - la url para el pie de página PDF.landscape Boolean (opcional) - true for landscape, false para portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin.scaleFactor Number (opcional) - El factor de escalado de la página web. Puede variar entre 0 to 100.pageRanges Record<string, number> (optional) - The page range to print.from Number - Index of the first page to print (0-based).to Number - Índice de la última página a imprimir (inclusive) (0-based).pageSize String | Size (opcional) - Especifica el tamaño de la página del PDF generado. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height and width in microns.printBackground Boolean (octional) - Si se va a imprimir los fondos CSS.printSelectionOnly Boolean (opcional) - Se va a imprimir solo la selección.Returns Promise<Buffer> - Se resuelve cuando los datos PDF son generados.
Imprime la página web de la ventana como PDF con la configuración personalizada de impresión previa de Chromium.
\nEl landscape se ignorará si @page CSS at-rule es utilizado en la página web.
Por defecto, una options en blanco se considerará como:
{\n marginsType: 0,\n printBackground: false,\n printSelectionOnly: false,\n landscape: false,\n pageSize: 'A4',\n scaleFactor: 100\n}\nUtilizar el estilo CCS page-break-before: always; para imprimir a la fuerza una página nueva.
Un ejemplo de webContents.printToPDF:
const { BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\nconst os = require('os')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nwin.webContents.on('did-finish-load', () => {\n // Use default printing options\n win.webContents.printToPDF({}).then(data => {\n const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')\n fs.writeFile(pdfPath, data, (error) => {\n if (error) throw error\n console.log(`Wrote PDF successfully to ${pdfPath}`)\n })\n }).catch(error => {\n console.log(`Failed to write PDF to ${pdfPath}: `, error)\n })\n})\ncontents.addWorkSpace(path)path StringAgrega la ruta especificada al workspace de DevTools. Debe ser usado después de la creación de DevTools:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.on('devtools-opened', () => {\n win.webContents.addWorkSpace(__dirname)\n})\ncontents.removeWorkSpace(path)path StringElimina la ruta especificada del espacio de trabajo de DevTools.
\ncontents.setDevToolsWebContents(devToolsWebContents)devToolsWebContents WebContentsUsa el devToolsWebContents como objetivo WebContents para mostrar devtools.
El devToolsWebContents no debe tener ninguna ninguna navegación, y este no debería ser usado para otros propósitos después de la llamada.
Por defecto Electron maneja el devtools creando un WebContents interno con un vista nativa, de lo cual los desarrolladores tienen un control muy limitado. Con el método setDevToolsWebContents, los desarrolladores pueden usar algún WebContents para mostrar el devtools en él, incluyendo la etiqueta BrowserWindow, BrowserView y <webview>.
Tenga en cuenta que cerrando el devtools no se destruye el devToolsWebContents, es responsabilidad del que llamo destruir el devToolsWebContents.
Un ejemplo de mostrar devtools en una etiqueta <webview>:
<html>\n<head>\n <style type=\"text/css\">\n * { margin: 0; }\n #browser { height: 70%; }\n #devtools { height: 30%; }\n </style>\n</head>\n<body>\n <webview id=\"browser\" src=\"https://github.com\"></webview>\n <webview id=\"devtools\" src=\"about:blank\"></webview>\n <script>\n const { ipcRenderer } = require('electron')\n const emittedOnce = (element, eventName) => new Promise(resolve => {\n element.addEventListener(eventName, event => resolve(event), { once: true })\n })\n const browserView = document.getElementById('browser')\n const devtoolsView = document.getElementById('devtools')\n const browserReady = emittedOnce(browserView, 'dom-ready')\n const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')\n Promise.all([browserReady, devtoolsReady]).then(() => {\n const targetId = browserView.getWebContentsId()\n const devtoolsId = devtoolsView.getWebContentsId()\n ipcRenderer.send('open-devtools', targetId, devtoolsId)\n })\n </script>\n</body>\n</html>\n// Main process\nconst { ipcMain, webContents } = require('electron')\nipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {\n const target = webContents.fromId(targetContentsId)\n const devtools = webContents.fromId(devtoolsContentsId)\n target.setDevToolsWebContents(devtools)\n target.openDevTools()\n})\nUn ejemplo de mostrar devtools en un BrowserWindow:
const { app, BrowserWindow } = require('electron')\n\nlet win = null\nlet devtools = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n devtools = new BrowserWindow()\n win.loadURL('https://github.com')\n win.webContents.setDevToolsWebContents(devtools.webContents)\n win.webContents.openDevTools({ mode: 'detach' })\n})\ncontents.openDevTools([options])options Object (opcional)mode String - Abre las herramientas del desarrollador con el estado de dock especificado, puede ser right, bottom, undocked, detach. Por defecto se utiliza el último estado de dock. En el modo undocked es posible acoplarse de nuevo. En el modo detach no se puede.activate Boolean (optional) - Whether to bring the opened devtools window to the foreground. El valor por defecto es true.Abre las herramientas del desarrolador.
\nCuando contents es un tag <webview>, el mode debería ser detach por defecto, explícitamente pasando un mode vacío puede forzar el uso del último estado del dock.
contents.closeDevTools()Cierra las devtools.
\ncontents.isDevToolsOpened()Devuelve Boolean - Si se abren las herramientas del desarrollador.
contents.isDevToolsFocused()Devuelve Boolean - Si se enfoca la vista de las herramientas del desarrollador .
contents.toggleDevTools()Alterna las herramientas de desarrollador.
\ncontents.inspectElement(x, y)x Integery IntegerEmpieza a inspeccionar elementos en la posición (x, y).
contents.inspectSharedWorker()Abre las herramientas de desarrollador para el contexto de los trabajadores compartidos.
\ncontents.inspectSharedWorkerById(workerId)workerIdInspecciona el worker compartido basado en su ID.
\ncontents.getAllSharedWorkers()Devuelve SharedWorkerInfo[] - Información acerca de todos los Workers Compartidos.
contents.inspectServiceWorker()Abre las herramientas de desarrollador para el contexto del trabajador de servicio.
\ncontents.send(channel, ...args)channel Cadena...args any[]Envía un mensaje asíncrono al render process a través de channel, junto con los argumentos. Los argumentos serán serializados con el Structured CloneAlgorithm, al igual que postMessage, así que las cadenas del prototipo no estarán incluidas. El envío de funciones, promesas, símbolos, WeakMaps o WeakSets lanzará una excepción.
\n\nNOTA: Enviar tipos de JavaScript no estándar tales como objetos DOM o objetos especiales de Electron lanzará una excepción.
\n
El proceso de renderizado puede manejar el mensaje escuchando el canal con el módulo ipcRenderer.
Un ejemplo de envío de mensajes desde el proceso principal al proceso de renderizado:
\n/// In the main process.\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL(`file://${__dirname}/index.html`)\n win.webContents.on('did-finish-load', () => {\n win.webContents.send('ping', 'whoooooooh!')\n })\n})\n<!-- index.html -->\n<html>\n<body>\n <script>\n require('electron').ipcRenderer.on('ping', (event, message) => {\n console.log(message) // Prints 'whoooooooh!'\n })\n </script>\n</body>\n</html>\ncontents.sendToFrame(frameId, channel, ...args)frameId Integer | [number, number] - the ID of the frame to send to, or a pair of [processId, frameId] if the frame is in a different process to the main frame.channel Cadena...args any[]Envía un mensaje asíncrono al frame especifico en un renderer process a través de channel, junto con los argumentos. Los argumentos serán serializados con el Structured CloneAlgorithm, al igual que postMessage, así que las cadenas del prototipo no estarán incluidas. El envío de funciones, promesas, símbolos, WeakMaps o WeakSets lanzará una excepción.
\n\nNOTA: Enviar tipos de JavaScript no estándar tales como objetos DOM o objetos especiales de Electron lanzará una excepción.
\n
El proceso de renderizado puede manejar el mensaje escuchando el canal con el módulo ipcRenderer.
Si quieres obtener el frameId de un renderer context dado deberías usar el valor webFrame.routingId. P.e.
// In a renderer process\nconsole.log('My frameId is:', require('electron').webFrame.routingId)\nTambién puede leer el frameId de todos los mensajes IPC entrantes en el proceso principal.
// In the main process\nipcMain.on('ping', (event) => {\n console.info('Message came from frameId:', event.frameId)\n})\ncontents.postMessage(channel, message, [transfer])Envía un mensaje al renderer process, transfiriendo opcionalmente la propiedad de cero o más objetos [MessagePortMain][].
Los objetos MessagePortMain transferidos estarán disponible en el renderer process accediendo a la propiedad ports del evento emitido. Cuando llegan al renderer, serán objetos DOM MessagePort nativos.
Por ejemplo:
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\ncontents.enableDeviceEmulation(parameters)parametersscreenPosition String - Specify the screen type to emulate (default: desktop):desktop - El tipo de la pantalla de escritorio.mobile - El tipo de la pantalla móvil.screenSize Size - Configura el tamaño de la pantalla emulada (screenPosition == mobile).viewPosition Point - Posiciona la vista sobre la pantalla (screenPosition == mobile) (por defecto: { x: 0, y: 0 }).deviceScaleFactor Integer - Configura el factor escala del dispositivo (si es cero regresa por defecto al factor de escala original del dispositivo) (por defecto: 0).viewSize Size - Configura el tamaño de la vista emulada (en blanco significa que no hay anulación)scale Float - Escala de la vista emulada dentro del espacio disponible (no dentro del modo vista) (por defecto: 1).Habilita la emulación del dispositivo con los parámetros predeterminados.
\ncontents.disableDeviceEmulation()Deshabilita la emulación del dispositivo habilitado por webContents.enableDeviceEmulation.
contents.sendInputEvent(inputEvent)inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventEnvía un input event a la página. Nota: El BrowserWindow que contiene los contenidos necesita estar enfocado para que sendInputEvent() trabaje.
contents.beginFrameSubscription([onlyDirty ,]callback)onlyDirty Boolean (opcional) - Por defecto es false.callback Funciónimage NativeImagedirtyRect RectangleEmpezar suscripción para eventos de presentación y capturas de fotogramas, la callback sera llamada con callback(image, dirtyRect) cuando hay un evento de presentación.
La image es una instancia de NativeImage que almacena el fotograma capturado.
El dirtyRect es un objeto con propiedades x, y, width, height que describe cual parte de la página fue pintada de nuevo. Si onlyDirty está configurado a true, image solo contendrá el área repintada. onlyDirty por defecto en false.
contents.endFrameSubscription()Finalizar suscripción para eventos de presentación de marcos.
\ncontents.startDrag(item)itemfile String - La ruta al archivo que está siendo arrastrado.files String - Las rutas a los archivos que están siendo arrastrados. (files anulará el campo file)icon NativeImage | String - La imagen no debe estar vacía en on macOS.Configura el item como un elemento arrastrable para la operación drag-drop actual. El file es la ruta absoluta del archivo que se va a arrastrar, y icon es la imagen que se muestra debajo del cursor cuando se arrastra.
contents.savePage(fullPath, saveType)fullPath String - La ruta completa del archivo.saveType String - Specify the save type.HTMLOnly - Guarda solamente el HTML de la página.HTMLComplete - Guarda una página html completa.MHTML - Guarda una página html completa como MHTML.Devuelve Promise<void> - resuelve si la pagina se guardo.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.loadURL('https://github.com')\n\nwin.webContents.on('did-finish-load', async () => {\n win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {\n console.log('Page was saved successfully.')\n }).catch(err => {\n console.log(err)\n })\n})\ncontents.showDefinitionForSelection() macOSMuestra un diccionario que busca la palabra seleccionada en la página.
\ncontents.isOffscreen()Devuelve Boolean - Indica si offscreen rendering está habilitado o no.
contents.startPainting()Si offscreen rendering está habilitado y no pinta, comienza a pintar.
\ncontents.stopPainting()Si offscreen rendering está habilitado y pinta, deja de pintar.
\ncontents.isPainting()Devuelve Boolean - Si offscreen rendering está habilitado devuelve lo que esté pintando en ese momento.
contents.setFrameRate(fps)fps IntegerSi offscreen rendering está activada establece el radio del frame al número especificado. Sólo se aceptan valores entre 1 y 240.
\ncontents.getFrameRate()Devuelve Integer - Si offscreen rendering esta habilitado devuelve el indice de fotogramas en ese momento.
contents.invalidate()Programa un repintado completo de la ventana en la que se encuentra este contenido web.
\nSi offscreen rendering está habilitado invalida el fotograma y genera uno nuevo a través del evento 'paint'.
contents.getWebRTCIPHandlingPolicy()Devuelve String - Devuelve el WebRTC IP Handling Policy.
contents.setWebRTCIPHandlingPolicy(policy)policy String - Specify the WebRTC IP Handling Policy.default - Revela los IPs locales y publicos del usuario. Este es el comportamiento por defecto. Cuando se usa esta política, WebRTC tiene el derecho de enumerar todas las interfaces y vincularlas para descubrir interfaces públicas.default_public_interface_only - Revela el IP público del usuario pero no revela el IP local del usuario. Cuando se usa esta política, WebRTC solo debe usar la ruta predeterminada utilizada por http. Esto no expone ninguna dirección local.default_public_and_private_interfaces - Revela los IPs público y local del usuario. Cuando se usa esta política, WebRTC solo debe usar la ruta predeterminada utilizada por http. Esto también expone la dirección privada predeterminada asociada. La ruta predeterminada es la ruta elegida por el SO en un punto final multitarjeta.disable_non_proxied_udp - Does not expose public or local IPs. When this policy is used, WebRTC should only use TCP to contact peers or servers unless the proxy server supports UDP.La configuración de política de manejo WebRTC IP, le permite controlar cuales IPs son expuestas a través de WebRTC. Vea BrowserLeaks para más detalles.
\ncontents.getOSProcessId()Devuelve Integer - El pid del sistema operativo, del proceso de renderizado asociado.
contents.getProcessId()Devuelve Integer - El pid interno de Chromium del renderizador asociado. Puede ser comparado con el frameProcessId pasado por los eventos de navegación específicos del frame (e.g. did-frame-navigate)
contents.takeHeapSnapshot(filePath)filePath String - Ruta al archivo de salida.Devuelve Promise<void> - Indica si la instantánea se ha creado correctamente.
Toma una instantánea de la pila V8 y la guarda en filePath.
contents.getBackgroundThrottling()Devuelve Boolean - si este contenido web acelerará o no animaciones y temporizadores cuando la página se haga de fondo. Esto también afecta a la API de visibilidad de la página.
contents.setBackgroundThrottling(allowed)allowed BooleanControla si este WebContents acelerará o no las animaciones y los temporizadores cuando la página pasa a segundo plano. Esto también afecta a la API de visibilidad de la página.
\ncontents.getType()Devuelve String - el tipo de webContent. Puede ser backgroundPage, window, browserView, remote, webview o offscreen.
contents.setImageAnimationPolicy(policy)policy String - Puede ser animate, animateOnce o noAnimation.Establece la política de animación de imágenes para este webContents. La política solo afecta a imágenes new, las imágenes que se está animando actualmente no son afectadas. Esta es una limitación conocida en Chromium, puede forzar que la animación de la imagen sea recalculada con img.src = img.src lo cual no dará como resultado tráfico de red pero actualizará la política de la animación.
Esto corresponde a la característica de accesibilidad animationPolicy en Chromium.
\ncontents.audioMutedUna propiedad Boolean que determina si la página está silenciada.
contents.userAgentUna propiedad String que determina el user agent para esta página web.
contents.zoomLevelUna propiedad Number que determina el nivel de zoom de este contenido web.
El tamaño original es 0 y cada incremento por encima o por debajo representa un zoom del 20% mayor o menor a los límites predeterminados de 300% y 50% del tamaño original, respectivamente. La formula para esto es scale := 1.2 ^ level.
contents.zoomFactorUna propiedad Number que determina el facto del zoom para este contenido web.
El factor de zoom es el porcentaje de zoom dividido entre 100, por lo que 300% = 3.0.
\ncontents.frameRateUna propiedad Integer que establece el ratio del frame del contenido web al número especificado. Sólo se aceptan valores entre 1 y 240.
Solo aplicable si offscreen rendering está habilitado.
\ncontents.id SoloLecturaUn Integer representando el ID único de este WebContents. Cada ID es único entre todas las instancias WebContents de toda la aplicación Electron.
contents.session SoloLecturaUn Session usado por este webContents.
contents.hostWebContents SoloLecturaUn instancia de WebContents que podría poseer este WebContents.
contents.devToolsWebContents SoloLecturaUna propiedad WebContents | null que representa el WebContents de la DevTools asociada con el WebContents dado.
Note: Los usuario nunca deberían almacenar este objeto porque puede convertirse en null cuando el DevTools ha sido cerrado.
contents.debugger SoloLecturaUna instancia Debugger para este webContents.
contents.backgroundThrottlingUna propiedad Boolean que determina si este WebContents acelera o no las animaciones y los temporizadores cuando la página pasa a segundo plano. Esto también afecta a la API de visibilidad de la página.
contents.mainFrame SoloLecturaA WebFrameMain property that represents the top frame of the page's frame hierarchy.
Si quiere incrustar contenido web (de terceros) en un BrowserWindow de Electron, hay tres opciones disponible para usted: <iframe> tags, <webview> tags, y BrowserViews. Cada una ofrece una funcionalidad ligeramente diferente y es útil en diferentes situaciones. To help you choose between these, this guide explains the differences and capabilities of each option.
Iframes en Electron se comportan como iframes en los navegadores regulares. An <iframe> element in your page can show external web pages, provided that their Content Security Policy allows it. To limit the number of capabilities of a site in an <iframe> tag, it is recommended to use the sandbox attribute and only allow the capabilities you want to support.
\n\nNota importante: no se recomienda el uso de WebViews, ya que esta etiqueta genera cambios dramáticos en la arquitectura que podrían afectar a la estabilidad de tu aplicación. Considere cambiar a alternativas, como
\niframeyBrowserViewde Electron, o una arquitectura que evite el contenido incrustado por diseño.
WebViews son basados en las WebViews de Chromium y no están soportados explícitamente por Electron. No garantizamos que la API WebView permanezca disponible en versiones futuro de Electron. Para usar <webview> etiquetas, necesitaras establecer webviewTag a true en el webPreferences de tu BrowserWindow.
WebView es un elemento personalizado (<webview>) que sólo funcionara dentro de Electron. Están implementadas como un \"iframe fuera de proceso\". Esto quiere decir que toda la comunicación con el <webview> se hace de forma asíncrona usando IPC. The <webview> element has many custom methods and events, similar to webContents, that provide you with greater control over the content.
Compared to an <iframe>, <webview> tends to be slightly slower but offers much greater control in loading and communicating with the third-party content and handling various events.
BrowserViews are not a part of the DOM - instead, they are created in and controlled by your Main process. Son simplemente otra capa de contenido web sobre su ventana existente. Esto quiere decir que están completamente separados de tu propio contenido BrowserWindow y su posición no es controlada por el DOM o CSS. En su lugar, es controlado estableciendo limites en el Main process.
BrowserViews ofrece el mayor control sobre sus contenidos, ya que implementan el webContents de forma similar a como BrowserWindow lo hace. Sin embargo, como BrowserViews no son parte de tu DOM, sino que están superpuestos sobre ellos, tendrá que administrar su posición manualmente.
\n\nPersonalizar el renderizado de la página web actual.
\n
Proceso: Renderer
\nwebFrame exportación del mudulo Electron es una instancia de la clase WebFrame que representa el frame superior del actual BrowserWindow. Sub-frames pueden ser recuperados a través de propiedades y métodos determinados (ejemplo webFrame.firstChild).
Un ejemplo de zoom de la página actual al 200%.
\nconst { webFrame } = require('electron')\n\nwebFrame.setZoomFactor(2)\nLa clase WebFrame tiene los siguientes métodos de instancia:
webFrame.setZoomFactor(factor)factor Double - Factor de zoom; por defecto es 1.0.Cambia el nivel de zoom al nivel especificado. Factor de zoom es porcentaje de zoom dividido entre 100, así que 300% = 3.0.
\nEl factor debe ser mayor que 0.0.
\nwebFrame.getZoomFactor()Devuelve Número - El factor de zoom actual.
webFrame.setZoomLevel(level)nivel Número - Nivel de Zoom.Cambia el nivel de zoom al nivel especificado. El tamaño original es 0 y cada incremento por encima o por debajo representa un zoom del 20% mayor o menor a los límites predeterminados de 300% y 50% del tamaño original, respectivamente.
\n\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
webFrame.getZoomLevel()Devuelve Número - El nivel de zoom actual.
webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NúmeromaximumLevel NúmeroEstablecer el nivel de máximo y mínimo pizca de zoom.
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\nwebFrame.setVisualZoomLevelLimits(1, 3)\n
\n\nNOTE: Visual zoom only applies to pinch-to-zoom behavior. Cmd+/-/0 zoom shortcuts are controlled by the 'zoomIn', 'zoomOut', and 'resetZoom' MenuItem roles in the application Menu. Para desactivar los atajos manualmente, defina el menú y omita los roles de zoom de la definición.
\n
webFrame.setSpellCheckProvider(language, provider)idioma CadenaproviderspellCheck Funciónwords String[]callback FunciónmisspeltWords String[]Establece un proveedor para la corrección ortográfica en campos de entrada y áreas de texto.
\nSi quiere utilizar este método debe deshabilitar el corrector ortográfico incorporado cuando construya la ventana.
\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: false\n }\n})\nEl provider debe ser un objeto que tiene un método spellCheck que acepte un array de palabras individuales para revisión ortográfica. La función spellCheck corre cronológicamente y llama a la función callback con un array de palabras mal escritas cuando se completa.
Un ejemplo de uso de node-spellchecker como proveedor:
\nconst { webFrame } = require('electron')\nconst spellChecker = require('spellchecker')\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck (words, callback) {\n setTimeout(() => {\n const spellchecker = require('spellchecker')\n const misspelled = words.filter(x => spellchecker.isMisspelled(x))\n callback(misspelled)\n }, 0)\n }\n})\nwebFrame.insertCSS(css)css String - CSS codigo de origen.Devuelve String - Una llave para el CSS insertado que puede ser utilizado más tarde para eliminar el CSS a través de webFrame.removeInsertedCSS(key).
Inyecta CSS en la página web actual y devuelve un identificador único para la hoja de estilo insertada.
\nwebFrame.removeInsertedCSS(key)llave CadenaElimina el CSS insertado desde la página web actual. La hoja de estilos se identifica por su clave, el cual es devuelto desde webFrame.insertCSS(css).
webFrame.insertText(texto)texto CadenaInserta texto en el elemento enfocado.
webFrame.executeJavaScript(code[, userGesture, callback])code StringuserGesture Boolean (opcional) - Predeterminado es falso.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.resultado Cualquieraerror ErrorReturns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
Evalúa el código en la página.
En la ventana del navegador, algunas API HTML como requestFullScreen solo pueden invocarse con un gesto del usuario. Establecer userGesture a true eliminará esta limitación.
webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])worldId Integer - The ID of the world to run the javascript in, 0 is the default main world (where content runs), 999 is the world used by Electron's contextIsolation feature. Accepts values in the range 1..536870911.scripts WebSource[]userGesture Boolean (opcional) - Predeterminado es falso.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.resultado Cualquieraerror ErrorReturns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution could not start.
Funciona como executeJavaScript pero evaluá scripts en un contexto aislado.
Note that when the execution of script fails, the returned promise will not reject and the result would be undefined. This is because Chromium does not dispatch errors of isolated worlds to foreign worlds.
webFrame.setIsolatedWorldInfo(worldId, info)worldId Integer - El ID de la palabra para correr javascript en, 0 es el mundo por defecto, 999 es el mundo usado por la característica de Electron contextIsolation. Las extenciones de Chrome reservan el rango de IDs en [1 << 20, 1 << 29). Aquí puede suministrar cualquier entero.infosecurityOrigin String (opcional) - Origen de seguridad para el mundo aislado.csp String (opcional) - Política de Seguridad de Contenido para el mundo aislado.name String (optional) - Name for isolated world. Useful in devtools.Set the security origin, content security policy and name of the isolated world. Note: If the csp is specified, then the securityOrigin also has to be specified.
webFrame.getResourceUsage()Devuelve Objeto:
images MemoryUsageDetailsscripts MemoryUsageDetailscssStyleSheets MemoryUsageDetailsxslStyleSheets MemoryUsageDetailsfonts MemoryUsageDetailsother MemoryUsageDetailsDevuelve un objeto que describe la información de uso de las cachés de memoria interna de Blink.
\nconst { webFrame } = require('electron')\nconsole.log(webFrame.getResourceUsage())\nEsto generará:
\n{\n images: {\n count: 22,\n size: 2549,\n liveSize: 2542\n },\n cssStyleSheets: { /* same with \"images\" */ },\n xslStyleSheets: { /* same with \"images\" */ },\n fonts: { /* same with \"images\" */ },\n other: { /* same with \"images\" */ }\n}\nwebFrame.clearCache()Intenta liberar memoria que ya no se usa (como las imágenes de una navegación anterior).
\nTenga en cuenta que llamar ciegamente este método probablemente haga que Electron sea más lento, ya que tendrá que volver a llenar estos cachés vacíos, solo debe llamarlo si ha ocurrido un evento en su aplicación que le haga pensar que su página está usando menos memoria (es decir, ha navegado desde una página muy pesada a una casi vacía, y tiene la intención de permanecer allí).
\nwebFrame.getFrameForSelector(selector)selector String - selector CSS para un elemento frame.Devuelve WebFrame - El elemento de frame en webFrame's documento seleccionado por selector, null sería devuelto si selector no selecciona un frame o si el frame no está en el proceso actual de renderizado.
webFrame.findFrameByName(name)name StringDeveulve WebFrame - Un hijo de webFrame con el name suministrado, null sería retornado is no hay tal frame o si el frame no está en el proceso renderer actual.
webFrame.findFrameByRoutingId(routingId)routingId Integer - Un Integer representando el id único del frame en el proceso renderer actual. Las IDs de rutas se pueden recuperar de WebFrame instancias (webFrame.routingId) y también son pasados por el frame WebContents específicos eventos de navegación (por ejemplo, did-frame-navigate)Devuelve WebFrame - que tiene el routingId proporcionado, null si no se encuentra.
webFrame.isWordMisspelled(word)word String - The word to be spellchecked.Returns Boolean - True if the word is misspelled according to the built in spellchecker, false otherwise. If no dictionary is loaded, always return false.
webFrame.getWordSuggestions(word)word String - The misspelled word.Returns String[] - A list of suggested words for a given word. If the word is spelled correctly, the result will be empty.
webFrame.top ReadonlyUn WebFrame | null que representa el frame superior en la jerarquía de frames al cual pertenece el webFrame, la propiedad debe ser null si el frame superior no está en el renderer process actual.
webFrame.opener ReadonlyUn WebFrame representa el frame webFrame que abrió, la propiedad debería ser null si no hay abridores o si el abridor no está en el proceso renderer actual.
webFrame.parent ReadonlyUn WebFrame | null que representa el frame padre de webFrame, la propiedad debería ser null si webFrame es superior o el padre no está en renderer process actual.
webFrame.firstChild ReadonlyUn WebFrame | null que representa al primer frame hijo de webFrame, la propiedad debería ser null si webFrame no tiene hijos o el primer hijo no esta en el renderer process actual.
webFrame.nextSibling ReadonlyUn WebFrame | null que representa el siguiente frame hermano, la propiedad debería ser null si webFrame es el último frame en su padre o si el siguiente hermano no está en el renderer process actual.
webFrame.routingId ReadonlyAn Integer representing the unique frame id in the current renderer process. Distinct WebFrame instances that refer to the same underlying frame will have the same routingId.
\n\nControl web pages and iframes.
\n
Proceso: principal</0>
\nThe webFrameMain module can be used to lookup frames across existing WebContents instances. Navigation events are the common use case.
const { BrowserWindow, webFrameMain } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://twitter.com')\n\nwin.webContents.on(\n 'did-frame-navigate',\n (event, url, isMainFrame, frameProcessId, frameRoutingId) => {\n const frame = webFrameMain.fromId(frameProcessId, frameRoutingId)\n if (frame) {\n const code = 'document.body.innerHTML = document.body.innerHTML.replaceAll(\"heck\", \"h*ck\")'\n frame.executeJavaScript(code)\n }\n }\n)\nTambién puedes acceder a los frames de una página existente usando la propiedad mainFrame de WebContents.
const { BrowserWindow } = require('electron')\n\nasync function main () {\n const win = new BrowserWindow({ width: 800, height: 600 })\n await win.loadURL('https://reddit.com')\n\n const youtubeEmbeds = win.webContents.mainFrame.frames.filter((frame) => {\n try {\n const url = new URL(frame.url)\n return url.host === 'www.youtube.com'\n } catch {\n return false\n }\n })\n\n console.log(youtubeEmbeds)\n}\n\nmain()\nThese methods can be accessed from the webFrameMain module:
webFrameMain.fromId(processId, routingId)processId Integer - Un Integer representando el ID interno del proceso que posee el frame.routingId Integer - Un Integer representando el ID único del frame en el renderer process actual. Routing IDs can be retrieved from WebFrameMain instances (frame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate).Returns WebFrameMain | undefined - A frame with the given process and routing IDs, or undefined if there is no WebFrameMain associated with the given IDs.
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emitido cuando es documento está cargado.
\nframe.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (opcional) - Predeterminado es falso.Returns Promise<unknown> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
Evalúa el código en la página.
En la ventana del navegador, algunas API HTML como requestFullScreen solo pueden invocarse con un gesto del usuario. Establecer userGesture a true eliminará esta limitación.
frame.reload()Devuelve boolean - Si la recarga fue iniciada correctamente. Solo resulta en false cuando el frame no tiene historial.
frame.send(channel, ...args)channel Cadena...args any[]Envía un mensaje asíncrono al render process a través de channel, junto con los argumentos. Los argumentos serán serializados con la [Structured Clone Algorithm][SCA], al igual que [postMessage][], así que las cadenas de prototipos no serán incluidas. El envío de funciones, promesas, símbolos, WeakMaps o WeakSets lanzará una excepción.
El proceso de renderizado puede manejar el mensaje escuchando el canal con el módulo ipcRenderer.
frame.postMessage(channel, message, [transfer])Envía un mensaje al renderer process, transfiriendo opcionalmente la propiedad de cero o más objetos [MessagePortMain][].
Los objetos MessagePortMain transferidos estarán disponible en el renderer process accediendo a la propiedad ports del evento emitido. Cuando llegan al renderer, serán objetos DOM MessagePort nativos.
Por ejemplo:
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nframe.url ReadonlyUn string representando la URL actual del frame.
frame.top ReadonlyUn WebFrameMain | null representando el frame superior en la jerarquía a la que pertenece el frame.
frame.parent ReadonlyUn WebFrameMain | null representando al frame padre de frame, la propiedad debería ser null si el frame es el frame superior en la jerarquía de frame.
frame.frames ReadonlyUna colección WebFrameMain[] que contiene los descendientes directos del frame.
frame.framesInSubtree ReadonlyUna colección WebFrameMain[] que contiene cada frame en el subárbol de frame incluyendo el mismo. Esto puede resultar útil al atravesar todos los frames.
frame.frameTreeNodeId ReadonlyUn Integer que representa el id de la instancia FrameTreeNode del frame. Este id es global del navegador y unicamente identifica a un frame que aloja contenido. El identificador se fija en la creación del frame y permanece constante por durante el ciclo de vida del frame. Cuando el frame es eliminado, el id no se vuelve a utilizar.
frame.name ReadonlyUn String que representa el nombre del frame.
frame.osProcessId ReadonlyUn Integer que representa el pid del proceso del sistema operativo al cual pertenece este frame.
frame.processId ReadonlyUn Integer que representa el pid del proceso interno de Chromium al cual pertenece este frame. Esto no es el mismo que el process ID del sistema operativo; para leer eso use frame.osProcessId.
frame.routingId ReadonlyAn Integer representing the unique frame id in the current renderer process. Las instancias distintas de WebFrameMain que se refieren al mimo frame subyacente tendrán el mismo routingId.
frame.visibilityState SoloLecturaUn string que representa el visibility state del frame.
Ver también como la Page Visibility API es afectada por otras APIs de Electron.
", "title": "webFrameMain", "description": "Control web pages and iframes." }, "/docs/api/web-request": { "locale": "es-ES", "slug": "web-request", "href": "/docs/api/web-request", "crowdinFileId": "256405", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-request.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nInterceptar y modificar el contenido de una solicitud en varias etapas de su ciclo de vida.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Instancias de la clase WebRequest son accesibles usando la propiedad webRequest de una Session.
Los métodos de WebRequest aceptan un filter opcional y un listener. El listener será cancelado con listener(details) cuando el evento de API haya pasado. El objeto details describe la solicitud.
⚠️ Only the last attached listener will be used. Passing null as listener will unsubscribe from the event.
El objeto filter tiene una propiedad urls que es un arreglo de patrones URL que serán usados para filtrar las solicitudes que no coincidan con los patrones de URL. Si el filtro es omitido todas las solicitudes serán atendidas.
Para ciertos eventos el listener es pasado con una callback, Que debe ser llamada con un objeto response cuando el listener haya hecho su trabajo.
Un ejemplo de añadir encabezados User-Agent a las solicitudes:
const { session } = require('electron')\n\n// Modify the user agent for all requests to the following urls.\nconst filter = {\n urls: ['https://*.github.com/*', '*://electron.github.io']\n}\n\nsession.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {\n details.requestHeaders['User-Agent'] = 'MyAgent'\n callback({ requestHeaders: details.requestHeaders })\n})\nLo siguientes métodos están disponibles en instancias de WebRequest:
webRequest.onBeforeRequest([filter, ]listener)filter WebRequestFilter (opcional)listener Function | nulldetails Objectid Íntegrourl Stringmethod StringwebContentsId Entero (opcional)webContents WebContents (opcional)frame WebFrameMain (opcional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringfecha y hora DobleuploadData UploadData[]callback Funciónresponse Objectcancelar Booleano (opcional)Redireccionar URL Cadena (opcional) - La solicitud original está prevenida de ser enviada o completada y en vez de eso es redireccionada a una URL dada.El oyente Será cancelado con listener(details) cuando la redirección del servidor esté por ocurrir.
Los buttons es un arreglo de objetos Button.
The callback has to be called with an response object.
Algunos ejemplos de urls válidas:
'http://foo:1234/'\n'http://foo.com/'\n'http://foo:1234/bar'\n'*://*/*'\n'*://example.com/*'\n'*://example.com/foo/*'\n'http://*.foo:1234/'\n'file://foo:1234/bar'\n'http://foo:*/'\n'*://www.foo.com/'\nwebRequest.onBeforeSendHeaders([filter, ]listener)filter WebRequestFilter (opcional)listener Function | nulldetails Objectid Íntegrourl Stringmethod StringwebContentsId Entero (opcional)webContents WebContents (opcional)frame WebFrameMain (opcional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringfecha y hora DoblerequestHeaders Record<string, string>callback FunciónbeforeSendResponse Objectcancelar Booleano (opcional)requestHeaders Record<string, string | string[]> (opcional) -Cuando es proveído, la solicitud será hecha con esas cabeceras.El oyente se llamará con listener(details, callback) Antes de enviar la solicitud HTTP, una vez que los encabezados de las solicitudes estén disponibles. Esto puede ocurrir después de que se realiza una conexión TCP al servidor, pero antes de que se envíe cualquier información http.
El callback ha de ser llamado con un objeto response.
webRequest.onSendHeaders([filter, ]listener)filter WebRequestFilter (opcional)listener Function | nulldetails Objectid Íntegrourl Stringmethod StringwebContentsId Entero (opcional)webContents WebContents (opcional)frame WebFrameMain (opcional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringfecha y hora DoblerequestHeaders Record<string, string>Eloyente Será llamado con listener(details) justo antes que una solicitud vaya a ser enviada al servidor, modificaciones de previas respuestas onBeforeSendHeaders son visibles en el momento que este oyente esté en funcionamiento.
webRequest.onHeadersReceived([filter, ]listener)filter WebRequestFilter (opcional)listener Function | nulldetails Objectid Íntegrourl Stringmethod StringwebContentsId Entero (opcional)webContents WebContents (opcional)frame WebFrameMain (opcional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringfecha y hora Doblelinea de estatus CadenaEstatus de código enteroresponseHeaders Record<string, string[]> (opcional)callback FunciónheadersReceivedResponse Objectcancelar Booleano (opcional)responseHeaders Record<string, string | string[]> (opcional) - Cuando es proveído, el servidor se asume que ha respondido con estas cabeceras.Linea de estatus Cadena (opcional) - Se proveerá al reemplazar el encabezado de respuesta para cambiar el estatus del encabezado, de otra manera el estatus original del encabezado de respuesta será usado.El oyente será cancelado con listener(details, callback) cuando la respuesta HTTP de los encabezados de de una solicitud hayan sido recibidos.
El callback ha de ser llamado con un objeto response.
webRequest.onResponseStarted([filter, ]listener)filter WebRequestFilter (opcional)listener Function | nulldetails Objectid Íntegrourl Stringmethod StringwebContentsId Entero (opcional)webContents WebContents (opcional)frame WebFrameMain (opcional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringfecha y hora DobleresponseHeaders Record<string, string[]> (opcional)Desde Cache Booleano - Indica cuando al respuesta fue obtenida desde la memoria caché.Estatus de código enterolinea de estatus CadenaEl oyente será cancelado con listener(details) cuando se reciba el primer byte del cuerpo de la respuesta. Para las solicitudes HTTP, esto significa que la línea de estado y los encabezados de respuesta están disponibles.
webRequest.onBeforeRedirect([filter, ]listener)filter WebRequestFilter (opcional)listener Function | nulldetails Objectid Íntegrourl Stringmethod StringwebContentsId Entero (opcional)webContents WebContents (opcional)frame WebFrameMain (opcional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringfecha y hora DobleredirectURL StringEstatus de código enterolinea de estatus Cadenaip Cadena (opcional) - La dirección IP del servidor al cual fue enviada en realidad la solicitud.Desde cache BooleanoresponseHeaders Record<string, string[]> (opcional)El oyente Será cancelado con listener(details) cuando la redirección del servidor esté por ocurrir.
webRequest.onCompleted([filter, ]listener)filter WebRequestFilter (opcional)listener Function | nulldetails Objectid Íntegrourl Stringmethod StringwebContentsId Entero (opcional)webContents WebContents (opcional)frame WebFrameMain (opcional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringfecha y hora DobleresponseHeaders Record<string, string[]> (opcional)Desde cache BooleanoEstatus de código enterolinea de estatus Cadenaerror StringEl listener será llamado con listener(details) cuando una petición es completada.
webRequest.onErrorOccurred([filter, ]listener)filter WebRequestFilter (opcional)listener Function | nulldetails Objectid Íntegrourl Stringmethod StringwebContentsId Entero (opcional)webContents WebContents (opcional)frame WebFrameMain (opcional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringfecha y hora DobleDesde cache Booleanoerror Cadena - la descripción del error.El oyente será cancelado con listener(details) cuando ocurra un error.
urls String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.code Stringurl String (optional)startLine Integer (optional) - Default is 1.<webview> EtiquetaLa etiqueta webview de Electron está basada en Chromium's webview, el cual está experimentado cambios de arquitectura dramáticos. Esto impacta la estabilidad de webviews, incluyendo el renderizado, navegación y el enrutamiento de evento. We currently recommend to not use the webview tag and to consider alternatives, like iframe, Electron's BrowserView, or an architecture that avoids embedded content altogether.
By default the webview tag is disabled in Electron >= 5. Usted necesita habilitar la etiqueta estableciendo la opción webviewTag de webPreferences cuando se construye su BrowserWindow. Para más información vea el BrowserWindow constructor docs.
\n\nMostrar contenido externo de la web en un cuadro aislado y procesado.
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Use the webview tag to embed 'guest' content (such as web pages) in your Electron app. The guest content is contained within the webview container. Una página incrustada dentro de los controles de tu aplicación como el contenido de invitado es dispuesto y renderizado.
Unlike an 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. Esto mantiene a tu aplicación a salvo del contenido incrustado. Note: Muchos de los métodos en la vista web de la página anfitriona requieren una llamada sincrónica al proceso principal.
Para incrustar una página web en tu aplicación, añade la etiqueta webview a la página de embebido de tu aplicación (esta es la página de la aplicación que mostrará el contenido del invitado). En su manera más sencilla, la etiqueta webview incluye el src de la página web y los estilos css que controlan la apariencia de el contenedor webview:
<webview id=\"foo\" src=\"https://www.github.com/\" style=\"display:inline-flex; width:640px; height:480px\"></webview>\nSi tú quieres controlar el contenido de invitado de cualquier manera, puedes escribir JavaScript que escucha los eventos webview y responde a esos eventos usando los métodos webview. Aquí tenemos un código de muestra con dos detectores de eventos: uno que escucha para que la página web empiece a cargar, la otra para que la página web deje de cargar y muestre un mensaje que indique \"cargando...\" durante el tiempo de carga:
<script>\n onload = () => {\n const webview = document.querySelector('webview')\n const indicator = document.querySelector('.indicator')\n\n const loadstart = () => {\n indicator.innerText = 'loading...'\n }\n\n const loadstop = () => {\n indicator.innerText = ''\n }\n\n webview.addEventListener('did-start-loading', loadstart)\n webview.addEventListener('did-stop-loading', loadstop)\n }\n</script>\nBajo la capa webview es implementado con Out-of-Process iframes (OOPIFs). La etiqueta webview es esencialmente un elemento personalizado usando shadow DOM para envolver un elemento iframe dentro de el.
Entonces el comportamiento de webview es muy similar a iframe cross-domain, como ejemplos:
webview, el foco de la página se moverá desde el incrustador a webview.webview.webview son asíncronas.Por favor tenga en cuenta que las etiquetas de estilos de webview usa internamente display:flex; para asegurar que el elemento iframe hijo rellena el alto y el ancho por completo de su webview contenedor cuando es usado con el layouts tradicionales y flexbox. Por favor no sobrescrita la propiedad CSS por defecto display:flex; a menos que se especifique display:inline-flex; para layout inline.
La etiqueta de webview tiene los siguientes atributos:
src<webview src=\"https://www.github.com/\"></webview>\nA String representing the visible URL. Writing to this attribute initiates top-level navigation.
Asignarle a src su propio valor reiniciará la página actual.
El atributo src puede aceptar data de URL, como data:text/plain,Hello, world!.
nodeintegration<webview src=\"http://www.google.com/\" nodeintegration></webview>\nUn Boolean. Cuando este atributo esté presente, la página de invitado en webview tendrá integración de nodo y puede usar nodos APIs como require y process para acceder a bajos niveles de recursos de sistemas. La integración de nodo está desactivada por defecto en la página de invitado.
nodeintegrationinsubframes<webview src=\"http://www.google.com/\" nodeintegrationinsubframes></webview>\nUn Boolean para habilitar la opción experimental soporte NodeJS en sub frames tal como iframes dentro de webview. Todas sus precargas se cargarán por cada iframe, pude usar process.isMainFrame para determinar si estás en el frame principal o no. Esta opción está deshailitada por defecto en la pagina de invitado.
plugins<webview src=\"https://www.github.com/\" plugins></webview>\nUn Boolean. When this attribute is present the guest page in webview will be able to use browser plugins. Plugins are disabled by default.
preload<!-- from a file -->\n<webview src=\"https://www.github.com/\" preload=\"./test.js\"></webview>\n<!-- or if you want to load from an asar archive -->\n<webview src=\"https://www.github.com/\" preload=\"./app.asar/test.js\"></webview>\nUn String que especifica un script que será cargada antes que se ejecuten otros scripts en la página de invitado. The protocol of script's URL must be file: (even when using asar: archives) because it will be loaded by Node's require under the hood, which treats asar: archives as virtual directories.
Cuando la página de invitado no tiene integración de nodo, este guión todavía tendrá acceso a todos los nodos APIs, pero los objetos globales inyectados por Nodo serán eliminados luego de que el guión haya finalizado de ejecutarse.
\nNota: Esta opción aparecerá como preloadURL (no preload) en el webPreferences especificado al evento will-attach-webview.
httpreferrer<webview src=\"https://www.github.com/\" httpreferrer=\"http://cheng.guru\"></webview>\nUn String que establece la URL de referencia para la página de invitado.
useragent<webview src=\"https://www.github.com/\" useragent=\"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko\"></webview>\nA String that sets the user agent for the guest page before the page is navigated to. Once the page is loaded, use the setUserAgent method to change the user agent.
disablewebsecurity<webview src=\"https://www.github.com/\" disablewebsecurity></webview>\nUn Boolean. When this attribute is present the guest page will have web security disabled. Web security is enabled by default.
partition<webview src=\"https://github.com\" partition=\"persist:github\"></webview>\n<webview src=\"https://electronjs.org\" partition=\"electron\"></webview>\nUn String que representa la sesión utilizada por la página. Si partition empieza con persist:, la página usará una sesión persistente disponible para todas las páginas en la aplicación con la misma partition. si no hay un prefijo persist:, la página usará una sesión en memoria. Al asignar la misma partition, las páginas múltiples pueden compartir la misma sesión. Si la partition no se establece entonces la sesión por defecto de la aplicación será usada.
This value can only be modified before the first navigation, since the session of an active renderer process cannot change. Subsequent attempts to modify the value will fail with a DOM exception.
\nallowpopups<webview src=\"https://www.github.com/\" allowpopups></webview>\nUn Boolean. When this attribute is present the guest page will be allowed to open new windows. Popups are disabled by default.
webpreferences<webview src=\"https://github.com\" webpreferences=\"allowRunningInsecureContent, javascript=no\"></webview>\nUn String el cual es una lista de cadenas separada por coma que especifica las web preferences a ser establecidas en el webview. La lista completa de cuerdas preferenciales soportadas puede ser encontradas en BrowserWindow.
La cuerda sigue el mismo formato que las cuerdas que aparecen en window.open. Un nombre por sí mismo es dado a true por valores booleanos. Una preferencia puede ser establecida por otro valor incluyendo un =, seguido por el valor. Valores especiales como yes y 1 son interpretados como true, mientras que no y 0 son interpretados como false.
enableblinkfeatures<webview src=\"https://www.github.com/\" enableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nUn String que es una lista de cadenas que especifica las funciones de parpadeo que se habilitarán separadas por ,. La lista completa de cadenas características soportadas puede ser encontrada en el archivo RuntimeEnabledFeatures.json5.
disableblinkfeatures<webview src=\"https://www.github.com/\" disableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nUn String que es una lista de cadenas que especifica las funciones de parpadeo a ser desactivadas separadas por ,. La lista completa de cadenas características soportadas puede ser encontrada en el archivo RuntimeEnabledFeatures.json5.
La etiqueta de webview tiene los siguientes métodos:
Nota: El elemento webview debe ser cargado antes de usar los métodos.
\nEjemplo
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('dom-ready', () => {\n webview.openDevTools()\n})\n<webview>.loadURL(url[, options])url URLoptions Object (opcional)httpReferrer (String | Referrer) (opcional) - Una url HTTP Referencia.userAgent Cadena (opcional) - Un agente de usuario originando el pedido.extraHeaders Cadena (opcional) - Encabezados extras separados por \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (opcional) - Url base (con separadores de ruta arrastrables) para archivos que se cargan por el url de datos. Esto es necesario únicamente si el url especificado es un url de datos y necesita cargar otros archivos.Devuelve Promise<void> - La promesa se resolverá cuando la pagina ha finalizado de cargar (ver did-finish-load), y rechaza si la página falla al cargar (ver did-fail-load).
Carga el url en el webview, el url debe contener el prefijo protocolo, e.g. el http:// or file://.
<webview>.downloadURL(url)url StringInicia una descarga del recurso en url sin navegar.
<webview>.getURL()Devuelve String - El URL de la página de invitado.
<webview>.getTitle()Devuelve Cadena - El título de la página de invitado.
<webview>.isLoading()Devuelve Boolean - Aunque la página de invitado esté cargando recursos.
<webview>.isLoadingMainFrame()Devuelve Boolean - Si el marco principal (y no sólo iframes o frames dentro de él) todavía está cargando.
<webview>.isWaitingForResponse()Devuelve Boolean - Aunque la página de invitado esté esperando por una primera respuesta de el principal recurso de la página.
<webview>.stop()Detiene cualquier navegación pendiente.
\n<webview>.reload()Recarga la página de invitado.
\n<webview>.reloadIgnoringCache()Recarga la página de invitado e ignora el caché.
\n<webview>.canGoBack()Devuelve Boolean - Aunque la página de invitado pueda retroceder.
<webview>.canGoForward()Devuelve Boolean - Aunque la página de invitado úeda ir hacia adelante.
<webview>.canGoToOffset(offset)offset ÍntegroDevuelve Boolean - Aunque la página de invitado pueda ir a offset.
<webview>.clearHistory()Borra el historial de navegación.
\n<webview>.goBack()Hace que la página de invitado vaya hacia atrás.
\n<webview>.goForward()Hace que la página de invitado vaya hacia adelante.
\n<webview>.goToIndex(index)index ÍntegroNavega a el índice absoluto específico.
\n<webview>.goToOffset(offset)offset ÍntegroNavega hacia el offset especificado desde \"la entrada actual\".
\n<webview>.isCrashed()Devuelve Boolean - Si el proceso de renderizado ha fallado.
<webview>.setUserAgent(userAgent)userAgent cadenaAnula el agente usuario para la página de invitado.
\n<webview>.getUserAgent()Devuelve String - El agente usuario para la página de invitado.
<webview>.insertCSS(css)css CadenaDevuelve Promise<String> - Una promesa que resuelve con una llave para el CSS insertado que puede ser utilizado más tarde para eliminar el CSS a través <webview>contents.removeInsertedCSS(key).
Inyecta CSS en la página web actual y devuelve un identificador único para la hoja de estilo insertada.
\n<webview>.removeInsertedCSS(key)llave CadenaDevuelve Promise<void> - Resuelve si la eliminación fue exitosa.
Elimina el CSS insertado desde la página web actual. La hoja de estilos se identifica por su clave, el cual es devuelto desde <webview>.insertCSS(css).
<webview>.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (opcional) - Por defecto false.Devuelve Promise<any> - Una promesa que resuelve con el resultado de la ejecución del código o es rechazada si el resultado del código es una promesa rechazada.
Evalúa el código en la página. Si userGesture está establecido, creará el contexto de gesto del usuario en la página. APIs de HTML como requestFullScreen, los cuales requieren acciones de usuario, puede tomar ventaja de esta opción para automatización.
<webview>.openDevTools()Abre una ventana de DevTools para la página de invitado.
\n<webview>.closeDevTools()Cierra la ventana de DevTools para la página de invitado.
\n<webview>.isDevToolsOpened()Devuelve Boolean - Aunque la página de invitado tenga una ventana de DevTools unida.
<webview>.isDevToolsFocused()Devuelve Boolean - Aunque la ventana de DevTools de la página de invitado esté centrada.
<webview>.inspectElement(x, y)x Integery IntegerEmpieza inspeccionado elementos en posición (x, y) de la página de invitado.
<webview>.inspectSharedWorker()Abre el DevTools para el contexto de trabajadores compartidos presentes en la página de invitado.
\n<webview>.inspectServiceWorker()Abre el DevTools para el contexto del trabajador de servicio presente en la página de invitado.
\n<webview>.setAudioMuted(muted)muted BooleanEstablece la página de invitado silenciada.
\n<webview>.isAudioMuted()Devuelve Boolean - Aunque a página de invitado haya sido silenciada.
<webview>.isCurrentlyAudible()Devuelve Boolean - Si el audio se esta reproduciendo actualmente.
<webview>.undo()Ejecuta el comando de edición undo en página.
<webview>.redo()Ejecuta el comando de edición redo en página.
<webview>.cut()Ejecuta comando de edición cut en página.
<webview>.copy()Ejecuta comando de edición copy en página.
<webview>.paste()Ejecuta el comando de edición paste en la página.
<webview>.pasteAndMatchStyle()Ejecuta el comando de edición pasteAndMatchStyle en la página.
<webview>.delete()Ejecuta el comando de edición delete en página.
<webview>.selectAll()Ejecuta el comando de edición selectAll en página.
<webview>.unselect()Ejecuta el comando de edición unselect en página.
<webview>.replace(text)texto CadenaEjecuta el comando de edición replace en página.
<webview>.replaceMisspelling(text)texto CadenaEjecuta el comando de edición replaceMisspelling en página.
<webview>.insertText(text)texto CadenaDevuelve Promise<void>
Inserta texto en el elemento enfocado.
<webview>.findInPage(text[, options])text String - El contenido para ser buscado, no debe quedar en blanco.options Object (opcional)forward Boolean (opcional) - Ya sea para buscar hacia adelante o hacia atrás, el valor predeterminado es true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Por defecto es false.matchCase Boolean (opcional) - Si la busqueda debe ser sensible a mayúsculas, por defecto es false.Devuelve Integer - El id de la solicitud usado para la solicitud.
Empieza una solicitud para encontrar todas las coincidencias para el text en la página web. El resultado de la petición puede ser obtenido por suscripción al evento found-in-page.
<webview>.stopFindInPage(action)action String - Specifies the action to take place when ending <webview>.findInPage request.clearSelection - Borrar la selección.keepSelection - Traduce la selección en una selección normal.activateSelection - Enfoca y hace clic en el nodo de selección.Detiene cualquier solicitud findInPage para el webview con la action dada.
<webview>.print([options])options Object (opcional)silent Boolean (optional) - Don't ask user for print settings. Por defecto es false.printBackground Boolean (optional) - Prints the background color and image of the web page. Por defecto es false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. Por defecto es true.margins Object (opcional)marginType String (opcional) - Puede ser default, none, printableArea, o custom. Si custom es elegido, además necesitar especificar top, bottom, left, y right.top Number (opcional) - El margen superior de la página web impresa, en píxeles.bottom Number (opcional) - El margen inferior de la página web impresa, en píxeles.left Number (opcional) - El margen izquierdo de la página web impresa, en píxeles.right Number (opcional) - El margen derecho de la página web impresa, en píxeles.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. Por defecto es false.scaleFactor Number (opcional) - El factor de escalado de la página web.pagesPerSheet Number (opcional) - El número de páginas a imprimir por hoja de página.collate Boolean (opcional) - Si la página web debe ser intercalada.copies Number (opcional) - El número de copias de la página web a imprimir.pageRanges Object - The page range to print.from Number - Index of the first page to print (0-based).to Number - Índice de la última página a imprimir (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Puede ser simplex, shortEdge, o longEdge.dpi Record<string, number> (opcional)horizontal Number (opcional) - El dpi horizontal.vertical Number (opcional) - El dpi vertical.header String (opcional) - Cadena a ser impresa como cabecera de la página.footer String (opcional) - Cadena a ser impresa como pie de página.pageSize String | Tamaño (opcional) - Especifique el tamaño de página del documento impreso. Puede ser A3, A4, A5, Legal, Letter, Tabloid o un objeto que contenga height.Devuelve Promise<void>
Imprime la página web de webview. Igual que webContents.print([options]).
<webview>.printToPDF(opciones)options ObjectheaderFooter Record<string, string> (opcional) - el encabezado y el pie de página para el PDF.title String - El título para el encabezado PDF.url String - la url para el pie de página PDF.landscape Boolean (opcional) - true for landscape, false para portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin. y width en micrones.scaleFactor Number (opcional) - El factor de escalado de la página web. Puede variar entre 0 to 100.pageRanges Record<string, number> (optional) - The page range to print. On macOS, only the first range is honored.from Number - Index of the first page to print (0-based).to Number - Índice de la última página a imprimir (inclusive) (0-based).pageSize String | Size (opcional) - Especifica el tamaño de la página del PDF generado. Puede ser A3, A4, A5, Legal, Letter, Tabloid o un objeto que contenga heightprintBackground Boolean (octional) - Si se va a imprimir los fondos CSS.printSelectionOnly Boolean (opcional) - Se va a imprimir solo la selección.Returns Promise<Uint8Array> - Se resuelve cuando los datos PDF son generados.
Imprime la página web de webview como PDF, Igual como webContents.printToPDF(options).
<webview>.capturePage([rect])rect Rectangle (opcional) - El área de la página para ser capturada.Devuelve Promise<NativeImage> - Resuelve con el un NativeImage
Captura una foto instantánea de la página dentro de rect. Omitiendo rect capturará toda la página visible.
<webview>.send(channel, ...args)channel Cadena...args any[]Devuelve Promise<void>
Envía un mensaje asincrónico al proceso de renderizado a través de channel. También se puede enviar argumentos arbitrarios. El proceso renderizador puede manejar el mensaje escuchando el evento channel con el módulo ipcRenderer.
Ver webContents.send para ejemplos.
\n<webview>.sendToFrame(frameId, channel, ...args)frameId [number, number] - [processId, frameId]channel Cadena...args any[]Devuelve Promise<void>
Envía un mensaje asincrónico al proceso de renderizado a través de channel. También se puede enviar argumentos arbitrarios. El proceso renderizador puede manejar el mensaje escuchando el evento channel con el módulo ipcRenderer.
Vea webContents.sendToFrame para ejemplos.
\n<webview>.sendInputEvent(event)event MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventDevuelve Promise<void>
Envía un input event a la página.
Ver webContents.sendInputEvent para una descripción detallada del objeto event.
<webview>.setZoomFactor(factor)factor Number - Zoom factor.Cambia el nivel de zoom al nivel especificado. Factor de zoom es porcentaje de zoom dividido entre 100, así que 300% = 3.0.
\n<webview>.setZoomLevel(level)nivel Número - Nivel de Zoom.Cambia el nivel de zoom al nivel especificado. El tamaño original es 0 y cada incremento por encima o por debajo representa un zoom del 20% mayor o menor a los límites predeterminados de 300% y 50% del tamaño original, respectivamente. La fórmula para esto es scale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
<webview>.getZoomFactor()Devuelve Number - el factor de zoom actual.
<webview>.getZoomLevel()Devuelve Number - el nivel de zoom actual.
<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NúmeromaximumLevel NúmeroDevuelve Promise<void>
Establecer el nivel de máximo y mínimo pizca de zoom.
\n<webview>.showDefinitionForSelection() macOSMuestra un diccionario que busca la palabra seleccionada en la página.
\n<webview>.getWebContentsId()Devuelve Number - El ID de WebContents de este webview.
Los siguientes eventos DOM están disponibles en la etiqueta webview:
Devuelve:
\nurl StringEsElFramePrincipal BooleanFired when a load has committed. This includes navigation within the current document as well as subframe document-level loads, but does not include asynchronous resource loads.
\nDisparado cuando la navegación es terminada, i.e. el girador del tabulador dejará de girar, y el evento onload es discapacitado.
Devuelve:
\nerrorCode IntegererrorDescription StringvalidatedURL StringEsElFramePrincipal BooleanEste evento es como did-finish-load,pero disparado cuando la carga falla o es cancelada, e.g. window.stop() es involucrada.
Devuelve:
\nEsElFramePrincipal BooleanDisparado cuando un frame ha terminado la navegación.
\nCorresponde a los puntos en tiempo cuando el girador del tabulador empieza a girar.
\nCorresponde a los puntos en tiempo cuando el girador del tabulador termina de girar.
\nFired when attached to the embedder web contents.
\nDisparado cuando el documento en el frame dado es cargado.
\nDevuelve:
\ntitle StringexplicitSet BoolenDisparado cuando el título de la página se configura durante la navegación. explicitSet es false cuando el título es sincronizado desde el archivo url.
Devuelve:
\nfavicons Cadena[] - Arreglo para URLs.Disparado cuando la página recibe urls de favicon.
\nDisparado cuando la página entra en pantalla entera i¿y es activado por HTML API.
\nDisparado cuando la página deja la pantalla completa activada por HTML API.
\nDevuelve:
\nlevel Entero - El nivel de registro, desde 0 hasta 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Entero - El número de línea de la fuente que activó este mensaje de consolasourceId CadenaDisparado cuando la ventana invitada entra un mensaje de consola.
\nEl siguiente código ejemplo sigue con todos los mensajes guardados a la consola embebedora sin preocupación por el nivel de guardado u otras propiedades.
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('console-message', (e) => {\n console.log('Guest page logged a message:', e.message)\n})\nDevuelve:
\nresult ObjectrequestId ÍntegroactiveMatchOrdinal Integer - Posición de la coincidencia activa.matches Integer - Número de coincidencias.selectionArea Rectangle - Coordenadas de la primera región de coincidencia.finalUpdate BooleanDisparado cuando un resultado es disponible en la solicitud webview.findInPage.
const webview = document.querySelector('webview')\nwebview.addEventListener('found-in-page', (e) => {\n webview.stopFindInPage('keepSelection')\n})\n\nconst requestId = webview.findInPage('test')\nconsole.log(requestId)\nDevuelve:
\nurl StringframeName Stringdisposition String - Puede ser default, foreground-tab, background-tab, new-window, save-to-disk and other.options BrowserWindowConstructorOptions - Las opciones que deberían ser usadas para crear el nuevo BrowserWindow.Disparado cuando la página de invitado intenta abrir una nueva ventana de buscador.
\nEl siguiente código ejemplo abre el nuevo url en el buscador por defecto del sistema.
\nconst { shell } = require('electron')\nconst webview = document.querySelector('webview')\n\nwebview.addEventListener('new-window', async (e) => {\n const protocol = (new URL(e.url)).protocol\n if (protocol === 'http:' || protocol === 'https:') {\n await shell.openExternal(e.url)\n }\n})\nDevuelve:
\nurl StringEmitido cuando un usuario o l página quiere empezar la navegación. Puede ocurrir cuando el objeto window.location se cambia o un usuario hace clic en un enlace en la página.
Este evento no se emitirá cuando la navegación es iniciada con programación con APIs como <webview>.loadURL y <webview>.back.
It is also not emitted during in-page navigation, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Llamar a event.preventDefault(), NO tiene ningún efecto.
Devuelve:
\nurl StringisInPlace BooleanEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEmitido cuando cualquier frame (incluyendo el principal) comienza la navegación. isInPlace will be true for in-page navigations.
Devuelve:
\nurl StringisInPlace BooleanEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nDevuelve:
\nurl StringEmitido cuando la navegación es finalizada.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Devuelve:
\nurl StringhttpResponseCode Integer - -1 para navegaciones no HTTPhttpStatusText String - vacío para navegaciones no HTTPEsElFramePrincipal BooleanframeProcessId IntegerframeRoutingId IntegerEmitido cuando se ha realizado un navegación de algun frame.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Devuelve:
\nEsElFramePrincipal Booleanurl StringEmitido cuando una navegación dentro de la página sucede.
\nCuando una navegación dentro de la página sucede, el URL de la página cambia, pero no causa una navegación fuera de la página. Ejemplos de ésto ocurriendo son cuando los links son clickeados o cuando el evento DOM hashchange es activado.
Disparado cuando la página de invitado intenta cerrarse.
\nEl siguiente código ejemplo navega el webview a about:blank cuando el invitado intenta cerrase.
const webview = document.querySelector('webview')\nwebview.addEventListener('close', () => {\n webview.src = 'about:blank'\n})\nDevuelve:
\nframeId [number, number] - par de [processId, frameId].channel Cadenaargs any[]Disparado cuando la página de invitado ha enviado un mensaje asincrónico a la página de embebido.
\nCon el método sendToHost y el evento ipc-message puedes comunicarte entre la página de invitado y la página del integrador:
// In embedder page.\nconst webview = document.querySelector('webview')\nwebview.addEventListener('ipc-message', (event) => {\n console.log(event.channel)\n // Prints \"pong\"\n})\nwebview.send('ping')\n// In guest page.\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('ping', () => {\n ipcRenderer.sendToHost('pong')\n})\nDisparado cuando el proceso de renderizado se cierra.
\nDevuelve:
\nname Stringversion CadenaDisparado cuando el proceso de plugin se cae.
\nDisparado cuando el WebContents es destrozado.
\nEmitido cuando la media empieza a reproducirse.
\nEmitido cuando la media es pausada o ha terminado de reproducirse.
\nDevuelve:
\nthemeColor CadenaEmitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nDevuelve:
\nurl StringEmitido cuando el mouse se mueve sobre un link o el teclado se mueve el concentrado a un link.
\nEmitido cuando DevTools es abierto.
\nEmitido cuando Devtools es cerrado.
\nEmitido cuando DevTools es centrado o abierto.
", "title": "There are several ways to control how windows are created from trusted or untrusted content within a renderer. Windows can be created from the renderer in two ways:
\ntarget=_blankwindow.open()Para contenido del mismo origen, la nueva ventana es creada dentro del mismo proceso, permitiendo al padres acceder a la ventana hija derectamente. Esto puede ser muy útil para las sub ventanas de la aplicación que actúan como paneles de preferencia o similares, ya que el padre puede renderizar directamente a la sub ventana, como si fuera un div en el padre. Este es el mismo comportamiento que en el navegador.
Cuando nativeWindowOpen se establece a false, window.open en cambio resulta en la creación de una BrowserWindowProxy, un envoltorio ligero alrededor de 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 BrowserWindow in the main process by using webContents.setWindowOpenHandler() for renderer-created windows.
BrowserWindow constructor options are set by, in increasing precedence order: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Note that webContents.setWindowOpenHandler has final say and full privilege because it is invoked in the main process.
window.open(url[, frameName][, features])url StringframeName String (opcional)features String (opcional)Returns BrowserWindowProxy | Window
features is a comma-separated key-value list, following the standard format of the browser. Electron will parse BrowserWindowConstructorOptions out of this list where possible, for convenience. For full control and better ergonomics, consider using webContents.setWindowOpenHandler to customize the BrowserWindow creation.
A subset of WebPreferences can be set directly, unnested, from the features string: zoomFactor, nodeIntegration, preload, javascript, contextIsolation, and webviewTag.
Por ejemplo:
\nwindow.open('https://github.com', '_blank', 'top=500,left=200,frame=false,nodeIntegration=no')\nNotas:
\nwindow abierta si está deshabilitada en la ventana principal.window abierta si está habilitado en la ventana principal.window abierta si está deshabilitado en la ventana principal.features serán pasadas a cualquier manejador de evento registrado did-create-window de webContents en el argumento options.frameName follows the specification of windowName located in the native documentation.To customize or cancel the creation of the window, you can optionally set an override handler with webContents.setWindowOpenHandler() from the main process. Devolver { action: 'deny' } cancela la ventana. Devolver {action: 'allow', overrideBrowserWindowOptions: { ... } } permitará abrir la ventana y configurar el BrowserWindowConstructorOptions que se usará al crear la ventana. Tenga en cuenta que esto es más poderoso que pasar opciones a través de la cadena de características, ya que el renderizador tiene privilegios más limitados para decidir las preferencias de seguridad que el proceso principal.
Window nativo// main.js\nconst mainWindow = new BrowserWindow()\n\n// En este ejemplo, solo ventanas con la url `about:blank` serán creadas.\n// All other urls will be blocked.\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url === 'about:blank') {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n frame: false,\n fullscreenable: false,\n backgroundColor: 'black',\n webPreferences: {\n preload: 'my-child-window-preload-script.js'\n }\n }\n }\n }\n return { action: 'deny' }\n})\n// renderer process (mainWindow)\nconst childWindow = window.open('', 'modal')\nchildWindow.document.write('<h1>Hello</h1>')\nBrowserWindowProxy\n// main.js\nconst mainWindow = new BrowserWindow({\n webPreferences: { nativeWindowOpen: false }\n})\n\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url.startsWith('https://github.com/')) {\n return { action: 'allow' }\n }\n return { action: 'deny' }\n})\n\nmainWindow.webContents.on('did-create-window', (childWindow) => {\n // Por ejemplo...\n childWindow.webContents.on('will-navigate', (e) => {\n e.preventDefault()\n })\n})\n// renderer.js\nconst windowProxy = window.open('https://github.com/', null, 'minimizable=false')\nwindowProxy.postMessage('hi', '*')\nIf your app runs with Electron 6.0.8 or later, you can now build it for Windows 10 on Arm. Esto aumenta considerablemente el rendimiento, pero necesitará recopilar cualquier módulo nativo usado en tu app. It may also require small fixups to your build and packaging scripts.
\nIf your app doesn't use any native modules, then it's really easy to create an Arm version of your app.
\nnode_modules directory is empty.set npm_config_arch=arm64 before running npm install/yarn install as usual.Lots of Windows-specific code contains if... else logic that selects between either the x64 or x86 architectures.
\nif (process.arch === 'x64') {\n // Do 64-bit thing...\n} else {\n // Do 32-bit thing...\n}\nIf you want to target arm64, logic like this will typically select the wrong architecture, so carefully check your application and build scripts for conditions like this. In custom build and packaging scripts, you should always check the value of npm_config_arch in the environment, rather than relying on the current process arch.
If you use native modules, you must make sure that they compile against v142 of the MSVC compiler (provided in Visual Studio 2017). You must also check that any pre-built .dll or .lib files provided or referenced by the native module are available for Windows on Arm.
To test your app, use a Windows on Arm device running Windows 10 (version 1903 or later). Make sure that you copy your application over to the target device - Chromium's sandbox will not work correctly when loading your application assets from a network location.
\nNode.js v12.9.0 or later is recommended. If updating to a new version of Node is undesirable, you can instead update npm's copy of node-gyp manually to version 5.0.2 or later, which contains the required changes to compile native modules for Arm.
\nVisual Studio 2017 (any edition) is required for cross-compiling native modules. You can download Visual Studio Community 2017 via Microsoft's Visual Studio Dev Essentials program. After installation, you can add the Arm-specific components by running the following from a Command Prompt:
\nvs_installer.exe ^\n--add Microsoft.VisualStudio.Workload.NativeDesktop ^\n--add Microsoft.VisualStudio.Component.VC.ATLMFC ^\n--add Microsoft.VisualStudio.Component.VC.Tools.ARM64 ^\n--add Microsoft.VisualStudio.Component.VC.MFC.ARM64 ^\n--includeRecommended\nSetting npm_config_arch=arm64 in the environment creates the correct arm64 .obj files, but the standard Developer Command Prompt for VS 2017 will use the x64 linker. To fix this:
vcvarsamd64_arm64.bat at the end instead of vcvarsamd64_x86.bat.If done successfully, the command prompt should print something similar to this on startup:
\n**********************************************************************\n** Visual Studio 2017 Developer Command Prompt v15.9.15\n** Copyright (c) 2017 Microsoft Corporation\n**********************************************************************\n[vcvarsall.bat] Environment initialized for: 'x64_arm64'\nIf you want to develop your application directly on a Windows on Arm device, substitute vcvarsx86_arm64.bat in Target so that cross-compilation can happen with the device's x86 emulation.
node.libBy default, node-gyp unpacks Electron's node headers and downloads the x86 and x64 versions of node.lib into %APPDATA%\\..\\Local\\node-gyp\\Cache, but it does not download the arm64 version (a fix for this is in development.) To fix this:
node.lib from https://electronjs.org/headers/v6.0.9/win-arm64/node.lib%APPDATA%\\..\\Local\\node-gyp\\Cache\\6.0.9\\arm64\\node.libSubstitute 6.0.9 for the version you're using.
After completing all of the above, open your cross-compilation command prompt and run set npm_config_arch=arm64. Then use npm install to build your project as normal. As with cross-compiling x86 modules, you may need to remove node_modules to force recompilation of native modules if they were previously compiled for another architecture.
Debugging native modules can be done with Visual Studio 2017 (running on your development machine) and corresponding Visual Studio Remote Debugger running on the target device. To debug:
\n.exe on the target device via the Command Prompt (passing --inspect-brk to pause it before any native modules are loaded)..pdb symbols under Debugging > Symbols.If you encounter a problem with this documentation, or if your app works when compiled for x86 but not for arm64, please file an issue with \"Windows on Arm\" in the title.
", "title": "Windows on ARM", "description": "" }, "/docs/tutorial/windows-store-guide": { "locale": "es-ES", "slug": "windows-store-guide", "href": "/docs/tutorial/windows-store-guide", "crowdinFileId": "256273", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-store-guide.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Con Windows 10, el buen ejecutable anterior win32 obtuvo un nuevo hermano: La Plataforma Universal de Windows. El nuevo formato .appx no solo permite un nuevo número de nuevas y poderosas API como Cortana o Notificaciones Push, pero a través de la Tienda Windows, también simplifica la instalación y la actualización.
Microsoft desarrolló una herramienta que compila las aplicaciones Electron como .appx paquetes, permitiendo a los desarrolladores usar algunas de las buenas cosas encontradas en la nueva aplicación modelo. Esta guía explica cómo usarla - y cuáles son las capacidades y limitaciones de un paquete de Electron AppX.
Windows 10 \"Actualización Aniversario\" puede ejecutar los binarios win32 .exe con su lanzamiento junto a un sistema de archivos y registro virtualizados. Ambos se crean durante la compilación mediante la ejecución de la aplicación y el instalador dentro de un Contenedor de Windows, lo que permite a Windows identificar exactamente qué modificaciones en el sistema operativo se realizan durante la instalación. Emparejar el ejecutable con un sistema de archivos virtual y un registro virtual permite que Windows habilite la instalación y desinstalación con un solo clic.
Además, el exe es lanzado dentro del modelo de appx, lo que significa que puede usar muchas de las API disponibles para la Plataforma Universal de Windows. Para obtener aún más capacidades, una aplicación de Electron puede emparejarse con una tarea de fondo UWP invisible lanzada junto con el exe - un tipo de lanzamiento similar a un sidekick para ejecutar tareas en segundo plano, recibir notificaciones push, o comunicarse con otras aplicaciones UWP.
Para compilar cualquier aplicación Electron existente, asegúrese de tener los siguientes requisitos:
\nnode -v)Luego, vaya e instale la CLI electron-windows-store:
npm install -g electron-windows-store\nEmpaquetar la aplicación usando electron-packager (o una herramienta similar). Asegúrese de eliminar los node_modules que no necesita en su aplicación final, ya que cualquier módulo que realmente no necesite, aumentará el tamaño de su aplicación.
La salida debería verse más o menos de esta forma:
\n├── Ghost.exe\n├── LICENSE\n├── content_resources_200_percent.pak\n├── content_shell.pak\n├── d3dcompiler_47.dll\n├── ffmpeg.dll\n├── icudtl.dat\n├── libEGL.dll\n├── libGLESv2.dll\n├── locales\n│ ├── am.pak\n│ ├── ar.pak\n│ ├── [...]\n├── node.dll\n├── resources\n│ └── app.asar\n├── v8_context_snapshot.bin\n├── squirrel.exe\n└── ui_resources_200_percent.pak\nDesde un PowerShell elevado (ejecútelo como \"Administrador\"), ejecute electron-windows-store con los parámetros requeridos, pasando los directorios de entrada y salida, el nombre y la versión de la aplicación y la confirmación de que node_modules debe ser aplanado.
electron-windows-store `\n --input-directory C:\\myelectronapp `\n --output-directory C:\\output\\myelectronapp `\n --package-version 1.0.0.0 `\n --package-name myelectronapp\nUna vez ejecutada, la herramienta comienza a funcionar: acepta su aplicación Electron como entrada, aplanando los node_modules. Luego, archiva su aplicación como app.zip. Utilizando un instalador y un contenedor de Windows, la herramienta crea un paquete AppX \"expandido\", incluido el Manifiesto de Aplicación de Windows (AppXManifest.xml), así como el sistema de archivos virtual y el registro virtual dentro de su carpeta de salida.
Una vez que se crean los archivos de AppX expandidos, la herramienta usa el Empaquetador de Aplicaciones de Windows (MakeAppx.exe) para crear un paquete de AppX de un solo archivo a partir de esos archivos en el disco. Finalmente, la herramienta se puede usar para crear un certificado de confianza en su computadora para firmar el nuevo paquete AppX. Con el paquete AppX firmado, la CLI también puede instalar automáticamente el paquete en su máquina.
Para ejecutar su paquete, sus usuarios necesitarán Windows 10 con la llamada \"Actualización Aniversario\". Se pueden encontrar detalles sobre cómo actualizar Windows aquí.
\nEn oposición a las aplicaciones UWP tradicionales, las aplicaciones empaquetadas actualmente necesitan someterse a un proceso de verificación manual, para lo cual puede aplicar aquí. Mientras tanto, todos los usuarios podrán instalar sus paquetes haciendo doble clic en él, podría no ser necesario volver a enviar el paquete a la tienda, si lo que esta buscando es un metodo de instalacion mas sencillo. En entornos administrados (generalmente empresas), se puede usar el Add-AppxPackage PowerShell Cmdlet se puede utilizar para instalarlo de forma automática.
Otra limitación importante es que el paquete AppX compilado todavía contiene un ejecutable Win32 - y por lo tanto, no se ejecutará en Xbox, HoloLens o teléfonos.
\nPuede asociar su aplicación Electron con una tarea de fondo UWP invisible que haga uso completo de las características de Windows 10, como notificaciones push, integración Cortana o Live Tiles.
\nPara comprobar cómo una aplicación de Electron que es utilizada por una tarea en segundo plano envía notificaciones Toast y Lives Tiles, dale una mirada al ejemplo proporcionado por Microsoft.
\nPara generar el paquete AppX, la CLI electron-windows-store usa una plantilla que debería funcionar para la mayoría de las aplicaciones Electron. Sin embargo, si está utilizando un instalador personalizado o experimenta algún problema con el paquete generado, puede intentar crear un paquete mediante la compilación con un contenedor de Windows: en este modo, la CLI instalará y ejecutará su aplicación en un contenedor en blanco de Windows para determinar qué modificaciones está haciendo exactamente su aplicación al sistema operativo.
Antes de ejecutar la CLI por primera vez, deberá configurar el \"Windows Desktop App Converter\". Esto llevará algunos minutos, pero no te preocupes, solo tienes que hacerlo esta vez. Descarga y Desktop App Converter desde aquí. Recibirá dos archivos: DesktopAppConverter.zip y BaseImage-14316.wim.
DesktopAppConverter.zip. Desde un PowerShell elevado (abierto con \"ejecutar como administrador\", asegúrese de que la política de ejecución de su sistema nos permita ejecutar todo lo que pretendemos ejecutar llamando a Set-ExecutionPolicy bypass.BaseImage-14316.wim), llamando a .\\DesktopAppConverter.ps1 -Setup -BaseImage.\\BaseImage-14316.wim.Una vez que la instalación haya tenido éxito, puede pasar a la compilación de su aplicación Electron.
", "title": "Guía de Windows Store", "description": "" }, "/docs/tutorial/windows-taskbar": { "locale": "es-ES", "slug": "windows-taskbar", "href": "/docs/tutorial/windows-taskbar", "crowdinFileId": "256275", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-taskbar.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron tiene APIs para configurar el icono de la aplicación en la barra de tareas de Windows. This API supports both Windows-only features like creation of a JumpList, custom thumbnails and toolbars, icon overlays, and the so-called \"Flash Frame\" effect, and cross-platform features like recent documents and application progress.
Windows permite a las aplicaciones definir un menú contextual personalizado que aparece cuando los usuarios hacen clic con el botón derecho en el ícono de las aplicaciones en la barra de tareas. Ese menú contextual se llama JumpList. Especificas acciones personalizadas en la categoría Tasks de JumpList, como se menciona en MSDN:
\n\nLas aplicaciones definen tareas basadas tanto en las características del programa como en las cosas claves que se espera que haga un usuario con ellas. Las tareas deben estar libres de contexto, en que la aplicación no necesita ejecutarse para que funcione. También deberían ser las acciones estadísticamente más comunes que un usuario normal llevaría a cabo en una aplicación, como redactar un mensaje de correo electrónico o abrir el calendario en un programa de correo, crear un nuevo documento en un procesador de texto, iniciar una aplicación en un determinado modo, o ejecuta uno de sus subcomandos. Una aplicación no debe saturar el menú con características avanzadas que los usuarios estándar no necesitarán o acciones únicas como el registro. No utilice tareas para artículos promocionales como actualizaciones u ofertas especiales.
\nSe recomienda encarecidamente que la lista de tareas sea estática. Debería permanecer igual independientemente del estatus o estado de la aplicación. Si bien es posible variar la lista de forma dinámicamente, debe considerar que esto podría confundir al usuario que no espera que esa parte de la lista de destinos cambie.
\n
\n\nNOTA: La captura anterior es un ejemplo de tareas generales de Internet Explorer
\n
A diferencia del dock menú en macOS el cual es un menú real, user tasks en Windows funcionan como atajos de aplicación. Por ejemplo, cuando un usuario pulsa en un task, el programa será ejecutado con argumentos especificados.
\nPara establecer las tareas de usuario en tu aplicación, puedes usar la API app.setUserTasks.
\nComenzando con una aplicación funcionando desde Guía de Inicio Rápido, actualiza el archivo main.js con las siguiente lineas:
const { app } = require('electron')\n\napp.setUserTasks([\n {\n program: process.execPath,\n arguments: '--new-window',\n iconPath: process.execPath,\n iconIndex: 0,\n title: 'New Window',\n description: 'Create a new window'\n }\n])\nPara limpiar tu lista de tareas, necesitas llamar a app.setUserTasks con un array vacío en el archivo main.js.
const { app } = require('electron')\n\napp.setUserTasks([])\n\n\nNOTE: The user tasks will still be displayed even after closing your application, so the icon and program path specified for a task should exist until your application is uninstalled.
\n
En Windows puedes añadir una miniatura a la barra de tareas con botones específicos a un layout de barra de tareas de una ventana de aplicacion. Provee a los usuarios con una manera de acceder a un comando de ventana en particular sin restaurar o activar la ventana.
\nComo se cita desde MSDN:
\n\n\nEsta barra de herramientas es la barra de tareas estándar de control común. Tiene un máximo de siete botones. Cada botón de identificación, imagen, descripción y estado está definido en una estructura, la cual es pasada a la barra de tareas. La aplicación puede mostrar, habilitar, deshabilitar u ocultar botones de la barra de herramientas si es requerido por su estado actual.
\nPor ejemplo, el reproductor de Windows ofrece regularmente controles de transporte como play, pausa, silenciar y detener.
\n
\n\nNOTA: La captura de pantalla anterior es un ejemplo de thumbnail toolbar del Media Player de Windows
\n
Para establecer la miniatura de la barra de tareas en tu aplicación, tienes que usar BrowserWindow.setThumbarButtons
\nComenzando con una aplicación funcionando desde Guía de Inicio Rápido, actualiza el archivo main.js con las siguiente lineas:
const { BrowserWindow } = require('electron')\nconst path = require('path')\n\nconst win = new BrowserWindow()\n\nwin.setThumbarButtons([\n {\n tooltip: 'button1',\n icon: path.join(__dirname, 'button1.png'),\n click () { console.log('button1 clicked') }\n }, {\n tooltip: 'button2',\n icon: path.join(__dirname, 'button2.png'),\n flags: ['enabled', 'dismissonclick'],\n click () { console.log('button2 clicked.') }\n }\n])\nPara borrar los botones de thumbnail toolbar, necesitas llamar BrowserWindow.setThumbarButtons con un array vacío en el archivo main.js.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.setThumbarButtons([])\nEn Windows, un botón de la barra de tareas puede usar una pequeña superposición para mostrar el estado de la aplicación.
\nComo se cita desde MSDN:
\n\n\nEl encubrimiento de íconos sirve como una notificación contextual del estatus, y tiene la intención de negar la necesidad de separar el ícono de la notificación del estatus del ícono para comunicar la información al usuario. Por ejemplo, el nuevo estatus de correos en Microsoft Outlook, actualmente se muestra en el área de notificaciones, ahora puede ser indicado a través de un encubrimiento en el botón de la barra de tareas. De nuevo, debes decidir durante su ciclo de desarrollo cual método es el mejor para su aplicación. El encubrimiento de íconos tiene la intención de dar información importante, estatus de larga duración o notificaciones así como estado de la red o de mensajería, o nuevos correos. El usuario no debe ser presentado con cambios constantes en el encubrimiento o animaciones.
\n
\n\nNOTA: La captura de pantalla anterior es un ejemplo de superposición en un botón de la barra de tareas
\n
To set the overlay icon for a window, you need to use the BrowserWindow.setOverlayIcon API.
\nComenzando con una aplicación funcionando desde Guía de Inicio Rápido, actualiza el archivo main.js con las siguiente lineas:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.setOverlayIcon('path/to/overlay.png', 'Description for overlay')\nEn Windows, puedes resaltar el botón de la barra de tareas para obtener la atención del usuario. Esto es similar al rebote del ícono en el dock de macOS.
\nComo se cita desde MSDN:
\n\n\nPor lo general, una ventana está iluminada para informar al usuario que la ventana requiere atención pero este no está concentrado en el teclado en el momento.
\n
To flash the BrowserWindow taskbar button, you need to use the BrowserWindow.flashFrame API.
\nComenzando con una aplicación funcionando desde Guía de Inicio Rápido, actualiza el archivo main.js con las siguiente lineas:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.once('focus', () => win.flashFrame(false))\nwin.flashFrame(true)\n\n", "title": "Taskbar Customization (Windows)", "description": "Las aplicaciones definen tareas basadas tanto en las características del programa como en las cosas claves que se espera que haga un usuario con ellas. Las tareas deben estar libres de contexto, en que la aplicación no necesita ejecutarse para que funcione. También deberían ser las acciones estadísticamente más comunes que un usuario normal llevaría a cabo en una aplicación, como redactar un mensaje de correo electrónico o abrir el calendario en un programa de correo, crear un nuevo documento en un procesador de texto, iniciar una aplicación en un determinado modo, o ejecuta uno de sus subcomandos. Una aplicación no debe saturar el menú con características avanzadas que los usuarios estándar no necesitarán o acciones únicas como el registro. No utilice tareas para artículos promocionales como actualizaciones u ofertas especiales.\nSe recomienda encarecidamente que la lista de tareas sea estática. Debería permanecer igual independientemente del estatus o estado de la aplicación. Si bien es posible variar la lista de forma dinámicamente, debe considerar que esto podría confundir al usuario que no espera que esa parte de la lista de destinos cambie." } }, "zh-CN": { "/docs/api/accelerator": { "locale": "zh-CN", "slug": "accelerator", "href": "/docs/api/accelerator", "crowdinFileId": "256277", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/accelerator.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "NOTA: No olvides llamar a
\nwin.flashFrame(false)para desactivar el destello. En el ejemplo anterior, es llamado cuando la ventana entra en foco, pero puede que uses un temporizador o algún otro evento para desactivarlo.
\n\n定义键盘快捷键。
\n
快捷键可以包含多个功能键和一个键码的字符串，由符号+结合，用来定义你应用中的键盘快捷键
示例
\nCommandOrControl+ACommandOrControl+Shift+Z快捷方式使用 register 方法在 globalShortcut 模块中注册, 即:
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+Y' shortcut listener.\n globalShortcut.register('CommandOrControl+Y', () => {\n // Do stuff when Y and either Command/Control is pressed.\n })\n})\n在 Linux 和 Windows 上, Command 键没有任何效果, 所以使用 CommandOrControl表述, macOS 是 Command ，在 Linux 和 Windows 上是Control。
使用 Alt按键替代 Option按键。 使用 Alt 键代替Option. Option 键只在 macOS 系统上存在, 而 Alt 键在任何系统上都有效.
Super (或 Meta) 键对应Windows 和 Linux 系统上的 Windows 键，但在 macOS 里为 Cmd 键.
Command (缩写为Cmd)Control (缩写为Ctrl)CommandOrControl (缩写为 CmdOrCtrl)AltOptionAltGrShiftSuper元数据0 到 9A 到 ZF1 到 F24~, !, @, #, $, etc.PlusSpaceTab大写锁定（Capslock）数字锁定（Numlock）滚动锁定Backspace删除InsertReturn (等同于 Enter)Up, Down, Left and RightHome 和 EndPageUp 和 PageDownEscape (缩写为 Esc)VolumeUp, VolumeDown 和 VolumeMuteMediaNextTrack、MediaPreviousTrack、MediaStop 和 MediaPlayPausePrintScreennum1-num9 -数字1-数字9numdec - 小数点numadd - 加号numsub - 减号nummult - 乘号numdiv - 除号为程序制作辅助功能是很重要的。在这里，我们很高兴地向你们介绍Devtron和Spectron。这两个新功能有机会使开发者们让他们的应用程序更加可用。
\nElectron 应用中有关辅助功能的开发和网站是相似的，因为两者最终使用的都是HTML. 然而, 对于Electron应用, 你不能使用在线的辅助功能审查者, 因为你的应用没有一个URL可以提供给审查者.
\n这些功能将会提供一些审查工具给你的Electron 应用。 您可以选择使用 Spectron 将审查添加到你的测试环境中，或在开发者工具（DevTools）中使用Devtron。 详见各工具的文档.
\nIn the testing framework Spectron, you can now audit each window and <webview> tag in your application. 例如：
app.client.auditAccessibility().then(function (audit) {\n if (audit.failed) {\n console.error(audit.message)\n }\n})\n你可以从这里Spectron文档阅读到更多有关于这个功能的信息。
\nIn Devtron, there is an accessibility tab which will allow you to audit a page in your app, sort and filter the results.
\n
这两种工具都使用了Google 为 Chrome 所构建的 辅助功能开发工具 库。 您可以在 repository's wiki 上了解到更加详细的辅助功能审核规则。
\n如果你知道其他适用于Electron的辅助功能开发工具, 请通过pull request添加到本文档中.
\n当辅助技术存在时，Electron 应用程序将自动启用辅助功能（例如 Windows 上的 JAWS 或 macOS 上的 VoiceOver）。 有关详细信息, 请参阅 Chrome 的 辅助功能文档 。
\nYou can also manually toggle these features either within your Electron application or by setting flags in third-party native software.
\n通过使用 app.setAccessibilitySupportEnabled(enabled) API，您可以在应用程序首选项中的手动向用户暴露Chrome的访问树。 请注意，用户的系统辅助工具优先于此设置并将覆盖它。
On macOS, third-party assistive technology can toggle accessibility features inside Electron applications by setting the AXManualAccessibility attribute programmatically:
CFStringRef kAXManualAccessibility = CFSTR(\"AXManualAccessibility\");\n\n+ (void)enableAccessibility:(BOOL)enable inElectronApplication:(NSRunningApplication *)app\n{\n AXUIElementRef appRef = AXUIElementCreateApplication(app.processIdentifier);\n if (appRef == nil)\n return;\n\n CFBooleanRef value = enable ? kCFBooleanTrue : kCFBooleanFalse;\n AXUIElementSetAttributeValue(appRef, kAXManualAccessibility, value);\n CFRelease(appRef);\n}\n\n\n控制应用程序的事件生命周期。
\n
进程：主进程
\n下面的这个例子将会展示如何在最后一个窗口被关闭时退出应用：
\nconst { app } = require('electron')\napp.on('window-all-closed', () => {\n app.quit()\n})\napp 对象会发出以下事件:
当应用程序完成基础的启动的时候被触发。 在 Windows 和 Linux 中, will-finish-launching 事件与 ready 事件是相同的; 在 macOS 中，这个事件相当于 NSApplication 中的 applicationWillFinishLaunching 提示。 通常会在这里为 open-file 和 open-url 设置监听器，并启动崩溃报告和自动更新。
绝大部分情况下，你必须在ready事件句柄中处理所有事务。
返回:
\nevent EventlaunchInfo Record<string, any> | NotificationResponse macOS当 Electron 完成初始化时，发出一次。 在 macOS 上，如果从通知中心启动， launchInfo 内含有用于打开应用程序的 NSUserNotification 或来自 UNNotificationResponse 的 userInfo 信息。 你也可以通过调用 app.isReady() 来检查该事件是否已被触发，以及通过 app.whenReady() 得到一个当Electron已初始化后fulfill 的 Promise。
当所有的窗口都被关闭时触发。
\n如果你没有监听此事件并且所有窗口都关闭了，默认的行为是控制退出程序；但如果你监听了此事件，你可以控制是否退出程序。 如果用户按下了 Cmd + Q，或者开发者调用了 app.quit()，Electron 会首先关闭所有的窗口然后触发 will-quit 事件，在这种情况下 window-all-closed 事件不会被触发。
返回:
\nevent Event在程序关闭窗口前发信号。 调用 event.preventDefault() 将阻止终止应用程序的默认行为。
注意： 如果由 autoUpdater.quitAndInstal() 退出应用程序 ，那么在所有窗口触发 close 之后 才会触发 before-quit 并关闭所有窗口。
注:在 Windows 系统中，如果应用程序因系统关机/重启或用户注销而关闭，那么这个事件不会被触发。
\n返回:
\nevent Event当所有窗口被关闭后触发，同时应用程序将退出。 调用 event.preventDefault() 将阻止终止应用程序的默认行为。
关于 window-all-closed 和 will-quit 事件之间的差异, 请参见 window-all-closed 事件的说明。
注:在 Windows 系统中，如果应用程序因系统关机/重启或用户注销而关闭，那么这个事件不会被触发。
\n返回:
\nevent EventexitCode Integer在应用程序退出时发出。
\n注:在 Windows 系统中，如果应用程序因系统关机/重启或用户注销而关闭，那么这个事件不会被触发。
\n返回:
\nevent Eventpath String当用户想要在应用中打开一个文件时发出。 open-file 事件通常在应用已经打开，并且系统要再次使用该应用打开文件时发出。 open-file也会在一个文件被拖到 dock 并且还没有运行的时候发出。 请确认在应用启动的时候(甚至在 ready 事件发出前) 就对 open-file 事件进行监听。
如果你想处理这个事件，你应该调用 event.preventDefault() 。
在 Windows 系统中，你需要解析 process.argv (在主进程中) 来获取文件路径
返回:
\nevent Eventurl String当用户想要在应用中打开一个 URL 时发出。 你的应用程序的 Info. plist 文件必须在 CFBundleURLTypes 这个key中定义 url scheme, 并将 NSPrincipalClass 设置为 AtomApplication。
如果你想处理这个事件，你应该调用 event.preventDefault() 。
返回:
\nevent EventhasVisibleWindows Boolean当应用被激活时发出。 各种操作都可以触发此事件, 例如首次启动应用程序、尝试在应用程序已运行时或单击应用程序的坞站或任务栏图标时重新激活它。
\n返回:
\nevent Event当应用被激活时发出。 与 activate 事件的不同是应用，程序激活时都会触发 did-become-active ，而不仅仅在 Dock 图标被点击或应用程序被重新启动的时候。
返回:
\nevent EventtypeString-标识活动的字符串。 映射到 NSUserActivity. activityType。userInfo unknown - 包含另一个设备上activity存储的应用特定状态。details ObjectwebpageURL String (optional) - A string identifying the URL of the webpage accessed by the activity on another device, if available.当来自不同设备的活动通过 Handoff 想要恢复时触发。 如果你想处理这个事件，你应该调用 event.preventDefault() 。
只有具有支持相应的活动类型并且相同的开发团队 ID 作为启动程序时，用户行为才会进行。 所支持活动类型已在应用的 Info.plist 中的 NSUserActivityTypes 里明确定义。
返回:
\nevent EventtypeString-标识活动的字符串。 映射到 NSUserActivity. activityType。当来自不同设备的活动通过 Handoff 恢复之前触发。 如果你想处理这个事件，你应该调用 event.preventDefault() 。
返回:
\nevent EventtypeString-标识活动的字符串。 映射到 NSUserActivity. activityType。error String - 详细的错误信息当来自不同设备的活动通过 Handoff 恢复失败时触发。
\n返回:
\nevent EventtypeString-标识活动的字符串。 映射到 NSUserActivity. activityType。userInfo unknown - 包含activity存储的应用特定状态。当来自不同设备的活动通过 Handoff 成功恢复后触发。
\n返回:
\nevent EventtypeString-标识活动的字符串。 映射到 NSUserActivity. activityType。userInfo unknown - 包含activity存储的应用特定状态。当 Handoff 即将通过另一个设备恢复时触发。 如果需要更新要传输的状态，你应该立即调用 event.preventDefault(), 构造新的 userInfo 字典，并及时调用 app.updateCurrentActiviy()。 否则，操作会失败，并且触发 continue-activity-error
返回:
\nevent Event当用户点击原生的macOS新标签按钮时触发。 只有在当前 BrowserWindow 有 tabbingIdentifier 时，新建tab按钮才可见。
返回:
\nevent Eventwindow BrowserWindow在 browserWindow 失去焦点时发出。
\n返回:
\nevent Eventwindow BrowserWindow在 browserWindow 获得焦点时发出。
\n返回:
\nevent Eventwindow BrowserWindow在创建新的 browserWindow 时发出。
\n返回:
\nevent EventwebContents WebContents在创建新的 webContents 时发出。
\n返回:
\nevent EventwebContents WebContentsurl Stringerror String - 错误码certificate 证书callback FunctionisTrustedBoolean-是否将证书视为可信的isMainFrame Boolean当对 url 的 certificate 证书验证失败的时候发出。如果需要信任这个证书，你需要阻止默认行为 event.preventDefault() 并且调用 callback(true)。
const { app } = require('electron')\n\napp.on('certificate-error', (event, webContents, url, error, certificate, callback) => {\n if (url === 'https://github.com') {\n // Verification logic.\n event.preventDefault()\n callback(true)\n } else {\n callback(false)\n }\n})\n返回:
\nevent EventwebContents WebContentsurl URLcertificateList 证书[]callback Functioncertificate 证书 (可选)当一个客户证书被请求的时候发出。
\nurl 指的是请求客户端认证的网页地址，调用 callback 时需要传入一个证书列表中的证书。 需要通过调用 event.preventDefault() 来防止应用自动使用第一个证书进行验证。
const { app } = require('electron')\n\napp.on('select-client-certificate', (event, webContents, url, list, callback) => {\n event.preventDefault()\n callback(list[0])\n})\n返回:
\nevent EventwebContents WebContentsauthenticationResponseDetails Objecturl URLauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (可选)password String (可选)当 webContents 要进行基本身份验证时触发。
默认行为是取消所有身份验证。 默认行为是取消所有的验证行为，如果需要重写这个行为，你需要用 event.preventDefault() 来阻止默认行为，并且使用 callback(username, password) 来验证。
const { app } = require('electron')\n\napp.on('login', (event, webContents, details, authInfo, callback) => {\n event.preventDefault()\n callback('username', 'secret')\n})\n当 callback 在缺少用户名和密码的时候被调用，身份验证请求将被取消，同时将返回身份验证错误到页面。
每当有 GPU 信息更新时触发。
\n返回:
\nevent Eventkilled Boolean当gpu进程崩溃或关闭（杀死）时触发
\n已废弃：这个事件被包含更多子进程退出信息原因的child-process-gone事件取代了。 并不总是因为崩溃而触发。 当你换用child-process-gone事件时，原事件的 killed 布尔值可以被 reason === 'killed' 取代。
返回:
\nevent EventwebContents WebContentskilled Boolean当渲染器进程webContents崩溃或关闭（杀死）时触发。
已废弃： 此事件被包含更多关于渲染过程为何消失的信息的 render-process-gone 事件替代了 并不总是因为崩溃而触发。 当你换用child-process-gone事件时，原事件的 killed 布尔值可以被 reason === 'killed' 取代。
返回:
\nevent EventwebContents WebContentsdetails Objectreason String - 渲染进程消失的原因。 可选值：clean-exit - 以零为退出代码退出的进程abnormal-exit - 以非零退出代码退出的进程killed - 进程发送一个SIGTERM，否则是被外部杀死的。crashed - 进程崩溃oom - 进程内存不足launch-failed - 进程从未成功启动integrity-failure - 窗口代码完整性检查失败exitCode Integer - 进程的退出代码，除非在 reason 是 launch-failed 的情况下， exitCode 将是一个平台特定的启动失败错误代码。渲染器进程意外消失时触发。 这种情况通常因为进程崩溃或被杀死。
\n返回:
\nevent Eventdetails Objecttype String - 进程类型。 以下值之一：UtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownreason String - 子进程消失的原因。 可选值：clean-exit - 以零为退出代码退出的进程abnormal-exit - 以非零退出代码退出的进程killed - 进程发送一个SIGTERM，否则是被外部杀死的。crashed - 进程崩溃oom - 进程内存不足launch-failed - 进程从未成功启动integrity-failure - 窗口代码完整性检查失败exitCode Number - 进程的退出代码 (例如，在posix上，来自waitpid的状态；在Windows上则来自 GetExitCodeProcess)。serviceName String (可选) - 进程的非本地化名称。name String (可选) - 进程的名称。 功能性示例： Audio Service, Content Decryption Module Service, Network Service, Video Capture, 等等。子进程意外消失时触发。 这种情况通常因为进程崩溃或被杀死。 子进程不包括渲染器进程。
\n返回:
\nevent EventaccessibilitySupportEnabled当启用了 Chrome 的辅助功能时为 true, 其他情况为 false。当 Chrome 的辅助功能状态改变时触发。 当启用或禁用辅助技术时将触发此事件，例如屏幕阅读器 。 查看更多详情 https://www.chromium.org/developers/design-documents/accessibility
\n返回:
\nsession Session当 Electron创建了一个新的 session后被触发.
const { app } = require('electron')\n\napp.on('session-created', (session) => {\n console.log(session)\n})\n返回:
\nevent Eventargv String[] - 第二个实例的命令行参数数组workingDirectory String - 第二个实例的工作目录当第二个实例被执行并且调用 app.requestSingleInstanceLock() 时，这个事件将在你的应用程序的首个实例中触发
argv 是第二个实例的命令行参数的数组, workingDirectory 是这个实例当前工作目录。 通常, 应用程序会激活窗口并且取消最小化来响应。
注意： 如果第二个实例是由不同于第一个实例的用户启动的。 argv 数组不包含参数。
保证在 app 的 ready 事件发出后发出此事件。
注意： 额外命令行参数可能由 Chromium 添加， ，例如 --original-process-start-time。
返回:
\nevent EventwebContents WebContents在 webContents 的渲染器进程中调用 desktopCapturer.getSources() 时触发。 调用 event.preventDefault() 将使它返回空的sources。
app 对象具有以下方法:
注意: 某些方法仅在特定的操作系统上可用, 这些方法会被标记出来。
\napp.quit()尝试关闭所有窗口 将首先发出 before-quit 事件。 如果所有窗口都已成功关闭, 则将发出 will-quit 事件, 并且默认情况下应用程序将终止。
此方法会确保执行所有beforeunload 和 unload事件处理程序。 可以在退出窗口之前的beforeunload事件处理程序中返回false取消退出。
app.exit([exitCode])exitCode Integer (可选)使用 exitCode 立即退出。 exitCode 默认为0。
所有窗口都将立即被关闭，而不询问用户，而且 before-quit 和 will-quit 事件也不会被触发。
app.relaunch([options])从当前实例退出，重启应用。
\n默认情况下，新的实例将会使用和当前实例相同的工作目录以及命令行参数。 当设置了 args 参数时， args 将作为命令行参数传递。 当设置了 execPath ，execPath 将被执行以重新启动，而不是当前的应用程序。
请注意, 此方法在执行时不会退出当前的应用程序, 你需要在调用 app.relaunch 方法后再执行 app. quit 或者 app.exit 来让应用重启。
当 app.relaunch 被多次调用时,多个实例将在当前实例退出后启动。
立即重启当前实例并向新的实例添加新的命令行参数的示例：
\nconst { app } = require('electron')\n\napp.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) })\napp.exit(0)\napp.isReady()返回 Boolean 类型 - 如果 Electron 已经完成初始化，则返回 true, 其他情况为 false 另见 app.whenReady()。
app.whenReady()返回 Promise<void> - 当Electron 初始化完成。 可用作检查 app.isReady() 的方便选择，假如应用程序尚未就绪，则订阅ready事件。
app.focus([options])options Object (可选)steal Boolean macOS - 使接收器成为激活的应用程序，即使另一个应用程序当前处于激活状态。在 Linux 上，使第一个可见窗口获得焦点。 在 macOS上，将应用程序变成激活的app。 在 Windows上，使应用程序的第一个窗口获得焦点。
\n你应该尽可能少地使用 steal 选项。
app.hide() macOS隐藏所有的应用窗口，不是最小化.
\napp.show() macOS显示隐藏后的应用程序窗口。 不会使它们自动获得焦点。
\napp.setAppLogsPath([path])path String (可选) - 日志存放的自定义路径。 必须是绝对路径。设置或创建一个您的应用程序日志目录，然后可以通过 app.getPath() 或 app.setPath(pathName, newPath) 进行操作。
调用 app.setAppLogsPath() 却没有指定 path 参数将导致此目录在 macOS 下被设置为 ~/Library/Logs/YourAppName；在 Linux 和Windows 下将被设置到 userData 目录中。
app.getAppPath()返回 String 类型 - 当前应用程序所在目录
app.getPath(name)name String - 你可以通过这些名称请求下列路径：home 用户的 home 文件夹（主目录）appData 每个用户的应用程序数据目录，默认情况下指向：%APPDATA% Windows 中$XDG_CONFIG_HOME or ~/.config Linux 中~/Library/Application Support macOS 中userData 储存你应用程序设置文件的文件夹，默认是 appData 文件夹附加应用的名称缓存temp 临时文件夹exe当前的可执行文件module The libchromiumcontent 库desktop 当前用户的桌面文件夹documents 用户文档目录的路径downloads 用户下载目录的路径music 用户音乐目录的路径pictures 用户图片目录的路径videos 用户视频目录的路径recent 用户最近文件的目录 (仅限 Windows)。logs应用程序的日志文件夹crashDumps 崩溃转储文件存储的目录。返回 String - 一个与 name相关的特殊目录或文件的路径。 失败会抛出一个Error。
如果 app.getPath('logs') 被调用前没有先调用 app.setAppLogsPath() ，将创建一个相当于调用 app.setAppLogsPath() 却没有 path 参数的默认日志目录。
app.getFileIcon(path[, options])path Stringoptions Object (可选)size Stringsmall - 16x16normal - 32x32large - Linux上是 48x48, Windows 上是 32x32, macOS 中无效返回 Promise<NativeImage> - 完成后返回当前应用的图标, 类型是 NativeImage.
读取文件的关联图标。
\n在 Windows 上, 会有两种图标：
\n. mp3 ，. png 等。.exe, .dll, .ico在 Linux 和 macOS 系统中，图标取决于和应用程序绑定的 文件 mime 类型
\napp.setPath(name, path)name Stringpath String重写 name 的路径为 path，一个特定的文件夹或者文件。 如果路径指向一个不存在的目录，则抛出一个 Error。 在这种情况下，目录应该以 fs.mkdirSync 或类似的方式创建。
name 参数只能使用 app.getPath 定义过的 name
默认情况下, 网页的 cookie 和缓存将存储在 userData 目录下。 如果要更改这个位置, 你需要在 app 模块中的 ready 事件被触发之前重写 userData 的路径。
app.getVersion()返回 String-加载的应用程序的版本。 如果应用程序的 package. json 文件中找不到版本号, 则返回当前包或者可执行文件的版本。
app.getName()返回 String-当前应用程序的名称, 它是应用程序的 package. json 文件中的名称。
根据 npm 的命名规则, 通常 package.json 中的 name 字段是一个短的小写字符串。 通常还应该指定一个 productName 字段, 是首字母大写的完整名称，用于表示应用程序的名称。Electron 会优先使用这个字段作为应用名。
app.setName(name)name String设置当前应用程序的名字
\n注意： 此函数会覆盖Electron内部使用的名称；它不会影响操作系统使用的名称。
\napp.getLocale()返回 String - 当前应用程序区域，使用Chromium的 l10n_util 库获取。 可能的返回值记录在这里。
To set the locale, you'll want to use a command line switch at app startup, which may be found here.
\n 注意: 分发打包的应用程序时, 你必须指定 locales 文件夹。
注意： 在 Windows 上，你必须得等 ready 事件触发之后，才能调用该方法
app.getLocaleCountryCode()返回 String - 用户操作系统区域设置的双字母 ISO 3166 国家代码。 该值取自本地操作系统 API。
注意： 当无法检测本地国家代码时，它返回空字符串。
\napp.addRecentDocument(path) macOS Windowspath String将此 path 添加到最近打开的文件列表中
此列表由操作系统管理。 在Windows上，您可以从任务栏访问此列表，在macOS上，您可以从dock菜单访问。
\napp.clearRecentDocuments() macOS Windows清空最近打开的文档列表
\napp.setAsDefaultProtocolClient(protocol[, path, args])protocol String - 协议的名称, 不包含 ://。 例如，如果你希望应用处理 electron:// 链接，请以electron 为参数调用此方法。path String (可选) Windows - Electron可执行文件路径。 默认为 process.execPathargs String Windows - 传递给可执行文件的参数。 默认为空数组。返回 Boolean-是否成功调用。
将当前可执行文件的设置为协议(也就是 URI scheme) 的默认处理程序。 该方法允许你将应用更深入地集成到操作系统中。 一旦注册了，所有 your-protocol:// 开头的链接将使用当前可执行文件打开。 整个链接，包括协议部分，将作为参数传递给你的应用程序。
注意: 在 macOS 上，您只能注册已添加到应用程序的 info.plist 中的协议，这个列表在运行时不能修改。 然而，你可以在构建时通过 Electron Forge, Electron Packager, 或通过文本编辑器编辑info.plist文件的方式修改。 有关详细信息，请参阅 Apple's documentation
注意： 在 Windows Store 环境下(当打包为 appx)，此 API 对所有调用都返回 true，但它设置的注册表项将无法通过其他应用程序访问。 为了注册你的 Windows Store 应用程序作为默认的协议处理程序，你必须 在你的清单中声明协议。
API 在内部使用 Windows 注册表和 LSSetDefaultHandlerForURLScheme。
app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windowsprotocol String - 协议的名称, 不包含 ://。pathString (可选) Windows -默认为 process.execPathargs String Windows - 默认为空数组返回 Boolean-是否成功调用。
此方法检查当前可执行程序是否是协议(也就是URI scheme) 的默认处理程序。 如果是，则会将应用移除默认处理器。
\napp.isDefaultProtocolClient(protocol[, path, args])protocol String - 协议的名称, 不包含 ://。pathString (可选) Windows -默认为 process.execPathargs String Windows - 默认为空数组返回 Boolean - 当前可执行程序是否是协议(也就是URI scheme) 的默认处理程序。
注意: 在macOS上, 您可以使用此方法检查应用程序是否已注册为协议的默认协议处理程序。 同时可以通过查看 ~/Library/Preferences/com.apple.LaunchServices.plist 来确认。 有关详细信息，请参阅 Apple's documentation
API 在内部使用 Windows 注册表和 LSCopyDefaultHandlerForURLScheme。
app.getApplicationNameForProtocol(url)url String - 要检查的协议名称的 URL。 不同于家族中的其他方法，该方法接收至少包含 :// (例如：https://)的完整URL。返回 String - 处理协议的应用程序名称，或如果没有处理程序的空 字符串。 例如，如果Electron 是这个URL的默认 处理程序，那么在 Windows 和 Mac 上，这个返回值可以是 Electron。 然而，不要依赖于无法保证保持不变的精确格式。 Linux 上期望不同格式，可能带有 .desktop 后缀。
此方法返回URL协议(也就是URI scheme) 的默认处理器的应用程序名称。
\napp.getApplicationInfoForProtocol(url) macOS Windowsurl String - 要检查的协议名称的 URL。 不同于家族中的其他方法，该方法接收至少包含 :// (例如：https://)的完整URL。返回 Promise<Object> - resolve包含以下内容的object：
icon NativeImage - 处理协议的应用程序的显示图标。path String - 处理协议的应用程序的安装路径。name String - 处理协议的应用程序的显示名称。此方法返回包含应用程序名称，图标和默认协议处理器路径(也就是URI scheme) 的Promise。
\napp.setUserTasks(tasks) Windowstasks Task[] - 由 Task 对象组成的数组Windows上添加 tasks 到 Jump List的 Tasks 类别。
tasks 是 Task 对象组成的数组
返回 Boolean-是否成功调用。
注意: 如果您想自定义跳转列表, 请使用 aapp.setJumpList(categories) 来代替。
app.getJumpListSettings() Windows返回 Object:
minItems Integer - 将在跳转列表中显示项目的最小数量(有关此值的更详细描述，请参阅 MSDN docs).removedItems JumpListItem[] - 用户已明确从Jump List自定义类别中删除的项对应的 JumpListItem 对象数组。 这些项目不能在 next 调用 app.setJumpList() 时重新添加到跳转列表中, Windows不会显示任何包含已删除项目的自定义类别.app.setJumpList(categories) Windowscategories JumpListCategory[] | null - JumpListCategory 对象数组。设置或删除应用程序的自定义跳转列表，并返回以下字符串之一：
\nok - 没有出现错误error - 发生一个或多个错误，启用运行日志记录找出可能的原因。invalidSeparatorError - 已尝试在跳转列表中向自定义类别添加分隔符。 分隔符只允许在标准 Tasks 类别下出现。fileTypeRegistrationError -尝试向自定义跳转列表添加一个文件链接，但是该应用未注册处理该应用类型customCategoryAccessDeniedError - 由于用户隐私或策略组设置，自定义类别无法添加到跳转列表。如果 categories 的值为 null， 之前设定的自定义跳转列表(如果存在) 将被替换为标准的应用跳转列表(由windows生成)
注意： 如果一个 JumpListCategory 对象既没有设置 type 属性，也没有设置 name 属性，则假设其 type 是 tasks。 如果设置了 name 属性, 但省略了 type 属性, 则假定 type 为 custom。
注意: 用户可以从自定义类别中移除项目， after 调用 app.setJumpList(categories) 方法之前， Windows不允许删除的项目添加回自定义类别。 尝试提前将删除的项目重新添加 到自定义类别中，将导致整个自定义类别被隐藏。 删除的项目可以使用 app.getJumpListSettings() 获取。
注意： 跳列表项目 description 属性的最大长度为 260 个字符。 超过这个限制，当前项将不会被添加到跳转列表，也不会被展示。
下面是创建自定义跳转列表的一个非常简单的示例:
\nconst { app } = require('electron')\n\napp.setJumpList([\n {\n type: 'custom',\n name: 'Recent Projects',\n items: [\n { type: 'file', path: 'C:\\\\Projects\\\\project1.proj' },\n { type: 'file', path: 'C:\\\\Projects\\\\project2.proj' }\n ]\n },\n { // has a name so `type` is assumed to be \"custom\"\n name: 'Tools',\n items: [\n {\n type: 'task',\n title: 'Tool A',\n program: process.execPath,\n args: '--run-tool-a',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool A'\n },\n {\n type: 'task',\n title: 'Tool B',\n program: process.execPath,\n args: '--run-tool-b',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool B'\n }\n ]\n },\n { type: 'frequent' },\n { // has no name and no type so `type` is assumed to be \"tasks\"\n items: [\n {\n type: 'task',\n title: 'New Project',\n program: process.execPath,\n args: '--new-project',\n description: 'Create a new project.'\n },\n { type: 'separator' },\n {\n type: 'task',\n title: 'Recover Project',\n program: process.execPath,\n args: '--recover-project',\n description: 'Recover Project'\n }\n ]\n }\n])\napp.requestSingleInstanceLock()返回 Boolean
此方法的返回值表示你的应用程序实例是否成功取得了锁。 如果它取得锁失败，你可以假设另一个应用实例已经取得了锁并且仍旧在运行，并立即退出。
\nI.e. 如果当前进程是应用程序的主要实例，则此方法返回true，同时你的应用会继续运行。 如果当它返回 false如果你的程序没有取得锁，它应该立刻退出，并且将参数发送给那个已经取到锁的进程。
在 macOS 上, 当用户尝试在 Finder 中打开您的应用程序的第二个实例时, 系统会通过发出 open-file 和 open-url 事件来自动强制执行单个实例,。 但是当用户在命令行中启动应用程序时, 系统的单实例机制将被绕过, 您必须手动调用此方法来确保单实例。
在第二个实例启动时激活主实例窗口的示例:
\nconst { app } = require('electron')\nlet myWindow = null\n\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // 当运行第二个实例时,将会聚焦到myWindow这个窗口\n if (myWindow) {\n if (myWindow.isMinimized()) myWindow.restore()\n myWindow.focus()\n }\n })\n\n // 创建 myWindow, 加载应用的其余部分, etc...\n app.whenReady().then(() => {\n myWindow = createWindow()\n })\n}\napp.hasSingleInstanceLock()返回 Boolean
此方法返回你的应用实例当前是否持有单例锁。 你可以通过 app.requestSingleInstanceLock()请求锁，并且通过 app.releaseSingleInstanceLock() 释放锁。
app.releaseSingleInstanceLock()释放所有由 requestSingleInstanceLock 创建的锁。 该方法将允许应用程序的多个实例再次并行运行。
app.setUserActivity(type, userInfo[, webpageURL]) macOStype String - 活动的唯一标识。 映射到 NSUserActivity. activityType。userInfo any - 存储供其他设备使用的特定应用状态。webpageURL String (可选) - 如果在返回的设备上没有安装合适的应用，要在浏览器中加载的网页。 协议必须是 http 或 https。创建一个 NSUserActivity 并将其设置为当前活动。 该活动之后可以Handoff到另一个设备。
app.getCurrentActivityType() macOS返回 String - 正在运行的 activity 的类型
app.invalidateCurrentActivity() macOS使当前的Handoff用户活动无效。
\napp.resignCurrentActivity() macOS将当前 Handoff 用户活动标记为非活动，但不使其失效。
\napp.updateCurrentActivity(type, userInfo) macOStype String - 活动的唯一标识。 映射到 NSUserActivity. activityType。userInfo any - 存储供其他设备使用的特定应用状态。当其类型与 type 匹配时更新当前活动, 将项目从 用户信息 合并到其当前 用户信息 字典中。
app.setAppUserModelId(id) Windowsid String改变当前应用的 Application User Model ID 为 id.
app.setActivationPolicy(policy) macOSpolicy String - 可以是'regular', 'accessory', 或 'prohibited'。为给定应用设置激活策略。
\n激活策略类型：
\napp.importCertificate(options, callback) Linux选项 对象certificate String - pkcs12 文件的路径password String - 证书的密码callback Functionresult Integer - 导入结果将 pkcs12 格式的证书导入到平台证书库。 使用导入操作的 callback 调用返回 result ，值 0 表示成功，而任何其他值表示失败，根据Chromium net_error_list 。
app.configureHostResolver(options)选项 对象enableBuiltInResolver Boolean (optional) - Whether the built-in host resolver is used in preference to getaddrinfo. When enabled, the built-in resolver will attempt to use the system's DNS settings to do DNS lookups itself. Enabled by default on macOS, disabled by default on Windows and Linux.secureDnsMode String (optional) - Can be \"off\", \"automatic\" or \"secure\". Configures the DNS-over-HTTP mode. When \"off\", no DoH lookups will be performed. When \"automatic\", DoH lookups will be performed first if DoH is available, and insecure DNS lookups will be performed as a fallback. When \"secure\", only DoH lookups will be performed. Defaults to \"automatic\".secureDnsServers String[] (optional) - A list of DNS-over-HTTP server templates. See RFC8484 § 3 for details on the template format. Most servers support the POST method; the template for such servers is simply a URI. Note that for some DNS providers, the resolver will automatically upgrade to DoH unless DoH is explicitly disabled, even if there are no DoH servers provided in this list.enableAdditionalDnsQueryTypes Boolean (optional) - Controls whether additional DNS query types, e.g. HTTPS (DNS type 65) will be allowed besides the traditional A and AAAA queries when a request is being made via insecure DNS. Has no effect on Secure DNS which always allows additional types. 默认值为 true。Configures host resolution (DNS and DNS-over-HTTPS). By default, the following resolvers will be used, in order:
\ngetaddrinfo).This can be configured to either restrict usage of non-encrypted DNS (secureDnsMode: \"secure\"), or disable DNS-over-HTTPS (secureDnsMode: \"off\"). It is also possible to enable or disable the built-in resolver.
To disable insecure DNS, you can specify a secureDnsMode of \"secure\". If you do so, you should make sure to provide a list of DNS-over-HTTPS servers to use, in case the user's DNS configuration does not include a provider that supports DoH.
app.configureHostResolver({\n secureDnsMode: 'secure',\n secureDnsServers: [\n 'https://cloudflare-dns.com/dns-query'\n ]\n})\n此 API 必须在 ready 事件触发后调用
app.disableHardwareAcceleration()禁用当前应用程序的硬件加速。
\n这个方法只能在应用程序准备就绪（ready）之前调用。
\napp.disableDomainBlockingFor3DAPIs()默认情况下, 如果 GPU 进程频繁崩溃, Chromium 会禁用 3D API (例如 WebGL) 直到在每个域的基础上重新启动。 这个函数会禁用该行为。
\n这个方法只能在应用程序准备就绪（ready）之前调用。
\napp.getAppMetrics()返回 ProcessMetric[]: 包含所有与应用相关的进程的内存和CPU的使用统计的 ProcessMetric 对象的数组。
app.getGPUFeatureStatus()返回 GPUFeatureStatus-来自 chrome://gpu/ 的图形功能状态。
注意： 此信息仅在 gpu-info-update 事件触发后才可用。
app.getGPUInfo(infoType)infoType String - 可以是 basic 或 complete。返回 Promise<unknown>
对于infoType等于complete： Promise 将包含所有GPU信息的Object正如 chromium's GPUInfo object。 这包括 chrome://gpu 页面上显示的版本和驱动程序信息。
对于infoType等于basic： Promise 至少包含当请求complete时的属性Object。 下面是一个基础响应示例：
{\n auxAttributes:\n {\n amdSwitchable: true,\n canSupportThreadedTextureMailbox: false,\n directComposition: false,\n directRendering: true,\n glResetNotificationStrategy: 0,\n inProcessGpu: true,\n initializationTime: 0,\n jpegDecodeAcceleratorSupported: false,\n optimus: false,\n passthroughCmdDecoder: false,\n sandboxed: false,\n softwareRendering: false,\n supportsOverlays: false,\n videoDecodeAcceleratorFlags: 0\n },\n gpuDevice:\n [{ active: true, deviceId: 26657, vendorId: 4098 },\n { active: false, deviceId: 3366, vendorId: 32902 }],\n machineModelName: 'MacBookPro',\n machineModelVersion: '11.5'\n}\n如果只需要基本信息，如vendorId或driverId，则应优先使用basic。
app.setBadgeCount([count]) Linux macOScount Integer (可选) - 如果传入值，则将角标设置为所传入值，否则，在 macOS 上显示一个普通的白点(例如：通知数量未知)。 在 Linux 上，如果没有传入值，角标将不会显示。返回 Boolean-是否成功调用。
为当前应用设置计数器角标。 将计数设置为 0 将隐藏角标。
在 macOS 上，它会在dock 图标上显示。 在 Linux 上，它只适用于 Unity 启动器。
\n注意： Unity 启动器需要一个 .desktop 文件才能工作。 欲了解更多信息， 请阅读 Unity integration 文档。
app.getBadgeCount() Linux macOSReturns Integer - 获取计数器提醒(badge) 中显示的当前值
app.isUnityRunning() LinuxReturns Boolean - 当前桌面环境是否为 Unity 启动器
app.getLoginItemSettings([options]) macOS Windowsoptions Object (可选)如果你为 app. setLoginItemSettings 提供path 和 args 选项，那么你需要在这里为 openAtLogin 设置相同的参数已确保正确的设置。
返回 Object:
openAtLogin Boolean - true 如果应用程序设置为在登录时打开, 则为 <0>true</0>openAsHidden Boolean macOS - 当应用程序设置为在登录时隐藏打开为true。 此设置在 MAS 构建 上不可用。wasOpenedAtLogin Boolean macOS - 当应用程序在登录时自动运行为true。 此设置在 MAS 构建 上不可用。wasOpenedAsHidden Boolean macOS - 当应用程序作为一个隐藏的登录项运行时为 true 。 这表示应用程序在启动时不应打开任何窗口。 此设置在 MAS 构建 上不可用。restoreState Boolean macOS - true 如果应用程序作为登录项打开， 应该还原上一个会话状态。 这表示程序应该还原上次关闭时打开的窗口。 此设置在 MAS 构建 上不可用。executableWillLaunchAtLogin Boolean Windows - true 应用程序被设置为在登录时打开，并且其启动项未停用。 该属性与 openAtLogin 不同，因为它忽略了 args 选项，如果给定的可执行程序在登录时启动并带有 任意 参数，此属性将为true。launchItems Object[] Windowsname String Windows - 注册表项的名称值。path String Windows - 与注册表条目相对应的应用可执行程序。args String[] Windows - 传递到可执行文件的命令行参数。scope String Windows - user 或 machine之一。 指示注册表条目是否处于 HKEY_CURRENT USER 或 HKEY_LOCAL_MACHINE下。enabled Boolean Windows - true 如果应用注册表项已获得启动批准，此时在任务管理器和 Windows 设置中显示为 enabled 。app.setLoginItemSettings(settings) macOS Windowssettings ObjectopenAtLogin Boolean (可选) - true 登录时打开应用程序， false 将应用从登录启动项中删除。 默认值为 false.openAsHidden Boolean (可选) macOS - true 以隐藏方式打开应用程序。 默认为false。 用户可以从系统首选项中编辑此设置, 以便在打开应用程序时检查 app.getLoginItemSettings().wasOpenedAsHidden 以了解当前值。 此设置在 MAS 构建 上不可用。path String (可选) Windows - 登录时运行的可执行文件。 默认为 process.execPath。args String Windows - 传递给可执行文件的控制台参数。 默认为空数组。 注意用引号包裹路径。enabled Boolean (可选) Windows - true 将更改已启用的启动注册表项，并在任务管理器和 Windows 设置中 启用 / 禁用 应用程序。 默认值为 true。name String (可选) Windows - 要写入注册表的值名称。 默认为应用的 AppUserModelId()。 设置应用程序的登录项设置。如果需要在 Windows 上使用Squirrel的 autoUpdater ，你需要将启动路径设置为 Update.exe，并传递指定应用程序名称的参数。 例如：
const appFolder = path.dirname(process.execPath)\nconst updateExe = path.resolve(appFolder, '..', 'Update.exe')\nconst exeName = path.basename(process.execPath)\n\napp.setLoginItemSettings({\n openAtLogin: true,\n path: updateExe,\n args: [\n '--processStart', `\"${exeName}\"`,\n '--process-start-args', `\"--hidden\"`\n ]\n})\napp.isAccessibilitySupportEnabled() macOS WindowsReturns Boolean - 如果开启了Chrome的辅助功能, 则返回 true，其他情况返false。 如果使用了辅助技术（例如屏幕阅读），该 API 将返回 true。 查看更多细节，请查阅 https://www.chromium.org/developers/design-documents/accessibility
app.setAccessibilitySupportEnabled(enabled) macOS Windowsenable 逻辑值 - 启用或禁用访问权限树视图。手动启用 Chrome 的辅助功能的支持, 允许在应用程序中设置是否开启辅助功能。 在Chromium's accessibility docs查看更多的细节 默认为禁用
\n此 API 必须在 ready 事件触发后调用
注意： 渲染访问权限树可能会严重影响您应用的性能。 默认情况下不应启用该功能。
\napp.showAboutPanel()显示应用程序的\"关于\"面板选项。 这些选项可以被 app.setAboutPanelOptions(可选) 所覆盖。
app.setAboutPanelOptions(options)选项 对象applicationName String (可选) - 应用程序的名字applicationVersion String (可选) - 应用程序版本copyright String (可选) - 版权信息version String (可选) macOS - 应用程序版本号credits String (可选) macOS Windows - 信用信息。authors String Linux - 应用程序作者列表。website String (可选) Linux - 应用程序的网站。iconPath String (可选) Linux Windows - 以JPEG 或 PNG 文件格式为应用程序图标路径。 在 Linux 上，将显示为 64x64 像素，同时保留纵横比。设置 \"关于\" 面板选项。 这将覆盖应用程序在 macOS 上的 .plist 文件中定义的值。 详细信息请查阅 Apple 文档 。 在 Linux 上，没有默认值，所以必须设置值才能显示。
如果您没有设置 credits 但仍希望在应用中显示它们，AppKit 将在 NSBundle 类的main方法返回的捆绑包中按顺序查找名为\"Credits.html\", \"Credits.rtf\"和\"Credits.rtfd\"的文件。 先找到的文件将被使用，如果未找到，则信息区域将留空。 有关更多信息，请参阅 Apple 文档 。
app.isEmojiPanelSupported()返回 布尔值 - 当前操作系统版本是否允许使用本机emoji选取器。
app.showEmojiPanel() macOS Windows打开系统自身的emjio选取器。
\napp.startAccessingSecurityScopedResource(bookmarkData) macOSbookmarkData String - base64 编码的安全作用域的书签数据(bookmark data) ，通过 dialog.showOpenDialog 或者 dialog.showSaveDialog 方法获取。返回 Function - 该函数 必须 在你完成访问安全作用域文件后调用一次。 如果你忘记停止访问书签，内核资源将会泄漏，并且你的应用将失去完全到达沙盒之外的能力，直到应用重启。
//开始读取文件\nconst stopAcessingSecurityScopedResource = app。 tartAccessingSecurityScopedResource(数据)\n// 您现在可以在 sandbox:party_popper 之外访问文件🎉\n\n// 记住在文件完成后停止访问\nstopAccessingSecurityScopedResource()\n开始访问安全范围内的资源。 通过这个方法，Electron 应用被打包为可到达Mac App Store沙箱之外访问用户选择的文件。 关于系统工作原理，请查阅Apple's documentation
\napp.enableSandbox()在应用程序上启用完全沙盒模式。 这意味着所有渲染器都将以沙盒的方式运行，无论 WebPreence 中 sandbox 标志的值是什么。
这个方法只能在应用程序准备就绪（ready）之前调用。
\napp.isInApplicationsFolder() macOS返回 Boolean - 应用程序当前是否从系统应用程序文件夹运行。 与 app.moveToApplicationsFolder()一起使用
app.moveToApplicationsFolder([options]) macOSoptions Object (可选)conflictHandler FunctionconflictType String - 处理器遇到移动冲突的类型； 可以是 exists 或 existsAndRunning, exists 意味着应用程序目录中存在相同名称的应用， existsAndRunning 表示存在并且正在运行。返回 Boolean - 移动是否成功。 请注意，如果移动成功，您的应用程序将退出并重新启动。
默认情况下不会显示确认对话框。 如果您希望允许用户确认操作，您可以使用dialog API 进行确认。
注意：如果并非是用户造成操作失败，这个方法会抛出错误。 例如，如果用户取消了授权会话，这个方法将返回false。 如果无法执行复制操作, 则此方法将抛出错误。 错误中的信息应该是翔实的，并告诉你到底是哪里出了问题。
\n默认情况下，如果应用程序目录中存在与被移动的应用同名的应用，并且 未 运行，则已有应用将被丢弃，被移动的应用将顶替其位置。 如果它 正在 运行，预先存在的运行应用程序将承担焦点，以前活动的应用程序将退出自己。 此行为可以通过提供可选的冲突处理器来更改，处理器返回的 boolean 将决定移动冲突是否通过默认行为得到解决。 即：返回 false 将确保不采取进一步行动，返回 true 将导致默认行为同时方法继续执行。
例如：
\napp.moveToApplicationsFolder({\n conflictHandler: (conflictType) => {\n if (conflictType === 'exists') {\n return dialog.showMessageBoxSync({\n type: 'question',\n buttons: ['Halt Move', 'Continue Move'],\n defaultId: 0,\n message: 'An app of this name already exists'\n }) === 1\n }\n }\n})\n这意味着，如果应用已经存在于用户目录中，如果用户选择 '继续移动'，则该功能将继续其默认行为，现有应用将被丢弃，当前应用将移动到其位置。
\napp.isSecureKeyboardEntryEnabled() macOS返回 Boolean - 是否启用 Secure Keyboard Entry 。
默认情况下，此 API 将返回 false。
app.setSecureKeyboardEntryEnabled(enabled) macOSenabled Boolean - 启用或禁用 Secure Keyboard Entry在应用中启用 Secure Keyboard Entry 。
通过使用此 API，可以防止密码和其他敏感信息等重要信息被其他进程截获。
\n有关更多详细信息，请参阅 apple 文档 。
\n注意： 仅在需要时启用 Secure Keyboard Entry ，并在不再需要时禁用。
app.accessibilitySupportEnabled macOS WindowsBoolean属性 - 如果开启了Chrome的辅助功能，则返回 true，否则返回false。 如果使用了辅助功能（例如屏幕阅读），该 API 将返回 true。 手动将此属性设置为 true 可启用 Chrome 的辅助功能支持，允许开发人员在应用程序设置中向用户开放无障碍切换。
有关详细信息，请参阅 chromium 的无障碍文档 。 默认为禁用
\n此 API 必须在 ready 事件触发后调用
注意： 渲染访问权限树可能会严重影响您应用的性能。 默认情况下不应启用该功能。
\napp.applicationMenuMenu | null 属性，如果设置 Menu ，则返回，否则返回 null 。 用户可以传递 Menu 来给此属性赋值。
app.badgeCount Linux macOS返回当前应用角标计数的 Integer 属性。 将计数设置为 0 将隐藏角标。
在 macOS 上，为该属性设置任何非零整数，会显示在dock 图标上。 在 Linux 上，这个属性只适用于 Unity 启动器。
\n注意： Unity 启动器需要一个 .desktop 文件才能工作。 欲了解更多信息， 请阅读 Unity integration 文档。
注意： 在 macOS 上，为了使该属性生效，您需要确保您的应用程序具有显示通知的权限。
\napp.commandLine 只读CommandLine 对象，允许您读取和操作 Chromium 使用的命令行参数。
app.dock macOS 只读Dock | undefined 对象，允许您在 macOS 上的用户dock中对应用图标进行操作。
app.isPackaged 只读返回一个Boolean值，如果应用已经打包，返回true ，否则返回false 。 对于大多数应用程序，此属性可用于区分开发和生产环境。
app.nameString 属性，指明当前应用程序的名称，即应用程序 package.json 文件中的名称。
根据 npm 的命名规则, 通常 package.json 中的 name 字段是一个短的小写字符串。 通常还应该指定一个 productName 字段, 是首字母大写的完整名称，用于表示应用程序的名称。Electron 会优先使用这个字段作为应用名。
app.userAgentFallbackString Electron 用于全局回退的用户代理字符串。
当用户代理在webContents 或 session 级别没有被设置时，将使用此用户代理。 有助于确保您的整个应用程序具有相同的用户代理。 在应用初始化中尽早设置为自定义值，以确保使用的是您覆盖的值。
app.runningUnderRosettaTranslation macOS Readonly DeprecatedBoolean ，为 true 表明该应用程序目前正在运行在转译环境下。
您可以使用此属性来提示用户下载应用程序的 arm64 版本，当用户错误地在转译环境下运行 x64 版本。
\nDeprecated: This property is superceded by the runningUnderARM64Translation property which detects when the app is being translated to ARM64 in both macOS and Windows.
app.runningUnderARM64Translation Readonly macOS WindowsA Boolean which when true indicates that the app is currently running under an ARM64 translator (like the macOS Rosetta Translator Environment or Windows WOW).
您可以使用此属性来提示用户下载应用程序的 arm64 版本，当用户错误地在转译环境下运行 x64 版本。
", "title": "app", "description": "控制应用程序的事件生命周期。" }, "/docs/tutorial/application-debugging": { "locale": "zh-CN", "slug": "application-debugging", "href": "/docs/tutorial/application-debugging", "crowdinFileId": "256175", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/application-debugging.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "无论何时，您的Electron应用程序没有按照您设想的方式运行，一组调试工具也许可以帮助您找到代码的错误，性能瓶颈，或者优化的机会。
\n最广泛使用来调试指定渲染进程的工具是Chromium的开发者工具集。 它可以获取到所有的渲染进程，包括BrowserWindow的实例，BrowserView以及WebView。 您可以通过编程的方式在BrowserWindow的webContents中调用openDevTool()API来打开它们：
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.webContents.openDevTools()\n谷歌为他们的开发者工具提供了杰出的文档。 我们建议您熟悉它们，它们对于任何Electron开发者来说通常都是工具包中最强大的工具之一。
\n调试主进程有点棘手, 因为您不能简单地打开开发者工具来调试它们。 多亏了谷歌和Node.js的紧密合作，Chromium开发者工具可以被用来调试Electron的主进程，否则你也许会遇到许多怪事就像require不能再控制台中显示。
如果想获取更多信息，可以看调试主进程的文档
\n如果V8环境崩溃的话, DevTools 将显示以下信息
\nDevTools was disconnected from the page. Once page is reloaded, DevTools will automatically reconnect.
Chromium日志可以通过ELECTRON_ENABLE_LOGGING环境变量启用。 有关更多信息，请参见环境变量文档。
或者，可以传递命令行参数--enable-logging。 更多信息请查看命令行开关文档
To distribute your app with Electron, you need to package and rebrand it. 为此，您可以使用专用工具或手动方法。
\n您可以使用以下工具来分发您的应用程序：
\n\n这些工具将自动进行所有的步骤，例如，打包您的应用程序，重组可执行文件，并设置正确的图标。
\n您可以查看 快速上手指南 中如何用 electron-forge 打包您的应用程序的例子。
To distribute your app manually, you need to download Electron's prebuilt binaries. 接下来，你存放应用程序的文件夹需要叫做 app 并且需要放在 Electron 的 资源文件夹Resources下，如下面的示例所示。
\n\nNOTE: the location of Electron's prebuilt binaries is indicated with
\nelectron/in the examples below.
在 macOS 中:
\nelectron/Electron.app/Contents/Resources/app/\n├── package.json\n├── main.js\n└── index.html\n在 Windows 和 Linux 中:
\nelectron/resources/app\n├── package.json\n├── main.js\n└── index.html\nThen execute Electron.app on macOS, electron on Linux, or electron.exe on Windows, and Electron will start as your app. The electron directory will then be your distribution to deliver to users.
Instead of from shipping your app by copying all of its source files, you can package your app into an asar archive to improve the performance of reading files on platforms like Windows, if you are not already using a bundler such as Parcel or Webpack.
\n为了使用一个 asar 档案文件代替 app 文件夹，你需要修改这个档案文件的名字为 app.asar ， 然后将其放到 Electron 的资源文件夹下，然后 Electron 就会试图读取这个档案文件并从中启动。 如下所示：
在 macOS 中:
\nelectron/Electron.app/Contents/Resources/\n└── app.asar\n在 Windows 和 Linux 中:
\nelectron/resources/\n└── app.asar\nYou can find more details on how to use asar in the electron/asar repository.
将您的应用程序捆绑到Electron后，您可能需要在把应用分发给用户前将Electron进行重新定制
\n你可以将 Electron.app 重命名为任意你喜欢的名字，然后你也需要将一些文件中的 CFBundleDisplayName， CFBundleIdentifier 以及 CFBundleName 字段一并修改掉。 这些文件如下：
Electron.app/Contents/Info.plistElectron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plist你也可以重命名帮助程序以避免它在系统活动监视器中显示为Electron Helper， 但是请确保你已经修改了帮助应用的可执行文件的名字。
一个重命名后的应用程序的结构可能是这样的
\nMyApp.app/Contents\n├── Info.plist\n├── MacOS/\n│ └── MyApp\n└── Frameworks/\n └── MyApp Helper.app\n ├── Info.plist\n └── MacOS/\n └── MyApp Helper\n你可以将 electron.exe 重命名为任何你喜欢的名字，然后可以使用像 rcedit 那样的工具编辑它的 icon 和其他信息。
你可以将 electron 重命名为任意你喜欢的名字。
你也可以通过改变产品名称后从源码构建来重塑Electron的形象。 你只需要在 args.gn 文件中将构建参数设置为对应产品的名称(electron_product_name = \"YourProductName\")，并进行重新构建。
\n\n使应用程序能够自动更新
\n
进程：主进程
\n请参阅：在应用程序中如何实现更新的详细指南。
\nautoUpdater是一个EventEmitter.
目前只支持 macOS 和 Windows 版本。 在 Linux 上没有内置的自动更新程序，因此建议使用发行版包管理器来更新您的应用程序。
\n此外，每个平台都有一些细微的差别:
\n在macOS上, autoUpdater模块建立在 Squirrel.Mac上,这意味着你不需要任何特殊的设置来使它工作。 对于服务器端要求, 你可以阅读 Server Support. 注意App Transport Security (ATS) 适用于所有请求作为更新过程的一部分。</0> 如需禁用ATS的应用程序可以在其应用程序的plist中添加 NSAllowsArbitraryLoads属性。
注意： 在 macOS 上，您的应用程序必须得到签名后方可自动更新。 这是 Squirrel.Mac 的要求。
在 Windows 上, 你必须将应用程序安装在用户的计算机上才能使用autoUpdater, 所以推荐使用 electron-winstaller, electron-forge 或者 grunt-electron-installer 模块来生成Windows安装程序。
当使用 electron-winstaller 或 electron-forge 时，请确保不要在第一次运行你的应用程序时进行更新操作(也可查看这个 issue获取更多信息)。 还建议使用 electron-squirrel-startup 来创建应用程序的桌面快捷方式。
\n使用Squirrel生成的安装程序将以 com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE 的格式创建一个带有 Application User Model ID 的快捷图标，例子是 com.squirrel.slack.Slack 和 com.squirrel.code.Code。 你应该在自己的应用中使用 app.setAppUserModelId API 方法设置相同的 API和ID，不然 Windows 将不能正确地把你的应用固定在任务栏上。
Like Squirrel.Mac, Windows can host updates on S3 or any other static file host. 你可以阅读 Squirrel.Windows的文档来获得更多关于 Squirrel.Windows 是如何工作的信息。
\nautoUpdater 对象会触发以下的事件:
返回:
\nerror Error当更新发生错误的时候触发。
\n当开始检查更新的时候触发。
\n当有可用更新的时候触发。 更新将自动下载。
\n当没有可用更新的时候触发。
\n返回:
\nevent EventreleaseNotes StringreleaseName StringreleaseDate DateupdateURL String在更新下载完成的时候触发。
\n在 Windows 上只有 releaseName 是有效的。
注意： 此事件并不一定需要处理。 成功下载的更新仍将在应用程序下次启动时应用。
\n此事件是在用户调用quitAndInstall()之后发出的。
当此API被调用时，会在所有窗口关闭之前发出 before-quit 事件。 因此，如果您希望在关闭窗口进程退出之前执行操作，则应该侦听此事件，以及侦听 before-quit。
autoUpdater 对象具有以下方法:
autoUpdater.setFeedURL(选项)选项 对象url Stringheaders Record<String, String> (可选) macOS - HTTP 请求头。serverType String(可选) macOS - 可以是json 或者 default,查看 Squirrel.Mac 的README文件获取更多详细信息。设置检查更新的 url，并且初始化自动更新。
autoUpdater.getFeedURL()返回 String - 获取当前更新的 Feed 链接.
autoUpdater.checkForUpdates()询问服务器是否有更新。 在使用此 API 之前，您必须调用setFeedURL 。
Note: If an update is available it will be downloaded automatically. Calling autoUpdater.checkForUpdates() twice will download the update two times.
autoUpdater.quitAndInstall()重启应用并在下载后安装更新。 它只应在发出 update-downloaded 后方可被调用。
在此机制下，调用 autoUpdater.quitAndInstall() 将首先关闭所有应用程序窗口，并且在所有窗口都关闭之后自动调用 app.quit()
注意: 严格来讲，执行一次自动更新不一定要调用此方法。因为下载更新文件成功之后，下次应用启动的时候会强制更新。
", "title": "autoUpdater", "description": "使应用程序能够自动更新" }, "/docs/tutorial/automated-testing-with-a-custom-driver": { "locale": "zh-CN", "slug": "automated-testing-with-a-custom-driver", "href": "/docs/tutorial/automated-testing-with-a-custom-driver", "crowdinFileId": "256179", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/automated-testing-with-a-custom-driver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "为Electron应用编写自动测试, 你需要一种 \"驱动\" 应用程序的方法。 Spectron is a commonly-used solution which lets you emulate user actions via WebDriver. 当然，也可以使用node的内建IPC STDIO来编写自己的自定义驱动。 自定义驱动的优势在于，它往往比Spectron需要更少的开销，并允许你向测试套件公开自定义方法。
\n我们将用 Node.js 的 child_process API 来创建一个自定义驱动。 测试套件将生成 Electron 子进程，然后建立一个简单的消息传递协议。
\nconst childProcess = require('child_process')\nconst electronPath = require('electron')\n\n// spawn the process\nconst env = { /* ... */ }\nconst stdio = ['inherit', 'inherit', 'inherit', 'ipc']\nconst appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })\n\n// listen for IPC messages from the app\nappProcess.on('message', (msg) => {\n // ...\n})\n\n// 向应用发送IPC消息\nappProcess.send({ my: 'message' })\n在 Electron 应用程序中，您可以侦听消息或者使用 Node.js 的 process API 发送回复：
\n// 从测试套件进程侦听IPC消息\nprocess.on('message', (msg) => {\n // ...\n})\n\n// 向测试套件进程发送IPC消息\nprocess.send({ my: 'message' })\n现在，我们可以使用appProcess 对象从测试套件到Electron应用进行通讯。
为了方便起见，你可能需要封装appProcess到一个驱动对象，以便提供更多高级函数。 下面是一个如何这样做的示例：
class TestDriver {\n constructor ({ path, args, env }) {\n this.rpcCalls = []\n\n // start child process\n env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages\n this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })\n\n // handle rpc responses\n this.process.on('message', (message) => {\n // pop the handler\n const rpcCall = this.rpcCalls[message.msgId]\n if (!rpcCall) return\n this.rpcCalls[message.msgId] = null\n // reject/resolve\n if (message.reject) rpcCall.reject(message.reject)\n else rpcCall.resolve(message.resolve)\n })\n\n // wait for ready\n this.isReady = this.rpc('isReady').catch((err) => {\n console.error('Application failed to start', err)\n this.stop()\n process.exit(1)\n })\n }\n\n // simple RPC call\n // to use: driver.rpc('method', 1, 2, 3).then(...)\n async rpc (cmd, ...args) {\n // send rpc request\n const msgId = this.rpcCalls.length\n this.process.send({ msgId, cmd, args })\n return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))\n }\n\n stop () {\n this.process.kill()\n }\n}\n在应用中, 你需要为 RPC 回调编写一个简单的处理程序:
\nif (process.env.APP_TEST_DRIVER) {\n process.on('message', onMessage)\n}\n\nasync function onMessage ({ msgId, cmd, args }) {\n let method = METHODS[cmd]\n if (!method) method = () => new Error('Invalid method: ' + cmd)\n try {\n const resolve = await method(...args)\n process.send({ msgId, resolve })\n } catch (err) {\n const reject = {\n message: err.message,\n stack: err.stack,\n name: err.name\n }\n process.send({ msgId, reject })\n }\n}\n\nconst METHODS = {\n isReady () {\n // do any setup needed\n return true\n }\n // define your RPC-able methods here\n}\n然后, 在测试套件中, 可以按如下方式使用测试驱动程序:
\nconst test = require('ava')\nconst electronPath = require('electron')\n\nconst app = new TestDriver({\n path: electronPath,\n args: ['./app'],\n env: {\n NODE_ENV: 'test'\n }\n})\ntest.before(async t => {\n await app.isReady\n})\ntest.after.always('cleanup', async t => {\n await app.stop()\n})\nWindows 上的 Electron CI 使用 AppVeyor, 后者则使用 Azure VM 镜像运行。 有时，由于 Chromium 要求发生变化，这些 VM 镜像需要更新。 为了更新，您将需要 PowerShell 和 Azure PowerShell 模块。
\nOccasionally we need to update these images owing to changes in Chromium or other miscellaneous build requirement changes.
\nExample Use Case:\n* 我们需要安装VS15.9或者我们已安装好VS15.7；然后可能会请求我们去更新Azure镜像
Identify the image you wish to modify.
\nGet the Azure storage account key
\nappveyorlibccbuilds Disk Storage Account Name you'd look for appveyorlibccbuilds in the list of storage accounts @ Home < Storage AccountsAccess Keys, and then you can use any of the keys present in the list.Get the full virtual machine image URI from Azure
\n$ACCT_NAME < Blobs < ImagesCopy the image using the Copy Master Image PowerShell script.
\n(images)libcc-20core-vs2017-15.9-2019-04-15.vhdSpin up a new VM using the Create Master VM from VHD PowerShell.
\nps1 file with ./create_master_vm_from_vhd.ps1Standard_F32s_v2East USLog back into Azure and find the VM you just created in Home < Virtual Machines < $YOUR_NEW_VM
Using Microsoft Remote Desktop, click Connect to connect to the VM.
AppVeyor Enterprise master VM credentials.Modify the VM as required.
\nShut down the VM and then delete it in Azure.
\nAdd the new image to the Appveyor Cloud settings or modify an existing image to point to the new VHD.
\ndeviceName StringdeviceId StringElectron 的开发并不那么死板. 也就是说, 开发, 编译, 打包, 与发布 Electron 应用程序的方法中, 没有一个是可以称为 \"唯一标准\" 的方法. Electron 的编译和运行时相关额外功能通常可以在 npm 的独立安装包中找到, 这样开发者就可以根据自己的需求同时编译应用和 build pipeline.
\n得益于高度的模块化和扩展性，所有的开发团队，无论大小都可以在整个开发周期中无往不利、所向披靡。 与此同时，对于大多数开发者来说如果能有一款社区驱动的boilerplates或者命令行 工具，无疑会使应用的编译、打包、分发更加简单。
\n一个模板就像是一张空白的画布，你可以以它为基础来搭建你的应用。 通常来说，你可以从一个代码仓库克隆一个模板，然后修改成你心仪的样子。
\n命令行工具则是在整个开发和分发过程中从另一方面给你提供帮助。 他们更有用，但同时也对代码结构和构建项目有着硬性的要求。 特别是对于初学者来说，命令行工具十分有用。
\nElectron Forge 是一个用来构建现代化Electron应用的完善的工具。 Electron Forge将多个现有的（ 且有稳定维护的 ）Electron构建工具整合为一个简单易用的工具包，所有人都可以用它来快速地搭建Electron开发环境。
\nForge 始于一个使用了 Webpack 作为打包器的 a ready-to-use template 模板项目。 该项目包含有一个 typescript 配置的示例，并预置了两个便于定制化的配置文件。 Forge 的一些核心模块来自于上层的 Electron 社区（比如electron-packager），因而 Electron 主要维护人员（比如说 Slack）提交的 Electron 更新也会使 Forge 的用户受益。
关于Forge的更多信息，请查阅electronforge.io。
\nElectron Builder 是一个完备的Electron应用打包和分发解决方案，它致力于软件开发的集成体验。 electron-builder 出于简化的目的添加了一个依赖项，可以在内部管理所有更多的要求。
electron-builder 会将Electron维护者使用的模块和功能(例如: auto-updater) 替换为自定义的. Electron Builder打包的应用内组件的集成度会更高，同时与主流的Electron应用共同点也就更少了。
关于Electron Builder的更多信息，请查阅代码仓库。
\n如果你不希望任何工具，而想要简单地从一个模板开始构建，CT Lin的 electron-react-boilerplate 可能值得一看。 它在社区中很受欢迎，并在内部使用了 electron-builder。
\"Awesome Electron\" 列表涵盖了众多可供选择的工具和模板。 如果您发现列表的长度令人畏惧，请不要忘记，您也可以在开发过程中逐渐添加工具。
", "title": "模板和命令行界面", "description": "" }, "/docs/breaking-changes": { "locale": "zh-CN", "slug": "breaking-changes", "href": "/docs/breaking-changes", "crowdinFileId": "256117", "githubUrl": "https://github.com/electron/electron/tree/main/docs/breaking-changes.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "这里将记录重大更改,并在可能的情况下向JS代码添加弃用警告,在这更改之前至少会有一个重要版本.
\n本文档使用以下约定对重大更改进行分类：
\nremote moduleThe remote module was deprecated in Electron 12, and will be removed in Electron 14. 由@electronic/remote 模块替代。
// Deprecated in Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// 替换为：\nconst { BrowserWindow } = require('@electron/remote')\n\n// 在主进程中：\nrequire('@electron/remote/main').initialize()\napp.allowRendererProcessReuseThe app.allowRendererProcessReuse property will be removed as part of our plan to more closely align with Chromium's process model for security, performance and maintainability.
For more detailed information see #18397.
\nThe affinity option when constructing a new BrowserWindow will be removed as part of our plan to more closely align with Chromium's process model for security, performance and maintainability.
For more detailed information see #18397.
\nwindow.open()可选参数 frameName 将不再设置窗口的标题。 该功能现在遵循 原生文档 中的约束，由名为 windowName 的参数控制。
若您之前使用了该参数用于设置窗口标题，您可以转而使用 win.setTitle(title)。
\nworldSafeExecuteJavaScript在 Electron 14, worldSafeExecuteJavaScript 将被移除。 除此之外没有其他方式，请保证您的代码中包含该属性。 Electron 12中默认启用该属性。\n12.
若您使用了 webFrame.executeJavaScript 或 webFrame.executeJavaScriptInIsolatedWorld，这个改动会对您造成影响。 您需要保证 Context Bridge API 支持这些方法的返回值，因为这些方法使用相同的值传递语义。
nativeWindowOpen 默认为 truePrior to Electron 14, window.open was by default shimmed to use BrowserWindowProxy. This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. nativeWindowOpen is no longer experimental, and is now the default.
See the documentation for window.open in Electron for more details.
\nPrior to Electron 14, windows opened with window.open would inherit BrowserWindow constructor options such as transparent and resizable from their parent window. Beginning with Electron 14, this behavior is removed, and windows will not inherit any BrowserWindow constructor options from their parents.
Instead, explicitly set options for the new window with setWindowOpenHandler:
webContents.setWindowOpenHandler((details) => {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n // ...\n }\n }\n})\nadditionalFeaturesThe deprecated additionalFeatures property in the new-window and did-create-window events of WebContents has been removed. Since new-window uses positional arguments, the argument is still present, but will always be the empty array []. (Though note, the new-window event itself is deprecated, and is replaced by setWindowOpenHandler.) Bare keys in window features will now present as keys with the value true in the options object.
// Removed in Electron 14\n// Triggered by window.open('...', '', 'my-key')\nwebContents.on('did-create-window', (window, details) => {\n if (details.additionalFeatures.includes('my-key')) {\n // ...\n }\n})\n\n// Replace with\nwebContents.on('did-create-window', (window, details) => {\n if (details.options['my-key']) {\n // ...\n }\n})\nsession.setPermissionCheckHandler(handler)handler 方法的第一个参数曾是 webContents，但现在可以为 null。 为正确响应权限检查，您需要使用requestingOrigin、embeddingOrigin 和 securityOrigin 这些属性。 因为 webContents 现在可能为 null，您不应当依赖此参数。
// 旧代码\nsession.setPermissionCheckHandler((webContents, permission) => {\n if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {\n return true\n }\n return false\n})\n\n// 变更为\nsession.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {\n return true\n }\n return false\n})\nshell.moveItemToTrash()已废弃的同步方法 shell.moveItemToTrash() 已移除。 作为替代，您应当使用异步的 shell.trashItem()。
// 在 Electron 13 移除\nshell.moveItemToTrash(path)\n// 替换为\nshell.trashItem(path).then(/* ... */)\nBrowserWindow 扩展 API移除已弃用的扩展 API：
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()改为使用 session API：
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// 在 Electron 13 移除\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// 替换为\nsession.defaultSession.loadExtension(path)\n// 在 Electron 13 移除\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// 替换为\nsession.defaultSession.removeExtension(extension_id)\n// 在 Electron 13 移除\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// 替换为\nsession.defaultSession.getAllExtensions()\nsystemPreferences 中的方法systemPreferences 方法已经被废弃：
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()使用 nativeTheme 属性作为替代：
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// 在 Electron 13 移除\nsystemPreferences.isDarkMode()\n// 替换为\nnativeTheme.shouldUseDarkColors\n\n// 在 Electron 13 移除\nsystemPreferences.isInvertedColorScheme()\n// 替换为\nnativeTheme.shouldUseInvertedColorScheme\n\n// 在 Electron 13 移除\nsystemPreferences.isHighContrastColorScheme()\n// 替换为\nnativeTheme.shouldUseHighContrastColors\nnew-window 事件WebContents 中的 new-window 事件已经被废弃。 已弃用：webContents.setWindowOpenHandler()。
// 在 Electron 13 废弃\nwebContents.on('new-window', (event) => {\n event.preventDefault()\n})\n\n// 替换为\nwebContents.setWindowOpenHandler((details) => {\n return { action: 'deny' }\n})\nChromium 已经取消了对Flash的支持，因此我们必须效仿。 更多详细信息，请参阅 Chromium 的 Flash Roadmap
\nworldSafeExecuteJavaScript 默认为 true在 Electron 12, worldSafeExecuteJavaScript 将默认启用。 要恢复 上一个行为， worldSafeExecuteJavaScript: false 必须在 Web 首选项中指定。 请注意，设置此选项为 false 是不安全的。
此选项将在 Electron 14 中删除，所以请迁移您的代码以支持默认 值。
\ncontextIsolation 默认为 true在 Electron 12, contextIsolation 将默认启用。 要恢复 上一个行为， contextIsolation: false 必须在 Web 首选项中指定。
我们 建议启用contextIsolation ，以保证您的应用程序的安全性。
\nAnother implication is that require() cannot be used in the renderer process unless nodeIntegration is true and contextIsolation is false.
更多信息请参阅：https://github.com/electron/electron/issues/23506
\ncrashReporter.getCrashesDirectory()crashReporter.getCrashesDirectory 方法已被删除。 这个方法 应该被 app.getPath('crashDumps')替换。
// 在 Electron 12 移除\ncrashReporter.getCrashesDirectory()\n// 替换为\napp.getPath('crashDumps')\ncrashReporter methods in the renderer processcrashReporter 方法在渲染进程中不再能使用：
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectory它们只应从主要进程中调用。
\n更多详细信息请访问 #23265
\ncrashReporter.start({ compress: true })The default value of the compress option to crashReporter.start has changed from false to true. This means that crash dumps will be uploaded to the crash ingestion server with the Content-Encoding: gzip header, and the body will be compressed.
If your crash ingestion server does not support compressed payloads, you can turn off compression by specifying { compress: false } in the crash reporter options.
remote 模块remote 模块在 Electron 12 废弃，并将在 Electron 14 被移除 由@electronic/remote 模块替代。
// Deprecated in Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// 替换为：\nconst { BrowserWindow } = require('@electron/remote')\n\n// 在主进程中：\nrequire('@electron/remote/main').initialize()\nshell.moveItemToTrash()The synchronous shell.moveItemToTrash() has been replaced by the new, asynchronous shell.trashItem().
// 在 Electron 12 废弃\nshell.moveItemToTrash(path)\n// 替换为\nshell.trashItem(path).then(/* ... */)\nBrowserView.{destroy, fromId, fromWebContents, getAllViews} and id property of BrowserViewThe experimental APIs BrowserView.{destroy, fromId, fromWebContents, getAllViews} have now been removed. Additionally, the id property of BrowserView has also been removed.
For more detailed information, see #23578.
\ncompanyName argument to crashReporter.start()The companyName argument to crashReporter.start(), which was previously required, is now optional, and further, is deprecated. To get the same behavior in a non-deprecated way, you can pass a companyName value in globalExtra.
// Deprecated in Electron 10\ncrashReporter.start({ companyName: 'Umbrella Corporation' })\n// Replace with\ncrashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })\ncrashReporter.getCrashesDirectory()The crashReporter.getCrashesDirectory method has been deprecated. 这个方法 应该被 app.getPath('crashDumps')替换。
// Deprecated in Electron 10\ncrashReporter.getCrashesDirectory()\n// Replace with\napp.getPath('crashDumps')\ncrashReporter 方法Calling the following crashReporter methods from the renderer process is deprecated:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryThe only non-deprecated methods remaining in the crashReporter module in the renderer are addExtraParameter, removeExtraParameter and getParameters.
当从主要进程调用时，上述所有方法均未被弃用。
\n更多详细信息请访问 #23265
\ncrashReporter.start({ compress: false })Setting { compress: false } in crashReporter.start is deprecated. Nearly all crash ingestion servers support gzip compression. 此选项将在未来版本的 Electron 中删除。
enableRemoteModule 默认为 falseIn Electron 9, using the remote module without explicitly enabling it via the enableRemoteModule WebPreferences option began emitting a warning. In Electron 10, the remote module is now disabled by default. To use the remote module, enableRemoteModule: true must be specified in WebPreferences:
const w = new BrowserWindow({\n webPreferences: {\n enableRemoteModule: true\n }\n})\nWe recommend moving away from the remote module.
\nprotocol.unregisterProtocolprotocol.uninterceptProtocol这些 APIs 现在是同步的，不再需要可选的回调。
\n// Deprecated\nprotocol.unregisterProtocol(scheme, () => { /* ... */ })\n// Replace with\nprotocol.unregisterProtocol(scheme)\nprotocol.registerFileProtocolprotocol.registerBufferProtocolprotocol.registerStringProtocolprotocol.registerHttpProtocolprotocol.registerStreamProtocolprotocol.interceptFileProtocolprotocol.interceptStringProtocolprotocol.interceptBufferProtocolprotocol.interceptHttpProtocolprotocol.interceptStreamProtocol这些 APIs 现在是同步的，不再需要可选的回调。
\n// 已废弃\nprotocol.registerFileProtocol(scheme, handler, () => { /* ... */ })\n// 替换为\nprotocol.registerFileProtocol(scheme, handler)\nThe registered or intercepted protocol does not have effect on current page until navigation happens.
\nprotocol.isProtocolHandledThis API is deprecated and users should use protocol.isProtocolRegistered and protocol.isProtocolIntercepted instead.
// Deprecated\nprotocol.isProtocolHandled(scheme).then(() => { /* ... */ })\n// Replace with\nconst isRegistered = protocol.isProtocolRegistered(scheme)\nconst isIntercepted = protocol.isProtocolIntercepted(scheme)\nAs of Electron 9 we do not allow loading of non-context-aware native modules in the renderer process. This is to improve security, performance and maintainability of Electron as a project.
\nIf this impacts you, you can temporarily set app.allowRendererProcessReuse to false to revert to the old behavior. This flag will only be an option until Electron 11 so you should plan to update your native modules to be context aware.
For more detailed information see #18397.
\nBrowserWindow 扩展 API以下扩展 APIs 已废弃:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()改为使用 session API：
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// 在 Electron 9 废弃\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// 替换为\nsession.defaultSession.loadExtension(path)\n// 在 Electron 9 废弃\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// 替换为\nsession.defaultSession.removeExtension(extension_id)\n// 在 Electron 9 废弃\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// 替换为\nsession.defaultSession.getAllExtensions()\n<webview>.getWebContents()此API在 Electron 8.0中被废弃，现已删除。
\n// 在 Electron 9.0 移除\nwebview.getWebContents()\n// 替换为\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium has removed support for changing the layout zoom level limits, and it is beyond Electron's capacity to maintain it. 函数在 Electron 8.x 废弃，并将在 Electron 9.x 被移除。 The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.
\nIn Electron 8.0, IPC was changed to use the Structured Clone Algorithm, bringing significant performance improvements. To help ease the transition, the old IPC serialization algorithm was kept and used for some objects that aren't serializable with Structured Clone. In particular, DOM objects (e.g. Element, Location and DOMMatrix), Node.js objects backed by C++ classes (e.g. process.env, some members of Stream), and Electron objects backed by C++ classes (e.g. WebContents, BrowserWindow and WebFrame) are not serializable with Structured Clone. Whenever the old algorithm was invoked, a deprecation warning was printed.
In Electron 9.0, the old serialization algorithm has been removed, and sending such non-serializable objects will now throw an \"object could not be cloned\" error.
\nshell.openItem is now shell.openPathThe shell.openItem API has been replaced with an asynchronous shell.openPath API. You can see the original API proposal and reasoning here.
The algorithm used to serialize objects sent over IPC (through ipcRenderer.send, ipcRenderer.sendSync, WebContents.send and related methods) has been switched from a custom algorithm to V8's built-in Structured Clone Algorithm, the same algorithm used to serialize messages for postMessage. This brings about a 2x performance improvement for large messages, but also brings some breaking changes in behavior.
undefined.// Previously:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => results in { value: 3 } arriving in the main process\n\n// From Electron 8:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => throws Error(\"() => {} could not be cloned.\")\nNaN, Infinity and -Infinity will now be correctly serialized, instead of being converted to null.null.Set, Map, Error and RegExp values will be correctly serialized, instead of being converted to {}.BigInt values will be correctly serialized, instead of being converted to null.nulls.Date objects will be transferred as Date objects, instead of being converted to their ISO string representation.Uint8Array, Uint16Array, Uint32Array and so on) will be transferred as such, instead of being converted to Node.js Buffer.Buffer objects will be transferred as Uint8Arrays. You can convert a Uint8Array back to a Node.js Buffer by wrapping the underlying ArrayBuffer:Buffer.from(value.buffer, value.byteOffset, value.byteLength)\nSending any objects that aren't native JS types, such as DOM objects (e.g. Element, Location, DOMMatrix), Node.js objects (e.g. process.env, Stream), or Electron objects (e.g. WebContents, BrowserWindow, WebFrame) is deprecated. In Electron 8, these objects will be serialized as before with a DeprecationWarning message, but starting in Electron 9, sending these kinds of objects will throw a 'could not be cloned' error.
<webview>.getWebContents()This API is implemented using the remote module, which has both performance and security implications. Therefore its usage should be explicit.
// Deprecated\nwebview.getWebContents()\n// Replace with\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nHowever, it is recommended to avoid using the remote module altogether.
// main\nconst { ipcMain, webContents } = require('electron')\n\nconst getGuestForWebContents = (webContentsId, contents) => {\n const guest = webContents.fromId(webContentsId)\n if (!guest) {\n throw new Error(`Invalid webContentsId: ${webContentsId}`)\n }\n if (guest.hostWebContents !== contents) {\n throw new Error('Access denied to webContents')\n }\n return guest\n}\n\nipcMain.handle('openDevTools', (event, webContentsId) => {\n const guest = getGuestForWebContents(webContentsId, event.sender)\n guest.openDevTools()\n})\n\n// renderer\nconst { ipcRenderer } = require('electron')\n\nipcRenderer.invoke('openDevTools', webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium has removed support for changing the layout zoom level limits, and it is beyond Electron's capacity to maintain it. The function will emit a warning in Electron 8.x, and cease to exist in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.
\nsystemPreferencesThe following systemPreferences events have been deprecated:
inverted-color-scheme-changedhigh-contrast-color-scheme-changedUse the new updated event on the nativeTheme module instead.
// Deprecated\nsystemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })\nsystemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })\n\n// Replace with\nnativeTheme.on('updated', () => { /* ... */ })\nsystemPreferences 中的方法systemPreferences 方法已经被废弃：
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()使用 nativeTheme 属性作为替代：
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// 已废弃\nsystemPreferences.isDarkMode()\n// 替换为\nnativeTheme.shouldUseDarkColors\n\n// 已废弃\nsystemPreferences.isInvertedColorScheme()\n// 替换为\nnativeTheme.shouldUseInvertedColorScheme\n\n// 已废弃\nsystemPreferences.isHighContrastColorScheme()\n// 替换为\nnativeTheme.shouldUseHighContrastColors\n这是在构建原生 node 模块时在 .npmrc 文件中指定为 disturl 的 url 或是 --dist-url 命令行标志. Both will be supported for the foreseeable future but it is recommended that you switch.
Deprecated: https://atom.io/download/electron
\nReplace with: https://electronjs.org/headers
\nsession.clearAuthCache() no longer accepts optionsThe session.clearAuthCache API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.
// Deprecated\nsession.clearAuthCache({ type: 'password' })\n// Replace with\nsession.clearAuthCache()\npowerMonitor.querySystemIdleState is now powerMonitor.getSystemIdleState// Removed in Electron 7.0\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime is now powerMonitor.getSystemIdleTime// Removed in Electron 7.0\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\nwebFrame.setIsolatedWorldInfo replaces separate methods// Removed in Electron 7.0\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Replace with\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nmarked property on getBlinkMemoryInfoThis property was removed in Chromium 77, and as such is no longer available.
\nwebkitdirectory attribute for <input type=\"file\"/> now lists directory contentsThe webkitdirectory property on HTML file inputs allows them to select folders. Previous versions of Electron had an incorrect implementation where the event.target.files of the input returned a FileList that returned one File corresponding to the selected folder.
As of Electron 7, that FileList is now list of all files contained within the folder, similarly to Chrome, Firefox, and Edge (link to MDN docs).
As an illustration, take a folder with this structure:
\nfolder\n├── file1\n├── file2\n└── file3\nIn Electron <=6, this would return a FileList with a File object for:
path/to/folder\nIn Electron 7, this now returns a FileList with a File object for:
/path/to/folder/file3\n/path/to/folder/file2\n/path/to/folder/file1\nNote that webkitdirectory no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).
Electron 5 and Electron 6 introduced Promise-based versions of existing asynchronous APIs and deprecated their older, callback-based counterparts. In Electron 7, all deprecated callback-based APIs are now removed.
\nThese functions now only return Promises:
\napp.getFileIcon() #15742app.dock.show() #16904contentTracing.getCategories() #16583contentTracking.getTraceBufferUs() #16600contentTracing.startRecording() #16584contentTracing.stopRecording() #16584contents.executeJavaScript() #17312cookies.flushStore() #16464cookies.get() #16464cookies.remove() #16464cookies.set() #16464debugger.sendCommand() #16861dialog.showCertificateTrustDialog() #17181inAppPurchase.getProducts() #17355inAppPurchase.purchaseProduct()#17355netLog.stopLogging() #16862session.clearAuthCache() #17259session.clearCache() #17185session.clearHostResolverCache() #17229session.clearStorageData() #17249session.getBlobData() #17303session.getCacheSize() #17185session.getCacheSize() #17185session.setProxy() #17222shell.openExternal() #16176webContents.loadFile() #15855webContents.loadURL() #15855webContents.hasServiceWorker() #16535webContents.printToPDF() #16795webContents.savePage() #16742webFrame.executeJavaScript() #17312webFrame.executeJavaScriptInIsolatedWorld() #17312webviewTag.executeJavaScript() #17312win.capturePage() #15743这些功能现在有两种形式，即同步和基于Promise的异步：
\ndialog.showMessageBox()/dialog.showMessageBoxSync() #17298dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054win.setMenu(null) is now win.removeMenu()// 不推荐\nwin.setMenu(null)\n// 替换为\nwin.removeMenu()\nelectron.screen in the renderer process should be accessed via remote// 不推荐\nrequire('electron').screen\n// 替换为\nrequire('electron').remote.screen\nrequire()ing node builtins in sandboxed renderers no longer implicitly loads the remote version// 不推荐\nrequire('child_process')\n// 替换为\nrequire('electron').remote.require('child_process')\n\n// 不推荐\nrequire('fs')\n// 替换为\nrequire('electron').remote.require('fs')\n\n// 不推荐\nrequire('os')\n// 替换为\nrequire('electron').remote.require('os')\n\n// 不推荐\nrequire('path')\n// 替换为\nrequire('electron').remote.require('path')\npowerMonitor.querySystemIdleState replaced with powerMonitor.getSystemIdleState// Deprecated\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime replaced with powerMonitor.getSystemIdleTime// Deprecated\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\napp.enableMixedSandbox() is no longer needed// Deprecated\napp.enableMixedSandbox()\n混合沙盒模式已默认启用。
\nTray.setHighlightModeUnder macOS Catalina our former Tray implementation breaks. Apple's native substitute doesn't support changing the highlighting behavior.
\n// Deprecated\ntray.setHighlightMode(mode)\n// API will be removed in v7.0 without replacement.\nnodeIntegration and webviewTag default to false, contextIsolation defaults to true不推荐使用以下 webPreferences 选项默认值，以支持下面列出的新默认值。
| 属性 | 不推荐使用的默认值 | 新的默认值 |
|---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration 未设置过则是 true | false |
如下: Re-enabling the webviewTag
\nconst w = new BrowserWindow({\n webPreferences: {\n webviewTag: true\n }\n})\nnodeIntegration in child windows opened via nativeWindowOpenChild windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is true.
Renderer process APIs webFrame.registerURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. 新的 API protocol.registerSchemeasviliged 已被添加，并用于注册具有必要权限的自定义 scheme。 自定义 scheme 需要在 app 触发 ready 事件之前注册。
webFrame.setIsolatedWorld* replaced with webFrame.setIsolatedWorldInfo// 弃用\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// 替换为\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nwebFrame.setSpellCheckProvider now takes an asynchronous callbackThe spellCheck callback is now asynchronous, and autoCorrectWord parameter has been removed.
// Deprecated\nwebFrame.setSpellCheckProvider('en-US', true, {\n spellCheck: (text) => {\n return !spellchecker.isMisspelled(text)\n }\n})\n// Replace with\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck: (words, callback) => {\n callback(words.filter(text => spellchecker.isMisspelled(text)))\n }\n})\nwebContents.getZoomLevel and webContents.getZoomFactor are now synchronouswebContents.getZoomLevel and webContents.getZoomFactor no longer take callback parameters, instead directly returning their number values.
// Deprecated\nwebContents.getZoomLevel((level) => {\n console.log(level)\n})\n// Replace with\nconst level = webContents.getZoomLevel()\nconsole.log(level)\n// Deprecated\nwebContents.getZoomFactor((factor) => {\n console.log(factor)\n})\n// Replace with\nconst factor = webContents.getZoomFactor()\nconsole.log(factor)\n以下列表包含了Electron4.0中重大的API更新
\napp.makeSingleInstance// 已废弃\napp.makeSingleInstance((argv, cwd) => {\n /* ... */\n})\n// 替换为\napp.requestSingleInstanceLock()\napp.on('second-instance', (event, argv, cwd) => {\n /* ... */\n})\napp.releaseSingleInstance// 废弃\napp.releaseSingleInstance()\n// 替换为\napp.releaseSingleInstanceLock()\napp.getGPUInfoapp.getGPUInfo('complete')\n// 现在的行为将与macOS下的`basic`设置一样\napp.getGPUInfo('basic')\nwin_delay_load_hook在为 Windows 构建本机模块时，将使 win_delay_load_hook 变量值 位于 binding.gyp 模块，必须为 true (这是默认值)。 如果这个钩子 不存在，那么本机模块将无法在 Windows 上加载，并出现错误 消息如 无法找到模块。 查看 原生模块指南 以获取更多信息.
以下包含了Electron 3.0中重大的API更新
\napp// 弃用\napp.getAppMemoryInfo()\n// 替换为\napp.getAppMetrics()\n\n// 弃用\nconst metrics = app.getAppMetrics()\nconst { memory } = metrics[0] // 弃用的属性\nBrowserWindow// 已废弃\nconst optionsA = { webPreferences: { blinkFeatures: '' } }\nconst windowA = new BrowserWindow(optionsA)\n// 替换为\nconst optionsB = { webPreferences: { enableBlinkFeatures: '' } }\nconst windowB = new BrowserWindow(optionsB)\n\n// 已废弃\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play_pause') {\n // do something\n }\n})\n// 替换为\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play-pause') {\n // do something\n }\n})\nclipboard// 过时的\nclipboard.readRtf()\n// 替换为\nclipboard.readRTF()\n\n// 过时的\nclipboard.writeRtf()\n// 替换为\nclipboard.writeRTF()\n\n// 过时的\nclipboard.readHtml()\n// 替换为\nclipboard.readHTML()\n\n// 过时的\nclipboard.writeHtml()\n//替换为\nclipboard.writeHTML()\ncrashReporter// 过时的\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n autoSubmit: true\n})\n// 替换为\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n uploadToServer: true\n})\nnativeImage// 弃用\nnativeImage.createFromBuffer(buffer, 1.0)\n// 替换为\nnativeImage.createFromBuffer(buffer, {\n scaleFactor: 1.0\n})\nprocess// 弃用\nconst info = process.getProcessMemoryInfo()\nscreen// 弃用\nscreen.getMenuBarHeight()\n// 替换为\nscreen.getPrimaryDisplay().workArea\nsession// 弃用\nses.setCertificateVerifyProc((hostname, certificate, callback) => {\n callback(true)\n})\n// 替换为\nses.setCertificateVerifyProc((request, callback) => {\n callback(0)\n})\nTray// 过时的\ntray.setHighlightMode(true)\n// 替换为\ntray.setHighlightMode('on')\n\n// 过时的\ntray.setHighlightMode(false)\n// 替换为\ntray.setHighlightMode('off')\nwebContents// 弃用\nwebContents.openDevTools({ detach: true })\n// 替换为\nwebContents.openDevTools({ mode: 'detach' })\n\n// 移除\nwebContents.setSize(options)\n// 没有该API的替代\nwebFrame// 弃用\nwebFrame.registerURLSchemeAsSecure('app')\n// 替换为\nprotocol.registerStandardSchemes(['app'], { secure: true })\n\n// 弃用\nwebFrame.registerURLSchemeAsPrivileged('app', { secure: true })\n// 替换为\nprotocol.registerStandardSchemes(['app'], { secure: true })\n<webview>// 移除\nwebview.setAttribute('disableguestresize', '')\n// 没有该API的替代\n\n// 移除\nwebview.setAttribute('guestinstance', instanceId)\n// 没有该API的替代\n\n// 键盘监听器在webview标签中不再起效\nwebview.onkeydown = () => { /* handler */ }\nwebview.onkeyup = () => { /* handler */ }\n这是在构建原生 node 模块时在 .npmrc 文件中指定为 disturl 的 url 或是 --dist-url 命令行标志.
过时的: https://atom.io/download/atom-shell
\n替换为: https://atom.io/download/electron
\n以下包含了Electron 2.0中重大的API更新
\nBrowserWindow// 已废弃\nconst optionsA = { titleBarStyle: 'hidden-inset' }\nconst windowA = new BrowserWindow(optionsA)\n// 替换为\nconst optionsB = { titleBarStyle: 'hiddenInset' }\nconst windowB = new BrowserWindow(optionsB)\nmenu// 移除\nmenu.popup(browserWindow, 100, 200, 2)\n// 替换为\nmenu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })\nnativeImage// 移除\nnativeImage.toPng()\n// 替换为\nnativeImage.toPNG()\n\n// 移除\nnativeImage.toJpeg()\n// 替换为\nnativeImage.toJPEG()\nprocessprocess.versions.electron 和 process.version.chrome 将成为只读属性, 以便与其他 process.versions 属性由Node设置。webContents// 移除\nwebContents.setZoomLevelLimits(1, 2)\n// 替换为\nwebContents.setVisualZoomLevelLimits(1, 2)\nwebFrame// 移除\nwebFrame.setZoomLevelLimits(1, 2)\n// 替换为\nwebFrame.setVisualZoomLevelLimits(1, 2)\n<webview>// 移除\nwebview.setZoomLevelLimits(1, 2)\n// 替换为\nwebview.setVisualZoomLevelLimits(1, 2)\n每个 Electron 发布版本包含两个相同的ARM版本，文件名略有不同，如electron-v1.7.3-linux-arm.zip 和 electron-v1.7.3-linux-armv7l.zip 添加包含v7l前缀的资源向用户明确其支持的ARM版本，并消除由未来armv6l 和 arm64 资源可能产生的歧义。
The file without the prefix is still being published to avoid breaking any setups that may be consuming it. Starting at 2.0, the unprefixed file will no longer be published.
\n", "title": "重大更改", "description": "" }, "/docs/api/browser-view": { "locale": "zh-CN", "slug": "browser-view", "href": "/docs/api/browser-view", "crowdinFileId": "256283", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-view.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "BrowserView 被用来让 BrowserWindow 嵌入更多的 web 内容。 它就像一个子窗口，除了它的位置是相对于父窗口。 这意味着可以替代webview标签.
\n\n创建和控制视图
\n
进程：主进程
\n// 在主进程中.\nconst { BrowserView, BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nconst view = new BrowserView()\nwin.setBrowserView(view)\nview.setBounds({ x: 0, y: 0, width: 300, height: 300 })\nview.webContents.loadURL('https://electronjs.org')\nnew BrowserView([可选]) 实验功能options Object (可选)webPreferences Object (可选) - 详情请看 BrowserWindow.使用 new BrowserView 创建的对象具有以下属性:
view.webContents 实验功能视图的WebContents 对象
使用 new BrowserView创建的对象具有以下实例方法:
view.setAutoResize(options) 实验功能选项 对象width Boolean（可选） - 如果为true，视图宽度跟随窗口变化。 默认值为 falseheight Boolean(可选) - 如果 true，视图的高度将增长和缩小 与窗口。 默认值为 falsehorizontal Boolean (可选) - 如果为 true，视图的x轴和宽度将随着窗口的大小变化等比例缩放。 默认值为 falsevertical Boolean(可选) - 如果 true，视图的y位置和高度将增长 和收缩比例与窗口。 默认值为 falseview.setBounds(bounds) 实验功能bounds Rectangle调整视图的大小，并将它移动到窗口边界
\nview.getBounds() 实验功能返回 Rectangle
此BrowserView实例的 bounds 为 Object。
view.setBackgroundColor(color) 实验功能color String - Color in #aarrggbb or #argb form. Alpha 通道是 可选的。\n\n创建并控制浏览器窗口。
\n
进程：主进程
\n// 在主进程中.\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\n// Load a remote URL\nwin.loadURL('https://github.com')\n\n// Or load a local HTML file\nwin.loadFile('index.html')\n如果想创建一个无边框或者任意形状的透明窗口，你可以使用Frameless Window 的API
\nWhen loading a page in the window directly, users may see the page load incrementally, which is not a good experience for a native app. To make the window display without a visual flash, there are two solutions for different situations.
\nready-to-show event在加载页面时，渲染进程第一次完成绘制时，如果窗口还没有被显示，渲染进程会发出 ready-to-show 事件 。 在此事件后显示窗口将没有视觉闪烁：
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ show: false })\nwin.once('ready-to-show', () => {\n win.show()\n})\n这个事件通常在 did-finish-load 事件之后发出，但是页面有许多远程资源时，它可能会在 did-finish-load之前发出事件。
请注意，使用此事件意味着渲染器会被认为是\"可见的\"并绘制，即使 show 是false。 如果您使用 paintWhenInitiallyHidden: false，此事件将永远不会被触发。
backgroundColor property对于一个复杂的应用，ready-to-show 可能发出的太晚，会让应用感觉缓慢。 在这种情况下，建议立刻显示窗口，并使用接近应用程序背景的 backgroundColor
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ backgroundColor: '#2e2c29' })\nwin.loadURL('https://github.com')\n请注意，即使是使用 ready-to-show 事件的应用程序，仍建议使用设置 backgroundColor 使应用程序感觉更原生。
通过使用 parent 选项，你可以创建子窗口：
const { BrowserWindow } = require('electron')\n\nconst top = new BrowserWindow()\nconst child = new BrowserWindow({ parent: top })\nchild.show()\ntop.show()\nchild 窗口将总是显示在 top 窗口的顶部.
模态窗口是禁用父窗口的子窗口，创建模态窗口必须设置 parent 和 modal 选项：
const { BrowserWindow } = require('electron')\n\nconst child = new BrowserWindow({ parent: top, modal: true, show: false })\nchild.loadURL('https://github.com')\nchild.once('ready-to-show', () => {\n child.show()\n})\n页面可见性 API 的工作方式如下:
\nhidden. 在其他平台上，可见性状态只有在使用 win.hide()使窗口最小化或者隐藏时才为 hiddenBrowserWindow 时带有 show: false的参数, 最初的可见性状态将为visible 尽管窗口实际上是隐藏的。backgroundThrottling被禁用，可见性状态将保持为visible 即使窗口被最小化、遮挡或隐藏。推荐您在可见性状态为 hidden 时暂停消耗资源的操作以便减少电力消耗。
dialog.\n\n创建并控制浏览器窗口。
\n
进程：主进程
\nBrowserWindow是一个EventEmitter.
通过 options 可以创建一个具有原生属性的 BrowserWindow 。
new BrowserWindow([options])options Object (可选)width 整数型 (可选) - 窗口的宽度（以像素为单位）。 默认值为 800。height 整数型 (可选) - 窗口的高度（以像素为单位）。 默认值为 600。x Interger (可选) - (必选 如果使用了y) 窗口相对于屏幕左侧的偏移量。 默认值为将窗口居中。y Integer (可选) - (必选 如果使用了x) 窗口相对于屏幕顶端的偏移量。 默认值为将窗口居中。useContentSize Boolean (可选) - width 和 height 将设置为 web 页面的尺寸(译注: 不包含边框), 这意味着窗口的实际尺寸将包括窗口边框的大小，稍微会大一点。 默认值为 false.center Boolean (可选) - 窗口是否在屏幕居中.0.minHeight Integer(可选) - 窗口的最小高度。 默认值为 0.maxWidth Integer(可选)-窗口的最大宽度。 默认值不限maxHeight Integer (可选) - 窗口的最大高度。 默认值不限resizable Boolean (可选) - 窗口大小是否可调整。 默认值为 true。movable Boolean (可选) - 窗口是否可以移动. 该属性在Linux上未实现。 默认值为 true。minimizable Boolean (可选) - 窗口是否可最小化。 该属性在Linux上未实现。 默认值为 true。maximizable Boolean (可选) - 窗口是否可最大化。 该属性在Linux上未实现。 默认值为 true。closable Boolean (可选) - 窗口是否可关闭。 该属性在Linux上未实现。 默认值为 true。focusable Boolean (可选) - 窗口是否可以聚焦. 默认值为 true。 在 Windows 中设置 focusable: false 也意味着设置了skipTaskbar: true. 在 Linux 中设置 focusable: false 时窗口停止与 wm 交互, 并且窗口将始终置顶。alwaysOnTop Boolean (可选) - 窗口是否永远在别的窗口的上面。 默认值为 false.fullscreen Boolean (可选) - 窗口是否全屏. 当明确设置为 false 时，在 macOS 上全屏的按钮将被隐藏或禁用. 默认值为 false.fullscreenable Boolean (可选) - 窗口是否可以进入全屏状态. 在 macOS上, 最大化/缩放按钮是否可用 默认值为 true。simpleFullscreen Boolean (可选) - 在 macOS 上使用 pre-Lion 全屏。 默认值为 false.skipTaskbar Boolean (可选) - 是否在任务栏中显示窗口。 默认值为 false。kiosk Boolean (可选) - 窗口是否进入kiosk模式。 默认值为 false.titleString(可选) - 默认窗口标题 默认为\"Electron\"。 如果由loadURL()加载的HTML文件中含有标签<title>，此属性将被忽略。icon (NativeImage | String) (可选) - 窗口的图标. 在 Windows 上推荐使用 ICO 图标来获得最佳的视觉效果, 默认使用可执行文件的图标.show Boolean (可选) - 窗口是否在创建时显示。 默认值为 true。paintWhenInitiallyHiddenBoolean(可选) - 当show为false并且渲染器刚刚被创建时，它是否应激活。 为了让document.visibilityState 在show: false的情况下第一次加载时正确地工作，你应该把这个设置成false. 设置为 false 将会导致ready-to-show 事件不触发。 默认值为 true。frame Boolean (可选) - 设置为 false 时可以创建一个无边框窗口。 默认值为 true。parent BrowserWindow (可选) - 指定父窗口 默认值为 null.momodalable Boolean (可选) - 当前是否为模态窗口。 只有当窗口是子窗口时才起作用。 默认值为 false.acceptFirstMouse Boolean (optional) - Whether clicking an inactive window will also click through to the web contents. Default is false on macOS. This option is not configurable on other platforms.disableAutoHideCursor Boolean (可选) - 是否在打字时隐藏光标。 默认值为 false.autoHideMenuBar Boolean (可选) - 自动隐藏菜单栏，除非按了Alt键。 默认值为 false.enableLargerThanScreen Boolean (可选) - 是否允许改变窗口的大小使之大于屏幕的尺寸. 仅适用于 macOS，因为其它操作系统默认允许 大于屏幕的窗口。 默认值为 false.backgroundColor String(可选) - 窗口的背景颜色为十六进制值，例如#66CD00, #FFF, #80FFFFFF (设置transparent为true方可支持alpha属性，格式为#AARRGGBB)。 默认值为 #FFF（白色）。hasShadow Boolean (可选) - 窗口是否有阴影. 默认值为 true。opacity Number (可选)-设置窗口初始的不透明度, 介于 0.0 (完全透明) 和 1.0 (完全不透明) 之间。 目前仅支持Windows 和 macosdarkTheme Boolean (optional) - 强制窗口使用深色主题，只在部分GTK+3桌面环境下有效。 默认值为 false.transparent Boolean (可选) - 使窗口 透明。 默认值为 false. 在Windows上，仅在无边框窗口下起作用。type String (可选) - 窗口的类型, 默认为普通窗口. 更多信息见下文visualEffectState String (optional) - 指定material外观应如何反映macOS上的窗口活动状态。 必须与 vibrancy 属性一起使用。 可能的值有followWindow - 当窗口处于激活状态时，后台应自动显示为激活状态，当窗口处于非激活状态时，后台应自动显示为非激活状态。 默认为该值。active - 后台应一直显示为激活状态。inactive - 后台应一直显示为非激活状态。titleBarStyle String (optional) macOS Windows - The style of window title bar. 默认值为 default. 可能的值有default - Results in the standard title bar for macOS or Windows respectively.hidden - Results in a hidden title bar and a full size content window. On macOS, the window still has the standard window controls (“traffic lights”) in the top left. On Windows, when combined with titleBarOverlay: true it will activate the Window Controls Overlay (see titleBarOverlay for more information), otherwise no window controls will be shown.hiddenInset - Only on macOS, results in a hidden title bar with an alternative look where the traffic light buttons are slightly more inset from the window edge.customButtonsOnHover - Only on macOS, results in a hidden title bar and a full size content window, the traffic light buttons will display when being hovered over in the top left of the window. 注意: 此选项目前是实验性的。trafficLightPosition Point (可选的) - 设置控制按钮在无边框窗口中的位置。roundedCorners Boolean (可选) - 无框窗口是否应该在 macOS 上 圆角。 默认值为 true。fullscreenWindowTitle Boolean (可选) 已弃用 - macOS全屏模式下，在标题栏展示标题，需要 titleBarStyle 设置 hiddenInset 属性。 默认值为 false.thickFrame Boolean(可选)-对 Windows 上的无框窗口使用WS_THICKFRAME 样式，会增加标准窗口框架。 设置为 false 时将移除窗口的阴影和动画. 默认值为 true。vibrancy String (可选) - 窗口是否使用 vibrancy 动态效果, 仅 macOS 中有效. 可选值为 appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window 或 under-page。 请注意： appearance-based, light, dark, medium-light, and ultra-dark 已被弃用，并将在即将推出的 macOS Catalina (10.15版本) 中被移除。zoomToPageWidth Boolean (可选) - 控制 macOS 上，当选择性单击工具栏上的绿色stoplight按钮或单击 Window > Zoom menu item时的行为。 如果为 true, 窗口将放大到网页的本身宽度, false 将使其缩放到屏幕的宽度。 这也会影响直接调用 maximize() 时的行为。 默认值为 false.tabbingIdentifier String (可选) - 选项组卡的名称，在macOS 10.12+上可使窗口在原生选项卡中打开. 具有相同标识符的窗口将被组合在一起。 这还会在窗口的标签栏中添加一个原生的新选项卡按钮, 并允许 app 和窗口接收 new-window-for-tab 事件。webPreferences Object (可选) - 网页功能设置。devTools Boolean (可选) - 是否开启 DevTools. 如果设置为 false, 则无法使用 BrowserWindow.webContents.openDevTools () 打开 DevTools。 默认值为 true。nodeIntegration Boolean (可选) - 是否启用Node integration. 默认值为 false.nodeIntegrationInWorker Boolean (可选) - 是否在Web工作器中启用了Node集成. 默认值为 false. 更多内容参见 多线程.nodeIntegrationInSubFrames Boolean (可选项)(实验性)，是否允许在子页面(iframe)或子窗口(child window)中集成Node.js； 预先加载的脚本会被注入到每一个iframe，你可以用 process.isMainFrame 来判断当前是否处于主框架（main frame）中。preload String (可选) -在页面运行其他脚本之前预先加载指定的脚本 无论页面是否集成Node, 此脚本都可以访问所有Node API 脚本路径为文件的绝对路径。 当 node integration 关闭时, 预加载的脚本将从全局范围重新引入node的全局引用标志 参考示例.sandbox Boolean (可选)-如果设置该参数, 沙箱的渲染器将与窗口关联, 使它与Chromium OS-level 的沙箱兼容, 并禁用 Node. js 引擎。 它与 nodeIntegration 的选项不同，且预加载脚本的 API 也有限制. 更多详情.session Session (可选) - 设置页面的 session 而不是直接忽略 Session 对象, 也可用 partition 选项来代替，它接受一个 partition 字符串. 同时设置了session 和 partition时, session 的优先级更高. 默认使用默认的 session.partition String (optional) - 通过 session 的 partition 字符串来设置界面session. 如果 partition 以 persist:开头, 该页面将使用持续的 session，并在所有页面生效，且使用同一个partition. 如果没有 persist: 前缀, 页面将使用 in-memory session. 通过分配相同的 partition, 多个页可以共享同一会话。 默认使用默认的 session.zoomFactor Number (可选) - 页面的默认缩放系数, 3.0 表示 300%。 默认值为 1.0.javascript Boolean (可选) - 是否启用 JavaScript 支持。 默认值为 true。webSecurity Boolean (可选) - 当设置为 false, 它将禁用同源策略 (通常用来测试网站), 如果此选项不是由开发者设置的，还会把 allowRunningInsecureContent设置为 true. 默认值为 true。allowRunningInsecureContent Boolean (可选) - 允许一个 https 页面运行来自http url的JavaScript, CSS 或 plugins。 默认值为 false.images Boolean (可选) - 允许加载图片。 默认值为 true。imageAnimationPolicy String (optional) - Specifies how to run image animations (E.g. GIFs). Can be animate, animateOnce or noAnimation. 默认值为 animate.textAreasAreResizable Boolean (可选) - 允许调整 TextArea 元素大小。 默认值为 true。webgl Boolean (可选) - 启用 WebGL 支持。 默认值为 true。plugins Boolean (可选) - 是否应该启用插件。 默认值为 false.experimentalFeatures Boolean (可选) - 启用 Chromium 的实验功能。 默认值为 false.scrollBounce Boolean (可选) - 在 macOS 启用弹力动画 (橡皮筋) 效果。 默认值为 false.enableBlinkFeaturesString(可选) - 以逗号分隔的需要启用的特性列表，譬如CSSVariables,KeyboardEventKey 在 RuntimeEnabledFeatures.json5文件中查看被支持的所有特性.disableBlinkFeatures String (可选) - 以 ,分隔的禁用特性列表, 如 CSSVariables,KeyboardEventKey. 在RuntimeEnabledFeatures.json5 文件中查看被支持的所有特性.defaultFontFamily Object (可选) - 为font-family设置默认字体。standard String (可选) - 默认值为 Times New Roman.serif String (可选) - 默认值为 Times New Roman.sansSerif String (可选) - 默认值为 Arial.monospace String (可选) - 默认值为 Courier New.cursive String (可选) - 默认值为 Script.fantasy String (可选) - 默认值为 Impact.defaultFontSize Integer (可选) - 默认值为 16.defaultMonospaceFontSize Integer (可选) - 默认值为 13.minimumFontSize Integer (可选) - 默认值为 0.defaultEncoding String (可选) - 默认值为 ISO-8859-1.backgroundThrottlingBoolean (可选)-是否在页面成为背景时限制动画和计时器。 这也会影响到 Page Visibility API. 默认值为 true。offscreen Boolean (optional) - 是否绘制和渲染可视区域外的窗口. 默认值为 false. 更多详情, 请参见 offscreen rendering tutorial 。contextIsolation Boolean (可选) - 是否在独立 JavaScript 环境中运行 Electron API和指定的preload 脚本. 默认为 true。 预加载脚本所运行的上下文环境只能访问其自身专用的文档和全局窗口，其自身一系列内置的JavaScript (Array, Object, JSON, 等等) 也是如此，这些对于已加载的内容都是不可见的。 Electron API 将只在预加载脚本中可用，在已加载页面中不可用。 这个选项应被用于加载可能不被信任的远程内容时来确保加载的内容无法篡改预加载脚本和任何正在使用的Electron api。 该选项使用的是与Chrome内容脚本相同的技术。 你可以在开发者工具Console选项卡内顶部组合框中选择 'Electron Isolated Context'条目来访问这个上下文。nativeWindowOpen Boolean (可选) - 是否使用原生的window.open(). 默认值为 true。 除了 nodeIntegrationInSubFrames 为true时，其它情况下node integration将永远禁用。webviewTag Boolean (可选) - 是否启用 <webview> tag标签. 默认值为 false. 注意: 为 < webview> 配置的 preload 脚本在执行时将启用节点集成, 因此应确保远程或不受信任的内容无法创建恶意的 preload 脚本 。 可以使用 webContents 上的 will-attach-webview 事件对 preload 脚本进行剥离, 并验证或更改 <webview> 的初始设置。additionalArguments String - 一个将被附加到当前应用程序的渲染器进程中process.argv的字符串列表 。 可用于将少量的数据传递到渲染器进程预加载脚本中。safeDialogs Boolean (可选) - 是否启用浏览器样式的持续对话框保护。 默认值为 false.safeDialogsMessage String (可选) - 当持续对话框保护被触发时显示的消息。 如果没有定义，那么将使用缺省的消息。注意：当前缺省消息是英文，并没有本地化。disableDialogs Boolean (可选) - 是否完全禁用对话框。 覆盖 safeDialogs。 默认值为 false.navigateOnDragDrop Boolean (可选) - 将文件或链接拖放到页面上时是否触发页面跳转。 默认值为 false.autoplayPolicy String (可选) - 窗口中内容要使用的自动播放策略，值可以是 no-user-gesture-required, user-gesture-required, document-user-activation-required。 默认为 no-user-gesture-required。disableHtmlFullscreenWindowResize Boolean (可选) - 是否阻止窗口在进入 HTML 全屏时调整大小。 默认值为 false.accessibleTitle String (可选) - 仅提供给如屏幕读取器等辅助工具的替代标题字符串。 此字符串不直接对用户可见。spellcheck Boolean (可选) - 是否启用内置拼写检查器。 默认值为 true。enableWebSQL Boolean (可选) - 是否启用 WebSQL api。 默认值为 true。v8CacheOptions String (可选) - 强制 blink 使用 v8 代码缓存策略。 可接受的值为：none - 禁用代码缓存code - 基于启发式代码缓存bypassHeatCheck - 绕过启发式代码缓存，但使用懒编译。bypassHeatCheckAndEagerCompile - 与上面相同，除了编译是及时的。 默认策略是 code。enablePreferredSizeMode Boolean (可选) - 是否启用首选大小模式。 首选大小是包含文档布局所需的最小大小--无需滚动。 启用该属性将导致在首选大小发生变化时，在WebContents 上触发 preferred-size-changed 事件。 默认值为 false.titleBarOverlay Object | Boolean (optional) - When using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS or using a titleBarStyle so that the standard window controls (\"traffic lights\" on macOS) are visible, this property enables the Window Controls Overlay JavaScript APIs and CSS Environment Variables. Specifying true will result in an overlay with default system colors. 默认值为 false.color String (optional) Windows - The CSS color of the Window Controls Overlay when enabled. Default is the system color.symbolColor String (optional) Windows - The CSS color of the symbols on the Window Controls Overlay when enabled. Default is the system color.当使用 minWidth/maxWidth/minHeight/maxHeight 设置最小或最大窗口大小时, 它只限制用户。 它不会阻止您将不符合大小限制的值传递给 setBounds/setSize 或 BrowserWindow 的构造函数。
type 选项的候选值和行为与平台相关。 可能的值有
desktop、dock、toolbar、splash、notification。desktop, textured。textured 类型增加金属色泽的外观 (NSTexturedBackgroundWindowMask).desktop 类型将窗口置于桌面背景级别 (kCGDesktopWindowLevel - 1). 注意，桌面窗口不会接收焦点、键盘或鼠标事件，但您可以使用< 0> globalShortcut < /0 >接收快捷键的消息toolbar.使用 new BrowserWindow 创建的对象具有以下属性:
注意: 某些事件仅在特定的操作系统上可用, 这些方法会被标记出来。
\n返回:
\nevent Eventtitle StringexplicitSet Boolean文档更改标题时触发，调用event.preventDefault()将阻止更改标题 当标题合成自文件 URL 中时， explicitSet 的值为false。
返回:
\nevent Event在窗口要关闭的时候触发。 它在DOM 的beforeunload 和 unload 事件之前触发. 调用event.preventDefault()将阻止这个操作。
通常你想通过 beforeunload处理器来决定是否关闭窗口，但是它也会在窗口重载的时候触发. 在 Electron 里，返回除 undefined之外的任何值都将取消关闭. 例如：
window.onbeforeunload = (e) => {\n console.log('I do not want to be closed')\n\n // 与通常的浏览器不同,会提示给用户一个消息框,\n //返回非空值将默认取消关闭\n //建议使用对话框 API 让用户确认关闭应用程序.\n e.returnValue = false // 相当于 `return false` ，但是不推荐使用\n}\n注意: window.onbeforeunload = handler 和 window.addEventListener('beforeunload', handler) 的行为有细微的区别。 推荐总是显式地设置 event.returnValue, 而不是仅仅返回一个值, 因为前者在Electron中作用得更为一致.
在窗口关闭时触发 当你接收到这个事件的时候, 你应当移除相应窗口的引用对象，避免再次使用它.
\n因为强制关机或机器重启或会话注销而导致窗口会话结束时触发
\n网页变得未响应时触发
\n未响应的页面变成响应时触发
\n当窗口失去焦点时触发
\n当窗口获得焦点时触发
\n当窗口显示时触发
\n当窗口隐藏时触发
\n当页面已经渲染完成(但是还没有显示) 并且窗口可以被现实时触发
\n请注意，使用此事件意味着渲染器会被认为是\"可见的\"并绘制，即使 show 是false。 如果您使用 paintWhenInitiallyHidden: false，此事件将永远不会被触发。
窗口最大化时触发
\n当窗口从最大化状态退出时触发
\n窗口最小化时触发
\n当窗口从最小化状态恢复时触发
\n返回:
\nevent EventnewBounds Rectangle - 将要调整到的窗口尺寸。details Objectedge (String) - The edge of the window being dragged for resizing. Can be bottom, left, right, top-left, top-right, bottom-left or bottom-right.调整窗口大小前触发。 调用 event.preventDefault() 将阻止窗口大小调整。
请注意，该事件仅在手动调整窗口大小时触发。 通过 setBounds/setSize 调整窗口大小不会触发此事件。
The possible values and behaviors of the edge option are platform dependent. 可能的值有
bottom, top, left, right, top-left, top-right, bottom-left, bottom-right.bottom and right.bottom is used to denote vertical resizing.right is used to denote horizontal resizing.调整窗口大小后触发。
\n当窗口完成调整大小后触发一次。
\n这通常在手动调整窗口大小后触发。 在 macOS 系统上，使用setBounds/setSize调整窗口大小并将animate参数设置为true也会在调整大小完成后触发此事件。
返回:
\nevent EventnewBounds Rectangle - 窗口将要被移动到的位置。窗口移动前触发。 在Windows上，调用 event.preventDefault() 将阻止窗口移动。
请注意，该事件仅在手动调整窗口大小时触发。 通过 setBounds/setSize 调整窗口大小不会触发此事件。
窗口移动到新位置时触发
\n当窗口移动到新位置时触发一次
\n注意: 在 macOS 上，此事件是move的别名。
窗口进入全屏状态时触发
\n窗口离开全屏状态时触发
\n窗口进入由HTML API 触发的全屏状态时触发
\n窗口离开由HTML API触发的全屏状态时触发
\n返回:
\nevent EventisAlwaysOnTop Boolean设置或取消设置窗口总是在其他窗口的顶部显示时触发。
\n返回:
\nevent Eventcommand String请求一个应用程序命令时触发. 典型的是键盘上的媒体键或浏览器命令, 以及在Windows上的一些鼠标中内置的“后退”按钮。
\n命令是小写的，下划线替换为连字符，以及APPCOMMAND_ 前缀将被删除。 例如 APPCOMMAND_BROWSER_BACKWARD将被browser-backward触发.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.on('app-command', (e, cmd) => {\n // 当用户鼠标单击返回按钮时将自动返回上一个窗口\n if (cmd === 'browser-backward' && win.webContents.canGoBack()) {\n win.webContents.goBack()\n }\n})\n以下应用命令在 Linux 上有明确地支持：
\nbrowser-backwardbrowser-forward滚轮事件阶段开始时触发
\n滚轮事件阶段结束时触发
\n滚轮事件阶段到达元素边缘时触发
\n返回:
\nevent Eventdirection String三指滑动时触发。 可能的方向是 up, right, down, left。
此事件的基本方法是用来处理旧的macOS风格的触摸板滑动，屏幕内容不会随着滑动而移动。 大多数macOS触摸板都不再允许配置这样的滑动，因此为了正确地触发该事件，需将System Preferences > Trackpad > More Gestures中'Swipe between pages'首选项设置为'Swipe with two or three fingers'。
返回:
\nevent Eventrotation Float在触控板旋转手势上触发。 持续触发直到旋转手势结束。 每次触发的 rotation 值是自上次触发以来旋转的角度。 旋转手势最后一次触发的事件值永远是0。 逆时针旋转值为正值，顺时针旋转值为负值。
窗口打开sheet(工作表) 时触发
\n窗口关闭sheet(工作表) 时触发
\n当点击了系统的新标签按钮时触发
\n返回:
\nevent Eventpoint Point - 上下文菜单触发时的屏幕坐标。当系统上下文菜单在窗口上触发时发出， 通常只在用户右键点击你窗口的非客户端区域时触发。 非客户端区域指的是窗口标题栏或无边框窗口中被你声明为 -webkit-app-region: drag 的任意区域。
调用 event.preventDefault() 将阻止菜单显示。
BrowserWindow 类有以下方法:
BrowserWindow.getAllWindows()返回 BrowserWindow[] - 所有打开的窗口的数组
BrowserWindow.getFocusedWindow()返回 BrowserWindow | null - 此应用程序中当前获得焦点的窗口，如果无就返回 null.
BrowserWindow.fromWebContents(webContents)webContents WebContents返回 BrowserWindow | null - 返回拥有给定 webContents的窗口，否则如果内容不属于一个窗口，返回null。
BrowserWindow.fromBrowserView(browserView)browserView BrowserView返回 BrowserWindow | null - 拥有给定 browserView 的窗口。 如果给定的视图没有附加到任何窗口，返回 null。
BrowserWindow.fromId(id)id Integer返回 BrowserWindow | null - 带有给定 id 的窗口。
使用 new BrowserWindow 创建的对象具有以下属性:
const { BrowserWindow } = require('electron')\n// 本例中 `win` 是我们的实例\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('https://github.com')\nwin.webContents 只读此窗口拥有的 WebContents 对象。 所有与网页相关的事件和操作都将通过它完成。
有关它的方法和事件, 请参见 webContents documentation
win.id 只读一个 Integer 属性代表了窗口的唯一ID。 每个ID在整个Electron应用程序的所有 BrowserWindow 实例中都是唯一的。
win.autoHideMenuBar一个 Boolean 属性决定窗口菜单栏是否自动隐藏。 一旦设置，菜单栏将只在用户单击 Alt 键时显示。
如果菜单栏已经可见，将该属性设置为 true 将不会使其立刻隐藏。
win.simpleFullScreen一个 Boolean 属性，用于决定窗口是否处于简单(pre-Lion) 全屏模式。
win.fullScreen一个 Boolean 属性，用于决定窗口是否处于全屏模式。
win.focusable Windows macOSA Boolean property that determines whether the window is focusable.
win.visibleOnAllWorkspaces一个 Boolean 属性，用于决定窗口是否在所有工作区中可见。
注意： 在 Windows 上始终返回 false。
\nwin.shadow一个 Boolean 属性，用于决定窗口是否显示阴影。
win.menuBarVisible Windows Linux一个 Boolean 属性，用于决定菜单栏是否可见。
注意： 如果菜单栏自动隐藏，用户仍然可以通过单击 Alt 键来唤出菜单栏。
win.kiosk一个 Boolean 属性，用于决定窗口是否处于kiosk模式。
win.documentEdited macOS一个 Boolean 属性指明窗口文档是否已被编辑。
当设置为 true 时，标题栏的图标将变灰。
win.representedFilename macOS一个 String 属性，用于确定窗口代表的文件的路径名，文件的图标将显示在窗口的标题栏中。
win.title一个 String 属性，用于确定原生窗口的标题。
注意： 网页的标题可以与原生窗口的标题不同。
\nwin.minimizable一个 Boolean 属性，用于决定窗口是否可被用户手动最小化。
在 Linux 上，setter 不会进行任何操作，尽管 getter 返回的是 true。
win.maximizable一个 Boolean 属性，用于决定窗口是否可被用户手动最大化。
在 Linux 上，setter 不会进行任何操作，尽管 getter 返回的是 true。
win.fullScreenable一个 Boolean 属性，决定最大化/缩放窗口按钮是切换全屏模式还是最大化窗口。
win.resizable一个 Boolean 属性，用于决定窗口是否可被用户手动调整大小。
win.closable一个 Boolean 属性，用于决定窗口是否可被用户手动关闭。
在 Linux 上，setter 不会进行任何操作，尽管 getter 返回的是 true。
win.movable一个 Boolean 属性，用于决定窗口是否可被用户移动。
在 Linux 上，setter 不会进行任何操作，尽管 getter 返回的是 true。
win.excludedFromShownWindowsMenu macOS一个 Boolean 属性，用于决定窗口是否从应用程序的 Windows 菜单排除。 默认值为 false
const win = new BrowserWindow({ height: 600, width: 600 })\n\nconst template = [\n {\n role: 'windowmenu'\n }\n]\n\nwin.excludedFromShownWindowsMenu = true\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nwin.accessibleTitle一个 String 属性，定义一个仅为如屏幕阅读器等辅助工具提供的替代标题 。 此字符串不直接对用户可见。
使用 new BrowserWindow 创建的对象具有以下实例方法:
注意: 某些方法仅在特定的操作系统上可用, 这些方法会被标记出来。
\nwin.destroy()强制关闭窗口, 除了closed之外，close，unload 和 beforeunload 都不会被触发
win.close()尝试关闭窗口。 该方法与用户手动单击窗口的关闭按钮效果相同。 但网页可能会取消这个关闭操作。 查看 关闭事件。
\nwin.focus()聚焦于窗口
\nwin.blur()取消窗口的聚焦
\nwin.isFocused()返回 Boolean - 判断窗口是否聚焦
win.isDestroyed()返回 Boolean -判断窗口是否被销毁
win.show()显示并聚焦于窗口
\nwin.showInactive()显示但不聚焦于窗口
\nwin.hide()隐藏窗口
\nwin.isVisible()返回 Boolean - 判断窗口是否可见
win.isModal()返回 Boolean - 判断是否为模态窗口
win.maximize()最大化窗口。 如果窗口尚未显示，该方法也会将其显示 (但不会聚焦)。
\nwin.unmaximize()取消窗口最大化
\nwin.isMaximized()返回 Boolean - 判断窗口是否最大化
win.minimize()最小化窗口。 在某些平台上, 最小化的窗口将显示在Dock中。
\nwin.restore()将窗口从最小化状态恢复到以前的状态。
\nwin.isMinimized()返回 Boolean -判断窗口是否最小化
win.setFullScreen(flag)flag Boolean设置窗口是否应处于全屏模式。
\nwin.isFullScreen()返回 Boolean - 窗口当前是否已全屏
win.setSimpleFullScreen(flag) macOSflag Boolean进入或离开简单的全屏模式。
\n简单全屏模式模拟了 Lion (10.7) 之前的macOS版本中的原生全屏行为。
\nwin.isSimpleFullScreen() macOS返回 Boolean - 窗口是否为简单全屏模式(pre-Lion)。
win.isNormal()返回 Boolean - 窗口是否处于正常状态（未最大化，未最小化，不在全屏模式下）。
win.setAspectRatio(aspectRatio[, extraSize])aspectRatio Float- 为内容视图保持的宽高比.extraSize Size (可选) macOS - 保持宽高比时不包括的额外大小。这将使窗口保持长宽比。 额外的大小允许开发人员有空间 (以像素为单位), 不包括在纵横比计算中。 此 API 已经考虑了窗口大小和内容大小之间的差异。
\n想象一个使用高清视频播放器和相关控件的普通窗口。 假假如左边缘有15px, 右边缘有25px, 在播放器下面有50px. 为了保持播放器本身16:9 的长宽比 (标准的HD长宽比为1920x1080)， 我们可以使用 16/9 和 { width: 40, height: 50 } 的参数调用这个函数。 第二个参数不管网页中的额外的宽度和高度在什么位置, 只要它们存在就行. 在全部内部窗口中，加上任何额外的宽度和高度 。
\nThe aspect ratio is not respected when window is resized programmatically with APIs like win.setSize.
win.setBackgroundColor(backgroundColor)backgroundColor String - 十六进制的窗口背景色，如 #66CD00、#FFF和#80FFFFFF。 (如果transparent是true的话，也支持alpha 通道。) 默认值为 #FFF（白色）。设置窗口的背景颜色。 请参阅 设置背景颜色。
win.previewFile(path[, displayName]) macOSpath String -要用 QuickLook 预览的文件的绝对路径。 这一点很重要，因为Quick Look 使用了路径上的文件名和文件扩展名 来决定要打开的文件的内容类型。displayName String (可选) - 在Quick Look 模态视图中显示的文件的名称。 这完全是视觉的，不会影响文件的内容类型。 默认值为 path.使用 Quick Look来预览路径中的文件.
\nwin.closeFilePreview() macOS关闭当前打开的 Quick Look 面板.
\nwin.setBounds(bounds[, animate])bounds Partial<Rectangle>animate Boolean (可选) macOS重置窗口，并且移动窗口到指定的位置. 任何未提供的属性将默认为其当前值。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\n// 设置所有 bounds 边界属性\nwin.setBounds({ x: 440, y: 225, width: 800, height: 600 })\n\n// 设置单一 bounds 边界属性\nwin.setBounds({ width: 100 })\n\n// { x: 440, y: 225, width: 100, height: 600 }\nconsole.log(win.getBounds())\nwin.getBounds()返回 Rectangle - 窗口的 bounds 作为 Object。
win.getBackgroundColor()返回 String - 获取窗口的背景颜色。 请参阅 设置背景颜色。
win.setContentBounds(bounds[, animate])bounds Rectangleanimate Boolean (可选) macOS调整窗口的工作区 (如网页) 的大小并将其移动到所提供的边界。
\nwin.getContentBounds()返回 Rectangle - 窗口客户端区域的 bounds 对象。
win.getNormalBounds()返回 Rectangle - 包含正常状态下的窗口大小。
注意：无论当前的窗口状态为：最大化、最小化或者全屏，这个方法都将得到窗口在正常显示状态下的位置信息以及大小信息。 在正常状态下，getBounds 与 getNormalBounds 得到的边界信息 Rectangle 是一致的。
win.setEnabled(enable)enable Boolean禁用或者启用窗口。
\nwin.isEnabled()返回 Boolean - 窗口是否启用。
win.setSize(width, height[, animate])width Integerheight Integeranimate Boolean (可选) macOS调整窗口的width和 height. 如果 width 或 height 低于任何设定的最小尺寸约束，窗口将对齐到约束的最小尺寸。
win.getSize()返回 Integer []-包含窗口的宽度和高度。
win.setContentSize(width, height[, animate])width Integerheight Integeranimate Boolean (可选) macOS将窗口的工作区 (如网页) 的大小调整为 width 和 height。
win.getContentSize()返回 Integer []-包含窗口的宽度和高度。
win.setMinimumSize(width, height)width Integerheight Integer设置窗口最小化的 width 和height.
win.getMinimumSize()返回 Integer []-包含窗口最小化的宽度和高度。
win.setMaximumSize(width, height)width Integerheight Integer设置窗口最大化的 width 和 height.
win.getMaximumSize()返回 Integer []-包含窗口最大化的宽度和高度。
win.setResizable(resizable)resizable Boolean设置用户是否可以手动调整窗口大小。
\nwin.isResizable()返回 Boolean - 用户是否可以手动调整窗口大小。
win.setMovable(movable) macOS Windowsmovable Boolean设置用户是否可以移动窗口。 在Linux上不起作用。
\nwin.isMovable() macOS Windows返回 Boolean - 窗口是否可以被用户拖动
在 Linux 上总是返回 true。
win.setMinimizable(minimizable) macOS Windowsminimizable Boolean设置用户是否可以手动将窗口最小化。 在Linux上不起作用。
\nwin.isMinimizable() macOS Windows返回 Boolean - 用户是否可以手动最小化窗口。
在 Linux 上总是返回 true。
win.setMaximizable(maximizable) macOS Windowsmaximizable Boolean设置用户是否可以手动最大化窗口。 在Linux上不起作用。
\nwin.isMaximizable() macOS Windows返回 Boolean - 窗口是否可以最大化.
在 Linux 上总是返回 true。
win.setFullScreenable(fullscreenable)fullscreenable Boolean设置最大化/缩放窗口按钮是切换全屏模式还是最大化窗口。
\nwin.isFullScreenable()返回 Boolean - 最大化/缩放窗口按钮是切换全屏模式还是最大化窗口。
win.setClosable(closable) macOS Windowsclosable Boolean设置用户是否可以手动关闭窗口。 在Linux上不起作用。
\nwin.isClosable() macOS Windows返回 Boolean - 窗口是否可以被用户关闭.
在 Linux 上总是返回 true。
win.setAlwaysOnTop(flag[, level][, relativeLevel])flag Booleanlevel String (可选) macOS Windows - 值包括 normal, floating, torn-off-menu, modal-panel, main-menu, status, pop-up-menu, screen-saver和 dockflag 属性为true时，默认值为 floating 。 当flag为false时，level 会重置为 normal。 请注意，包括从 floating 到 status ，窗口会被置于 macOS 上的 Dock 下方和 Windows 上的任务栏下方。 从 pop-up-menu 到更高级别，窗口显示在 macOS 上的Dock上方和 Windows 上的任务栏上方。 更多信息，请查阅 macOS 文档。relativeLevel Integer (可选) macOS - 设置此窗口相对于给定 级别的层数。. 默认值为0. 请注意, Apple 不鼓励在 屏幕保护程序 之上设置高于1的级别。设置窗口是否应始终显示在其他窗口的前面。 设置后，窗口仍然是一个正常窗口，而不是一个无法获取焦点的工具框窗口。
\nwin.isAlwaysOnTop()返回 Boolean - 当前窗口是否始终在其它窗口之前.
win.moveAbove(mediaSourceId)mediaSourceId String - DesktopCapturerSource格式的窗口 id 。 例如 \"window:1869:0\"。将窗口按z轴顺序移动到源窗口前面。 如果 mediaSourceId 不是window类型，或者如果窗口不存在，则此方法会抛出一个错误。
win.moveTop()无论焦点如何, 将窗口移至顶端(z轴上的顺序).
\nwin.center()将窗口移动到屏幕中央。
\nwin.setPosition(x, y[, animate])x Integery Integeranimate Boolean (可选) macOS将窗口移动到 x 和 y。
win.getPosition()返回 Integer[] - 返回一个包含当前窗口位置的数组.
win.setTitle(title)title String将原生窗口的标题更改为 title。
win.getTitle()返回 String-原生窗口的标题。
注意： 网页的标题可以与原生窗口的标题不同。
\nwin.setSheetOffset(offsetY[, offsetX]) macOSoffsetY FloatoffsetX Float (可选)改变macOS上sheet组件的附着点。 默认情况下，sheet贴在窗口边框正下方，但你可能需要在 HTML 渲染工具栏下方显示它们。 例如：
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nconst toolbarRect = document.getElementById('toolbar').getBoundingClientRect()\nwin.setSheetOffset(toolbarRect.height)\nwin.flashFrame(flag)flag Boolean启动或停止闪烁窗口, 以吸引用户的注意。
\nwin.setSkipTaskbar(skip)skip Boolean使窗口不显示在任务栏中。
\nwin.setKiosk(flag)flag Boolean进入或离开 kiosk 模式。
\nwin.isKiosk()返回 Boolean - 判断窗口是否处于kiosk模式.
win.isTabletMode() Windows返回 Boolean - 无论当前窗口是否处在 Windows 10 平板模式
因为 Windows 10 用户可以 将他们的 PC 作为平板电脑来使用，在此模式下，应用可以选择为平板电脑的界面做出优化，如扩展标题栏和隐藏标题栏按钮。
\n此 API 返回 窗口是否在平板电脑模式下，并且 调整大小 事件可以用于监听对平板模式的更改。
win.getMediaSourceId()返回 String - DesktopCapturerSource的id格式的窗口 id 。 例如 \"window:1324:0\"。
更确切地说，格式是 window:id:other_id。在Windows上 id 是 HWND 类型；在macOS上是 CGWindowID (uint64_t)；在Linux上是 Window (unsigned long)。 other_id 用于识别同一顶层窗口内的Web 内容 (选项卡)。
win.getNativeWindowHandle()返回 Buffer - 窗口的平台特定句柄
Windows上句柄类型为 HWND，macOS 上为 NSView*，Linux 上为Window (unsigned long)
win.hookWindowMessage(message, callback) Windowsmessage Integercallback FunctionwParam any - 提供给 WndProc的 wParam 值。lParam any - 提供给 WndProc的 lParam 值。钩住窗口消息。 当消息到达 WndProc 时调用callback 。
win.isWindowMessageHooked(message) Windowsmessage Integer返回 Boolean - true 或false ，具体取决于是否钩挂了消息.
win.unhookWindowMessage(message) Windowsmessage Integer取消窗口信息的钩子。
\nwin.unhookAllWindowMessages() Windows取消所有窗口信息的钩子。
\nwin.setRepresentedFilename(filename) macOSfilename String设置窗口所代表的文件的路径名，并且将这个文件的图标放在窗口标题栏上。
\nwin.getRepresentedFilename() macOS返回 String - 获取窗口当前文件路径.
win.setDocumentEdited(edited) macOSedited Boolean明确指出窗口文档是否可以编辑, 如果设置为true则将标题栏的图标变成灰色.
win.isDocumentEdited() macOS返回 Boolean - 判断当前窗口文档是否可编辑.
win.focusOnWebView()win.blurWebView()win.capturePage([rect])rect Rectangle (可选) - 捕获的区域返回 Promise<NativeImage> - 完成后返回一个NativeImage
在 rect内捕获页面的快照。 省略 rect 将捕获整个可见页面。 如果页面不可见， rect 可能是空的。
win.loadURL(url[, options])url Stringoptions Object (可选)httpReferrer (String | Referrer) (可选) - HTTP 引用 url。userAgent String (可选) - 发起请求的 userAgent.extraHeaders String (可选) - 用 \"\\n\" 分割的额外标题postData (UploadRawData | UploadFile)baseURLForDataURL String (可选) - 要由数据URL加载的文件基本URL(末尾带有路径分隔符)。 仅当指定的url是数据url并且需要加载其他文件时，才需要此选项。返回 Promise<void> - 当页面完成加载后 promise 将会resolve (见 did-finish-load)，如果页面加载失败，则 reject (见 did-fail-load)。
与 webContents.loadURL(url[, options]) 相同。
url 可以是远程地址 (例如 http://),也可以是 file:// 协议的本地HTML文件的路径.
为了确保文件网址格式正确, 建议使用Node的 url.format 方法:
const url = require('url').format({\n protocol: 'file',\n slashes: true,\n pathname: require('path').join(__dirname, 'index.html')\n})\n\nwin.loadURL(url)\n您可以通过执行以下操作, 使用带有网址编码数据的 POST请求加载网址:
win.loadURL('http://localhost:8000/post', {\n postData: [{\n type: 'rawData',\n bytes: Buffer.from('hello=world')\n }],\n extraHeaders: 'Content-Type: application/x-www-form-urlencoded'\n})\nwin.loadFile(filePath[, options])filePath Stringoptions Object (可选)query Record<String, String> (可选) - 传递给 url.format().search String (可选) - 传递给 url.format().hash String (可选) - 传递给 url.format().返回 Promise<void> - 当页面完成加载后 promise 将会resolve (见 did-finish-load)，如果页面加载失败，则 reject (见 did-fail-load)。
与 webContents.loadFile相同， filePath 应该是一个与你的应用程序的根路径相关的HTML文件路径。 有关更多信息，请参阅webContents 文档。
win.reload()与 webContents.reload 相同.
win.setMenu(menu) Linux Windowsmenu Menu | null将 menu 设置为窗口的菜单栏。
win.removeMenu() Linux Windows删除窗口的菜单栏。
\nwin.setProgressBar(progress[, options])progress Doubleoptions Object (可选)mode String Windows - 进度条的状态。 可以是 none， normal， indeterminate， error 或 paused。设置进度条的进度值。 有效范围为 [0, 1.0]。
\n当进度小于0时不显示进度; 当进度大于0时显示结果不确定.
\n在 Linux 平台上，只支持 Unity 桌面模式, 你需要在 package.json 中为 desktopName 指定 *.desktop 的文件名. 默认情况下，将取 {app.name}.desktop。
在 Windows 上, 可以传递模式。 可以接受的值为none, normal, indeterminate, error和 paused. 如果没有设置模式 (但值在有效范围内) 的情况下调用 setProgressBar, 默认值为normal。
win.setOverlayIcon(overlay, description) Windowsoverlay NativeImage | null - 右下角任务栏的显示图标。 如果此参数是 null，覆盖层层会被清除。description String -提供给屏幕阅读器的描述文字在当前任务栏图标上设置一个 16 x 16 像素的图标, 通常用于传达某种应用程序状态或被动地通知用户。
\nwin.setHasShadow(hasShadow)hasShadow Boolean设置窗口是否有阴影。
\nwin.hasShadow()返回 Boolean - 判断窗口是否有阴影.
win.setOpacity(opacity) Windows macOSopacity Number - 介于0.0 ( 完全透明 ) 和1.0 ( 完全不透明 ) 之间设置窗口的不透明度。 在Linux上不起作用。 超出界限的数值被限制在[0, 1] 范围内。
\nwin.getOpacity()返回 Number - 介于0.0 (完全透明) 和1.0 (完全不透明) 之间。 在Linux上，始终返回1。
win.setShape(rects) Windows Linux 实验性rects Rectangle[] - 在窗口上设置形状。 通过传入空列表将窗口恢复为矩形。对窗口形状的设置决定了窗口内系统允许绘制与用户交互的区域. 在给定的区域外, 没有像素会被绘制, 且没有鼠标事件会被登记. 在该区域外的鼠标事件将不会被该窗口接收, 而是落至该窗口后方的任意窗口.
\nwin.setThumbarButtons(buttons) Windowsbuttons ThumbarButton[]返回 Boolean - 按钮是否成功添加
将指定的一组按钮添加到菜单栏的缩图工具栏上。 返回一个 Boolean 对象表示是否成功地添加了缩略图.
由于空间有限, 缩图工具栏中的按钮数量不要超过7个。 一旦设置了缩略图工具栏，则无法删除。 但你可以通过调用 API 传递一个空数组来清除按钮.
\nbuttons 是一个 Button 对象的数组:
Button Objecticon NativeImage - 在缩图工具栏上显示的图标.click Functiontooltip String (可选) - 按钮的提示文本.flags String - 控制按钮的特定状态和行为。 默认情况下，值为 ['enabled']。flags 属性是一个数组，包含以下String类型的值:
enabled - 该按钮处于活动状态并可供用户使用.disabled - 按钮已禁用。 会以一种视觉状态表示它不会响应用户操作的形式显示。dismissonclick - 当按钮被点击时，缩略图窗口立即关闭。nobackground - 仅仅使用图像而不绘制边框。hidden - 该按钮对用户不可见。noninteractive - 按钮已启用，但不交互；不绘制按钮按下的状态。 此值用于在通知中使用按钮的实例。win.setThumbnailClip(region) Windowsregion Rectangle 窗口的区域将窗口的区域设置为在任务栏中悬停在窗口上方时显示的缩略图图像。 通过指定空区域：{ x: 0, y: 0, width: 0, height: 0 }，可以重置整个窗口的缩略图。
win.setThumbnailToolTip(toolTip) WindowstoolTip String设置在任务栏中悬停在窗口缩略图上时显示的工具提示。
\nwin.setAppDetails(options) Windows选项 对象appId String (可选) - 窗口的 App User Model ID. 该项必须设置, 否则其他选项将没有效果.appIconPath String (可选) -窗口的 Relaunch Icon.appIconIndex Integer (可选) - appIconPath中的图标索引。 未设置 appIconPath 时忽略。 默认值为 0.relaunchCommand String (可选) - 窗口的 重新启动命令.relaunchDisplayName String (可选) - 窗口的重新启动显示名称.设置窗口任务栏按钮的属性。
\n注意：必须始终同时设置 relaunchCommand 和 relaunchDisplayName。 如果其中一个属性没有设置，那么这两个属性都不会使用。
win.showDefinitionForSelection() macOS和 webContents.showDefinitionForSelection() 相同.
win.setIcon(icon) Windows Linuxicon NativeImage | String设置窗口图标
\nwin.setWindowButtonVisibility(visible) macOSvisible Boolean设置是否窗口交通灯需要显示。
\nwin.setAutoHideMenuBar(hide)hide Boolean设置窗口菜单栏是否自动隐藏。 一旦设置，菜单栏将只在用户单击 Alt 键时显示。
如果菜单栏已经可见, 调用 setAutoHideMenuBar(true)时不会立刻隐藏。
win.isMenuBarAutoHide()返回 Boolean - 判断窗口的菜单栏是否自动隐藏.
win.setMenuBarVisibility(visible) Windows Linuxvisible Boolean设置菜单栏是否可见。 如果菜单栏自动隐藏，用户仍然可以通过单击 Alt 键来唤出菜单栏。
win.isMenuBarVisible()返回 Boolean - 判断窗口的菜单栏是否可见.
win.setVisibleOnAllWorkspaces(visible[, options])visible Booleanoptions Object (可选)visibleOnFullScreen Boolean (可选) macOS - 设置当前窗口是否可以在全屏窗口之上显示。skipTransformProcessType Boolean (可选) macOS - 调用 setVisibleOnAllWorkspaces ，默认转换流程类型于 UIElementApplication 和 ForegroundApplication 之间，用来保障正常响应。 然而，当方法被调用时将短暂的隐藏窗口和图标。 如果你的窗口已经是 UIElementApplication 类似，你可以绕过这次转换通过传递 true 参数给TransformProcessType。设置窗口是否在所有工作空间上可见
\n注意: 该 API 在 Windows 上无效.
\nwin.isVisibleOnAllWorkspaces()返回 Boolean - 判断窗口是否在所有工作空间上可见.
注意: 该 API 在 Windows 上始终返回 false.
\nwin.setIgnoreMouseEvents(ignore[, options])ignore Booleanoptions Object (可选)forward Boolean (可选) macOS Windows - 如果为 true, 传递鼠标移动消息给 Chromium，鼠标相关事件将可用，如 mouseleave。 仅当 ignore </ 0>为 true 时才被使用。 如果 <code>ignore 为 false, 转发始终是禁用的，不管这个值是什么。忽略窗口内的所有鼠标事件
\n在此窗口中发生的所有鼠标事件将被传递到此窗口下面的窗口, 但如果此窗口具有焦点, 它仍然会接收键盘事件
\nwin.setContentProtection(enable) macOS Windowsenable Boolean防止窗口内容被其他应用捕获
\n在 macOS 上，它将 NSWindow 的 sharingType 设置为 NSWindowSharingNone。 在 Windows 上，它以参数为 WDA_EXCLUDEFROMCAPTURE 调用 SetWindowDisplayAffinity 。 对于 Windows 10 2004以上版，本窗口将完全从抓取中移除，在低版本 Windows 上其行为就像是 WDA_MONITOR 捕捉了黑色窗口。
win.setFocusable(focusable) macOS Windowsfocusable Boolean设置窗口是否可聚焦
\n在 macOS 上，该方法不会从窗口中移除焦点。
\nwin.isFocusable() macOS WindowsReturns whether the window can be focused.
\nwin.setParentWindow(parent)parent BrowserWindow | null设置 parent 为当前窗口的父窗口. 为null时表示将当前窗口转为顶级窗口
win.getParentWindow()返回 BrowserWindow - 父窗口.
win.getChildWindows()返回 BrowserWindow[] - 首页的子窗口.
win.setAutoHideCursor(autoHide) macOSautoHide Boolean设置输入时是否隐藏光标
\nwin.selectPreviousTab() macOS当启用本地选项卡，并且窗口中有另一个标签时，选择上一个选项卡。
\nwin.selectNextTab() macOS当启用本地选项卡，并且窗口中有另一个标签时，选择下一个选项卡。
\nwin.mergeAllWindows() macOS当启用本地选项卡并且存在多个打开窗口时，将所有窗口合并到一个带有多个选项卡的窗口中。
\nwin.moveTabToNewWindow() macOS如果启用了本机选项卡并且当前窗口中有多个选项卡，则将当前选项卡移动到新窗口中。
\nwin.toggleTabBar() macOS如果启用了本机选项卡并且当前窗口中只有一个选项卡，则切换选项卡栏是否可见。
\nwin.addTabbedWindow(browserWindow) macOSbrowserWindow BrowserWindow在该窗口中添加一个窗口作为选项卡，位于窗口实例的选项卡之后。
\nwin.setVibrancy(type) macOStype String | null - 可以是 appearance-based，light，dark，titlebar，selection，menu，popover，sidebar，medium-light，ultra-dark，header，sheet，window，hud，fullscreen-ui，tooltip，content，under-window 或 under-page。 更多详细信息，请查阅 macOS documentation在浏览器窗口中添加一个动态特效。 传递 null 或空字符串将会移除窗口上的动态效果。
请注意， appearance-based，light，dark，medium-light 和 ultra-dark 已被弃用，并将在即将推出的 macOS 版本中被移除。
win.setTrafficLightPosition(position) macOSposition Point在无框窗口中设置自定义控制按钮的位置。
\nwin.getTrafficLightPosition() macOS返回 Point - 在无框窗口中自定义控制按钮的位置。
win.setTouchBar(touchBar) macOStouchBar TouchBar | null设置窗口的触摸条布局 设置为 null 或undefined将清除触摸条. 此方法只有在macOS 10.12.1+且设备支持触摸条TouchBar时可用.
注意: TouchBar API目前为实验性质，可能会更改或删除。
\nwin.setBrowserView(browserView) 实验browserView BrowserView | null - 将 browserView 附加到 win。 如果已经附加了其他 BrowserView，那么它们将会被从此窗口中移除。win.getBrowserView() 实验功能返回 BrowserView | null - 附加到 win 的 BrowserView 。 如果未附加，则返回 null。 如果附加了多个 BrowserView，则抛出错误。
win.addBrowserView(browserView) 实验功能browserView BrowserView替代 setBrowserView 的API，支持多个browserView一起使用。
\nwin.removeBrowserView(browserView) 实验功能browserView BrowserViewwin.setTopBrowserView(browserView) 实验功能browserView BrowserView提高 browserView 于其它附加到 win 的 BrowserView 之上 。 如果 browserView 未附加到 win，则抛出错误。
win.getBrowserViews() 实验功能返回 BrowserView[] - 所有通过 addBrowserView 或 setBrowserView 附加的BrowserView数组。
注意: BrowserView 的 API目前为实验性质，可能会更改或删除。
", "title": "BrowserWindow", "description": "创建并控制浏览器窗口。" }, "/docs/api/browser-window-proxy": { "locale": "zh-CN", "slug": "browser-window-proxy", "href": "/docs/api/browser-window-proxy", "crowdinFileId": "256285", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-window-proxy.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n操纵子浏览器窗口
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
使用 window.open 创建一个新窗口时会返回一个 BrowserWindowProxy对象，并提供一个有限功能的子窗口.
BrowserWindowProxy 对象具有以下实例方法:
win.blur()将焦点从子窗口中移除.
\nwin.close()不调用卸载事件，便关闭了子窗口。
\nwin.eval(code)code StringEval子窗口中的代码
\nwin.focus()聚焦子窗口(即窗口置顶)
\nwin.print()调用子窗口上的打印对话框
\nwin.postMessage(message, targetOrigin)message anytargetOrigin String调通过指定位置或用*来代替不明位置，向子窗口发送信息
除了这些方法,子窗口还可以无特性和使用单一方法来实现 window.opener 对象.
BrowserWindowProxy 对象具有以下实例属性:
win.closed在子窗口关闭后设置为 true 的 Boolean。
按照下面的步骤构建 Electron，来生成自定义的 Electron 二进制文件。 为了将您的应用代码与预构建的 Electron 二进制文件打包并发布，请参阅 应用程序发布 指南。
\n各个平台所对应的构建要求如下：
\n\nElectron的构建工具 自动化了很多配置不同的从源代码编译Electron的设置和构建目标。 如果您希望手动设置环境，则说明如下。
\n此外，你还需要安装depot_tools，这是一个用于获取Chromium，及其相关依赖工具。
另外，如果使用Windows系统, 你需要设置环境变量DEPOT_TOOLS_WIN_TOOLCHAIN=0。 依次打开 Control Panel → System and Security → System → Advanced system settings ，然后添加系统变量 DEPOT_TOOLS_WIN_TOOLCHAIN ，并设置默认值为 0. 这将促使depot_tools 使用本地已安装的Visual Studio(默认状态下，depot_tools将会下载一个只有谷歌内部员工有权限使用的内部版本)。
如果您想 checkout 多份 Electron 源码 (例如多个并行目录 checkout 到不同的分支)， 推荐使用 git 缓存来加速后续对 gclient的调用。 为此，设置 GIT_CACHE_PATH 环境变量：
$ export GIT_CACHE_PATH=\"${HOME}/.git_cache\"\n$ mkdir -p \"${GIT_CACHE_PATH}\"\n# 这将使用大约16G\n$ mkdir electron && cd electron\n$ gclient config --name \"src/electron\" --unmanaged https://github.com/electron/electron\n$ gclient sync --with_branch_heads --with_tags\n# 这将需要一段时间，喝杯咖啡休息一下。\n\n\n除了使用
\nhttps://github.com/electron/electron， 你也可以使用你自己的 fork (形如https://github.com/<username>/electron)。
如果您将来打算从 electron 官方地址进行 git pull 或 git push，那么您需要更新相应文件夹的源 URL。
$ cd src/electron\n$ git remote remove origin\n$ git remote add origin https://github.com/electron/electron\n$ git checkout main\n$ git branch --set-upstream-to=origin/main\n$ cd -\n📝 gclient 会检查 src/electron 目录下的 DEPS 文件，从中获取依赖信息 (就像 Chromium 或 Node.js 那样)。 运行 gclient sync -f 确保所有用来构建 Electron 的依赖都符合该文件的描述。
因此，为了拉取，您将运行以下命令：
\n$ cd src/electron\n$ git pull\n$ gclient sync -f\n$ cd src\n$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\n若在 Windows 上 (没有可选参数)：
\n$ cd src\n$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\\buildtools\n$ gn out/testing --args=\"import(\\\"//electron/build/args/testing.gn\\\")\n这将在src/下的out/Testing内生成一个有测试生成配置的文件夹 您可以用另一个名称 替换 Testing ，但它应该是 out 的子目录。 Also you shouldn't have to run gn gen again—if you want to change the build arguments, you can run gn args out/Testing to bring up an editor.
要查看可用的构建配置选项的列表，运行 gn args out/Testing--list。
用于生成测试Electron的构建配置：
\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nFor generating Release (aka \"non-component\" or \"static\") build config of Electron:
\n$ gn gen out/Release --args=\"import(\\\"//electron/build/args/release.gn\\\") $GN_EXTRA_ARGS\"\nTo build, run ninja with the electron target: Nota Bene: This will also take a while and probably heat up your lap.
测试配置：
\n$ ninja -C out/Testing electron\n发布配置：
\n$ ninja -C out/Release electron\nThis will build all of what was previously 'libchromiumcontent' (i.e. the content/ directory of chromium and its dependencies, incl. WebKit and V8), so it will take a while.
构建需要在./out/Testing文件下执行：
$ ./out/Testing/Electron.app/Contents/MacOS/Electron\n# or, on Windows\n$ ./out/Testing/electron.exe\n# or, on Linux\n$ ./out/Testing/electron\nOn linux, first strip the debugging and symbol information:
\nelectron/script/strip-binaries.py -d out/Release\nTo package the electron build as a distributable zip file:
\nninja -C out/Release electron:electron_dist_zip\nTo compile for a platform that isn't the same as the one you're building on, set the target_cpu and target_os GN arguments. For example, to compile an x86 target from an x64 host, specify target_cpu = \"x86\" in gn args.
$ gn gen out/Testing-x86 --args='... target_cpu = \"x86\"'\nNot all combinations of source and target CPU/OS are supported by Chromium.
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Host | 目标 | 状态 |
|---|---|---|
| Windows x64 | Windows arm64 | 实验性功能 |
| Windows x64 | Windows x86 | Automatically tested |
| Linux x64 | Linux x86 | Automatically tested |
If you test other combinations and find them to work, please update this document :)
\n有关 target_os 和 target_cpu 的有效值，请查看参考 GN。
To cross-compile for Windows on Arm, follow Chromium's guide to get the necessary dependencies, SDK and libraries, then build with ELECTRON_BUILDING_WOA=1 in your environment before running gclient sync.
set ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nOr (if using PowerShell):
\n$env:ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nNext, run gn gen as above with target_cpu=\"arm64\".
To run the tests, you'll first need to build the test modules against the same version of Node.js that was built as part of the build process. To generate build headers for the modules to compile against, run the following under src/ directory.
$ ninja -C out/Testing third_party/electron_node:headers\nYou can now run the tests.
\n可以通过增加其它标记来调试程序，例如：
\n$ npm run test -- \\\n --enable-logging -g 'BrowserWindow module'\n可以将gclient git 缓存与其他机器共享，导出为 SMB 在linux上共享。 但每次只能有一个进程或机器可以使用缓存。 The locks created by git-cache script will try to prevent this, but it may not work perfectly in a network.
\nOn Windows, SMBv2 has a directory cache that will cause problems with the git cache script, so it is necessary to disable it by setting the registry key
\nHKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\\DirectoryCacheLifetime\nto 0. 更多信息：https://stackoverflow.com/a/9935126
\nThis can be set quickly in powershell (ran as administrator):
\nNew-ItemProperty -Path \"HKLM:\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force\nIf gclient sync is interrupted the git tree may be left in a bad state, leading to a cryptic message when running gclient sync in the future:
2> Conflict while rebasing this branch.\n2> Fix the conflict and run gclient again.\n2> See man git-rebase for details.\nIf there are no git conflicts or rebases in src/electron, you may need to abort a git am in src:
$ cd ../\n$ git am --abort\n$ cd electron\n$ gclient sync -f\nIf you see a prompt for Username for 'https://chrome-internal.googlesource.com': when running gclient sync on Windows, it's probably because the DEPOT_TOOLS_WIN_TOOLCHAIN environment variable is not set to 0. Open Control Panel → System and Security → System → Advanced system settings and add a system variable DEPOT_TOOLS_WIN_TOOLCHAIN with value 0. 这将促使depot_tools 使用本地已安装的Visual Studio(默认状态下，depot_tools将会下载一个只有谷歌内部员工有权限使用的内部版本)。
Follow the guidelines below for building Electron itself on Linux, for the purposes of creating custom Electron binaries. 为了将您的应用代码与预构建的 Electron 二进制文件打包并发布，请参阅 应用程序发布 指南。
\nAt least 25GB disk space and 8GB RAM.
\nPython 2.7.x. Some distributions like CentOS 6.x still use Python 2.6.x so you may need to check your Python version with python -V.
Please also ensure that your system and Python version support at least TLS 1.2. For a quick test, run the following script:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, use your system's package manager to update Python to the latest version in the 2.7.x branch. Alternatively, visit https://www.python.org/downloads/ for detailed instructions.
\nNode.js. There are various ways to install Node. You can download source code from nodejs.org and compile it. Doing so permits installing Node on your own home directory as a standard user. Or try repositories such as NodeSource.
\nclang 3.4 or later.
\nDevelopment headers of GTK 3 and libnotify.
\nOn Ubuntu, install the following libraries:
\n$ sudo apt-get install build-essential clang libdbus-1-dev libgtk-3-dev \\\n libnotify-dev libgnome-keyring-dev \\\n libasound2-dev libcap-dev libcups2-dev libxtst-dev \\\n libxss1 libnss3-dev gcc-multilib g++-multilib curl \\\n gperf bison python-dbusmock openjdk-8-jre\nOn RHEL / CentOS, install the following libraries:
\n$ sudo yum install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Fedora, install the following libraries:
\n$ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Arch Linux / Manjaro, install the following libraries:
\n$ sudo pacman -Syu base-devel clang libdbus gtk2 libnotify \\\n libgnome-keyring alsa-lib libcap libcups libxtst \\\n libxss nss gcc-multilib curl gperf bison \\\n python2 python-dbusmock jdk8-openjdk\nOther distributions may offer similar packages for installation via package managers such as pacman. Or one can compile from source code.
\nIf you want to build for an arm target you should also install the following dependencies:
$ sudo apt-get install libc6-dev-armhf-cross linux-libc-dev-armhf-cross \\\n g++-arm-linux-gnueabihf\nSimilarly for arm64, install the following:
$ sudo apt-get install libc6-dev-arm64-cross linux-libc-dev-arm64-cross \\\n g++-aarch64-linux-gnu\nAnd to cross-compile for arm or ia32 targets, you should pass the target_cpu parameter to gn gen:
$ gn gen out/Testing --args='import(...) target_cpu=\"arm\"'\nPrebuilt clang will try to link to libtinfo.so.5. Depending on the host architecture, symlink to appropriate libncurses:
$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5\nThe default building configuration is targeted for major desktop Linux distributions. To build for a specific distribution or device, the following information may help you.
\nclang instead of downloaded clang binariesBy default Electron is built with prebuilt clang binaries provided by the Chromium project. If for some reason you want to build with the clang installed in your system, you can specify the clang_base_path argument in the GN args.
For example if you installed clang under /usr/local/bin/clang:
$ gn gen out/Testing --args='import(\"//electron/build/args/testing.gn\") clang_base_path = \"/usr/local/bin\"'\nclangBuilding Electron with compilers other than clang is not supported.
请按照下面的指南在macOS下构建 Electron 本身，以此创建自定义 Electron 二进制文件。 为了将您的应用代码与预构建的 Electron 二进制文件打包并发布，请参阅 应用程序发布 指南。
\nPlease also ensure that your system and Python version support at least TLS 1.2. 这取决于您的 macOS 和 Python 的版本。 对于快速测试，请运行：
\n$ npx @electron/check-python-tls\n如果以上命令的结果显示您正在使用过期的安全协议，您可以把macOS系统更新至High Sierra版，或者安装一个新的2.7.x版的Python。 您可以使用Homebrew来更新Python版本：
\n$ brew install python@2 && brew link python@2 --force\n如果你已经在使用Homebrew来管理Python，那你也需要安装以下Python模块：
\n您可以使用 pip 安装它：
$ pip install pyobjc\n如果你已经在开发Electron项目，而且没有重新分发Electron构建文件的计划，那你可以忽略下面内容。
\n官方 Electron 构建于Xcode 12.2.1, 和 MacOS 11.0 SDK. 可以使用新的SDK来构建，但是当前使用的Release版本是 11.0 SDK
\n按照下面的指南在Windows下构建 Electron 本身，以此创建自定义 Electron 二进制文件。 为了将您的应用代码与预构建的 Electron 二进制文件打包并发布，请参阅 应用程序发布 指南。
\nvs2019_install = DRIVE:\\path\\to\\Microsoft Visual Studio\\2019\\Community，用您当前已安装版本替换2019和Community以及用您当前安装Visual Studio的驱动器号替换DRIVE: 一般情况下将会是C:。WINDOWSSDKDIR = DRIVE:\\path\\to\\Windows Kits\\10, replacing DRIVE: with the drive that Windows Kits is on. 一般情况下将会是C:。symstore.exe is used for creating a symbol store from .pdb files.Modify → Individual Components, scroll down and select the appropriate Windows SDK to install. 另一个选择是查看 windows SDK 和仿真器存档 并分别下载 SDK 的独立版本。控制面板→程序→程序和功能→选择“Windows 软件开发工具包”→ 更改→更改→选中“Windows 调试工具”→更改。 或者，您可以下载独立的 SDK 安装程序，并且使用它安装调试工具。如果您当前没有安装 Windows， dev.microsoftedge.com 上有时间限制的 Windows 版本，你可以用来构建 Electron。
\n构建 Electron 完全由命令行脚本完成，无法通过 Visual Studio 完成。 您可以使用任何编辑器开发 Electron，但将来将会使用 Visual Studio 构建支持。
\n注意: 即使 Visual Studio 不用于构建，但是仍然需要，因为我们需要它提供的构建工具链。
\nWindows Security 不支持Chromium 源码中部分代码，详情(see https://crbug.com/441184). 此行为将会导致windows系统会删除Chromium里的危险文件从而导致 gclient sync Bug. 通过following these instructions你可以在Windows Security中排除这一行为。
为了构建 32bit 版本，您需要通过 target_cpu = “x86\" 作为 GN 参数。 可以使用不同的 GN 输出目录（例如， out/Release-x86） 和不同的参数，在 64 位目标旁边构建 32 位目标。
$ gn gen out/Release-x86 --args=\"import(\\\"//electron/build/args/release.gn\\\") target_cpu=\\\"x86\\\"\"\n其他构建步骤完全一样。
\n要生成 Visual Studio 项目，可以传递 --ide=vs2017 参数 给 gn gen：
$ gn gen out/Testing --ide=vs2017\n如果你遇到了一个错误，类似 Command xxxx not found, 可以尝试使用 VS2015 Command Prompt 控制台来执行构建脚本.
确保你已经安装了 Visual Studio 的最新安装包.
\n重新安装 32位的 Node.js.
\n创建那个目录 应该可以解决问题:
\n$ mkdir ~\\AppData\\Roaming\\npm\n如果你使用 Git Bash 来构建，或许会遇到这个错误，可以使用 PowerShell 或 VS2015 Command Prompt 来代替.
\nnode.js 有一些 极长的路径名，默认情况下，windows 上的 git 不能正确处理长路径名（即使 windows 支持它们）。 这应该可以修复它：
\n$ git config --system core.longpaths true\nThis can happen during build, when Debugging Tools for Windows has been installed with Windows Driver Kit. Uninstall Windows Driver Kit and install Debugging Tools with steps described above.
\n确保已使用 pip install pywin32 安装了 pywin32。
这个bug 是 Windows 命令提示符的一个\"功能\" It happens when clicking inside the prompt window with QuickEdit enabled and is intended to allow selecting and copying output text easily. 由于每次意外点击都会暂停构建过程，您可能需要在命令的属性中禁用此 功能。
Electron 使用 GN 生成项目，并用 Ninja 完成构建。 项目配置位于 .gn 和 .gni 文件中。
The following gn files contain the main rules for building Electron:
BUILD.gn 指明了如何构建 Electron，还包括与 Chromium 相关的默认配置。build/args/{debug,release,all}.gn 包含 Electron 的默认构建参数。由于 Chromium 项目及其庞大，最终的链接阶段往往需要数分钟，加大了开发难度。 为此，Chromium 采用了“分块构建”方式，将每个模块作为单独的动态库构建，虽然影响了文件大小和性能，但加快了链接速度，
\nElectron 也继承了 Chromium 这一构建方式。 在 Debug 模式下构建时，程序将与 Chromium 的动态库链接，以加快链接速度；而 Release 模式下程序则会与静态库链接，以优化程序大小和性能。
注意：_此内容已经过时，部分信息对于使用 GN 构建的 Electron 已不再适用。
\n使用以下方式测试你的修改符合项目编码风格：
\n$ npm run lint\n测试功能使用：
\n$ npm test\n每当您更改Electron源代码时，都需要在测试之前重新运行构建：
\n$ npm run build && npm test\n你可以通过分离特定的测试来让测试套件运行速度更快或阻止你目前正在使用摩卡的 独占性测试功能. 追加 .only 到任何 describe 或 it 函数调用：
describe.only('some feature', () => {\n // ... only tests in this block will be run\n})\n或者，您可以使用 mocha 的 grep 选项来只运行与给定正则表达式模式匹配的测试
$ npm test -- --grep child_process\n包含本地模块(例如runas)的测试无法在调试版本中执行 (查看 #2558 获取详情), 但它们将与发行版本一起使用。
要使用发行构建来运行测试：
\n$ npm test -- -R\ndata String - PEM encoded dataissuer CertificatePrincipal - Issuer principalissuerName String - Issuer's Common NameissuerCert Certificate - Issuer certificate (if not self-signed)subject CertificatePrincipal - Subject principalsubjectName String - Subject's Common NameserialNumber String - Hex value represented stringvalidStart Number - Start date of the certificate being valid in secondsvalidExpiry Number - End date of the certificate being valid in secondsfingerprint String - Fingerprint of the certificatecommonName String - Common Name.organizations String[] - Organization names.organizationUnits String[] - Organization Unit names.locality String - Locality.state String - State or province.country String - Country or region.\n\n学习以及了解 Chromium 开发进展的相关资源
\n
参阅 V8 开发
", "title": "Chromium 开发", "description": "学习以及了解 Chromium 开发进展的相关资源" }, "/docs/development/clang-format": { "locale": "zh-CN", "slug": "clang-format", "href": "/docs/development/clang-format", "crowdinFileId": "256143", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/clang-format.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "clang-format是一个自动格式化 C/C++/Objective-C 代码的工具, 可以让开发人员不需要担心代码审查期间的样式问题.
强烈建议在发起请求之前格式化已更改的 C++ 代码，这将节省您和审阅者的时间.
\n你可以通过 npm install -g clang-format 安装 clang-format 和 git-clang-format.
To automatically format a file according to Electron C++ code style, run clang-format -i path/to/electron/file.cc. It should work on macOS/Linux/Windows.
格式化已更改代码的工作流:
\ngit add your_changed_file.cc.git-clang-format, 然后你将可能会看到修改后的 your_changed_file.cc, 这些修改是从 clang-format 生成的.git add your_changed_file.cc, 并提交你的修改.If you want to format the changed code on your latest git commit (HEAD), you can run git-clang-format HEAD~1. See git-clang-format -h for more details.
You can also integrate clang-format directly into your favorite editors. For further guidance on setting up editor integration, see these pages:
叮当 是自动检查 C/C++/Objective-C 代码的样式冲突、编程 错误和最佳实践的工具。
Electron's clang-tidy integration is provided as a linter script which can be run with npm run lint:clang-tidy. While clang-tidy checks your on-disk files, you need to have built Electron so that it knows which compiler flags were used. There is one required option for the script --output-dir, which tells the script which build directory to pull the compilation information from. A typical usage would be: npm run lint:clang-tidy --out-dir ../out/Testing
With no filenames provided, all C/C++/Objective-C files will be checked. 您可以提供要检查的文件列表，在 选项后通过文件名： npm 运行行：clang-tidy --out-dir 。 /out/测试shell/browser/api/electron_api_app.cc
While clang-tidy has a long list of possible checks, in Electron only a few are enabled by default. At the moment Electron doesn't have a .clang-tidy config, so clang-tidy will find the one from Chromium at src/.clang-tidy and use the checks which Chromium has enabled. You can change which checks are run by using the --checks= option. This is passed straight through to clang-tidy, so see its documentation for full details. Wildcards can be used, and checks can be disabled by prefixing a -. By default any checks listed are added to those in .clang-tidy, so if you'd like to limit the checks to specific ones you should first exclude all checks then add back what you want, like --checks=-*,performance*.
Running clang-tidy is rather slow - internally it compiles each file and then runs the checks so it will always be some factor slower than compilation. While you can use parallel runs to speed it up using the --jobs|-j option, clang-tidy also uses a lot of memory during its checks, so it can easily run into out-of-memory errors. As such the default number of jobs is one.
\n\n发起HTTP/HTTPS请求.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
ClientRequest实现了Writable Stream接口, 因此是一个EventEmitter类型.
new ClientRequest(options)options (Object | String) - 如果 options 是字符串，则将其解释为请求 URL。 如果是对象，它应该通过以下属性完全指定HTTP请求：method String (可选) - HTTP 请求方法。 默认为GET方法。url String (可选) - 请求URL。 必须以绝对路径形式提供，并将协议指定为http或https。session Object (可选) - 与请求相关联的Session实例.partition String (可选) - 与请求相关联的partition名称. 默认为空字符串. session 选项取代了 partition。 因此, 如果session是显式指定的, 则partition将被忽略.credentials String (可选) - 可以是 include 或 omit。 是否随此请求发送 凭据。 如果设置为 include，将使用与请求相关的会话凭据。 如果设置为 omit，则不会随请求发送凭据(并且不会在 401响应的事件中触发 'login' 事件)。 这与同名的 fetch 选项的行为相同。 如果未指定此选项，则会发送来自会话的身份验证数据，同时不发送cookie(除非 设置了useSessionCookies)。useSessionCookies Boolean (可选) - 是否从提供的会话与请求一起发送cookie。 如果指定了 credentials ，则此选项没有效果。 默认值为 false.protocol String (可选) - 可以是 http: 或 https:。 协议方案的形式为“scheme:”。 默认为 'http:'。host String (可选) - 作为连接提供的服务器主机,主机名和端口号'hostname:port'.hostname String (可选) - 服务器主机名.port Integer (可选) - 服务器侦听的端口号.path String (可选) - 请求URL的路径部分.redirect String (可选) - 可以是 follow， error 或 manual。 当前请求的重定向模式。 当模式为 error 时，任何重定向都会被中止。 当模式为 manual 时，重定向会被取消，除非 request.followRedirect 在redirect 事件期间同步调用。 默认值为 follow.origin String (可选) - 请求的源 URL。options 属性，如 protocol, host, hostname, port 和 path，在 URL 模块中会严格遵循 Node.js 的模式
例如,我们可以创建与github.com相同的请求如下:
\nconst request = net.request({\n method: 'GET',\n protocol: 'https:',\n hostname: 'github.com',\n port: 443,\n path: '/'\n})\n返回:
\nresponse 收到的消息 - 表示HTTP响应消息的对象。返回:
\nauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (可选)password String (可选)当身份验证代理请求用户认证时触发
\n用户证书会调用 callback方法:
username Stringpassword Stringrequest.on('login', (authInfo, callback) => {\n callback('username', 'password')\n})\n提供空的凭证将取消请求，并在响应对象上报告一个身份验证错误:
\nrequest.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`);\n response.on('error', (error) => {\n console.log(`ERROR: ${JSON.stringify(error)}`)\n })\n})\nrequest.on('login', (authInfo, callback) => {\n callback()\n})\n在 request 最终的 chunk 数据后写入 request 后触发
在 request 被中止时触发。 如果 request 已经关闭， abort 事件将不会被触发。
返回:
\nerror Error -提供失败信息的错误对象。当 net网络模块没有发出网络请求时会触发。 通常情况下，当 request请求对象发出一个 error错误事件时，一个 close关闭事件会随之发生，并且不会提供响应对象。
作为HTTP 的 request-response 中的最后一个事件发出。 close事件表明，在request或response 对象中不会发出更多的事件。
返回:
\nstatusCode Integermethod StringredirectUrl StringresponseHeaders Record<String, String[]>当服务器返回重定向响应时触发(例如，301 页面永久性移走)。 调用 request.followRirect 将继续重定向。 如果该事件被处理，request.followRedirect 必须同步调用，否则请求将被取消。
request.chunkedEncoding一个Boolean类型的值，指定请求是否将使用 HTTP 分块传输编码。 默认值为 false. 该属性是可读写的, 但它只能在第一次写入操作之前设置，因为还没有写入 HTTP 头。 在第一写入后如果设置chunkedEncoding属性将引发错误。
如果 request 的 body 是一个大的数据时，强烈建议使用块编码。因为数据将以小块的方式进行传输, 而不是在 Electron 进程内存中内部缓冲。
\nrequest.setHeader(name, value)name String - 额外的 HTTP 头名称.value String - 额外的 HTTP 头部值。添加一个额外的 HTTP 头。 头名称将按原样发布，不会转为小写。 它只能在第一次写入之前调用。 在第一次写入后调用此方法将引发错误。 如果传递的值不是 String, 则会调用 toString () 方法来获取最终值。
某些头部受应用程序设置的限制。 这些头部如下所列。 有关受限头部的更多信息，可以在 Chromium的头部工具 中找到。
\nContent-LengthHostTrailer 或 TeUpgradeCookie2Keep-AliveTransfer-Encoding此外，也不允许将 Connection 头部设置为 upgrade。
request.getHeader(name)name String - 指定一个额外的头名称.返回 String - 以前设置的额外头部名称的值。
request.removeHeader(name)name String - 指定一个额外的头名称.移除先前设置的额外头部名称。 此方法只能在首次写入前调用。 尝试在第一次写入后调用将抛出一个错误。
\nrequest.write(chunk[, encoding][, callback])chunk (String | Buffer) - 请求主体的数据块。 如果是字符串，则使用指定的编码将其转换为Buffer。encoding String (可选) - 用于将字符串块转换为Buffer对象。 默认为“utf-8”。callback Function (可选)-在写操作结束后调用。callback 实质上是为了保持与 Node.js API 的相似性而引入的虚拟函数。 在将 chunk 内容传递到 Chromium 网络层之后, 在下一个 tick 中异步调用。 与 Node.js 实现相反, 不保证 chunk 内容在调用 callback 之前已经被刷新。
向请求正文中添加一个数据块。 第一次写操作可能导致在线路上发出请求头。 在第一次写入操作后, 不允许添加或删除自定义标头。
\nrequest.end([chunk][, encoding][, callback])chunk (String | Buffer) (可选)encoding String (可选)callback Function (可选)发送请求数据的剩下部分。 不允许进行后续的写入或结束操作。 finish 事件在结束操作后发出。
request.abort()取消正在进行的 HTTP 事务。 如果请求已发出 close 事件, 则中止操作将不起作用。 否则正在进行的事件将发出 abort 和 close 事件。 此外, 如果有一个正在进行的响应对象, 它将发出 aborted 事件。
request.followRedirect()继续任何待处理的重定向。 只能在 'redirect' 事件期间调用。
request.getUploadProgress()返回 Object:
active Boolean - 请求当前是否处于活动状态。 如果为 false，将不会设置其他属性。started Boolean - 上传是否已经开始。 如果值为false，current 和 total 将被设置为 0。current Integer - 到目前为止已上传的字节数total Integer - 本次请求总共要上传的字节数您可以使用此方法获取使用 POST 请求的文件上传或其他数据传输的进度
\n\n\n在系统剪贴板上执行复制和粘贴操作。
\n
在 Linux 上，还有一个 selection 粘贴板 。 想要操作该剪切板，你需要为每个函数传递 selection 参数。
const { clipboard } = require('electron')\n\nclipboard.writeText('Example String', 'selection')\nconsole.log(clipboard.readText('selection'))\nclipboard 对象具有以下方法:
注意: 被标记为实验性的 api 将来可能被删除。
\nclipboard.readText([type])type String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。返回 String- 剪贴板中的纯文本内容。
const { clipboard } = require('electron')\n\nclipboard.writeText('hello i am a bit of text!')\n\nconst text = clipboard.readText()\nconsole.log(text)\n// hello i am a bit of text!'\nclipboard.writeText(text[, type])text Stringtype String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。将 text 作为纯文本写入剪贴板。
const { clipboard } = require('electron')\n\nconst text = 'hello i am a bit of text!'\nclipboard.writeText(text)\nclipboard.readHTML([type])type String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。返回 String- 剪贴板中的HTML内容。
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b>')\nconst html = clipboard.readHTML()\n\nconsole.log(html)\n// <meta charset='utf-8'><b>Hi</b>\nclipboard.writeHTML(markup[, type])markup Stringtype String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。将 markup 写入剪贴板。
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b')\nclipboard.readImage([type])type String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。返回 NativeImage- 剪贴板中的图像内容。
clipboard.writeImage(image[, type])image NativeImagetype String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。将 image 写入剪贴板。
clipboard.readRTF([type])type String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。返回 String- 剪贴板中的RTF内容。
const { clipboard } = require('electron')\n\nclipboard.writeRTF('{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}')\n\nconst rtf = clipboard.readRTF()\nconsole.log(rtf)\n// {\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}\nclipboard.writeRTF(text[, type])text Stringtype String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。向剪贴板中写入 RTF 格式的 text.
const { clipboard } = require('electron')\n\nconst rtf = '{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}'\nclipboard.writeRTF(rtf)\nclipboard.readBookmark() macOS Windows返回 Object:
title Stringurl String返回一个对象, 其中包含表示剪贴板中书签 title 和 url 。 当书签不可用时, title 和 url 值将为空字符串。
clipboard.writeBookmark(title, url[, type]) macOS Windowstitle Stringurl Stringtype String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。将书签的 title 和 url 写入剪贴板。
注意：Windows上的大多数应用程序不支持粘贴书签，因此你可以使用 clipboard.write 将书签和后备文本写入剪贴板。
const { clipboard } = require('electron')\n\nclipboard.writeBookmark({\n text: 'https://electronjs.org',\n bookmark: 'Electron Homepage'\n})\nclipboard.readFindText() macOS返回 String - \"查找粘贴板\"上的文本，这是保存有关活动应用程序查找面板当前状态信息的粘贴板。
此方法从渲染进程调用时使用同步 IPC。 每当激活应用程序时, 都会从查找粘贴板中重新读取缓存值。
\nclipboard.writeFindText(text) macOStext String将 text 作为纯文本写入查找粘贴板(粘贴板上有关于当前应用程序查找面板状态的信息)。 此方法从渲染进程调用时使用同步 IPC。
clipboard.clear([type])type String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。清除剪贴板内容。
\nclipboard.availableFormats([type])type String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。返回 String []- 剪贴板 type 所支持的格式的数组。
const { clipboard } = require('electron')\n\nconst formats = clipboard.availableFormats()\nconsole.log(formats)\n// [ 'text/plain', 'text/html' ]\nclipboard.has(format[, type]) 实验功能format Stringtype String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。返回 Boolean, 剪贴板是否支持指定的 format。
const { clipboard } = require('electron')\n\nconst hasFormat = clipboard.has('<p>selection</p>')\nconsole.log(hasFormat)\n// 'true' or 'false'\nclipboard.read(format) 实验功能format String返回 String- 从剪贴板中读取 format 类型的内容。
format should contain valid ASCII characters and have / separator. a/c, a/bc are valid formats while /abc, abc/, a/, /a, a are not valid.
clipboard.readBuffer(format) 实验功能format String返回 Buffer- 从剪贴板中读取 format 类型的内容。
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('this is binary', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\n\nconst ret = clipboard.readBuffer('public/utf8-plain-text')\n\nconsole.log(buffer.equals(out))\n// true\nclipboard.writeBuffer(format, buffer[, type]) 实验功能format Stringbuffer Buffertype String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。将 buffer 作为 format 类型写入剪贴板。
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('writeBuffer', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\nclipboard.write(data[, type])data Objecttext String（可选）html String（可选）image NativeImage (可选)rtf String (可选)bookmark String (可选)- URL 的标题 text。type String (optional) -可以是 selection 或 clipboard; 默认为 'clipboard'. selection 仅在 Linux 中可用。将 data 写入剪贴板。
const { clipboard } = require('electron')\n\nclipboard.write({\n text: 'test',\n html: '<b>Hi</b>',\n rtf: '{\\\\rtf1\\\\utf8 text}',\n bookmark: 'a title'\n})\n\nconsole.log(clipboard.readText())\n// 'test'\n\nconsole.log(clipboard.readHTML())\n// <meta charset='utf-8'><b>Hi</b>\n\nconsole.log(clipboard.readRTF())\n// '{\\\\rtf1\\\\utf8 text}'\n\nconsole.log(clipboard.readBookmark())\n// { title: 'a title', url: 'test' }\n代码签名是一种用来证明应用是由你创建的一种安全技术。
\nmacOS 系统能通过代码签名检测对app的任何修改，包括意外修改和来自恶意代码的修改。
\nOn Windows, the system assigns a trust level to your code signing certificate which if you don't have, or if your trust level is low, will cause security dialogs to appear when users start using your application. 信任级别随着时间的推移构建，因此最好尽早开始代码签名。
\n即使开发者可以发布一个未签名的应用程序，但是我们并不建议这样做。 Both Windows and macOS will, by default, prevent either the download or the execution of unsigned applications. Starting with macOS Catalina (version 10.15), users have to go through multiple manual steps to open unsigned applications.
\n
如你所见，用户有两个选择：直接删除应用或者取消运行。 你不会想让用户看见该对话框。
\n如果你正在开发一款Electron应用，并打算将其打包发布，那你就应该为其添加代码签名。
\n正确准备 macOS 应用程序的发布需要两个步骤：首先，应用程序需要签名。 然后，应用程序需要上传到苹果，然后才能进行名为“公证”的过程， 自动化系统将会进一步验证您的应用没有做任何事情来危及其用户。
\nTo start the process, ensure that you fulfill the requirements for signing and notarizing your app:
\nElectron 的生态系统有利于配置和自由，所以有多种方法让您的应用程序签名和公证。
\nelectron-forgeIf you're using Electron's favorite build tool, getting your application signed and notarized requires a few additions to your configuration. Forge 是官方的 Electron 工具的 集合，在hood下使用 electron-packager electron-osx-sign electron-notarize 。
Let's take a look at an example configuration with all required fields. 并不是所有都是必需的：工具非常聪明足以自动找到合适的 identity, 例如，但我们建议你明白无误。
{\n \"name\": \"my-app\",\n \"version\": \"0.0.1\",\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"osxSign\": {\n \"identity\": \"Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)\",\n \"hardened-runtime\": true,\n \"entitlements\": \"entitlements.plist\",\n \"entitlements-inherit\": \"entitlements.plist\",\n \"signature-flags\": \"library\"\n },\n \"osxNotarize\": {\n \"appleId\": \"felix@felix.fun\",\n \"appleIdPassword\": \"my-apple-id-password\",\n }\n }\n }\n }\n}\n此处引用的 plist 文件需要以下的 macOS 特定权限来保证您的应用正在做这些事情的苹果安全机制并不意味着任何伤害：
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nNote that up until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required as well. However, it should not be used anymore if it can be avoided.
要查看所有这些都在操作中，请查看 Electron Fiddle 的源代码，尤其是其 electron-forge 配置文件。
如果您打算在应用中使用 Electron 的 API 访问麦克风或摄像头，您还需要添加以下权限：
\n<key>com.apple.security.device.audio-input</key>\n<true/>\n<key>com.apple.security.device.camera</key>\n<true/>\nIf these are not present in your app's entitlements when you invoke, for example:
\nconst { systemPreferences } = require('electron')\n\nconst microphone = systemPreferences.askForMediaAccess('microphone')\nYour app may crash. 在 Hardened Runtime 中查看资源访问部分以获取更多信息和您可能需要的权限。
\nelectron-builderElectron Builder comes with a custom solution for signing your application. 你可以在这里找到 它的文档
\nelectron-packagerIf you're not using an integrated build pipeline like Forge or Builder, you are likely using electron-packager, which includes electron-osx-sign and electron-notarize.
如果您正在使用Packager的 API，您可以通过配置 来签名并对您的应用程序进行公证
\nconst packager = require('electron-packager')\n\npackager({\n dir: '/path/to/my/app',\n osxSign: {\n identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',\n 'hardened-runtime': true,\n entitlements: 'entitlements.plist',\n 'entitlements-inherit': 'entitlements.plist',\n 'signature-flags': 'library'\n },\n osxNotarize: {\n appleId: 'felix@felix.fun',\n appleIdPassword: 'my-apple-id-password'\n }\n})\n此处引用的 plist 文件需要以下的 macOS 特定权限来保证您的应用正在做这些事情的苹果安全机制并不意味着任何伤害：
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nUp until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required as well. However, it should not be used anymore if it can be avoided.
See the Mac App Store Guide.
\n在签署Windows应用程序前，你需要完成以下事项：
\nYou can get a code signing certificate from a lot of resellers. 价格各异，所以值得你花点时间去货比三家。 Popular resellers include:
\n\n你可以运用许多方式来签署你的应用：
\nelectron-winstaller will generate an installer for windows and sign it for youelectron-forge can sign installers it generates through the Squirrel.Windows or MSI targets.electron-builder can sign some of its windows targetsSee the Windows Store Guide.
", "title": "代码签名", "description": "" }, "/docs/development/coding-style": { "locale": "zh-CN", "slug": "coding-style", "href": "/docs/development/coding-style", "crowdinFileId": "256147", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/coding-style.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "这些是 Electron 编码风格指南。
\n您可以运行 npm run lint 来显示 cpplint 和eslint 检测到的任何样式问题。
path）ipc、app）@)path.join() 来组织文件路径。os.tmpdir()而不是/tmp来引用临时目录。return when returning explicitly at the end of a function.return null，return undefined，null或undefined对于 C++ 和 Python, 我们遵循 Chromium 的编码风格. 你可以使用 clang-format 来自动格式化 C++ 代码. 你可以使用 script/cpplint.py 来检验文件是否符合要求。
我们现在使用的 Python 版本是 Python 2.7。
\nC++ 代码使用了大量 Chromium 的抽象和类型，因此建议您熟悉它们。 一个起步的好地方是 Chromium 的 重要的抽象概念和数据库结构 文档. 该文档提到一些特殊类型，范围类型(超出范围时自动释放其内存), 记录机制等。
\n你可以运行 npm run lint-docs 来保证你修改的文档格式正确。
- 连接而不是 _, 例如. file-name.js 而不是 file_name.js, 因为在 github/atom中模块名通常是 module-name 形式. 此规则仅适用于 .js 文件。const 用于需要的和其他的常数. If the value is a primitive, use uppercase naming (eg const NUMBER_OF_RETRIES = 5).let 用于定义变量function () { }+Electron API 使用与 Node.js 相同的大小写方案：
\nBrowserWindow, 使用 CamelCase.globalShortcut时，使用 mixedCase。win.webContents, 使用 mixedCase.<webview> Tag 或 Process Object.当创建新的 API 时， 最好使用 getter 和 setter 而不是 jQuery 的一次性函数。 举个例子, .getText() 和 .setText(text) 优于 .text([text]). 这是一些相关的 讨论
\n\n操作Chromium读取的应用程序的命令行参数
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
下面的例子展示了如何检查—disable-gpu标志是否设置。
const { app } = require('electron')\napp.commandLine.hasSwitch('disable-gpu')\n关于你可以使用哪些参数，请查阅命令行参数文档。
\ncommandLine.appendSwitch(switch[, value])switch String - 命令行开关，不包含前边的-- --value String (optional) - 给开关设置的值通过可选的参数 value 给 Chromium 中添加一个命令行开关。
注意: 该方法不会影响 process. argv 该功能是为控制Chromium行为设计的。
commandLine.appendArgument(value)valueString - 要追加到命令行的参数在Chromium的命令行中附加一个参数。 参数会被正确引用。 无论附加顺序如何，切换将在参数之前进行。
\n如果你正在追加一个参数，如--switch=value, 请考虑使用appendSwitch('switch', 'value')
注意: 该方法不会影响 process. argv 该功能是为控制Chromium行为设计的。
commandLine.hasSwitch(switch)switch String - 命令行开关返回Boolean - 命令行开关是否打开。
commandLine.getSwitchValue(switch)switch String - 命令行开关返回 String - 命令行开关值。
注意： 当开关不存在或没有值时，它返回空字符串。
", "title": "类: CommandLine", "description": "操作Chromium读取的应用程序的命令行参数" }, "/docs/api/command-line-switches": { "locale": "zh-CN", "slug": "command-line-switches", "href": "/docs/api/command-line-switches", "crowdinFileId": "256293", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/command-line-switches.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nElectron支持的命令行开关.
\n
您可以在app 模块的ready事件生效之前，使用app.commandLine.appendSwitch将它们附加到您的应用程序的主要脚本中：
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('remote-debugging-port', '8315')\napp.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')\n\napp.whenReady().then(() => {\n // 在这里写入你的代码\n})\nurl启用了集成身份验证的以逗号分隔的服务器列表。
\n例如：
\n--auth-server-whitelist='*example.com, *foobar.com, *baz'\n则任何以example.com, foobar.com, baz结尾的url, 都需要考虑集成验证. 没有 * 前缀的 URL 必须完全匹配。
url需要授权用户凭据的以逗号分隔的服务器列表。 没有 * 前缀的 URL 必须完全匹配。
禁用NTLM v2的posix平台，对别处没有影响。
\n禁用HTTP请求的磁盘缓存.
\n禁用HTTP/2和SPDY/3.1协议.
\n防止Chromium降低不可见的页面渲染进程的优先级.
\n这个标识是全局的, 影响所有渲染进程. 如果你只想禁用一个窗口的节流保护，你可以采取playing silent audio.
\nsize强制磁盘缓存使用的最大磁盘空间（以字节为单位）。
\n开启以下API 的调用堆栈日志记录(过滤事件)：
\ndesktopCapturer.getSources() / desktop-capturer-get-sourcesPrints Chromium's logging to stderr (or a log file).
\nThe ELECTRON_ENABLE_LOGGING environment variable has the same effect as passing --enable-logging.
Passing --enable-logging will result in logs being printed on stderr. Passing --enable-logging=file will result in logs being saved to the file specified by --log-file=..., or to electron_debug.log in the user-data directory if --log-file is not specified.
\n\nNote: On Windows, logs from child processes cannot be sent to stderr. Logging to a file is the most reliable way to collect logs on Windows.
\n
See also --log-file, --log-level, --v, and --vmodule.
trials试用特性将强制启用或禁用。
\n例如： WebRTC-Audio-Red-For-Opus/Enabled/
rules以逗号分隔的rules列表，用于控制主机名的映射方式
例如：
\nMAP * 127.0.0.1 强制将所有主机名映射到127.0.0.1MAP *.google.com proxy 强制所有google.com子域名解析到\"proxy\".MAP test.com [::1]:77 强制将 \"test.com\" 解析到 IPv6 环回接口。 也会强制目标套接字地址的端口为77。MAP * baz, EXCLUDE www.google.com 把所有地址重新映射到“baz”, 除了\"www.google.com\".这些映射适用于网络请求中的端点主机. 网络请求包括TCP连接和直连的主机解析器, 以及HTTP代理连接中的CONNECT方式, 以及在SOCKS代理连接中的端点主机.
rules与--host-rules类似, 但是这些rules仅适用于主机解析器.
忽略证书相关的错误.
\ndomains忽略由,分割的domains列表的连接限制.
flags指定传递到 Node.js 引擎的flags。 如果您想在主进程中启用 flags ，则必须在一开始运行Electron的时候就传递。
$ electron --js-flags=\"--harmony_proxies --harmony_collections\" your-app\n查看Node.js 文档或者在终端中运行node --help命令查看可用的flags列表。 此外，还可以运行node --v8-options来查看与Node.js的V8 JavaScript引擎特定相关的flags列表。
设置系统语言环境
\npathIf --enable-logging is specified, logs will be written to the given path. The parent directory must exist.
Setting the ELECTRON_LOG_FILE environment variable is equivalent to passing this flag. If both are present, the command-line switch takes precedence.
path启用需要保存的网络日志事件并将其写入path路径下.
NSets the verbosity of logging when used together with --enable-logging. N should be one of Chrome's LogSeverities.
Note that two complimentary logging mechanisms in Chromium -- LOG() and VLOG() -- are controlled by different switches. --log-level controls LOG() messages, while --v and --vmodule control VLOG() messages. So you may want to use a combination of these three switches depending on the granularity you want and what logging calls are made by the code you're trying to watch.
See Chromium Logging source for more information on how LOG() and VLOG() interact. Loosely speaking, VLOG() can be thought of as sub-levels / per-module levels inside LOG(INFO) to control the firehose of LOG(INFO) data.
See also --enable-logging, --log-level, --v, and --vmodule.
不使用代理服务器，并始终保持直连。 会覆盖其他代理服务器标记。
\n禁用 Chromium 沙箱。 强制渲染器进程和Chromium助手进程以非沙盒化运行。 应该只在测试时使用。
\nhosts指示Electron绕过使用; 分号; 分割的给定的主机列表中的代理服务器。 这个标志只有在与--proxy-server 同时使用时才具有效果。
例如：
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')\n上面的代码, 除了本地地址(localhost,127.0.0.1等等.), google.com子域名, 包含foo.com后缀的主机地址, 以及任何在1.2.3.4:5678上的地址以外的所有主机都将使用代理服务器.
url在指定url中使用PAC脚本.
address:port使用指定的覆盖系统设置的代理服务器. 这个开关只影响HTTP协议请求, 包括HTTPS和WebSocket请求. 值得注意的是并不是所有的代理服务器都支持HTTPS和WebSocket请求. 代理 URL 不支持用户名和密码认证方式 Chromium 的问题。
\nport在指定端口开启HTTP远程调试.
log_level指定默认的最大活跃V-logging级别；默认值为0。 通常 V-logging 级别为正数。
\n这个开关只有在--enable-logging也被传递时才起效.
See also --enable-logging, --log-level, and --vmodule.
pattern给定每个模块最大的V-logging等级, 覆盖--v设定的值. 如下: my_module=2,foo*=3 会更改所有代码在源文件 my_module.* 和 foo*.* 中的日志级别。
任何包含正斜杠或反斜杠的模式都将针对 整个路径名进行测试，而不仅仅是模块。 如下: */foo/bar/*=2 会更改foo/bar 目录下源文件中所有代码的日志级别。
这个开关只有在--enable-logging也被传递时才起效.
See also --enable-logging, --log-level, and --v.
当有多个GPU可用时，强制使用独立显卡。
\n当有多个GPU可用时，强制使用集成显卡。
\nElectron 支持一些 Node.js 支持的 CLI flags。
\n注意： 当Electron 不是以 ELECTRON_RUN_AS_NODE运行时，传递不支持的命令行参数到Electron 不会起作用。
在 主机:端口 上激活检查器并在用户脚本开始运行后中断。 默认 主机:端口 为127.0.0.1:9229。
\n是 --debug-brk=[host:]port的别名
当检查器被激活时要使用的 主机:端口。 常用于通过发送 SIGUSR1 信号激活检查器时。 默认主机是 127.0.0.1。
是 --debug-port=[host:]port的别名
在 主机:端口 上激活检查器。 默认是 127.0.0.1:9229。
集成V8 检查器允许Chrome 开发者工具和 IDE 这些工具调试和修改 Electron 实例。 这些工具通过 TCP 端口连接到 Electron 实例，并使用 Chrome 开发者工具协议进行通信。
\n调试相关的标识, 更多详细信息请查看 Debugging the Main Process指南。
\n是 --debug[host:]port的别名
指定检查器的 web 套接字url 公开方式。
\n默认情况下，websocket url在 stderr 中和在 http://host:port/json/list 的 /json/list 端点下都是可用的。
", "title": "支持的命令行开关", "description": "Electron支持的命令行开关." }, "/docs/api/content-tracing": { "locale": "zh-CN", "slug": "content-tracing", "href": "/docs/api/content-tracing", "crowdinFileId": "256297", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/content-tracing.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n从Chromium收集追踪数据以找到性能瓶颈和慢操作。
\n
进程：主进程
\n此模块不包括 Web 界面。 若要查看记录的轨迹，请使用跟踪查看器，在Chrome上可以访问 chrome://tracking 。
注意：在应用程序模块的 ready 事件触发之前，您不应该使用此模块。
const { app, contentTracing } = require('electron')\n\napp.whenReady().then(() => {\n (async () => {\n await contentTracing.startRecording({\n included_categories: ['*']\n })\n console.log('Tracing started')\n await new Promise(resolve => setTimeout(resolve, 5000))\n const path = await contentTracing.stopRecording()\n console.log('Tracing data recorded to ' + path)\n })()\n})\ncontentTracing模块包含以下方法：
contentTracing.getCategories()返回 Promise<String[]> - 一旦所有子进程都确认了 getCategories 请求，会 resolve 一个类别组的数组
获取一组类别组。 当到达新的代码路径时，类别组可能会更改。 另请参阅内置跟踪类别列表。
\n\n\n注意： Electron 添加了一个名为
\n\"electron\"的非默认追踪类别。 此类别可以用于捕捉Electron特定的追踪事件。
contentTracing.startRecording(options)options (TraceConfig | TraceCategoriesAndOptions)返回 Promise<void> - 当所有子进程都确认了 startRecording 请求后 resolve.
在所有进程上开始记录
\n一旦收到EnableRecording请求，记录立即在本地开始进行，并在子进程上异步执行。
\n如果一个记录已经运行了，promise将立即resolve，因为一次只能进行一个跟踪操作。
\ncontentTracing.stopRecording([resultFilePath])resultFilePath String (可选)返回 Promise<String> - 一旦所有子进程都确认了 stopRecording 请求，会 resolve 一个包含了追踪数据的文件路径
停止所有进程记录。
\n子进程通常缓存跟踪数据，并且很少清空和发送跟踪数据回到主进程。 这有助于最小化运行时间开销，因为通过IPC发送跟踪数据可能是一个开销巨大的操作。 因此，为了结束跟踪，Chromium异步地要求所有子进程刷新所有挂起的跟踪数据。
\n追踪数据将被写入 resultFilePath。 如果 resultFilePath 是空的或未提供，追踪数据将被写入临时文件，并且路径将在promise中返回。
contentTracing.getTraceBufferUsage()返回 Promise<Object> - resolve一个包含了追踪缓冲器的 value 和 percentage 最大使用量的对象
value Numberpercentage Number获取追踪缓冲区在进程间的最大使用量（占全部状态的百分比）。
", "title": "contentTracing", "description": "从Chromium收集追踪数据以找到性能瓶颈和慢操作。" }, "/docs/api/context-bridge": { "locale": "zh-CN", "slug": "context-bridge", "href": "/docs/api/context-bridge", "crowdinFileId": "256299", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/context-bridge.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n在隔离的上下文中创建一个安全的、双向的、同步的桥梁。
\n
进程: Renderer
\n如下，是一个从隔离的预加载脚本将 API 暴露给渲染器的示例：
\n// Preload (Isolated World)\nconst { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing')\n }\n)\n// Renderer (Main World)\n\nwindow.electron.doThing()\n\"Main World\"是主渲染器代码运行的 JavaScript 上下文。 默认情况下，你在渲染器中加载的页面在此环境中执行代码。
\n当你在webPreferences属性中启用contextIsolation (Electron 12.0.0 及以上版本默认启用)，你的预加载脚本将运行在一个“被隔离的环境”中。 您可以在Security 文档中阅读更多关于上下文隔离及其影响的信息。
contextBridge模块有以下方法:
contextBridge.exposeInMainWorld(apiKey, api)apiKey String - 将 API 注入到 窗口 的键。 API 将可通过 window[apiKey] 访问。api any - 你的 API可以是什么样的以及它是如何工作的相关信息如下。提供给 exposeInMainWorld 的 api 必须是一个 Function， String， Number， Array， Boolean；或一个键为字符串，值为一个 Function， String， Number， Array， Boolean的对象；或其他符合相同条件的嵌套对象。
Function 类型的值被代理到其他上下文中，所有其他类型的值都会被 复制 并 冻结。 在 API 中发送的任何数据 /原始数据将不可改变，在桥接器其中一侧的更新不会导致另一侧的更新。
复杂 API 的示例如下：
\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing'),\n myPromises: [Promise.resolve(), Promise.reject(new Error('whoops'))],\n anAsyncFunction: async () => 123,\n data: {\n myFlags: ['a', 'b', 'c'],\n bootTime: 1234\n },\n nestedAPI: {\n evenDeeper: {\n youCanDoThisAsMuchAsYouWant: {\n fn: () => ({\n returnData: 123\n })\n }\n }\n }\n }\n)\n你通过 contextBridge 绑定的 Function 值会被 Electron 代理，以确保保持上下文隔离。 这导致了我们在下面概述的一些键的限制。
因为当参数、错误和返回值在桥接器上发送时会被 复制 ，所以只有某些类型可以使用。 从上层来看，如果你想要使用的类型可以序列化并反序列化为同一个对象，这个类型可以使用。 为确保完整性，下面列出了一份类型支持表：
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| 类型 | 复杂度 | 有入参 | 有返回值 | 局限性 |
|---|---|---|---|---|
String | 简单 | ✅ | ✅ | N/A |
Number | 简单 | ✅ | ✅ | N/A |
Boolean | 简单 | ✅ | ✅ | N/A |
Object | 复杂 | ✅ | ✅ | 键仅支持使用此表中的“简单”的类型。 值必须在此表中支持的值。 修改prototype将被丢弃。 发送自定义类将复制值，但不会包含prototype。 |
Array | 复杂 | ✅ | ✅ | 与 Object 类型相同的限制 |
Error | 复杂 | ✅ | ✅ | 所抛出的错误也会被复制，这可能导致消息和堆栈跟踪的错误略有变化，由于在不同的上下文中抛出 |
Promise | 复杂 | ✅ | ✅ | 只有当 promise 是返回值或确切参数时，它们才会被代理。 嵌套在数组或对象中的Promise将被丢弃。 |
Function | 复杂 | ✅ | ✅ | 修改prototype将被丢弃。 发送类或构造函数将不起作用。 |
| Cloneable Types | 简单 | ✅ | ✅ | 点击链接查看可克隆类型的文档 |
Element | 复杂 | ✅ | ✅ | 修改prototype将被丢弃。 发送自定义元素将不生效。 |
Blob | 复杂 | ✅ | ✅ | N/A |
Symbol | N/A | ❌ | ❌ | Symbol不能跨上下文复制，因此会丢弃它们 |
如果您关心的类型不在上表中，可能是因为不支持该类型。
\ncontextBridge 可以被预加载脚本用来让您的渲染器访问Node API。 上面所述的支持类型表也适用于您通过 contextBridge暴露的Node API。 请注意许多Node的API授权访问本地系统资源。 请非常谨慎地暴露全局变量和api给不受信任的远程内容。
const { contextBridge } = require('electron')\nconst crypto = require('crypto')\ncontextBridge.exposeInMainWorld('nodeCrypto', {\n sha256sum (data) {\n const hash = crypto.createHash('sha256')\n hash.update(data)\n return hash.digest('hex')\n }\n})\n上下文隔离功能将确保您的 预加载脚本 和 Electron的内部逻辑 运行在所加载的 webcontent网页 之外的另一个独立的上下文环境里。 这对安全性很重要，因为它有助于阻止网站访问 Electron 的内部组件 和 您的预加载脚本可访问的高等级权限的API 。
这意味着，实际上，您的预加载脚本访问的 window 对象并不是网站所能访问的对象。 For example, if you set window.hello = 'wave' in your preload script and context isolation is enabled, window.hello will be undefined if the website tries to access it.
Context isolation has been enabled by default since Electron 12, and it is a recommended security setting for all applications.
\n\n\nWithout context isolation, I used to provide APIs from my preload script using
\nwindow.X = apiObject. Now what?
Exposing APIs from your preload script to a loaded website in the renderer process is a common use-case. With context isolation disabled, your preload script would share a common global window object with the renderer. You could then attach arbitrary properties to a preload script:
// preload with contextIsolation disabled\nwindow.myAPI = {\n doAThing: () => {}\n}\nThe doAThing() function could then be used directly in the renderer process:
// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nThere is a dedicated module in Electron to help you do this in a painless way. The contextBridge module can be used to safely expose APIs from your preload script's isolated context to the context the website is running in. API 还可以像以前一样，从 window.myAPI 网站上访问。
// preload with contextIsolation enabled\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n doAThing: () => {}\n})\n// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nPlease read the contextBridge documentation linked above to fully understand its limitations. For instance, you can't send custom prototypes or symbols over the bridge.
单单开启和使用 contextIsolation 并不直接意味着您所做的一切都是安全的。 For instance, this code is unsafe.
// ❌ Bad code\ncontextBridge.exposeInMainWorld('myAPI', {\n send: ipcRenderer.send\n})\n它直接暴露了一个没有任何参数过滤的高等级权限 API 。 This would allow any website to send arbitrary IPC messages, which you do not want to be possible. 相反，暴露进程间通信相关 API 的正确方法是为每一种通信消息提供一种实现方法。
\n// ✅ Good code\ncontextBridge.exposeInMainWorld('myAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nIf you're building your Electron app with TypeScript, you'll want to add types to your APIs exposed over the context bridge. The renderer's window object won't have the correct typings unless you extend the types with a declaration file.
For example, given this preload.ts script:
contextBridge.exposeInMainWorld('electronAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nYou can create a renderer.d.ts declaration file and globally augment the Window interface:
export interface IElectronAPI {\n loadPreferences: () => Promise<void>,\n}\n\ndeclare global {\n interface Window {\n electronAPI: IElectronAPI\n }\n}\nDoing so will ensure that the TypeScript compiler will know about the electronAPI property on your global window object when writing scripts in your renderer process:
window.electronAPI.loadPreferences()\nname String - The name of the cookie.value String - The value of the cookie.domain String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains.hostOnly Boolean (optional) - Whether the cookie is a host-only cookie; this will only be true if no domain was passed.path String (optional) - The path of the cookie.secure Boolean (optional) - Whether the cookie is marked as secure.httpOnly Boolean (optional) - Whether the cookie is marked as HTTP only.session Boolean (optional) - Whether the cookie is a session cookie or a persistent cookie with an expiration date.expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.sameSite String - The Same Site policy applied to this cookie. Can be unspecified, no_restriction, lax or strict.\n\n查询和修改一个会话的cookies
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
通过Session的cookies属性来访问Cookies的实例
例如：
\nconst { session } = require('electron')\n\n// 查询所有 cookies。\nsession.defaultSession.cookies.get({})\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// 查询所有与设置的 URL 相关的所有 cookies.\nsession.defaultSession.cookies.get({ url: 'http://www.github.com' })\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// 设置一个 cookie，使用设置的名称；\n// 如果存在，则会覆盖原先 cookie.\nconst cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }\nsession.defaultSession.cookies.set(cookie)\n .then(() => {\n // success\n }, (error) => {\n console.error(error)\n })\n以下事件会在Cookies实例触发。
返回:
\nevent Eventcookie Cookie - 变更后的 cookie 值。cause String - 导致更改的原因，为以下值之一：explicit - cookie 是由消费者的操作直接更改的。overwrite - 一个覆盖原值的插入操作导致的 cookie 被自动删除。expired - cookie 在过期时自动删除。evicted - 在GC（垃圾回收机制）过程中被回收。expired-overwrite - 一个已过期的时间覆写了原cookie 的过期时间。removed Boolean - true 表示cookie 已被删掉, 否则为 false.该事件在cookie 被添加、修改、删除或过期时触发。
\n以下方法可以在Cookies实例调用。
cookies.get(filter)filter Objecturl String (可选) - 检索与 url 相关的 cookie。 空意味着检索所有 URL 的 cookie 。nameString (可选) - 按名称筛选 cookie。domain String (optional) - 检索与域名或者 domain 子域名匹配的cookie。pathString (可选) - 检索路径与 path 匹配的 cookie。secureBoolean (可选) - 通过其Secure 属性筛选 cookie。sessionBoolean (可选) - 筛选出session 内可用或持久性 cookie。返回 Promise<Cookie[]> - 一个会解析成数组或者 cookie 对象的 promise。
发送请求以获取匹配 filter 的所有 cookie，并通过响应来解决承诺问题。
cookies.set(details)details Objecturl String - 与 cookie 关联的 url。 如果URL无效，promise将返回reject。name String (可选) - cookie 的名称。 如果省略则默认为空。value String (可选) - cookie 的值。 如果省略则默认为空。domain String (可选) - cookie所在域名，通常使用点号开头，以使其对子域名可用。 如果省略则默认为空。path String (可选) - cookie 的路径。 如果省略则默认为空。secure Boolean (可选) - cookie 是否应该标记为Secure。 Defaults to false unless Same Site=None attribute is used.httpOnly Boolean (可选) - cookie 是否应该标记为 HTTP only。 默认值为 false.expirationDateDouble (可选) - cookie 的到期日期，类型为时间戳，单位为秒。 如果省略, 则 cookie 将成为会话 cookie, 并且不会在会话之间保留。sameSite String (可选) - 要应用于此 cookie 的 Same Site 策略。 可以被设置为unspecified，no_restriction，lax或者strict 默认值为 no_restriction.返回 Promise<void> - cookie 设置时解析的一个 promise。
用 details 去设置一个 cookie。
cookies.remove(url, name)urlString - 与 cookie 关联的 URL。nameString - cookie 名称。返回 Promise<void> - cookie 移除时解析的的一个 promise。
移除与url 和 name匹配的 cookie。
cookies.flushStore()返回 Promise<void> - 一个在 cookie 写入时解析的 promise。
写入所有未写入磁盘的 cookie。
", "title": "类：Cookies", "description": "查询和修改一个会话的cookies" }, "/docs/api/structures/cpu-usage": { "locale": "zh-CN", "slug": "cpu-usage", "href": "/docs/api/structures/cpu-usage", "crowdinFileId": "256419", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/cpu-usage.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "percentCPUUsage Number - Percentage of CPU used since the last call to getCPUUsage. First call returns 0.idleWakeupsPerSecond Number - The number of average idle CPU wakeups per second since the last call to getCPUUsage. First call returns 0. Will always return 0 on Windows.date Dateid String\n\n\n将崩溃日志提交给远程服务器
\n
以下是一个设置Electron自动提交崩溃日志到远程服务器的示例：
\nconst { crashReporter } = require('electron')\n\ncrashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })\n构建一个用于接受和处理崩溃日志的服务，你需要以下工程
\n\n或者使用第三方托管的解决办法：
\n\n崩溃报告在上传之前会临时存储在应用程序的用户数据目录下 (在Windows和Mac上称为“Crashpad”，在Linux上称为“Crash reports”)。 在启动崩溃报告器之前，你可以通过调用 app.setPath('crashDumps', '/path/to/crashes') 来覆盖该目录。
在 Windows 和 macOS 上，Electron 使用 crashpad 来监视和报告崩溃情况。 在 Linux上，Electron 使用breakpad。 这个实现细节是由Chromium驱动的，将来可能会发生变化。 尤其，crashpad是新出的，可能最终会取代所有平台的breakpad。
\n如果你在Linux上使用的是Node.js的 child_process 模块，并且想要在这些进程中报告崩溃信息，那么需要采取额外的步骤来在子进程中正确初始化崩溃报告器。 在 Mac 或 Windows 上就没有这个问题，因为这两个平台使用的Crashpad会自动监视子进程。
由于Node的子进程中无法使用 require('electron') ，那么在Node的子进程中的 process 对象中的以下 API 是可用的。 请注意，在Linux上，每个Node子进程的 breakpad 崩溃报告器都有自己独立的实例。 这与渲染器子进程不同，其具有\"存根\" breakpad 报告器，将信息返回到主进程进行报告。
process.crashReporter.start(options)process.crashReporter.getParameters()见 crashReporter.getParameters()。
process.crashReporter.addExtraParameter(key, value)见 crashReporter.addExtraParameter(key, value)。
process.crashReporter.removeExtraParameter(key)见 crashReporter.removeExtraParameter(key)。
crashReporter 模块具有以下方法:
crashReporter.start(options)选项 对象submitURL String (可选) - 崩溃报告将以POST的方式发送给这个URL。 必填 除非uploadToServer是falseproductName String (可选) - 默认为 app.name.companyName String (可选) 已废弃 - 已废弃别名为{ globalExtra: { _companyName: ... } }。uploadToServer Boolean (可选) - 是否将崩溃报告发送给服务器。 如果为 false，崩溃报告将被收集并存储在崩溃目录中，但不会上传。 默认值为 true。ignoreSystemCrashHandler Boolean (可选) - 如果为true，在主进程中生成的崩溃将不会转发给系统崩溃处理器。 默认值为 false.rateLimit Boolean (可选) macOS Windows - 如果为true，将上传的崩溃次数限制到 1次/小时。 默认值为 false.compress Boolean (可选) - 如果为true，崩溃报告将压缩并上传，使用带有 Content-Encoding: gzip 的头部。 默认值为 true。extra Record<String, String> (可选) - 将随主进程生成的崩溃报告一起发送的额外字符串键/值注解。 只支持string值。 在子进程中产生的崩溃将不会在子进程生成的崩溃报告中包含这些额外的参数。 在子进程中调用 addExtrameter 。globalExtra Record<String, String> (可选) - 会与任意进程产生的崩溃报告一起发送的额外字符串键/值注解。 一旦崩溃报告器启动，这些注解就无法更改。 如果一个键在global extra参数和进程特定的额外参数中出现，那么全局的那个将优先使用。 默认情况下，会包括 productName 和应用程序版本，也就是Electron版本。该方法必须在使用其他 崩溃报告器 的API之前调用。 一旦以这种方式初始化，crashpad处理器就会从所有随后创建的进程中收集崩溃信息。 崩溃报告器一旦启动就无法禁用了。
该方法应尽早地在app启动后调用，最好在 app.on('ready') 之前。 如果崩溃报告器没有在渲染器进程创建前初始化，那么渲染器进程将不会被崩溃报告器监视。
注意： 您可以通过使用process.crash()生成一个崩溃来测试崩溃报告器。
注意: ，如果您在第一次调用 start 后需要发送 附加的/更新的 extra 参数，你可以调用 addExtraParameter。
注意： 通过 extra, globalExtra传递，或通过addExtrameter设置的参数对键和值的长度有限制。 键名最长是 39 字节，值不能超过 127 字节。 超过最大长度的键名将被直接忽略。 超过最大长度的键值将被截断。
注意： 此方法仅在主进程中可用。
\ncrashReporter.getLastCrashReport()返回 CrashReport - 上次崩溃报告的日期和 ID。 只有已上传的崩溃报告会被返回；在磁盘上存在崩溃报告，除非上传了，否则不会返回。 如果没有上传的报告，则返回null
注意： 此方法仅在主进程中可用。
\ncrashReporter.getUploadedReports()返回 CrashReport[]:
返回所有已上传的崩溃报告。 每个报告包含日期以及上传ID。
\n注意： 此方法仅在主进程中可用。
\ncrashReporter.getUploadToServer()返回 Boolean - 是否应向服务器提交报告。 通过start 方法或 setUploadToServer设置。
注意： 此方法仅在主进程中可用。
\ncrashReporter.setUploadToServer(uploadToServer)uploadToServer Boolean - 是否将报告提交到服务器。通常由用户首选项控制。 如果在 start 被调用前调用，该方法将不起作用。
注意： 此方法仅在主进程中可用。
\ncrashReporter.addExtraParameter(key, value)key String - 参数键，长度必须小于39个字节。value String - 参数值，长度必须小于127个字节。设置一个在发送崩溃报告时将额外包含的参数。 当调用 start 时, 在这里指定的值会和所有通过 extra 选项设置的值一起发送。
以这种方式添加的参数 (或通过 extra 参数到crashReporter.start)是特定于调用进程的。 在主进程中添加extra参数，这些参数将不会与渲染器或其它子进程的崩溃报告一起发送。 同样，在渲染器进程中添加的extra参数不会与其它渲染器进程或主进程中发生的崩溃一起发送。
注意： 参数对键和值的长度有限制。 键名最长是 39 字节，值不能超过 20320 字节。 超过最大长度的键名将被直接忽略。 超过最大长度的键值将被截断。
\n注意： 在linux上，超过 127 字节的值将被分割成多个键，每个长度为127个字节。 如下: addExtraParameter('foo', 'a'.repeat(130))将产生两个分块的键， foo__1 和 foo__2，第一个将包含前127字节，第二个将包含剩余的3字节。 在你的崩溃报告后端，你应该以这种格式将键合在一起。
crashReporter.removeExtraParameter(key)key String - 参数键，长度必须小于39个字节。从当前的参数集中删除一个额外的参数。 未来的崩溃中将不包含此参数。
\ncrashReporter.getParameters()返回 Record<String, String> - 崩溃报告器当前的“extra”参数。
崩溃报告将发送下面 multipart/form-data POST 型的数据给 submitURL:
ver String - Electron 的版本.platform String - 例如 'win32'.process_type String - 例如 'renderer'.guid String - 例如 '5e1286fc-da97-479e-918b-6bfb0c3d1c72'._version String - package.json 里的版本号._productName String - crashReporter options 对象中的产品名字prod String - 基础产品的名称。 在这种情况下是Electron。_companyName String - crashReporter options 对象中的公司名称upload_file_minidump File - minidump 格式的崩溃报告extra object in the crashReporter options object.scheme String - Custom schemes to be registered with options.privileges Object (optional)standard Boolean (optional) - Default false.secure Boolean (optional) - Default false.bypassCSP Boolean (optional) - Default false.allowServiceWorkers Boolean (optional) - Default false.supportFetchAPI Boolean (optional) - Default false.corsEnabled Boolean (optional) - Default false.stream Boolean (optional) - Default false.\"本地界面\"包括文件选择器、窗口边框、对话框、上下文 菜单等 - 任何UI来自操作系统而非应用的界面。 默认行为是从操作系统选择自动主题。
\n如果您的应用有自己的黑暗模式，您应该在与系统黑暗模式设置同步时切换。 您可以通过使用[prefer-color-scheme] CSS 媒体查询来做到这一点。
\nIf you want to manually switch between light/dark modes, you can do this by setting the desired mode in the themeSource property of the nativeTheme module. This property's value will be propagated to your Renderer process. Any CSS rules related to prefers-color-scheme will be updated accordingly.
在 macOS 10.14 Mojave中， Apple 为所有 macOS 电脑引入了一个全新的 系统级黑暗模式。 如果您的 Electron 应用具有深色模式，您可以 使用\"本机 api\" 应用 应用。
In macOS 10.15 Catalina, Apple introduced a new \"automatic\" dark mode option for all macOS computers. 为了让API isDarkMode 和 Tray 在这个模式中正常工作，你需要在 Info.plist 文件里把 NSRequiresAquaSystemAppearance 设置为 false ，或者使用 >=7.0.0 的Electron。 Both Electron Packager and Electron Forge have a darwinDarkModeSupport option to automate the Info.plist changes during app build time.
If you wish to opt-out while using Electron > 8.0.0, you must set the NSRequiresAquaSystemAppearance key in the Info.plist file to true. Please note that Electron 8.0.0 and above will not let you opt-out of this theming, due to the use of the macOS 10.14 SDK.
此示例演示了Electron 应用程序从nativeTheme中获取主题颜色。 此外，它还使用 IPC 通道提供主题切换和重置控制。
从 index.html 文件开始：
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n <link rel=\"stylesheet\" type=\"text/css\" href=\"./styles.css\">\n</head>\n<body>\n <h1>Hello World!</h1>\n <p>Current theme source: <strong id=\"theme-source\">System</strong></p>\n\n <button id=\"toggle-dark-mode\">Toggle Dark Mode</button>\n <button id=\"reset-to-system\">Reset to System Theme</button>\n\n <script src=\"renderer.js\"></script>\n </body>\n</body>\n</html>\n以及 styles.css 文件：
@media (prefers-color-scheme: dark) {\n body { background: #333; color: white; }\n}\n\n@media (prefers-color-scheme: light) {\n body { background: #ddd; color: black; }\n}\n该示例渲染一个包含几个元素的 HTML 页面。 <strong id=\"theme-source\"> 元素显示当前选中的主题，两个 <button> 元素是 控件。 CSS 文件使用 prefers-color-scheme 媒体查询 设置 <body> 元素背景和文本颜色。
preload.js 脚本在 window对象中添加了一个新的 API叫做 深色模式。 此 API 暴露两个IPC 通道到渲染器进程，分别为 'dark-mode:toggle' 和 'dark-mode:system'。 它还分配了两个方法， toggle 和 system，它们将渲染器中的信息传递到 主进程。
const { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld('darkMode', {\n toggle: () => ipcRenderer.invoke('dark-mode:toggle'),\n system: () => ipcRenderer.invoke('dark-mode:system')\n})\n现在，渲染器进程可以安全地与主进程通信，并对nativeTheme 对象执行必要的变更。
renderer.js 文件负责控制 <button> 功能。
document.getElementById('toggle-dark-mode').addEventListener('click', async () => {\n const isDarkMode = await window.darkMode.toggle()\n document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'\n})\n\ndocument.getElementById('reset-to-system').addEventListener('click', async () => {\n await window.darkMode.system()\n document.getElementById('theme-source').innerHTML = 'System'\n})\n使用 addEventListener， renderer.js 文件将'click' 事件监听器添加到每个按钮元素上。 每个事件监听处理器都会调用到相关的 window.darkmode API 方法。
最后， main.js 文件代表了主进程并包含实际的 nativeTheme API。
const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n\n ipcMain.handle('dark-mode:toggle', () => {\n if (nativeTheme.shouldUseDarkColors) {\n nativeTheme.themeSource = 'light'\n } else {\n nativeTheme.themeSource = 'dark'\n }\n return nativeTheme.shouldUseDarkColors\n })\n\n ipcMain.handle('dark-mode:system', () => {\n nativeTheme.themeSource = 'system'\n })\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nipcMain.handle 方法表明主进程如何响应来自 HTML 页面上 按钮的点击事件。
'dark-mode:toggle' IPC 通道处理器方法检查 shouldUseDarkColors boolean属性 设置对应的 themeSource, 然后返回当前的 shouldUseDarkColors 属性。 回顾此 IPC 通道的渲染器进程事件监听器，此处理器的返回值为 <strong id='theme-source'> 元素指定正确的文本。
'dark-mode:system' IPC 通道处理器方法将字符串 'system' 赋值到 themeSource 同时无返回值。 这也对应于相应的渲染器进程事件监听器，因为方法正在等待，且不需要返回值。
使用Electron Fiddle运行示例，然后点击“切换深色模式”按钮； 应用程序应该开始在亮色和黑色背景颜色之间交替。
\n
如果你在 Electron 中遇到问题或者引起崩溃，你认为它不是由你的JavaScript应用程序引起的，而是由 Electron 本身引起的。调试可能有点棘手，特别是对于不习惯 native/C++ 调试的开发人员。 However, using Visual Studio, Electron's hosted Symbol Server, and the Electron source code, you can enable step-through debugging with breakpoints inside Electron's source code.
\nSee also: There's a wealth of information on debugging Chromium, much of which also applies to Electron, on the Chromium developers site: Debugging Chromium on Windows.
\nElectron 的调试版本: 最简单的方法是自己构建它，使用 Windows 的构建说明中列出的工具和先决条件要求。 While you can attach to and debug Electron as you can download it directly, you will find that it is heavily optimized, making debugging substantially more difficult: The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations.
\nVisual Studio 与 C++ 工具: Visual Studio 2013 和 Visual Studio 2015 的免费社区版本都可以使用。 Once installed, configure Visual Studio to use Electron's Symbol server. 它将使 Visual Studio 能够更好地理解 Electron 中发生的事情，从而更容易以人类可读的格式呈现变量。
\nProcMon: 免费的 SysInternals 工具允许您检查进程参数，文件句柄和注册表操作。
\n要启动调试会话，请打开 PowerShell/CMD 并执行 Electron 的调试版本，使用应用程序作为参数打开。
\n$ ./out/Testing/electron.exe ~/my-electron-app/\n然后，打开 Visual Studio。 Electron 不是使用 Visual Studio 构建的，因此不包含项目文件 - 但是您可以打开源代码文件 \"As File\"，这意味着 Visual Studio 将自己打开它们。 您仍然可以设置断点 - Visual Studio 将自动确定源代码与附加过程中运行的代码相匹配，并相应地中断。
\nRelevant code files can be found in ./shell/.
您可以将 Visual Studio 调试器附加到本地或远程计算机上正在运行的进程。 进程运行后，单击 调试 / 附加 到进程(或按下 CTRL+ALT+P) 打开“附加到进程”对话框。 您可以使用此功能调试在本地或远程计算机上运行的应用程序，同时调试多个进程。
如果Electron在不同的用户帐户下运行，请选中 显示所有用户的进程 复选框。 请注意，根据您的应用程序打开的浏览器窗口数量，您将看到多个进程。 典型的单窗口应用程序将导致 Visual Studio 向您提供两个 Electron.exe 条目 - 一个用于主进程，一个用于渲染器进程。 因为列表只给你的名字，目前没有可靠的方法来弄清楚哪个是。
Code executed within the main process (that is, code found in or eventually run by your main JavaScript file) will run inside the main process, while other code will execute inside its respective renderer process.
\n您可以在调试时附加到多个程序，但在任何时候只有一个程序在调试器中处于活动状态。 您可以在 调试位置 工具栏或 进程窗口 中设置活动程序。
虽然 Visual Studio 非常适合检查特定的代码路径，但 ProcMon 的优势在于它可以监视应用程序对操作系统的所有操作 - 捕获进程的文件，注册表，网络，进程和分析详细信息。 它试图记录发生的 所有 事件，并且可能是相当压倒性的，而且果你想了解你的应用程序对操作系统做什么和如何做，它则是一个很有价值的资源。
\n有关 ProcMon 的基本和高级调试功能的介绍，请查看Microsoft提供的 视频教程.
", "title": "在 Windows 中调试", "description": "" }, "/docs/api/debugger": { "locale": "zh-CN", "slug": "debugger", "href": "/docs/api/debugger", "crowdinFileId": "256305", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/debugger.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n备用的 Chrome 远程调试接口。
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Chrome Developer Tools 在 JavaScript 运行时提供了一个 special binding , 允许与页面进行交互和检测。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\ntry {\n win.webContents.debugger.attach('1.1')\n} catch (err) {\n console.log('Debugger attach failed : ', err)\n}\n\nwin.webContents.debugger.on('detach', (event, reason) => {\n console.log('Debugger detached due to : ', reason)\n})\n\nwin.webContents.debugger.on('message', (event, method, params) => {\n if (method === 'Network.requestWillBeSent') {\n if (params.request.url === 'https://www.github.com') {\n win.webContents.debugger.detach()\n }\n }\n})\n\nwin.webContents.debugger.sendCommand('Network.enable')\n返回:
\nevent Eventreason String - 分离调试器的原因调试会话终止时激活 发生在对应的webContents 关闭或者调用 devtools 时,。
返回:
\nevent Eventmethod String - 方法名.params any - 远程调试协议中的 parameters 属性定义的事件参数。sessionId String - 附加调试会话的唯一标识符， 与从 debugger.sendCommand 中发送的值相同。当正在调试的目标发出条件检测事件时触发。
\ndebugger.attach([protocolVersion])protocolVersion String (optional) - 需要调试的协议的版本添加调试器到 webContents 。
debugger.isAttached()Returns Boolean - 表示调试器是否成功添加到 webContents 。
debugger.detach()从 webContents 里分离调试器.
debugger.sendCommand(method[, commandParams, sessionId])method String - 方法名称，应该是 远程调试协议中定义的方法之一。commandParams any (可选) - 具有请求参数的 JSON 对象。sessionId String (可选) - 发送带有调试会话id的命令给目标。 初始值可以通过发送 Target.attachToTarget 消息来获得。返回 Promise<any> - 一个 promise，远程调试协议中的命令描述的“returns”属性定义的响应，或者显示命令失败的错误消息。
向调试目标发送给定的命令。
", "title": "类: Debugger", "description": "备用的 Chrome 远程调试接口。" }, "/docs/development/debugging-instructions-macos": { "locale": "zh-CN", "slug": "debugging-instructions-macos", "href": "/docs/development/debugging-instructions-macos", "crowdinFileId": "256153", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "如果你在 Electron 中遇到问题或者引起崩溃，你认为它不是由你的JavaScript应用程序引起的，而是由 Electron 本身引起的。调试可能有点棘手，特别是对于不习惯 native/C++ 调试的开发人员。 然而，使用 lldb 和 Electron 源代码，可以在 Electron 的源代码中使用断点启用逐步调试。 如果您希望用图形界面的开发工具，也可以使用XCode for debugging。
\nElectron 的调试版本: 最简单的方法是自己构建它，使用 macOS 的构建说明 中列出的工具和先决条件要求。 While you can attach to and debug Electron as you can download it directly, you will find that it is heavily optimized, making debugging substantially more difficult: The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations.
\nXcode: 除了 Xcode，还安装 Xcode 命令行工具. They include LLDB, the default debugger in Xcode on macOS. It supports debugging C, Objective-C and C++ on the desktop and iOS devices and simulator.
\n.lldbinit: Create or edit ~/.lldbinit to allow Chromium code to be properly source-mapped.
# e.g: ['~/electron/src/tools/lldb']\nscript sys.path[:0] = ['<...path/to/electron/src/tools/lldb>']\nscript import lldbinit\nTo start a debugging session, open up Terminal and start lldb, passing a non-release build of Electron as a parameter.
$ lldb ./out/Testing/Electron.app\n(lldb) target create \"./out/Testing/Electron.app\"\nCurrent executable set to './out/Testing/Electron.app' (x86_64).\nLLDB是一个强大的工具，支持进行多种策略的代码检查。 在这做一个基本的介绍，让我们假设你从 JavaScript 调用一个不正常的命令 - 所以你想打断该命令的 C++ 对应的 Electron 源。
\nRelevant code files can be found in ./shell/.
让我们假设你想调试 app.setName(), 在 browser.cc 中定义为 Browser::SetName(). 使用 breakpoint 命令进行断点，指定文件和断点位置:
(lldb) breakpoint set --file browser.cc --line 117\nBreakpoint 1: where = Electron Framework`atom::Browser::SetName(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) + 20 at browser.cc:118, address = 0x000000000015fdb4\n然后, 启动 Electron:
\n(lldb) run\n应用程式会立即暂停，因为 Electron 会在启动时设定应用程序名称:
\n(lldb) run\nProcess 25244 launched: '/Users/fr/Code/electron/out/Testing/Electron.app/Contents/MacOS/Electron' (x86_64)\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1\n frame #0: 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118\n 115 }\n 116\n 117 void Browser::SetName(const std::string& name) {\n-> 118 name_override_ = name;\n 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n(lldb)\n显示当前帧的参数和局部变量, 运行 frame variable (或 fr v), 这将显示你的应用程序当前设置名称为 “Electron”.
(lldb) frame variable\n(atom::Browser *) this = 0x0000000108b14f20\n(const string &) name = \"Electron\": {\n [...]\n}\n在当前选择的线程中执行源级单步执行, 执行 step (或 s). 这将带你进入 name_override_.empty()。 继续前进，步过，运行 next (或 n).
(lldb) step\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162dcc Electron Framework`atom::Browser::SetName(\n this=0x0000000108b14f20, name=\"Electron\"\n) + 44 at browser.cc:119, queue = 'com.apple.main-thread', stop reason = step in\n frame #0: 0x0000000100162dcc Electron Framework`atom::Browser::SetName(\n this=0x0000000108b14f20, name=\"Electron\"\n) + 44 at browser.cc:119\n 116\n 117 void Browser::SetName(const std::string& name) {\n 118 name_override_ = name;\n-> 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n 122 return badge_count_;\nNOTE: If you don't see source code when you think you should, you may not have added the ~/.lldbinit file above.
要完成此时的调试，运行 process continue。 你也可以继续，直到这个线程中的某一行被命中(线程直到100)。 此命令将在当前帧中运行线程，直到它到达此帧中的行100，或者如果它离开当前帧，则停止。
现在，如果你打开 Electron 的开发工具并调用 setName，你将再次命中断点。
LLDB是一个强大的工具，有一个庞大的文档。 To learn more about it, consider Apple's debugging documentation, for instance the LLDB Command Structure Reference or the introduction to Using LLDB as a Standalone Debugger.
\nYou can also check out LLDB's fantastic manual and tutorial, which will explain more complex debugging scenarios.
", "title": "在 macOS 中调试", "description": "" }, "/docs/development/debugging-instructions-macos-xcode": { "locale": "zh-CN", "slug": "debugging-instructions-macos-xcode", "href": "/docs/development/debugging-instructions-macos-xcode", "crowdinFileId": "256151", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos-xcode.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "运行 gn gen 并带上 --ide=xcode 参数
$ gn gen out/Testing --ide=xcode\n这会生成 electron.ninja.xcworkspace。 您需要打开这个工作区来设置断点和检查。
\nSee gn help gen for more information on generating IDE projects with GN.
Launch Electron app after build. You can now open the xcode workspace created above and attach to the Electron process through the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug the renderer process, you need to attach to the Electron Helper as well.]
\nYou can now set breakpoints in any of the indexed files. However, you will not be able to set breakpoints directly in the Chromium source. To set break points in the Chromium source, you can choose Debug > Breakpoints > Create Symbolic Breakpoint and set any function name as the symbol. This will set the breakpoint for all functions with that name, from all the classes if there are more than one. You can also do this step of setting break points prior to attaching the debugger, however, actual breakpoints for symbolic breakpoint functions may not show up until the debugger is attached to the app.
", "title": "使用 XCode 调试", "description": "" }, "/docs/tutorial/debugging-main-process": { "locale": "zh-CN", "slug": "debugging-main-process", "href": "/docs/tutorial/debugging-main-process", "crowdinFileId": "256189", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/debugging-main-process.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron 浏览器窗口中的 DevTools 只能调试 在该窗口中执行的 JavaScript (即 web 页面) 。 为了提供一个可以调试主进程的方法，Electron 提供了 --inspect 和 --inspect-brk 开关。
使用如下的命令行开关来调试 Electron 的主进程：
\n--inspect=[port]Electron will listen for V8 inspector protocol messages on the specified port, an external debugger will need to connect on this port. The default port is 5858.
electron --inspect=5858 your/app\n--inspect-brk=[port]和--inspector 一样，但是会在JavaScript 脚本的第一行暂停运行。
你需要使用一个支持 V8 调试协议的调试器
\nchrome://inspect 来连接 Chrome 并在那里选择需要检查的Electron 应用程序。本指南将介绍如何使用 VSCode debugging 为您自己的 Electron 项目和 native Electron 代码库（Electron codebase）调试。
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json，内容为{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"Debug Main Process\",\n \"type\": \"node\",\n \"request\": \"launch\",\n \"cwd\": \"${workspaceFolder}\",\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron\",\n \"windows\": {\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron.cmd\"\n },\n \"args\" : [\".\"]\n }\n ]\n}\n在 main.js 中设置一些断点，并在 调试视图 中开始调试. 您应该能够点击断点。
这是一个预先配置好了的项目，你可以下载并直接在 VSCode 中调试：https://github.com/octref/vscode-electron-debug/tree/master/electron-quick-start
\n如果您想从源代码构建 Electron 并修改 native Electron 代码库，本节将帮助您测试您的修改。
\n对于那些不确定在哪里获得代码或如何构建它， Electron 的构建工具 自动化并解释此过程的大部分。 如果你想手动设置环境，你可以使用这些 构建指令。
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json，内容为{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"(Windows) Launch\",\n \"type\": \"cppvsdbg\",\n \"request\": \"launch\",\n \"program\": \"${workspaceFolder}\\\\out\\\\your-executable-location\\\\electron.exe\",\n \"args\": [\"your-electron-project-path\"],\n \"stopAtEntry\": false,\n \"cwd\": \"${workspaceFolder}\",\n \"environment\": [\n {\"name\": \"ELECTRON_ENABLE_LOGGING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_ENABLE_STACK_DUMPING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_RUN_AS_NODE\", \"value\": \"\"},\n ],\n \"externalConsole\": false,\n \"sourceFileMap\": {\n \"o:\\\\\": \"${workspaceFolder}\",\n },\n },\n ]\n}\n配置说明
\ncppvsdbg 需要启用 内置的 C/C++ 扩展。${workspaceFolder} 是 Chromium 的 源 的完整路径。your-executable-location 将是以下几项之一：Testing：如果您使用的是默认的 Electron 构建工具 设置，或默认的 从源端构建 的设置。Release：如果你构建了一个发布版本，而不是测试版本。your-directory-name：如果你在构建过程中修改， 这将是你指定的。args 数组字符串 \"your electron-project-path\" 应为您正在用于测试的 Electron 项目或 main.js 的绝对路径。 在本示例中，它应该是您的 electron-quick-start 的路径。在你选择的原始 Electron C++ 代码中的 .cc 文件中设置一些断点，并在 Debug View 中开始调试。
", "title": "使用 VsCode调试", "description": "" }, "/docs/api/desktop-capturer": { "locale": "zh-CN", "slug": "desktop-capturer", "href": "/docs/api/desktop-capturer", "crowdinFileId": "256307", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/desktop-capturer.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n\n访问关于使用
\nnavigator.mediaDevices.getUserMediaAPI 获取的可以用来从桌面捕获音频和视频的媒体源的信息。
下面的示例演示如何从标题为 Electron 的桌面窗口捕获视频:
// In the renderer process.\nconst { desktopCapturer } = require('electron')\n\ndesktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources => {\n for (const source of sources) {\n if (source.name === 'Electron') {\n try {\n const stream = await navigator.mediaDevices.getUserMedia({\n audio: false,\n video: {\n mandatory: {\n chromeMediaSource: 'desktop',\n chromeMediaSourceId: source.id,\n minWidth: 1280,\n maxWidth: 1280,\n minHeight: 720,\n maxHeight: 720\n }\n }\n })\n handleStream(stream)\n } catch (e) {\n handleError(e)\n }\n return\n }\n }\n})\n\nfunction handleStream (stream) {\n const video = document.querySelector('video')\n video.srcObject = stream\n video.onloadedmetadata = (e) => video.play()\n}\n\nfunction handleError (e) {\n console.log(e)\n}\n为了从desktopCapturer提供的源捕获视频，传递给 navigator.mediaDevices.getUserMedia 的约束条件需包括 chromeMediaSource: 'desktop' 和 audio: false。
为了同时捕获整个桌面的音视频，传递给 navigator.mediaDevices.getUserMedia 的约束条件需包括 chromeMediaSource: 'desktop'，audio 和 视频，但不应该包括 chromeMediaSourceId 约束。
const constraints = {\n audio: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n },\n video: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n }\n}\ndesktopCapturer 模块有以下方法:
desktopCapturer.getSources(options)选项 对象 类型String[]-列出要捕获的桌面源类型的字符串数组, 可用类型为 screen 和 window。thumbnailSizeSize(可选) - 媒体源缩略图应缩放到的尺寸大小。 默认是 150 x 150。 当您不需要缩略图时，设置宽度或高度为0。 这将节省用于获取每个窗口和屏幕内容时的处理时间。fetchWindowIcons Boolean (可选) - 设置为true以便启用获取窗口图标。 默认值为false。 当值为false时，源的appIcon属性返回null。 如果一个源是屏幕类型也是如此。返回 Promise<DesktopCapturerSource[]> - resolve 一个DesktopCapturerSource 对象类型的数组，每个 DesktopCapturerSource 代表一个屏幕或一个可以被捕获的独立窗口。
注意 在macOS 10.15 Catalina 或更高版本上捕获屏幕内容需要用户同意，可通过 systemPreferences.getMediaAccessStatus 检测是否授权。
由于存在基本限制，因此navigator.mediaDevices.getUserMedia 无法在macOS上进行音频捕获，因此要访问系统音频的应用程序需要一个签名内核拓展. Chromium以及Electron扩展不提供这个。
通过使用另一个MacOS应用程序（如Soundflower）捕获系统音频并将其通过虚拟音频输入设备来规避此限制是可能的。 然后可以用 navigator.mediaDevices.getUserMedia查询该虚拟设备。
id String - The identifier of a window or screen that can be used as a chromeMediaSourceId constraint when calling [navigator.webkitGetUserMedia]. The format of the identifier will be window:XX:YY or screen:ZZ:0. XX is the windowID/handle. YY is 1 for the current process, and 0 for all others. ZZ is a sequential number that represents the screen, and it does not equal to the index in the source's name.name String - A screen source will be named either Entire Screen or Screen <index>, while the name of a window source will match the window title.thumbnail NativeImage - A thumbnail image. Note: There is no guarantee that the size of the thumbnail is the same as the thumbnailSize specified in the options passed to desktopCapturer.getSources. The actual size depends on the scale of the screen or window.display_id String - A unique identifier that will correspond to the id of the matching Display returned by the Screen API. On some platforms, this is equivalent to the XX portion of the id field above and on others it will differ. It will be an empty string if not available.appIcon NativeImage - An icon image of the application that owns the window or null if the source has a type screen. The size of the icon is not known in advance and depends on what the application provides.Like Chromium based browsers, Electron provides access to device hardware through web APIs. For the most part these APIs work like they do in a browser, but there are some differences that need to be taken into account. The primary difference between Electron and browsers is what happens when device access is requested. In a browser, users are presented with a popup where they can grant access to an individual device. In Electron APIs are provided which can be used by a developer to either automatically pick a device or prompt users to pick a device via a developer created interface.
\nThe Web Bluetooth API can be used to communicate with bluetooth devices. In order to use this API in Electron, developers will need to handle the select-bluetooth-device event on the webContents associated with the device request.
This example demonstrates an Electron application that automatically selects the first available bluetooth device when the Test Bluetooth button is clicked.
The WebHID API can be used to access HID devices such as keyboards and gamepads. Electron provides several APIs for working with the WebHID API:
\nselect-hid-device event on the Session can be used to select a HID device when a call to navigator.hid.requestDevice is made. Additionally the hid-device-added and hid-device-removed events on the Session can be used to handle devices being plugged in or unplugged during the navigator.hid.requestDevice process.ses.setDevicePermissionHandler(handler) can be used to provide default permissioning to devices without first calling for permission to devices via navigator.hid.requestDevice. Additionally, the default behavior of Electron is to store granted device permision through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.ses.setPermissionCheckHandler(handler) can be used to disable HID access for specific origins.By default Electron employs the same blocklist used by Chromium. If you wish to override this behavior, you can do so by setting the disable-hid-blocklist flag:
app.commandLine.appendSwitch('disable-hid-blocklist')\nThis example demonstrates an Electron application that automatically selects HID devices through ses.setDevicePermissionHandler(handler) and through select-hid-device event on the Session when the Test WebHID button is clicked.
The Web Serial API can be used to access serial devices that are connected via serial port, USB, or Bluetooth. In order to use this API in Electron, developers will need to handle the select-serial-port event on the Session associated with the serial port request.
There are several additional APIs for working with the Web Serial API:
\nserial-port-added and serial-port-removed events on the Session can be used to handle devices being plugged in or unplugged during the navigator.serial.requestPort process.ses.setPermissionCheckHandler(handler) can be used to disable serial access for specific origins.This example demonstrates an Electron application that automatically selects the first available Arduino Uno serial device (if connected) through select-serial-port event on the Session when the Test Web Serial button is clicked.
Electron supports Chrome DevTools extensions, which can be used to extend the ability of Chrome's developer tools for debugging popular web frameworks.
\n加载 DevTools 扩展的最简单方法是使用第三方工具，来为您实现自动化过程。 electron-devtools-installer 是一个受欢迎的 NPM 包。
\n如果你不想使用工具加载，你也可以手动完成所有必需的操作。 要在 Electron 中加载扩展，您需要在 Chrome 下载它，找到其文件系统路径，然后通过调用[ses.loadExtension] API 将其加载到您的 Session 中。
下面以React Developer Tools为例：
\n在 Google Chrome 中安装扩展。
\n打开chrome://extensions，找到扩展程序的ID，像 fmkadmapgofadopljbjfkapdkoienihi 一样的 hash 字符串。
找到 Chrome 扩展程序的存放目录：
\n%LOCALAPPDATA%\\Google\\Chrome\\User Data\\Default\\Extensions;~/.config/google-chrome/Default/Extensions/~/.config/google-chrome-beta/Default/Extensions/~/.config/google-chrome-canary/Default/Extensions/~/.config/chromium/Default/Extensions/~/Library/Application Support/Google/Chrome/Default/Extensions。将扩展的位置传递给 ses.loadExtension API。 对于 React Developer Tools v4.9.0, 它看起来像：
const { app, session } = require('electron')\n const path = require('path')\n const os = require('os')\n\n // on macOS\n const reactDevToolsPath = path.join(\n os.homedir(),\n '/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.9.0_0'\n )\n\n app.whenReady().then(async () => {\n await session.defaultSession.loadExtension(reactDevToolsPath)\n })\n说明：
\nloadExtension 返回一个包含 扩展对象 的 Promise，其中包含加载的扩展有关的元数据。 在加载页面前，此 Promise 需要被 resolve（例如使用 await 表达式）。 否则将无法保证扩展被加载。loadExtension 无法在 app 模块 ready 之前调用，也不能被内存(非持久) 会话调用。loadExtension 。您可以将扩展的 ID 传递给 ses.removeExtension API，以将其从您的 Session 中删除。 每次应用重新启动，扩展不会持续。
Electron 仅支持 有限的 chrome.* APIs ，所以使用不支持的 chrome.* 扩展的 APIs 可能无法工作。
以下 DevTools 扩展程序已经通过测试，可以在 Electron 中正常工作：
\n首先，请确保扩展仍在维护中，并与最新版本的 Google Chrome 兼容。 我们不能为不受支持的扩展提供额外支持。
\n如果扩展可以在 Chrome 上运行，但不能在 Electron 上运行， 在 Electron 的 issue Tracker 中提交一个错误，并描述扩展的哪个部分不能按预期工作。
", "title": "开发者工具扩展", "description": "" }, "/docs/api/dialog": { "locale": "zh-CN", "slug": "dialog", "href": "/docs/api/dialog", "crowdinFileId": "256309", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/dialog.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n显示用于打开和保存文件、警报等的本机系统对话框。
\n
进程：主进程
\n下面是一个选择多个文件的对话框示例：
\nconst { dialog } = require('electron')\nconsole.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))\ndialog 模块具有以下方法:
dialog.showOpenDialogSync([browserWindow, ]options)browserWindow BrowserWindow (可选)选项 对象title String (可选) - 对话框窗口的标题defaultPath String (可选) - 对话框的默认展示路径buttonLabel String (可选) - 「确认」按钮的自定义标签, 当为空时, 将使用默认标签。filters FileFilter[] (可选)properties String[] (可选) - 包含对话框相关属性。 支持以下属性值:openFile - 允许选择文件openDirectory - 允许选择文件夹multiSelections-允许多选。showHiddenFiles-显示对话框中的隐藏文件。createDirectory macOS -允许你通过对话框的形式创建新的目录。promptToCreate Windows-如果输入的文件路径在对话框中不存在, 则提示创建。 这并不是真的在路径上创建一个文件，而是允许返回一些不存在的地址交由应用程序去创建。noResolveAliases macOS-禁用自动的别名路径(符号链接) 解析。 所选别名现在将会返回别名路径而非其目标路径。treatPackageAsDirectory macOS -将包 (如 .app 文件夹) 视为目录而不是文件。dontAddToRecent Windows - 不要将正在打开的项目添加到最近的文档列表中。message String (可选) macOS -显示在输入框上方的消息。securityScopedBookmarks Boolean (可选) macOS mas - 在打包提交到Mac App Store时创建 security scoped bookmarks返回 String[] | undefined, 用户选择的文件路径，如果对话框被取消了 ，则返回undefined。
browserWindow 参数允许该对话框将自身附加到父窗口, 作为父窗口的模态框。
filters 指定一个文件类型数组，用于规定用户可见或可选的特定类型范围。 例如：
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nextensions 数组应为没有通配符或点的扩展名 (例如, \"png\" 是正确的, 而 \".png\" 和 *. png \" 就是错误的)。 若要显示所有文件, 请使用 \"*\" 通配符 (不支持其他通配符)。
注意: 在 Windows 和 Linux 上, 打开对话框不能同时是文件选择器和目录选择器, 因此如果在这些平台上将 properties 设置为[\"openFile\"、\"openDirectory\"], 则将显示为目录选择器。
dialog.showOpenDialogSync(mainWindow, {\n properties: ['openFile', 'openDirectory']\n})\ndialog.showOpenDialog([browserWindow, ]options)browserWindow BrowserWindow (可选)选项 对象title String (可选) - 对话框窗口的标题defaultPath String (可选) - 对话框的默认展示路径buttonLabel String (可选) - 「确认」按钮的自定义标签, 当为空时, 将使用默认标签。filters FileFilter[] (可选)properties String[] (可选) - 包含对话框相关属性。 支持以下属性值:openFile - 允许选择文件openDirectory - 允许选择文件夹multiSelections-允许多选。showHiddenFiles-显示对话框中的隐藏文件。createDirectory macOS -允许你通过对话框的形式创建新的目录。promptToCreate Windows-如果输入的文件路径在对话框中不存在, 则提示创建。 这并不是真的在路径上创建一个文件，而是允许返回一些不存在的地址交由应用程序去创建。noResolveAliases macOS-禁用自动的别名路径(符号链接) 解析。 所选别名现在将会返回别名路径而非其目标路径。treatPackageAsDirectory macOS -将包 (如 .app 文件夹) 视为目录而不是文件。dontAddToRecent Windows - 不要将正在打开的项目添加到最近的文档列表中。message String (可选) macOS -显示在输入框上方的消息。securityScopedBookmarks Boolean (可选) macOS mas - 在打包提交到Mac App Store时创建 security scoped bookmarks返回 Promise<Object> - resolve包含以下内容的object：
canceled Boolean - 对话框是否被取消。filePaths String[] - 用户选择的文件路径的数组. 如果对话框被取消，这将是一个空的数组。bookmarks String[] (optional) macOS mas - 一个数组， filePaths 数组，base64编码字符串包含安全范围书签数据。 securityScopedBookmarks 必须启用才能捕获数据。 (返回值见 这里的表格。)browserWindow 参数允许该对话框将自身附加到父窗口, 作为父窗口的模态框。
filters 指定一个文件类型数组，用于规定用户可见或可选的特定类型范围。 例如：
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nextensions 数组应为没有通配符或点的扩展名 (例如, \"png\" 是正确的, 而 \".png\" 和 *. png \" 就是错误的)。 若要显示所有文件, 请使用 \"*\" 通配符 (不支持其他通配符)。
注意: 在 Windows 和 Linux 上, 打开对话框不能同时是文件选择器和目录选择器, 因此如果在这些平台上将 properties 设置为[\"openFile\"、\"openDirectory\"], 则将显示为目录选择器。
dialog.showOpenDialog(mainWindow, {\n properties: ['openFile', 'openDirectory']\n}).then(result => {\n console.log(result.canceled)\n console.log(result.filePaths)\n}).catch(err => {\n console.log(err)\n})\ndialog.showSaveDialogSync([browserWindow, ]options)browserWindow BrowserWindow (可选)选项 对象title String (可选) - 对话框标题。 无法在一些 Linux 桌面环境中显示。defaultPath String (可选) - 默认情况下使用的绝对目录路径、绝对文件路径或文件名。buttonLabel String (可选) - 「确认」按钮的自定义标签, 当为空时, 将使用默认标签。filters FileFilter[] (可选)message String (可选) macOS -显示在对话框上的消息。nameFieldLabel String (可选) macOS - 文件名输入框对应的自定义标签名。showsTagField Boolean (可选) macOS -显示标记输入框, 默认为 true。properties String[] (可选)showHiddenFiles-显示对话框中的隐藏文件。createDirectory macOS -允许你通过对话框的形式创建新的目录。treatPackageAsDirectory macOS -将包 (如 .app 文件夹) 视为目录而不是文件。showOverwriteConfirmation Linux - 设置如果用户输入了已存在的文件名，是否会向用户显示确认对话框。dontAddToRecent Windows - 不要将正在保存的项目添加到最近的文档列表中。securityScopedBookmarks Boolean (可选) macOS mas - 在打包提交到Mac App Store时创建 security scoped bookmarks 当该选项被启用且文件尚不存在时，那么在选定的路径下将创建一个空文件。返回 String | undefined, 用户选择的文件路径，如果对话框被取消了 ，则返回undefined。
browserWindow 参数允许该对话框将自身附加到父窗口, 作为父窗口的模态框。
filters 可以指定可显示文件的数组类型，详见 dialog.showOpenDialog 事例
dialog.showSaveDialog([browserWindow, ]options)browserWindow BrowserWindow (可选)选项 对象title String (可选) - 对话框标题。 无法在一些 Linux 桌面环境中显示。defaultPath String (可选) - 默认情况下使用的绝对目录路径、绝对文件路径或文件名。buttonLabel String (可选) - 「确认」按钮的自定义标签, 当为空时, 将使用默认标签。filters FileFilter[] (可选)message String (可选) macOS -显示在对话框上的消息。nameFieldLabel String (可选) macOS - 文件名输入框对应的自定义标签名。showsTagField Boolean (可选) macOS - 显示标签输入框，默认为 true。properties String[] (可选)showHiddenFiles-显示对话框中的隐藏文件。createDirectory macOS -允许你通过对话框的形式创建新的目录。treatPackageAsDirectory macOS -将包 (如 .app 文件夹) 视为目录而不是文件。showOverwriteConfirmation Linux - 设置如果用户输入了已存在的文件名，是否会向用户显示确认对话框。dontAddToRecent Windows - 不要将正在保存的项目添加到最近的文档列表中。securityScopedBookmarks Boolean (可选) macOS mas - 在打包提交到Mac App Store时创建 security scoped bookmarks 当该选项被启用且文件尚不存在时，那么在选定的路径下将创建一个空文件。返回 Promise<Object> - resolve包含以下内容的object：
canceled Boolean - 对话框是否被取消。filePath String (可选) - 如果对话框被取消，该值为 undefined。bookmark String(optional) macOS mas - 包含了安全作用域的书签数据 Base64 编码的字符串来保存文件。 securityScopedBookmarks 必须启用才有效。 (返回值见 这里的表格。)browserWindow 参数允许该对话框将自身附加到父窗口, 作为父窗口的模态框。
filters 可以指定可显示文件的数组类型，详见 dialog.showOpenDialog 事例
注意： 在macOS上，建议使用异步版本，以避免展开和折叠对话框时出现问题。
\ndialog.showMessageBoxSync([browserWindow, ]options)browserWindow BrowserWindow (可选)选项 对象message String - message box 的内容.type String (可选) - 可以为 \"none\", \"info\", \"error\", \"question\" 或者 \"warning\". 在 Windows 上, \"question\" 与\"info\"显示相同的图标, 除非你使用了 \"icon\" 选项设置图标。 在 macOS 上, \"warning\" 和 \"error\" 显示相同的警告图标buttons String[] (可选) - 按钮文本数组。 在 Windows上，一个空数组将导致按钮被标为“OK”。defaultId Integer (可选) - 在 message box 对话框打开的时候，设置默认选中的按钮，值为在 buttons 数组中的索引.title String (可选) - message box 的标题，一些平台不显示.detail String (可选) - 额外信息.icon (NativeImage | String) (可选)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (可选) - 用于取消对话框的按钮的索引，例如 Esc 键. 默认情况下，它被分配给第一个按钮，文字为 “cancel” 或 “no”。 如果不存在这个标签的按钮，同时该选项又未设置，返回值为0。noLink Boolean (可选) - 在Windows上，应用将尝试找出哪个 buttons 是常用按钮(例如 \"Cancel\" 或 \"Yes\")，然后在对话框中以链接命令的方式展现其它的按钮。 这可以使对话框以现代Windows应用程序的风格显示。 如果你不喜欢这个行为, 你可以设置 noLink 为 true.normalizeAccessKeys Boolean (可选) -规范跨平台的键盘访问键。 默认值为 false. 用 & 连接和转换键盘访问键, 以便它们在每个平台上正常工作.& 字符会在macOS上被删除，在 Linux 上会被转换为 _，在 Windows 上保持不变。 例如 Vie&w 的按钮标签在 Linux 上会被转换为 Vie_w，在 macOS 转换为 View 并且可以被选择。而Windows和Linux上表示 Alt-W 。返回 Integer - 点击的按钮的索引。
显示一个消息框，它将阻塞进程直到消息框关闭。 它返回点击的按钮的索引。
\nbrowserWindow 参数允许该对话框将自身附加到父窗口, 作为父窗口的模态框。 如果 浏览器窗口 没有显示，则对话框不会附属于它。 在这种情况想，它将作为一个独立的窗口显示。
dialog.showMessageBox([browserWindow, ]options)browserWindow BrowserWindow (可选)选项 对象message String - message box 的内容.type String (可选) - 可以为 \"none\", \"info\", \"error\", \"question\" 或者 \"warning\". 在 Windows 上, \"question\" 与\"info\"显示相同的图标, 除非你使用了 \"icon\" 选项设置图标。 在 macOS 上, \"warning\" 和 \"error\" 显示相同的警告图标buttons String[] (可选) - 按钮文本数组。 在 Windows上，一个空数组将导致按钮被标为“OK”。defaultId Integer (可选) - 在 message box 对话框打开的时候，设置默认选中的按钮，值为在 buttons 数组中的索引.signal AbortSignal (optional) - Pass an instance of AbortSignal to optionally close the message box, the message box will behave as if it was cancelled by the user. On macOS, signal does not work with message boxes that do not have a parent window, since those message boxes run synchronously due to platform limitations.title String (可选) - message box 的标题，一些平台不显示.detail String (可选) - 额外信息.checkboxLabel String (可选) - 如果使用了，消息框将包含带有给定标签的复选框。checkboxChecked Boolean (可选) - checkbox 的初始值。 默认值为 falseicon NativeImage (可选)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (可选) - 用于取消对话框的按钮的索引，例如 Esc 键. 默认情况下，它被分配给第一个按钮，文字为 “cancel” 或 “no”。 如果不存在这个标签的按钮，同时该选项又未设置，返回值为0。noLink Boolean (可选) - 在Windows上，应用将尝试找出哪个 buttons 是常用按钮(例如 \"Cancel\" 或 \"Yes\")，然后在对话框中以链接命令的方式展现其它的按钮。 这可以使对话框以现代Windows应用程序的风格显示。 如果你不喜欢这个行为, 你可以设置 noLink 为 true.normalizeAccessKeys Boolean (可选) -规范跨平台的键盘访问键。 默认值为 false. 用 & 连接和转换键盘访问键, 以便它们在每个平台上正常工作.& 字符会在macOS上被删除，在 Linux 上会被转换为 _，在 Windows 上保持不变。 例如 Vie&w 的按钮标签在 Linux 上会被转换为 Vie_w，在 macOS 转换为 View 并且可以被选择。而Windows和Linux上表示 Alt-W 。返回 Promise<Object> - resolve包含以下属性的promise：
response Number - 点击的按钮的索引。checkboxChecked Boolean - 如果设置了 checkboxLabel，返回复选框是否被选中的状态。 否则，返回 false。显示一个消息框
\nbrowserWindow 参数允许该对话框将自身附加到父窗口, 作为父窗口的模态框。
dialog.showErrorBox(title, content)title String - 显示在错误框中的标题.content String - 显示在错误框中的文本内容.显示一个显示错误消息的模态对话框。
\n这个API可以在 app 模块触发 ready 事件之前被安全地调用，它通常用在启动时报告错误。 在 Linux 上, ready 事件之前调用这个API, 消息将被发送到stderr, 并且不会出现GUI对话框。
dialog.showCertificateTrustDialog([browserWindow, ]options) macOS WindowsbrowserWindow BrowserWindow (可选)选项 对象certificate Certificate - 信任/导入的证书message String - 要向用户显示的消息返回 Promise<void> - 当显示信任证书对话框时resolve。
在macOS中, 将弹出一个用于展示消息与证书信息并向用户提供信任/导入证书的选项的模态对话框。 如果提供 browserWindow 参数, 则该对话框将附加到父窗口, 使其成模态框。
在Windows中, 受限于Win32 API，可选项变得更为有限:
\nmessage 参数无效，因为操作系统提供了自身的确认对话框。browserWindow 参数被忽略，因此无法成为模态对话框。showOpenDialog、 showOpenDialogSync、 showSaveDialog和 showSaveDialogSync 将返回一个 bookmarks 数组。
| 构建类型 | securityScopedBookmarks boolean | 返回类型 | 返回值 |
|---|---|---|---|
| macOS mas | True | 成功 | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | Error | [''] (空字符串数组) |
| macOS mas | False | NA | [] (空数组) |
| non mas | any | NA | [] (空数组) |
在MaCOS中，如果在<0>browserWindow</0>的参数中提供<0>BrowerWindow</0>这一参数，或者在非<0>browserWindow</0>中未提供<0>modals</0>参数，则将对附加到<0>window</0>中的<0>sheet</0>的形式呈现。
您可以调用 BrowserWindow.getCurrentWindow().setSheetOffset(offset) 来更改附加工作表的窗口框架的偏移量。
id Number - Unique identifier associated with the display.rotation Number - Can be 0, 90, 180, 270, represents screen rotation in clock-wise degrees.scaleFactor Number - Output device's pixel scale factor.touchSupport String - Can be available, unavailable, unknown.monochrome Boolean - Whether or not the display is a monochrome display.accelerometerSupport String - Can be available, unavailable, unknown.colorSpace String - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversionscolorDepth Number - The number of bits per pixel.depthPerComponent Number - The number of bits per color component.displayFrequency Number - The display refresh rate.bounds Rectangle - the bounds of the display in DIP points.size SizeworkArea Rectangle - the work area of the display in DIP points.workAreaSize Sizeinternal Boolean - true for an internal display and false for an external displayThe Display object represents a physical display connected to the system. A fake Display may exist on a headless system, or a Display may correspond to a remote, virtual display.
\n\n在 macOS dock中控制您的应用
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
下面的例子展示了如何在dock上使你的图标弹跳。
\nconst { app } = require('electron')\napp.dock.bounce()\ndock.bounce([type]) macOStype String (可选) - 可以是 critical 或 informational。 默认值为informational返回 Integer - 代表请求的 ID。
当传入的是 critical 时, dock 中的应用将会开始弹跳, 直到这个应用被激活或者这个请求被取消。
当传递了 informational 时，dock图标将弹跳一秒钟。 然而，该请求仍然有效，直到应用程序激活或请求被取消。
注意： 此方法只能在应用未获得焦点时使用；当应用获得焦点，该方法将返回 -1。
\ndock.cancelBounce(id) macOSid Integer取消这个 id 对应的请求。
dock.downloadFinished(filePath) macOSfilePath String如果 filePath 位于 Downloads 文件夹中，则弹出下载队列。
\ndock.setBadge(text) macOStext String设置应用在 dock 中显示的字符串。
\ndock.getBadge() macOS返回 String - 应用在 dock 中显示的字符串。
dock.hide() macOS隐藏 dock 中的图标。
\ndock.show() macOS返回 Promise<void> - 当dock图标显示时resolve。
dock.isVisible() macOS返回 Boolean - dock图标是否可见.
dock.setMenu(menu) macOSmenu Menu设置应用程序的 [dock 菜单][dock-menu]。
\ndock.getMenu() macOS返回 Menu | null - 应用程序的[dock 菜单][dock-menu]。
dock.setIcon(image) macOSimage (NativeImage | String)设置image作为应用在 dock 中显示的图标
\n\n控制来自于远程资源的文件下载。
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
DownloadItem 是一个 EventEmitter 事件触发器，在Electron中代表一个下载项。 它用于will-download事件以及Session类，并且允许用户控制下载项目。
// 在主进程中.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.session.on('will-download', (event, item, webContents) => {\n // 无需对话框提示， 直接将文件保存到路径\n item.setSavePath('/tmp/save.pdf')\n\n item.on('updated', (event, state) => {\n if (state === 'interrupted') {\n console.log('Download is interrupted but can be resumed')\n } else if (state === 'progressing') {\n if (item.isPaused()) {\n console.log('Download is paused')\n } else {\n console.log(`Received bytes: ${item.getReceivedBytes()}`)\n }\n }\n })\n item.once('done', (event, state) => {\n if (state === 'completed') {\n console.log('Download successfully')\n } else {\n console.log(`Download failed: ${state}`)\n }\n })\n})\n返回:
\nevent Eventstate String - 可以是 progressing 或 interrupted.当下载正在执行但还没完成的时候发出。
\n状态可以是以下之一：
\nprogressing - 下载正在进行中interrupted - 下载已经中断，可以恢复返回:
\nevent Eventstate String - 可以是 completed, cancelled 或 interrupted.当下载处于终止态时触发。 包括下载完成，取消下载 (通过 downloadItem.cancel())，以及无法恢复的中断下载。
状态可以是以下之一：
\ncompleted - 下载成功完成cancelled - 下载已被取消interrupted - 下载已经中断，无法恢复downloadItem 对象具有以下方法：
downloadItem.setSavePath(path)path String - 设置下载项目的保存文件路径。该API仅能在will-download 方法的回调中使用。 如果 path 不存在，Electron 将尝试递归创建目录。 如果用户没有通过这个API设置保存路径，Electron 将使用默认方式决定保存路径；通常弹出保存对话框。
downloadItem.getSavePath()返回String - 下载项的保存路径。 该值为通过 downloadItem.setSavePath(path) 设置的路径或通过显示的保存对话框选择的路径。
downloadItem.setSaveDialogOptions(options)options SaveDialogOptions - 设置保存文件对话框选项。 这个对象与 dialog.showSaveDialog() 的 options 参数有相同属性。此 API 允许用户为下载项默认打开的保存对话框设置自定义选项。 该API仅能在will-download 方法的回调中使用。
downloadItem.getSaveDialogOptions()返回 SaveDialogOptions - 返回之前通过 downloadItem.setSaveDialogOptions(options) 设置的对象。
downloadItem.pause()暂停下载。
\ndownloadItem.isPaused()Returns Boolean - Whether the download is paused.
downloadItem.resume()Resumes the download that has been paused.
\n注意： 为了支持断点续传，必须要从支持范围请求的服务器下载，并且提供Last-Modified 和 ETag的头部值。 否则，resume() 将关闭以前接收到的字节并从头开始重新开始下载。
downloadItem.canResume()返回Boolean - 下载是否可以恢复。
downloadItem.cancel()取消下载操作。
\ndownloadItem.getURL()返回String - 下载项的源URL。
downloadItem.getMimeType()返回String - MIME类型的文件。
downloadItem.hasUserGesture()返回Boolean - 下载是否具有用户手势。
downloadItem.getFilename()返回String - 下载项目的文件名。
注意： 文件名并不总是和实际保存到本地磁盘中的文件名相同。 如果用户在提示的下载保存对话框中更改文件名称，保存的文件的实际名称将会不同。
\ndownloadItem.getTotalBytes()返回Integer - 下载项目的总大小（以字节为单位）。
如果大小未知，则返回0。
\ndownloadItem.getReceivedBytes()返回Integer - 下载项目的接收字节。
downloadItem.getContentDisposition()返回String - 响应头中的Content-Disposition字段。
downloadItem.getState()返回 String - 当前状态。 可以是 progressing、 completed、 cancelled 或 interrupted。
注意： 以下方法尤其对于当会话重启后恢复 取消了的 项目非常有用。
downloadItem.getURLChain()返回 String[] - 项目的完整URL链，包括任何重定向。
downloadItem.getLastModifiedTime()返回String - Last-Modified的值。
\ndownloadItem.getETag()返回String - ETag的值。
\ndownloadItem.getStartTime()返回Double - 自下载开始时的UNIX纪元以来的秒数。
downloadItem.savePath一个 String 属性，决定了下载项的保存文件路径。
该属性仅在会话的 will-download 回调函数中可用。 如果用户未通过属性设置保存路径，Electron将使用默认方式决定保存路径；通常为弹出保存对话框。
Special notes:
\n-beta.1和稳定版日期是我们的具体的发布日期。| Electron | Alpha | 测试版 | Stable | Chrome | Node |
|---|---|---|---|---|---|
| 2.0.0 | -- | 2018-Feb-21 | 2018-May-01 | M61 | v8.9 |
| 3.0.0 | -- | 2018-Jun-21 | 2018-Sep-18 | M66 | v10.2 |
| 4.0.0 | -- | 2018-Oct-11 | 2018-Dec-20 | M69 | v10.11 |
| 5.0.0 | -- | 2019-Jan-22 | 2019-Apr-24 | M73 | v12.0 |
| 6.0.0 | -- | 2019-May-01 | 2019-Jul-30 | M76 | v12.4 |
| 7.0.0 | -- | 2019-Aug-01 | 2019-Oct-22 | M78 | v12.8 |
| 8.0.0 | -- | 2019-Oct-24 | 2020-Feb-04 | M80 | v12.13 |
| 9.0.0 | -- | 2020-Feb-06 | 2020-May-19 | M83 | v12.14 |
| 10.0.0 | -- | 2020-May-21 | 2020-Aug-25 | M85 | v12.16 |
| 11.0.0 | -- | 2020-Aug-27 | 2020-Nov-17 | M87 | v12.18 |
| 12.0.0 | -- | 2020-Nov-19 | 2021-Mar-02 | M89 | v14.16 |
| 13.0.0 | -- | 2021-Mar-04 | 2021-May-25 | M91 | v14.16 |
| 14.0.0 | -- | 2021-May-27 | 2021-Aug-31 | M93 | v14.17 |
| 15.0.0 | 2021-Jul-20 | 2021-Sep-01 | 2021-Sep-21 | M94 | v16.5 |
| 16.0.0 | -- | 2021-Sep-23 | 2021-Nov-16 | M96 | 待定 |
\n\n详细查看我们的版本控制策略和实现。
\n
自 2.0.0 版本起，Electron 遵循 SemVer。 以下命令将安装最新稳定版的 Electron：
\nnpm install --save-dev electron\n现有项目更新到最新的稳定版本:
\nnpm install --save-dev electron@latest\n小于 2.0 的 Electron 版本编号并不遵循 SemVer 规范: major 版本对应最终用户 API 的变更, minor 版本更新对应 Chromium 的主版本更新, patch 版本更新会带来新功能和 bug 修复。 虽然方便开发人员合并功能，但却为面向客户端应用程序的开发人员带来了麻烦。 像Slack，Stride，Teams，Skype，VS Code，Atom和Desktop等主要应用程序的QA测试周期可能很长，稳定性是一个非常理想的结果。 尝试吸收错误修复时，采用新功能的风险很高。
\n以下是 1.x 策略的一个例子：
\n
使用 1.8.1开发的应用程序无法吸收 1.8.2 的功能，或者通过反向移植修复和维护新的发行版，无法采用 1.8.3错误修复。
There are several major changes from our 1.x strategy outlined below. Each change is intended to satisfy the needs and priorities of developers/maintainers and app developers.
\n-beta 标签master分支没有版本信息，只有稳定分支会包含版本信息。我们将详细介绍 git 分支是如何工作的，npm 标记是如何工作的，开发人员应该看到什么，以及如何能够支持更改。
\n从 2.0 开始，Electron 将遵循 SemVer。
\n下面是一个表格，明确地将变化的类型映射到它们对应的 SemVer 类别 (例如Major，Minor，Patch)。
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Major 版本增量 | Minor 版本增量 | Patch 版本增量 |
|---|---|---|
| Electron 突破性 API 变更 | Electron 无突破性 API 变更 | Electron bug fixes |
| Node.js 重大版本更新 | Node.js 次要版本更新 | Node.js patch 版本更新 |
| Chromium 版本更新 | 修复相关的 chromium 补丁 |
请注意，大多数 Chromium 更新都将被认为是破坏性的。 Fixes that can be backported will likely be cherry-picked as patches.
\n稳定分支是与主控并行运行的分支，仅接受与安全性或稳定性有关的最优提交。 这些分支永远不会合并回 master 分支.
\n
自 Electron 8 以来，稳定分支始终为 marjar 版本，并且根据以下模板 $MAJOR-x-y 例如： 8-x-y。 在此之前，我们使用 minor 版本行，并将它们命名为 $MAJOR-$MINOR-x 例如： 2-0-x
我们允许同时存在多个稳定分支，并且打算在任何时候至少支持两个并行支持安全修复。
GitHub不支持旧线路，但是其他分组可以自行获取所有权和返回稳定性和安全修复。 我们不鼓励这样做，但是认识到它使得许多应用程序开发人员的生活更轻松。
\n开发人员想知道哪个版本可以 安全 使用。 即使是简单的功能也会使应用程序变得复杂。 同时，锁定到一个固定的版本是很危险的，因为你忽略了自你的版本以来可能出现的安全补丁和错误修复。 我们的目标是在 package.json 中允许以下标准的 semver 范围:
~ 2.0. 0 只接受您的 2.0.0 版本的稳定性或安全性相关的修复程序。^ 2.0. 0 可允许不破坏性的 合理稳定 功能以及安全性和 bug 修复。第二点重要的是使用 ^ 的应用程序仍然能够期望合理的稳定性水平。 为了达到这个目的，SemVer允许使用一个 pre-release 标识 来表示一个特定的版本还不够 安全 或 稳定。
无论你选择什么，你将定期不得不在 package.json 中打破版本，因为突破性变更是 Chromium 的一个常态。
过程如下:
\nbeta.N, e.g. 2.0.0-beta.1. After the first beta, subsequent beta releases must meet all of the following conditions:2.0.0-beta.2。2.0.0-beta.1. 在第一个稳定之后，所有的变化都必须落后兼容的 bug 或安全修复。2.0.1。特别地，上述步骤意味着：
\n对于每个主要和次要的颠覆，你都应该像以下示例一样进行操作：
\n2.0.0-beta.1\n2.0.0-beta.2\n2.0.0-beta.3\n2.0.0\n2.0.1\n2.0.2\n图片中的生命周期示例:
\n2.0.0-beta.1。 2.0.0-beta.2. 2.0.0 下作为非 beta 版本再次被发布。 2-0-x line and release 2.0.1. 几个不同的 SemVer 范围将如何接收新版本的示例:
\n
我们的战略有几次权衡，我们现在认为这是适当的。 最重要的是, 新的主分支特性可能需要一段时间才能作为稳定版发布。 如果你想立即尝试一个新的特性, 你必须自己编译Electron 。
\n作为未来的考虑, 我们可以介绍以下一种或两种情况:
\n功能标志是 Chromium 的一种常见的做法, 在网络开发生态系统中得到了很好的确立。 在 Electron 环境中, 功能标志或 软分支 必须具有以下属性:
\n我们力求在更新和发布过程的各个层面提高清晰度。 从 2.0.0 开始, 我们将要求遵循 常规提交 规范的拉请求, 可以概括如下:
会导致 SemVer major 版本改变的提交必须以BREAKING CHANGE:开头。
会导致 SemVer minor 版本改变的提交必须以 feat: 开头。
会导致 SemVer patch 版本改变的提交必须以 fix: 开头。
我们允许合并提交，只要合并提交的消息符合上述消息格式。
\n只要pull request里包含有意义的总结性的版本语义消息，即使它其中的某些提交消息不包含版本语义前缀也是可以接受的
\n主分支master 分支将始终在其 package.json 中包含 0.0.0-dev.package.json 中包含正确的版本master is always versioned as the next theoretical release branch类似于 NW.js，Electron 提供了一个使用 Web 技术开发桌面应用程序的平台。 两个平台都允许开发者使用 HTML、JavaScript 和 Node.js。 表面上，它们似乎非常相似。
\n但是这两个项目也有本质上的区别，使得 Electron 和 NW.js 成为两个相互独立的产品。
\n在 NW.js 中，应用程序的主入口是一个 HTML 网页。 在这种情况下，NW.js 得在浏览器窗口中打开给定的入口点。
\n在 Electron 中，入口点是一个 JavaScript 脚本。 我们需要通过 Javascript 代码手动创建一个浏览器窗口并加载一个 HTML 文件，而不是直接提供一个 URL 的方法。 你还可以监听窗口事件，决定何时让应用退出。
\nElectron 的工作方式更像 Node.js 运行时。 而且 Electron 的 API 实际上更为底层，所以我们可以使用它进行相应的浏览器测试并替代 PhantomJS。
\n在 NW.js 中，网页中的 Node 集成需要通过给 Chromium 打补丁来实现。但在 Electron 中，我们选择了另一种方式：通过各个平台的消息循环与 libuv 的循环集成，避免了直接在 Chromium 上做改动。 你可以查看 node_bindings 来了解这是如何完成的。
如果你是一个经验丰富的 NW.js 用户，你应该熟悉节点上下文和网页上下文的概念。 这些概念是由于 NW.js 的实现方式而发明的。
\n通过使用 Node 的 multi-context（多上下文）特性，Electron 不需要在网页中引入新的 Javascript 上下文。
\n注意：从 0.13 开始，NW.js 也支持使用多上下文。
\nNW.js 仍然提供一个支持 Windows XP 的 \"传统版本\"， 它没有收到安全更新。
\n鉴于硬件制造商、微软、Chromium 和 Node.js 甚至没有为该系统发布关键的安全更新，我们不得不警告你，使用 Windows XP 是非常不安全的，是彻头彻尾的不负责任。
\n然而，我们明白，可能存在超出我们想象的要求存在，因此，如果你正在寻找像 Electron 那样在 Windows XP 上运行的东西，NW.js 的传统版本可能是适合你的。
\n在支持的功能数量上有许多差异。 Electron有一个更大的社区，有更多的生产应用在使用它，并且有大量的用户端模块在 npm 上可用。
\n例如，Electron 内置了对自动更新的支持和无数的工具，使安装程序更加容易创建。 一个有利于 NW.js 的例子，NW.js 支持更多的 Chrome.* API，用于开发 Chrome 应用程序。
当然，我们相信 Electron 是用 Web 技术构建生产应用程序更好的平台（如 Visual Studio Code、Slack 或 Facebook Messenger）；但是，我们希望公平对待同样用 Web 技术的朋友。 如果你有 Electron 不能满足的功能需求，你可能需要尝试 NW.js。
", "title": "Electron 和 NW.js 之间的技术差异 类似于NW.js，Electron提供了一个使用Web技术开发桌面应用程序的平台。它们都可以让开发者很便利地使用HTML、JavaScript以及Node.js进行开发。表面上，它们俩非常相似。、 然而，两个项目间依旧存在着一些本质的差异，这使得Electron是一个完全独立且不同于NW.js的项目。 1）应用程序的入口 NW.js中，应用程序的主入口是一个HTML网页。NW.js将会使用一个浏览器窗口打开给定的入口点（HTML网页）。 在Electron中，入口点是一个Javascript脚本文件。我们需要通过Javascript代码手动创建一个浏览器窗口并加载一个HTML文件，而不是直接提供一个URL的方法。当然我们也可以去监听窗口的事件来决定什么时候退出应用程序。 Electron的工作机制更像是Node.js的运行时。而且Electron的API实际上更为底层，所以我们可以使用它进行相应的浏览器测试并替代PhantomJS。 2）Node集成 在NW.js中，在Web页面中集成Node需要通过给Chromium打补丁的方式才能运行。而Electron采取了通过在集成libuv loop——不同的操作系统平台（Windows、Linux、MacOS）的消息循环来避免魔改Chromium。 3）Javascript上下文", "description": "" }, "/docs/api/environment-variables": { "locale": "zh-CN", "slug": "environment-variables", "href": "/docs/api/environment-variables", "crowdinFileId": "256315", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/environment-variables.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n在不更改代码的情况下控制应用程序配置和行为。
\n
Electron的某些行为受环境变量的控制, 因为它们比命令行标志和应用程序的代码更早初始化。
\nPOSIX shell示例:
\n$ export ELECTRON_ENABLE_LOGGING=true\n$ electron\nWindows 控制台示例:
\n> set ELECTRON_ENABLE_LOGGING=true\n> electron\n以下环境变量主要用于在打包后的Electron应用运行时使用。
\nNODE_OPTIONSElectron 包括对 Node 的 NODE_OPTIONS 的子集的支持。 除与 Chromium 使用 BoringSSL 相抵触的情况外，大多数都得到了支持。
示例：
\nexport NODE_OPTIONS=\"--no-warnings --max-old-space-size=2048\"\n不支持的选项是：
\n--use-bundled-ca\n--force-fips\n--enable-fips\n--openssl-config\n--use-openssl-ca\nNODE_OPTIONS 在打包应用程序中明确禁止使用，以下情况除外:
--max-http-header-size\n--http-parser\nGOOGLE_API_KEYElectron中的地理定位支持需要使用Google云平台的地理定位网络服务。 为了启用此功能，需获取一个 Google API 密钥 并将以下代码放入你的主进程文件， 在打开任何 浏览器窗口之前将生成地理位置请求：
\nprocess.env.GOOGLE_API_KEY = 'YOUR_KEY_HERE'\n默认情况下, 可能不允许新生成的 Google API key进行地理编码请求。 要为你的项目启用地理定位网络服务，请通过 API 库 启用它。
\n注： 你需要在与 API 密钥相关的项目中添加一个计费帐户，以便地理定位网络服务工作。
\nELECTRON_NO_ASAR禁用 ASAR 支持。 该变量只在设置 ELECTRON_RUN_AS_NODE 的派生子进程和衍生子进程中受支持。
ELECTRON_RUN_AS_NODE当做普通Node.js进程启动。
\n在当前模式下，当运行普通可执行Node.js文件时，你可以将 cli 选项 传递给Node.js，但下列标志除外：
\n由于Electron 在构建 Node.js 的 crypto 模块时使用 BoringSSL 而不是 OpenSSL，因此这些标志被禁用。所以不会像设计的那样工作。
ELECTRON_NO_ATTACH_CONSOLE Windows不附加到当前控制台会话。
\nELECTRON_FORCE_WINDOW_MENU_BAR Linux 不使用 Linux 的全局菜单栏。
\nELECTRON_TRASH Linux在 Linux 上设置垃圾回收实现。 默认值为 gio.
选项:
\ngvfs-trashtrash-clikioclient5kioclient以下环境变量主要用于开发和调试目的。
\nELECTRON_ENABLE_LOGGINGPrints Chromium's internal logging to the console.
\nSetting this variable is the same as passing --enable-logging on the command line. For more info, see --enable-logging in command-line switches.
ELECTRON_LOG_FILESets the file destination for Chromium's internal logging.
\nSetting this variable is the same as passing --log-file on the command line. For more info, see --log-file in command-line switches.
ELECTRON_DEBUG_DRAG_REGIONS在 macOS 的 BrowserView上添加可拖动区域的颜色 - 可拖动区域将着绿色， 不可拖动区域将着红色以帮助调试。
ELECTRON_DEBUG_NOTIFICATIONS在 macOS 上添加额外日志到 通知 生命周期以帮助调试。 当创建或激活新通知时，将显示额外日志。 They will also be displayed when common a tions are taken: a notification is shown, dismissed, its button is clicked, or it is replied to.
示例输出：
\nNotification created (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification displayed (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification activated (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification replied to (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nELECTRON_LOG_ASAR_READS当 Electron 从 ASAR 文件读取时，记录读取 offset 偏移和文件路径到系统 tmpdir 临时目录。 生成的文件可以提供给ASAR 模块以优化文件排序。
ELECTRON_ENABLE_STACK_DUMPING当Electron崩溃时, 将跟踪堆栈输出到控制台。
\n如果 crashReporter已经启动了, 则此环境变量将不起作用。
ELECTRON_DEFAULT_ERROR_MODE Windows 当Electron崩溃时显示 Windows 的崩溃对话框。
\n如果 crashReporter已经启动了, 则此环境变量将不起作用。
ELECTRON_OVERRIDE_DIST_PATH当 electron 包运行时，该变量告知 electron 命令使用指定Electron的构建代替由 npm install 下载的构建。 用法：
export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing\n在Electron运行时设置一些环境变量
\nORIGINAL_XDG_CURRENT_DESKTOP此变量设置为你的应用程序最初启动的 XDG_CURRENT_DESKTOP 值。 Electron 有时修改 XDG_CURRENT_DESKTOP 的值以影响Chromium 中的其他逻辑，所以如果您想访问 原始的 值 您应该重新查看此环境变量。
GlobalEventpreventDefault VoidFunctionSome of Electrons APIs are tagged with _Experimental_ in the documentation. This tag indicates that the API may not be considered stable and the API may be removed or modified more frequently than other APIs with less warning.
Anyone can request an API be tagged as experimental in a feature PR, disagreements on the experimental nature of a feature can be discussed in the API WG if they can't be resolved in the PR.
\nOnce an API has been stable and in at least two major stable release lines it can be nominated to have its experimental tag removed. This discussion should happen at an API WG meeting. Things to consider when discussing / nominating:
\nid Stringmanifest any - Copy of the extension's manifest data.name Stringpath String - The extension's file path.version Stringurl String - The extension's chrome-extension:// URL.name Stringversion StringElectron 支持 Chrome 扩展API的子集， 主要是支持 DevTools 扩展和 Chromium-internal 扩展，但它同时也支持一些其他扩展能。
\n\n\n注意：Electron 不支持商店中的任意 Chrome 扩展，Electron 项目的目标不是与 Chrome 的扩展实现完全兼容。
\n
Electron 只支持加载未打包的扩展 (即不能使用 .crx 文件)。 插件会被安装到每一个会话。 要加载扩展，请调用 ses.loadextension：
const { session } = require('electron')\n\nsession.loadExtension('path/to/unpacked/extension').then(({ id }) => {\n // ...\n})\n加载的扩展将不会被自动记住；如果在应用程序运行时未调用 loadExtension，则不会加载扩展。
注意，仅能在持久 session 中加载扩展。 尝试将扩展加载到内存 session 中会出现错误。
\n有关加载、卸载和查询活动扩展的更多信息，请查阅 session 文档。
我们支持以下扩展 API，并需要注意一些警告。 其他API可能会得到额外支持，但对此处未列出的任何API的支持都是临时的，可能会被删除。
\nchrome.devtools.inspectedWindow支持这些 API 的所有功能。
\nchrome.devtools.network支持这些 API 的所有功能。
\nchrome.devtools.panels支持这些 API 的所有功能。
\nchrome.extension支持 chrome.extension 的以下属性：
chrome.extension.lastError支持 chrome.extension 的以下方法：
chrome.extension.getURLchrome.extension.getBackgroundPagechrome.runtime支持 chrome.runtime 的以下属性：
chrome.runtime.lastErrorchrome.runtime.id支持 chrome.runtime 的以下方法：
chrome.runtime.getBackgroundPagechrome.runtime.getManifestchrome.runtime.getPlatformInfochrome.runtime.getURLchrome.runtime.connectchrome.runtime.sendMessagechrome.runtime.reload支持 chrome.runtime 的以下事件：
chrome.runtime.onStartupchrome.runtime.onInstalledchrome.runtime.onSuspendchrome.runtime.onSuspendCanceledchrome.runtime.onConnectchrome.runtime.onMessagechrome.storage仅支持 chrome.storage.local ； chrome.storage.sync 和 chrome.storage.manage.manage 不支持。
chrome.tabs支持 chrome.tab 的以下方法：
chrome.tabs.sendMessagechrome.tabs.executeScript\n\n注意： 在 Chrome 中，通过
\n-1作为标签ID表示“当前活动的标签”。 因为 Electron 没有这样的概念，通过-1作为选项卡ID不支持而且会报错。
chrome.management支持 chrome.management 的以下方法：
chrome.management.getAllchrome.management.getchrome.management.getSelfchrome.management.getPermissionWarningsByIdchrome.management.getPermissionWarningsByManifestchrome.management.onEnabledchrome.management.onDisabledchrome.webRequest支持这些 API 的所有功能。
\n\n", "title": "Chrome 扩展支持", "description": "注意：Electron 不支持商店中的任意 Chrome 扩展，Electron 项目的目标不是与 Chrome 的扩展实现完全兼容。" }, "/docs/faq": { "locale": "zh-CN", "slug": "faq", "href": "/docs/faq", "crowdinFileId": "256121", "githubUrl": "https://github.com/electron/electron/tree/main/docs/faq.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "注意： 如果有冲突需要处理，Electron 的
\nwebRequest模块将优先于chrome.web。
在运行 npm install electron 时，有些用户会偶尔遇到安装问题。
在大多数情况下，这些错误都是由网络问题导致，而不是因为 electron npm 包的问题。 如 ELIFECYCLE、EAI_AGAIN、ECONNRESET 和 ETIMEDOUT 等错误都是此类网络问题的标志。 最佳的解决方法是尝试切换网络，或是稍后再尝试安装。
如果通过 npm 安装失败，您可以尝试直接从 electron/electron/releases 直接下载 Electron。
通常来说，在稳定版的 Chrome 发布后一到两周内，我们会更新 Electron 内的 Chrome 版本。 这个只是个估计且不能保证，取决于与升级所涉及的工作量。
\n我们只使用稳定的 Chrome 频道。 如果一个重要的修复在 beta 或 dev 通道中，我们将返回端口。
\n更多信息，请看安全介绍
\n我们通常会在最新版的 Node.js 发布后一个月左右将 Electron 更新到这个版本的 Node.js。 我们通过这种方式来避免新版本的 Node.js 带来的 bug（这种 bug 太常见了）。
\nNode.js 的新特性通常是由新版本的 V8 带来的。由于 Electron 使用的是 Chrome 浏览器中附带的 V8 引擎，所以 Electron 内往往已经有了部分新版本 Node.js 才有的崭新特性。
\n在两个网页（渲染进程）间共享数据最简单的方法是使用浏览器中已经实现的 HTML5 API。 其中比较好的方案是 Storage API, localStorage, sessionStorage, and IndexedDB.
或者，您可以使用 Electron 提供的原始版 IPC 。 To share data between the main and renderer processes, you can use the ipcMain and ipcRenderer modules. To communicate directly between web pages, you can send a MessagePort from one to the other, possibly via the main process using ipcRenderer.postMessage(). Subsequent communication over message ports is direct and does not detour through the main process.
当用来存储 Tray 的变量被垃圾回收时，就会发生这种情况。
\n你可以参考以下两篇文章来了解为什么会遇到这个问题：
\n\n如果你只是要一个快速的修复方案，你可以用下面的方式改变变量的作用域，防止这个变量被垃圾回收。
\nconst { app, Tray } = require('electron')\napp.whenReady().then(() => {\n const tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\n改为
\nconst { app, Tray } = require('electron')\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\n因为 Electron 在运行环境中引入了 Node.js，所以在 DOM 中有一些额外的变量，比如 module、exports 和 require。 这导致 了许多库不能正常运行，因为它们也需要将同名的变量加入运行环境中。
我们可以通过禁用 Node.js 来解决这个问题，在Electron里用如下的方式：
\n// 在主进程中.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n webPreferences: {\n nodeIntegration: false\n }\n})\nwin.show()\n假如你依然需要使用 Node.js 和 Electron 提供的 API，你需要在引入那些库之前将这些变量重命名，比如：
\n<head>\n<script>\nwindow.nodeRequire = require;\ndelete window.require;\ndelete window.exports;\ndelete window.module;\n</script>\n<script type=\"text/javascript\" src=\"jquery.js\"></script>\n</head>\nrequire('electron').xxx 未定义。在使用 Electron 的提供的模块时，你可能会遇到和以下类似的错误：
\n> require('electron').webFrame.setZoomFactor(1.0)\nUncaught TypeError: Cannot read property 'setZoomLevel' of undefined\n很可能是你在过程中使用了错误的模块。 比如，electron.app 只能在主进程中使用, 然而 electron.webFrame 只能在渲染进程中使用。
如果 sub-pixel anti-aliasing已被禁用，那么 LCD 屏幕上的字体可能会看起来模糊。 示例：
\n
子像素反锯齿需要一个包含字体光图的图层的非透明背景。 （详情请参阅这个问题）
\nTo achieve this goal, set the background in the constructor for BrowserWindow:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n backgroundColor: '#fff'\n})\n效果仅可见于（一些） LCD 屏幕。 Even if you don't see a difference, some of your users may. It is best to always set the background this way, unless you have reasons not to do so.
\n注意到，仅设置 CSS 背景并不具有预期的效果。
", "title": "Electron 常见问题 (FAQ)", "description": "" }, "/docs/api/structures/file-filter": { "locale": "zh-CN", "slug": "file-filter", "href": "/docs/api/structures/file-filter", "crowdinFileId": "256435", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/file-filter.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "name Stringextensions String[]File 对象\n\n在文件系统中，使用HTML5
\nFile原生API操作文件
DOM的文件接口提供了关于原生文件的抽象，以便用户可以直接使用HTML5文件API处理原生文件。 Electron已经向 文件 接口添加了一个 path 属性, 在文件系统上暴露出文件的真实路径
示例：获取拖拽到app上的文件的真实路径
\n<div id=\"holder\">\n Drag your file here\n</div>\n\n<script>\n document.addEventListener('drop', (e) => {\n e.preventDefault();\n e.stopPropagation();\n\n for (const f of e.dataTransfer.files) {\n console.log('File(s) you dragged here: ', f.path)\n }\n });\n document.addEventListener('dragover', (e) => {\n e.preventDefault();\n e.stopPropagation();\n });\n</script>\npath String - The path to the file to send.headers Record<string, string> (optional) - Additional headers to be sent.\n\n打开一个无工具栏、边框、和其它图形化外壳的窗口。
\n
无边框窗口是不带外壳（包括窗口边框、工具栏等），只含有网页内容的窗口。 这些是 BrowserWindow 类上的选项。
要创建无边框窗口，只需在 BrowserWindow 的 options 中将 frame 设置为 false：
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600, frame: false })\nwin.show()\nThere's an alternative way to specify a chromeless window on macOS and Windows. Instead of setting frame to false which disables both the titlebar and window controls, you may want to have the title bar hidden and your content extend to the full window size, yet still preserve the window controls (\"traffic lights\" on macOS) for standard window actions. 你可以通过指定 titleBarStyle 选项来完成此操作：
hiddenResults in a hidden title bar and a full size content window. On macOS, the title bar still has the standard window controls (“traffic lights”) in the top left.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hidden' })\nwin.show()\nhiddenInset返回一个另一种隐藏了标题栏的窗口，其中控制按钮到窗口边框的距离更大。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })\nwin.show()\ncustomButtonsOnHover使用自定义的关闭、缩小和全屏按钮，这些按钮会在划过窗口的左上角时显示。 由于无框窗口与苹果 macOS 窗口界面的限制，全屏按钮不可用。 这些自定义的按钮能防止, 与发生于标准的窗口工具栏按钮处的鼠标事件相关的问题. 这个选项只适用于无框窗口。
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover', frame: false })\nwin.show()\nWhen using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS, using one of the titleBarStyles as described above so that the traffic lights are visible, or using titleBarStyle: hidden on Windows, you can access the Window Controls Overlay JavaScript APIs and CSS Environment Variables by setting the titleBarOverlay option to true. Specifying true will result in an overlay with default system colors.
On Windows, you can also specify the color of the overlay and its symbols by setting titleBarOverlay to an object with the options color and symbolColor. If an option is not specified, the color will default to its system color for the window control buttons:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: true\n})\nwin.show()\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: {\n color: '#2f3241',\n symbolColor: '#74b1be'\n }\n})\nwin.show()\n通过将 transparent 选项设置为 true, 还可以使无框窗口透明:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ transparent: true, frame: false })\nwin.show()\nresizable 设置为 true 可能会使透明窗口停止工作。blur 筛选器仅适用于网页, 因此无法对位于透明窗口下方的内容应用模糊效果 (例如在用户系统上打开的其他应用程序) 。--enable-transparent-visuals --disable-gpu 来禁用GPU, 启用 ARGB，用以实现窗体透明。 这是由一个上游的 bug 导致的, 即 在Linux机上，透明度通道（alpha channel ）在一些英伟达的驱动（NVidia drivers）中无法运行。要创建一个点击穿透窗口，也就是使窗口忽略所有鼠标事件，可以调用 win.setIgnoreMouseEvents(ignore) API：
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.setIgnoreMouseEvents(true)\n忽略鼠标消息会使网页无视鼠标移动，这意味着鼠标移动事件不会被发出。 在 Windows 操作系统上，可以使用可选参数将鼠标移动消息转发到网页，从而允许发出诸如 mouseleave 之类的事件：
const { ipcRenderer } = require('electron')\nconst el = document.getElementById('clickThroughElement')\nel.addEventListener('mouseenter', () => {\n ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })\n})\nel.addEventListener('mouseleave', () => {\n ipcRenderer.send('set-ignore-mouse-events', false)\n})\n\n// Main process\nconst { ipcMain } = require('electron')\nipcMain.on('set-ignore-mouse-events', (event, ...args) => {\n BrowserWindow.fromWebContents(event.sender).setIgnoreMouseEvents(...args)\n})\n这将使网页在 el 上点击时穿透，在它外面时恢复正常。
默认情况下, 无边框窗口是不可拖拽的。 应用程序需要在 CSS 中指定 -webkit-app-region: drag 来告诉 Electron 哪些区域是可拖拽的（如操作系统的标准标题栏），在可拖拽区域内部使用 -webkit-app-region: no-drag 则可以将其中部分区域排除。 请注意, 当前只支持矩形形状。
注意: -webkit-app-region: drag 在开发人员工具打开时会出现问题。 查看更多信息 (包括变通方法), 请参见此 GitHub 问题 。
要使整个窗口可拖拽, 您可以添加 -webkit-app-region: drag 作为 body 的样式:
<body style=\"-webkit-app-region: drag\">\n</body>\n请注意，如果您使整个窗口都可拖拽，则必须将其中的按钮标记为不可拖拽，否则用户将无法点击它们：
\nbutton {\n -webkit-app-region: no-drag;\n}\n如果只将自定义标题栏设置为可拖拽，还需要使标题栏中的所有按钮都不可拖拽。
\n在无框窗口中, 拖动行为可能与选择文本冲突。 例如, 当您拖动标题栏时, 您可能会意外地选择标题栏上的文本。 为防止此操作, 您需要在可区域中禁用文本选择, 如下所选:
\n.titlebar {\n -webkit-user-select: none;\n -webkit-app-region: drag;\n}\n在某些平台上，可拖拽区域不被视为窗口的实际内容，而是作为窗口边框处理，因此在右键单击时会弹出系统菜单。 要使上下文菜单在所有平台上都正确运行, 您永远也不要在可拖拽区域上使用自定义上下文菜单。
", "title": "无边框窗口", "description": "打开一个无工具栏、边框、和其它图形化外壳的窗口。" }, "/docs/tutorial/fuses": { "locale": "zh-CN", "slug": "fuses", "href": "/docs/tutorial/fuses", "crowdinFileId": "256201", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/fuses.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nPackage time feature toggles
\n
For a subset of Electron functionality it makes sense to disable certain features for an entire application. For example, 99% of apps don't make use of ELECTRON_RUN_AS_NODE, these applications want to be able to ship a binary that is incapable of using that feature. We also don't want Electron consumers building Electron from source as that is both a massive technical challenge and has a high cost of both time and money.
Fuses are the solution to this problem, at a high level they are \"magic bits\" in the Electron binary that can be flipped when packaging your Electron app to enable / disable certain features / restrictions. Because they are flipped at package time before you code sign your app the OS becomes responsible for ensuring those bits aren't flipped back via OS level code signing validation (Gatekeeper / App Locker).
\nWe've made a handy module @electron/fuses to make flipping these fuses easy. Check out the README of that module for more details on usage and potential error cases.
require('@electron/fuses').flipFuses(\n // Path to electron\n require('electron'),\n // Fuses to flip\n {\n runAsNode: false\n }\n)\nManually flipping fuses requires editing the Electron binary and modifying the fuse wire to be the sequence of bytes that represent the state of the fuses you want.
\nSomewhere in the Electron binary there will be a sequence of bytes that look like this:
\n| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |\nsentinel_bytes is always this exact string dL7pKGdnNz796PbbjQWNKmHXBZaB9tsXfuse_version is a single byte whose unsigned integer value represents the version of the fuse schemafuse_wire_length is a single byte whose unsigned integer value represents the number of fuses in the following fuse wirefuse_wire is a sequence of N bytes, each byte represents a single fuse and its state.To flip a fuse you find its position in the fuse wire and change it to \"0\" or \"1\" depending on the state you'd like.
\n您可以在 这里查看当前schema。
", "title": "Electron Fuses", "description": "Package time feature toggles" }, "/docs/api/global-shortcut": { "locale": "zh-CN", "slug": "global-shortcut", "href": "/docs/api/global-shortcut", "crowdinFileId": "256323", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/global-shortcut.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n在应用程序没有键盘焦点时，监听键盘事件。
\n
进程：主进程
\nglobalShortcut 模块可以在操作系统中注册/注销全局快捷键, 以便可以为操作定制各种快捷键。
注意: 快捷方式是全局的; 即使应用程序没有键盘焦点, 它也仍然在持续监听键盘事件。 在 app 模块的 ready 事件就绪之前，这个模块不能使用。
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+X' shortcut listener.\n const ret = globalShortcut.register('CommandOrControl+X', () => {\n console.log('CommandOrControl+X is pressed')\n })\n\n if (!ret) {\n console.log('registration failed')\n }\n\n // 检查快捷键是否注册成功\n console.log(globalShortcut.isRegistered('CommandOrControl+X'))\n})\n\napp.on('will-quit', () => {\n // 注销快捷键\n globalShortcut.unregister('CommandOrControl+X')\n\n // 注销所有快捷键\n globalShortcut.unregisterAll()\n})\nglobalShortcut 模块具有以下方法:
globalShortcut.register(accelerator, callback)accelerator Acceleratorcallback Function返回Boolean - 快捷键注册是否成功
注册 accelerator 的全局快捷键。 当用户按下注册快捷键时， callback 会被调用。
如果指定的快捷键已经被其他应用程序注册掉, 调用会默默失败。 该特性由操作系统定义，因为操作系统不希望多个程序的全局快捷键互相冲突。
\n在 macOS 10.14 Mojave 下面，如果 app 没有被授权为可信任使用的客户端，那么下列快捷键会注册失败：
\nglobalShortcut.registerAll(accelerators, callback)accelerators String[] - an array of Accelerators.callback FunctionRegisters a global shortcut of all accelerator items in accelerators. 当用户按下注册快捷键时， callback 会被调用。
如果定义的快捷键已经被其他应用占用，这个调用会失效。 该特性由操作系统定义，因为操作系统不希望多个程序的全局快捷键互相冲突。
\n在 macOS 10.14 Mojave 下面，如果 app 没有被授权为可信任使用的客户端，那么下列快捷键会注册失败：
\nglobalShortcut.isRegistered(accelerator)accelerator Accelerator返回 Boolean - 表示 accelerator 全局快捷键是否注册成功
当快捷键已经被其他应用程序注册时, 此调用依然将返回 false。 该特性由操作系统定义，因为操作系统不希望多个程序的全局快捷键互相冲突。
globalShortcut.unregister(accelerator)accelerator Accelerator注销 accelerator 的全局快捷键。
globalShortcut.unregisterAll()注销所有的全局快捷键（清空该应用程序的所有全局快捷键）。
", "title": "globalShortcut", "description": "在应用程序没有键盘焦点时，监听键盘事件。" }, "/docs/glossary": { "locale": "zh-CN", "slug": "glossary", "href": "/docs/glossary", "crowdinFileId": "256123", "githubUrl": "https://github.com/electron/electron/tree/main/docs/glossary.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "这篇文档解释了一些经常在 Electron 开发中使用的专业术语。
\nASAR 表示 Atom Shell Archive Format。 一个 asar 档案就是一个简单的 tar 文件 - 比如将那些有关联的文件放至一个单独的文件格式中。 Electron 能够任意读取其中的文件并且不需要解压整个文件。
The ASAR format was created primarily to improve performance on Windows when reading large quantities of small files (e.g. when loading your app's JavaScript dependency tree from node_modules).
Code signing is a process where an app developer digitally signs their code to ensure that it hasn't been tampered with after packaging. Both Windows and macOS implement their own version of code signing. As a desktop app developer, it's important that you sign your code if you plan on distributing it to the general public.
\nFor more information, read the Code Signing tutorial.
\nContext isolation is a security measure in Electron that ensures that your preload script cannot leak privileged Electron or Node.js APIs to the web contents in your renderer process. With context isolation enabled, the only way to expose APIs from your preload script is through the contextBridge API.
For more information, read the Context Isolation tutorial.
\nSee also: preload script, renderer process
\nThe C Runtime Library (CRT) is the part of the C++ Standard Library that incorporates the ISO C99 standard library. 实现了 CRT 的 Visual c++ 库支持本机代码开发, 以及混合的本机和托管代码, 以及用于. NET 开发的纯托管代码。
\n是指在 macOS 上使用的苹果系统的磁盘镜像打包格式。 DMG 文件通常被用来分发应用的 \"installers\"。
\n输入法编辑器. 是一个允许用户输入在键盘上找不到的字符和符号的程序。 例如，使用户可以用拉丁语键盘输入中文，日文，韩文和印度文字。
\n接口描述语言（Interface Description Language）。 Write function signatures and data types in a format that can be used to generate interfaces in Java, C++, JavaScript, etc.
\nIPC stands for inter-process communication. Electron uses IPC to send serialized JSON messages between the main and renderer processes.
\n参见： main process, renderer process
\n主进程，通常是指 main.js 文件，是每个 Electron 应用的入口文件。 控制着整个应用的生命周期，从打开到关闭。 它也管理着系统原生元素比如菜单，菜单栏，Dock 栏，托盘等。 主进程负责创建 APP 的每一个渲染进程。 包含了全功能的 Node API。
应用的主进程定义在 package.json 中的 main 属性中。 当您运行 electron . 时 Electron 便会知道需要运行哪个文件。
在Chromium中，此进程被称为“浏览器进程”。 Electron 中这样称呼是为了不与渲染进程混淆。
\n参见: process, renderer process
\n这是苹果 Mac App Store 的缩写。 有关如何提交您的应用到 MAS 上，请参见 Mac App Store Submission Guide。
\nAn IPC system for communicating intra- or inter-process, and that's important because Chrome is keen on being able to split its work into separate processes or not, depending on memory pressures etc.
\n可参考https://chromium.googlesource.com/chromium/src/+/master/mojo/README.md
\nSee also: IPC
\nOn Windows, MSI packages are used by the Windows Installer (also known as Microsoft Installer) service to install and configure applications.
\nMore information can be found in Microsoft's documentation.
\n原生模块（在 Node.js 中也称为 addon）是用C/C++写成的，可以在 Node.js 中加载，或通过 require() 函数在 Electron 中引入的模块。这些模块用起来与普通的Node.js模块并无二致。 它主要用于桥接在 JavaScript 上运行 Node.js 和 C/C++ 的库。
\nElectron 支持原生的 Node 模块，但是 Electron 非常可能使用了和你系统中安装的Node所不一样的 V8 版本，所以在构建原生模块的时候你需要手动指定 Electron 所使用的头文件的位置。
\nFor more information, read the [Native Node Modules] tutorial.
\nNotarization is a macOS-specific process where a developer can send a code-signed app to Apple servers to get verified for malicious components through an automated service.
\nSee also: code signing
\nOSR (offscreen rendering) can be used for loading heavy page in background and then displaying it after (it will be much faster). 这使您不必将页面显示到屏幕上也可以渲染它。
\nFor more information, read the Offscreen Rendering[osr] tutorial.
\nPreload scripts contain code that executes in a renderer process before its web contents begin loading. These scripts run within the renderer context, but are granted more privileges by having access to Node.js APIs.
\nSee also: renderer process, context isolation
\n一个进程是计算机程序执行中的一个实例。 Electron 应用同时使用了main 进程和一个或者多个 renderer 进程来运行多个程序。
\n在 Node.js 和 Electron 里面，每个运行的进程包含一个 process 对象。 这个对象作为一个全局的提供当前进程的相关信息和操作方法。 作为一个全局变量，它在应用内能够不用 require() 来随时取到。
参见： main process, renderer process
\n渲染进程是应用中的浏览器窗口。 与主进程不同，渲染进程可能同时存在多个，同时，每一个渲染进程都运行与独立的进程中。 渲染进程也可以隐藏。
\n参见： process, main process
\nThe sandbox is a security feature inherited from Chromium that restricts your renderer processes to a limited set of permissions.
\nFor more information, read the Process Sandboxing tutorial.
\nSee also: process
\nSquirrel 是一个开源框架, 能够让 Electron 应用程序自动更新到最新发布的版本. 详见 autoUpdater API 了解如何开始使用 Squirrel。
\n\"userland\" 或者 \"userspace\" 术语起源于 Unix 社区，当程序运行在操作系统内核之外。 最近这个术语被推广到 Node 和 npm 社区，用于区分 \"Node 内核\"功能与在 npm 上注册的\"用户\" 们所发布的包的功能。
\n就像 Node ，Electron 致力于使用较小的API集来支持开发跨平台应用所必需的原语。 这个设计理念让 Electron 能够保持灵活而不被过多的规定有关于如何应该被使用。 Userland 让用户能够创造和分享一些工具来提额外的功能在这个能够使用的 \"core（核心）\"之上。
\nV8 是谷歌开源的 JavaScript 引擎。 它是用 C++ 编写的，用于谷歌的 Chrome 浏览器。 V8 可以单独运行，也可以嵌入任何 C++ 应用程序。
\nElectron将 V8 作为Chromium的一个部分进行构建，然后在构建Node时也指向那个 V8
\nV8 的版本号与谷歌 Chrome 的版本号对应。 Chrome 59 的 V8 版本是 5.9，Chrome 58 的V8 版本是 5.8，以此类推。
\n\nwebview 标签页用于在您的 Electron 应用中嵌入“访客”内容（例如外部网页）。 其功能与 iframe 类似，但 webview 运行于独立的进程中。 作为页面它拥有不一样的权限并且所有的嵌入的内容和你应用之间的交互都将是异步的。 这将保证你的应用对于嵌入的内容的安全性。
\n\nGoma是一款很多开源项目都在使用的分布式编译服务，例如Chromium和Android。
\n
Electron has a deployment of a custom Goma Backend that we make available to all Electron Maintainers. See the Access section below for details on authentication. There is also a cache-only Goma endpoint that will be used by default if you do not have credentials. Requests to the cache-only Goma will not hit our cluster, but will read from our cache and should result in significantly faster build times.
Currently the only supported way to use Goma is to use our Build Tools. Goma configuration is automatically included when you set up build-tools.
If you are a maintainer and have access to our cluster, please ensure that you run e init with --goma=cluster in order to configure build-tools to use the Goma cluster. If you have an existing config, you can just set \"goma\": \"cluster\" in your config file.
When you are using Goma you can run ninja with a substantially higher j value than would normally be supported by your machine.
Please do not set a value higher than 200 on Windows or Linux and 50 on macOS. We monitor Goma system usage, and users found to be abusing it with unreasonable concurrency will be de-activated.
\nninja -C out/Testing electron -j 200\nIf you're using build-tools, appropriate -j values will automatically be used for you.
If you access http://localhost:8088 on your local machine you can monitor compile jobs as they flow through the goma system.
\nFor security and cost reasons, access to Electron's Goma cluster is currently restricted to Electron Maintainers. If you want access please head to #access-requests in Slack and ping @goma-squad to ask for access. Please be aware that being a maintainer does not automatically grant access and access is determined on a case by case basis.
We have automated monitoring of our Goma cluster and cache at https://status.notgoma.com
\nWe do not provide support for usage of Goma and any issues raised asking for help / having issues will probably be closed without much reason, we do not have the capacity to handle that kind of support.
", "title": "Goma", "description": "Goma是一款很多开源项目都在使用的分布式编译服务，例如Chromium和Android。" }, "/docs/api/structures/gpu-feature-status": { "locale": "zh-CN", "slug": "gpu-feature-status", "href": "/docs/api/structures/gpu-feature-status", "crowdinFileId": "256439", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/gpu-feature-status.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "2d_canvas String - Canvas.flash_3d String - Flash.flash_stage3d String - Flash Stage3D.flash_stage3d_baseline String - Flash Stage3D Baseline profile.gpu_compositing String - Compositing.multiple_raster_threads String - Multiple Raster Threads.native_gpu_memory_buffers String - Native GpuMemoryBuffers.rasterization String - Rasterization.video_decode String - Video Decode.video_encode String - Video Encode.vpx_decode String - VPx Video Decode.webgl String - WebGL.webgl2 String - WebGL2.可选值：
\ndisabled_software - Software only. Hardware acceleration disabled (yellow)disabled_off - Disabled (red)disabled_off_ok - Disabled (yellow)unavailable_software - Software only, hardware acceleration unavailable (yellow)unavailable_off - Unavailable (red)unavailable_off_ok - Unavailable (yellow)enabled_readback - Hardware accelerated but at reduced performance (yellow)enabled_force - Hardware accelerated on all pages (green)enabled - Hardware accelerated (green)enabled_on - Enabled (green)enabled_force_on - Force enabled (green)deviceId String - Unique identifier for the device.name String - Name of the device.vendorId Integer - The USB vendor ID.productId Integer - The USB product ID.serialNumber String (optional) - The USB device serial number.guid String (optional) - Unique identifier for the HID interface. A device may have multiple HID interfaces.\n\nMac App Store中的应用内购买
\n
进程：主进程
\ninAppPurchase 模块触发以下事件:
一个或多个 transactions 更新时会触发这一事件。
\n返回:
\nevent Eventtransactions Transaction[] - Array of Transaction objects.inAppPurchase 模块包含以下方法：
inAppPurchase.purchaseProduct(productID[, quantity])productID String - 预付款商品的ID (com.example.app.product1 的ID是 product1).quantity Integer (可选) - 用户所要购买的商品数量.Returns Promise<Boolean> - Returns true if the product is valid and added to the payment queue.
在调用purchaseProduct之前，你应该尽可能快的监听transactions-updated事件
inAppPurchase.getProducts(productIDs)productIDs String[] - 预购商品IDReturns Promise<Product[]> - Resolves with an array of Product objects.
检索商品的描述
\ninAppPurchase.canMakePayments()Returns Boolean - whether a user can make a payment.
inAppPurchase.restoreCompletedTransactions()Restores finished transactions. This method can be called either to install purchases on additional devices, or to restore purchases for an application that the user deleted and reinstalled.
\nThe payment queue delivers a new transaction for each previously completed transaction that can be restored. Each transaction includes a copy of the original transaction.
\ninAppPurchase.getReceiptURL()Returns String - the path to the receipt.
inAppPurchase.finishAllTransactions()完成所有待处理的交易
\ninAppPurchase.finishTransactionByDate(date)date String - 待完成交易的ISO标准日期格式完成与日期对应的待处理事务
", "title": "inAppPurchase", "description": "Mac App Store中的应用内购买" }, "/docs/tutorial/in-app-purchases": { "locale": "zh-CN", "slug": "in-app-purchases", "href": "/docs/tutorial/in-app-purchases", "crowdinFileId": "256203", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/in-app-purchases.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "如果你还没有，你需要在 iTunes Connect 签署付费应用协议, 并设置您的银行和税务信息。
\niTunes Connect 开发人员帮助: 协议、税务和银行概述
\n然后，您需要在iTunes Connect中配置您的应用内购买，并包含名称，定价和说明等详细信息，以突出显示您的应用内购买的功能。
\niTunes Connect开发人员帮助：创建应用程序内购买
\n若要在Electron开发阶段对应用内购买功能进行测试，您必须在node_modules/electron/dist/Electron.app/Contents/Info.plist路径下修改CFBundleIdentifier。 您必须使用通过ITunes Connect创建的应用的bundle indentifier来替换掉com.github.electron。
<key>CFBundleIdentifier</key>\n<string>com.example.app</string>\n通过下面的例子来了解如何在Electron中使用应用内购买功能。 您必须使用通过ITunes Connect创建的产品的唯一标识 （ID）来替换掉下面示例中的PRODUCT_IDS。( com.example.app.product1 的ID是 product1)。 请注意，您必须尽可能早的在你的应用中监听transactions-updated事件。
// Main process\nconst { inAppPurchase } = require('electron')\nconst PRODUCT_IDS = ['id1', 'id2']\n\n// Listen for transactions as soon as possible.\ninAppPurchase.on('transactions-updated', (event, transactions) => {\n if (!Array.isArray(transactions)) {\n return\n }\n\n // 检查每一笔交易.\n transactions.forEach(function (transaction) {\n const payment = transaction.payment\n\n switch (transaction.transactionState) {\n case 'purchasing':\n console.log(`Purchasing ${payment.productIdentifier}...`)\n break\n\n case 'purchased': {\n console.log(`${payment.productIdentifier} purchased.`)\n\n // Get the receipt url.\n const receiptURL = inAppPurchase.getReceiptURL()\n\n console.log(`Receipt URL: ${receiptURL}`)\n\n // Submit the receipt file to the server and check if it is valid.\n // @see https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html\n // ...\n // 如果收据通过校验，说明产品已经被购买了\n // ...\n\n // 交易完成.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n }\n\n case 'failed':\n\n console.log(`Failed to purchase ${payment.productIdentifier}.`)\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n case 'restored':\n\n console.log(`The purchase of ${payment.productIdentifier} has been restored.`)\n\n break\n case 'deferred':\n\n console.log(`The purchase of ${payment.productIdentifier} has been deferred.`)\n\n break\n default:\n break\n }\n })\n})\n\n// 检查用户是否允许当前app启用应用内购买功能.\nif (!inAppPurchase.canMakePayments()) {\n console.log('The user is not allowed to make in-app purchase.')\n}\n\n// Retrieve and display the product descriptions.\ninAppPurchase.getProducts(PRODUCT_IDS).then(products => {\n // 检查参数.\n if (!Array.isArray(products) || products.length <= 0) {\n console.log('Unable to retrieve the product informations.')\n return\n }\n\n // Display the name and price of each product.\n products.forEach(product => {\n console.log(`The price of ${product.localizedTitle} is ${product.formattedPrice}.`)\n })\n\n // 询问用户需要购买哪个产品.\n const selectedProduct = products[0]\n const selectedQuantity = 1\n\n // Purchase the selected product.\n inAppPurchase.purchaseProduct(selectedProduct.productIdentifier, selectedQuantity).then(isProductValid => {\n if (!isProductValid) {\n console.log('The product is not valid.')\n return\n }\n\n console.log('The payment has been added to the payment queue.')\n })\n})\n\n\n处理 HTTP/HTTPS 请求的响应。
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
ClientRequest实现了Readable Stream接口, 因此是一个EventEmitter类型.
返回:
\nchunk 缓冲区: 响应体数据块。data事件是将响应数据转换为应用程序代码的常用方法。
指示响应正文已结束。 必须在 'data' 事件之前放置。
\n正在进行的 HTTP 事务被取消后触发。
\n返回:
\nerror 通常保存一个错误字符串，识别失败的根本原因。
当流响应数据事件遇到错误时发出。 例如, 如果服务器在响应仍在流时关闭基础, 则会在响应对象上发出一个 error 事件, 随后将在请求对象上执行 close 事件。
IncomingMessage 实例具有以下可读属性:
response.statusCode一个指示 HTTP 响应状态代码的 Integer。
response.statusMessage表示HTTP状态消息的string。
response.headersA Record<string, string | string[]> 代表HTTP响应头。 headers对象格式如下：
age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer,retry-after, server, user-agentset-cookie 永远是一个数组。 重复项被添加到数组内。cookie 头，对应的值会用 '; ' 连接response.httpVersion表示HTTP协议版本号的 String 。 一般是“1”或“1.1”。 此外 httpVersionMajor 和httpVersionMinor 两整数值可读属性，分别返回HTTP的主要和次要版本号
response.httpVersionMajor表示HTTP协议主要版本号的 整数。
response.httpVersionMinor表示http协议次要版本号的整数。
modifiers String - An array of modifiers of the event, can be shift, control, ctrl, alt, meta, command, cmd, isKeypad, isAutoRepeat, leftButtonDown, middleButtonDown, rightButtonDown, capsLock, numLock, left, right.要安装预编译的 Electron 二进制文件，请使用 npm。 首选方法是在你的应用程序中安装 Electron 作为开发依赖：
npm install electron --save-dev\n查看versioning doc获取如何在你的应用中管理Electron的相关信息。
\n如果你不想在本地工程上使用 npm install 同时又没用其它选择时，你也可以使用 npm 捆绑的 npx 命令来运行 Electron ad-hoc：
npx electron .\n上面的命令会在当前工作目录下运行Electron。 需要注意的是，你的应用中的任何依赖将不会被安装。
\n如果想修改下载安装的位版本(例如, 在x64机器上安装ia32位版本), 你可以使用npm install中的--arch标记，或者设置npm_config_arch 环境变量:
npm install --arch=ia32 electron\n此外, 您还可以使用 --platform 来指定开发平台 (例如, win32、linux 等):
npm install --platform=win32 electron\n如果您需要使用 HTTP 代理，您需要设置 ELECTRON_GET_USE_PROXY 变量为 任何值。 附加额外的环境变量，取决于您的主机系统Node版本：
在安装过程中，electron 模块会通过 electron-download 为您的平台下载 Electron 的预编译二进制文件。 这将通过访问 GitHub 的发布下载页面来完成 (https://github.com/electron/electron/releases/tag/v$VERSION, 这里的 $VERSION 是 Electron 的确切版本).
如果您无法访问GitHub，或者您需要提供自定义构建，则可以通过提供镜像或现有的缓存目录来实现。
\n您可以使用环境变量来覆盖基本 URL，查找 Electron 二进制文件的路径以及二进制文件名。 electron/get 使用的网址组成如下：
url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME\n例如，使用一个中国的镜像：
\nELECTRON_MIRROR=\"https://cdn.npm.taobao.org/dist/electron/\"\n默认情况下，ELECTRON_CUSTTOM_DIR被设置为 v$VERSION。 要更改格式，请使用 {{ version }} 占位符。 例如，version-{{ version }} 被解析为 version-5.0.0, {{ version }} 被解析为 5.0.0， v{{ version }} 与默认值等价。 更具体的例子，使用中国非CDN镜像：
ELECTRON_MIRROR=\"https://npm.taobao.org/mirrors/electron/\"\nELECTRON_CUSTOM_DIR=\"{{ version }}\"\n上述配置将从URL下载，例如https://npm.taobao.org/mirrors/electron-v8.0.0-linux-x64.zip
If your mirror serves artifacts with different checksums to the official Electron release you may have to set ELECTRON_USE_REMOTE_CHECKSUMS=1 to force Electron to use the remote SHASUMS256.txt file to verify the checksum instead of the embedded checksums.
或者，您可以覆盖本地缓存。 electron-download 会将下载的二进制文件缓存在本地目录中，不会增加网络负担。 您可以使用该缓存文件夹来提供 Electron 的定制版本，或者避免进行网络连接。
$XDG_CACHE_HOME or ~/.cache/electron/~/Library/Caches/electron/$LOCALAPPDATA/electron/Cache or ~/AppData/Local/electron/Cache/在使用旧版本 Electron 的环境中，您也可以在~/.electron中找到缓存。
您也可以通过提供一个 electron_config_cache 环境变量来覆盖本地缓存位置。
缓存中包含了以文本文件形式存储的带有校验和的版本官方zip文件。 典型的缓存可能看起来像这样：
\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9electron-v1.7.9-darwin-x64.zip\n│ └── electron-v1.7.9-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1electron-v1.8.1-darwin-x64.zip\n│ └── electron-v1.8.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1electron-v1.8.2-beta.1-darwin-x64.zip\n│ └── electron-v1.8.2-beta.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2electron-v1.8.2-beta.2-darwin-x64.zip\n│ └── electron-v1.8.2-beta.2-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3electron-v1.8.2-beta.3-darwin-x64.zip\n│ └── electron-v1.8.2-beta.3-darwin-x64.zip\n└── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3SHASUMS256.txt\n └── SHASUMS256.txt\nUnder the hood, Electron's JavaScript API binds to a binary that contains its implementations. Because this binary is crucial to the function of any Electron app, it is downloaded by default in the postinstall step every time you install electron from the npm registry.
However, if you want to install your project's dependencies but don't need to use Electron functionality, you can set the ELECTRON_SKIP_BINARY_DOWNLOAD environment variable to prevent the binary from being downloaded. For instance, this feature can be useful in continuous integration environments when running unit tests that mock out the electron module.
ELECRON_SKIP_BINARY_DOWNOAD=1 npm install\n在运行 npm install electron 时，有些用户会偶尔遇到安装问题。
在大多数情况下，这些错误都是由网络问题导致，而不是因为 electron npm 包的问题。 如 ELIFECYCLE、EAI_AGAIN、ECONNRESET 和 ETIMEDOUT 等错误都是此类网络问题的标志。 最佳的解决方法是尝试切换网络，或是稍后再尝试安装。
You can also attempt to download Electron directly from electron/electron/releases if installing via npm is failing.
如果安装失败并报错EACCESS，您可能需要修复npm权限。
如果上述报错持续出现，unsafe-perm 标志可能需要被设置为 true:
\nsudo npm install electron --unsafe-perm=true\n在较慢的网络上, 最好使用 --verbose 标志来显示下载进度:
npm install --verbose electron\n如果需要强制重新下载文件, 并且 SHASUM 文件将 force_no_cache 环境变量设置为 true。
欢迎来到electron文档中心。 如果你第一次开发electron应用，可以阅读入门部分了解开发基础， 此外，你也可以直接浏览API文档
\nElectron是一个使用 JavaScript、HTML 和 CSS 构建桌面应用程序的框架。 嵌入 Chromium 和 Node.js 到 二进制的 Electron 允许您保持一个 JavaScript 代码代码库并创建 在Windows上运行的跨平台应用 macOS和Linux——不需要本地开发 经验。
\n熟悉该文档之前，需要你有Node.js和web开发经验。 如果您需要了解这两个方面的开发知识，我们推荐您使用以下学习资源：
\n\n此外，如果您熟悉Chromium进程模型，您将更好了解 Electron 的工作原理。 You can get a brief overview of Chrome architecture with the Chrome comic, which was released alongside Chrome's launch back in 2008. 尽管Chrome发布十多年了，【Chrome comic】漫画中介绍的核心原理仍然有助于理解Electron。
\nElectron Fiddle是由Electron开发并由其维护者支持的沙盒程序。 我们强烈建议将其作为一个学习工具来安装，以便在开发过程中对Electron的api进行实验或对特性进行原型化。
\nFiddle 已经完美的集成到我们的帮助文档之中。 当你浏览我们tutorial中的例子的时候，你会发现有个\"Open In Electron Fiddler\" 按钮在代码示例中。 如果你已经安装了Fiddle, “Open In Electron Fiddle\" 按钮回打开一个fiddle.electronjs.org链接并加载示例。
还是有疑问？ 请参考一下例子
\nelectron package里的疑难杂症，你可以去 GitHub issue tracker 查看是否有人已经遇到相同的问题。 如果你很幸运的找到bug，欢迎提交issue到github。readOperationCount Number - The number of I/O read operations.writeOperationCount Number - The number of I/O write operations.otherOperationCount Number - Then number of I/O other operations.readTransferCount Number - The number of I/O read transfers.writeTransferCount Number - The number of I/O write transfers.otherTransferCount Number - Then number of I/O other transfers.\n\n从主进程到渲染进程的异步通信。
\n
进程：主进程
\nipcRenderer 是一个 EventEmitter 的实例。 当在主进程中使用时，它处理从渲染器进程（网页）发送出来的异步和同步信息。 从渲染器进程发送的消息将被发送到该模块。
也可以从主进程向渲染进程发送消息，查阅ebContents.send获取更多信息。
\nchannel 。event.returnValue。event.reply(...)将异步消息发送回发送者。 此方法将自动处理从非主 frame 发送的消息(比如： iframes)。相应的发送方法是: event.sender.send(...) 它将总是把消息发送到主 frame下面是在渲染和主进程之间发送和处理消息的一个例子：
\n// 在主进程中.\nconst { ipcMain } = require('electron')\nipcMain.on('asynchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.reply('asynchronous-reply', 'pong')\n})\n\nipcMain.on('synchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.returnValue = 'pong'\n})\n//在渲染器进程 (网页) 中。\n// NB. Electron APIs are only accessible from preload, unless contextIsolation is disabled.\n// See https://www.electronjs.org/docs/tutorial/process-model#preload-scripts for more details.\nconst { ipcRenderer } = require('electron')\nconsole.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // prints \"pong\"\n\nipcRenderer.on('asynchronous-reply', (event, arg) => {\n console.log(arg) // prints \"pong\"\n})\nipcRenderer.send('asynchronous-message', 'ping')\nIpcMain模块有以下方法来侦听事件：
\nipcMain.on(channel, listener)channel Stringlistener Functionevent IpcMainEvent...args any[]监听 channel, 当新消息到达，将通过 listener(event, args...) 调用 listener。
\nipcMain.once(channel, listener)channel Stringlistener Functionevent IpcMainEvent...args any[]添加一次性 listener 函数。 这个 listener 只会在 channel下一次收到消息的时候被调用，之后这个监听器会被移除。
ipcMain.removeListener(channel, listener)channel Stringlistener Function...args any[]为特定的 channel 从监听队列中删除特定的 listener 监听者.
\nipcMain.removeAllListeners([channel])channel String (optional)移除所有指定 channel 的监听器； 若未指定 channel，则移除所有监听器。
\nipcMain.handle(channel, listener)channel Stringlistener Function<Promise\\event IpcMainInvokeEvent...args any[]为一个 invokeable的IPC 添加一个handler。 每当一个渲染进程调用 ipcRenderer.invoke(channel, ...args) 时这个处理器就会被调用。
如果 listener 返回一个 Promise，那么 Promise 的最终结果就是远程调用的返回值。 否则， 监听器的返回值将被用来作为应答值。
// 主进程\nipcMain.handle('my-invokable-ipc', async (event, ...args) => {\n const result = await somePromise(...args)\n return result\n})\n\n// 渲染进程\nasync () => {\n const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)\n // ...\n}\n传递给处理器的第一个参数的 event 与传递给常规事件侦听器的相同。 里面包含了哪些 WebContents 是调用请求的来源
通过handle在主线程抛出的异常并不易读，那是因为他们已经被序列化了。只有原始错误中的 message 属性可提供给渲染进程。 详情请参阅 #24427
ipcMain.handleOnce(channel, listener)channel Stringlistener Function<Promise\\event IpcMainInvokeEvent...args any[]处理单个 invokeable 可触发的 IPC 消息，然后移除侦听器。 详见 ipcMain.handle(channel, listener)
ipcMain.removeHandler(channel)channel String移除 channel的所有处理程序，若存在。
callback 的参数 event 对象文档可以在 ipc-main-event 一节找到。
handle回调参数event对象文档可以在ipc-main-invoke-event一节找到
EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagereturnValue any - Set this to the value to be returned in a synchronous messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this messageports MessagePortMain[] - A list of MessagePorts that were transferred with this messagereply Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to \"reply\" to the sent message in order to guarantee the reply will go to the correct process and frame.channel String...args any[]EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this message\n\n从渲染器进程到主进程的异步通信。
\n
进程: Renderer
\nipcRenderer 是一个 EventEmitter 的实例。 你可以使用它提供的一些方法从渲染进程 (web 页面) 发送同步或异步的消息到主进程。 也可以接收主进程回复的消息。
请从 ipcMain 查看代码示例。
\nipcRenderer 模块使用以下方法来监听事件和发送消息。
ipcRenderer.on(channel, listener)channel Stringlistener Functionevent IpcRendererEvent...args any[]监听 channel, 当新消息到达，将通过 listener(event, args...) 调用 listener。
\nipcRenderer.once(channel, listener)channel Stringlistener Functionevent IpcRendererEvent...args any[]添加一次性 listener 函数。 这个 listener 只会在 channel下一次收到消息的时候被调用，之后这个监听器会被移除。
ipcRenderer.removeListener(channel, listener)channel Stringlistener Function...args any[]为特定的 channel 从监听队列中删除特定的 listener 监听者.
\nipcRenderer.removeAllListeners(channel)channel String移除所有的监听器，当指定 channel 时只移除与其相关的所有监听器。
ipcRenderer.send(channel, ...args)channel String...args any[]通过channel向主进程发送异步消息，可以发送任意参数。 Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
The main process handles it by listening for channel with the ipcMain module.
If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you want to receive a single response from the main process, like the result of a method call, consider using ipcRenderer.invoke.
ipcRenderer.invoke(channel, ...args)channel String...args any[]Returns Promise<any> - Resolves with the response from the main process.
Send a message to the main process via channel and expect a result asynchronously. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
The main process should listen for channel with ipcMain.handle().
例如：
\n// Renderer process\nipcRenderer.invoke('some-name', someArgument).then((result) => {\n // ...\n})\n\n// Main process\nipcMain.handle('some-name', async (event, someArgument) => {\n const result = await doSomeWork(someArgument)\n return result\n})\nIf you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
如果你不需要回复此消息，请考虑使用 ipcRender.sent。
ipcRenderer.sendSync(channel, ...args)channel String...args any[]返回 any - 由 ipcMain 处理程序发送过来的值。
Send a message to the main process via channel and expect a result synchronously. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
主进程可以使用 ipcMain 监听 channel来接收这些消息，并通过 event.returnValue 设置回复消息。
\n\n⚠️ WARNING: Sending a synchronous message will block the whole renderer process until the reply is received, so use this method only as a last resort. It's much better to use the asynchronous version,
\ninvoke().
ipcRenderer.postMessage(channel, message, [transfer])Send a message to the main process, optionally transferring ownership of zero or more MessagePort objects.
The transferred MessagePort objects will be available in the main process as MessagePortMain objects by accessing the ports property of the emitted event.
例如：
\n// Renderer process\nconst { port1, port2 } = new MessageChannel()\nipcRenderer.postMessage('port', { message: 'hello' }, [port1])\n\n// Main process\nipcMain.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nFor more information on using MessagePort and MessageChannel, see the MDN documentation.
ipcRenderer.sendTo(webContentsId, channel, ...args)webContentsId Numberchannel String...args any[]通过 channel 发送消息到带有 webContentsId 的窗口.
ipcRenderer.sendToHost(channel, ...args)channel String...args any[]就像 ipcRenderer.send，不同的是消息会被发送到 host 页面上的 <webview> 元素，而不是主进程。
The documentation for the event object passed to the callback can be found in the ipc-renderer-event structure docs.
Eventsender IpcRenderer - The IpcRenderer instance that emitted the event originallysenderId Integer - The webContents.id that sent the message, you can call event.sender.sendTo(event.senderId, ...) to reply to the message, see ipcRenderer.sendTo for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set event.senderId to 0.ports MessagePort[] - A list of MessagePorts that were transferred with this message对于任何问题，个人可以通过三种方式贡献：
\nelectron/electron issue tracker.electron/electron中的源代码的拉取请求。\"Finding Support\" has a list of resources for getting programming help, reporting security issues, contributing, and more. 请仅对漏洞使用问题追踪器！
\nTo submit a bug report:
\nWhen opening a new issue in the electron/electron issue tracker, users will be presented with a template that should be filled in.
如果你确信自己发现了Electron的bug，请尽可能详细的填写一份表单。
\n要评估报告需要的两个最重要的部分是漏洞的描述和重现它的简单测试样例。 It is easier to fix a bug if it can be reproduced.
\n\n提出问题经常会出现讨论。 贡献者会有不同的观点，包括提出的情况是一个漏洞还是一个功能。 这些讨论是解决问题的一部分，并且应该保持专注、有用、专业。
\n没有任何内容和详细信息的简单回复是无用的而且不专业的。 在很多情况下，这些恢复是烦人而且不友好的。
\n我们鼓励贡献者共同解决问题并互相帮助取得进展。 If you encounter an issue that you feel is invalid, or which contains incorrect information, explain why you feel that way with additional supporting context, and be willing to be convinced that you may be wrong. 通过这样做，我们可以更快地得到正确的结果。
\n大部分的问题是通过打开拉取请求解决的。 The process for opening and reviewing a pull request is similar to that of opening and triaging issues, but carries with it a necessary review and approval workflow that ensures that the proposed changes meet the minimal quality and functional guidelines of the Electron project.
", "title": "Electron中的问题", "description": "" }, "/docs/api/structures/jump-list-category": { "locale": "zh-CN", "slug": "jump-list-category", "href": "/docs/api/structures/jump-list-category", "crowdinFileId": "256451", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/jump-list-category.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "type String (optional) - One of the following:tasks - Items in this category will be placed into the standard Tasks category. There can be only one such category, and it will always be displayed at the bottom of the Jump List.frequent - Displays a list of files frequently opened by the app, the name of the category and its items are set by Windows.recent - Displays a list of files recently opened by the app, the name of the category and its items are set by Windows. Items may be added to this category indirectly using app.addRecentDocument(path).custom - Displays tasks or file links, name must be set by the app.name String (optional) - Must be set if type is custom, otherwise it should be omitted.items JumpListItem - Array of JumpListItem objects if type is tasks or custom, otherwise it should be omitted.Note: If a JumpListCategory object has neither the type nor the name property set then its type is assumed to be tasks. If the name property is set but the type property is omitted then the type is assumed to be custom.
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
type String (optional) - One of the following:task - A task will launch an app with specific arguments.separator - Can be used to separate items in the standard Tasks category.file - A file link will open a file using the app that created the Jump List, for this to work the app must be registered as a handler for the file type (though it doesn't have to be the default handler).path String (optional) - Path of the file to open, should only be set if type is file.program String (optional) - Path of the program to execute, usually you should specify process.execPath which opens the current program. Should only be set if type is task.args String (optional) - The command line arguments when program is executed. Should only be set if type is task.title String (optional) - The text to be displayed for the item in the Jump List. Should only be set if type is task.description String (optional) - Description of the task (displayed in a tooltip). Should only be set if type is task. Maximum length 260 characters.iconPath String (optional) - The absolute path to an icon to be displayed in a Jump List, which can be an arbitrary resource file that contains an icon (e.g. .ico, .exe, .dll). You can usually specify process.execPath to show the program icon.iconIndex Number (optional) - The index of the icon in the resource file. If a resource file contains multiple icons this value can be used to specify the zero-based index of the icon that should be displayed for this task. If a resource file contains only one icon, this property should be set to zero.workingDirectory String (optional) - The working directory. Default is empty.ctrlKey Boolean (optional) - whether the Control key was used in an accelerator to trigger the EventmetaKey Boolean (optional) - whether a meta key was used in an accelerator to trigger the EventshiftKey Boolean (optional) - whether a Shift key was used in an accelerator to trigger the EventaltKey Boolean (optional) - whether an Alt key was used in an accelerator to trigger the EventtriggeredByAccelerator Boolean (optional) - whether an accelerator was used to trigger the event as opposed to another user gesture like mouse clickInputEventtype String - The type of the event, can be keyDown, keyUp or char.keyCode String - The character that will be sent as the keyboard event. Should only use the valid key codes in Accelerator.该功能允许你为 Electron 应用程序配置应用和全局键盘快捷键。
\n应用键盘快捷键仅在应用程序被聚焦时触发。 为了配置本地快捷键，你需要在创建Menu模块中的MenuItem时指定`accelerator<0>属性。
\n从 Quick Start Guide 中的应用开始，将以下内容更新到 main.js`。
\nconst { Menu, MenuItem } = require('electron')\n\nconst menu = new Menu()\nmenu.append(new MenuItem({\n label: 'Electron',\n submenu: [{\n role: 'help',\n accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Alt+Shift+I',\n click: () => { console.log('Electron rocks!') }\n }]\n}))\n\nMenu.setApplicationMenu(menu)\n
\n\n注意：在上面的代码中，您可以看到基于用户的操作系统的 accelerator 差异。 对于MacOS，是 Alt+Cmd+I，而对于Linux 和 Windows，则是 Alt+Shift+I.
\n
\n启动 Electron 应用程序后，你应该看到应用程序菜单以及您刚刚定义的本地快捷方式：
\n
\nIf you click Help or press the defined accelerator and then open the terminal that you ran your Electron application from, you will see the message that was generated after triggering the click event: \"Electron rocks!\".
\n全局快捷键
\n要配置全局键盘快捷键， 您需要使用 globalShortcon 模块来检测键盘事件，即使应用程序没有获得键盘焦点。
\n从 Quick Start Guide 中的应用开始，将以下内容更新到 main.js。
\nconst { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n globalShortcut.register('Alt+CommandOrControl+I', () => {\n console.log('Electron loves global shortcuts!')\n })\n}).then(createWindow)\n
\n\nNOTE: In the code above, the CommandOrControl combination uses Command on macOS and Control on Windows/Linux.
\n
\nAfter launching the Electron application, if you press the defined key combination then open the terminal that you ran your Electron application from, you will see that Electron loves global shortcuts!
\n在浏览器窗口内的快捷方式
\n使用 web APIs
\n如果您想要在 BrowserWindow 中处理键盘快捷键，你可以在渲染进程中使用 addEventListener() API来监听 kepup 和 keydown DOM事件。
\nfunction handleKeyPress(event) {\n // 你可以把处理按键按下事件的代码放在这里。\n document.getElementById(\"last-keypress\").innerText = event.key;\n console.log(`你按下了 ${event.key}`);\n}\n\nwindow.addEventListener('keyup', handleKeyPress, true);\n
\n\n注意：第三个参数 true 表明了当前监听器会持续在其它监听器之前接收按键按下事件，因此无法在其它监听器中调用 stopPropagation()。
\n
\n拦截主进程中的事件
\n在调度页面中的keydown和keyup事件之前，会发出before-input-event事件。 它可以用于捕获和处理在菜单中不可见的自定义快捷方式。
\n从 Quick Start Guide 中的应用开始，将以下内容更新到 main.js。
\nconst { app, BrowserWindow } = require('electron')\n\napp.whenReady().then(() => {\n const win = new BrowserWindow({ width: 800, height: 600 })\n\n win.loadFile('index.html')\n win.webContents.on('before-input-event', (event, input) => {\n if (input.control && input.key.toLowerCase() === 'i') {\n console.log('Pressed Control+I')\n event.preventDefault()\n }\n })\n})\n
\n在运行Electron应用程序之后，如果你打开你运行Electron应用的终端并按下 Ctrl+I 组合键，你会发现刚才按下的组合键被成功拦截了。
\n使用第三方库
\n如果您不想手动进行快捷键解析，可以使用一些库来进行高级的按键检测。例如 mousetrap. 以下是在渲染进程中 mousetrap 的使用示例：
\nMousetrap.bind('4', () => { console.log('4') })\nMousetrap.bind('?', () => { console.log('show shortcuts!') })\nMousetrap.bind('esc', () => { console.log('escape') }, 'keyup')\n\n// combinations\nMousetrap.bind('command+shift+k', () => { console.log('command shift k') })\n\n// map multiple combinations to the same callback\nMousetrap.bind(['command+k', 'ctrl+k'], () => {\n console.log('command k or control k')\n\n // return false to prevent default behavior and stop event from bubbling\n return false\n})\n\n// gmail style sequences\nMousetrap.bind('g i', () => { console.log('go to inbox') })\nMousetrap.bind('* a', () => { console.log('select all') })\n\n// konami code!\nMousetrap.bind('up up down down left right left right b a enter', () => {\n console.log('konami code')\n})\n
",
"title": "键盘快捷键",
"description": "注意：在上面的代码中，您可以看到基于用户的操作系统的 accelerator 差异。 对于MacOS，是 Alt+Cmd+I，而对于Linux 和 Windows，则是 Alt+Shift+I."
},
"/docs/tutorial/launch-app-from-url-in-another-app": {
"locale": "zh-CN",
"slug": "launch-app-from-url-in-another-app",
"href": "/docs/tutorial/launch-app-from-url-in-another-app",
"crowdinFileId": "256211",
"githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/launch-app-from-url-in-another-app.md",
"category": "tutorial",
"categoryFancy": "Guides",
"isTutorial": true,
"isApiDoc": false,
"isApiStructureDoc": false,
"isDevTutorial": false,
"html": "title: Launching Your Electron App From a URL In Another App\ndescription: 本指南将会指导您配置 Electron 应用为特定协议的默认处理器。\nslug: 从其他应用中的URL启动应用
\nThis guide will take you through the process of setting your Electron app as the default handler for a specific protocol.
\n通过此教程，您会掌握如何设置您的应用以拦截并处理任意特定协议的URL的点击事件。 在本指南中，我们假定这个协议名为“electron-fiddle://”。
First, we will import the required modules from electron. These modules help control our application lifecycle and create a native browser window.
const { app, BrowserWindow, shell } = require('electron')\nconst path = require('path')\n其次，我们将应用注册为“electron-fiddle://”协议的处理器。
if (process.defaultApp) {\n if (process.argv.length >= 2) {\n app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])\n }\n} else {\n app.setAsDefaultProtocolClient('electron-fiddle')\n}\n现在我们定义负责创建浏览器窗口的函数，并加载应用的 index.html 文件。
const createWindow = () => {\n // Create the browser window.\n mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n mainWindow.loadFile('index.html')\n}\n紧接着，我们将创建 BrowserWindow 并在应用中定义如何处理此外部协议被点击的事件。
This code will be different in Windows compared to MacOS and Linux. This is due to Windows requiring additional code in order to open the contents of the protocol link within the same Electron instance. 请点击 此处 了解更多
\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // 用户正在尝试运行第二个实例，我们需要让焦点指向我们的窗口\n if (mainWindow) {\n if (mainWindow.isMinimized()) mainWindow.restore()\n mainWindow.focus()\n }\n })\n\n // 创建 mainWindow，加载其他资源，等等……\n app.whenReady().then(() => {\n createWindow()\n })\n\n // Handle the protocol. 在本例中，我们选择显示一个错误提示对话框。\n app.on('open-url', (event, url) => {\n dialog.showErrorBox('欢迎回来', `导向自: ${url}`)\n })\n}\n// Electron 在完成初始化，并准备创建浏览器窗口时，\n// 会调用这个方法。\n// 部分 API 在 ready 事件触发后才能使用。\napp.whenReady().then(() => {\n createWindow()\n})\n\n// Handle the protocol. 在本例中，我们选择显示一个错误提示对话框。\napp.on('open-url', (event, url) => {\n dialog.showErrorBox('欢迎回来', `导向自: ${url}`)\n})\nFinally, we will add some additional code to handle when someone closes our application.
\n// 在除 MacOS 的其他平台上，当所有窗口关闭后，退出当前应用。 There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') app.quit()\n})\nOn macOS and Linux, this feature will only work when your app is packaged. It will not work when you're launching it in development from the command-line. When you package your app you'll need to make sure the macOS Info.plist and the Linux .desktop files for the app are updated to include the new protocol handler. Some of the Electron tools for bundling and distributing apps handle this for you.
If you're using Electron Forge, adjust packagerConfig for macOS support, and the configuration for the appropriate Linux makers for Linux support, in your Forge configuration (please note the following example only shows the bare minimum needed to add the configuration changes):
{\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"protocols\": [\n {\n \"name\": \"Electron Fiddle\",\n \"schemes\": [\"electron-fiddle\"]\n }\n ]\n },\n \"makers\": [\n {\n \"name\": \"@electron-forge/maker-deb\",\n \"config\": {\n \"mimeType\": [\"x-scheme-handler/electron-fiddle\"]\n }\n }\n ]\n }\n }\n}\nFor macOS support:
\nIf you're using Electron Packager's API, adding support for protocol handlers is similar to how Electron Forge is handled, except protocols is part of the Packager options passed to the packager function.
const packager = require('electron-packager')\n\npackager({\n // ...other options...\n protocols: [\n {\n name: 'Electron Fiddle',\n schemes: ['electron-fiddle']\n }\n ]\n\n}).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))\n .catch(err => console.error(`ERROR: ${err.message}`))\nIf you're using Electron Packager's CLI, use the --protocol and --protocol-name flags. For example:
npx electron-packager . --protocol=electron-fiddle --protocol-name=\"Electron Fiddle\"\nAfter you start your Electron app, you can enter in a URL in your browser that contains the custom protocol, for example \"electron-fiddle://open\" and observe that the application will respond and show an error dialog box.
On many Linux environments, you can add custom entries to the system launcher by modifying the .desktop file. 关于 Canonical 的 Unity 启动器文档， 参考 Adding Shortcuts to a Launcher。 详细的参考信息请见 freedesktop.org Specification。
\n\n注：上面的截图是 Audacious 音频播放器中启动器快捷方式的一个例子
\n
若要创建快捷方式，你需要为添加到快捷菜单的条目提供 Name 和 Exec 属性。 Unity 将在用户点击快捷菜单项后执行 Exec 字段定义的命令。 .desktop 文件的示例如下：
Actions=PlayPause;Next;Previous\n\n[Desktop Action PlayPause]\nName=Play-Pause\nExec=audacious -t\n\n\n[Desktop Action Next]\nName=Next\nExec=audacious -f\n\n\n[Desktop Action Previous]\nName=Previous\nExec=audacious -r\nUnity 推荐应用程序操作的首选方式是使用参数。 您可以在应用的全局变量 process.argv 中找到它们。
本指南提供以下相关资讯：
\n要为 Electron 应用签名，则必须首先安装下列应用：
\n您还必须注册一个苹果开发者帐户，并加入 苹果开发者计划。
\nElectron应用可以通过 Mac 应用商店或其外部进行发布。 每种方式都需要不同的签名和测试方法。 本指南侧重于通过 Mac 应用商店进行发布，也会提及其他方法。
\n以下步骤描述了如何从 Apple 获得证书，如何对Electron应用程序进行签名以及如何测试它们。
\n获得签名证书的最简单方法是使用 Xcode：
\n“Apple Development”证书用于在Apple Developer网站上注册的计算机上签署用于开发和测试的应用程序。 注册方法会在准备配置文件中描述。
\n带有\"Apple Development\"证书签名的应用无法提交到Mac 应用商店。 为此，应用程序必须使用\"Apple Distribution\"证书进行签名。 但请注意，使用\"Apple Distribution\"证书签名的应用程序不能直接运行，它们必须由 Apple 重新签名才能运行，也就是只有从 Mac 应用商店下载后才能运行。
\n您可以注意到还有其他类型的证书。
\n\"Developer ID Application\"证书用于将应用发布到Mac 应用商店以外的地方之前签名。
\n\"Deceloper ID Installer\"和\"Mac Installer Distribution\"证书用于签署 Mac 安装程序包，而不是应用程序本身。 大多数Electron应用不使用Mac Installer Package，因此通常不需要它们。
\n完整的证书类型列表可以在这里找到。
\n使用 \"Apple Development\" 和 \"Apple Distribution\" 证书签名的应用程序只能在 App Sandbox下运行， 所以他们必须使用Electron 的 MAS 构建。 然而，“Developer ID Application”证书没有这个限制，因此，用其签名的应用既可以使用普通构建也可以使用 Electron 的 MAS 构建。
\nApple在过去几年中一直在更改证书的名称，您可能会在阅读旧文档时遇到这些证书，并且一些工具仍然在使用旧名称。
\n如果您想在将应用提交给Mac App Store之前在本地机器上测试您的应用， 您必须使用\"Apple Development\"证书签名该应用，并在程序包中嵌入配置文件。
\n要 创建一个配置文件，您可以按照以下步骤：
\n/path/to/yourapp.provisionfile。提交到 Mac App Store 的应用程序必须在 Apple App Sandbox下运行， 并且只有Electron的 MAS 构建可以使用App Sandbox 运行。 在 App Sandbox 下运行时，Electron 的标准 darwin 构建将无法启动。
\n使用 electron-osx-signe签名时，它将会自动将必要的权限添加到您应用的所需权利中， 但如果您正在使用自定义所需权利，您必须确保App Sandbox capacity已经添加：
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n </dict>\n</plist>\nelectron-osx-sign的额外步骤如果您的应用没有使用 electron-osx-signe 进行签名，您必须确保应用包的权限至少有以下键：
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.application-groups</key>\n <array>\n <string>TEAM_ID.your.bundle.id</string>\n </array>\n </dict>\n</plist>\nTEAM_ID 应替换为 Apple 开发者帐户的Team ID，your.bundle.id 应替换为应用的App ID。
以下权限必须添加到应用程序包的二进制程序和助手中：
\n\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.inherit</key>\n <true/>\n </dict>\n</plist>\n应用程序包的 Info.plist 必须包含 ElectronTeamID 键，其值为你的 Apple 开发者团队ID：
<plist version=\"1.0\">\n<dict>\n ...\n <key>ElectronTeamID</key>\n <string>TEAM_ID</string>\n</dict>\n</plist>\n当使用 electron-osx-signing 时， ElectronTeamID 键将通过从证书名称提取团队 ID 自动添加。 如果electron-osx-sign找不到正确的团队 ID，则可能需要你手动添加此键 。
To sign an app that can run on your development machine, you must sign it with the \"Apple Development\" certificate and pass the provisioning profile to electron-osx-sign.
electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile\nIf you are signing without electron-osx-sign, you must place the provisioning profile to YourApp.app/Contents/embedded.provisionprofile.
The signed app can only run on the machines that registered by the provisioning profile, and this is the only way to test the signed app before submitting to Mac App Store.
\nTo sign an app that will be submitted to Mac App Store, you must sign it with the \"Apple Distribution\" certificate. Note that apps signed with this certificate will not run anywhere, unless it is downloaded from Mac App Store.
\nelectron-osx-sign YourApp.app --identity='Apple Distribution'\nIf you don't plan to submit the app to Mac App Store, you can sign it the \"Developer ID Application\" certificate. In this way there is no requirement on App Sandbox, and you should use the normal darwin build of Electron if you don't use App Sandbox.
\nelectron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess\nBy passing --no-gatekeeper-assess, the electron-osx-sign will skip the macOS GateKeeper check as your app usually has not been notarized yet by this step.
This guide does not cover App Notarization, but you might want to do it otherwise Apple may prevent users from using your app outside Mac App Store.
\nAfter signing the app with the \"Apple Distribution\" certificate, you can continue to submit it to Mac App Store.
\nHowever, this guide do not ensure your app will be approved by Apple; you still need to read Apple's Submitting Your App guide on how to meet the Mac App Store requirements.
\nThe Application Loader should be used to upload the signed app to iTunes Connect for processing, making sure you have created a record before uploading.
\nIf you are seeing errors like private APIs uses, you should check if the app is using the MAS build of Electron.
\nAfter uploading, you should submit your app for review.
\n为了让你的应用满足沙箱的所有条件，在 MAS 构建的时候，下面的模块已被禁用：
\ncrashReporterautoUpdater并且下面的行为也改变了:
\n此外，由于应用沙盒的使用，应用程序可以访问的资源受到严格限制；您可以阅读 应用沙盒 ，了解更多信息。
\nDepending on which Electron APIs your app uses, you may need to add additional entitlements to your app's entitlements file. Otherwise, the App Sandbox may prevent you from using them.
\n启用传出的网络连接，允许你的应用程序连接到服务器：
\n<key>com.apple.security.network.client</key>\n<true/>\n启用传入的网络连接，让你的应用程序打开网络 socket 监听：
\n<key>com.apple.security.network.server</key>\n<true/>\n有关更多 详细信息，请参阅启用网络访问文档。
\n<key>com.apple.security.files.user-selected.read-only</key>\n<true/>\n有关更多详细信息，请参阅\"启用访问用户选择的文件\"文档。
\n<key>com.apple.security.files.user-selected.read-write</key>\n<true/>\n有关更多详细信息，请参阅\"启用访问用户选择的文件\"文档。
\n根据你发布应用所在的国家或地区，你可能需要提供您软件使用的加密算法的信息。 更多信息，请参阅 加密导出合规性文档 。
\nElectron 使用下列加密算法：
\nElectron有API来配置macOS Dock中的应用程序图标。 A macOS-only API exists to create a custom dock menu, but Electron also uses the app dock icon as the entry point for cross-platform features like recent documents and application progress.
\n一个自定义的Dock项也普遍用于为那些用户不愿意为之打开整个应用窗口的任务添加快捷方式。
\nTerminal.app 的 Dock 菜单:
\n
要设置您的自定义 dock 菜单，您需要使用 app.dock.setmenu API，它仅在 macOS 上可用。
从 Quick Start Guide 中的应用开始，将以下内容更新到 main.js。
const { app, BrowserWindow, Menu } = require('electron')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n })\n\n win.loadFile('index.html')\n}\n\nconst dockMenu = Menu.buildFromTemplate([\n {\n label: 'New Window',\n click () { console.log('New Window') }\n }, {\n label: 'New Window with Settings',\n submenu: [\n { label: 'Basic' },\n { label: 'Pro' }\n ]\n },\n { label: 'New Command...' }\n])\n\napp.whenReady().then(() => {\n if (process.platform === 'darwin') {\n app.dock.setMenu(dockMenu)\n }\n}).then(createWindow)\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n\nAfter launching the Electron application, right click the application icon. 您应该可以看到您刚刚设置的自定义菜单：
\n
workingSetSize Integer - The amount of memory currently pinned to actual physical RAM.peakWorkingSetSize Integer - The maximum amount of memory that has ever been pinned to actual physical RAM.privateBytes Integer (optional) Windows - The amount of memory not shared by other processes, such as JS heap or HTML content.Note that all statistics are reported in Kilobytes.
", "title": "MemoryInfo Object", "description": "" }, "/docs/api/structures/memory-usage-details": { "locale": "zh-CN", "slug": "memory-usage-details", "href": "/docs/api/structures/memory-usage-details", "crowdinFileId": "256461", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/memory-usage-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "count Numbersize NumberliveSize Number\n\n创建原生应用菜单和上下文菜单。
\n
进程：主进程
\nnew Menu()创建新菜单。
\nMenu类有以下方法:
Menu.setApplicationMenu(menu)menu Menu | null在macOS上将 menu设置成应用内菜单 在windows和Linux上，menu 将会被设置成窗口顶部菜单
在Windows和Linux中，可以在菜单的顶层标签的某个字母前添加&以绑定快捷键。 例如，使用&File后可以使用Alt-F呼出File的子选项。 按钮标签中指定的字符会出现下划线， & 字符不会显示在按钮标签上。
要转义并在项名中显示 & 字符, 可以添加字符 &. 比如, &&File 将在按钮标签上出现 &File
传递 null 值可以禁用默认菜单。 在 Windows 和 Linux 上，使用此方法移除窗口上的菜单栏可能会有额外的效果。
注释:如果应用没有设置菜单的话，系统会生成一个默认菜单。 默认生成的菜单中包含了一些初始选项，例如 文件,编辑, 视图,窗口,帮助。
Menu.getApplicationMenu()返回 Menu | null - 如果有设置, 则返回应用程序菜单， 如果没设置，则返回 null。
注释:返回的 Menu实例不支持动态添加或删除菜单项， 但仍然可以动态修改 实例属性 。
Menu.sendActionToFirstResponder(action) macOSaction String将 action 发送到应用程序的第一个响应方。 这用于模拟默认的 macOS 菜单行为。 通常你可以使用MenuItem的role属性
有关 macOS 的本地操作的详细信息, 请参阅 macOS Cocoa Event Handling Guide 。
\nMenu.buildFromTemplate(template)template (MenuItemConstructorOptions | MenuItem)[]返回 Menu
一般来说， template是一个options类型的数组，用于构建MenuItem。 使用方法可参考前文。
您还可以将其他字段附加到template，它们将成为菜单项的属性。
menu 对象具有以下实例方法:
menu.popup([options])options Object (可选)window BrowserWindow (可选) - 默认为选中窗口.x Number (可选) - 默认为当前鼠标的位置。 如果指定了y，则该选项必选。y Number (可选) - 默认为当前鼠标的位置。 如果指定了x，则该选项必选。positioningItem Number (可选) macOS - 在指定鼠标光标下定位的菜单项的索引。 默认值为 -1。callback Function (optional) - 会在菜单关闭后被调用.弹出此菜单作为上下文菜单在 BrowserWindow。
menu.closePopup([browserWindow])browserWindow BrowserWindow (可选) - 默认为选中窗口.关闭 browserWindow 中的上下文菜单。
menu.append(menuItem)menuItem 菜单项将 menuItem 追加到菜单。
menu.getMenuItemById(id)id String返回具有指定id项的MenuItem | null
menu.insert(pos, menuItem)pos IntegermenuItem 菜单项将 menuItem 插入菜单的 pos 位置。
使用 new Menu 创建对象或通过 Menu.buildFromTemplate返回对象均会触发下列事件：
注意: 某些事件仅在特定的操作系统上可用, 这些方法会被标记出来。
\n返回:
\nevent Event调用menu.popup()事件时触发该事件。
返回:
\nevent Event手动关闭弹出，或使用 menu.closePopup()方法关闭弹出时，触发该事件。
menu 对象还具有以下属性:
menu.items包含菜单项的 MenuItem [] 数组。
每个 菜单 由多个 MenuItem 组成, 每个 MenuItem可以有子菜单。
使用简单模板API创建 application menu 的示例代码：
\nconst { app, Menu } = require('electron')\n\nconst isMac = process.platform === 'darwin'\n\nconst template = [\n // { role: 'appMenu' }\n ...(isMac ? [{\n label: app.name,\n submenu: [\n { role: 'about' },\n { type: 'separator' },\n { role: 'services' },\n { type: 'separator' },\n { role: 'hide' },\n { role: 'hideOthers' },\n { role: 'unhide' },\n { type: 'separator' },\n { role: 'quit' }\n ]\n }] : []),\n // { role: 'fileMenu' }\n {\n label: 'File',\n submenu: [\n isMac ? { role: 'close' } : { role: 'quit' }\n ]\n },\n // { role: 'editMenu' }\n {\n label: 'Edit',\n submenu: [\n { role: 'undo' },\n { role: 'redo' },\n { type: 'separator' },\n { role: 'cut' },\n { role: 'copy' },\n { role: 'paste' },\n ...(isMac ? [\n { role: 'pasteAndMatchStyle' },\n { role: 'delete' },\n { role: 'selectAll' },\n { type: 'separator' },\n {\n label: 'Speech',\n submenu: [\n { role: 'startSpeaking' },\n { role: 'stopSpeaking' }\n ]\n }\n ] : [\n { role: 'delete' },\n { type: 'separator' },\n { role: 'selectAll' }\n ])\n ]\n },\n // { role: 'viewMenu' }\n {\n label: 'View',\n submenu: [\n { role: 'reload' },\n { role: 'forceReload' },\n { role: 'toggleDevTools' },\n { type: 'separator' },\n { role: 'resetZoom' },\n { role: 'zoomIn' },\n { role: 'zoomOut' },\n { type: 'separator' },\n { role: 'togglefullscreen' }\n ]\n },\n // { role: 'windowMenu' }\n {\n label: 'Window',\n submenu: [\n { role: 'minimize' },\n { role: 'zoom' },\n ...(isMac ? [\n { type: 'separator' },\n { role: 'front' },\n { type: 'separator' },\n { role: 'window' }\n ] : [\n { role: 'close' }\n ])\n ]\n },\n {\n role: 'help',\n submenu: [\n {\n label: 'Learn More',\n click: async () => {\n const { shell } = require('electron')\n await shell.openExternal('https://electronjs.org')\n }\n }\n ]\n }\n]\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\n要创建由渲染器启动的菜单，请通过 IPC 发送所需的信息到主过程，并让主过程代替渲染器显示菜单。
\n以下是用户右键单击页面时显示菜单的示例：
\n// renderer\nwindow.addEventListener('contextmenu', (e) => {\n e.preventDefault()\n ipcRenderer.send('show-context-menu')\n})\n\nipcRenderer.on('context-menu-command', (e, command) => {\n // ...\n})\n\n// main\nipcMain.on('show-context-menu', (event) => {\n const template = [\n {\n label: 'Menu Item 1',\n click: () => { event.sender.send('context-menu-command', 'menu-item-1') }\n },\n { type: 'separator' },\n { label: 'Menu Item 2', type: 'checkbox', checked: true }\n ]\n const menu = Menu.buildFromTemplate(template)\n menu.popup(BrowserWindow.fromWebContents(event.sender))\n})\nmacOS 相比于 Windows 和 Linux 有着完全不同的应用程序菜单。 以下是一些有关使应用菜单更像原生应用菜单的注意事项。
\nMacOS有一些系统预定义的菜单，像是Services and Windows。 让你的菜单更像MacOS标准菜单，只需设置菜单role值为如下示之一，Electron便会自动认出并设置成标准菜单，：
windowhelpservicesmacOS 已经为某些菜单项提供了标准操作, 如 about xxx、Hide xxx 和 Hide Others。 若要将菜单项的操作设置为标准操作, 应设置菜单项的 role 属性。
在 macOS 中应用程序菜单的第一个项目的标签总是你的应用程序的名字, 无论你设置什么标签。 如要更改它, 请修改应用程序包的 Info. plist 文件。 详情参阅：About Information Property List Files
浏览器窗口的 setMenu 方法 可以设置特定浏览器窗口的菜单。
你可以使用 before, after, beforeGroupContaining, afterGroupContaining 和 id 来控制由 Menu.buildFromTemplate 生成的菜单项的位置.
before - 在指定的标签之前插入菜单项。 如果引用值不存在，那么该菜单项会插在这个菜单的尾部。 这还意味着，菜单项应该被放置在与引用项相同的组中。after - 在指定的标签之后插入菜单项。 如果引用值不存在，那么该菜单项会插在这个菜单的尾部。 这还意味着，菜单项应该被放置在与引用项相同的组中。beforeGroupContaining - 为单个上下文菜单提供一种方法，用于在具有指定标签项的包含组之前声明其包含组的位置afterGroupContaining - 为单个上下文菜单提供一种方法，用于在具有指定标签项的包含组之后声明其包含组的位置默认情况下，除非有位置相关的属性，所有的菜单项会按照模板中的顺序排放。
\n模板：
\n[\n { id: '1', label: 'one' },\n { id: '2', label: 'two' },\n { id: '3', label: 'three' },\n { id: '4', label: 'four' }\n]\n菜单:
\n- 1\n- 2\n- 3\n- 4\n模板：
\n[\n { id: '1', label: 'one' },\n { type: 'separator' },\n { id: '3', label: 'three', beforeGroupContaining: ['1'] },\n { id: '4', label: 'four', afterGroupContaining: ['2'] },\n { type: 'separator' },\n { id: '2', label: 'two' }\n]\n菜单:
\n- 3\n- 4\n- ---\n- 1\n- ---\n- 2\n模板：
\n[\n { id: '1', label: 'one', after: ['3'] },\n { id: '2', label: 'two', before: ['1'] },\n { id: '3', label: 'three' }\n]\n菜单:
\n- ---\n- 3\n- 2\n- 1\n\n\n添加菜单项到应用程序菜单和上下文菜单中
\n
进程：主进程
\n有关示例, 请参见 Menu。
new MenuItem(options)选项 对象click 函数(可选) - 单击菜单项时，将用 click(menuItem, browserWindow, event) 调用。menuItem MenuItembrowserWindow BrowserWindow |未定义 - 如果没有打开窗口，则无法定义此定义。event KeyboardEventrole String (optional) - Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu - Define the action of the menu item, when specified the click property will be ignored. 参见 rolestypeString (可选)-可以是 normal、separator、submenu、checkbox 或 radio。label String (可选)sublabel String (可选)toolTip String (可选) macOS - 此菜单的悬停文本提示accelerator Accelerator (可选)icon (NativeImage | String) (可选)enabled Boolean (可选) - 如果为 false，该菜单项将会置灰且不可点击。acceleratorWorksWhenHidden Boolean (可选) macOS - 默认为 true, 当为 false 时将阻止隐藏按钮通过快捷键触发。visibleBoolean (可选)-如果为 false, 该菜单项将完全隐藏。checkedBoolean (可选)-只应为 checkbox 或 radio 类型菜单项指定。registerAccelerator Boolean (可选) Linux Windows - 若为 false, 则快捷键将不会被注册到系统内，但还是会显示出来。 默认值为 true。sharingItem SharingItem (可选) macOS - 当 role 为 shareMenu时指定要分享的项submenu (MenuItemConstructorOptions[] | Menu) (可选) - 应该是固定类型菜单submenu 如果指定 submenu ，可以省略 type: 'submenu' 如果该值不属于Menu，它将被函数Menu.buildFromTemplate自动转换。id String (可选) - 单个菜单内唯一。 若定义，则可以通过 position 位置属性找到此选项before String - 在指定标签项前插入此项 如果引用值不存在，那么该菜单项会插在这个菜单的尾部。 这还意味着，菜单项应该被放置在与引用项相同的组中。after String - 在指定的标签之后插入菜单项。 如果引用值不存在，那么该菜单项会插在这个菜单的尾部。beforeGroupContaining String - 为单个上下文菜单提供一种方法，用于在具有指定标签的项的包含组之前声明其包含组的位置。afterGroupContaining String - 为单个上下文菜单提供一种方法，用于在具有指定标签的项的包含组之后声明其包含组的位置。注意: acceleratorWorksWhenHidden 这个选项只有 macOS 生效，因为在 Windows 和 Linux 系统下快捷键即使在隐藏情况下也会生效。 该选项让用户可以选择关闭，因为这是本地 macOS 开发中的可能。 此属性只能在macOS High Sierra 10.13或以上中使用。
可以通过角色来为menu添加预定义行为。
\n最好给任何一个菜单指定 role去匹配一个标准角色, 而不是尝试在 click 函数中手动实现该行为。 内置的 role 行为将提供最佳的原生体验。
使用 role 时, label 和 accelerator 值是可选的, 并为每个平台，将默认为适当值。
每个菜单项必须有一个 role, label, 或者一个分隔符一个 type
role 属性可以具有以下值:
undo - 撤销。about - 触发原生信息面板 (在 Window 中自定义消息盒子, 本身不提供).redocut - 剪切。copy - 复制。paste - 粘贴。pasteAndMatchStyleselectAll - 全选。delete -删除minimize - 最小化当前窗口。close - 关闭当前窗口quit - 退出程序reload - 重新加载当前窗口。forcereload - 忽略缓存，重新加载当前窗口。toggledevtools - 在当前窗口中隐藏/显示开发者工具。togglefullscreen - 将当前窗口切换至全屏模式。resetzoom - 将主页的缩放级别重置为初始大小.zoomin - 主页面放大 10%.zoomout -主页面缩小 10%.toggleSpellChecker - 启用/禁用内置拼写检查器。fileMenu - 默认的“文件”菜单（关闭/退出）editMenu-默认的 \"编辑\" 菜单 (包括撤消、复制等)viewMenu - 默认的“视图”菜单（包括重新加载、开发者工具等）windowMenu - 默认的“窗口”菜单（包括最小化、缩放等）以下其他角色可在 macOS 上找到：
\nappMenu - 整个默认\"App\" menu (About, Services, 等)hide-映射到 hide 操作.hideOthers-映射到 hideOtherApplications 操作.unhide - 映射到 unhideAllApplications 动作startSpeaking-映射到 startSpeaking 操作.stopSpeaking-映射到 stopSpeaking 操作.front - 映射到 arrangeInFront 动作zoom - 映射到 performZoom 动作toggleTabBar-映射到 toggleTabBar 操作.selectNextTab - 映射到 selectNextTab 操作.selectPreviousTab - 映射到 selectPreviousTab 操作.mergeAllWindows - 映射到 mergeAllWindows 操作.moveTabToNewWindow - 映射到 moveTabToNewWindow 操作.window - 这个子菜单是\"Window\" 菜单.help-这个子菜单是 \"Help\" 菜单.services - 子菜单是 \"Services\" 菜单。 此选项仅应用于 Application Menu 而且 不同于在 macOS app 中上下文菜单中的 \"Services\" 子菜单，因为它不是由 Electron 实现的recentDocuments-这个子菜单是 \"Open Recent\" 菜单.clearRecentDocuments -映射到 clearRecentDocuments 操作.shareMenu - share menu的子菜单。 sharingItem 属性必须被设置， 用于指向被分享的项在 macOS 上指定 role 时, label 和 accelerator 是影响菜单项的唯一选项。 所有其它选项都将被忽略。 不过，仍然支持小写的role，如toggledevtools。
注意: 对于托盘上的顶级菜单项不可用的 enabled 和 visibility 属性
以下为 MenuItem 实例的可用属性:
menuItem.idString 指定了该选项唯一的id，此属性可被动态更改。
menuItem.label一个表示菜单项标签的 String
menuItem.clickMenuItem接收到点击事件后自动触发的方法 Function 。 调用方法为 menuItem.click(event, focusedWindow, focusedWebContents).
event KeyboardEventfocusedWindow BrowserWindowfocusedWebContents WebContentsmenuItem.submenuA Menu (可选) 指定子菜单
menuItem.typeString 表示菜单项的类型 可以是 normal, separator, submenu, checkbox 或 radio.
menuItem.roleString（可选） 指出菜单项的角色 Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu
menuItem.acceleratorAn Accelerator (optional) indicating the item's accelerator, if set.
menuItem.userAccelerator Readonly macOSAn Accelerator | null indicating the item's user-assigned accelerator for the menu item.
Note: This property is only initialized after the MenuItem has been added to a Menu. Either via Menu.buildFromTemplate or via Menu.append()/insert(). Accessing before initialization will just return null.
menuItem.iconNativeImage | String (可选) 若设置， 则从对应的值中找选项图标
menuItem.sublabelString 表明选项的子标签
menuItem.toolTip macOSString 选项的悬停文本内容
menuItem.enabled一个 Boolean 类型的值, 指示是否启用该项, 该属性可以动态改变
menuItem.visible一个 Boolean 类型的值, 指示该项是否可见, 该属性可以动态改变。
menuItem.checked一个 Boolean 类型的值, 指示是否选中该项, 该属性可以动态改变。
checkbox 菜单项将在选中时切换 checked 的开关属性。
单选菜单项 将返回单击时checked属性, 并将关闭同一菜单中所有相邻项的属性。
你可以为其他行为添加click函数。
menuItem.registerAccelerator通过 Boolean表明快捷键跟随系统注册还是仅仅展示出来
此属性可以动态更改。
\nmenuItem.sharingItem macOSSharingItem 表示了当 role 是 shareMenu 时要分享的项。
此属性可以动态更改。
\nmenuItem.commandId表示项目顺序唯一 Id 的 Number
menuItem.menu多个选项组成一个 Menu
MessageChannelMain is the main-process-side equivalent of the DOM MessageChannel object. Its singular function is to create a pair of connected MessagePortMain objects.
See the Channel Messaging API documentation for more information on using channel messaging.
\n\n\n主进程中用于通道消息传递的通道接口。
\n
进程：主进程
\n示例：
\n// 主进程\nconst { MessageChannelMain } = require('electron')\nconst { port1, port2 } = new MessageChannelMain()\nw.webContents.postMessage('port', null, [port2])\nport1.postMessage({ some: 'message' })\n\n// 渲染器进程\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('port', (e) => {\n // e.ports is a list of ports sent along with this message\n e.ports[0].on('message', (messageEvent) => {\n console.log(messageEvent.data)\n })\n})\nchannel.port1A MessagePortMain property.
channel.port2A MessagePortMain property.
MessagePortMain 是 DOM MessagePort 对象的主进程等价对象。 它的行为类似于DOM版本，不同的是它使用 Node.js EventEmitter 事件系统，而不是 DOM EventTarget 系统。 这意味着你应该用 port.on('message', ...) 来监听事件, 来代替 port.onmessage = ... 或 port.addEventListener('message', ...)
关于 channel 消息的使用文档详见 Channel Messaging API
\nMessagePortMain 是一个 [EventEmitter][event-emitter].
\n\n主进程中用于通道消息传递的端口接口。
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
port.postMessage(message, [transfer])从端口发送消息，并可选地将对象的所有权转移到其他浏览上下文。
\nport.start()开始发送在端口上排队的消息。 消息将先缓存到队列, 直到此方法被调用。
\nport.close()断开端口连接
\n返回:
\nmessageEvent Objectdata anyports MessagePortMain[]MessagePortMain 对象收到消息时触发此事件
\n当MessagePortMain 对象的远程端断开连接时触发此事件
", "title": "MessagePortMain", "description": "主进程中用于通道消息传递的端口接口。" }, "/docs/tutorial/message-ports": { "locale": "zh-CN", "slug": "message-ports", "href": "/docs/tutorial/message-ports", "crowdinFileId": "256219", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/message-ports.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "MessagePorts are a web feature that allow passing messages between different contexts. It's like window.postMessage, but on different channels. The goal of this document is to describe how Electron extends the Channel Messaging model, and to give some examples of how you might use MessagePorts in your app.
Here is a very brief example of what a MessagePort is and how it works:
\n// renderer.js ///////////////////////////////////////////////////////////////\n// MessagePorts are created in pairs. A connected pair of message ports is\n// called a channel.\nconst channel = new MessageChannel()\n\n// The only difference between port1 and port2 is in how you use them. Messages\n// sent to port1 will be received by port2 and vice-versa.\nconst port1 = channel.port1\nconst port2 = channel.port2\n\n// It's OK to send a message on the channel before the other end has registered\n// a listener. Messages will be queued until a listener is registered.\nport2.postMessage({ answer: 42 })\n\n// Here we send the other end of the channel, port1, to the main process. It's\n// also possible to send MessagePorts to other frames, or to Web Workers, etc.\nipcRenderer.postMessage('port', null, [port1])\n// main.js ///////////////////////////////////////////////////////////////////\n// In the main process, we receive the port.\nipcMain.on('port', (event) => {\n // When we receive a MessagePort in the main process, it becomes a\n // MessagePortMain.\n const port = event.ports[0]\n\n // MessagePortMain uses the Node.js-style events API, rather than the\n // web-style events API. So .on('message', ...) instead of .onmessage = ...\n port.on('message', (event) => {\n // data is { answer: 42 }\n const data = event.data\n })\n\n // MessagePortMain queues messages until the .start() method has been called.\n port.start()\n})\nThe Channel Messaging API documentation is a great way to learn more about how MessagePorts work.
\nIn the renderer, the MessagePort class behaves exactly as it does on the web. The main process is not a web page, though—it has no Blink integration—and so it does not have the MessagePort or MessageChannel classes. In order to handle and interact with MessagePorts in the main process, Electron adds two new classes: MessagePortMain and MessageChannelMain. These behave similarly to the analogous classes in the renderer.
MessagePort objects can be created in either the renderer or the main process, and passed back and forth using the ipcRenderer.postMessage and WebContents.postMessage methods. Note that the usual IPC methods like send and invoke cannot be used to transfer MessagePorts, only the postMessage methods can transfer MessagePorts.
By passing MessagePorts via the main process, you can connect two pages that might not otherwise be able to communicate (e.g. due to same-origin restrictions).
close eventElectron adds one feature to MessagePort that isn't present on the web, in order to make MessagePorts more useful. That is the close event, which is emitted when the other end of the channel is closed. Ports can also be implicitly closed by being garbage-collected.
In the renderer, you can listen for the close event either by assigning to port.onclose or by calling port.addEventListener('close', ...). In the main process, you can listen for the close event by calling port.on('close', ...).
In this example, your app has a worker process implemented as a hidden window. You want the app page to be able to communicate directly with the worker process, without the performance overhead of relaying via the main process.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, ipcMain, MessageChannelMain } = require('electron')\n\napp.whenReady().then(async () => {\n // The worker process is a hidden BrowserWindow, so that it will have access\n // to a full Blink context (including e.g. <canvas>, audio, fetch(), etc.)\n const worker = new BrowserWindow({\n show: false,\n webPreferences: { nodeIntegration: true }\n })\n await worker.loadFile('worker.html')\n\n // The main window will send work to the worker process and receive results\n // over a MessagePort.\n const mainWindow = new BrowserWindow({\n webPreferences: { nodeIntegration: true }\n })\n mainWindow.loadFile('app.html')\n\n // We can't use ipcMain.handle() here, because the reply needs to transfer a\n // MessagePort.\n ipcMain.on('request-worker-channel', (event) => {\n // For security reasons, let's make sure only the frames we expect can\n // access the worker.\n if (event.senderFrame === mainWindow.webContents.mainFrame) {\n // Create a new channel ...\n const { port1, port2 } = new MessageChannelMain()\n // ... send one end to the worker ...\n worker.webContents.postMessage('new-client', null, [port1])\n // ... and the other end to the main window.\n event.senderFrame.postMessage('provide-worker-channel', null, [port2])\n // Now the main window and the worker can communicate with each other\n // without going through the main process!\n }\n })\n})\n<!-- worker.html ------------------------------------------------------------>\n<script>\nconst { ipcRenderer } = require('electron')\n\nfunction doWork(input) {\n // Something cpu-intensive.\n return input * 2\n}\n\n// We might get multiple clients, for instance if there are multiple windows,\n// or if the main window reloads.\nipcRenderer.on('new-client', (event) => {\n const [ port ] = event.ports\n port.onmessage = (event) => {\n // The event data can be any serializable object (and the event could even\n // carry other MessagePorts with it!)\n const result = doWork(event.data)\n port.postMessage(result)\n }\n})\n</script>\n<!-- app.html --------------------------------------------------------------->\n<script>\nconst { ipcRenderer } = require('electron')\n\n// We request that the main process sends us a channel we can use to\n// communicate with the worker.\nipcRenderer.send('request-worker-channel')\n\nipcRenderer.once('provide-worker-channel', (event) => {\n // Once we receive the reply, we can take the port...\n const [ port ] = event.ports\n // ... register a handler to receive results ...\n port.onmessage = (event) => {\n console.log('received result:', event.data)\n }\n // ... and start sending it work!\n port.postMessage(21)\n})\n</script>\nElectron's built-in IPC methods only support two modes: fire-and-forget (e.g. send), or request-response (e.g. invoke). Using MessageChannels, you can implement a \"response stream\", where a single request responds with a stream of data.
// renderer.js ///////////////////////////////////////////////////////////////\n\nfunction makeStreamingRequest (element, callback) {\n // MessageChannels are lightweight--it's cheap to create a new one for each\n // request.\n const { port1, port2 } = new MessageChannel()\n\n // We send one end of the port to the main process ...\n ipcRenderer.postMessage(\n 'give-me-a-stream',\n { element, count: 10 },\n [port2]\n )\n\n // ... and we hang on to the other end. The main process will send messages\n // to its end of the port, and close it when it's finished.\n port1.onmessage = (event) => {\n callback(event.data)\n }\n port1.onclose = () => {\n console.log('stream ended')\n }\n}\n\nmakeStreamingRequest(42, (data) => {\n console.log('got response data:', event.data)\n})\n// We will see \"got response data: 42\" 10 times.\n// main.js ///////////////////////////////////////////////////////////////////\n\nipcMain.on('give-me-a-stream', (event, msg) => {\n // The renderer has sent us a MessagePort that it wants us to send our\n // response over.\n const [replyPort] = event.ports\n\n // Here we send the messages synchronously, but we could just as easily store\n // the port somewhere and send messages asynchronously.\n for (let i = 0; i < msg.count; i++) {\n replyPort.postMessage(msg.element)\n }\n\n // We close the port when we're done to indicate to the other end that we\n // won't be sending any more messages. This isn't strictly necessary--if we\n // didn't explicitly close the port, it would eventually be garbage\n // collected, which would also trigger the 'close' event in the renderer.\n replyPort.close()\n})\nWhen context isolation is enabled, IPC messages from the main process to the renderer are delivered to the isolated world, rather than to the main world. Sometimes you want to deliver messages to the main world directly, without having to step through the isolated world.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, MessageChannelMain } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(async () => {\n // Create a BrowserWindow with contextIsolation enabled.\n const bw = new BrowserWindow({\n webPreferences: {\n contextIsolation: true,\n preload: path.join(__dirname, 'preload.js')\n }\n })\n bw.loadURL('index.html')\n\n // We'll be sending one end of this channel to the main world of the\n // context-isolated page.\n const { port1, port2 } = new MessageChannelMain()\n\n // It's OK to send a message on the channel before the other end has\n // registered a listener. Messages will be queued until a listener is\n // registered.\n port2.postMessage({ test: 21 })\n\n // We can also receive messages from the main world of the renderer.\n port2.on('message', (event) => {\n console.log('from renderer main world:', event.data)\n })\n port2.start()\n\n // The preload script will receive this IPC message and transfer the port\n // over to the main world.\n bw.webContents.postMessage('main-world-port', null, [port1])\n})\n// preload.js ////////////////////////////////////////////////////////////////\nconst { ipcRenderer } = require('electron')\n\n// We need to wait until the main world is ready to receive the message before\n// sending the port. We create this promise in the preload so it's guaranteed\n// to register the onload listener before the load event is fired.\nconst windowLoaded = new Promise(resolve => {\n window.onload = resolve\n})\n\nipcRenderer.on('main-world-port', async (event) => {\n await windowLoaded\n // We use regular window.postMessage to transfer the port from the isolated\n // world to the main world.\n window.postMessage('main-world-port', '*', event.ports)\n})\n<!-- index.html ------------------------------------------------------------->\n<script>\nwindow.onmessage = (event) => {\n // event.source === window means the message is coming from the preload\n // script, as opposed to from an <iframe> or other source.\n if (event.source === window && event.data === 'main-world-port') {\n const [ port ] = event.ports\n // Once we have the port, we can communicate directly with the main\n // process.\n port.onmessage = (event) => {\n console.log('from main process:', event.data)\n port.postMessage(event.data * 2)\n }\n }\n}\n</script>\nmimeType String (optional) - MIME type of the buffer.charset String (optional) - Charset of the buffer.data Buffer - The actual Buffer content.InputEventtype String - The type of the event, can be mouseDown, mouseUp, mouseEnter, mouseLeave, contextMenu, mouseWheel or mouseMove.x Integery Integerbutton String (optional) - The button pressed, can be left, middle, right.globalX Integer (optional)globalY Integer (optional)movementX Integer (optional)movementY Integer (optional)clickCount Integer (optional)MouseInputEventtype String - The type of the event, can be mouseWheel.deltaX Integer (optional)deltaY Integer (optional)wheelTicksX Integer (optional)wheelTicksY Integer (optional)accelerationRatioX Integer (optional)accelerationRatioY Integer (optional)hasPreciseScrollingDeltas Boolean (optional)canScroll Boolean (optional)通过Web Workers，可以实现用操作系统级别的线程来跑JavaScript
\n可以在Electron的Web Workers里使用Node.js的特性。要用的话，需把webPreferences中的nodeIntegrationInWorker选项设置为true
const win = new BrowserWindow({\n webPreferences: {\n nodeIntegrationInWorker: true\n }\n})\nnodeIntegrationInWorker 可以独立于nodeIntegration使用，但sandbox必须不能设置为true
Web Workers支持Node.js的所有内置模块，而且asar档案也仍通过Node.js的API来读取。 不过所有的Electron内置模块不可以用在多线程环境中。
在Web Workers里可以直接加载任何原生Node.js模块，但不推荐这样做。 大多数现存的原生模块是在假设单线程环境的情况下编写的，如果把它们用在Web Workers里会导致崩溃和内存损坏。
\n请注意, 即使原生Node.js模块如果考虑到了线程安全问题， 但在 Web Worker中加载它仍然不安全, 因为 process.dlopen 函数并没有考虑线程安全。
现在安全顺利地加载原生模块的唯一办法，就是确保在Web Workers启动后app不加载原生模块。
\nprocess.dlopen = () => {\n throw new Error('Load native module is not safe')\n}\nconst worker = new Worker('script.js')\n作为桌面程序，当然希望能够实现操作系统的 drag & drop 功能。 很多网站已经支持拖拽文件， Electron 当然也支持
\n要在您的应用中实现此功能，您需要调用 webContent.startDrag(item) API 响应 ondragstart 事件。
一个演示如何动态创建要从窗口中拖出的文件的示例。
\n在 preload.js 中使用 contextBridge 注入方法 window.electron.startDrag(...) 将向主进程发送IPC消息。
const { contextBridge, ipcRenderer } = require('electron')\nconst path = require('path')\n\ncontextBridge.exposeInMainWorld('electron', {\n startDrag: (fileName) => {\n ipcRenderer.send('ondragstart', path.join(process.cwd(), fileName))\n }\n})\n添加一个可拖动元素到 index.html, 并引用你的渲染器脚本：
<div style=\"border:2px solid black;border-radius:3px;padding:5px;display:inline-block\" draggable=\"true\" id=\"drag\">拖动我</div>\n<script src=\"renderer.js\"></script>\n在 renderer.js 通过调用通过上述 contextBridge 添加的方法来设置渲染器进程处理拖动事件。
document.getElementById('drag').ondragstart = (event) => {\n event.preventDefault()\n window.electron.startDrag('drag-and-drop.md')\n}\n在主进程中(main.js 文件)，将收到的事件带上文件路径和图标扩展到正在拖动的文件：
const { ipcMain } = require('electron')\n\nipcMain.on('ondragstart', (event, filePath) => {\n event.sender.startDrag({\n file: filePath,\n icon: '/path/to/icon.png'\n })\n})\n启动 Electron 应用程序后，尝试将该项从 BrowserWindow 拖放到桌面上。 在本指南中，本项是位于项目根目录下的 Markdown 文件：
\n
\n\n\n使用 PNG 或 JPG 文件创建托盘、dock和应用程序图标。
\n
在 Electron 内, 那些需要图片的 API 可以传递两种参数, 一种是文件路径, 一种是 NativeImage 实例对象。 空的图片对象将被 null 参数替代
例如, 创建托盘或设置窗口图标时, 你可以传递 String 格式的图片路径
const { BrowserWindow, Tray } = require('electron')\n\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconst win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })\nconsole.log(appIcon, win)\n或者从粘贴板读取图片，将返回 NativeImage 对象：
const { clipboard, Tray } = require('electron')\nconst image = clipboard.readImage()\nconst appIcon = new Tray(image)\nconsole.log(appIcon)\n当前只支持 PNG 和 JPEG 格式， 推荐使用 PNG ，因为这种格式支持透明和无损压缩
在 Windows 平台下, 你同样可以从文件路径中加载ICO 格式的 icons 对象。 为了达到最佳观看效果，推荐至少包含以下大小的图片尺寸：
在这篇文章中查看 尺寸说明 的章节
\n在具有高 DPI 支持的平台 (如 Apple 视网膜显示器) 上, 可以在图像的基本文件名之后追加 @ 2x 以将其标记为高分辨率图像。
比如， 如果 icon.png 是一个普通的标准分辨率的图片，而 icon@2x.png 将被视为具有两倍DPI密度的高分辨率图像
如果您想同时支持不同的DPI密度显示，您可以将不同大小的图像放置在同一文件夹中，并使用文件名而不需要DPI 后缀。 例如：
\nimages/\n├── icon.png\n├── icon@2x.png\n└── icon@3x.png\nconst { Tray } = require('electron')\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconsole.log(appIcon)\n还支持以下DPI的后缀：
\n@1x@1.25x@1.33x@1.4x@1.5x@1.8x@2x@2.5x@3x@4x@5x模板图像由黑色和透明通道组成。 模板图片不是单独使用的, 它通常与其他内容混合以创建期望的最终效果
\n最常见的情况是使用模板图像作为菜单栏图标，因此它可以适应浅色和深色菜单栏。
\n注意: 仅在 macOS 上支持Template image。
\n要将图像标记为模板图像，其文件名应以 Template 一词结尾。 例如：
xxxTemplate.pngxxxTemplate@2x.pngnativeImage 模块具有以下方法, 它们都返回 nativeImage 类的实例:
nativeImage.createEmpty()返回 NativeImage
创建一个空的 NativeImage 实例。
nativeImage.createThumbnailFromPath(path, maxSize) macOS Windowspath String - 打算用来构建缩略图的文件路径maxSize Size - 返回缩略图的最大宽度和高度(正数)。 在 Windows 平台下将忽略 maxSize.height 并根据 maxSize.width 缩放高度返回 Promise<NativeImage> - 文件的缩略图预览图像，包含类型是 NativeImage
nativeImage.createFromPath(path)path String返回 NativeImage
从位于 path 的文件创建新的 NativeImage 实例。 如果 path 不存在，，无法读取或不是有效图像，方法将返回空图像, 。
const nativeImage = require('electron').nativeImage\n\nconst image = nativeImage.createFromPath('/Users/somebody/images/icon.png')\nconsole.log(image)\nnativeImage.createFromBitmap(buffer, options)buffer Buffer选项 对象width Integerheight IntegerscaleFactor Double (可选) - 默认1.0返回 NativeImage
从 buffer 中创建一个新的 NativeImage 实例，其中包含由 toBitmap()返回的原始位图 像素数据。 具体格式取决于平台。
nativeImage.createFromBuffer(buffer[, options])buffer Bufferoptions Object (可选)width Integer (可选) - 位图缓冲器所必需height Integer (可选) - 位图缓冲器所必需scaleFactor Double (可选) - 默认1.0返回 NativeImage
从 buffer 创建新的 NativeImage 实例。 尝试先解码为 PNG 或 JPEG
nativeImage.createFromDataURL(dataURL)dataURL String返回 NativeImage
从 dataURL 创建新的 NativeImage 实例。
nativeImage.createFromNamedImage(imageName[, hslShift]) macOS返回 NativeImage
从映射到给定图像名称的 NSImage 创建一个 NativeImage 实例。 可用值列表详见 System Icons
使用以下规则将hslShift应用于图像:
hsl_shift[0] (色调): 图像的绝对色调值，0 和1 映射到 0和360，在色环上 (红色)。hsl_shift[1] (饱和度): 图像的饱和度调值， 以下关键值： 0 = 删除所有颜色。 0.5 = 保持不变。 1 = 图像完全饱和hsl_shift[2] (亮度): 图像的亮度调值, 可以为下列值: 0 = 移除所有亮度 (所有像素点设置为黑色). 0.5 = 保持不变。 1 = 全亮 (所有像素点设置为白色)。这意味着 [-1, 0, 1] 将使图像完全变白，[-1, 1, 0]将使图像完全变黑.
在某些情况下， NSImageName 与其字符串表示并不匹配：其中一个例子是 NSFolderImageName，它的字符串表示实际上将是 NSFolder。 因此，您需要在传递图像之前确定正确的字符串表示方式。 可以像下面这样做：
echo -e '#import <Cocoa/Cocoa.h>\\nint main() { NSLog(@\"%@\", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test
其中 SYSTEM_IMAGE_NAME 应替换为 this list里面的值
\n\n本机图像，如托盘、dock栏和应用图标。
\n
Process: Main, Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
以下方法可用于 NativeImage 类的实例:
image.toPNG([options])options Object (可选)scaleFactor Double (可选) - 默认1.0返回 Buffer-一个包含图像 PNG 编码数据的 Buffer 。
image.toJPEG(quality)quality Integer - 在 0 - 100 之间返回 Buffer-一个包含图像 JPEG 编码数据的 Buffer 。
image.toBitmap([options])options Object (可选)scaleFactor Double (可选) - 默认1.0返回 Buffer-一个包含图像的原始位图像素数据副本的 Buffer 。
image.toDataURL([options])options Object (可选)scaleFactor Double (可选) - 默认1.0返回 String-图像的数据 URL。
image.getBitmap([options])options Object (可选)scaleFactor Double (可选) - 默认1.0返回 Buffer-一个包含图像原始位图像素数据的 Buffer 。
getBitmap() 和 toBitmap() 的不同之处在于，<code>getBitmap() 不会拷贝位图数据，所以你必须在返回 Buffer 后立刻使用它，否则数据可能会被更改或销毁
image.getNativeHandle() macOS返回 Buffer-一个 Buffer , 它将 C 指针存储在图像的基础本机句柄上。 在 macOS 上, 将返回指向 NSImage 实例的指针。
请注意, 返回的指针是指向基础本机映像而不是副本的弱指针, 因此 必须 确保关联的 nativeImage 实例保留在周围。
image.isEmpty()返回 Boolean-图像是否为空。
image.getSize([scaleFactor])scaleFactor Double (可选) - 默认1.0Returns Size.
如果传递了 scaleFactor ，将返回与图像表示最接近的传递值对应的大小。
image.setTemplateImage(option)option Boolean将图像标记为模板图像。
\nimage.isTemplateImage()返回 Boolean-图像是否为模板图像。
image.crop(rect)rect Rectangle -要裁剪的图像区域.返回 NativeImage-裁剪的图像。
image.resize(options)选项 对象width Integer (可选) - 默认值为图片宽度height Integer (可选) - 默认值为图片高度.quality String (optional) 所要设置的图片质量。 可能的值为 good、better 或 best。 默认值为best. 这些值表示期望的 质量/速度 的权衡。 他们被转换为某个特定算法, 取决于基础平台的能力 (CPU, GPU)。 这三种方法都可以在指定的平台上映射到相同的算法。返回 NativeImage-裁剪的图像。
如果只指定height或width，那么当前的长宽比将保留在缩放图像中。
image.getAspectRatio([scaleFactor])scaleFactor Double (可选) - 默认1.0返回 Float - 图像的长宽比.
如果传递了 scaleFactor ，将返回与图像表示最接近的传递值对应的大小。
image.getScaleFactors()Returns Float[] - 给定 nativeImage 的表示相对应的所有比例因子的数组
image.addRepresentation(options)选项 对象scaleFactor Double - 要添加图像的缩放系数width Integer (可选) - 默认值为 0. 如果将位图缓冲区指定为buffer, 则为必填项height Integer (可选) - 默认值为 0. 如果将位图缓冲区指定为buffer, 则为必填项buffer Buffer (可选) - 包含原始图像数据的缓冲区.dataURL String (可选) - data URL 可以为 base 64 编码的 PNG 或 JPEG 图像.为特定比例因子添加图像表示。 这可以用于在图像中明确添加不同的比例因子表示。 这种可以调用在空图像上。
\nnativeImage.isMacTemplateImage macOSBoolean 属性，用于决定图像是否被认为是一个 template image.
请注意，此属性仅对 macOS 有影响。
", "title": "nativeImage", "description": "使用 PNG 或 JPG 文件创建托盘、dock和应用程序图标。" }, "/docs/api/native-theme": { "locale": "zh-CN", "slug": "native-theme", "href": "/docs/api/native-theme", "crowdinFileId": "256343", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/native-theme.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n读取并响应Chromium本地色彩主题中的变化。
\n
进程：主进程
\nnativeTheme模块包括以下事件：
当以下NativeTheme属性发生变化时会触发此事件： shouldUseDarkColors, shouldUseHighContrastColors或shouldUseInvertedColorScheme 。 你需要自己检查到底是哪个属性发生了变化。
nativeTheme 模块具备以下属性：
nativeTheme.shouldUseDarkColors 只读此属性的值为一个 Boolean 类型的值，代表着当前OS / Chromium是否正处于dark模式。或者应用程序是否正被建议使用dark模式的皮肤 如果你希望修改此属性的值，你应该使用下面的 themeSource属性
nativeTheme.themeSource一个类型为String的属性，此属性可能的值为：system, light or dark. It is used to override and supersede the value that Chromium has chosen to use internally.
Setting this property to system will remove the override and everything will be reset to the OS default. By default themeSource is system.
Settings this property to dark will have the following effects:
nativeTheme.shouldUseDarkColors will be true when accessedprefers-color-scheme CSS query will match dark mode.updated event will be emittedSettings this property to light will have the following effects:
nativeTheme.shouldUseDarkColors will be false when accessedprefers-color-scheme CSS query will match light mode.updated event will be emittedThe usage of this property should align with a classic \"dark mode\" state machine in your application where the user has three options.
\nFollow OS --> themeSource = 'system'Dark Mode --> themeSource = 'dark'Light Mode --> themeSource = 'light'Your application should then always use shouldUseDarkColors to determine what CSS to apply.
nativeTheme.shouldUseHighContrastColors macOS Windows ReadonlyA Boolean for if the OS / Chromium currently has high-contrast mode enabled or is being instructed to show a high-contrast UI.
nativeTheme.shouldUseInvertedColorScheme macOS Windows ReadonlyA Boolean for if the OS / Chromium currently has an inverted color scheme or is being instructed to use an inverted color scheme.
\n\n使用Chromium的原生网络库发出HTTP / HTTPS请求
\n
进程：主进程
\nnet 模块是一个发送 HTTP(S) 请求的客户端API。 它类似于Node.js的HTTP 和 HTTPS 模块 ，但它使用的是Chromium原生网络库来替代Node.js的实现，提供更好的网络代理支持。 它还支持检查网络状态。
下面是一个非详尽的列表, 用于说明为什么使用 net 模块而不是原生Node. js 模块:
The API components (including classes, methods, properties and event names) are similar to those used in Node.js.
\nExample usage:
\nconst { app } = require('electron')\napp.whenReady().then(() => {\n const { net } = require('electron')\n const request = net.request('https://github.com')\n request.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`)\n console.log(`HEADERS: ${JSON.stringify(response.headers)}`)\n response.on('data', (chunk) => {\n console.log(`BODY: ${chunk}`)\n })\n response.on('end', () => {\n console.log('No more data in response.')\n })\n })\n request.end()\n})\nThe net API can be used only after the application emits the ready event. Trying to use the module before the ready event will throw an error.
net 模块具有以下方法:
net.request(options)options (ClientRequestConstructorOptions | String) - The ClientRequest constructor options.使用 options 创建 ClientRequest 实例, 这些选项直接转发到 ClientRequest 的构造函数。 net.request 方法将根据 options 对象中的指定协议方案, 去发送安全和不安全的 HTTP 请求（ both secure and insecure HTTP requests）。
net.isOnline()Returns Boolean - Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
net.online 只读A Boolean property. Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
\n\nLogging network events for a session.
\n
进程：主进程
\nconst { netLog } = require('electron')\n\napp.whenReady().then(async () => {\n await netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\n查看 --log-net-log 记录应用生命周期的网络事件。
注意: 除了指定的方法, 其他方法只能在 app 模块的 ready 事件被触发后使用。
netLog.startLogging(path[, options])path String - 记录网络日志的文件路径。options Object (可选)captureMode String (optional) - What kinds of data should be captured. By default, only metadata about requests will be captured. Setting this to includeSensitive will include cookies and authentication data. Setting it to everything will include all bytes transferred on sockets. Can be default, includeSensitive or everything.maxFileSize Number (optional) - When the log grows beyond this size, logging will automatically stop. Defaults to unlimited.Returns Promise<void> - resolves when the net log has begun recording.
开始记录网络事件日志到 path。
netLog.stopLogging()Returns Promise<void> - resolves when the net log has been flushed to disk.
停止网络事件日志的记录。 如果未被调用，net 记录将自动结束当 app 退出的时候。
\nnetLog.currentlyLogging 只读A Boolean property that indicates whether network logs are currently being recorded.
EventnewGuest BrowserWindow (optional)\n\n创建OS(操作系统)桌面通知
\n
进程：主进程
\n如果要显示来自渲染进程的通知, 你应该使用 HTML5 Notification API
\n\n\n创建OS(操作系统)桌面通知
\n
进程：主进程
\nNotification是一个EventEmitter.
通过 options 来设置的一个新的原生 Notification。
Notification 类有以下静态方法：
Notification.isSupported()Returns Boolean-当前系统是否支持桌面通知
new Notification([options])options Object (可选)title String (optional) - A title for the notification, which will be shown at the top of the notification window when it is shown.subtitleString (可选) 通知的副标题, 显示在标题下面。 macOS body String (optional) - The body text of the notification, which will be displayed below the title or subtitle.silentBoolean (可选) 在显示通知时是否发出系统提示音。 icon(String | NativeImage ) (可选) 用于在该通知上显示的图标。hasReplyBoolean (可选) 是否在通知中添加一个答复选项。 macOS timeoutType String (optional) Linux Windows - The timeout duration of the notification. Can be 'default' or 'never'.replyPlaceholderString (可选) 答复输入框中的占位符。 macOS sound String (可选) 显示通知时播放的声音文件的名称。 macOS urgency String (optional) Linux - The urgency level of the notification. Can be 'normal', 'critical', or 'low'.actions NotificationAction[] (可选) macOS - 要添加到通知中的操作 请阅读 NotificationAction文档来了解可用的操作和限制。closeButtonText String (optional) macOS - A custom title for the close button of an alert. An empty string will cause the default localized text to be used.toastXml String (optional) Windows - A custom description of the Notification on Windows superseding all properties above. Provides full customization of design and behavior of the notification.用 new Notification 创建的对象触发以下事件：
注意: 某些事件仅在特定的操作系统上可用, 这些方法会被标记出来。
\n返回:
\nevent Event当通知向用户显示时触发, 请注意, 这可能会多次触发, 因为「通知」可以通过 show() 方法多次显示。
返回:
\nevent Event在用户单击通知时触发。
\n返回:
\nevent Event当用户手动关闭通知时触发
\n当通知关闭后，这个事件不能保证在所有情况下都会触发。
\n返回:
\nevent EventreplyString-用户在内联答复字段中输入的字符串.当用户单击 hasReply: true 的通知上的 \"Reply\" 按钮时触发。
返回:
\nevent Eventindex Number - 已激活的操作的索引.返回:
\nevent Eventerror String - The error encountered during execution of the show() method.Emitted when an error is encountered while creating and showing the native notification.
\n用new Notification 创建的对象有以下实例方法：
notification.show()即时向用户展示 notification ，请注意这意味着与HTML5的 Notification 的实现不同，实例化一个new Notification 不会立刻向用户展示， 你需要在系统将要显示它之前调用这个方法
如果以前已显示通知, 则此方法将忽略以前显示的通知，并创建具有相同属性的新通知
\nnotification.close()忽略这条通知
\nnotification.titleA String property representing the title of the notification.
notification.subtitleA String property representing the subtitle of the notification.
notification.bodyA String property representing the body of the notification.
notification.replyPlaceholderA String property representing the reply placeholder of the notification.
notification.soundA String property representing the sound of the notification.
notification.closeButtonTextA String property representing the close button text of the notification.
notification.silentA Boolean property representing whether the notification is silent.
notification.hasReplyA Boolean property representing whether the notification has a reply action.
notification.urgency LinuxA String property representing the urgency level of the notification. Can be 'normal', 'critical', or 'low'.
Default is 'low' - see NotifyUrgency for more information.
\nnotification.timeoutType Linux WindowsA String property representing the type of timeout duration for the notification. Can be 'default' or 'never'.
If timeoutType is set to 'never', the notification never expires. It stays open until closed by the calling API or the user.
notification.actionsA NotificationAction[] property representing the actions of the notification.
notification.toastXml WindowsA String property representing the custom Toast XML of the notification.
在 macOS 上, 您可以指定在显示通知时要播放的声音的名称。 Any of the default sounds (under System Preferences > Sound) can be used, in addition to custom sound files. 请确保声音文件是在应用程序包(例如, YourApp.app/Contents/Resources) 内存在副本, 或者是下列位置之一:
~/Library/Sounds/Library/Sounds/Network/Library/Sounds/System/Library/Sounds有关详细信息, 请参见 NSSound 文档。
type String - The type of action, can be button.text String (optional) - The label for the given action.| Action Type | Platform Support | Usage of text | Default text | Limitations |
|---|---|---|---|---|
button | macOS | Used as the label for the button | \"Show\" (or a localized string by system default if first of such button, otherwise empty) | Only the first one is used. If multiple are provided, those beyond the first will be listed as additional actions (displayed when mouse active over the action button). Any such action also is incompatible with hasReply and will be ignored if hasReply is true. |
In order for extra notification buttons to work on macOS your app must meet the following criteria.
\nNSUserNotificationAlertStyle set to alert in the Info.plist.If either of these requirements are not met the button won't appear.
", "title": "NotificationAction Object", "description": "" }, "/docs/api/structures/notification-response": { "locale": "zh-CN", "slug": "notification-response", "href": "/docs/api/structures/notification-response", "crowdinFileId": "256473", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/notification-response.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "actionIdentifier String - The identifier string of the action that the user selected.date Number - The delivery date of the notification.identifier String - The unique identifier for this notification request.userInfo Record<String, any> - A dictionary of custom information associated with the notification.userText String (optional) - The text entered or chosen by the user.这三个操作系统都为应用程序向用户发送通知提供了手段。 在主进程和渲染进程中，显示通知的技术不同的。
\n对于渲染进程，Electron 方便地允许开发者使用 HTML5 通知 API 发送通知，然后使用当前运行中的系统的原生通知 API 来进行显示。
\n要在主进程中显示通知，您需要使用 Notification 模块。
\n从 Quick Start Guide 示例的应用程序开始，将以下行添加到 index.html 文件：
<script src=\"renderer.js\"></script>\n并添加 renderer.js 文件：
const NOTIFICATION_TITLE = 'Title'\nconst NOTIFICATION_BODY = 'Notification from the Renderer process. Click to log to console.'\nconst CLICK_MESSAGE = 'Notification clicked'\n\nnew Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY }).onclick = () => console.log(CLICK_MESSAGE)\n启动 Electron 应用程序后，您应该能看到通知：
\n
此外，如果您点击通知，DOM将更新以显示“Notification clicked!”
\n从 Quick Start Guide 中的应用开始，将以下内容更新到 main.js。
const { Notification } = require('electron')\n\nconst NOTIFICATION_TITLE = 'Basic Notification'\nconst NOTIFICATION_BODY = 'Notification from the Main process'\n\nfunction showNotification () {\n new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()\n}\n\napp.whenReady().then(createWindow).then(showNotification)\n启动 Electron 应用程序后，您应该能看到系统通知：
\n
虽然操作系统的代码和用户体验相似，但依然存在微妙的差异。
\nnode_modules\\electron\\dist\\electron.exe to your Start Menu also does the trick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'. 然后您需要添加 app.setAppUserModelId(process.execPath) 到主进程才能看到通知。Electron尝试将应用程序用户模型 ID 的相关工作自动化。 Electron在和安装和更新框架 Squirrel 协同使用的时候，快捷方式将被自动正确的配置好。 更棒的是，Electron 会自动检测 Squirrel 的存在，并且使用正确的值来自动调用app.setAppUserModelId()。 在开发的过程中, 你可能需要自己调用app.setAppUserModelld()
此外，在Windows 8中，通知正文的最大长度为250个字符，Windows团队建议将通知保留为200个字符。 然而，Windows 10中已经删除了这个限制，但是Windows团队要求开发人员合理使用。 尝试将大量文本发送到API(数千个字符) 可能会导致不稳定。
\nWindows 的更高版本允许高级通知，自定义模板，图像和其他灵活元素。 要发送这些通知(来自主进程或渲染器进程)，请使用用户区模块 electron-windows-notifications 来用原生节点附件发送 ToastNotification 和 TileNotification 对象。
当包括按钮在内的通知使用 electron-windows-notifications 时，处理回复需要使用 electron-windows-interactive-notifications 帮助注册所需的 COM 组件并调用您的 Electron 应用程序和输入的用户数据。
如果要检测是否允许发送通知，请使用 electron-notification-state 模块。
\n这样，您可以提前确定 Windows 是否会将通知忽略。
\nMacOS上的通知是最直接的，但你应该注意苹果关于通知的人机接口指南（Apple's Human Interface guidelines regarding notifications）.
\n请注意，通知的大小限制为256个字节，如果超过该限制，则会被截断。
\n要检测是否允许发送通知，请使用用户区模块 electron-notification-state。
\n这样可以提前检测是否显示通知。
\n通知是通过libnotify发送的，libnotify可以在任何实现了桌面通知规范（Desktop Notifications Specification）的桌面环境中发送通知，包括Cinnamon、Enlightenment、Unity、GNOME、KDE
离屏渲染允许你以位图的方式来获取 BrowserWindow 中的内容，所以它可以在任何地方被渲染，例如在3D场景中的纹理。 Electron中的离屏渲染使用与 Chromium Embedded Framework 项目类似的方法。
注意：
\n绘图 事件才能提高效率。GPU加速渲染意味着使用GPU用于合成。 这也就意味着帧必须从GPU拷贝过来，从而需求更多的资源，因此这会比软件输出设备更慢。 这种模式的优点是支持WebGL和3D CSS动画.
\n此模式使用软件输出设备在 CPU 中渲染，因此帧 生成的速度要快得多。 因此，此模式优先于 GPU 加速模式。
\n要启用此模式，必须通过调用 app.disableHardwareAcceleration() API 来禁用GPU加速。
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\n\napp.disableHardwareAcceleration()\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ webPreferences: { offscreen: true } })\n\n win.loadURL('https://github.com')\n win.webContents.on('paint', (event, dirty, image) => {\n fs.writeFileSync('ex.png', image.toPNG())\n })\n win.webContents.setFrameRate(60)\n})\n在运行Electron应用后，进入你的应用的工作目录，你会在里面找到渲染的图片。
", "title": "离屏渲染", "description": "" }, "/docs/tutorial/online-offline-events": { "locale": "zh-CN", "slug": "online-offline-events", "href": "/docs/tutorial/online-offline-events", "crowdinFileId": "256229", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/online-offline-events.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "在渲染进程中，在线/离线事件 的探测，是通过标准 HTML5 API 中 navigator.onLine 属性来实现的。
navigator.onLine 属性返回值：
false：如果所有网络请求都失败(例如，断开网络)。true: 在其他情况下都返回 true由于许多情况都会返回 true，你应该小心对待误报的情况， 因为我们不能总是假设 true 值意味着 Electron 可以访问互联网。 例如，当计算机运行的虚拟化软件时，虚拟以太网适配器处于 \"always connected\" 状态。 因此，如果您想要确定 Electron 的互联网访问状态，您应该为此检查进行额外的开发。
从HTML文件 index.html 开始，这个例子会演示 navigator.onLine API 是如何被用来构建一个连接状态指示器的。
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n</head>\n<body>\n <h1>Connection status: <strong id='status'></strong></h1>\n <script src=\"renderer.js\"></script>\n</body>\n</html>\n为了操作DOM，创建一个 renderer.js 文件，添加事件监听器到 'online' 和 'offline' 窗口 中. 事件处理器设置基于 navigator.onLine 的结果到 <strong id='status'> element 的内容中。
function updateOnlineStatus () {\n document.getElementById('status').innerHTML = navigator.onLine ? 'online' : 'offline'\n}\n\nwindow.addEventListener('online', updateOnlineStatus)\nwindow.addEventListener('offline', updateOnlineStatus)\n\nupdateOnlineStatus()\n最后，创建一个 main.js 文件用来给主进程创建窗口。
const { app, BrowserWindow } = require('electron')\n\nfunction createWindow () {\n const onlineStatusWindow = new BrowserWindow({\n width: 400,\n height: 100\n })\n\n onlineStatusWindow.loadFile('index.html')\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n启动 Electron 应用程序后，您应该能看到通知：
\n
\n", "title": "在线/离线事件探测", "description": "注意：如果你需要将连接状态发送给主流程，请使用 IPC 渲染器 API。" }, "/docs/development/patches": { "locale": "zh-CN", "slug": "patches", "href": "/docs/development/patches", "crowdinFileId": "256161", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/patches.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "注意：如果你需要将连接状态发送给主流程，请使用 IPC 渲染器 API。
\n
Electron是基于两个主要的上游项目：Chromium和Node.js Each of these projects has several of their own dependencies, too. We try our best to use these dependencies exactly as they are but sometimes we can't achieve our goals without patching those upstream dependencies to fit our use cases.
\nEvery patch in Electron is a maintenance burden. When upstream code changes, patches can break—sometimes without even a patch conflict or a compilation error. It's an ongoing effort to keep our patch set up-to-date and effective. So we strive to keep our patch count at a minimum. To that end, every patch must describe its reason for existence in its commit message. That reason must be one of the following:
\nProfile). Include reasoning about why the change cannot be implemented without a patch (e.g. by subclassing or copying the code).In general, all the upstream projects we work with are friendly folks and are often happy to accept refactorings that allow the code in question to be compatible with both Electron and the upstream project. (See e.g. this change in Chromium, which allowed us to remove a patch that did the same thing, or this change in Node, which was a no-op for Node but fixed a bug in Electron.) We should aim to upstream changes whenever we can, and avoid indefinite-lifetime patches.
\nIf you find yourself in the unfortunate position of having to make a change which can only be made through patching an upstream project, you'll need to know how to manage patches in Electron.
\nAll patches to upstream projects in Electron are contained in the patches/ directory. Each subdirectory of patches/ contains several patch files, along with a .patches file which lists the order in which the patches should be applied. Think of these files as making up a series of git commits that are applied on top of the upstream project after we check it out.
patches\n├── config.json <-- this describes which patchset directory is applied to what project\n├── chromium\n│ ├── .patches\n│ ├── accelerator.patch\n│ ├── add_contentgpuclient_precreatemessageloop_callback.patch\n│ ⋮\n├── node\n│ ├── .patches\n│ ├── add_openssl_is_boringssl_guard_to_oaep_hash_check.patch\n│ ├── build_add_gn_build_files.patch\n│ ⋮\n⋮\nTo help manage these patch sets, we provide two tools: git-import-patches and git-export-patches. git-import-patches imports a set of patch files into a git repository by applying each patch in the correct order and creating a commit for each one. git-export-patches does the reverse; it exports a series of git commits in a repository into a set of files in a directory and an accompanying .patches file.
\n\nSide note: the reason we use a
\n.patchesfile to maintain the order of applied patches, rather than prepending a number like001-to each file, is because it reduces conflicts related to patch ordering. It prevents the situation where two PRs both add a patch at the end of the series with the same numbering and end up both getting merged resulting in a duplicate identifier, and it also reduces churn when a patch is added or deleted in the middle of the series.
$ cd src/third_party/electron_node\n$ vim some/code/file.cc\n$ git commit\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\n\n\nNOTE:
\ngit-export-patchesignores any uncommitted files, so you must create a commit if you want your changes to be exported. The subject line of the commit message will be used to derive the patch file name, and the body of the commit message should include the reason for the patch's existence.
Re-exporting patches will sometimes cause shasums in unrelated patches to change. This is generally harmless and can be ignored (but go ahead and add those changes to your PR, it'll stop them from showing up for other people).
\n$ cd src/v8\n$ vim some/code/file.cc\n$ git log\n# Find the commit sha of the patch you want to edit.\n$ git commit --fixup [COMMIT_SHA]\n$ git rebase --autosquash -i [COMMIT_SHA]^\n$ ../electron/script/git-export-patches -o ../electron/patches/v8\n$ vim src/electron/patches/node/.patches\n# Delete the line with the name of the patch you want to remove\n$ cd src/third_party/electron_node\n$ git reset --hard refs/patches/upstream-head\n$ ../../electron/script/git-import-patches ../../electron/patches/node\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\nNote that git-import-patches will mark the commit that was HEAD when it was run as refs/patches/upstream-head. This lets you keep track of which commits are from Electron patches (those that come after refs/patches/upstream-head) and which commits are in upstream (those before refs/patches/upstream-head).
When updating an upstream dependency, patches may fail to apply cleanly. Often, the conflict can be resolved automatically by git with a 3-way merge. You can instruct git-import-patches to use the 3-way merge algorithm by passing the -3 argument:
$ cd src/third_party/electron_node\n# If the patch application failed midway through, you can reset it with:\n$ git am --abort\n# And then retry with 3-way merge:\n$ ../../electron/script/git-import-patches -3 ../../electron/patches/node\nIf git-import-patches -3 encounters a merge conflict that it can't resolve automatically, it will pause and allow you to resolve the conflict manually. Once you have resolved the conflict, git add the resolved files and continue to apply the rest of the patches by running git am --continue.
开发者经常询问优化 Electron 应用程序性能的策略。 软件工程师、用户和框架开发者并不总是就“性能”的含义达成单一定义。 此文档概述了Electron 维护者最喜欢的减少内存使用、 CPU 负载以及磁盘资源使用的方式。以确保您的应用程序能够响应用户输入并尽快完成操作。 此外，我们希望所有的性能策略都能保持您应用的高标准安全。
\n关于如何使用 JavaScript构建高性能网站的技巧和方法通常也适用于Electron 应用程序。 在某种程度上，讨论如何构建高性能 Node.js 应用的方法同样也适用。但是小心理解“性能”一词的含义对于 Node.js 后端和客户端程序并不相同。
\n文中的列表提供了一些方便，同时也需要注意，它和我们的安全性检查列表类似，并不详尽。 即使你参照了下面提到的所有步骤，依然有可能构建出来一个性能低的Electron应用。 Electron是一个强大的开发平台，可以让开发人员按照自己所想，做更多的或更少的事情。 而这种自由的代价就是开发者需要承担大部分性能上的责任。
\n以下列举了一些直截了当、易于实现的方式。 但是，如果你想构建性能最优秀的应用，仅仅这些是不够的。 你需要仔细检查应用中运行的所有代码，认真地进行分析和衡量。 瓶颈在哪里？ 当用户点击按钮时，哪些操作的执行占用了最多的时间？ 当应用程序被挂起时，哪些对象占用了最多的内存？
\n通过多次的尝试，我们发现，构建高性能的Electron应用程序，最成功的策略是分析正在运行的代码，查找其中最耗资源的部分，然后对其进行优化。 一遍又一遍地重复这个“搬砖”的过程，将极大地提高应用程序的性能。 在大型应用程序（例如Visual Studio Code、Slack）中的实践经验证明了这是目前最可靠的性能提升策略。
\n要了解更多关于如何分析应用程序代码的信息，请熟悉Chrome开发者工具。 若要高级分析查看多个进程，请使用 Chrome Tracing 工具。
\n如果你尝试这些步骤，你的应用可能会略微简洁、快速，而且一般来说会更少出现资源不足的情况。
\n在向你的应用程序添加一个 Node.js 模块之前，请检查这个模块。 这个模块包含了多少依赖？ 简单的一个a require()声明中包含了什么种类的资源？ 你可能发现NPM包注册的最多的或者Github上Star最多的模块实际上并不是最简单或者最小可用的模块。
这一建议背后的理由最好用一个真实的例子来说明。 在Electron最开始的那些日子，可靠的检查网络连接是一个问题，导致很多应用公开的使用了一个简单的isOnline()方法。
该模块通过尝试访问多个众所周知的端点，检测到您的网络连接。 至于这些资源的列表，它取决于一个完全不同的模块，这个模块也包含一个众所周知的端口。 这个依赖本身又依赖一个包含超过 100 000行端口信息的JSON文件的模块。 每当模块加载时(通常用 require('module'))，它会加载所有依赖关系并最终读取并解析此 JSON 文件。 解析几千行的JSON是一个非常繁重的操作。 在性能差的机器上，它会占用整整几秒的时间。
在许多服务器环境中，启动时间几乎无关紧要。 一个Node.js 服务器要求所有端口的信息可能实际上是“性能更好” 如果服务器在启动时将所有需要的信息加载到内存，这样就能更快地为响应请求。 此示例中讨论的模块不是一个“坏”模块。 然而，Electron 应用不应该将实际上不需要的信息加载、解析和存储在内存中。
\n简而言之，一个主要为运行在Linux系统上的Node.js 服务器编写的模块，虽然看起来很好，但是对你的应用性能来说可能是个坏消息。 在这个特殊的示例中，正确的解决方案是根本不需要加载模块， 而是使用了一 个包含在以后版本的 Chromium 中的连接性检查。
\n当考虑一个模块时，我们建议你做以下检查：
\nrequire()) 资源可以使用命令行上的单个命令生成用于加载模块的 CPU 配置文件和堆内存配置文件 在下面的示例中，我们看一下受欢迎的模块 request。
node --cpu-prof --heap-prof -e \"require('request')\"\n执行此命令将在您执行的目录下生成一个.cpuprofile和一个.heapprofile 文件。 这两个文件都可以使用 Chrome 开发者工具进行分析，分别使用 Performance 和 Memory 标签 进行分析。
在这个例子里，我们看到在作者的机器上加载request 大概用了半秒钟，其中 node-fetch明显占用了极少的内存并且加载用时少于 50ms。
如果你有非常繁重的初始化操作，请考虑推迟进行。 程序启动立刻查看应用执行的全部工作。 考虑按照用户操作的顺序将它们错开执行，而不是立刻执行所有的操作。
\n在传统的Node.js开发中，我们习惯将所有的require()语句放在代码顶部。 如果你目前正在使用相同的策略and并且使用你不需要立即加载的大型模块编写你的 Electron 应用程序，使用相同的策略并推迟到更适当的时机加载。
加载模块是令人吃惊的繁重的操作，尤其是在Windows上。 当你的应用开始，不应该让用户等待当时不需要的操作。
\n这似乎是显而易见的， 但许多应用程序在程序启动后可能会马上完成大量的 工作 - 如检查更新，正在下载稍后流程中使用的内容，或执行大型的磁盘I/O 操作。
\n让我们把Visual Studio 代码作为一个例子。 当你打开一个文件，它会立刻展示没有高亮任何代码的内容，优先实现和文本交互的功能。 一旦它完成了这项工作，它将继续让代码高亮。
\n让我们考虑一个示例，并假定您的应用程序正在以架空的.foo形式解析文件 。 为了做到这一点，它依赖同样架空的foo-parserver 模块。 在传统的 Node.js 开发中，你可以写代码热加载依赖：
const fs = require('fs')\nconst fooParser = require('foo-parser')\n\nclass Parser {\n constructor () {\n this.files = fs.readdirSync('.')\n }\n\n getParsedFiles () {\n return fooParser.parse(this.files)\n }\n}\n\nconst parser = new Parser()\n\nmodule.exports = { parser }\n在上面的例子中，我们做了很多工作，一旦文件加载，我们就会立即执行。 我们需要立即获取解析的文件吗？ 或许我们可以晚一点再做这件事，当getParsedFiles() 真正的执行到的时候？
// \"fs\" is likely already being loaded, so the `require()` call is cheap\nconst fs = require('fs')\n\nclass Parser {\n async getFiles () {\n // Touch the disk as soon as `getFiles` is called, not sooner.\n // Also, ensure that we're not blocking other operations by using\n // the asynchronous version.\n this.files = this.files || await fs.readdir('.')\n\n return this.files\n }\n\n async getParsedFiles () {\n // Our fictitious foo-parser is a big and expensive module to load, so\n // defer that work until we actually need to parse files.\n // Since `require()` comes with a module cache, the `require()` call\n // will only be expensive once - subsequent calls of `getParsedFiles()`\n // will be faster.\n const fooParser = require('foo-parser')\n const files = await this.getFiles()\n\n return fooParser.parse(files)\n }\n}\n\n// This operation is now a lot cheaper than in our previous example\nconst parser = new Parser()\n\nmodule.exports = { parser }\n简而言之，只有当需要的时候才分配资源，而不是在你的应用启动时分配所有。
\nElectron的主要进程(有时称为“浏览器进程”) 非常特殊：它是与你应用的所有其他进程的父进程，也是和操作系统交互的关键进程。 It handles windows, interactions, and the communication between various components inside your app. It also houses the UI thread.
\n在任何情况下你都不应阻塞此进程或者运行时间长的用户界面线程。 阻塞UI线程意味着您的整个应用程序将冻结直到主进程准备好继续处理。
\nThe main process and its UI thread are essentially the control tower for major operations inside your app. When the operating system tells your app about a mouse click, it'll go through the main process before it reaches your window. 如果您的窗口呈现黄色平滑动画， 它需要和 GPU 进程进行通信——再次穿越主进程。
\nElectron 和 Chromium 谨慎地将大型的磁盘I/O 和 CPU绑定的操作放入新线程，以避免阻塞UI 线程。 你也应该这样做。
\nElectron强大的多进程架构随时准备帮助你完成你的长期任务，但其中也包含少量性能陷阱。
\n1) 对于需要长期占用CPU繁重任务，使用 worker threads， 考虑将它们移动到 BrowserWindow, 或 (作为最后手段) 生成一个专用进程。
\n2) 尽可能避免使用同步IPC 和 remote 模块。 虽然有合法的使用案例，但使用remote模块的时候非常容易不知情地阻塞 UI线程。
3) Avoid using blocking I/O operations in the main process. 简而言之，每当Node.js的核心模块 (如fs 或 child_process) 提供一个同步版本或 异步版本，你更应该使用异步和非阻塞式的变量。
自从 Electron 使用了当前版本的 Chrome，你可以使用Web 平台提供的最新和最优秀的功能来推迟或卸载繁重的操作，以使你的应用保持流畅和迅速的反应。
\n你的应用可能有很多JavaScript在渲染过程中运行。 有个技巧是尽快执行操作，而不占用保持滚动平滑、响应用户输入或60帧/秒动画所需的资源。
\n如果有用户抱怨你的应用“口吃”的时候在渲染的代码中编排操作流就显得尤其重要。
\n一般来说，所有用于构建现代浏览器的性能网络应用程序的建议，对于Electron 的渲染器也同样适用。 现在处理你的应用的主要两个方法是对于小的操作使用requestIdleCallback() 而长时间运行的操作使用 Web Workers。
requestIdleCallback()允许开发者将函数排队为在进程进入空闲期后立刻执行。 它使你能够在不影响用户体验的情况下执行低优先级或后台执行的工作。 想要了解如何使用它的更多信息，请查看MDN上的文档。
Web Workers是在单独线程上运行代码的一个好方式。 有一些注意事项需要考虑 - 请查阅 Electron 的 多线程文档 和 MDN 的 Web Workers文档。 对于长时间并且大量使用CPU的操作来说它们是一个理想的解析器。
\nElectron的一大好处是，你准确地知道哪个引擎将解析你的 JavaScript, HTML和CSS。 如果你重新设计的代码是为整个网页编写的，请确保不会polyfill包含在Electron 中的特性。
\n现在互联网构建网页应用程序时，最老的环境决定了你能够和不能使用的功能。 尽管Electron支持性能良好的 CSS 选择器和动画，但是较早的浏览器可能不支持。 在你可以使用WebGL的场合，你的开发者可能选择了一个资源更加匮乏的解决方案来支持旧机器。
\n当它遇到JavaScript时， 你可能已经包含了工具包库，如DOM选择器 jQuery 或是 如regenerator-runtime支持async/await 的polyfills。
基于 JavaScript 的polyfill速度比Electron 中的原生特征要快一些。 不要通过发布你自己的网络平台标准来减慢你的 Electron 应用速度。
\n假定当前版本的 Electron不需要使用polyfills。 如果你有所疑虑，检查 caniuse.com 以确认 是否在你的Electron版本中使用的Chromium版本 已经支持了你需要的特性.
\n此外，仔细检查您使用的三方库。 它们是否真的必要？ 例如，jQuery非常成功，它的许多功能现在都是 标准JavaScript功能设置的 的一部分。
如果您正在使用 TypeScript 这样的编译器，检查它的配置并确保你的目标是Electron 支持的最新 ECMAScript 版本。
\n避免从互联网中获取几乎不变化的资源，如果它可以轻松地与你的应用程序捆绑起来。
\n许多开始使用基于Web的应用程序的Electron用户后来都使用了桌面应用。 作为网页开发者，我们习惯了从各种内容交付网站加载资源。 Now that you are shipping a proper desktop application, attempt to \"cut the cord\" where possible and avoid letting your users wait for resources that never change and could easily be included in your app.
\n一个典型的例子是谷歌字体。 许多开发者使用谷歌令人印象深刻的免费字体集，这些字体通过内容交付网络获取。 方法显而易见：包括几行CSS 和谷歌将处理其余部分。
\n构建Electron应用程序时，如果你下载字体并将其包含在应用包中，你的用户将会得到更好的服务。
\n在理想情况下，你的应用程序不需要网络就可以运行。 要达到这个目标，你必须了解你的应用正在下载哪些资源以及这些资源的大小。
\n要做到这一点，请打开开发者工具。 导航到 Network 选项卡，然后检查 Disable cache 选项。 然后重新加载你的页面。 除非你的应用禁止重新加载， 你通常可以在使用开发者工具时点击Cmd + R 或Ctrl + R触发重新加载。
开发者工具将仔细记录所有网络请求。 第一步，评估正在下载的所有资源，首先侧重于较大的文件。 其中是否有任何图像、字体或媒体文件不会改变并且可以包含在你的包中？ 如果可以，把它们打包。
\n下一步，启用 Network Throttling。 查找当前读取Online的下拉列表，并选择较慢的速度，例如Fast 3G。 重新加载你的页面并查看你的应用程序是否有等待任何不必要的资源。 在大多数情况下，尽管实际上不需要相关的资源，应用还是会等待网络请求完成。
作为一个提示, 从互联网上加载你可能想要更改的而不发送应用程序更新是一个强有力的策略。 为了进一步控制如何加载资源，请考虑使用Service Worker。
\n正如中已经指出的那样，\"加载和运行代码太早\", 调用 require() 是一项繁重的操作。 如果你能够这样做，将你的应用程序的代码打包到单个文件中。
现代JavaScript开发通常涉及许多文件和模块。 对于使用Electron开发的人来说这是非常好的事情，我们强烈建议你将你的代码打包到单个文件中以确保调用require() 时只在你的应用加载花费一次开销。
有许多JavaScript打包的方法可供使用，我们知道我们最好不要通过推荐一种工具来导致社区不满。 然而，我们的确建议您使用一个能够处理Electron独特的环境的打包程序，它需要处理Node.js 和浏览器两种环境。
\n在撰写这篇文章时，受欢迎的选择包括Webpack, Parcel和rollup.js。
", "title": "性能", "description": "" }, "/docs/api/structures/point": { "locale": "zh-CN", "slug": "point", "href": "/docs/api/structures/point", "crowdinFileId": "256475", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/point.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "x Numbery NumberNote: Both x and y must be whole integers, when providing a point object as input to an Electron API we will automatically round your x and y values to the nearest whole integer.
data (UploadRawData | UploadFile)[] - The post data to be sent to the new window.contentType String - The content-type header used for the data. One of application/x-www-form-urlencoded or multipart/form-data. Corresponds to the enctype attribute of the submitted HTML form.boundary String (optional) - The boundary used to separate multiple parts of the message. Only valid when contentType is multipart/form-data.Note that keys starting with -- are not currently supported. For example, this will errantly submit as multipart/form-data when nativeWindowOpen is set to false in webPreferences:
<form\n target=\"_blank\"\n method=\"POST\"\n enctype=\"application/x-www-form-urlencoded\"\n action=\"https://postman-echo.com/post\"\n>\n <input type=\"text\" name=\"--theKey\">\n <input type=\"submit\">\n</form>\n\n\n监视电源状态的改变。
\n
进程：主进程
\npowerMonitor 模块触发以下事件:
在系统挂起时触发。
\n在系统恢复时触发。
\n当系统变为交流电源时触发。
\n当系统更改为电池电量时触发。
\n当系统即将重启或关机时触发。 如果事件调用e.preventDefault(), Electron 将会尝试延迟系统关机，以便 app 完全退出。 如果e.preventDefault()被调用，在调用类似 app.quit() 后，app 会很快地退出。
当系统即将锁定屏幕时触发。
\n当系统屏幕解锁，立即触发。
\n当应用被激活时发出。 更多信息请访问 文档。
\n当应用被激活时发出。 更多信息请访问 文档。
\n电源监视器 模块具有以下方法：
powerMonitor.getSystemIdleState(idleThreshold)idleThreshold IntegerReturns String - 系统当前状态。 可以被设置为active，idle，locked或者unknown
计算系统空闲状态。 idleThreshold 是闲置之前 (秒内) 的时间量。 locked 仅在支持的系统上可用。
powerMonitor.getSystemIdleTime()Returns Integer - 几秒钟内的空闲时间
计算系统空闲时间以秒为单位。
\npowerMonitor.isOnBatteryPower()返回Boolean，表示系统是否使用电池电源。
要监视此属性的变化，请使用 on-battery 和 on-ac< 事件。
powerMonitor.onBatteryPowerBoolean 属性。 如果系统处于电池电源状态，则为 true。
参见 powerMonitor.isOnBatteryPower()。
\n\n阻止系统进入低功耗 (休眠) 模式。
\n
进程：主进程
\n例如：
\nconst { powerSaveBlocker } = require('electron')\n\nconst id = powerSaveBlocker.start('prevent-display-sleep')\nconsole.log(powerSaveBlocker.isStarted(id))\n\npowerSaveBlocker.stop(id)\npowerSaveBlocker 模块具有以下方法:
powerSaveBlocker.start(type)type String - Power save blocker type.prevent-app-suspension - Prevent the application from being suspended. Keeps system active but allows screen to be turned off. Example use cases: downloading a file or playing audio.prevent-display-sleep - Prevent the display from going to sleep. Keeps system and screen active. Example use case: playing video.Returns Integer-指派给此电源拦截器的 id.
Starts preventing the system from entering lower-power mode. Returns an integer identifying the power save blocker.
\n 注意: prevent-display-sleep 比 prevent-app-suspension 具有更高的优先级。 只有最高优先类型才能生效。 换言之, prevent-display-sleep 始终优先于 prevent-app-suspension。
例如, 一个 API 调用A的类型是 prevent-app-suspension, 另一个调用B的类型是 prevent-display-sleep。 prevent-display-sleep 一直生效，直到 B 停止请求， 之后，prevent-app-suspension才生效。
powerSaveBlocker.stop(id)id Integer 由powerSaveBlocker.start 返回的拦截器 id。停止指定的省电拦截器。
\npowerSaveBlocker.isStarted(id)id Integer 由powerSaveBlocker.start 返回的拦截器 id。Returns Boolean指定的powerSaveBlocker是否已启动。
name String - the name of the printer as understood by the OS.displayName String - the name of the printer as shown in Print Preview.description String - a longer description of the printer's type.status Number - the current status of the printer.isDefault Boolean - whether or not a given printer is set as the default printer on the OS.options Object - an object containing a variable number of platform-specific printer information.The number represented by status means different things on different platforms: on Windows its potential values can be found here, and on Linux and macOS they can be found here.
Below is an example of some of the additional options that may be set which may be different on each platform.
\n{\n name: 'Austin_4th_Floor_Printer___C02XK13BJHD4',\n displayName: 'Austin 4th Floor Printer @ C02XK13BJHD4',\n description: 'TOSHIBA ColorMFP',\n status: 3,\n isDefault: false,\n options: {\n copies: '1',\n 'device-uri': 'dnssd://Austin%204th%20Floor%20Printer%20%40%20C02XK13BJHD4._ipps._tcp.local./?uuid=71687f1e-1147-3274-6674-22de61b110bd',\n finishings: '3',\n 'job-cancel-after': '10800',\n 'job-hold-until': 'no-hold',\n 'job-priority': '50',\n 'job-sheets': 'none,none',\n 'marker-change-time': '0',\n 'number-up': '1',\n 'printer-commands': 'ReportLevels,PrintSelfTestPage,com.toshiba.ColourProfiles.update,com.toshiba.EFiling.update,com.toshiba.EFiling.checkPassword',\n 'printer-info': 'Austin 4th Floor Printer @ C02XK13BJHD4',\n 'printer-is-accepting-jobs': 'true',\n 'printer-is-shared': 'false',\n 'printer-is-temporary': 'false',\n 'printer-location': '',\n 'printer-make-and-model': 'TOSHIBA ColorMFP',\n 'printer-state': '3',\n 'printer-state-change-time': '1573472937',\n 'printer-state-reasons': 'offline-report,com.toshiba.snmp.failed',\n 'printer-type': '10531038',\n 'printer-uri-supported': 'ipp://localhost/printers/Austin_4th_Floor_Printer___C02XK13BJHD4',\n system_driverinfo: 'T'\n }\n}\n\n\n\n处理对象的扩展
\n
Electron's process 对象继承 Node.js process object。 它新增了以下事件、属性和方法
在沙盒化的渲染进程中， process 对象只包含了API的一个子集:
crash()hang()getCreationTime()getHeapStatistics()getBlinkMemoryInfo()getProcessMemoryInfo()getSystemMemoryInfo()getSystemVersion()getCPUUsage()getIOCounters()uptime()argvexecPathenvpidarchplatform沙盒化contextIsolatedtypeversionversionsmaswindowsStorecontextId当Electron加载了它的内部初始化脚本并且是正要开始加载网页或主脚本时触发。
\nprocess.defaultApp 只读一个 Boolean。 当应用程序启动时被作为参数传递给默认应用，这个属性在主进程中是true，否则是undefined。
process.isMainFrame 只读Boolean，若当前渲染器上下文是 渲染器\"主\"框架时为true。 如果你想得到当前框架的ID，你应该使用 webFrame.routingId。
process.mas 只读一个 Boolean。 为Mac App Store 构建，该属性是 true，为其他构建则为undefined。
process.noAsarBoolean 控制您应用程序内的 ASAR 支持。 设置为 true将会禁用Node内置模块中对 asar 的支持。
process.noDeprecationBoolean 类型，用于控制弃用警告是否被打印到stderr。 将其设置为true将会禁用弃用警告。 使用此属性代替 -no-deprecation 命令行标志。
process.resourcesPath 只读String 类型， 表示资源目录的路径。
process.sandboxed 只读一个 Boolean。 当渲染器进程被沙盒化时，该属性是 true，否则是 undefined。
process.contextIsolated 只读一个Boolean类型的值指明当前渲染上下文是否启用了contextIsolation。 这在主进程中是undefined的。
process.throwDeprecationBoolean类型，用于控制是否将弃用警告当做例外。 设置它为 true 时会抛出错误。 使用此属性代替 --throw-deprecation 命令行标志。
process.traceDeprecationBoolean类型，用于控制打印到 stderr 的弃用中是否包含其堆栈跟踪。 将此设置为 true 将会打印对弃用的堆栈跟踪。 此属性代替 --trace-deprecation 命令行标志。
process.traceProcessWarnings一个 Boolean, 用于控制是否将进程的警告打印到包含堆栈跟踪的 stderr中 。 将此设置为 true 将打印对进程警告的堆栈跟踪（包括弃用）。 此属性代替 --trace-warnings 命令行标志。
process.type 只读String 代表当前进程的类型，可以是：
browser - The main processrenderer - A renderer processworker - In a web workerprocess.versions.chrome 只读string，一个表示 Chrome 版本的字符串。
process.versions.electron 只读string，一个表示 Electron 版本的字符串。
process.windowsStore 只读一个 Boolean。 如果应用以 Windows 商店应用(appx) 运行，该属性为true，否则为 undefined。
process.contextId 只读一个字符串 (可选) 代表当前JavaScript 上下文中的全局唯一ID。 每个对话框都有自己的 JavaScript 上下文。 当上下文隔离被启用，被隔离的环境中也有单独的JavaScript上下文。 该属性仅在渲染进程中可用。
process 对象具有以下方法:
process.crash()导致当前进程崩溃的主线程。
\nprocess.getCreationTime()返回 Number | null -从纪元开始的毫秒数，如果信息不可用则返回null
指示应用程序的创建时间。 新时代（1970-01-01 00:00:00 UTC）以来的毫秒数表示的时间。 如果无法获得进程创建时间，则返回为空。
\nprocess.getCPUUsage()返回 CPUUsage
process.getIOCounters() Windows Linux返回 IOCounters
process.getHeapStatistics()返回 Object:
totalHeapSize IntegertotalHeapSizeExecutable IntegertotalPhysicalSize IntegertotalAvailableSize IntegerusedHeapSize IntegerheapSizeLimit IntegermallocedMemory IntegerpeakMallocedMemory IntegerdoesZapGarbage Boolean返回包含 V8 堆统计的对象。 备注：所有数据值以KB为单位
\nprocess.getBlinkMemoryInfo()返回 Object:
allocated Integer - Size of all allocated objects in Kilobytes.marked Integer - Size of all marked objects in Kilobytes.total Integer - Total allocated space in Kilobytes.返回带有Blink内存信息的对象。 可以用于调试渲染/DOM相关内存问题。 请注意，所有值都以KB为单位
\nprocess.getProcessMemoryInfo()返回 Promise<ProcessMemoryInfo> - Promise成功返回 PrecessMemoryInfo
返回一个对象，提供当前进程的内存使用统计。 请注意，所有统计值都以KB为单位 这个api应该在应用程序准备就绪后被调用。
\nChromium 没有为macOS提供 residentSet 值。 因为macOS对最近未使用过的页面进行内存压缩。 结果是原始设置大小的值不是我们所期望的。 私有 内存更能代表在 macOS 上进程的实际预压缩内存的使用情况。
process.getSystemMemoryInfo()返回 Object:
total Integer - 系统可用的物理内存总量(Kb)。free Integer - 应用程序或磁盘缓存未使用的内存总量。swapTotal Integer Windows Linux - 系统交换内存容量（单位：千字节）。swapFree Integer Windows Linux - 系统可用交换内存大小（单位：千字节）。返回一个对象，提供整个系统的内存使用统计。 请注意，所有统计值都以KB为单位
\nprocess.getSystemVersion()返回 String - 主机操作系统的版本。
示例：
\nconst version = process.getSystemVersion()\nconsole.log(version)\n// On macOS -> '10.13.6'\n// On Windows -> '10.0.17763'\n// On Linux -> '4.15.0-45-generic'\n注意： 它返回实际操作系统版本，而不是在 macOS 上的内核版本，不同于 os.release()。
process.takeHeapSnapshot(filePath)filePath String - Path to the output file.返回 Boolean - 指明快捷方式是否被成功创建。
Takes a V8 heap snapshot and saves it to filePath.
process.hang()导致当前进程挂起的主线程。
\nprocess.setFdLimit(maxDescriptors) macOS LinuxmaxDescriptors Integer将文件描述符的软限制设置为 maxDescriptors 或 OS 硬限制, 其中以当前进程较低的值为准。
residentSet Integer Linux Windows - The amount of memory currently pinned to actual physical RAM in Kilobytes.private Integer - The amount of memory not shared by other processes, such as JS heap or HTML content in Kilobytes.shared Integer - The amount of memory shared between processes, typically memory consumed by the Electron code itself in Kilobytes.pid Integer - Process id of the process.type String - 进程类型。 以下值之一：BrowserTabUtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownserviceName String (可选) - 进程的非本地化名称。name String (可选) - 进程的名称。 功能性示例： Audio Service, Content Decryption Module Service, Network Service, Video Capture, 等等。cpu CPUUsage - CPU usage of the process.creationTime Number - Creation time for this process. The time is represented as number of milliseconds since epoch. Since the pid can be reused after a process dies, it is useful to use both the pid and the creationTime to uniquely identify a process.memory MemoryInfo - Memory information for the process.sandboxed Boolean (optional) macOS Windows - Whether the process is sandboxed on OS level.integrityLevel String (optional) Windows - One of the following values:untrustedlowmediumhighunknownElectron 继承了来自 Chromium 的多进程架构，这使得此框架在架构上非常相似于一个现代的网页浏览器。 在本指南中，我们将会阐述那些我们运用于 最小的 快速启动应用 中的关于 Electron 的概念性知识。
\n网页浏览器是个极其复杂的应用程序。 除了显示网页内容的主要能力之外，他们还有许多次要的职责，例如：管理众多窗口 ( 或 标签页 ) 和加载第三方扩展。
\n在早期，浏览器通常使用单个进程来处理所有这些功能。 虽然这种模式意味着您打开每个标签页的开销较少，但也同时意味着一个网站的崩溃或无响应会影响到整个浏览器。
\n为了解决这个问题，Chrome 团队决定让每个标签页在自己的进程中渲染， 从而限制了一个网页上的有误或恶意代码可能导致的对整个应用程序造成的伤害。 然后用单个浏览器进程控制这些標籤頁进程，以及整个应用程序的生命周期。 下方来自 Chrome 漫画 的图表可视化了此模型：
\n
Electron 应用程序的结构非常相似。 作为应用开发者，您控制着两种类型的进程：主进程和渲染器。 这些类似于上面概述的 Chrome 自己的浏览器和其渲染器进程。
\n每个 Electron 应用都有一个单一的主进程，作为应用程序的入口点。 主进程在 Node.js 环境中运行，这意味着它具有 require 模块和使用所有 Node.js API 的能力。
主进程的主要目的是使用 BrowserWindow 模块创建和管理应用程序窗口。
BrowserWindow 类的每个实例创建一个应用程序窗口，且在单独的渲染器进程中加载一个网页。 您可从主进程用 window 的 webContent 对象与网页内容进行交互。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\n\n\n注意：渲染器进程也是为 web embeds 而被创建的，例如
\nBrowserView模块。 嵌入式网页内容也可访问webContents对象。
由于 BrowserWindow 模块是一个 EventEmitter， 所以您也可以为各种用户事件 ( 例如，最小化 或 最大化您的窗口 ) 添加处理程序。
当一个 BrowserWindow 实例被销毁时，与其相应的渲染器进程也会被终止。
主进程还能通过 Electron 的 app 模块来控制您应用程序的生命周期。 该模块提供了一整套的事件和方法，可以使你添加自定义的应用程序行为 ( 例如：以编程方式退出您的应用程序、修改程序坞或显示关于面板 ) 。
这是一个实际的例子，这个app来源于快速入门指南，用 app API 创建了一个更原生的应用程序窗口体验。
// quitting the app when no windows are open on non-macOS platforms\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\n为了使 Electron 的功能不仅仅限于对网页内容的封装，主进程也添加了自定义的 API 来与用户的作业系统进行交互。 Electron 有着多种控制原生桌面功能的模块，例如菜单、对话框以及托盘图标。
\n关于 Electron 主进程模块的完整列表，请参阅我们的 API 文档。
\n每个 Electron 应用都会为每个打开的 BrowserWindow ( 与每个网页嵌入 ) 生成一个单独的渲染器进程。 洽如其名，渲染器负责 渲染 网页内容。 所以实际上，运行于渲染器进程中的代码是须遵照网页标准的 (至少就目前使用的 Chromium 而言是如此) 。
因此，一个浏览器窗口中的所有的用户界面和应用功能，都应与您在网页开发上使用相同的工具和规范来进行攥写。
\n虽然解释每一个网页规范超出了本指南的范围，但您最起码要知道的是：
\n<script> 元素可添加可执行的 JavaScript 代码。此外，这也意味着渲染器无权直接访问 require 或其他 Node.js API。 为了在渲染器中直接包含 NPM 模块，您必须使用与在 web 开发時相同的打包工具 (例如 webpack 或 parcel)
\n\n注意：渲染器进程可以生成一个完整的 Node.js 环境以便于开发。 在过去这是默认的，但如今此功能考虑到安全问题已经被禁用。
\n
此刻，您也许会好奇，您在渲染器进程中的用户介面该如何与 Node.js 和 Electron 的原生桌面功能进行交互，如果这些功能都仅适用于主进程的话。 而事实上，确实没有直接导入 Electron 內容脚本的方法。
\n预加载脚本可以在 BrowserWindow 构造方法中的 webPreferences 选项里被附加到主进程。
const { BrowserWindow } = require('electron')\n//...\nconst win = new BrowserWindow({\n webPreferences: {\n preload: 'path/to/preload.js'\n }\n})\n//...\n由于预加载脚本与渲染器共享同一个全局 Window 接口，并且可以访问 Node.js API，因此它通过在 window 全局中暴露任意您的网络内容可以随后使用的 API 来增强渲染器。
虽然预加载脚本与其所附加的渲染器在全局共享着一个 window 变数，但您并不能从中直接附加任何变数到 window 之中，因为 contextIsolation 是默认的。
window.myAPI = {\n desktop: true\n}\nconsole.log(window.myAPI)\n// => undefined\n语境隔离（Context Isolation）意味着预加载脚本与渲染器的主要运行环境是隔离开来的，以避免泄漏任何具特权的 API 到您的网页内容代码中。
\n取而代之，我们將使用 contextBridge 模块来安全地实现交互：
const { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n desktop: true\n})\nconsole.log(window.myAPI)\n// => { desktop: true }\n此功能对两个主要目的來說非常有用：
\nipcRenderer 帮手模块于渲染器中，您可以使用 进程间通讯 ( inter-process communication, IPC ) 来从渲染器触发主进程任务 ( 反之亦然 ) 。window 全局变量上添加自定义的属性，好在 web 客户端用上仅适用于桌面应用的设计逻辑 。productIdentifier String - The string that identifies the product to the Apple App Store.localizedDescription String - A description of the product.localizedTitle String - The name of the product.contentVersion String - A string that identifies the version of the content.contentLengths Number[] - The total size of the content, in bytes.price Number - The cost of the product in the local currency.formattedPrice String - The locale formatted price of the product.currencyCode String - 3 character code presenting a product's currency based on the ISO 4217 standard.isDownloadable Boolean - A Boolean value that indicates whether the App Store has downloadable content for this product. true if at least one file has been associated with the product.进度条使窗口能够向用户提供其进度信息，而无需被切换到前台。
\n在Windows环境下，进度条被显示在任务栏按钮上。
\n![Windows Progress Bar][https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png\\]
\n在MacOS环境下，进度条将被显示在dock栏图标上
\n
在Linux系统中，Unity桌面也有相似的特性，能在Launcher上显示进度条。
\n
\n\n注意：在 Windows 上，每个窗口都可以有自己的进度条，而在 macOS 和 Linux（unity桌面）上，同一个应用程序只能有一个进度条。
\n
这三种环境中的进度条功能由同一个API实现：BrowserWindow实例下的setProgressBar()方法。 此方法以介于 0 和 1 之间的小数表示进度。 例如，如果有一个耗时很长的任务，它当前的进度是63%，那么你可以用setProgressBar(0.63)来显示这一进度。
将参数设置为负值 (例如， -1) 将删除progress bar。 设定值大于 1 在 Windows 中将表示一个不确定的进度条 ，或在其他操作系统中显示为 100%。 一个不确定的progress bar 仍然处于活动状态，但不显示实际百分比， 并且用于当 您不知道一个操作需要多长时间才能完成的情况。
参见 API documentation for more options and modes。
\n在此示例中，我们将进度栏添加到main window中，该窗口会使用node.js的计时器实现随着时间的推移而进度增长。
\nconst { app, BrowserWindow } = require('electron')\n\nlet progressInterval\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n\n const INCREMENT = 0.03\n const INTERVAL_DELAY = 100 // ms\n\n let c = 0\n progressInterval = setInterval(() => {\n // update progress bar to next value\n // values between 0 and 1 will show progress, >1 will show indeterminate or stick at 100%\n win.setProgressBar(c)\n\n // increment or reset progress bar\n if (c < 2) c += INCREMENT\n else c = 0\n }, INTERVAL_DELAY)\n}\n\napp.whenReady().then(createWindow)\n\n// before the app is terminated, clear both timers\napp.on('before-quit', () => {\n clearInterval(progressInterval)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n启动 Electron 应用程序后，Dock (macOS) 或 taskbar (Windows, Unity) 应该显示一个进度条, 从零开始, 到100%到完成。 应该显示不确定的 (Windows) 或短暂的固定到100% (其他操作系统) 并然后循环。
\n
对于macOS，当使用 Mission Control 时，应用程序也会显示进度条
\n
\n\n注册自定义协议并拦截基于现有协议的请求。
\n
进程：主进程
\n实现与 file:// 协议具有相同效果的协议的示例:
const { app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n})\n 注意: 除了指定的方法, 其他方法只能在 app 模块的 ready 事件被触发后使用。
protocol with a custom partition or sessionA protocol is registered to a specific Electron session object. If you don't specify a session, then your protocol will be applied to the default session that Electron uses. However, if you define a partition or session on your browserWindow's webPreferences, then that window will use a different session and your custom protocol will not work if you just use electron.protocol.XXX.
To have your custom protocol work in combination with a custom session, you need to register it to that session explicitly.
\nconst { session, app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const partition = 'persist:example'\n const ses = session.fromPartition(partition)\n\n ses.protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n\n mainWindow = new BrowserWindow({ webPreferences: { partition } })\n})\nprotocol 模块具有以下方法：
protocol.registerSchemesAsPrivileged(customSchemes)customSchemes CustomScheme[]注意. 此方法只能在 app 的 ready 事件触发前调用，且只能调用一次
Registers the scheme as standard, secure, bypasses content security policy for resources, allows registering ServiceWorker, supports fetch API, and streaming video/audio. Specify a privilege with the value of true to enable the capability.
An example of registering a privileged scheme, that bypasses Content Security Policy:
\nconst { protocol } = require('electron')\nprotocol.registerSchemesAsPrivileged([\n { scheme: 'foo', privileges: { bypassCSP: true } }\n])\n标准scheme遵循 RFC 3986 所设定的 URI泛型语法 。 例如, http 和 https 是标准协议, 而 file 不是。
Registering a scheme as standard allows relative and absolute resources to be resolved correctly when served. 否则, 该协议将表现为 file 协议, 而且，这种文件协议将不能解析相对路径。
例如, 当您使用自定义协议加载以下内容时，如果你不将其注册为标准scheme, 图片将不会被加载, 因为非标准scheme无法识别相对 路径:
\n<body>\n <img src='test.png'>\n</body>\n注册一个scheme作为标准scheme将允许其通过FileSystem 接口访问文件。 否则, 渲染器将会因为该scheme，而抛出一个安全性错误。
\nBy default web storage apis (localStorage, sessionStorage, webSQL, indexedDB, cookies) are disabled for non standard schemes. So in general if you want to register a custom protocol to replace the http protocol, you have to register it as a standard scheme.
Protocols that use streams (http and stream protocols) should set stream: true. The <video> and <audio> HTML elements expect protocols to buffer their responses by default. The stream flag configures those elements to correctly expect streaming responses.
protocol.registerFileProtocol(scheme, handler)scheme Stringhandler 函数request ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a file as the response. The handler will be called with request and callback where request is an incoming request for the scheme.
要处理 request, 应当使用文件的路径或具有 path 属性的对象来调用 callback。例如:callback(filePath)或 callback({ path: filePath }). The filePath must be an absolute path.
By default the scheme is treated like http:, which is parsed differently from protocols that follow the \"generic URI syntax\" like file:.
protocol.registerBufferProtocol(scheme, handler)scheme Stringhandler 函数request ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
注册一个 scheme 协议, 将 Buffer作为响应发送
The usage is the same with registerFileProtocol, except that the callback should be called with either a Buffer object or an object that has the data property.
示例：
\nprotocol.registerBufferProtocol('atom', (request, callback) => {\n callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })\n})\nprotocol.registerStringProtocol(scheme, handler)scheme Stringhandler 函数request ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
注册一个 scheme 协议, 将 String 作为响应发送
The usage is the same with registerFileProtocol, except that the callback should be called with either a String or an object that has the data property.
protocol.registerHttpProtocol(scheme, handler)scheme Stringhandler 函数request ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully registered
注册一个 scheme 协议, 将 HTTP 请求作为响应发送
The usage is the same with registerFileProtocol, except that the callback should be called with an object that has the url property.
protocol.registerStreamProtocol(scheme, handler)scheme Stringhandler 函数request ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a stream as a response.
The usage is the same with registerFileProtocol, except that the callback should be called with either a ReadableStream object or an object that has the data property.
示例：
\nconst { protocol } = require('electron')\nconst { PassThrough } = require('stream')\n\nfunction createStream (text) {\n const rv = new PassThrough() // PassThrough is also a Readable stream\n rv.push(text)\n rv.push(null)\n return rv\n}\n\nprotocol.registerStreamProtocol('atom', (request, callback) => {\n callback({\n statusCode: 200,\n headers: {\n 'content-type': 'text/html'\n },\n data: createStream('<h5>Response</h5>')\n })\n})\nIt is possible to pass any object that implements the readable stream API (emits data/end/error events). For example, here's how a file could be returned:
protocol.registerStreamProtocol('atom', (request, callback) => {\n callback(fs.createReadStream('index.html'))\n})\nprotocol.unregisterProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unregistered
取消对自定义scheme的注册
protocol.isProtocolRegistered(scheme)scheme StringReturns Boolean - Whether scheme is already registered.
protocol.interceptFileProtocol(scheme, handler)scheme Stringhandler 函数request ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
终止 scheme 协议, 并将 handler 作为该protocol新的处理方式，即返回一个file。
protocol.interceptStringProtocol(scheme, handler)scheme Stringhandler 函数request ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
终止 scheme 协议, 并将 handler 作为该protocol新的处理方式，即返回一个String。
protocol.interceptBufferProtocol(scheme, handler)scheme Stringhandler 函数request ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
终止 scheme 协议, 并将 handler 作为该protocol新的处理方式，即返回一个Buffer。
protocol.interceptHttpProtocol(scheme, handler)scheme Stringhandler 函数request ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully intercepted
终止 scheme 协议, 并将 handler 作为该protocol新的处理方式，即返回一个新 HTTP 请求。
protocol.interceptStreamProtocol(scheme, handler)scheme Stringhandler 函数request ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
它与 registerStreamProtocol方法相同, 不过它是用来替换现有的protocol处理方式。
protocol.uninterceptProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unintercepted
移除为 scheme 安装的拦截器，并还原其原始处理方式。
protocol.isProtocolIntercepted(scheme)scheme StringReturns Boolean - Whether scheme is already intercepted.
url Stringreferrer Stringmethod StringuploadData UploadData[] (optional)headers Record<String, String>error Integer (optional) - When assigned, the request will fail with the error number . For the available error numbers you can use, please see the net error list.statusCode Number (optional) - The HTTP response code, default is 200.charset String (optional) - The charset of response body, default is \"utf-8\".mimeType String (optional) - The MIME type of response body, default is \"text/html\". Setting mimeType would implicitly set the content-type header in response, but if content-type is already set in headers, the mimeType would be ignored.headers Record<string, string | string[]> (optional) - An object containing the response headers. The keys must be String, and values must be either String or Array of String.data (Buffer | String | ReadableStream) (optional) - The response body. When returning stream as response, this is a Node.js readable stream representing the response body. When returning Buffer as response, this is a Buffer. When returning String as response, this is a String. This is ignored for other types of responses.path String (optional) - Path to the file which would be sent as response body. This is only used for file responses.url String (optional) - Download the url and pipe the result as response body. This is only used for URL responses.referrer String (optional) - The referrer URL. This is only used for file and URL responses.method String (optional) - The HTTP method. This is only used for file and URL responses.session Session (optional) - The session used for requesting URL, by default the HTTP request will reuse the current session. Setting session to null would use a random independent session. This is only used for URL responses.uploadData ProtocolResponseUploadData (optional) - The data used as upload data. This is only used for URL responses when method is \"POST\".contentType String - MIME type of the content.data String | Buffer - Content to be sent.在 GitHub 上复制项目到你的账号并把项目克隆到本地。
\n$ git clone git@github.com:username/electron.git\n$ cd electron\n$ git remote add upstream https://github.com/electron/electron.git\n$ git fetch upstream\n根据您的操作系统, 项目构建步骤和依赖项稍有不同。 请参阅这些关于构建 Electron 项目的详细指南:
\n\n一旦您在本地构建了项目, 就可以开始进行更改了!
\n为了保持您的开发环境的组织, 创建本地分支来保存您的工作。 These should be branched directly off of the main branch.
$ git checkout -b my-branch -t upstream/main\nMost pull requests opened against the electron/electron repository include changes to either the C/C++ code in the shell/ folder, the JavaScript code in the lib/ folder, the documentation in docs/api/ or tests in the spec/ folder.
请确保都运行 npm run lint 在任何代码更改后, 以确保它们遵循项目的代码样式。
在项目的不同部分修改代码时, 有关最佳实践的更多信息, 请参见 编码样式 。
\n建议将更改按逻辑分组在每个独立提交中。 其他贡献者可以从拆分多个提交中更容易的检查代码的改变。 合并请求没有限制提交的数量。
\n$ git add my/changed/files\n$ git commit\n请注意, 在最后执行合并代码时多个提交通常会被合并。
\n好的提交说明应描述更改的内容和原因。 Electron项目使用语义化提交信息以精简发布过程。
\nBefore a pull request can be merged, it must have a pull request title with a semantic prefix.
\n带有语义化前缀的提交信息的样例：
\nfix: don't overwrite prevent_default if default wasn't preventedfeat: add app.isPackaged() methoddocs: app.isDefaultProtocolClient 现在在Linux可用常见前缀：
\n其他在写提交信息时需要留意的事情：
\nA commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with Major in semantic versioning). 一个重大更改可以是任何类型提交的一部分。 e.g., a fix:, feat: & chore: types would all be valid, in addition to any other type.
参阅 conventionalcommits.org 以获得更多细节。
\n提交更改后, 最好使用 git rebase (而不是 git merge) 将您的工作与主代码库同步。
$ git fetch upstream\n$ git rebase upstream/main\nThis ensures that your working branch has the latest changes from electron/electron main.
Bug 修复和功能应始终与测试一起进行。 提供了 测试指南 使流程更容易。 看其他测试, 看看它们应该如何结构化也会有帮助。
\n当提交您的改变到合并代码请求前, 请始终运行完整的测试套件。 运行测试:
\n$ npm run test\n请确保 linter 不报告任何问题, 并且所有测试都通过。 请不要提交失败的修补程序或检查。
\nIf you are updating tests and want to run a single spec to check it:
\n$ npm run test -match=menu\n上述操作只运行与 menu 匹配的规范模块, 这对于那些在测试周期的末尾进行测试的任何人都很有用。
一旦您的提交准备就绪--通过测试和 linting--将您的工作分支推送到您在 GitHub 上复制的分支, 然后开始开启合并代码请求的过程。
\n$ git push origin my-branch\n从 GitHub 中, 开启一个新的合并代码请求将为您呈现一个模板，这应填写如下:
\n<!--\nThank you for your pull request. Please provide a description above and review\nthe requirements below.\n\nBug fixes and new features should include tests and possibly benchmarks.\n\nContributors guide: https://github.com/electron/electron/blob/main/CONTRIBUTING.md\n-->\n您可能会得到反馈或请求更改您的请求。 这是提交过程的重要部分, 所以不要气馁! 有些贡献者可能会立刻签署请求。 其他人可能有详细的评论或反馈。 这是过程的必要部分, 以便评估更改是否正确和必要。
\n要更改现有的请求, 请对本地分支进行更改, 添加新的提交, 并将这些更改推送到您的分支。 GitHub 将自动更新请求。
\n$ git add my/changed/files\n$ git commit\n$ git push origin my-branch\n一些更高级的方法比如使用 git rebase 来管理提交是很有效的, 但这超出本指南的范围。
如果您正在等待某事的答案, 请随时添加评论 ping 向审阅者。 如果您遇到的单词或缩略词似乎不熟悉, 请参阅此 词汇表 。
\nAll pull requests require approval from a Code Owner of the area you modified in order to land. Whenever a maintainer reviews a pull request they may request changes. These may be small, such as fixing a typo, or may involve substantive changes. Such requests are intended to be helpful, but at times may come across as abrupt or unhelpful, especially if they do not include concrete suggestions on how to change them.
\n尽量不要气馁。 如果你觉得审查是不公平的, 那么说或者寻求另一个项目参与者的投入。 通常, 这种评论是由于审阅者没有足够的时间来审查和无意的。 这样的困难往往可以用一点耐心来解决。 That said, reviewers should be expected to provide helpful feedback.
\n为了合并代码, 代码合并请求要求必须由至少一个 Electron 代码所有者审查和批准并且通过 CI。 之后, 如果没有其他参与者的异议, 请求可以合并。
\n恭喜您, 感谢您的贡献!
\n每个请求都在连续集成 (CI) 系统上进行测试, 以确认它在 Electron 支持的平台上工作。
\n理想情况下, 代码合并请求将在 CI 的所有平台上通过测试 (\"变成绿色\")。 这意味着所有测试都通过, 并且没有 linting 错误。 然而，CI 自身的基础设施在特定的平台上或者在\"不可靠\"的测试下会失败(\"变红\") 的情况并不少见。 必须手动检查每个 CI 故障以确定原因。
\nCI starts automatically when you open a pull request, but only core maintainers can restart a CI run. If you believe CI is giving a false negative, ask a maintainer to restart the tests.
", "title": "合并请求", "description": "" }, "/docs/tutorial/quick-start": { "locale": "zh-CN", "slug": "quick-start", "href": "/docs/tutorial/quick-start", "crowdinFileId": "256237", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/quick-start.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "本指南将会通过使用Electron创建一个极简的 Hello World 应用一步步的带你了解，该应用与electron/electron-quick-start类似。
通过这个教程，你的app将会打开一个浏览器窗口，来展示包含当前正在运行的 Chromium, Node.js与 Electronweb等版本信息的web界面
\n在使用Electron进行开发之前，您需要安装 Node.js。 我们建议您使用最新的LTS版本。
\n\n\n请使用为你平台预构建的 Node.js 安装器来进行安装， 否则，您可能会遇到与不同开发工具不兼容的问题。
\n
要检查 Node.js 是否正确安装，请在您的终端输入以下命令：
\nnode -v\nnpm -v\n这两个命令应输出了 Node.js 和 npm 的版本信息。
\n注意 因为 Electron 将 Node.js 嵌入到其二进制文件中，你应用运行时的 Node.js 版本与你系统中运行的 Node.js 版本无关。
\nElectron 应用程序遵循与其他 Node.js 项目相同的结构。 首先创建一个文件夹并初始化 npm 包。
\nmkdir my-electron-app && cd my-electron-app\nnpm init\ninit初始化命令会提示您在项目初始化配置中设置一些值 为本教程的目的，有几条规则需要遵循：
entry point 应为 main.js.author 与 description 可为任意值，但对于应用打包是必填项。你的 package.json 文件应该像这样：
{\n \"name\": \"my-electron-app\",\n \"version\": \"1.0.0\",\n \"description\": \"Hello World!\",\n \"main\": \"main.js\",\n \"author\": \"Jane Doe\",\n \"license\": \"MIT\"\n}\n然后，将 electron 包安装到应用的开发依赖中。
$ npm install --save-dev electron\n\n\n注意：如果您在安装 Electron 时遇到任何问题，请 参见 高级安装 指南。
\n
最后，您希望能够执行 Electron 如下所示，在您的 package.json配置文件中的scripts字段下增加一条start命令：
{\n \"scripts\": {\n \"start\": \"electron .\"\n }\n}\nstart命令能让您在开发模式下打开您的应用
npm start\n\n\n注意：此脚本将告诉 Electron 在您项目根目录运行 此时，您的应用将立即抛出一个错误提示您它无法找到要运行的应用
\n
任何 Electron 应用程序的入口都是 main 文件。 这个文件控制了主进程，它运行在一个完整的Node.js环境中，负责控制您应用的生命周期，显示原生界面，执行特殊操作并管理渲染器进程(稍后详细介绍)。
执行期间，Electron 将依据应用中 package.json配置下main字段中配置的值查找此文件，您应该已在应用脚手架步骤中配置。
要初始化这个main文件，需要在您项目的根目录下创建一个名为main.js的空文件。
\n\n注意：如果您此时再次运行
\nstart命令，您的应用将不再抛出任何错误！ 然而，它不会做任何事因为我们还没有在main.js中添加任何代码。
在可以为我们的应用创建窗口前，我们需要先创建加载进该窗口的内容。 在 Electron 中，每个窗口中无论是本地的HTML文件还是远程URL都可以被加载显示。
\n此教程中，您将采用本地HTML的方式。 在您的项目根目录下创建一个名为index.html的文件：
\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n </body>\n</html>\n\n\n注意：在这个HTML文本中，您会发现主体文本中丢失了版本编号。 稍后我们将使用 JavaScript 动态插入它们。
\n
现在您有了一个页面，将它加载进应用窗口中。 要做到这一点，你需要 两个Electron模块：
\napp 模块，它控制应用程序的事件生命周期。BrowserWindow 模块，它创建和管理应用程序 窗口。因为主进程运行着Node.js，您可以在文件头部将他们导入作为公共JS模块：
\nconst { app, BrowserWindow } = require('electron')\n然后，添加一个createWindow()方法来将index.html加载进一个新的BrowserWindow实例。
function createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\n接着，调用createWindow()函数来打开您的窗口。
在 Electron 中，只有在 app 模块的 ready 事件被激发后才能创建浏览器窗口。 您可以通过使用 app.whenReady() API来监听此事件。 在whenReady()成功后调用createWindow()。
app.whenReady().then(() => {\n createWindow()\n})\n\n\n注意：此时，您的电子应用程序应当成功 打开显示您页面的窗口！
\n
虽然你现在可以打开一个浏览器窗口，但你还需要一些额外的模板代码使其看起来更像是各平台原生的。 应用程序窗口在每个OS下有不同的行为，Electron将在app中实现这些约定的责任交给开发者们。
\n一般而言，你可以使用 进程 全局的 platform 属性来专门为某些操作系统运行代码。
在Windows和Linux上，关闭所有窗口通常会完全退出一个应用程序。
\nTo implement this, listen for the app module's 'window-all-closed' event, and call app.quit() if the user is not on macOS (darwin).
app.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\n当 Linux 和 Windows 应用在没有窗口打开时退出了，macOS 应用通常即使在没有打开任何窗口的情况下也继续运行，并且在没有窗口可用的情况下激活应用时会打开新的窗口。
\nTo implement this feature, listen for the app module's activate event, and call your existing createWindow() method if no browser windows are open.
因为窗口无法在 ready 事件前创建，你应当在你的应用初始化后仅监听 activate 事件。 通过在您现有的 whenReady() 回调中附上您的事件监听器来完成这个操作。
app.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n\n注意：此时，您的窗口控件应功能齐全！
\n
现在，最后要做的是输出Electron的版本号和它的依赖项到你的web页面上。
\n在主进程通过Node的全局 process 对象访问这个信息是微不足道的。 然而，你不能直接在主进程中编辑DOM，因为它无法访问渲染器 文档 上下文。 它们存在于完全不同的进程！
\n\nNote: If you need a more in-depth look at Electron processes, see the Process Model document.
\n
这是将 预加载 脚本连接到渲染器时派上用场的地方。 预加载脚本在渲染器进程加载之前加载，并有权访问两个 渲染器全局 (例如 window 和 document) 和 Node.js 环境。
创建一个名为 preload.js 的新脚本如下：
window.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\n上面的代码访问 Node.js process.versions 对象，并运行一个基本的 replaceText 辅助函数将版本号插入到 HTML 文档中。
要将此脚本附加到渲染器流程，请在你现有的 BrowserWindow 构造器中将路径中的预加载脚本传入 webPreferences.preload 选项。
// 在文件头部引入 Node.js 中的 path 模块\nconst path = require('path')\n\n// 修改现有的 createWindow() 函数\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n}\n// ...\n这里使用了两个Node.js概念：
\n__dirname string points to the path of the currently executing script (in this case, your project's root folder).path.join API joins multiple path segments together, creating a combined path string that works across all platforms.我们使用一个相对当前正在执行JavaScript文件的路径，这样您的相对路径将在开发模式和打包模式中都将有效。
\n此刻，您可能想知道如何为您的应用程序添加更多功能。
\n对于与您的网页内容的任何交互，您想要将脚本添加到您的渲染器进程中。 由于渲染器运行在正常的 Web 环境中，因此您可以在 index.html 文件关闭 </body> 标签之前添加一个 <script> 标签，来包括您想要的任意脚本：
<script src=\"./renderer.js\"></script>\nThe code contained in renderer.js can then use the same JavaScript APIs and tooling you use for typical front-end development, such as using webpack to bundle and minify your code or React to manage your user interfaces.
完成上述步骤后，您应该有一个功能齐全的Electron程序，如下所示：
\n
完整代码如下：
\n// main.js\n\n// Modules to control application life and create native browser window\nconst { app, BrowserWindow } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n // Create the browser window.\n const mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n // and load the index.html of the app.\n mainWindow.loadFile('index.html')\n\n // Open the DevTools.\n // mainWindow.webContents.openDevTools()\n}\n\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// 部分 API 在 ready 事件触发后才能使用。\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n // On macOS it's common to re-create a window in the app when the\n // dock icon is clicked and there are no other windows open.\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\n\n// In this file you can include the rest of your app's specific main process\n// code. 也可以拆分成几个文件，然后用 require 导入。\n// preload.js\n\n// All of the Node.js APIs are available in the preload process.\n// 它拥有与Chrome扩展一样的沙盒。\nwindow.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\n<!--index.html-->\n\n\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n\n <!-- You can also require other files to run in this process -->\n <script src=\"./renderer.js\"></script>\n </body>\n</html>\n总结我们所做的所有步骤：
\n*我们启动了一个Node.js程序，并将Electron添加为依赖。
\nWe created a main.js script that runs our main process, which controls our app\nand runs in a Node.js environment. 在此脚本中， 我们使用 Electron 的 app 和 BrowserWindow 模块来创建一个浏览器窗口，在一个单独的进程(渲染器)中显示网页内容。
为了访问渲染器中的Node.js的某些功能，我们在 BrowserWindow 的构造函数上附加了一个预加载脚本。
最快捷的打包方式是使用 Electron Forge。
\n将 Electron Forge 添加到您应用的开发依赖中，并使用其\"import\"命令设置 Forge 的脚手架：
\nnpm install --save-dev @electron-forge/cli\nnpx electron-forge import\n\n✔ Checking your system\n✔ Initializing Git Repository\n✔ Writing modified package.json file\n✔ Installing dependencies\n✔ Writing modified package.json file\n✔ Fixing .gitignore\n\nWe have ATTEMPTED to convert your app to be in a format that electron-forge understands.\n\nThanks for using \"electron-forge\"!!!\n使用 Forge 的 make 命令来创建可分发的应用程序：
npm run make\n\n> my-electron-app@1.0.0 make /my-electron-app\n> electron-forge make\n\n✔ Checking your system\n✔ Resolving Forge Config\nWe need to package your application before we can make it\n✔ Preparing to Package Application for arch: x64\n✔ Preparing native dependencies\n✔ Packaging Application\nMaking for the following targets: zip\n✔ Making for target: zip - On platform: darwin - For arch: x64\nElectron Forge creates the out folder where your package will be located:
// Example for macOS\nout/\n├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip\n├── ...\n└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app\n请确认你所使用的文档与你的 Electron 版本匹配。 版本号应该是页面URL的一部分。 如果没有，你可能正在使用开发版本分支里的文档，这个分支可能包含了一些与你的 Electron 版本不兼容的 API。 如果想要访问旧版本的文档，你可以浏览标签： 通过在 GitHub 中打开下拉菜单“Switch branches/tags”中选择与你的版本匹配的分支。
\n有些问题经常被问到。 在新建问题之前请先查看：
\n\n这些独立教程扩展了上面指南中所讨论的主题。
\n这些指南是为希望修改 Electron 自身的人准备的。 有关使用 Electron 来开发应用程序的指南，请参见/docs/README.md。
\nWindows 和 macOS 分别通过打开跳转列表和dock菜单使应用程序能够快速的访问最近打开的文档列表。
\nJumpList:
\n
应用 dock 菜单
\n
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\n\nconst fileName = 'recently-used.md'\nfs.writeFile(fileName, 'Lorem Ipsum', () => {\n app.addRecentDocument(path.join(__dirname, fileName))\n})\n若要增加一个文件到最近文件列表，你可以使用app.addRecentDocument API.
\nAfter launching the Electron application, right click the application icon. 在本指南中，本项是位于项目根目录下的 Markdown 文件： 您应该可以看到添加到最近文件列表中的 recently-used.md ：
若要清空最近文件列表，你可以使用app.clearRecentDocuments API. 在此指南中，一旦所有窗口都关闭，文件列表就会被清除。
\n若要在 Windows 上使用此功能，您的应用程序必须注册为这类文件的处理程序。 否则，文件将不会在跳转列表中出现。 你可以在 Application Registration 里找到所有关于注册事宜的说明。
\n当用户点击“跳转列表”上的一个文件时，系统会启动一个新的应用程序的实例 ，而文件的路径将作为一个命令行参数被传入这个实例。
\n您可以添加菜单项以访问和清除最近的文档，方法是在菜单模板中添加以下代码片段：
\n{\n \"submenu\":[\n {\n \"label\":\"Open Recent\",\n \"role\":\"recentdocuments\",\n \"submenu\":[\n {\n \"label\":\"Clear Recent\",\n \"role\":\"clearrecentdocuments\"\n }\n ]\n }\n ]\n}\n请确保在 'ready'事件后添加应用菜单而不是之前，否则菜单项将被禁用：
const { app, Menu } = require('electron')\n\nconst template = [\n // 这里是菜单模版\n]\nconst menu = Menu.buildFromTemplate(template)\n\napp.whenReady().then(() => {\n Menu.setApplicationMenu(menu)\n})\n
从 \"最近文档\" 菜单中请求文件时, 将为其发出 app 模块的 open-file 事件。
x Number - The x coordinate of the origin of the rectangle (must be an integer).y Number - The y coordinate of the origin of the rectangle (must be an integer).width Number - The width of the rectangle (must be an integer).height Number - The height of the rectangle (must be an integer).url String - HTTP Referrer URL.policy String - Can be default, unsafe-url, no-referrer-when-downgrade, no-referrer, origin, strict-origin-when-cross-origin, same-origin or strict-origin. See the Referrer-Policy spec for more details on the meaning of these values.读取(Read)-运算(Eval)-输出(Print)-循环(Loop) (REPL) 是一个简单的, 交互式的计算机编程环境，它采用单个用户输入(即单个表达式)，运算并返回结果给用户。
\nElectron 通过 --interactive 命令行参数将 Node.js repl 模块暴露出去。 假设你已将 electron 安装为本地项目依赖，则应能够使用下面的命令访问 REPL：
./node_modules/.bin/electron --interactive\n注意： electron --interactive 在 Windows 上不可用(详情请参阅electron/electron#5776)。
你可以使用开发者工具Console选项卡获取任意渲染器进程的REPL。 要了解更多，请阅读 Chrome 文档。
", "title": "交互式解释器 (REPL)", "description": "" }, "/docs/tutorial/represented-file": { "locale": "zh-CN", "slug": "represented-file", "href": "/docs/tutorial/represented-file", "crowdinFileId": "256243", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/represented-file.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "在 macOS 上，您可以为应用程序中的任何窗口设置一个代表文件。 代表文件的图标将显示在标题栏中，当用户 Command-单击 或 Control-单击，一个带有文件路径的弹出窗口将会显示。
\n\n注意：上面的屏幕截图是一个示例，其中此功能用于指示 Atom 文本编辑器中当前打开的文件。
\n
您还可以设置窗口的编辑状态，以便文件图标可以指示该窗口中的文档是否已修改。
\n要设置窗口的代表文件，您可以使用 BrowserWindow.setRepresentedFilename 和 BrowserWindow.setDocumentEdited API。
\nconst { app, BrowserWindow } = require('electron')\nconst os = require('os');\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n}\n\napp.whenReady().then(() => {\n const win = new BrowserWindow()\n\n win.setRepresentedFilename(os.homedir())\n win.setDocumentEdited(true)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n启动 Electron 应用程序后，在按下 Command 或 Control 键时单击标题。 You should see a popup with the represented file at the top. In this guide, this is the current user's home directory:
\n\nAllows access to simple encryption and decryption of strings for storage on the local machine.
\n
进程：主进程
\nThis module protects data stored on disk from being accessed by other applications or users with full disk access.
\nNote that on Mac, access to the system Keychain is required and these calls can block the current thread to collect user input. The same is true for Linux, if a password management tool is available.
\nsafeStorage 模块包含以下方法：
safeStorage.isEncryptionAvailable()Returns Boolean - Whether encryption is available.
On Linux, returns true if the secret key is available. On MacOS, returns true if Keychain is available. On Windows, returns true with no other preconditions.
\nsafeStorage.encryptString(plainText)plainText StringReturns Buffer - An array of bytes representing the encrypted string.
This function will throw an error if encryption fails.
\nsafeStorage.decryptString(encrypted)encrypted BufferReturns String - the decrypted string. Decrypts the encrypted buffer obtained with safeStorage.encryptString back into a string.
This function will throw an error if decryption fails.
", "title": "safeStorage", "description": "Allows access to simple encryption and decryption of strings for storage on the local machine." }, "/docs/tutorial/sandbox": { "locale": "zh-CN", "slug": "sandbox", "href": "/docs/tutorial/sandbox", "crowdinFileId": "256245", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/sandbox.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Chromium的一个关键安全特性是，进程可以在沙盒中执行。 沙盒通过限制对大多数系统资源的访问来减少恶意代码可能造成的伤害 — 沙盒化的进程只能自由使用CPU周期和内存。 为了执行需要额外权限的操作，沙盒处的进程通过专用通信渠道将任务下放给更大权限的进程。
\n在Chromium中，沙盒化应用于主进程以外的大多数进程。 其中包括渲染器进程，以及功能性进程，如音频服务、GPU 服务和网络服务。
\n查阅Chromium的 沙箱设计文档 了解更多信息。
\nElectron带有一个混合的沙盒环境，意味着沙盒化进程可以和有权限的进程一起运行。 默认情况下，渲染器进程未被沙盒化，但功能性进程是被沙盒化的。 注意，就像在Chromium中一样，主 (浏览器) 进程是有特权的且无法被沙盒化。
\n从历史上看，这种混合沙盒方法之所以成立，是因为在渲染器中提供Node.js对于应用开发人员来说是一个非常强大的工具。 不幸的是，这一特性同时也是一个巨大的安全漏洞。
\n从理论上讲，对于只显示可信代码的桌面应用程序来说，未沙盒化的渲染器不是问题，但它们使 Electron 在显示不受信任的 Web 内容时的安全性低于 Chromium。 然而，即使据称可信的代码也可能是危险的 — 在远程加载的网站上有无数恶意行为者可以使用的攻击途径。稍微举几个例子：从跨站脚本到内容注入再到中间人攻击。 因此，我们建议在大多数非常谨慎的情况下启用渲染器沙盒化。
\n\nNote that there is an active discussion in the issue tracker to enable renderer sandboxing by default. See #28466) for details.
\n在 Electron 中沙盒进程 大部分地 表现都与 Chromium 差不多， 但因为介面是 Node.js 的关系 Electron 有一些额外的概念需要考虑。
\n当 Electron 中的渲染器进程被沙盒化时，它们的行为与常规 Chrome 渲染器一样。 一个沙盒化的渲染器不会有一个 Node.js 环境。
\n\n因此，在沙盒中，渲染器进程只能透过 进程间通讯 ( inter-process communication, IPC ) 委派任务给主进程的方式， 来执行需权限的任务 ( 例如：操作档案系统，改变作业系统 或 生成子进程 ) 。
\nIn order to allow renderer processes to communicate with the main process, preload scripts attached to sandboxed renderers will still have a polyfilled subset of Node.js APIs available. A require function similar to Node's require module is exposed, but can only import a subset of Electron and Node's built-in modules:
In addition, the preload script also polyfills certain Node.js primitives as globals:
\nBufferprocessclearImmediatesetImmediateBecause the require function is a polyfill with limited functionality, you will not be able to use CommonJS modules to separate your preload script into multiple files. If you need to split your preload code, use a bundler such as webpack or Parcel.
Note that because the environment presented to the preload script is substantially more privileged than that of a sandboxed renderer, it is still possible to leak privileged APIs to untrusted code running in the renderer process unless contextIsolation is enabled.
In Electron, renderer sandboxing can be enabled on a per-process basis with the sandbox: true preference in the BrowserWindow constructor.
// main.js\napp.whenReady().then(() => {\n const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n })\n win.loadURL('https://google.com')\n})\nIf you want to force sandboxing for all renderers, you can also use the app.enableSandbox API. Note that this API has to be called before the app's ready event.
// main.js\napp.enableSandbox()\napp.whenReady().then(() => {\n // no need to pass `sandbox: true` since `app.enableSandbox()` was called.\n const win = new BrowserWindow()\n win.loadURL('https://google.com')\n})\nYou can also disable Chromium's sandbox entirely with the --no-sandbox CLI flag, which will disable the sandbox for all processes (including utility processes). We highly recommend that you only use this flag for testing purposes, and never in production.
Note that the sandbox: true option will still disable the renderer's Node.js environment.
Rendering untrusted content in Electron is still somewhat uncharted territory, though some apps are finding success (e.g. Beaker Browser). Our goal is to get as close to Chrome as we can in terms of the security of sandboxed content, but ultimately we will always be behind due to a few fundamental issues:
\nWhile we make our best effort to backport Chromium security fixes to older versions of Electron, we do not make a guarantee that every fix will be backported. Your best chance at staying secure is to be on the latest stable version of Electron.
", "title": "进程沙盒化", "description": "" }, "/docs/api/screen": { "locale": "zh-CN", "slug": "screen", "href": "/docs/api/screen", "crowdinFileId": "256361", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/screen.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n检索有关屏幕大小、显示器、光标位置等的信息。
\n
进程：主进程
\n在 app 模块 emitted ready 事件之前，您不能使用此模块。
screen是一个EventEmitter.
Note: In the renderer / DevTools, window.screen is a reserved DOM property, so writing let { screen } = require('electron') will not work.
创建填充整个屏幕的窗口的示例:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\napp.whenReady().then(() => {\n const { width, height } = screen.getPrimaryDisplay().workAreaSize\n win = new BrowserWindow({ width, height })\n win.loadURL('https://github.com')\n})\n另一个在外部显示器中创建窗口的例子
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n const displays = screen.getAllDisplays()\n const externalDisplay = displays.find((display) => {\n return display.bounds.x !== 0 || display.bounds.y !== 0\n })\n\n if (externalDisplay) {\n win = new BrowserWindow({\n x: externalDisplay.bounds.x + 50,\n y: externalDisplay.bounds.y + 50\n })\n win.loadURL('https://github.com')\n }\n})\nscreen模块触发以下事件:
返回:
\nevent EventnewDisplay Display当新的窗口newDisplay被添加的时候触发。
返回:
\nevent EventoldDisplay Display当旧的窗口oldDisplay被移除的时候触发。
返回:
\nevent Eventdisplay DisplaychangedMetrics String[]当display中的一个或多个值发生改变时发出。 changedMetrics是描述更改信息的字符串数组。 可能改变的值有bounds, workArea, scaleFactor 和 rotation.
screen模块有以下方法:
screen.getCursorScreenPoint()返回 Point
当前鼠标的绝对位置。
\nNote: The return value is a DIP point, not a screen physical point.
\nscreen.getPrimaryDisplay()返回主窗口Display
screen.getAllDisplays()返回一个窗口数组Display[]，表示当前可用的窗口。
screen.getDisplayNearestPoint(point)point Point返回离指定点最近的一个窗口Display
screen.getDisplayMatching(rect)rect Rectangle返回离指定的图形最密切相交一个窗口Display
screen.screenToDipPoint(point) Windowspoint Point返回 Point
Converts a screen physical point to a screen DIP point. The DPI scale is performed relative to the display containing the physical point.
\nscreen.dipToScreenPoint(point) Windowspoint Point返回 Point
Converts a screen DIP point to a screen physical point. The DPI scale is performed relative to the display containing the DIP point.
\nscreen.screenToDipRect(window, rect) Windowswindow BrowserWindow | nullrect Rectangle返回 Rectangle
Converts a screen physical rect to a screen DIP rect. The DPI scale is performed relative to the display nearest to window. If window is null, scaling will be performed to the display nearest to rect.
screen.dipToScreenRect(window, rect) Windowswindow BrowserWindow | nullrect Rectangle返回 Rectangle
Converts a screen DIP rect to a screen physical rect. The DPI scale is performed relative to the display nearest to window. If window is null, scaling will be performed to the display nearest to rect.
label String (optional) - The text to appear in this item.icon NativeImage (optional) - The image to appear in this item.Web开发人员通畅享有浏览器强大的网络安全特性，而自己的代码风险相对较小。 我们的网站在沙盒中被赋予了有限的权力，我们相信我们的用户享受到的是一个由大型工程师团队打造的浏览器，它能够快速应对新发现的安全威胁。
\n当使用 Electron 时，很重要的一点是要理解 Electron 不是一个 Web 浏览器。 它允许您使用熟悉的 Web 技术构建功能丰富的桌面应用程序，但是您的代码具有更强大的功能。 JavaScript 可以访问文件系统，用户 shell 等。 这允许您构建更高质量的本机应用程序，但是内在的安全风险会随着授予您的代码的额外权力而增加。
\n考虑到这一点，请注意，展示任意来自不受信任源的内容都将会带来严重的安全风险，而这种风险Electron也没打算处理。 事实上，最流行的 Electron 应用程序(Atom，Slack，Visual Studio Code 等) 主要显示本地内容(即使有远程内容也是无 Node 的、受信任的、安全的内容) - 如果您的应用程序要运行在线的源代码，那么您需要确保源代码不是恶意的。
\n有关如何正确上报 Electron 漏洞的信息，参阅 SECURITY.md
\nElectron keeps up to date with alternating Chromium releases. 欲了解更多信息，请查看 Electron Release Cadence blog post。
\n需要牢记的是，你的 Electron 程序安全性除了依赖于整个框架基础（Chromium、Node.js）、Electron 本身和所有相关 NPM 库的安全性，还依赖于你自己的代码安全性。 因此，你有责任遵循下列安全守则：
\n使用最新版的 Electron 框架搭建你的程序。你最终发行的产品中会包含 Electron、Chromium 共享库和 Node.js 的组件。 这些组件存在的安全问题也可能影响你的程序安全性。 你可以通过更新Electron到最新版本来确保像是nodeIntegration绕过攻击一类的严重漏洞已经被修复因而不会影响到你的程序。 请参阅“使用当前版本的Electron”以获取更多信息。
\n评估你的依赖项目NPM提供了五百万可重用的软件包，而你应当承担起选择可信任的第三方库。 如果你使用了受已知漏洞的过时的库，或是依赖于维护的很糟糕的代码，你的程序安全就可能面临威胁。
\n遵循安全编码实践你的代码是你的程序安全的第一道防线。 一般的网络漏洞，例如跨站脚本攻击(Cross-Site Scripting, XSS)，对Electron将造成更大的影响，因此非常建议你遵循安全软件开发最佳实践并进行安全性测试。
\n每当你从不被信任的来源(如一个远程服务器)获取代码并在本地执行，其中就存在安全性问题。 例如在默认的 BrowserWindow中显示一个远程网站. 如果攻击者以某种方式设法改变所述内容 (通过直接攻击源或者通过在应用和实际目的地之间进行攻击) ，他们将能够在用户的机器上执行本地代码。
\n\n⚠️无论如何，在启用Node.js集成的情况下，你都不该加载并执行远程代码。 相反，只使用本地文件（和您的应用打包在一起）来执行Node.js代码 如果你想要显示远程内容，请使用
\n<webview>Tag或者BrowserView，并确保禁用nodeIntegration并启用contextIsolation
从Electron 2.0版本开始，开发者将会在开发者控制台看到打印的警告和建议。 这些警告仅在可执行文件名为 Electron 时才会为开发者显示。
\n你可以通过在process.env 或 window对象上配置ELECTRON_ENABLE_SECURITY_WARNINGS 或ELECTRON_DISABLE_SECURITY_WARNINGS来强制开启或关闭这些警告。
为加强程序安全性，你至少应当遵循下列规则：
\nses.setPermissionRequestHandler().webSecurityContent-Security-Policy并设置限制规则(如：script-src 'self')allowRunningInsecureContent 为 true.enableBlinkFeatures<webview>：不要使用 allowpopups <webview>：验证选项与参数openExternal如果你想要自动检测错误的配置或是不安全的模式，可以使用electronegativity 关于在使用Electron进行应用程序开发中的潜在薄弱点或者bug，您可以参考开发者与审核人员指南
\n任何不属于你的应用的资源都应该使用像HTTPS这样的安全协议来加载。 换言之， 不要使用不安全的协议 （如 HTTP）。 同理，我们建议使用WSS，避免使用WS，建议使用FTPS ，避免使用FTP，等等诸如此类的协议。
HTTPS 有三个主要好处：
1) 它对远程服务器进行身份验证, 确保您的应用程序连接到正确的主机而不是模仿器。 2) 确保数据完整性, 断言数据在应用程序和主机之间传输时未被修改。 3) 它对用户和目标主机之间的通信进行加密, 从而更难窃听应用程序和主机之间发送的信息。
\n// 不推荐\nbrowserWindow.loadURL ('http://example.com')\n// 推荐 \nbrowserWindow.loadURL ('https://example.com')\n<!-- 不推荐 -->\n<script crossorigin src=\"http://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"http://example.com/style.css\">\n\n<!-- 推荐 -->\n<script crossorigin src=\"https://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"https://example.com/style.css\">\nThis recommendation is the default behavior in Electron since 5.0.0.
\n加载远程内容时，不论使用的是哪一种渲染器（BrowserWindow，BrowserView 或者 <webview>），最重要的就是绝对不要启用 Node.js 集成。 其目的是限制您授予远程内容的权限, 从而使攻击者在您的网站上执行 JavaScript 时更难伤害您的用户。
在此之后，你可以为指定的主机授予附加权限。 举例来说，如果你正在打开一个指向 https://example.com/ 的 BrowserWindow，那么你可以给他刚刚好足够的权限，但是绝对不要超出这个范围。
如果攻击者跳过渲染进程并在用户电脑上执行恶意代码，那么这种跨站脚本(XSS) 攻击的危害是非常大的。 跨站脚本攻击很常见，通常情况下，威力仅限于执行代码的网站。 禁用Node.js集成有助于防止XSS攻击升级为“远程代码执行” (RCE) 攻击。
\n// 不推荐\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n nodeIntegration: true,\n nodeIntegrationInWorker: true\n }\n})\n\nmainWindow.loadURL('https://example.com')\n// 推荐\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n preload: path.join(app.getAppPath(), 'preload.js')\n }\n})\n\nmainWindow.loadURL('https://example.com')\n<!-- 不推荐 -->\n<webview nodeIntegration src=\"page.html\"></webview>\n\n<!-- 推荐 -->\n<webview src=\"page.html\"></webview>\n当禁用Node.js集成时，你依然可以暴露API给你的站点以使用Node.js的模块功能或特性。 预加载脚本依然可以使用require等Node.js特性， 以使开发者可以暴露自定义API给远程加载内容。
在下面的预加载脚本例子中，后加载的网站内容可以使用window.readConfig()方法，但不能使用Node.js特性。
const { readFileSync } = require('fs')\n\nwindow.readConfig = function () {\n const data = readFileSync('./config.json')\n return data\n}\n上下文隔离是Electron的一个特性，它允许开发者在预加载脚本里运行代码，里面包含Electron API和专用的JavaScript上下文。 实际上，这意味全局对象如 Array.prototype.push 或 JSON.parse等无法被渲染进程里的运行脚本修改。
Electron使用了和Chromium相同的Content Scripts技术来开启这个行为。
\n即便使用了 nodeIntegration: false, 要实现真正的强隔离并且防止使用 Node.js 的功能， contextIsolation 也 必须 开启.
For more information on what contextIsolation is and how to enable it please see our dedicated Context Isolation document.
Sandboxing is a Chromium feature that uses the operating system to significantly limit what renderer processes have access to. You should enable the sandbox in all renderers. Loading, reading or processing any untrusted content in an unsandboxed process, including the main process, is not advised.
\nWhen creating a window, pass the sandbox: true option in webPreferences:
const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n})\n当你使用Chromes时，也许见过这种许可请求：每当网站尝试使用某个特性时，就会弹出让用户手动确认(如网站通知)
\n此API基于Chromium permissions API，并已实现对应的许可类型。
\n默认情况下，Electron将自动批准所有的许可请求，除非开发者手动配置一个自定义处理函数。 尽管默认如此，有安全意识的开发者可能希望默认反着来。
\nconst { session } = require('electron')\n\nsession\n .fromPartition('some-partition')\n .setPermissionRequestHandler((webContents, permission, callback) => {\n const url = webContents.getURL()\n\n if (permission === 'notifications') {\n // 通过许可请求\n callback(true)\n }\n\n // Verify URL\n if (!url.startsWith('https://example.com/')) {\n // 拒绝许可请求\n return callback(false)\n }\n })\nElectron的默认值即是建议值。
\n在渲染进程（BrowserWindow、BrowserView 和 <webview>）中禁用 webSecurity 将导致至关重要的安全性功能被关闭。
不要在生产环境中禁用webSecurity。
禁用 webSecurity 将会禁止同源策略并且将 allowRunningInsecureContent 属性置 true。 换句话说，这将使得来自其他站点的非安全代码被执行。
// 不推荐\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n webSecurity: false\n }\n})\n// 推荐\nconst mainWindow = new BrowserWindow()\n<!-- 不推荐 -->\n<webview disablewebsecurity src=\"page.html\"></webview>\n\n<!-- 推荐 -->\n<webview src=\"page.html\"></webview>\n内容安全策略(CSP) 是应对跨站脚本攻击和数据注入攻击的又一层保护措施。 我们建议任何载入到Electron的站点都要开启。
\nCSP允许Electron通过服务端内容对指定页面的资源加载进行约束与控制。 如果你定义https://example.com这个源，所属这个源的脚本都允许被加载，反之https://evil.attacker.com不会被允许加载运行。 对于提升你的应用安全性，设置CSP是个很方便的办法。
下面的CSP设置使得Electron只能执行自身站点和来自apis.example.com的脚本。
// 不推荐\nContent-Security-Policy: '*'\n\n// 推荐\nContent-Security-Policy: script-src 'self' https://apis.example.com\nElectron 会处理 Content-Security-Policy HTTP 标头，它可以在 webRequest.onHeadersReceived 中进行设置：
const { session } = require('electron')\n\nsession.defaultSession.webRequest.onHeadersReceived((details, callback) => {\n callback({\n responseHeaders: {\n ...details.responseHeaders,\n 'Content-Security-Policy': ['default-src \\'none\\'']\n }\n })\n})\nCSP的首选传递机制是HTTP报头，但是在使用file://协议加载资源时，不可能使用此方法。 在某些用例下, 例如使用file://协议时, 在页面的<meta>的标签中设置CSP是非常有用的.
<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'\">\nallowRunningInsecureContent为trueElectron的默认值即是建议值。
\n默认情况下，Electron不允许网站在HTTPS中加载或执行非安全源(HTTP) 中的脚本代码、CSS或插件。 将allowRunningInsecureContent属性设为true将禁用这种保护。
当网站的初始内容通过HTTPS加载并尝试在子请求中加载HTTP的资源时，这被称为\"混合内容\"。
通过HTTPS加载会将该资源进行加密传输，以保证其真实性和完整性。 参看只显示安全内容这节以获得更多信息。
// 不推荐\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n allowRunningInsecureContent: true\n }\n})\n// 推荐\nconst mainWindow = new BrowserWindow({})\nElectron的默认值即是建议值。
\nElectron 的熟练用户可以通过 experimentalFeatures 属性来启用 Chromium 实验性功能。
如名称所示，实验性功能是实验性的，尚未对所有 Chromium 用户启用。 此外，它们对整个 Electron 的影响很可能没有经过测试。
\n尽管存在合理的使用场景，但是除非你知道你自己在干什么，否则你不应该开启这个属性。
\n// 不推荐\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n experimentalFeatures: true\n }\n})\n// 推荐\nconst mainWindow = new BrowserWindow({})\nenableBlinkFeaturesElectron的默认值即是建议值。
\nBlink是Chromium里的渲染引擎名称。 就像experimentalFeatures一样，enableBlinkFeatures属性将使开发者启用被默认禁用的特性。
通常来说，某个特性默认不被开启肯定有其合理的原因。 针对特定特性的合理使用场景是存在的。 作为开发者，你应该非常明白你为何要开启它，有什么后果，以及对你应用安全性的影响。 在任何情况下都不应该推测性的开启特性。
\n// 不推荐\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n enableBlinkFeatures: 'ExecCommandInJavaScript'\n }\n})\n// 推荐\nconst mainWindow = new BrowserWindow()\nallowpopupsElectron的默认值即是建议值。
\n如果您正在使用 <webview> ，您可能需要页面和脚本加载进您的 <webview> 标签以打开新窗口。 开启allowpopups属性将使得BrowserWindows可以通过window.open()方法创建。 否则， <webview> 标签内不允许创建新窗口。
如果你不需要弹窗，最好使用默认值以关闭新BrowserWindows的创建。 以下是最低的权限要求原则：若非必要，不要再网站中创建新窗口。
<!-- 不推荐 -->\n<webview allowpopups src=\"page.html\"></webview>\n\n<!-- 推荐 -->\n<webview src=\"page.html\"></webview>\n通过渲染进程创建的WebView是不开启Node.js集成的，且也不能由自身开启。 但是，WebView可以通过其webPreferences属性创建一个独立的渲染进程。
通过控制主进程中创建新的<webview>，并确认其webPreferences没有禁用安全相关特性是个不错的办法。
由于 <webview> 存在在DOM中，因此即使Node继承被禁用，它也可以通过运行在您的 网站上的脚本创建它们。
Electron 可以让开发者关闭各种控制渲染进程的安全特性。 通常情况下，开发者并不需要关闭他们中的任何一种 - 因此你不应该允许创建不同配置的<webview>标签
在 <webview>标签生效前，Electron将产生一个will-attach-webview事件到webContents中。 利用这个事件来阻止可能含有不安全选项的 webViews 创建。
app.on('web-contents-created', (event, contents) => {\n contents.on('will-attach-webview', (event, webPreferences, params) => {\n // Strip away preload scripts if unused or verify their location is legitimate\n delete webPreferences.preload\n delete webPreferences.preloadURL\n\n // Disable Node.js integration\n webPreferences.nodeIntegration = false\n\n // Verify URL being loaded\n if (!params.src.startsWith('https://example.com/')) {\n event.preventDefault()\n }\n })\n})\n不过，这个清单只是将风险降低到最低限度，但没有将其消除。 如果您的目标是展示一个网站，浏览器将是一个更安全的选择。
\nIf your app has no need to navigate or only needs to navigate to known pages, it is a good idea to limit navigation outright to that known scope, disallowing any other kinds of navigation.
\nNavigation is a common attack vector. If an attacker can convince your app to navigate away from its current page, they can possibly force your app to open web sites on the Internet. Even if your webContents are configured to be more secure (like having nodeIntegration disabled or contextIsolation enabled), getting your app to open a random web site will make the work of exploiting your app a lot easier.
A common attack pattern is that the attacker convinces your app's users to interact with the app in such a way that it navigates to one of the attacker's pages. This is usually done via links, plugins, or other user-generated content.
\n如果您的应用不需要导航，您可以在 will-navigate 处理器中调用 event.preventDefault()。 If you know which pages your app might navigate to, check the URL in the event handler and only let navigation occur if it matches the URLs you're expecting.
We recommend that you use Node's parser for URLs. 简单的字符串比较有时会出错 - startsWith('https://example.com')测试会让https://example.com.attacker.com通过.
const URL = require('url').URL\n\napp.on('web-contents-created', (event, contents) => {\n contents.on('will-navigate', (event, navigationUrl) => {\n const parsedUrl = new URL(navigationUrl)\n\n if (parsedUrl.origin !== 'https://example.com') {\n event.preventDefault()\n }\n })\n})\nIf you have a known set of windows, it's a good idea to limit the creation of additional windows in your app.
\nMuch like navigation, the creation of new webContents is a common attack vector. Attackers attempt to convince your app to create new windows, frames, or other renderer processes with more privileges than they had before; or with pages opened that they couldn't open before.
If you have no need to create windows in addition to the ones you know you'll need to create, disabling the creation buys you a little bit of extra security at no cost. This is commonly the case for apps that open one BrowserWindow and do not need to open an arbitrary number of additional windows at runtime.
webContents将会在新窗口创建前传递给 打开窗口的处理函数。 The handler will receive, amongst other parameters, the url the window was requested to open and the options used to create it. We recommend that you register a handler to monitor the creation of windows, and deny any unexpected window creation.
const { shell } = require('electron')\n\napp.on('web-contents-created', (event, contents) => {\n contents.setWindowOpenHandler(({ url }) => {\n // In this example, we'll ask the operating system\n // to open this event's url in the default browser.\n //\n // See the following item for considerations regarding what\n // URLs should be allowed through to shell.openExternal.\n if (isSafeForExternalOpen(url)) {\n setImmediate(() => {\n shell.openExternal(url)\n })\n }\n\n return { action: 'deny' }\n })\n})\nopenExternal 打开含有不可信任内容Shell 的 openExternal 允许使用桌面的原生工具打开指定的协议 URI。 例如，在 macOS 上，此功能与 open 终端命令实用程序类似，将基于 URI 和文件类型关联打开特定的应用程序。
错误使用 openExternal 会危害用户的主机 当 openExternal 使用内容不受信任时，它可以用来执行任意命令。
// Bad\nconst { shell } = require('electron')\nshell.openExternal(USER_CONTROLLED_DATA_HERE)\n// Good\nconst { shell } = require('electron')\nshell.openExternal('https://example.com/index.html')\n你应该尽可能使用最新版本的 Electron。 每当发布新的主要版本时，你应该尝试尽快更新您的应用。
\n一个使用 Electron、Chromium 和 Node.js 的旧版本构建的应用程序比使用这些组件的最新版本的应用程序更容易成为目标。 Generally speaking, security issues and exploits for older versions of Chromium and Node.js are more widely available.
\nChromium 和 Node.js 都是数千名有才华的开发者建造的令人印象深刻的工程。 鉴于他们受欢迎的程度，他们的安全性都经过专业的安全研究人员仔细的测试和分析。 其中许多研究人员负责任地披露漏洞，这通常意味着研究人员会给 Chromium 和 Node.js 一些时间来修复问题，然后再发布它们。 如果你的应用程序运行的是 Electron 的最新版本 (包括 Chromium 和 Node.js)，你的应用程序将更加安全，因为潜在的安全问题并不广为人知。
", "title": "安全性，原生能力和你的责任", "description": "⚠️无论如何，在启用Node.js集成的情况下，你都不该加载并执行远程代码。 相反，只使用本地文件（和您的应用打包在一起）来执行Node.js代码 如果你想要显示远程内容，请使用label String (optional) - The text to appear in this segment.icon NativeImage (optional) - The image to appear in this segment.enabled Boolean (optional) - Whether this segment is selectable. Default: true.portId String - Unique identifier for the port.portName String - Name of the port.displayName String - A string suitable for display to the user for describing this device.vendorId String - Optional USB vendor ID.productId String - Optional USB product ID.serialNumber String - The USB device serial number.usbDriverName String (optional) - Represents a single serial port on macOS can be enumerated by multiple drivers.deviceInstanceId String (optional) - A stable identifier on Windows that can be used for device permissions.scriptUrl String - The full URL to the script that this service worker runsscope String - The base URL that this service worker is active for.renderProcessId Number - The virtual ID of the process that this service worker is running in. This is not an OS level PID. This aligns with the ID set used for webContents.getProcessId().\n\n从活跃的 service worker 会话中查询和接收事件
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
通过Session的serviceWorkers属性来访问ServiceWorkers的实例
例如：
\nconst { session } = require('electron')\n\n// Get all service workers.\nconsole.log(session.defaultSession.serviceWorkers.getAllRunning())\n\n// Handle logs and get service worker info\nsession.defaultSession.serviceWorkers.on('console-message', (event, messageDetails) => {\n console.log(\n 'Got service worker message',\n messageDetails,\n 'from',\n session.defaultSession.serviceWorkers.getFromVersionID(messageDetails.versionId)\n )\n})\nServiceWorkers实例中有下列事件：
返回:
\nevent EventmessageDetails Object - 有关控制台消息的信息message String - 实际控制台消息versionId Number - 发送消息日志的 service worker 的版本 IDsource String - 消息源的类型 可以是 javascript, xml, network, console-api, storage, app-cache, rendering, security, deprecation, worker, violation, intervention, recommendation 或 other.level Number - 日志等级，从 0 到 3 。 按顺序匹配 verbose, info, warning 和 error.sourceUrl String - 消息来源的URLlineNumber Number - 触发当前控制台消息的源代码行数当一个service worker记录日志到控制台的时候将自动触发此事件
\n返回:
\nevent Eventdetails Object - 有关 service worker 注册的信息scope String - 当前 service worker 所注册在的URL当一个service worker已经被注册完成的时候触发此事件。 注册完成分两种情况， 一个是调用navigator.serviceWorker.register('/sw.js')方法成功，另一个是当Chrome的扩展加载结束。
在ServiceWorkers实例对象中，有以下方法:
serviceWorkers.getAllRunning()返回 Record<Number, ServiceWorkerInfo> ， 一个 ServiceWorkerInfo 对象， 其中键是 service worker 的版本 ID ，值是 service worker 的信息。
serviceWorkers.getFromVersionID(versionId)versionId Number返回 ServiceWorkerInfo - service worker的相关信息
如果 service worker 不存在或者停止运行，此方法将抛出异常。
", "title": "ServiceWorkers", "description": "从活跃的 service worker 会话中查询和接收事件" }, "/docs/api/session": { "locale": "zh-CN", "slug": "session", "href": "/docs/api/session", "crowdinFileId": "256365", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/session.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n管理浏览器会话、cookie、缓存、代理设置等。
\n
进程：主进程
\nsession 模块可用于创建新的 session 对象。
您还可以通过使用 WebContents 的 session 属性或从 session 模块访问现有页面的 <0>session</0>。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nconst ses = win.webContents.session\nconsole.log(ses.getUserAgent())\nsession 模块具有以下方法:
session.fromPartition(partition[, options])partition Stringoptions Object (可选)cache Boolean - 是否可以使用缓存.Returns Session - 根据partition字符串产生的session实例。 当这里已存在一个Session具有相同的partition, 它将被返回; 否则一个新的Session实例将根据options被创建。
如果 partition 以 persist:开头, 该页面将使用持续的 session，并在所有页面生效，且使用同一个partition. 如果没有 persist: 前缀, 页面将使用 in-memory session. 如果没有设置partition，app 将返回默认的session。
要根据options创建Session，你需要确保Session的partition在之前从未被使用。 没有办法修改一个已存在的Session对象的options。
session 模块具有以下方法:
session.defaultSession一个Session对象，该应用程序的默认session对象。
\n\n获取和设置Session的属性。
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
你可以创建一个 Session对象在session模块中。
const { session } = require('electron')\nconst ses = session.fromPartition('persist:name')\nconsole.log(ses.getUserAgent())\n以下事件会在Session实例触发。
返回:
\nevent Eventitem DownloadItemwebContents WebContents当 Electron 刚要在webContents中下载item的时候触发。
调用event.preventDefault()方法，将会停止下载，并且在进程的next tick中，item将不再可用。
const { session } = require('electron')\nsession.defaultSession.on('will-download', (event, item, webContents) => {\n event.preventDefault()\n require('got')(item.getURL()).then((response) => {\n require('fs').writeFileSync('/somewhere', response.body)\n })\n})\n返回:
\nevent Eventextension 扩展插件在扩展插件加载完成后触发。 当一个扩展插件被添加到 \"enabled\" 的扩展插件集合内部时， 将自动触发 这包括：
\nSession.loadExtension 中被加载chrome.runtime.reload()).返回:
\nevent Eventextension 扩展插件当一个扩展插件被卸载后触发。 当 Session.removeExtension 被调用时也会触发。
返回:
\nevent Eventextension 扩展插件当一个扩展插件加载完成，同时所有必要的浏览器状态也初始化完毕，允许启动插件背景页面时， 将触发此事件。
\n返回:
\nevent EventpreconnectUrl String - 渲染器为预连接请求的 URLallowCredentials Boolean - True 代表着渲染器在请求一个包含 credentials 信息的链接 (详见spec)当渲染进程已经预链接到 URL 后将触发此事件, 通常用于 资源加载 提醒
\n返回:
\nevent EventlanguageCode String - 字典文件的语言代码当一个hunspell字典初始化成功时触发。 这个事件在文件被下载之后触发。
\n返回:
\nevent EventlanguageCode String - 字典文件的语言代码当 hunspell 字典文件开始下载时触发
\n返回:
\nevent EventlanguageCode String - 字典文件的语言代码当 hunspell 字典文件下载成功触发
\n返回:
\nevent EventlanguageCode String - 字典文件的语言代码当hunspell字典下载失败时触发。 如果需要详细信息，你应当查看网络日志并且检查下载请求。
\n返回:
\nevent Eventdetails ObjectdeviceList HIDDevice[]frame WebFrameMaincallback FunctiondeviceId String | null (optional)Emitted when a HID device needs to be selected when a call to navigator.hid.requestDevice is made. callback should be called with deviceId to be selected; passing no arguments to callback will cancel the request. Additionally, permissioning on navigator.hid can be further managed by using ses.setPermissionCheckHandler(handler) and ses.setDevicePermissionHandler(handler)`.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\n返回:
\nevent Eventdetails Objectdevice HIDDevice[]frame WebFrameMainEmitted when a new HID device becomes available. For example, when a new USB device is plugged in.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
返回:
\nevent Eventdetails Objectdevice HIDDevice[]frame WebFrameMainEmitted when a HID device has been removed. 比如， 当一个USB设备被移除时。
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
返回:
\nevent EventportList SerialPort[]webContents WebContentscallback FunctionportId String调用 navigator.serial.requestPort 并选择一系列端口时触发此事件。 callback 方法将在portId 被选中后调用, 给callback 方法一个空字符串参数将取消请求。 此外， navigator.serial 的许可权可以通过使用 ses.setPermissionCheckHandler(handler) 来设置 serial 权限。
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({\n width: 800,\n height: 600\n })\n win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {\n event.preventDefault()\n const selectedPort = portList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n if (!selectedPort) {\n callback('')\n } else {\n callback(selectedPort.portId)\n }\n })\n})\n返回:
\nevent Eventport SerialPortwebContents WebContents当 navigator.serial.requestPort 已经被调用时触发此事件，同时 如果新的串行端口可用则 select-serial-port 事件也将触发。 比如，当一个新的USB设备插入时将触发此事件。
返回:
\nevent Eventport SerialPortwebContents WebContents当 navigator.serial.requestPort 已经被调用时触发，同时如果串行端口已经被删除则触发 select-serial-port 事件。 比如， 当一个USB设备被移除时。
在Session实例对象中，有以下方法:
ses.getCacheSize()Returns Promise<Integer> - 当前 session 会话缓存大小，用 byte 字节作为单位。
ses.clearCache()Returns Promise<void> - 当缓存清除操作完成时可获取
清除session的HTTP缓存。
\nses.clearStorageData([options])options Object (可选)origin String - (可选项) 这个值应该按照 window.location.origin 的形式: 协议://主机名:端口方式设置。storages String - 要清除的存储类型，包含: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage. 如果没有指定storages，将会清除所有的storages类型quotas String[] - (可选项) 要清除的配额类型, 包含: temporary, persistent, syncable。 如果没有指定，将会清除所有的quotas。Returns Promise<void> - 当存储的数据已经被清理时可获得
ses.flushStorageData()写入任何未写入DOMStorage数据到磁盘.
\nses.setProxy(config)config Objectmode String (可选) - 代理模式。 可以是其中之一： direct, auto_detect, pac_script, fixed_servers 或 system。 如未指定，则根据其他选项自动判断direct 在直接模式下，所有连接都是直接创建的，无需任何代理。auto_detect 在auto_detect模式下，代理配置由 PAC 脚本决定，该脚本 可在 http://wpad/wpad.dat 下载。pac_script In pac_script mode the proxy configuration is determined by a PAC script that is retrieved from the URL specified in the pacScript. This is the default mode if pacScript is specified.fixed_servers In fixed_servers mode the proxy configuration is specified in proxyRules. This is the default mode if proxyRules is specified.system In system mode the proxy configuration is taken from the operating system. Note that the system mode is different from setting no proxy configuration. In the latter case, Electron falls back to the system settings only if no command-line options influence the proxy configuration.pacScript String (optional) - The URL associated with the PAC file.proxyRules String (optional) - Rules indicating which proxies to use.proxyBypassRules String (optional) - Rules indicating which URLs should bypass the proxy settings.Returns Promise<void> - Resolves when the proxy setting process is complete.
代理设置
\nWhen mode is unspecified, pacScript and proxyRules are provided together, the proxyRules option is ignored and pacScript configuration is applied.
You may need ses.closeAllConnections to close currently in flight connections to prevent pooled sockets using previous proxy from being reused by future requests.
proxyRules 要遵循以下规则:
proxyRules = schemeProxies[\";\"<schemeProxies>]\nschemeProxies = [<urlScheme>\"=\"]<proxyURIList>\nurlScheme = \"http\" | \"https\" | \"ftp\" | \"socks\"\nproxyURIList = <proxyURL>[\",\"<proxyURIList>]\nproxyURL = [<proxyScheme>\"://\"]<proxyHost>[\":\"<proxyPort>]\n例如：
\nhttp=foopy:80;ftp=foopy2 - Use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.foopy:80 - Use HTTP proxy foopy:80 for all URLs.foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing over to bar if foopy:80 is unavailable, and after that using no proxy.socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail over to the SOCKS5 proxy bar.com if foopy is unavailable.http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no proxy if foopy is unavailable.http=foopy;socks=foopy2 - 对于http URL，用foopy作为HTTP协议代理，而其它所有URL则用 socks4://foopy2 协议。proxyBypassRules是一个用逗号分隔的规则列表, 如下所述:
[ URL_SCHEME \"://\" ] HOSTNAME_PATTERN [ \":\" <port> ]
与 HOSTNAME_PATTERN 模式匹配的所有主机名。
\n例如: \"foobar.com\", \"foobar.com\", \".foobar.com\", \"foobar.com:99\", \"https://x..y.com:99\"
\n\".\" HOSTNAME_SUFFIX_PATTERN [ \":\" PORT ]
匹配特定域名后缀。
\n例如： \".google.com\", \".com\", \"http://.google.com\"
\n[ SCHEME \"://\" ] IP_LITERAL [ \":\" PORT ]
匹配 IP 地址文本的 url。
\n例如: \"127.0.1\", \"[0:0::1]\", \"[::1]\", \"http://[::1]:99\"
\nIP_LITERAL \"/\" PREFIX_LENGTH_IN_BITS
匹配任何在给定IP范围内失败的URL。 IP范围使用指定的CIDR。
\n例如: \"192.168.1.1/16\", \"fefe:13::abc/33\".
\n<local>
匹配本地地址。 The meaning of <local> is whether the host matches one of: \"127.0.0.1\", \"::1\", \"localhost\".
ses.resolveProxy(url)url URLReturns Promise<String> - Resolves with the proxy information for url.
ses.forceReloadProxyConfig()Returns Promise<void> - Resolves when the all internal states of proxy service is reset and the latest proxy configuration is reapplied if it's already available. The pac script will be fetched from pacScript again if the proxy mode is pac_script.
ses.setDownloadPath(path)path String - The download location.Sets download saving directory. By default, the download directory will be the Downloads under the respective app folder.
ses.enableNetworkEmulation(options)选项 对象offline Boolean (optional) - Whether to emulate network outage. Defaults to false.latency Double (optional) - RTT in ms. Defaults to 0 which will disable latency throttling.downloadThroughput Double (optional) - Download rate in Bps. Defaults to 0 which will disable download throttling.uploadThroughput Double (optional) - Upload rate in Bps. Defaults to 0 which will disable upload throttling.通过指定的配置为 session 模拟网络。
// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.\nwindow.webContents.session.enableNetworkEmulation({\n latency: 500,\n downloadThroughput: 6400,\n uploadThroughput: 6400\n})\n\n// To emulate a network outage.\nwindow.webContents.session.enableNetworkEmulation({ offline: true })\nses.preconnect(options)选项 对象url String - URL for preconnect. Only the origin is relevant for opening the socket.numSockets Number (optional) - number of sockets to preconnect. Must be between 1 and 6. Defaults to 1.Preconnects the given number of sockets to an origin.
\nses.closeAllConnections()Returns Promise<void> - Resolves when all connections are closed.
Note: It will terminate / fail all requests currently in flight.
\nses.disableNetworkEmulation()Disables any network emulation already active for the session. Resets to the original network configuration.
ses.setCertificateVerifyProc(proc)proc Function | nullrequest Objecthostname Stringcertificate 证书validatedCertificate CertificateverificationResult String - chromium证书验证结果errorCode Integer - 错误代码callback FunctionverificationResult Integer - Value can be one of certificate error codes from here. Apart from the certificate error codes, the following special codes can be used.-0 - 表示成功并禁用证书透明度验证-2 - 表示失败-3 - 使用chromium的验证结果每当一个服务器证书请求验证，proc 将被这样 proc(request, callback) 调用，为 session 设置证书验证过程。 回调函数 callback(0) 接受证书，callback(-2) 驳回证书。
调用 setCertificateVerifyProc（null）将恢复为默认证书验证过程。
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.webContents.session.setCertificateVerifyProc((request, callback) => {\n const { hostname } = request\n if (hostname === 'github.com') {\n callback(0)\n } else {\n callback(-2)\n }\n})\n\n\nNOTE: The result of this procedure is cached by the network service.
\n
ses.setPermissionRequestHandler(handler)handler Function | nullwebContents WebContents - 请求权限的WebContents。 Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.permission String - The type of requested permission.clipboard-read - Request access to read from the clipboard.media - Request access to media devices such as camera, microphone and speakers.display-capture - Request access to capture the screen.mediaKeySystem - Request access to DRM protected content.geolocation - Request access to user's current location.notifications - Request notification creation and the ability to display them in the user's system tray.midi - Request MIDI access in the webmidi API.midiSysex - Request the use of system exclusive messages in the webmidi API.pointerLock - Request to directly interpret mouse movements as an input method. Click here to know more.fullscreen - Request for the app to enter fullscreen mode.openExternal - Request to open links in external applications.unknown - An unrecognized permission requestcallback FunctionpermissionGranted Boolean - 允许或拒绝该权限.details Object - Some properties are only available on certain permission types.externalURL String (optional) - The url of the openExternal request.mediaTypes String - The types of media access being requested, elements can be video or audiorequestingUrl String - The last URL the requesting frame loadedisMainFrame Boolean - Whether the frame making the request is the main frame设置可用于响应 session 的权限请求的处理程序。 调用 callback(true) 将允许该权限, 调用 callback(false) 将拒绝它。 若要清除处理程序, 请调用 setPermissionRequestHandler (null)。 Please note that you must also implement setPermissionCheckHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied.
const { session } = require('electron')\nsession.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {\n if (webContents.getURL() === 'some-host' && permission === 'notifications') {\n return callback(false) // denied.\n }\n\n callback(true)\n})\nses.setPermissionCheckHandler(handler)handler 函数\\webContents (WebContents | null) - WebContents checking the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin. 所有进行权限检查的跨源子帧将传递一个 null 的 webContents 对象给此处理程序，而某些其他权限检查（如 notifications 检查）将始终传递一个 null。 You should use embeddingOrigin and requestingOrigin to determine what origin the owning frame and the requesting frame are on respectively.permission String - Type of permission check. Valid values are midiSysex, notifications, geolocation, media,mediaKeySystem,midi, pointerLock, fullscreen, openExternal, hid, or serial.requestingOrigin String - The origin URL of the permission checkdetails Object - Some properties are only available on certain permission types.embeddingOrigin String (optional) - The origin of the frame embedding the frame that made the permission check. Only set for cross-origin sub frames making permission checks.securityOrigin String (optional) - The security origin of the media check.mediaType String (optional) - The type of media access being requested, can be video, audio or unknownrequestingUrl String (optional) - The last URL the requesting frame loaded. This is not provided for cross-origin sub frames making permission checks.isMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission checks for the session. Returning true will allow the permission and false will reject it. Please note that you must also implement setPermissionRequestHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied. To clear the handler, call setPermissionCheckHandler(null).
const { session } = require('electron')\nconst url = require('url')\nsession.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {\n return true // granted\n }\n\n return false // denied\n})\nses.setDevicePermissionHandler(handler)handler 函数\\details ObjectdeviceType String - The type of device that permission is being requested on, can be hid.origin String - The origin URL of the device permission check.device HIDDevice - the device that permission is being requested for.frame WebFrameMain - WebFrameMain checking the device permission.Sets the handler which can be used to respond to device permission checks for the session. Returning true will allow the device to be permitted and false will reject it. To clear the handler, call setDevicePermissionHandler(null). This handler can be used to provide default permissioning to devices without first calling for permission to devices (eg via navigator.hid.requestDevice). If this handler is not defined, the default device permissions as granted through device selection (eg via navigator.hid.requestDevice) will be used. Additionally, the default behavior of Electron is to store granted device permision through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nses.clearHostResolverCache()Returns Promise<void> - Resolves when the operation is complete.
清除主机解析程序的缓存。
\nses.allowNTLMCredentialsForDomains(domains)domains String - 一个逗号分隔的服务器列表, 用于收集已经启用身份验证的服务器。动态设置是否始终为 HTTP NTLM 发送凭据或协商身份验证。
\nconst { session } = require('electron')\n// 以 \"example.com\"、\"foobar.com\"、\"baz\" 结尾的 url 用于身份验证。\nsession.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')\n\n// 所有的 url 都可以用作身份验证\nsession.defaultSession.allowNTLMCredentialsForDomains('*')\nses.setUserAgent(userAgent[, acceptLanguages])userAgent StringacceptLanguages String (可选)覆盖当前会话的 userAgent 和 acceptLanguages.
acceptLanguages 必须是用逗号分隔的语言代码列表，例如 \"en-US,fr,de,ko,zh-CN,ja\".
这不会影响现有的WebContents, 并且每个WebContents都可以使用 webContents.setUserAgent重写会话范围的user agent。
ses.isPersistent()Returns Boolean - Whether or not this session is a persistent one. The default webContents session of a BrowserWindow is persistent. When creating a session from a partition, session prefixed with persist: will be persistent, while others will be temporary.
ses.getUserAgent()返回 String - 当前会话的 user agent.
ses.setSSLConfig(config)config ObjectminVersion String (可选) - 值可以是 tls1， tls1.1， tls1.2 或 tls1.3。 The minimum SSL version to allow when connecting to remote servers. 默认为tls1。maxVersion String (可选) - 可以是 tls1.2 或 tls1.3。 The maximum SSL version to allow when connecting to remote servers. 默认值为 tls1.3。disabledCipherSuites Integer - List of cipher suites which should be explicitly prevented from being used in addition to those disabled by the net built-in policy. Supported literal forms: 0xAABB, where AA is cipher_suite[0] and BB is cipher_suite[1], as defined in RFC 2246, Section 7.4.1.2. Unrecognized but parsable cipher suites in this form will not return an error. Ex: To disable TLS_RSA_WITH_RC4_128_MD5, specify 0x0004, while to disable TLS_ECDH_ECDSA_WITH_RC4_128_SHA, specify 0xC002. Note that TLSv1.3 ciphers cannot be disabled using this mechanism.Sets the SSL configuration for the session. All subsequent network requests will use the new configuration. Existing network connections (such as WebSocket connections) will not be terminated, but old sockets in the pool will not be reused for new connections.
\nses.getBlobData(identifier)identifier String - 有效的 UUID.Returns Promise<Buffer> - resolves with blob data.
ses.downloadURL(url)url StringInitiates a download of the resource at url. The API will generate a DownloadItem that can be accessed with the will-download event.
Note: This does not perform any security checks that relate to a page's origin, unlike webContents.downloadURL.
ses.createInterruptedDownload(options)选项 对象path String - 下载的绝对路径.urlChain String[] - 完整的 url 下载地址.mimeType String (可选)offset Integer - 下载的开始范围.length Integer - 下载的总长度。lastModified String (optional) - Last-Modified header value.eTag String (optional) - ETag header value.startTime Double (optional) - 下载的时间是从 UNIX 时代以来的秒数开始的。允许从上一个 Session 恢复 cancelled 或 interrupted 下载。 该 API 将生成一个 DownloadItem , 可使用 will-download 事件进行访问。 DownloadItem 将不具有与之关联的任何 WebContents, 并且初始状态将为 interrupted。 只有在 DownloadItem 上调用 resume API 时, 才会启动下载。
ses.clearAuthCache()Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.
ses.setPreloads(preloads)preloads String[] - 数组，该数组由所有需要进行预加载的脚本的绝对路径组成。Adds scripts that will be executed on ALL web contents that are associated with this session just before normal preload scripts run.
ses.getPreloads()返回 String[] 返回一个数组，这个数组由已经注册过的预加载脚本的路径组成。
ses.setSpellCheckerEnabled(enable)enable BooleanSets whether to enable the builtin spell checker.
\nses.isSpellCheckerEnabled()Returns Boolean - Whether the builtin spell checker is enabled.
ses.setSpellCheckerLanguages(languages)languages String[] - An array of language codes to enable the spellchecker for.The built in spellchecker does not automatically detect what language a user is typing in. In order for the spell checker to correctly check their words you must call this API with an array of language codes. You can get the list of supported language codes with the ses.availableSpellCheckerLanguages property.
Note: On macOS the OS spellchecker is used and will detect your language automatically. This API is a no-op on macOS.
\nses.getSpellCheckerLanguages()Returns String[] - An array of language codes the spellchecker is enabled for. If this list is empty the spellchecker will fallback to using en-US. By default on launch if this setting is an empty list Electron will try to populate this setting with the current OS locale. This setting is persisted across restarts.
Note: On macOS the OS spellchecker is used and has its own list of languages. This API is a no-op on macOS.
\nses.setSpellCheckerDictionaryDownloadURL(url)url String - A base URL for Electron to download hunspell dictionaries from.By default Electron will download hunspell dictionaries from the Chromium CDN. If you want to override this behavior you can use this API to point the dictionary downloader at your own hosted version of the hunspell dictionaries. We publish a hunspell_dictionaries.zip file with each release which contains the files you need to host here, the file server must be case insensitive you must upload each file twice, once with the case it has in the ZIP file and once with the filename as all lower case.
If the files present in hunspell_dictionaries.zip are available at https://example.com/dictionaries/language-code.bdic then you should call this api with ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Please note the trailing slash. The URL to the dictionaries is formed as ${url}${filename}.
Note: On macOS the OS spellchecker is used and therefore we do not download any dictionary files. This API is a no-op on macOS.
\nses.listWordsInSpellCheckerDictionary()Returns Promise<String[]> - An array of all words in app's custom dictionary. Resolves when the full dictionary is loaded from disk.
ses.addWordToSpellCheckerDictionary(word)word String - The word you want to add to the dictionaryReturns Boolean - Whether the word was successfully written to the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be written to the OS custom dictionary as well
\nses.removeWordFromSpellCheckerDictionary(word)word String - The word you want to remove from the dictionaryReturns Boolean - Whether the word was successfully removed from the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be removed from the OS custom dictionary as well
\nses.loadExtension(path[, options])path String - Path to a directory containing an unpacked Chrome extensionoptions Object (可选)allowFileAccess Boolean - Whether to allow the extension to read local files over file:// protocol and inject content scripts into file:// pages. This is required e.g. for loading devtools extensions on file:// URLs. 默认值为 false.Returns Promise<Extension> - resolves when the extension is loaded.
This method will raise an exception if the extension could not be loaded. If there are warnings when installing the extension (e.g. if the extension requests an API that Electron does not support) then they will be logged to the console.
\nNote that Electron does not support the full range of Chrome extensions APIs. See Supported Extensions APIs for more details on what is supported.
\nNote that in previous versions of Electron, extensions that were loaded would be remembered for future runs of the application. This is no longer the case: loadExtension must be called on every boot of your app if you want the extension to be loaded.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.on('ready', async () => {\n await session.defaultSession.loadExtension(\n path.join(__dirname, 'react-devtools'),\n // allowFileAccess is required to load the devtools extension on file:// URLs.\n { allowFileAccess: true }\n )\n // Note that in order to use the React DevTools extension, you'll need to\n // download and unzip a copy of the extension.\n})\nThis API does not support loading packed (.crx) extensions.
\n注意: 该 API 不能在 app 模块的 ready 事件之前调用.
Note: Loading extensions into in-memory (non-persistent) sessions is not supported and will throw an error.
\nses.removeExtension(extensionId)extensionId String - ID of extension to removeUnloads an extension.
\n注意: 该 API 不能在 app 模块的 ready 事件之前调用.
ses.getExtension(extensionId)extensionId String - ID of extension to queryReturns Extension | null - The loaded extension with the given ID.
注意: 该 API 不能在 app 模块的 ready 事件之前调用.
ses.getAllExtensions()Returns Extension[] - A list of all loaded extensions.
注意: 该 API 不能在 app 模块的 ready 事件之前调用.
ses.getStoragePath()A String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
以下属性在Session实例上可用：
ses.availableSpellCheckerLanguages 只读A String[] array which consists of all the known available spell checker languages. Providing a language code to the setSpellCheckerLanguages API that isn't in this array will result in an error.
ses.spellCheckerEnabledA Boolean indicating whether builtin spell checker is enabled.
ses.storagePath 只读A String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
ses.cookies 只读A Cookies object for this session.
ses.serviceWorkers 只读A ServiceWorkers object for this session.
ses.webRequest 只读A WebRequest object for this session.
ses.protocol 只读Session中使用Protocol对象
const { app, session } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const protocol = session.fromPartition('some-partition').protocol\n if (!protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })) {\n console.error('Failed to register protocol')\n }\n})\nses.netLog 只读A NetLog object for this session.
const { app, session } = require('electron')\n\napp.whenReady().then(async () => {\n const netLog = session.fromPartition('some-partition').netLog\n netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\n调试 symbols 让你能更好的调试 sessions. 它们有可执行的动态库的函数信息，并且提供信息来获得干净的调用堆栈. 一个 Symbol 服务器允许调试器自动加载正确的 symbols, 二进制文件 和 资源文件，不用再去强制用户下载巨大的调试文件. 服务器函数类似 Microsoft's symbol server，所以这些文档是可以使用的。
\n注意，因为公众版本的 Electron 构建是最优化的，调试不一定一直简单. 调试器将不会给显示出所有变量内容，并且因为内联，尾调用，和其它编译器优化，执行路径会看起来很怪异. 唯一的解决办法是搭建一个不优化的本地构建.
\nElectron 使用的官方 symbol 服务器地址为 https://symbols.electronjs.org. 你不能直接访问这个路径，必须将其添加到你的调试工具的 symbol 路径上. 在下面的例子中，使用了一个本地缓存目录来避免重复从服务器获取 PDB. 在你的电脑上使用一个恰当的缓存目录来代替 c:\\code\\symbols.
Windbg symbol 路径被配制为一个限制带星号字符的字符串. 要只使用 Electron 的 symbol 服务器, 将下列记录添加到你的 symbol 路径 (注意: 如果你愿意使用一个不同的地点来下载 symbols，你可以在你的电脑中使用任何可写的目录来代替 c:\\code\\symbols):
SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\n使用 Windbg 菜单或通过输入 .sympath 命令，在环境中设置一个 _NT_SYMBOL_PATH 字符串. 如果你也想从微软的 symbol 服务器获得 symbols ，你应当首先将它们先列出来:
SRV*c:\\code\\symbols\\*https://msdl.microsoft.com/download/symbols;SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\n Options\">
在 Windbg 中输入下列命令，来打印出为什么 symbols 没有加载:
\n> !sym noisy\n> .reload /f electron.exe\nShareMenu 类用于创建macOS的Share Menu专用菜单 ，这可以将当前消息分享给其他应用、社交媒体账号等。
若要将共享菜单放在其他菜单下，使用MenuItem当中的shareMenu 。
\n\nCreate share menu on macOS.
\n
进程：主进程
\nnew ShareMenu(sharingItem)sharingItem SharingItem - The item to share.Creates a new share menu.
\n shareMenu 对象具有以下实例方法:
shareMenu.popup([options])options PopupOptions (optional)browserWindow BrowserWindow (可选) - 默认为选中窗口.x Number (可选) - 默认为当前鼠标的位置。 如果指定了y，则该选项必选。y Number (可选) - 默认为当前鼠标的位置。 如果指定了x，则该选项必选。positioningItem Number (optional) macOS - The index of the menu item to be positioned under the mouse cursor at the specified coordinates. 默认值为 -1。callback Function (optional) - 会在菜单关闭后被调用.将此菜单作为 browserWindow 中的上下文菜单弹出。
\nshareMenu.closePopup([browserWindow])\nbrowserWindow BrowserWindow (可选) - 默认为选中窗口.\n \n 关闭 browserWindow 中的上下文菜单。\n
id String - The unique id of the shared worker.url String - The url of the shared worker.texts String - An array of text to share.filePaths String - An array of files to share.urls String - An array of URLs to share.\n\n使用默认应用程序管理文件和 url。
\n
Process: Main, Renderer (non-sandboxed only)
\nshell 模块提供与桌面集成相关的功能。
在用户的默认浏览器中打开 URL 的示例:
\nconst { shell } = require('electron')\n\nshell.openExternal('https://github.com')\nNote: While the shell module can be used in the renderer process, it will not function in a sandboxed renderer.
shell 模块具有以下方法:
shell.showItemInFolder(fullPath)fullPath StringShow the given file in a file manager. If possible, select the file.
\nshell.openPath(path)path StringReturns Promise<String> - Resolves with a string containing the error message corresponding to the failure if a failure occurred, otherwise \"\".
以桌面的默认方式打开给定的文件。
\nshell.openExternal(url[, options])url String - Max 2081 characters on windows.options Object (可选)activate Boolean (optional) macOS - true to bring the opened application to the foreground. 默认值为 true。workingDirectory字符串 (可选的) Windows - 工作目录返回 Promise<void>
Open the given external protocol URL in the desktop's default manner. (For example, mailto: URLs in the user's default mail agent).
\nshell.trashItem(path)path String - path to the item to be moved to the trash.Returns Promise<void> - Resolves when the operation has been completed. Rejects if there was an error while deleting the requested item.
This moves a path to the OS-specific trash location (Trash on macOS, Recycle Bin on Windows, and a desktop-environment-specific location on Linux).
\nshell.beep()播放哔哔的声音.
\nshell.writeShortcutLink(shortcutPath[, operation], options) WindowsshortcutPath Stringoperation String (optional) - Default is create, can be one of following:create - 创建一个新的快捷方式, 如有必要可以覆盖。update - 仅更新现有快捷方式上的指定属性。replace - 覆盖现有快捷方式, 如果快捷方式不存在将会失败。options ShortcutDetails返回 Boolean - 快捷方式是否被成功创建。
在shortcutPath位置创建或更新一个快捷连接
shell.readShortcutLink(shortcutPath) WindowsshortcutPath String解析shortcutPath中的快捷链接。
发生任何错误时将引发异常。
", "title": "shell", "description": "使用默认应用程序管理文件和 url。" }, "/docs/api/structures/shortcut-details": { "locale": "zh-CN", "slug": "shortcut-details", "href": "/docs/api/structures/shortcut-details", "crowdinFileId": "256509", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/shortcut-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "target String - The target to launch from this shortcut.cwd String (optional) - The working directory. Default is empty.args String (optional) - The arguments to be applied to target when launching from this shortcut. Default is empty.description String (optional) - The description of the shortcut. Default is empty.icon String (optional) - The path to the icon, can be a DLL or EXE. icon and iconIndex have to be set together. Default is empty, which uses the target's icon.iconIndex Number (optional) - The resource ID of icon when icon is a DLL or EXE. Default is 0.appUserModelId String (optional) - The Application User Model ID. Default is empty.toastActivatorClsid String (optional) - The Application Toast Activator CLSID. Needed for participating in Action Center.width Numberheight Number本指南提供了有关如何包装你的 Electron 应用程序的任何 Snapcraft 环境, 包括 Ubuntu 软件中心的信息。
\n与更广泛的 Linux 社区一起, 规范旨在解决 snapcraft 项目中的许多常见的软件安装问题。 Snaps 是容器化的软件包, 包括所需的依赖项、自动更新和对所有主要 Linux 发行版的工作, 而无需进行系统修改。
创建 .snap 文件有三种方法:
1) 使用 electron-forge 或 electron-builder, 与 snap 支持的两个工具都不在该框中。 这是最简单的选择。 2) 使用 electron-installer-snap, 它采用 electron-packager 的输出。 3) 使用已经创建的 .deb 包。
在某些情况下，您需要安装 snapcraft 工具。 安装特定发行版的 snapcraft 的指南在这里能看到。
electron-installer-snap该模块的工作原理与electron-winstaller类似 因为它的范围仅限于构建捕捉包。 你可以这样安装:
npm install --save-dev electron-installer-snap\n打包应用程序使用 electron-packager (或类似工具)。 Make sure to remove node_modules that you don't need in your final application, since any module you don't actually need will increase your application's size.
结构输出应该看起来大致像这样:
\n.\n└── dist\n └── app-linux-x64\n ├── LICENSE\n ├── LICENSES.chromium.html\n ├── content_shell.pak\n ├── app\n ├── icudtl.dat\n ├── libgcrypt.so.11\n ├── libnode.so\n ├── locales\n ├── resources\n ├── v8_context_snapshot.bin\n └── version\nelectron-installer-snapFrom a terminal that has snapcraft in its PATH, run electron-installer-snap with the only required parameter --src, which is the location of your packaged Electron application created in the first step.
npx electron-installer-snap --src=out/myappname-linux-x64\nIf you have an existing build pipeline, you can use electron-installer-snap programmatically. For more information, see the Snapcraft API docs.
const snap = require('electron-installer-snap')\n\nsnap(options)\n .then(snapPath => console.log(`Created snap at ${snapPath}!`))\nsnapcraft with electron-packager创建你的项目目录并将以下内容添加到 snap/snapcraft.yaml：
name: electron-packager-hello-world\nversion: '0.1'\nsummary: Hello World Electron app\ndescription: |\n Simple Hello World Electron app as an example\nbase: core18\nconfinement: strict\ngrade: stable\n\napps:\n electron-packager-hello-world:\n command: electron-quick-start/electron-quick-start --no-sandbox\n extensions: [gnome-3-34]\n plugs:\n - browser-support\n - network\n - network-bind\n environment:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n TMPDIR: $XDG_RUNTIME_DIR\n\nparts:\n electron-quick-start:\n plugin: nil\n source: https://github.com/electron/electron-quick-start.git\n override-build: |\n npm install electron electron-packager\n npx electron-packager . --overwrite --platform=linux --output=release-build --prune=true\n cp -rv ./electron-quick-start-linux-* $SNAPCRAFT_PART_INSTALL/electron-quick-start\n build-snaps:\n - node/14/stable\n build-packages:\n - unzip\n stage-packages:\n - libnss3\n - libnspr4\n如果要将此示例应用于现有项目：
\nsource: https://github.com/electron/electron-quick-start.git</0 > 为 <code>source: ...electron-quick-start 为你的项目名称。$ snapcraft\n\n<output snipped>\nSnapped electron-packager-hello-world_0.1_amd64.snap\nsudo snap install electron-packager-hello-world_0.1_amd64.snap --dangerous\nelectron-packager-hello-world\nSnapcraft is capable of taking an existing .deb file and turning it into a .snap file. The creation of a snap is configured using a snapcraft.yaml file that describes the sources, dependencies, description, and other core building blocks.
If you do not already have a .deb package, using electron-installer-snap might be an easier path to create snap packages. However, multiple solutions for creating Debian packages exist, including electron-forge, electron-builder or electron-installer-debian.
For more information on the available configuration options, see the documentation on the snapcraft syntax. Let's look at an example:
\nname: myApp\nversion: '2.0.0'\nsummary: A little description for the app.\ndescription: |\n You know what? This app is amazing! It does all the things\n for you. Some say it keeps you young, maybe even happy.\n\ngrade: stable\nconfinement: classic\n\nparts:\n slack:\n plugin: dump\n source: my-deb.deb\n source-type: deb\n after:\n - desktop-gtk3\n stage-packages:\n - libasound2\n - libnotify4\n - libnspr4\n - libnss3\n - libpcre3\n - libpulse0\n - libxss1\n - libxtst6\n electron-launch:\n plugin: dump\n source: files/\n prepare: |\n chmod +x bin/electron-launch\n\napps:\n myApp:\n command: bin/electron-launch $SNAP/usr/lib/myApp/myApp\n desktop: usr/share/applications/myApp.desktop\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n environment:\n TMPDIR: $XDG_RUNTIME_DIR\nAs you can see, the snapcraft.yaml instructs the system to launch a file called electron-launch. In this example, it passes information on to the app's binary:
\nexec \"$@\" --executed-from=\"$(pwd)\" --pid=$$ > /dev/null 2>&1 &\nAlternatively, if you're building your snap with strict confinement, you can use the desktop-launch command:
apps:\n myApp:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n command: env TMPDIR=$XDG_RUNTIME_DIR PATH=/usr/local/bin:${PATH} ${SNAP}/bin/desktop-launch $SNAP/myApp/desktop\n desktop: usr/share/applications/desktop.desktop\nElectron 的源代码主要依据 Chromium 的拆分约定被拆成了许多部分。
\n为了更好地理解源代码，您可能需要了解一下 Chromium 的多进程架构。
\nElectron\n├── build/ - Build configuration files needed to build with GN.\n├── buildflags/ - Determines the set of features that can be conditionally built.\n├── chromium_src/ - Source code copied from Chromium that isn't part of the content layer.\n├── default_app/ - A default app run when Electron is started without\n| providing a consumer app.\n├── docs/ - Electron's documentation.\n| ├── api/ - Documentation for Electron's externally-facing modules and APIs.\n| ├── development/ - Documentation to aid in developing for and with Electron.\n| ├── fiddles/ - A set of code snippets one can run in Electron Fiddle.\n| ├── images/ - Images used in documentation.\n| └── tutorial/ - Tutorial documents for various aspects of Electron.\n├── lib/ - JavaScript/TypeScript source code.\n| ├── browser/ - Main process initialization code.\n| | ├── api/ - API implementation for main process modules.\n| | └── remote/ - Code related to the remote module as it is\n| | used in the main process.\n| ├── common/ - Relating to logic needed by both main and renderer processes.\n| | └── api/ - API implementation for modules that can be used in\n| | both the main and renderer processes\n| ├── isolated_renderer/ - Handles creation of isolated renderer processes when\n| | contextIsolation is enabled.\n| ├── renderer/ - Renderer process initialization code.\n| | ├── api/ - API implementation for renderer process modules.\n| | ├── extension/ - Code related to use of Chrome Extensions\n| | | in Electron's renderer process.\n| | ├── remote/ - Logic that handles use of the remote module in\n| | | the main process.\n| | └── web-view/ - Logic that handles the use of webviews in the\n| | renderer process.\n| ├── sandboxed_renderer/ - Logic that handles creation of sandboxed renderer\n| | | processes.\n| | └── api/ - API implementation for sandboxed renderer processes.\n| └── worker/ - Logic that handles proper functionality of Node.js\n| environments in Web Workers.\n├── patches/ - Patches applied on top of Electron's core dependencies\n| | in order to handle differences between our use cases and\n| | default functionality.\n| ├── boringssl/ - Patches applied to Google's fork of OpenSSL, BoringSSL.\n| ├── chromium/ - Patches applied to Chromium.\n| ├── node/ - Patches applied on top of Node.js.\n| └── v8/ - Patches applied on top of Google's V8 engine.\n├── shell/ - C++ source code.\n| ├── app/ - 系统入口代码.\n| ├── browser/ - 包含了主窗口、UI 和所有主进程相关的东西.\n| | | 它会告诉渲染进程如何管理页面.\n| | ├── ui/ - 不同平台上 UI 部分的实现.\n| | | ├── cocoa/ - Cocoa 部分的源代码.\n| | | ├── win/ - Windows GUI 部分的源代码.\n| | | └── x/ - X11 部分的源代码.\n| | ├── api/ - 主进程 API 的实现.\n| | ├── net/ - 网络相关的代码.\n| | ├── mac/ - 与 Mac 有关的 Objective-C 代码.\n| | └── resources/ - Icons, platform-dependent files, etc.\n| ├── renderer/ - Code that runs in renderer process.\n| | └── api/ - 渲染进程 API 的实现.\n| └── common/ - 同时被主进程和渲染进程用到的代码,\n| | 包括了一些用来将 node 的消息循环整合到 Chromium 的\n| | 消息循环中时用到的工具函数和代码.\n| └── api/ - 同时被主进程和渲染进程使用到的 API 的实现,\n| 并且是 Electron 内置模块的基础.\n├── spec/ - Components of Electron's test suite run in the renderer process.\n├── spec-main/ - Components of Electron's test suite run in the main process.\n└── BUILD.gn - Electron 的构建规则.\nscript/create-dist.py 创建的临时发布目录.ninja 的临时输出目录.script/ - The set of all scripts Electron runs for a variety of purposes.\n├── codesign/ - Fakes codesigning for Electron apps; used for testing.\n├── lib/ - Miscellaneous python utility scripts.\n└── release/ - Scripts run during Electron's release process.\n ├── notes/ - Generates release notes for new Electron versions.\n └── uploaders/ - Uploads various release-related files during release.\n自 Electron 8 以来已内置支持 Chromium 拼写检查器。 On Windows and Linux this is powered by Hunspell dictionaries, and on macOS it makes use of the native spellchecker APIs.
\n对于 Electron 9 及以上，默认启用拼写检查器。 For Electron 8 you need to enable it in webPreferences.
const myWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: true\n }\n})\nOn macOS as we use the native APIs there is no way to set the language that the spellchecker uses. 默认情况下，macOS 本机拼写检查器会自动检测您使用的语言。
\n对于 Windows 和 Linux，你应该使用一些 Electron API 来设置拼写检查器的语言。
\n// Sets the spellchecker to check English US and French\nmyWindow.session.setSpellCheckerLanguages(['en-US', 'fr'])\n\n// An array of all available language codes\nconst possibleLanguages = myWindow.session.availableSpellCheckerLanguages\nBy default the spellchecker will enable the language matching the current OS locale.
\nAll the required information to generate a context menu is provided in the context-menu event on each webContents instance. 下面提供了一个小的示例，如何用此信息制作上下文菜单。
const { Menu, MenuItem } = require('electron')\n\nmyWindow.webContents.on('context-menu', (event, params) => {\n const menu = new Menu()\n\n // Add each spelling suggestion\n for (const suggestion of params.dictionarySuggestions) {\n menu.append(new MenuItem({\n label: suggestion,\n click: () => mainWindow.webContents.replaceMisspelling(suggestion)\n }))\n }\n\n // Allow users to add the misspelled word to the dictionary\n if (params.misspelledWord) {\n menu.append(\n new MenuItem({\n label: 'Add to dictionary',\n click: () => mainWindow.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord)\n })\n )\n }\n\n menu.popup()\n})\n虽然拼写检查器本身没有发送任何输入， 单词或用户输入到谷歌服务中，hunspell 字典文件默认从谷歌 CDN 下载。 如果你想要避免这种情况，你可以提供一个替代 URL 来下载字典。
\nmyWindow.session.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/')\nCheck out the docs for session.setSpellCheckerDictionaryDownloadURL for more information on where to get the dictionary files from and how you need to host them.
这里是一些编写 Electron 文档的指南。
\n# 级标题。## 级标题。# 的数量。举一个Quick Start的例子:
# 快速入门\n\n...\n\n## 主进程\n\n## 渲染进程\n\n...\n\n## 运行应用程序\n\n...\n\n### 作为分发版本运行\n\n...\n\n### 手动下载二进制格式的 Electron\n\n...\n对于 API 参考, 可以例外于这些规则.
\n这个仓库使用 markdownline 软件包来实行前后一致的 Markdown 风格。 有关确切规则，请参阅根文件夹中的 .markdownlint.json 文件。
有几个样式准则不在 linter 规则范围之内：
\n\nbash而不是cmd（由于语法高亮问题）. js 和javascript代码块均被标记为 standard-markdown.以下规则仅适用于 API 的文档。
\n每个模块的API文档必须使用由 require('electron') 返回的实际对象名称作为标题。(例如 BrowserWindow``autoUpdater 和 session)。
直接在页面标题下方，添加一行模块描述作为Markdown 引用(以 > 开头)。
以使用 session 模块作为例子:
# session\n\n> Manage browser sessions, cookies, cache, proxy settings, etc.\n对于非类的模块，它们的方法和事件必须在 ## Methods 和 ## Events 章节中列出
举一个 autoUpdater 的例子:
# autoUpdater\n\n## Events\n\n### Event: 'error'\n\n## Methods\n\n### `autoUpdater.setFeedURL(url[, requestHeaders])`\n## Class: TheClassName 章节中列出.### 级标题列出。### Static Methods 章节中列出。### Instance Methods 章节中列出。[TYPE] - [Return description]”开始Object，其结构可以使用冒号后跟换行符的方式，然后使用与函数参数相同样式的无序属性列表。### Instance Events 章节中列出.### Instance Properties 章节中列出。这里用 Session 和 Cookies 类作为例子:
# session\n\n## Methods\n\n### session.fromPartition(partition)\n\n## Static Properties\n\n### session.defaultSession\n\n## Class: Session\n\n### Instance Events\n\n#### Event: 'will-download'\n\n### Instance Methods\n\n#### `ses.getCacheSize()`\n\n### Instance Properties\n\n#### `ses.cookies`\n\n## Class: Cookies\n\n### Instance Methods\n\n#### `cookies.get(filter, callback)`\n方法章节必须采用以下形式：
\n### `objectName.methodName(required[, optional]))`\n\n* `required` String - A parameter description.\n* `optional` Integer (optional) - Another parameter description.\n\n...\n标题可以是 ### 级别或 #### 级别，具体取决于该方法是属于模块还是类。
对于模块， objectName 是模块的名称。 对于类，它必须是类实例的名称，而且不能与模块名称相同。
例如，session 模块下的 Session 类的方法必须使用 ses 作为 objectName 。
可选参数使用方括号 [] 表示，并且多个参数之间以逗号分隔：
required[, optional]\n关于每个参数的更详细信息将在方法下面的无序列表中列出。 参数类型是由 JavaScript 原始类型(例如: String, Promise, 或 Object)；自定义 API 结构，像Electron的 Cookie；或通配符 any 注明。
如果参数是 Array 类型，请使用带有数组内值类型的 [] 缩写 (例如，any[] 或 String[])。
如果参数类型为 Promise, 则将promise resolve时的类型作为参数(例如 Promise<void> 或 Promise<String>)。
如果参数可以是多种类型，则将类型通过 |分开。
Function 类型参数的描述应该清楚描述它是如何被调用的，并列出将被传递给它的参数的类型.
如果参数或方法对某些平台是唯一的，那么这些平台将使用数据类型后面的空格分隔的斜体列表来表示。 值可以是 macOS，Windows 或 Linux.
* `animate` Boolean (optional) _macOS_ _Windows_ - 进行动画处理的事情.\n事件章节必须采用以下形式:
\n### Event: 'wake-up'\n\nReturns:\n\n* `time` String\n\n...\n标题可以是 ### 级别或 #### 级别，具体取决于该事件是属于模块还是类。
事件的参数遵循与方法相同的规则.
\n属性章节必须采用以下形式:
\n### session.defaultSession\n\n...\n标题可以是 ### 级别或 #### 级别，具体取决于该属性属于模块还是类。
请参见 electron/i18n
", "title": "Electron 文档风格指南", "description": "" }, "/docs/tutorial/support": { "locale": "zh-CN", "slug": "support", "href": "/docs/tutorial/support", "crowdinFileId": "256253", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/support.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "如果您有安全方面的问题，请参阅 安全文档
\n如果你想获得编程方面的帮助、问题的答案亦或是想要加入Electron的开发者大家庭，您可以参考以下链接：
\nElectron's Discord has channels for:electron 各种 Atom 论坛#electron Atom's Slack上的频道electron-ru (俄语版)electron-br (巴西葡语版)electron-kr (韩语版)electron-jp (日语版)electron-tr (土耳其语版)electron-id (印尼语版)electron-pl (波兰语版)如果你有意为加入Electron的开发，可参阅贡献文档
\n如果你在Electron的支持版中发现漏洞，请在问题追踪中提交你发现的漏洞。
\nawesome-electron是一个社区维护的示例程序列表。
\nNote: Beginning in September 2021 with Electron 15, the Electron team will temporarily support the latest four stable major versions. This extended support is intended to help Electron developers transition to the new eight week release cadence, and will continue until May 2022, with the release of Electron 19. At that time, the Electron team will drop support back to the latest three stable major versions.
\n最新的 3 个稳定的的版本受 Electron 团队支持。 例如，如果最新版本是 6.1.x，则包括 5.0.x和 4.2.x系列的同样会被支持 We only support the latest minor release for each stable release series. This means that in the case of a security fix 6.1.x will receive the fix, but we will not release a new version of 6.0.x.
\nThe latest stable release unilaterally receives all fixes from main, and the version prior to that receives the vast majority of those fixes as time and bandwidth warrants. The oldest supported release line will receive only security fixes directly.
All supported release lines will accept external pull requests to backport fixes previously merged to main, though this may be on a case-by-case basis for some older supported lines. All contested decisions around release line backports will be resolved by the Releases Working Group as an agenda item at their weekly meeting the week the backport PR is raised.
当一个API的改动或移除会导致某个现有功能被破坏时，这个现有功能在被移除之前，仍然会在至少两个主要版本号内得到尽可能的支持。 比如，某个函数需要三个参数，而在主要版本10中，它被修改为需要两个参数，那么这个函数的三参数版本仍然会被支持，至少持续到主要版本12。 经过两个主要版本后，我们仍会尝试支持后向兼容，直到维护成本高得难以承受而无法继续支持。
\n当一个发行分支达到了其支持周期的末尾，该序列将会在NPM中弃用，且会发布一个最终的“结束支持”版本。 这个版本将会添加一个警告以通知正在使用一个不受支持的Electron版本。
\n这些步骤是用于帮助应用开发者了解他们使用的分支不受支持，而不会过分打扰最终用户。
\n如果一个应用有特殊情况并需要保持使用一个不受支持的Electron版本，开发者可以通过忽略来自应用的package.json devDependencies的最终版本以关闭结束支持警告。 For example, since the 1-6-x series ended with an end-of-support 1.6.18 release, developers could choose to stay in the 1-6-x series without warnings with devDependency of \"electron\": 1.6.0 - 1.6.17.
目前 Electron 支持以下平台：
\n对 macOS 仅提供64位版本，并且只支持 macOS 10.11 (El Capitan) 以及更高版本。
\nElectron 11.0.0 已原生支持 Apple Silicon (arm64) 设备。
仅支持 Windows 7 或更高版本, 旧版操作系统已不再支持(并且无法运行).
\n为Windows系统提供ia32 (x86) 和 x64 (amd64) 两种二进制版本。 Electron 6.0.8 已原生支持 Windows on Arm (arm64) 设备。 Running apps packaged with previous versions is possible using the ia32 binary.
在 Ubuntu 18.04 上预构建的二进制文件。
\n预编译版本是否能够正常运行，取决于其中是否包含了编译平台的链接库。所以只有 Ubuntu 18.04 是可以保证能正常运行的，并且以下平台也被证实可以正常运行 Electron 的预编译版本：
\n\n\n如何使用 Node.js 和 Electron APIs
\n
Node. js 的所有 内置模块 都在Electron中可用， 第三方 node 模块中也完全支持 (包括 原生模块 )。
\nElectron 还为开发原生桌面应用程序提供了一些额外的内置模块。 某些模块仅在主进程中可用, 有些仅在渲染进程 (web 页) 中可用, 而有些在这两个进程中都可以使用。
\n基本规则是: 如果一个模块是 GUI 或底层系统相关的, 那么它应该只在主进程中可用。 You need to be familiar with the concept of main process vs. renderer process scripts to be able to use those modules.
\n主进程脚本就像一个普通的Node.js脚本：
\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL('https://github.com')\n})\n如果 nodeIntegration 被启用，那么渲染进程除了额外能够使用node模块的能力外，与普通网页没有什么区别
\n<html>\n<body>\n<script>\n const fs = require('fs')\n console.log(fs.readFileSync(__filename, 'utf8'))\n</script>\n</body>\n</html>\n从0.37开始，可以使用 destructuring assignment (es6解构赋值)来使内置模块更容易使用。
\nconst { app, BrowserWindow } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\n如果您需要整个 electron 模块, 则可以require它, 然后使用解构（destructuring）从 <0> electron <0> 访问各个模块。
const electron = require('electron')\nconst { app, BrowserWindow } = electron\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\n这等效于以下代码:
\nconst electron = require('electron')\nconst app = electron.app\nconst BrowserWindow = electron.BrowserWindow\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\n\n\n获取system preferences.
\n
进程：主进程
\nconst { systemPreferences } = require('electron')\nconsole.log(systemPreferences.isDarkMode())\nsystemPreferences 对象触发以下事件:
返回:
\nevent EventnewColor String - 用户指定的新 RGBA 颜色作为系统偏好颜色.返回:
\nevent Event返回:
\nevent EventinvertedColorScheme Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is being used, false otherwise.Deprecated: Should use the new updated event on the nativeTheme module.
返回:
\nevent EventhighContrastColorScheme Boolean - true if a high contrast theme is being used, false otherwise.Deprecated: Should use the new updated event on the nativeTheme module.
systemPreferences.isDarkMode() macOS Windows Deprecated返回Boolean，表示系统是否处于Dark模式
已废弃： 请使用新的 nativeTheme.shouldUseDarkColors API。
systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS返回值 Boolean - 是否在页面设置之间进行滑动。
systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOSevent StringuserInfo Record<String, any>deliverImmediately Boolean (optional) - true to post notifications immediately even when the subscribing app is inactive.Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postLocalNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postWorkspaceNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.subscribeNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object String返回 Number - 此订阅的 ID
订阅macOS的原生通知，当通信的 event</ 0>发生时，将调用 <code>callback(event, userInfo) 。 userInfo是一个Object，它包含随通知一起发送的用户信息字典。 The object is the sender of the notification, and only supports NSString values for now.
返回订阅的 id, 可用于取消该订阅的 event.
在这个API下订阅NSDistributedNotificationCenter， event 的示例值为：
AppleInterfaceThemeChangedNotificationAppleAquaColorVariantChangedAppleColorPreferencesChangedNotificationAppleShowScrollBarsSettingChangedsystemPreferences.subscribeLocalNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object String返回 Number - 此订阅的 ID
Same as subscribeNotification, but uses NSNotificationCenter for local defaults. 这对事件 NSUserDefaultsDidChangeNotification 是必需的。
systemPreferences.subscribeWorkspaceNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object String返回 Number - 此订阅的 ID
与 subscribeNotification一样, 但使用NSWorkspace.sharedWorkspace.notificationCenter。 这对事件 NSWorkspaceDidActivateApplicationNotification 是必需的。
systemPreferences.unsubscribeNotification(id) macOSid Integer使用 id 删除订阅。
systemPreferences.unsubscribeLocalNotification(id) macOSid Integer与unsubscribeNotification相同，但将订户从NSNotificationCenter中删除。
systemPreferences.unsubscribeWorkspaceNotification(id) macOSid Integer与 unsubscribeNotification 一样，但是它从 NSWorkspace.sharedWorkspace.notificationCenter 中移除订阅者。
systemPreferences.registerDefaults(defaults) macOSdefaults Record<String, String | Boolean | Number> - a dictionary of (key: value) user defaults在应用的NSUserDefaults配置项中添加其它默认设置。
systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOSkey Stringtype Type - Can be string, boolean, integer, float, double, url, array or dictionary.Returns UserDefaultTypes[Type] - The value of key in NSUserDefaults.
常用的 key 和 type 的类型为:
AppleInterfaceStyle: stringAppleAquaColorVariant: integerAppleHighlightColor: stringAppleShowScrollBars: stringNSNavRecentPlaces: arrayNSPreferredWebServices: dictionaryNSUserDictionaryReplacementItems: arraysystemPreferences.setUserDefault(key, type, value) macOSkey Stringtype String - Can be string, boolean, integer, float, double, url, array or dictionary.value String设置 NSUserDefaults 中 key 的值.
请注意， type 应匹配实际类型的 value。 如果他们没有，就会抛出一个异常。
常用的 key 和 type 的类型为:
ApplePressAndHoldEnabled: booleansystemPreferences.removeUserDefault(key) macOSkey String删除 NSUserDefaults中的 key 。 可以用来恢复默认值或之前用 setUserDefault 为一个 key 设置的全局变量。
systemPreferences.isAeroGlassEnabled() Windows返回 Boolean - true 如果启用了 DWM composition (Aero Glass), 否则为 false.
使用它来确定是否应创建透明窗口的示例 (当禁用 DWM 组合时, 透明窗口无法正常工作):
\nconst { BrowserWindow, systemPreferences } = require('electron')\nconst browserOptions = { width: 1000, height: 800 }\n\n// Make the window transparent only if the platform supports it.\nif (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {\n browserOptions.transparent = true\n browserOptions.frame = false\n}\n\n// Create the window.\nconst win = new BrowserWindow(browserOptions)\n\n// Navigate.\nif (browserOptions.transparent) {\n win.loadURL(`file://${__dirname}/index.html`)\n} else {\n // No transparency, so we load a fallback that uses basic styles.\n win.loadURL(`file://${__dirname}/fallback.html`)\n}\nsystemPreferences.getAccentColor() Windows macOS返回 String - 用户当前系统偏好颜色，RGBA 十六进制形式.
const color = systemPreferences.getAccentColor() // `\"aabbccdd\"`\nconst red = color.substr(0, 2) // \"aa\"\nconst green = color.substr(2, 2) // \"bb\"\nconst blue = color.substr(4, 2) // \"cc\"\nconst alpha = color.substr(6, 2) // \"dd\"\n此 API 仅在 macOS 10.14 Mojave 或更高版本上可用。
\nsystemPreferences.getColor(color) Windows macOScolor String - One of the following values:3d-dark-shadow - 三维显示元素的暗阴影。3d-face - 面向三维显示元素和对话框背景的颜色。3d-highlight - 三维显示元素的高亮色.3d-light - 三维显示元素的亮色.3d-shadow - 三维显示元素的阴影颜色.active-border - 活动窗口边框。active-caption - Active window title bar. Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.active-caption-gradient - 活动窗口标题栏的颜色渐变中的右侧颜色。app-workspace - 多文档界面 (MDI) 应用程序的背景颜色。button-text - 按钮上的文本。caption-text - 标题，大小框和滚动条箭头框中的文本。desktop - 桌面的背景色。disabled-text - 灰色 (禁用的) 文字.highlight - 在控件中选择的项目。highlight-text - 在控件中选择的项目文本。hotlight - 超链接或热追踪项目的颜色。inactive-border - 非活动窗口边框。inactive-caption - Inactive window caption. Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.inactive-caption-gradient - 非活动窗口标题栏的颜色渐变中的右侧颜色。inactive-caption-text - 非活动标题中的文字颜色。info-background - 工具提示控件的背景颜色。info-text - 工具提示控件的文本颜色。menu - 菜单的背景色.menu-highlight - 当菜单显示为平面菜单时用于突出显示菜单项的颜色。menubar - 菜单显示为平面菜单时菜单栏的背景颜色。menu-text - 菜单的文字.scrollbar - 滚动条的灰色区域.window - 窗口的背景色.window-frame - 窗口框.window-text - 窗口的文字。alternate-selected-control-text - The text on a selected surface in a list or table. 已废弃control-background - The background of a large interface element, such as a browser or table.control - The surface of a control.control-text -The text of a control that isn’t disabled.disabled-control-text - The text of a control that’s disabled.find-highlight - The color of a find indicator.grid - The gridlines of an interface element such as a table.header-text - The text of a header cell in a table.highlight - The virtual light source onscreen.keyboard-focus-indicator - The ring that appears around the currently focused control when using the keyboard for interface navigation.label - The text of a label containing primary content.link - A link to other content.placeholder-text - A placeholder string in a control or text view.quaternary-label - The text of a label of lesser importance than a tertiary label such as watermark text.scrubber-textured-background - The background of a scrubber in the Touch Bar.secondary-label - The text of a label of lesser importance than a normal label such as a label used to represent a subheading or additional information.selected-content-background - The background for selected content in a key window or view.selected-control - The surface of a selected control.selected-control-text - The text of a selected control.selected-menu-item-text - The text of a selected menu.selected-text-background - The background of selected text.selected-text - Selected text.separator - A separator between different sections of content.shadow - The virtual shadow cast by a raised object onscreen.tertiary-label - The text of a label of lesser importance than a secondary label such as a label used to represent disabled text.text-background - Text background.text - The text in a document.under-page-background - The background behind a document's content.unemphasized-selected-content-background - The selected content in a non-key window or view.unemphasized-selected-text-background - A background for selected text in a non-key window or view.unemphasized-selected-text - Selected text in a non-key window or view.window-background - The background of a window.window-frame-text - The text in the window's titlebar area.返回 String -系统颜色设置为RGB十六进制格式 (#ABCDEF). 更多详细信息请参阅 Windows docs 和 macOS 文档。
以下颜色仅在 macOS 10.14 上可用：find-hightlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, 和 unemphasized-selected-text
systemPreferences.getSystemColor(color) macOScolor String - One of the following values:bluebrowngraygreenorangepinkpurpleredyellow返回 String - 标准系统颜色，格式为 #RRGGBBAA。
返回几个标准系统颜色之一，这些颜色可自动适应鲜艳度的变化并更改辅助功能设置，如\"增加对比度\"和\"降低透明度\"。 有关更多详细信息，请参阅 apple 文档 。
\nsystemPreferences.isInvertedColorScheme() Windows Deprecated返回 Boolean - 如果使用反转颜色方案(亮文字暗背景的高对比度主题) 则为true，否则为false。
已废弃： 请使用新的 nativeTheme.shouldUseInvertedColorScheme API。
systemPreferences.isHighContrastColorScheme() macOS Windows Deprecated返回 Boolean - 如果启用了高对比度主题为true，否则为false。
已废弃： 请使用新的 nativeTheme.shouldUseHighContrastColors API。
systemPreferences.getEffectiveAppearance() macOS返回 String - 其值可能是 dark、light 或 unknown.
获取当前应用到你的程序上的 macOS 设置项，会映射到 NSApplication.effectiveAppearance
\nsystemPreferences.getAppLevelAppearance() macOS Deprecated返回 String | null - 其值可能为 dark、light 或 unknown。
获取您在macOS上为您的应用程序设置的外观，映射到NSApplication.appearance。 您可以使用 setAppLevelAppearance API 来设置此值。
systemPreferences.setAppLevelAppearance(appearance) macOS Deprecatedappearance String | null - 可以是 dark 或 light设定您的应用程序的外观设置，这应该覆盖系统默认值以及覆盖 getEffectiveAppearance 的值。
systemPreferences.canPromptTouchID() macOS返回 Boolean - 此设备是否有能力使用 Touch ID。
注意：在 macOS 系统的版本低于 Sierra 10.12.2时，此 API 将返回 false 。
systemPreferences.promptTouchID(reason) macOSreason String - The reason you are asking for Touch ID authentication返回 Promise<void> - resolve如果用户已成功通过Touch ID授权。
const { systemPreferences } = require('electron')\n\nsystemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {\n console.log('You have successfully authenticated with Touch ID!')\n}).catch(err => {\n console.log(err)\n})\n此 API 本身不会保护您的用户数据；相反，这是一个机制，让你这样做。 原生应用需要在其密钥链入口设置 访问控制常量 ，如 kSecAccessControlUserPresence ，当应用读取到后将自动提示 Touch ID 生物识别许可。 该操作可以通过 node-keytar完成，这样，应用就会用 node-keytar 存储加密密钥，并且只有在 promptTouchID() resolve时才能取出。
注意：在 macOS 系统的版本低于 Sierra 10.12.2时，此 API 返回的Promise将reject 。
\nsystemPreferences.isTrustedAccessibilityClient(prompt) macOSprompt Boolean - whether or not the user will be informed via prompt if the current process is untrusted.返回 Boolean - 如果当前进程是受信任的无障碍客户端，则为true，否则为 false 。
systemPreferences.getMediaAccessStatus(mediaType) Windows macOSmediaType String - 可以是 microphone, camera 或 screen.返回 String - 值可以是 not-determined， granted， denied， restricted 或 unknown。
在 macOS 10.13 High Sierra 或更低版本上不需要用户授权，因此此方法总是返回 granted。 macOS 10.14 Mojave 或更高版本需要授权访问 麦克风 和 摄像头。 macOS 10.15 Catalina 或更高版本需要授权访问 屏幕。
Windows 10的全局设置控制了所有win32 应用程序对 麦克风 和 摄像头的访问权限。 It will always return granted for screen and for all media types on older versions of Windows.
systemPreferences.askForMediaAccess(mediaType) macOSmediaType String - the type of media being requested; can be microphone, camera.Returns Promise<Boolean> - A promise that resolves with true if consent was granted and false if it was denied. If an invalid mediaType is passed, the promise will be rejected. If an access request was denied and later is changed through the System Preferences pane, a restart of the app will be required for the new permissions to take effect. If access has already been requested and denied, it must be changed through the preference pane; an alert will not pop up and the promise will resolve with the existing access status.
Important: In order to properly leverage this API, you must set the NSMicrophoneUsageDescription and NSCameraUsageDescription strings in your app's Info.plist file. The values for these keys will be used to populate the permission dialogs so that the user will be properly informed as to the purpose of the permission request. See Electron Application Distribution for more information about how to set these in the context of Electron.
This user consent was not required until macOS 10.14 Mojave, so this method will always return true if your system is running 10.13 High Sierra or lower.
systemPreferences.getAnimationSettings()返回 Object:
shouldRenderRichAnimation Boolean - Returns true if rich animations should be rendered. Looks at session type (e.g. remote desktop) and accessibility settings to give guidance for heavy animations.scrollAnimationsEnabledBySystem Boolean - Determines on a per-platform basis whether scroll animations (e.g. produced by home/end key) should be enabled.prefersReducedMotion Boolean - Determines whether the user desires reduced motion based on platform APIs.Returns an object with system animation settings.
\nsystemPreferences.appLevelAppearance macOS一个类型为String的属性，此属性可能的值为：dark, light or unknown. It determines the macOS appearance setting for your application. This maps to values in: NSApplication.appearance. Setting this will override the system default as well as the value of getEffectiveAppearance.
Possible values that can be set are dark and light, and possible return values are dark, light, and unknown.
This property is only available on macOS 10.14 Mojave or newer.
\nsystemPreferences.effectiveAppearance macOS 只读一个类型为String的属性，此属性可能的值为：dark, light or unknown.
Returns the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance
", "title": "systemPreferences", "description": "获取system preferences." }, "/docs/api/structures/task": { "locale": "zh-CN", "slug": "task", "href": "/docs/api/structures/task", "crowdinFileId": "256513", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/task.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "program String - Path of the program to execute, usually you should specify process.execPath which opens the current program.arguments String - The command line arguments when program is executed.title String - The string to be displayed in a JumpList.description String - Description of this task.iconPath String - The absolute path to an icon to be displayed in a JumpList, which can be an arbitrary resource file that contains an icon. You can usually specify process.execPath to show the icon of the program.iconIndex Number - The icon index in the icon file. If an icon file consists of two or more icons, set this value to identify the icon. If an icon file consists of one icon, this value is 0.workingDirectory String (optional) - The working directory. Default is empty.我们的目的是保持 Electron 代码的高覆盖率。 我们要求所有的pull request不仅要通过所有现有的测试，还要增加新的测试来覆盖变更的代码和新的场景。 我们要尽可能多地覆盖Electron应用中的代码路径和用例，以确保我们发布的应用程序都能拥有更少的bug。
\n这个仓库为 JavaScript 和 C ++ 提供了linting 规则 - 以及单元和集成测试。 通过 coding-style文档来学习更多的Electron's编码风格
\n为确保您的JavaScript符合Electron编码风格，请执行npm run lint-js，它将针对Electron本身以及单元测试运行standard测试。 如果您正在使用带有插件/插件系统的编辑器，那么可以使用StandardJS addons之类的插件在你提交代码前来检查编码规范。
若要用参数运行standard测试，首先执行npm run lint-js -- 然后输入要传递给standard测试的参数。
要确保您的C ++代码符合Electron编码风格，请执行npm run lint-cpp，它将会执行cpplint脚本。 我们建议您使用clang-format并准备一个简短的教程。
There is not a lot of Python in this repository, but it too is governed by coding style rules. npm run lint-py will check all Python, using pylint to do so.
If you are not using build-tools, ensure that that name you have configured for your local build of Electron is one of Testing, Release, Default, Debug, or you have set process.env.ELECTRON_OUT_DIR. Without these set, Electron will fail to perform some pre-testing steps.
要运行所有单元测试，请执行 npm run test。 单元测试其实也是一个Electron应用！你可以在spec 文件夹中找到它。 请注意，单元测试也有自己的 package.json，因此它的依赖没有在最顶层的package.json中定义。
若要通过匹配模式运行单个测试，可以执行 npm run test -- -g=PATTERN，把PATTERN 替换为匹配某个测试的正则表达式。 例：如果想运行IPC测试，你可以执行npm run test -- -g ipc。
Visual Studio 2019 must be installed.
\nNode headers have to be compiled for your configuration.
\nninja -C out\\Testing third_party\\electron_node:headers\nThe electron.lib has to be copied as node.lib.
\ncd out\\Testing\nmkdir gen\\node_headers\\Release\ncopy electron.lib gen\\node_headers\\Release\\node.lib\n一些 Windows 10 设备上没有默认安装Meriryo字体，这会导致字体回退测试的失败。 要安装Meiryo字体：
\n由于浮点数精度误差，某些依赖于精确像素测量的测试可能无法正常在Hi-DPI屏幕的设备上工作。 为了使这些测试能正常运行，请确保设备的缩放比为100%。
\n要配置缩放比：
\nElectron 基于 Chromium，所以需要一个显示驱动使其运转。 如果 Chromium 无法找到一个显示驱动， Electron 会启动失败，因此无论你如何去运行它，Electron 不会执行你的任何测试。 在 Travis，Circle， Jenkins 或者类似的系统上测试基于Electron的应用时，需要进行一些配置。 本质上，我们需要使用一个 虚拟的显示驱动。
\n首先安装 Xvfb. 这是一个虚拟的帧缓冲，实现了X11显示服务协议，所有的图形操作都在内存中表现，而不需要显示在 任何屏幕输出设备上。这正是我们所需要的。
\n然后创建一个虚拟屏幕实例(Xvfb), 并导出 DISPLAY 变量, 该变量存储虚拟屏幕的引用. Electron 中的 Chromium 会自动的去寻找 $DISPLAY，所以你的应用不需要再去进行配置 这一步可以通过 Paul Betts 的 xvfb-maybe 实现自动化：如果系统需要，在xvfb-maybe前加上你的测试命令 然后这个小工具会自动的设置 xvfb。 在 Windows 或 macOS ，它不会执行任何东西。
## 在 Windows 或者 macOS，这只是调用 electron-mocha\n## 在 Linux， 如果我们在一个 headless 环境，这将是等同于\n## 执行 xvfb-run electron-mocha ./test/*.js\nxvfb-maybe electron-mocha ./test/*.js\n在 Travis 上, 你的 .travis.yml 应该和下面的代码相似:
addons:\n apt:\n packages:\n - xvfb\n\ninstall:\n - export DISPLAY=':99.0'\n - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &\nJenkins下, 有一个可用的 Xvfb 插件。
\nCircle CI is awesome and has Xvfb and $DISPLAY already set up, so no further configuration is required.
AppVeyor 运行于 Windows 上，支持 Selenium，Chromium，Electron 以及一些类似的工具，开箱即用，无需配置
", "title": "Headless CI Systems 测试 (Travis CI, Jenkins)", "description": "" }, "/docs/tutorial/testing-widevine-cdm": { "locale": "zh-CN", "slug": "testing-widevine-cdm", "href": "/docs/tutorial/testing-widevine-cdm", "crowdinFileId": "256257", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/testing-widevine-cdm.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "在 Electron 中，你可以使用 Widevine CDM 库装载 Chrome 浏览器。
\nWidevine Content Decryption Modules (CDMs) are how streaming services protect content using HTML5 video to web browsers without relying on an NPAPI plugin like Flash or Silverlight. Widevine support is an alternative solution for streaming services that currently rely on Silverlight for playback of DRM-protected video content. It will allow websites to show DRM-protected video content in Firefox without the use of NPAPI plugins. The Widevine CDM runs in an open-source CDM sandbox providing better user security than NPAPI plugins.
\nAs of Electron v1.8.0 (Chrome v59), the below steps are may only be some of the necessary steps to enable Widevine; any app on or after that version intending to use the Widevine CDM may need to be signed using a license obtained from Widevine itself.
Per Widevine:
\n\n\nChrome 59 (and later) includes support for Verified Media Path (VMP). VMP provides a method to verify the authenticity of a device platform. For browser deployments, this will provide an additional signal to determine if a browser-based implementation is reliable and secure.
\nThe proxy integration guide has been updated with information about VMP and how to issue licenses.
\nWidevine recommends our browser-based integrations (vendors and browser-based applications) add support for VMP.
\n
To enable video playback with this new restriction, castLabs has created a fork that has implemented the necessary changes to enable Widevine to be played in an Electron application if one has obtained the necessary licenses from widevine.
\nOpen chrome://components/ in Chrome browser, find Widevine Content Decryption Module and make sure it is up to date, then you can find the library files from the application directory.
The library file widevinecdm.dll will be under Program Files(x86)/Google/Chrome/Application/CHROME_VERSION/WidevineCdm/_platform_specific/win_(x86|x64)/ directory.
The library file libwidevinecdm.dylib will be under /Applications/Google Chrome.app/Contents/Versions/CHROME_VERSION/Google Chrome Framework.framework/Versions/A/Libraries/WidevineCdm/_platform_specific/mac_(x86|x64)/ directory.
Note: Make sure that chrome version used by Electron is greater than or equal to the min_chrome_version value of Chrome's widevine cdm component. The value can be found in manifest.json under WidevineCdm directory.
After getting the library files, you should pass the path to the file with --widevine-cdm-path command line switch, and the library's version with --widevine-cdm-version switch. The command line switches have to be passed before the ready event of app module gets emitted.
示例代码：
\nconst { app, BrowserWindow } = require('electron')\n\n// You have to pass the directory that contains widevine library here, it is\n// * `libwidevinecdm.dylib` on macOS,\n// * `widevinecdm.dll` on Windows.\napp.commandLine.appendSwitch('widevine-cdm-path', '/path/to/widevine_library')\n// The version of plugin can be got from `chrome://components` page in Chrome.\napp.commandLine.appendSwitch('widevine-cdm-version', '1.4.8.866')\n\nlet win = null\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.show()\n})\nTo verify whether widevine works, you can use following ways:
\nWidevine 的 manifest。bitdash uses Widevine in your browser，然后播放 video。icon NativeImage - The icon showing in thumbnail toolbar.click Functiontooltip String (optional) - The text of the button's tooltip.flags String - Control specific states and behaviors of the button. By default, it is ['enabled'].The flags is an array that can include following Strings:
enabled - The button is active and available to the user.disabled - The button is disabled. It is present, but has a visual state indicating it will not respond to user action.dismissonclick - When the button is clicked, the thumbnail window closes immediately.nobackground - Do not draw a button border, use only the image.hidden - The button is not shown to the user.noninteractive - The button is enabled but not interactive; no pressed button state is drawn. This value is intended for instances where the button is used in a notification.\n\n为原生macOS应用创建TouchBar布局
\n
进程：主进程
\nnew TouchBar(options)选项 对象items (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer)escapeItem (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer | null) (可选的)Creates a new touch bar with the specified items. Use BrowserWindow.setTouchBar to add the TouchBar to a window.
注意: TouchBar API目前为实验性质，可能会更改或删除。
\nTip: If you don't have a MacBook with Touch Bar, you can use Touch Bar Simulator to test Touch Bar usage in your app.
\nTouchBarButtonA typeof TouchBarButton reference to the TouchBarButton class.
TouchBarColorPickerA typeof TouchBarColorPicker reference to the TouchBarColorPicker class.
TouchBarGroupA typeof TouchBarGroup reference to the TouchBarGroup class.
TouchBarLabelA typeof TouchBarLabel reference to the TouchBarLabel class.
TouchBarPopoverA typeof TouchBarPopover reference to the TouchBarPopover class.
TouchBarScrubberA typeof TouchBarScrubber reference to the TouchBarScrubber class.
TouchBarSegmentedControlA typeof TouchBarSegmentedControl reference to the TouchBarSegmentedControl class.
TouchBarSliderA typeof TouchBarSlider reference to the TouchBarSlider class.
TouchBarSpacerA typeof TouchBarSpacer reference to the TouchBarSpacer class.
TouchBarOtherItemsProxyA typeof TouchBarOtherItemsProxy reference to the TouchBarOtherItemsProxy class.
在TouchBar的实例中有以下属性可用：
touchBar.escapeItemTouchBarItem设置的内容将替换掉Touch bar中的“esc”按钮 将该项设为null以使用默认的\"esc\"按钮 修改这个值将立即更新Touch bar中的返回按钮
下面是一个带有一个按钮和若干文本的简易Touch bar老虎机游戏示例
\nconst { app, BrowserWindow, TouchBar } = require('electron')\n\nconst { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar\n\nlet spinning = false\n\n// Reel labels\nconst reel1 = new TouchBarLabel()\nconst reel2 = new TouchBarLabel()\nconst reel3 = new TouchBarLabel()\n\n// Spin result label\nconst result = new TouchBarLabel()\n\n// Spin button\nconst spin = new TouchBarButton({\n label: '🎰 Spin',\n backgroundColor: '#7851A9',\n click: () => {\n // Ignore clicks if already spinning\n if (spinning) {\n return\n }\n\n spinning = true\n result.label = ''\n\n let timeout = 10\n const spinLength = 4 * 1000 // 4 seconds\n const startTime = Date.now()\n\n const spinReels = () => {\n updateReels()\n\n if ((Date.now() - startTime) >= spinLength) {\n finishSpin()\n } else {\n // Slow down a bit on each spin\n timeout *= 1.1\n setTimeout(spinReels, timeout)\n }\n }\n\n spinReels()\n }\n})\n\nconst getRandomValue = () => {\n const values = ['🍒', '💎', '7️⃣', '🍊', '🔔', '⭐', '🍇', '🍀']\n return values[Math.floor(Math.random() * values.length)]\n}\n\nconst updateReels = () => {\n reel1.label = getRandomValue()\n reel2.label = getRandomValue()\n reel3.label = getRandomValue()\n}\n\nconst finishSpin = () => {\n const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size\n if (uniqueValues === 1) {\n // All 3 values are the same\n result.label = '💰 Jackpot!'\n result.textColor = '#FDFF00'\n } else if (uniqueValues === 2) {\n // 2 values are the same\n result.label = '😍 Winner!'\n result.textColor = '#FDFF00'\n } else {\n // No values are the same\n result.label = '🙁 Spin Again'\n result.textColor = null\n }\n spinning = false\n}\n\nconst touchBar = new TouchBar({\n items: [\n spin,\n new TouchBarSpacer({ size: 'large' }),\n reel1,\n new TouchBarSpacer({ size: 'small' }),\n reel2,\n new TouchBarSpacer({ size: 'small' }),\n reel3,\n new TouchBarSpacer({ size: 'large' }),\n result\n ]\n})\n\nlet window\n\napp.whenReady().then(() => {\n window = new BrowserWindow({\n frame: false,\n titleBarStyle: 'hiddenInset',\n width: 200,\n height: 200,\n backgroundColor: '#000'\n })\n window.loadURL('about:blank')\n window.setTouchBar(touchBar)\n})\n要运行上面的示例，您需要 (假设您已经在将要运行该示例的目录中打开了一个终端)：
\ntouchbar.jsnpm install electron 来安装 Electron./node_modules/.bin/electron touchbar.js接下来这个应用会在你的Touch bar (或者Touch bar模拟器) 上运行，你将能看到一个Electron窗口
", "title": "触控板", "description": "为原生macOS应用创建TouchBar布局" }, "/docs/api/touch-bar-button": { "locale": "zh-CN", "slug": "touch-bar-button", "href": "/docs/api/touch-bar-button", "crowdinFileId": "256375", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/touch-bar-button.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n为mac os应用在touch bar中创建一个按钮组件
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarButton(options)选项 对象labelString (可选) 按钮文本。accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.backgroundColorString (可选) - 按钮背景颜色以十六进制格式，例如 #ABCDEF。icon NativeImage | String (optional) - Button icon.iconPositionString (可选) - 可以是 left、 right 或 overlay。 默认值为 overlay。clickfunction (可选) - 单击按钮时调用的函数。enabled Boolean (optional) - Whether the button is in an enabled state. 默认值为 true。When defining accessibilityLabel, ensure you have considered macOS best practices.
下面的这些是TouchBarButton中的属性：
touchBarButton.accessibilityLabelA String representing the description of the button to be read by a screen reader. Will only be read by screen readers if no label is set.
touchBarButton.labelA String representing the button's current text. Changing this value immediately updates the button in the touch bar.
touchBarButton.backgroundColorA String hex code representing the button's current background color. Changing this value immediately updates the button in the touch bar.
touchBarButton.iconA NativeImage representing the button's current icon. Changing this value immediately updates the button in the touch bar.
touchBarButton.iconPositionA String - Can be left, right or overlay. 默认值为 overlay。
touchBarButton.enabledA Boolean representing whether the button is in an enabled state.
\n\n在macOS 应用程序中，为触控栏创建拾色器
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarColorPicker(options)选项 对象以下为TouchBarColorPicker 实例的可用属性:
touchBarColorPicker.availableColorsA String[] array representing the color picker's available colors to select. Changing this value immediately updates the color picker in the touch bar.
touchBarColorPicker.selectedColorA String hex code representing the color picker's currently selected color. Changing this value immediately updates the color picker in the touch bar.
\n\n为本地mac os创建一个触控条组
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarGroup(options)选项 对象items TouchBar - 以分组的方式显示元素.\n\n在原生macOS应用程序的触摸栏中创建一个标签
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarLabel(options)选项 对象label String (可选) - 显示的文本.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.textColor String（可选） - 文本的十六进制颜色，例如#ABCDEF。When defining accessibilityLabel, ensure you have considered macOS best practices.
以下属性可用于 TouchBarLabel:
touchBarLabel.labelA String representing the label's current text. Changing this value immediately updates the label in the touch bar.
touchBarLabel.accessibilityLabelA String representing the description of the label to be read by a screen reader.
touchBarLabel.textColorA String hex code representing the label's current text color. Changing this value immediately updates the label in the touch bar.
\n\nInstantiates a special \"other items proxy\", which nests TouchBar elements inherited from Chromium at the space indicated by the proxy. By default, this proxy is added to each TouchBar at the end of the input. For more information, see the AppKit docs on NSTouchBarItemIdentifierOtherItemsProxy
\nNote: Only one instance of this class can be added per TouchBar.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarOtherItemsProxy()\n\n为macOS原生应用在触摸栏中创建一个弹出控件
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarPopover(options)选项 对象labelString (可选) 弹出按钮文本。icon (NativeImage | String) (可选) - 弹出按钮图标。items TouchBar - Items to display in the popover.showCloseButton Boolean (optional) - true to display a close button on the left of the popover, false to not show it. 默认值为 true。以下为 TouchBarPopover 实例的可用属性:
touchBarPopover.labelA String representing the popover's current button text. Changing this value immediately updates the popover in the touch bar.
touchBarPopover.iconA NativeImage representing the popover's current button icon. Changing this value immediately updates the popover in the touch bar.
\n\n创建一个scrubber (可滚动的选择程序)
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarScrubber(options)选项 对象items ScrubberItem[] 一个数组，表示 scrubber 里的项目。select Function (optional) - Called when the user taps an item that was not the last tapped item.selectedIndex Integer - 用户选中项排序。highlight Function (optional) - Called when the user taps any item.selectedStyle String (optional) - Selected item style. Can be background, outline or none. 默认值为：none。overlayStyle String (optional) - Selected overlay item style. Can be background, outline or none. 默认值为：none。showArrowButtons Boolean (可选) - 是否在任务栏中显示窗口。 默认为 false 并且只在 items 是非空的情况下才显示。mode String (可选) - 可以是 fixed 或 free。 默认值为free.continuous Boolean (optional) - Defaults to true.以下为 TouchBarScrubber 实例的可用属性:
touchBarScrubber.items一个Scrubberitem[] 数组代表Scrubber里的所有物品。 改变这个值会立刻刷新touch bar内的控件。 然而改变数组某元素内的嵌套属性不会刷新touch bar。
\ntouchBarScrubber.selectedStyle一个String，用来表示在scrubber内被选择的组件应有的样式。 改变这个值会立刻刷新touch bar内的控件。 可选值：
background - 映射为[NSScrubberSelectionStyle roundedBackgroundStyle]outline - 映射为[NSScrubberSelectionStyle outlineOverlayStyle]none - Removes all styles.touchBarScrubber.overlayStyle一个String，用来表示在scrubber内被选择的组件应有的样式。 该样式将会覆盖在scrubber组件之上而非其后。 改变这个值会立刻刷新touch bar的控件。 可选值：
background - 映射为[NSScrubberSelectionStyle roundedBackgroundStyle]outline - 映射为[NSScrubberSelectionStyle outlineOverlayStyle]none - Removes all styles.touchBarScrubber.showArrowButtonsA Boolean representing whether to show the left / right selection arrows in this scrubber. Updating this value immediately updates the control in the touch bar.
touchBarScrubber.modeA String representing the mode of this scrubber. 改变这个值会立刻刷新touch bar内的控件。 可选值：
fixed - 映射到NSScrubberModeFixedfree - 映射到NSScrubberModeFree.touchBarScrubber.continuousA Boolean representing whether this scrubber is continuous or not. 改变这个值会立刻刷新touch bar内的控件。
\n\n创建一个分段控件（按钮组），其中一个按钮具有选定状态
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSegmentedControl(options)选项 对象segmentStyle String (optional) - Style of the segments:automatic - Default. The appearance of the segmented control is automatically determined based on the type of window in which the control is displayed and the position within the window. Maps to NSSegmentStyleAutomatic.rounded - 控件的呈现使用圆形风格。 Maps to NSSegmentStyleRounded.textured-rounded - 控件的呈现使用纹理圆形风格。 Maps to NSSegmentStyleTexturedRounded.round-rect - 以圆角矩形样式显示控件。 Maps to NSSegmentStyleRoundRect.round-rect - 以带纹理的矩形样式显示控件。 Maps to NSSegmentStyleTexturedSquare.capsule - 以胶囊样式的风格显示控件 Maps to NSSegmentStyleCapsule.small-square - 以小尺寸的矩形样式显示控件 Maps to NSSegmentStyleSmallSquare.NSSegmentStyleSeparated.mode String (optional) - The selection mode of the control:single - Default. One item selected at a time, selecting one deselects the previously selected item. Maps to NSSegmentSwitchTrackingSelectOne.multiple - 可以选多个项。 Maps to NSSegmentSwitchTrackingSelectAny.buttons - 将段作为按钮使用, 每一段都可以被按下和释放但是不会被标记为激活状态 Maps to NSSegmentSwitchTrackingMomentary.segments SegmentedControlSegment[] - 被放到控件中的段的集合selectedIndex Integer (optional) - 当前选中的段的下标, 这个值会在用户交互时自动更改 When the mode is multiple it will be the last selected item.change Function (optional) - Called when the user selects a new segment.selectedIndex Integer - 用户选中的段的下标。isSelected Boolean - 当前段的选中状态以下为 TouchBarSegmentedControl 实例的可用属性:
touchBarSegmentedControl.segmentStyleA String representing the controls current segment style. Updating this value immediately updates the control in the touch bar.
touchBarSegmentedControl.segmentsSegmentedControlSegment[]类型表示的控件中段的集合 改变这个值会立刻刷新touch bar内的控件。 然而改变数组某元素内的嵌套属性不会刷新touch bar。
touchBarSegmentedControl.selectedIndexInteger类型表示的当前选中段 改变这个值会立即触发更新当前段 用户对触摸条的操作会自动更新这个值
touchBarSegmentedControl.modeA String representing the current selection mode of the control. Can be single, multiple or buttons.
\n\n为本机 macOS 应用程序在触摸栏中创建滑块
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSlider(options)选项 对象label String (可选) - 标签文本.value Integer (可选) - 选中值.minValue Integer (可选) - 最小值.maxValue Integer (可选) - 最大值.change Function (optional) - Function to call when the slider is changed.newValue Number - 用户选中的值.以下为 TouchBarSlider 实例的可用属性:
touchBarSlider.labelA String representing the slider's current text. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.valueA Number representing the slider's current value. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.minValueA Number representing the slider's current minimum value. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.maxValueA Number representing the slider's current maximum value. Changing this value immediately updates the slider in the touch bar.
\n\n在mac os应用中，为touch bar中的相邻项之间留白
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSpacer(options)选项 对象size String (optional) - Size of spacer, possible values are:small-项之间的留较小间距。 Maps to NSTouchBarItemIdentifierFixedSpaceSmall. 默认为该值。large-项之间的留较大间距。 Maps to NSTouchBarItemIdentifierFixedSpaceLarge.flexible-补齐所有可用空间。 Maps to NSTouchBarItemIdentifierFlexibleSpace.以下属性可用于 TouchBarSpacer:
touchBarSpacer.sizeA String representing the size of the spacer. Can be small, large or flexible.
categoryFilter String - A filter to control what category groups should be traced. A filter can have an optional '-' prefix to exclude category groups that contain a matching category. Having both included and excluded category patterns in the same list is not supported. Examples: test_MyTest*, test_MyTest*,test_OtherStuff, -excluded_category1,-excluded_category2.traceOptions String - Controls what kind of tracing is enabled, it is a comma-delimited sequence of the following strings: record-until-full, record-continuously, trace-to-console, enable-sampling, enable-systrace, e.g. 'record-until-full,enable-sampling'. The first 3 options are trace recording modes and hence mutually exclusive. If more than one trace recording modes appear in the traceOptions string, the last one takes precedence. If none of the trace recording modes are specified, recording mode is record-until-full. The trace option will first be reset to the default option (record_mode set to record-until-full, enable_sampling and enable_systrace set to false) before options parsed from traceOptions are applied on it.recording_mode String (optional) - Can be record-until-full, record-continuously, record-as-much-as-possible or trace-to-console. Defaults to record-until-full.trace_buffer_size_in_kb number (optional) - maximum size of the trace recording buffer in kilobytes. Defaults to 100MB.trace_buffer_size_in_events number (optional) - maximum size of the trace recording buffer in events.enable_argument_filter boolean (optional) - if true, filter event data according to a specific list of events that have been manually vetted to not include any PII. See the implementation in Chromium for specifics.included_categories String - a list of tracing categories to include. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.excluded_categories String - a list of tracing categories to exclude. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.included_process_ids number - a list of process IDs to include in the trace. If not specified, trace all processes.histogram_names String - a list of histogram names to report with the trace.memory_dump_config Record<String, any> (optional) - if the disabled-by-default-memory-infra category is enabled, this contains optional additional configuration for data collection. See the Chromium memory-infra docs for more information.An example TraceConfig that roughly matches what Chrome DevTools records:
\n{\n recording_mode: 'record-until-full',\n included_categories: [\n 'devtools.timeline',\n 'disabled-by-default-devtools.timeline',\n 'disabled-by-default-devtools.timeline.frame',\n 'disabled-by-default-devtools.timeline.stack',\n 'v8.execute',\n 'blink.console',\n 'blink.user_timing',\n 'latencyInfo',\n 'disabled-by-default-v8.cpu_profiler',\n 'disabled-by-default-v8.cpu_profiler.hires'\n ],\n excluded_categories: ['*']\n}\ntransactionIdentifier String - A string that uniquely identifies a successful payment transaction.transactionDate String - The date the transaction was added to the App Store’s payment queue.originalTransactionIdentifier String - The identifier of the restored transaction by the App Store.transactionState String - The transaction state, can be purchasing, purchased, failed, restored or deferred.errorCode Integer - The error code if an error occurred while processing the transaction.errorMessage String - The error message if an error occurred while processing the transaction.payment ObjectproductIdentifier String - The identifier of the purchased product.quantity Integer - The quantity purchased.\n\n添加图标和上下文菜单到系统通知区
\n
进程：主进程
\nTray是一个EventEmitter.
const { app, Menu, Tray } = require('electron')\n\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n ])\n tray.setToolTip('This is my application.')\n tray.setContextMenu(contextMenu)\n})\n平台限制：
\nGtkStatusIcon。libappindicator1才能使任务栏图标正常工作。click事件将被忽略MenuItems to take effect, you have to call setContextMenu again. 例如：const { app, Menu, Tray } = require('electron')\n\nlet appIcon = null\napp.whenReady().then(() => {\n appIcon = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' }\n ])\n\n // Make a change to the context menu\n contextMenu.items[1].checked = false\n\n // Call this again for Linux because we modified the context menu\n appIcon.setContextMenu(contextMenu)\n})\nICO 图标来获得最佳视觉效果。如果要在所有平台上保持完全相同的行为, 则不应依赖 click 事件, 并且始终将上下文菜单附加到任务栏图标。
new Tray(image, [guid])image (NativeImage | String)guid String (optional) Windows - Assigns a GUID to the tray icon. If the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. OS level settings like the position of the tray icon in the system tray will persist even if the path to the executable changes. If the executable is not code-signed then the GUID is permanently associated with the path to the executable. Changing the path to the executable will break the creation of the tray icon and a new GUID must be used. However, it is highly recommended to use the GUID parameter only in conjunction with code-signed executable. If an App defines multiple tray icons then each icon must use a separate GUID.创建与image关联的新任务栏图标。
Tray 对象会发出以下事件:
返回:
\nevent KeyboardEventbounds Rectangle - 系统托盘图标的边界。position Point - 事件的位置信息。当该图标被点击时触发。
\n返回:
\nevent KeyboardEventbounds Rectangle - 系统托盘图标的边界。当该图标被右击时触发。
\n返回:
\nevent KeyboardEventbounds Rectangle - 系统托盘图标的边界。当该图标被双击时触发。
\n当系统托盘图标气泡显示时，触发该事件。
\n当系统托盘气泡被点击时，触发该事件。
\n当系统托盘气泡因为超时被关闭或者用户手动关闭时，触发该事件。
\n当有任何拖动项拖到该任务栏图标上时，触发该事件。
\n返回:
\nevent Eventfiles String[] - 拖至任务栏图标上的文件的路径。当有任何文件被拖到该任务栏图标上时，触发该事件。
\n返回:
\nevent Eventtext String - 拖至任务栏图标上的文字内容。当有任何文字被拖到该任务栏图标上时，触发该事件。
\n当有任何拖动操作进入（拖动未结束）该任务栏图标时，触发该事件。
\n当有任何拖动操作离开该任务栏图标时，触发该事件。
\n当有任何拖动操作在托盘或其他地方结束时，触发该事件。
\n返回:
\nevent KeyboardEventposition Point - 事件的位置信息。Emitted when the mouse is released from clicking the tray icon.
\nNote: This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.
返回:
\nevent KeyboardEventposition Point - 事件的位置信息。Emitted when the mouse clicks the tray icon.
\n返回:
\nevent KeyboardEventposition Point - 事件的位置信息。当鼠标进入该任务栏图标时，触发该事件。
\n返回:
\nevent KeyboardEventposition Point - 事件的位置信息。当鼠标离开该任务栏图标时，触发该事件。
\n返回:
\nevent KeyboardEventposition Point - 事件的位置信息。当鼠标在该任务栏图标上移动时，触发该事件。
\nTray 类拥有以下方法:
tray.destroy()立即销毁该任务栏图标
\ntray.setImage(image)image (NativeImage | String)设置image作为托盘中显示的图标
tray.setPressedImage(image) macOSimage (NativeImage | String)在 macOS 中，设置image作为托盘图标被按下时显示的图标
tray.setToolTip(toolTip)toolTip String设置鼠标指针在托盘图标上悬停时显示的文本
\ntray.setTitle(title[, options]) macOStitle Stringoptions Object (可选)fontType String (optional) - The font family variant to display, can be monospaced or monospacedDigit. monospaced is available in macOS 10.15+ and monospacedDigit is available in macOS 10.11+. When left blank, the title uses the default system font.Sets the title displayed next to the tray icon in the status bar (Support ANSI colors).
\ntray.getTitle() macOSReturns String - the title displayed next to the tray icon in the status bar
tray.setIgnoreDoubleClickEvents(ignore) macOSignore BooleanSets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.
\nThis value is set to false by default.
\ntray.getIgnoreDoubleClickEvents() macOSReturns Boolean - Whether double click events will be ignored.
tray.displayBalloon(options) Windows选项 对象icon (NativeImage | String) (optional) - Icon to use when iconType is custom.iconType String (optional) - Can be none, info, warning, error or custom. 默认值为 custom.title Stringcontent StringlargeIcon Boolean (optional) - The large version of the icon should be used. 默认值为 true。 Maps to NIIF_LARGE_ICON.noSound Boolean (optional) - Do not play the associated sound. 默认值为 false. Maps to NIIF_NOSOUND.respectQuietTime Boolean (optional) - Do not display the balloon notification if the current user is in \"quiet time\". 默认值为 false. Maps to NIIF_RESPECT_QUIET_TIME.显示一个托盘气球通知.
\ntray.removeBalloon() WindowsRemoves a tray balloon.
\ntray.focus() WindowsReturns focus to the taskbar notification area. Notification area icons should use this message when they have completed their UI operation. For example, if the icon displays a shortcut menu, but the user presses ESC to cancel it, use tray.focus() to return focus to the notification area.
tray.popUpContextMenu([menu, position]) macOS Windowsmenu Menu (可选)position Point (可选) - 菜单弹出的位置.Pops up the context menu of the tray icon. When menu is passed, the menu will be shown instead of the tray icon's context menu.
参数 position 只在 Windows 上可用， 并拥有默认值 (0, 0)。
tray.closeContextMenu() macOS WindowsCloses an open context menu, as set by tray.setContextMenu().
tray.setContextMenu(menu)menu Menu | null设置这个图标的内容菜单
\ntray.getBounds() macOS Windows返回 Rectangle
以Object类型返回托盘图标的bounds
tray.isDestroyed()返回 Boolean -判断托盘图标是否被销毁
title: Tray\ndescription: This guide will take you through the process of creating a Tray icon with its own context menu to the system's notification area.\nslug: tray
\nThis guide will take you through the process of creating a Tray icon with its own context menu to the system's notification area.
\nOn MacOS and Ubuntu, the Tray will be located on the top right corner of your screen, adjacent to your battery and wifi icons. On Windows, the Tray will usually be located in the bottom right corner.
\nFirst we must import app, Tray, Menu, nativeImage from electron.
const { app, Tray, Menu, nativeImage } = require('electron')\nNext we will create our Tray. To do this, we will use a NativeImage icon, which can be created through any one of these methods. Note that we wrap our Tray creation code within an app.whenReady as we will need to wait for our electron app to finish initializing.
let tray\n\napp.whenReady().then(() => {\n const icon = nativeImage.createFromPath('path/to/asset.png')\n tray = new Tray(icon)\n\n // note: your contextMenu, Tooltip and Title code will go here!\n})\n太好了！ Now we can start attaching a context menu to our Tray, like so:
\nconst contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n])\n\ntray.setContextMenu(contextMenu)\nThe code above will create 4 separate radio-type items in the context menu. To read more about constructing native menus, click here.
\nFinally, let's give our tray a tooltip and a title.
\ntray.setToolTip('This is my application')\ntray.setTitle('This is my title')\nAfter you start your electron app, you should see the Tray residing in either the top or bottom right of your screen, depending on your operating system.\nfiddle docs/fiddles/native-ui/tray
有多种方法可以更新Electron应用. 最简单并且获得官方支持的方法是利用内置的Squirrel框架和Electron的autoUpdater模块。
\nupdate.electronjs.orgElectron 团队维护 update.electronjs.org，一个免费开源的网络服务，可以让 Electron 应用使用自动更新。 这个服务是设计给那些满足以下标准的 Electron 应用：
\n使用这个服务最简单的方法是安装 update-electron-app，一个预配置好的 Node.js 模块来使用 update.electronjs.org。
\n安装模块
\nnpm install update-electron-app\n从你的应用的 main process 文件调用这个更新：
\nrequire('update-electron-app')()\n默认情况下，这个模块会在应用启动的时候检查更新，然后每隔十分钟再检查一次。 当发现了一个更新，它会自动在后台下载。 当下载完成后，会显示一个对话框以允许用户重启应用。
\n如果你需要定制化你的配置，你可以 将配置设置传递给 update-electron-app 或者 直接使用更新服务。
如果你开发的是一个私有的 Electron 应用程序，或者你没有在 GitHub Releases 中公开发布，你可能需要运行自己的更新服务器。
\n根据你的需要，你可以从下方选择：
\n一旦你部署了更新服务器, 继续导入你所需要的代码模块. 下列代码可能因不同的服务器软件而变化，但它的工作原理就像使用Hazel所描述的那样。
\n重要: 请确保下面的代码只在打包的应用程序, 而不是开发中. 你可以使用electron-is-dev检查当前环境.
\nconst { app, autoUpdater, dialog } = require('electron')\n下一步, 构建更新服务器的URL并且通知autoUpdater:
\nconst server = 'https://your-deployment-url.com'\nconst url = `${server}/update/${process.platform}/${app.getVersion()}`\n\nautoUpdater.setFeedURL({ url })\nAs the final step, check for updates. The example below will check every minute:
\nsetInterval(() => {\n autoUpdater.checkForUpdates()\n}, 60000)\n应用程序被packaged后, 它将接收你每次发布在GitHub Release上的的更新。
\n现在您已经为应用程序配置了基本的更新机制, 您需要确保在更新时通知用户. 这可以使用autoUpdater API events来实现:
\nautoUpdater.on('update-downloaded', (event, releaseNotes, releaseName) => {\n const dialogOpts = {\n type: 'info',\n buttons: ['Restart', 'Later'],\n title: 'Application Update',\n message: process.platform === 'win32' ? releaseNotes : releaseName,\n detail: 'A new version has been downloaded. Restart the application to apply the updates.'\n }\n\n dialog.showMessageBox(dialogOpts).then((returnValue) => {\n if (returnValue.response === 0) autoUpdater.quitAndInstall()\n })\n})\nAlso make sure that errors are being handled. 下面是将错误日志输出到标准输出的例子。
autoUpdater.on('error', message => {\n console.error('There was a problem updating the application')\n console.error(message)\n})\nBecause the requests made by Auto Update aren't under your direct control, you may find situations that are difficult to handle (such as if the update server is behind authentication). The url field does support files, which means that with some effort, you can sidestep the server-communication aspect of the process. Here's an example of how this could work.
bytes Buffer - Content being sent.file String (optional) - Path of file being uploaded.blobUUID String (optional) - UUID of blob data. Use ses.getBlobData method to retrieve the data.type 'file' - file.filePath String - Path of file to be uploaded.offset Integer - Defaults to 0.length Integer - Number of bytes to read from offset. Defaults to 0.modificationTime Double - Last Modification time in number of seconds since the UNIX epoch.type 'rawData' - rawData.bytes Buffer - Data to be uploaded.string Stringboolean Booleaninteger Numberfloat Numberdouble Numberurl Stringarray Array\\dictionary Record\\<string, unknown>This type is a helper alias, no object will never exist of this type.
", "title": "UserDefaultTypes Object", "description": "" }, "/docs/tutorial/using-native-node-modules": { "locale": "zh-CN", "slug": "using-native-node-modules", "href": "/docs/tutorial/using-native-node-modules", "crowdinFileId": "256263", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-native-node-modules.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "原生Node.js模块由Electron支持，但由于Electron具有与给定Node.js不同的 应用二进制接口 (ABI)(由于使用Chromium的 BoringSL 而不是 OpenSSL 等 差异)，您使用的原生 模块需要为Electron重新编译。 否则，当您尝试运行您的应用程序时， 将会遇到以下的错误：
\nError: The module '/path/to/native/module.node'\nwas compiled against a different Node.js version using\nNODE_MODULE_VERSION $XYZ. This version of Node.js requires\nNODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing\nthe module (for instance, using `npm rebuild` or `npm install`).\n有多种不同的方法来安装原生模块：
\n您可以像其他 Node 项目一样安装模块，然后用 electron-rebuild 包重建这些模块以适配 Electron 。 这个包可以自动识别当前 Electron 版本，为你的应用自动完成下载 headers、重新编译原生模块等步骤。 如果您正在使用 Electron Forge，这个工具将在开发模式和发布时自动使用。
For example, to install the standalone electron-rebuild tool and then rebuild modules with it via the command line:
npm install --save-dev electron-rebuild\n\n# Every time you run \"npm install\", run this:\n./node_modules/.bin/electron-rebuild\n\n# If you have trouble on Windows, try:\n.\\node_modules\\.bin\\electron-rebuild.cmd\nFor more information on usage and integration with other tools such as Electron Packager, consult the project's README.
\nnpm 安装只要设置一些系统环境变量，你就可以通过 npm 直接安装原生模块。
例如，要安装所有Electron的依赖：
\n# Electron 的版本。\nexport npm_config_target=1.2.3\n# Electron的目标架构, 可用的架构列表请参见\n# https://electronjs.org/docs/tutorial/support#supported-platforms\nexport npm_config_arch=x64\nexport npm_config_target_arch=x64\n# 下载 Electron 的 headers。\nexport npm_config_disturl=https://electronjs.org/headers\n# 告诉 node-pre-gyp 我们是在为 Electron 生成模块。\nexport npm_config_runtime=electron\n# 告诉 node-pre-gyp 从源代码构建模块。\nexport npm_config_build_from_source=true\n# 安装所有依赖，并缓存到 ~/.electron-gyp。\nHOME=~/.electron-gyp npm install\n如果你是一个原生模块的开发人员，想在 Electron 中进行测试， 你可能要手动编译 Electron 模块。 你可以 使用 node-gyp 直接编译：
cd /path-to-module/\nHOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://electronjs.org/headers\nHOME=~/.electron-gyp 设置去哪找头文件--target=1.2.3 设置了 Electron 的版本。--dist-url=...设置了 Electron 的 headers 的下载地址。--arch=x64 设置了该模块为适配64位操作系统而编译。如果是为一个与公共发行版不匹配的Electron自定义版本编译原生Node模块，需要让npm使用你的Electron自定义版本所对应的Node版本。
npm rebuild --nodedir=/path/to/src/out/Default/gen/node_headers\n如果您安装了本机模块并发现它无法正常工作，则需要检查以下内容：
\nelectron-rebuild。binding.gyp中win_delay_load_hook没有被设置为false。win_delay_load_hook的说明在Windows上，默认情况下，node-gyp将原生模块与node.dll链接。 然而，在Electron 4.x和更高的版本中，原生模块需要的symbols由electron.exe导出，并且没有node.dll。 In order to load native modules on Windows, node-gyp installs a delay-load hook that triggers when the native module is loaded, and redirects the node.dll reference to use the loading executable instead of looking for node.dll in the library search path (which would turn up nothing). As such, on Electron 4.x and higher, 'win_delay_load_hook': 'true' is required to load native modules.
If you get an error like Module did not self-register, or The specified procedure could not be found, it may mean that the module you're trying to use did not correctly include the delay-load hook. If the module is built with node-gyp, ensure that the win_delay_load_hook variable is set to true in the binding.gyp file, and isn't getting overridden anywhere. If the module is built with another system, you'll need to ensure that you build with a delay-load hook installed in the main .node file. Your link.exe invocation should look like this:
link.exe /OUT:\"foo.node\" \"...\\node.lib\" delayimp.lib /DELAYLOAD:node.exe /DLL\n \"my_addon.obj\" \"win_delay_load_hook.obj\"\nIn particular, it's important that:
\nnode.lib from Electron and not Node. If you link against the wrong node.lib you will get load-time errors when you require the module in Electron./DELAYLOAD:node.exe. If the node.exe link is not delayed, then the delay-load hook won't get a chance to fire and the node symbols won't be correctly resolved.win_delay_load_hook.obj is linked directly into the final DLL. If the hook is set up in a dependent DLL, it won't fire at the right time.See node-gyp for an example delay-load hook if you're implementing your own.
prebuild 的模块prebuild provides a way to publish native Node modules with prebuilt binaries for multiple versions of Node and Electron.
If the prebuild-powered module provide binaries for the usage in Electron, make sure to omit --build-from-source and the npm_config_build_from_source environment variable in order to take full advantage of the prebuilt binaries.
node-pre-gyp 的模块node-pre-gyp 工具 提供一种部署原生 Node 预编译二进制模块的方法， 许多流行的模块都是使用它。
Sometimes those modules work fine under Electron, but when there are no Electron-specific binaries available, you'll need to build from source. Because of this, it is recommended to use electron-rebuild for these modules.
If you are following the npm way of installing modules, you'll need to pass --build-from-source to npm, or set the npm_config_build_from_source environment variable.
Electron 不再支持 Pepper Flash 插件，因为 Chrome 已经移除了支持。
\n更多详细信息，请参阅 Chromium's Flash Roadmap
", "title": "Pepper Flash Plugin", "description": "" }, "/docs/tutorial/using-selenium-and-webdriver": { "locale": "zh-CN", "slug": "using-selenium-and-webdriver", "href": "/docs/tutorial/using-selenium-and-webdriver", "crowdinFileId": "256267", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-selenium-and-webdriver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "引自 ChromeDriver - WebDriver for Chrome:
\n\n\nWebDriver 是一款开源的支持多浏览器的自动化测试工具。 它提供了操作网页、用户输入、JavaScript 执行等能力。 ChromeDriver 是一个实现了 WebDriver 与 Chromium 联接协议的独立服务。 它也是由开发了 Chromium 和 WebDriver 的团队开发的。
\n
Spectron 是 Electron 官方支持的 ChromeDriver 测试框架。 它是建立在 WebdriverIO 的顶层，并且 帮助你在测试中访问 Electron API 和绑定 ChromeDriver。
\n$ npm install --save-dev spectron\n// 一个简单的验证测试和一个带标题的可视窗口\nconst Application = require('spectron').Application\nconst assert = require('assert')\n\nconst myApp = new Application({\n path: '/Applications/MyApp.app/Contents/MacOS/MyApp'\n})\n\nconst verifyWindowIsVisibleWithTitle = async (app) => {\n await app.start()\n try {\n // 检查窗口是否可见\n const isVisible = await app.browserWindow.isVisible()\n // 验证窗口是否可见\n assert.strictEqual(isVisible, true)\n // 获取窗口标题\n const title = await app.client.getTitle()\n // 验证窗口标题\n assert.strictEqual(title, 'My App')\n } catch (error) {\n // 记录任何故障\n console.error('Test failed', error.message)\n }\n // 停止应用\n await app.stop()\n}\n\nverifyWindowIsVisibleWithTitle(myApp)\nWebDriverJs 是一个可以配合 WebDriver 做测试的 node 模块，我们会用它来做个演示。
\n首先，你要下载 chromedriver，然后运行以下命令：
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\n记住 9515 这个端口号，我们后面会用到
$ npm install selenium-webdriver\n在 Electron 下使用 selenium-webdriver 和其平时的用法并没有大的差异，只是你需要手动设置连接 ChromeDriver，以及 Electron 的路径：
const webdriver = require('selenium-webdriver')\n\nconst driver = new webdriver.Builder()\n // \"9515\" 是ChromeDriver使用的端口\n .usingServer('http://localhost:9515')\n .withCapabilities({\n 'goog:chromeOptions': {\n // 这里填您的Electron二进制文件路径。\n binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'\n }\n })\n .forBrowser('chrome') // 注意: 使用 .forBrowser('electron') for selenium-webdriver <= 3.6.0\n .build()\n\ndriver.get('http://www.google.com')\ndriver.findElement(webdriver.By.name('q')).sendKeys('webdriver')\ndriver.findElement(webdriver.By.name('btnG')).click()\ndriver.wait(() => {\n return driver.getTitle().then((title) => {\n return title === 'webdriver - Google Search'\n })\n}, 1000)\n\ndriver.quit()\nWebdriverIO 也是一个配合 WebDriver 用来测试的 node 模块.
\n首先，你要下载 chromedriver，然后运行以下命令：
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver --url-base=wd/hub --port=9515\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\n记住 9515 这个端口号，我们后面会用到
$ npm install webdriverio\nconst webdriverio = require('webdriverio')\nconst options = {\n host: 'localhost', // Use localhost as chrome driver server\n port: 9515, // \"9515\" is the port opened by chrome driver.\n desiredCapabilities: {\n browserName: 'chrome',\n 'goog:chromeOptions': {\n binary: '/Path-to-Your-App/electron', // Path to your Electron binary.\n args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/\n }\n }\n}\n\nconst client = webdriverio.remote(options)\n\nclient\n .init()\n .url('http://google.com')\n .setValue('#q', 'webdriverio')\n .click('#btnG')\n .getTitle().then((title) => {\n console.log('Title was: ' + title)\n })\n .end()\n无需重新编译 Electron，只要把 app 的源码放到 Electron的资源目录 里就可直接开始测试了。
\nAlternatively, pass an argument to run with your Electron binary that points to your app's folder. 这就消除了将您的应用复制粘贴到 Electron 资源目录的必要性。
", "title": "Selenium and WebDriver", "description": "WebDriver 是一款开源的支持多浏览器的自动化测试工具。 它提供了操作网页、用户输入、JavaScript 执行等能力。 ChromeDriver 是一个实现了 WebDriver 与 Chromium 联接协议的独立服务。 它也是由开发了 Chromium 和 WebDriver 的团队开发的。" }, "/docs/development/v8-development": { "locale": "zh-CN", "slug": "v8-development", "href": "/docs/development/v8-development", "crowdinFileId": "256171", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/v8-development.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "\n\n学习和使用 v8 引擎的资源集合
\n
--prof, --trace-ic, --trace-opt, --trace-deopt, --print-bytecode, --print-opt-code\n\n渲染以及控制 web 页面
\n
进程：主进程
\nwebContents是一个EventEmitter. 负责渲染和控制网页, 是 BrowserWindow 对象的一个属性。 这是一个访问 webContents 对象的例子:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('http://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\n通过webContents模块可以访问以下方法：
const { webContents } = require('electron')\nconsole.log(webContents)\nwebContents.getAllWebContents()返回 WebContents[] - 所有 WebContents 实例的数组。 包含所有Windows，webviews，opened devtools 和 devtools 扩展背景页的 web 内容
webContents.getFocusedWebContents()Returns WebContents - 此 app 中焦点的 web 内容，否则返回 null。
webContents.fromId(id)id IntegerReturns WebContents | undefined - A WebContents instance with the given ID, or undefined if there is no WebContents associated with the given ID.
webContents.fromDevToolsTargetId(targetId)targetId String - The Chrome DevTools Protocol TargetID associated with the WebContents instance.Returns WebContents | undefined - A WebContents instance with the given TargetID, or undefined if there is no WebContents associated with the given TargetID.
When communicating with the Chrome DevTools Protocol, it can be useful to lookup a WebContents instance based on its assigned TargetID.
\nasync function lookupTargetId (browserWindow) {\n const wc = browserWindow.webContents\n await wc.debugger.attach('1.3')\n const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')\n const { targetId } = targetInfo\n const targetWebContents = await webContents.fromDevToolsTargetId(targetId)\n}\n\n\n渲染和控制 BrowserWindow 实例的内容。
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
导航完成时触发，即选项卡的旋转器将停止旋转，并指派onload事件后。
返回:
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId Integer这个事件类似于 did-finish-load ，只不过是在加载失败之后触发。 完整的错误码列表以及含义，请看这
返回:
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId Integer这个事件类似于 did-finish-load，只不过是在加载失败或取消加载之后触发，例如调用 window.stop() 。
返回:
\nevent EventisMainFrame BooleanframeProcessId IntegerframeRoutingId Integer当框架完成导航（navigation）时触发
\n当tab中的旋转指针（spinner）开始旋转时，就会触发该事件。
\n当tab中的旋转指针（spinner）结束旋转时，就会触发该事件。
\n返回:
\nevent EventEmitted when the document in the top-level frame is loaded.
\n返回:
\nevent Eventtitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when title is synthesized from file url.
返回:
\nevent Eventfavicons String[] - 由连接组成的数组。当页面获取到favicon的连接时，触发该事件。
\n返回:
\nevent NewWindowWebContentsEventurl StringframeName Stringdisposition String - 可以被设置为 default, foreground-tab, background-tab, new-window, save-to-disk 及 other.options BrowserWindowConstructorOptions - 用于创建新的 BrowserWindow.additionalFeatures String[] - 非标准功能(非标准功能是指这些功能不是由Chromium或Electron处理的功能)，这些功能默认指向window.open(). Deprecated, and will now always be the empty array [].referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.已弃用：webContents.setWindowOpenHandler。
Emitted when the page requests to open a new window for a url. It could be requested by window.open or an external link like <a target='_blank'>.
默认情况下, 将为 url 创建新的 BrowserWindow。
调用event.preventDefault()事件，可以阻止Electron自动创建新的BrowserWindow实例。 调用event.preventDefault() 事件后，你还可以手动创建新的BrowserWindow实例，不过接下来你必须用event.newGuest方法来引用BrowserWindow实例，如果你不这样做，则可能会产生异常。 例如：
myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {\n event.preventDefault()\n const win = new BrowserWindow({\n webContents: options.webContents, // use existing webContents if provided\n show: false\n })\n win.once('ready-to-show', () => win.show())\n if (!options.webContents) {\n const loadOptions = {\n httpReferrer: referrer\n }\n if (postBody != null) {\n const { data, contentType, boundary } = postBody\n loadOptions.postData = postBody.data\n loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`\n }\n\n win.loadURL(url, loadOptions) // existing webContents will be navigated automatically\n }\n event.newGuest = win\n})\n返回:
\nwindow BrowserWindowdetails Objecturl String - URL for the created window.frameName String - Name given to the created window in the window.open() call.options BrowserWindowConstructorOptions - The options used to create the BrowserWindow. They are merged in increasing precedence: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Unrecognized options are not filtered out.referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.Emitted after successful creation of a window via window.open in the renderer. Not emitted if the creation of the window is canceled from webContents.setWindowOpenHandler.
See window.open() for more details and how to use this in conjunction with webContents.setWindowOpenHandler.
返回:
\nevent Eventurl StringEmitted when a user or the page wants to start navigation. It can happen when the window.location object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with APIs like webContents.loadURL and webContents.back.
It is also not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
调用event.preventDefault()将阻止导航。
返回:
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be true for in-page navigations.
返回:
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted as a server side redirect occurs during navigation. For example a 302 redirect.
\nThis event will be emitted after did-start-navigation and always before the did-redirect-navigation event for the same navigation.
Calling event.preventDefault() will prevent the navigation (not just the redirect).
返回:
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nThis event cannot be prevented, if you want to prevent redirects you should checkout out the will-redirect event above.
返回:
\nevent Eventurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigationsEmitted when a main frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
返回:
\nevent Eventurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigations,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
返回:
\nevent Eventurl StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when an in-page navigation happened in any frame.
\n当发生页内导航时，虽然页面地址发生变化，但它并没有导航到其它页面。 例如，点击锚点链接，或者DOM的 hashchange事件被触发时，都会触发该事件。
返回:
\nevent EventEmitted when a beforeunload event handler is attempting to cancel a page unload.
Calling event.preventDefault() will ignore the beforeunload event handler and allow the page to be unloaded.
const { BrowserWindow, dialog } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.webContents.on('will-prevent-unload', (event) => {\n const choice = dialog.showMessageBoxSync(win, {\n type: 'question',\n buttons: ['Leave', 'Stay'],\n title: 'Do you want to leave this site?',\n message: 'Changes you made may not be saved.',\n defaultId: 0,\n cancelId: 1\n })\n const leave = (choice === 0)\n if (leave) {\n event.preventDefault()\n }\n})\nNote: This will be emitted for BrowserViews but will not be respected - this is because we have chosen not to tie the BrowserView lifecycle to its owning BrowserWindow should one exist per the specification.
返回:
\nevent Eventkilled Boolean当渲染进程崩溃或被结束时触发
\n已废弃： 此事件被包含更多关于渲染过程为何消失的信息的 render-process-gone 事件替代了 并不总是因为崩溃而触发。 当你换用child-process-gone事件时，原事件的 killed 布尔值可以被 reason === 'killed' 取代。
返回:
\nevent Eventdetails Objectreason String - 渲染进程消失的原因。 可选值：clean-exit - 以零为退出代码退出的进程abnormal-exit - 以非零退出代码退出的进程killed - 进程发送一个SIGTERM，否则是被外部杀死的。crashed - 进程崩溃oom - 进程内存不足launch-failed - 进程从未成功启动integrity-failure - 窗口代码完整性检查失败exitCode Integer - 进程的退出代码，除非在 reason 是 launch-failed 的情况下， exitCode 将是一个平台特定的启动失败错误代码。渲染器进程意外消失时触发。 这种情况通常因为进程崩溃或被杀死。
\n网页变得未响应时触发
\n未响应的页面变成响应时触发
\n返回:
\nevent Eventname Stringversion String当有插件进程崩溃时触发
\n当webContents被销毁时，触发该事件。
返回:
\nevent Eventinput Object - Input properties.type String - 可以是 keyUp ，或者 keyDown.key String - 等同于 KeyboardEvent.key.code String - 等同于 KeyboardEvent. code .isAutoRepeat String - 等同于 KeyboardEvent. repeat .isComposing Boolean - Equivalent to KeyboardEvent.isComposing.shift String - 等同于 KeyboardEvent.shiftKey .control String - 等同于 KeyboardEvent. controlKey .alt String - 等同于 KeyboardEvent. altKey .meta String - 等同于 KeyboardEvent. metaKey .location Number - Equivalent to KeyboardEvent.location.modifiers String[] - See InputEvent.modifiers.Emitted before dispatching the keydown and keyup events in the page. Calling event.preventDefault will prevent the page keydown/keyup events and the menu shortcuts.
To only prevent the menu shortcuts, use setIgnoreMenuShortcuts:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nwin.webContents.on('before-input-event', (event, input) => {\n // For example, only enable application menu keyboard shortcuts when\n // Ctrl/Cmd are down.\n win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)\n})\n窗口进入由HTML API 触发的全屏状态时触发
\n窗口离开由HTML API触发的全屏状态时触发
\n返回:
\nevent EventzoomDirection String - Can be in or out.Emitted when the user is requesting to change the zoom level using the mouse wheel.
\n当开发者工具被打开时，触发该事件。
\n当开发者工具被关闭时，触发该事件。
\n当开发者工具被选中/打开时，触发该事件。
\n返回:
\nevent Eventurl Stringerror String - The error code.certificate 证书callback FunctionisTrusted Boolean - 用于显示证书是否可信。isMainFrame Boolean证书的链接验证失败时，触发该事件。
使用方式与app的certificate-error的事件相同。
返回:
\nevent Eventurl URLcertificateList 证书[]callback Functioncertificate Certificate - Must be a certificate from the given list.当一个客户证书被请求的时候发出。
\n使用方式与app的select-client-certificate的事件相同。
返回:
\nevent EventauthenticationResponseDetails Objecturl URLauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (可选)password String (可选)当 webContents 要进行基本身份验证时触发。
使用方式与app的login的事件相同。
返回:
\nevent Eventresult ObjectrequestId IntegeractiveMatchOrdinal Integer - 当前匹配位置。matches Integer - 符合匹配条件的元素个数。selectionArea Rectangle - Coordinates of first match region.finalUpdate Boolean如果调用[webContents.findInPage]有返回时，会触发这一事件。
多媒体开始播放时，触发该事件。
\n当媒体文件暂停或播放完成的时候触发
\n返回:
\nevent Eventcolor (String | null) - Theme color is in format of '#rrggbb'. It is null when no theme color is set.Emitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\n返回:
\nevent Eventurl String当鼠标滑到，或者键盘切换到a连接时，触发该事件。
\n返回:
\nevent Eventtype Stringimage NativeImage (可选)scale Float (optional) - scaling factor for the custom cursor.size Size (可选) - image大小。hotspot Point (optional) - coordinates of the custom cursor's hotspot.当鼠标指针改变的时候触发。 Type参数值包含：default, crosshair, pointer, text, wait, help, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ns-resize, ew-resize, nesw-resize, nwse-resize, col-resize, row-resize, m-panning, e-panning, n-panning, ne-panning, nw-panning, s-panning, se-panning, sw-panning, w-panning, move, vertical-text, cell, context-menu, alias, progress, nodrop, copy, none, not-allowed, zoom-in, zoom-out, grab, grabbing 或 custom.
If the type parameter is custom, the image parameter will hold the custom cursor image in a NativeImage, and scale, size and hotspot will hold additional information about the custom cursor.
返回:
\nevent Eventparams Objectx Integer - x 坐标。y Integer - y 坐标。frame WebFrameMain - Frame from which the context menu was invoked.linkURL String - URL of the link that encloses the node the context menu was invoked on.linkText String - Text associated with the link. May be an empty string if the contents of the link are an image.pageURL String - URL of the top level page that the context menu was invoked on.frameURL String - URL of the subframe that the context menu was invoked on.srcURL String - Source URL for the element that the context menu was invoked on. Elements with source URLs are images, audio and video.mediaType String - Type of the node the context menu was invoked on. Can be none, image, audio, video, canvas, file or plugin.hasImageContents Boolean - Whether the context menu was invoked on an image which has non-empty contents.isEditable Boolean - Whether the context is editable.selectionText String - Text of the selection that the context menu was invoked on.titleText String - Title text of the selection that the context menu was invoked on.altText String - Alt text of the selection that the context menu was invoked on.suggestedFilename String - Suggested filename to be used when saving file through 'Save Link As' option of context menu.selectionRect Rectangle - Rect representing the coordinates in the document space of the selection.selectionStartOffset Number - Start position of the selection text.referrerPolicy Referrer - The referrer policy of the frame on which the menu is invoked.misspelledWord String - The misspelled word under the cursor, if any.dictionarySuggestions String[] - An array of suggested words to show the user to replace the misspelledWord. Only available if there is a misspelled word and spellchecker is enabled.frameCharset String - The character encoding of the frame on which the menu was invoked.inputFieldType String - If the context menu was invoked on an input field, the type of that field. Possible values are none, plainText, password, other.spellcheckEnabled Boolean - If the context is editable, whether or not spellchecking is enabled.menuSourceType String - Input source that invoked the context menu. 可以是 none、mouse、keyboard、touch、touchMenu、longPress、longTap、touchHandle、stylus、adjustSelection 或 adjustSelectionReset。mediaFlags Object - The flags for the media element the context menu was invoked on.inError Boolean - Whether the media element has crashed.isPaused Boolean - Whether the media element is paused.isMuted Boolean - Whether the media element is muted.hasAudio Boolean - Whether the media element has audio.isLooping Boolean - Whether the media element is looping.isControlsVisible Boolean - Whether the media element's controls are visible.canToggleControls Boolean - Whether the media element's controls are toggleable.canPrint Boolean - Whether the media element can be printed.canSave Boolean - Whether or not the media element can be downloaded.canShowPictureInPicture Boolean - Whether the media element can show picture-in-picture.isShowingPictureInPicture Boolean - Whether the media element is currently showing picture-in-picture.canRotate Boolean - Whether the media element can be rotated.canLoop Boolean - Whether the media element can be looped.editFlags Object - These flags indicate whether the renderer believes it is able to perform the corresponding action.canUndo Boolean - Whether the renderer believes it can undo.canRedo Boolean - Whether the renderer believes it can redo.canCut Boolean - Whether the renderer believes it can cut.canCopy Boolean - Whether the renderer believes it can copy.canPaste Boolean - Whether the renderer believes it can paste.canDelete Boolean - Whether the renderer believes it can delete.canSelectAll Boolean - Whether the renderer believes it can select all.canEditRichly Boolean - Whether the renderer believes it can edit text richly.Emitted when there is a new context menu that needs to be handled.
\n返回:
\nevent Eventdevices BluetoothDevice[]callback FunctiondeviceId String 设备IdEmitted when bluetooth device needs to be selected on call to navigator.bluetooth.requestDevice. To use navigator.bluetooth api webBluetooth should be enabled. If event.preventDefault is not called, first available device will be selected. callback should be called with deviceId to be selected, passing empty string to callback will cancel the request.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\napp.commandLine.appendSwitch('enable-experimental-web-platform-features')\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {\n event.preventDefault()\n const result = deviceList.find((device) => {\n return device.deviceName === 'test'\n })\n if (!result) {\n callback('')\n } else {\n callback(result.deviceId)\n }\n })\n})\n返回:
\nevent EventdirtyRect Rectangleimage NativeImage - The image data of the whole frame.Emitted when a new frame is generated. Only the dirty area is passed in the buffer.
\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ webPreferences: { offscreen: true } })\nwin.webContents.on('paint', (event, dirty, image) => {\n // updateBitmap(dirty, image.getBitmap())\n})\nwin.loadURL('http://github.com')\n当在开发者工具中命令webContents重新加载时，触发该事件。
\n返回:
\nevent EventwebPreferences WebPreferences - The web preferences that will be used by the guest page. This object can be modified to adjust the preferences for the guest page.params Record<string, string> - The other <webview> parameters such as the src URL. This object can be modified to adjust the parameters of the guest page.Emitted when a <webview>'s web contents is being attached to this web contents. Calling event.preventDefault() will destroy the guest page.
This event can be used to configure webPreferences for the webContents of a <webview> before it's loaded, and provides the ability to set settings that can't be set via <webview> attributes.
Note: The specified preload script option will appear as preloadURL (not preload) in the webPreferences object emitted with this event.
返回:
\nevent EventwebContents WebContents - The guest web contents that is used by the <webview>.当<webview>被挂载到页面内容中时，触发该事件。
返回:
\nevent Eventlevel Integer - The log level, from 0 to 3. 按顺序匹配 verbose, info, warning 和 error.message String - 实际控制台消息line Integer - The line number of the source that triggered this console messagesourceId StringEmitted when the associated window logs a console message.
\n返回:
\nevent EventpreloadPath Stringerror ErrorEmitted when the preload script preloadPath throws an unhandled exception error.
返回:
\nevent Eventchannel String...args any[]Emitted when the renderer process sends an asynchronous message via ipcRenderer.send().
返回:
\nevent Eventchannel String...args any[]Emitted when the renderer process sends a synchronous message via ipcRenderer.sendSync().
返回:
\nevent EventEmitted when desktopCapturer.getSources() is called in the renderer process. 调用 event.preventDefault() 将使它返回空的sources。
返回:
\nevent EventpreferredSize Size - The minimum size needed to contain the layout of the document—without requiring scrolling.Emitted when the WebContents preferred size has changed.
This event will only be emitted when enablePreferredSizeMode is set to true in webPreferences.
返回:
\nevent Eventdetails Objectframe WebFrameMainEmitted when the mainFrame, an <iframe>, or a nested <iframe> is loaded within the page.
contents.loadURL(url[, options])url Stringoptions Object (可选)httpReferrer (String | Referrer) (可选) - 一个 HTTP Referrer url。userAgent String (可选) - 发起请求的 userAgent.extraHeaders String (optional) - Extra headers separated by \"\\n\".postData (UploadRawData | UploadFile)baseURLForDataURL String (可选) - 要加载的数据文件的根 url(带有路径分隔符). 只有当指定的 url是一个数据 url 并需要加载其他文件时，才需要这样做。Returns Promise<void> - the promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load). A noop rejection handler is already attached, which avoids unhandled rejection errors.
Loads the url in the window. The url must contain the protocol prefix, e.g. the http:// or file://. If the load should bypass http cache then use the pragma header to achieve it.
const { webContents } = require('electron')\nconst options = { extraHeaders: 'pragma: no-cache\\n' }\nwebContents.loadURL('https://github.com', options)\ncontents.loadFile(filePath[, options])filePath Stringoptions Object (可选)query Record<String, String> (可选) - 传递给 url.format().search String (可选) - 传递给 url.format().hash String (可选) - 传递给 url.format().返回 Promise<void> - 当页面完成加载后 promise 将会resolve (见 did-finish-load)，如果页面加载失败，则 reject (见 did-fail-load)。
Loads the given file in the window, filePath should be a path to an HTML file relative to the root of your application. For instance an app structure like this:
| root\n| - package.json\n| - src\n| - main.js\n| - index.html\n需要运行以下代码：
\nwin.loadFile('src/index.html')\ncontents.downloadURL(url)url StringInitiates a download of the resource at url without navigating. The will-download event of session will be triggered.
contents.getURL()Returns String - 当前页面的URL.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com').then(() => {\n const currentURL = win.webContents.getURL()\n console.log(currentURL)\n})\ncontents.getTitle()返回 String - 当前页面的标题.
contents.isDestroyed()返回 Boolean -判断页面是否被销毁
contents.focus()页面聚焦
\ncontents.isFocused()返回 Boolean - 判断页面是否聚焦
contents.isLoading()返回 Boolean - 判断页面是否正在加载资源
contents.isLoadingMainFrame()Returns Boolean - Whether the main frame (and not just iframes or frames within it) is still loading.
contents.isWaitingForResponse()Returns Boolean - Whether the web page is waiting for a first-response from the main resource of the page.
contents.stop()Stops any pending navigation.
\ncontents.reload()刷新当前页面
\ncontents.reloadIgnoringCache()忽略缓存强制刷新页面
\ncontents.canGoBack()返回Boolean，是否可以返回到上一个页面
contents.canGoForward()返回Boolean ，是否可以进入下一个页面
contents.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the web page can go to offset.
contents.clearHistory()清除定位历史。
\ncontents.goBack()使浏览器回退到上一个页面。
\ncontents.goForward()使浏览器前进到下一个页面。
\ncontents.goToIndex(index)index IntegerNavigates browser to the specified absolute web page index.
\ncontents.goToOffset(offset)offset Integer定位到相对于“当前入口”的指定的偏移。
\ncontents.isCrashed()Returns Boolean - Whether the renderer process has crashed.
contents.forcefullyCrashRenderer()Forcefully terminates the renderer process that is currently hosting this webContents. This will cause the render-process-gone event to be emitted with the reason=killed || reason=crashed. Please note that some webContents share renderer processes and therefore calling this method may also crash the host process for other webContents as well.
Calling reload() immediately after calling this method will force the reload to occur in a new process. This should be used when this process is unstable or unusable, for instance in order to recover from the unresponsive event.
contents.on('unresponsive', async () => {\n const { response } = await dialog.showMessageBox({\n message: 'App X has become unresponsive',\n title: 'Do you want to try forcefully reloading the app?',\n buttons: ['OK', 'Cancel'],\n cancelId: 1\n })\n if (response === 0) {\n contents.forcefullyCrashRenderer()\n contents.reload()\n }\n})\ncontents.setUserAgent(userAgent)userAgent String重写该页面的user agent
\ncontents.getUserAgent()返回 String - 当前页面的user agent.
contents.insertCSS(css[, options])css Stringoptions Object (可选)cssOrigin String (optional) - Can be either 'user' or 'author'; Specifying 'user' enables you to prevent websites from overriding the CSS you insert. Default is 'author'.Returns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via contents.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\ncontents.on('did-finish-load', () => {\n contents.insertCSS('html, body { background-color: #f00; }')\n})\ncontents.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from contents.insertCSS(css).
contents.on('did-finish-load', async () => {\n const key = await contents.insertCSS('html, body { background-color: #f00; }')\n contents.removeInsertedCSS(key)\n})\ncontents.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (optional) - Default is false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
在页面中执行 code。
在浏览器窗口中，一些HTML API（如requestFullScreen）只能是 由来自用户的手势调用。 将 userGesture 设置为 true 将删除此限制。
Code execution will be suspended until web page stop loading.
\ncontents.executeJavaScript('fetch(\"https://jsonplaceholder.typicode.com/users/1\").then(resp => resp.json())', true)\n .then((result) => {\n console.log(result) // Will be the JSON object from the fetch call\n })\ncontents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electron's contextIsolation feature. You can provide any integer here.scripts WebSource[]userGesture Boolean (optional) - Default is false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Works like executeJavaScript but evaluates scripts in an isolated context.
contents.setIgnoreMenuShortcuts(ignore)ignore BooleanIgnore application menu shortcuts while this web contents is focused.
\ncontents.setWindowOpenHandler(handler)handler 函数<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>
details Objecturl String - The resolved version of the URL passed to window.open(). e.g. opening a window with window.open('foo') will yield something like https://the-origin/the/current/path/foo.frameName String - Name of the window provided in window.open()features String - Comma separated list of window features provided to window.open().disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk or other.referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.Returns {action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny cancels the creation of the new window. allow will allow the new window to be created. Specifying overrideBrowserWindowOptions allows customization of the created window. Returning an unrecognized value such as a null, undefined, or an object without a recognized 'action' value will result in a console error and have the same effect as returning {action: 'deny'}.
Called before creating a window a new window is requested by the renderer, e.g. by window.open(), a link with target=\"_blank\", shift+clicking on a link, or submitting a form with <form target=\"_blank\">. See window.open() for more details and how to use this in conjunction with did-create-window.
contents.setAudioMuted(muted)muted Boolean使当前页面音频静音
\ncontents.isAudioMuted()返回 Boolean -判断页面是否被静音
contents.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
contents.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\nThe factor must be greater than 0.0.
\ncontents.getZoomFactor()Returns Number - the current zoom factor.
contents.setZoomLevel(level)level Number - 缩放等级。更改缩放等级。 The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
contents.getZoomLevel()Returns Number - the current zoom level.
contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel Number返回 Promise<void>
设置最大和最小缩放级别。
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\ncontents.setVisualZoomLevelLimits(1, 3)\n
contents.undo()在页面中执行undo编辑命令。
contents.redo()在页面中执行redo编辑命令。
contents.cut()在页面中执行cut编辑命令。
contents.copy()在页面中执行copy编辑命令。
contents.copyImageAt(x, y)x Integery IntegerCopy the image at the given position to the clipboard.
\ncontents.paste()在页面中执行paste编辑命令。
contents.pasteAndMatchStyle()在页面中执行pasteAndMatchStyle编辑命令。
contents.delete()在页面中执行delete编辑命令。
contents.selectAll()在页面中执行selectAll编辑命令。
contents.unselect()在页面中执行unselect编辑命令。
contents.replace(text)text String在页面中执行replace编辑命令。
contents.replaceMisspelling(text)text String在页面中执行replaceMisspelling编辑命令。
contents.insertText(text)text String返回 Promise<void>
插入text 到焦点元素
contents.findInPage(text[, options])text String - 要搜索的内容，必须非空。options Object (可选)forward Boolean (可选) -向前或向后搜索，默认为 true。findNext Boolean (可选) - 是否使用此请求开始一个新的文本查找会话。 对于初始请求应该为 true ，对后续请求为 false 。 默认值为 false.matchCase Boolean (optional) - Whether search should be case-sensitive, defaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. The result of the request can be obtained by subscribing to found-in-page event.
contents.stopFindInPage(action)action String - Specifies the action to take place when ending [webContents.findInPage] request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webContents with the provided action.
const { webContents } = require('electron')\nwebContents.on('found-in-page', (event, result) => {\n if (result.finalUpdate) webContents.stopFindInPage('clearSelection')\n})\n\nconst requestId = webContents.findInPage('api')\nconsole.log(requestId)\ncontents.capturePage([rect])rect Rectangle (optional) - The area of the page to be captured.返回 Promise<NativeImage> - 完成后返回一个NativeImage
在 rect内捕获页面的快照。 省略 rect 将捕获整个可见页面。
contents.isBeingCaptured()Returns Boolean - Whether this page is being captured. It returns true when the capturer count is large then 0.
contents.incrementCapturerCount([size, stayHidden, stayAwake])size Size (optional) - The preferred size for the capturer.stayHidden Boolean (optional) - Keep the page hidden instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Increase the capturer count by one. The page is considered visible when its browser window is hidden and the capturer count is non-zero. If you would like the page to stay hidden, you should ensure that stayHidden is set to true.
This also affects the Page Visibility API.
\ncontents.decrementCapturerCount([stayHidden, stayAwake])stayHidden Boolean (optional) - Keep the page in hidden state instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Decrease the capturer count by one. The page will be set to hidden or occluded state when its browser window is hidden or occluded and the capturer count reaches zero. If you want to decrease the hidden capturer count instead you should set stayHidden to true.
contents.getPrinters()获取系统打印机列表
\n\ncontents.print([options], [callback])options Object (可选)silent Boolean (optional) - Don't ask user for print settings. 默认值为 false.printBackground Boolean (optional) - Prints the background color and image of the web page. 默认值为 false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. 默认值为 true。margins Object (可选)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. 默认值为 false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print. On macOS, only one range is honored.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. 可以是 simplex、shortEdge 或 longEdge。dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.callback Function (可选)success Boolean - Indicates success of the print call.failureReason String - Error description called back if the print fails.When a custom pageSize is passed, Chromium attempts to validate platform specific minimum values for width_microns and height_microns. Width and height must both be minimum 353 microns but may be higher on some operating systems.
Prints window's web page. When silent is set to true, Electron will pick the system's default printer if deviceName is empty and the default settings for printing.
Use page-break-before: always; CSS style to force to print to a new page.
示例：
\nconst options = {\n silent: true,\n deviceName: 'My-Printer',\n pageRanges: [{\n from: 0,\n to: 1\n }]\n}\nwin.webContents.print(options, (success, errorType) => {\n if (!success) console.log(errorType)\n})\ncontents.printToPDF(options)选项 对象headerFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height and width in microns.printBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Buffer> - Resolves with the generated PDF data.
Prints window's web page as PDF with Chromium's preview printing custom settings.
\nThe landscape will be ignored if @page CSS at-rule is used in the web page.
By default, an empty options will be regarded as:
{\n marginsType: 0,\n printBackground: false,\n printSelectionOnly: false,\n landscape: false,\n pageSize: 'A4',\n scaleFactor: 100\n}\nUse page-break-before: always; CSS style to force to print to a new page.
An example of webContents.printToPDF:
const { BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\nconst os = require('os')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nwin.webContents.on('did-finish-load', () => {\n // Use default printing options\n win.webContents.printToPDF({}).then(data => {\n const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')\n fs.writeFile(pdfPath, data, (error) => {\n if (error) throw error\n console.log(`Wrote PDF successfully to ${pdfPath}`)\n })\n }).catch(error => {\n console.log(`Failed to write PDF to ${pdfPath}: `, error)\n })\n})\ncontents.addWorkSpace(path)path StringAdds the specified path to DevTools workspace. Must be used after DevTools creation:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.on('devtools-opened', () => {\n win.webContents.addWorkSpace(__dirname)\n})\ncontents.removeWorkSpace(path)path StringRemoves the specified path from DevTools workspace.
\ncontents.setDevToolsWebContents(devToolsWebContents)devToolsWebContents WebContentsUses the devToolsWebContents as the target WebContents to show devtools.
The devToolsWebContents must not have done any navigation, and it should not be used for other purposes after the call.
By default Electron manages the devtools by creating an internal WebContents with native view, which developers have very limited control of. With the setDevToolsWebContents method, developers can use any WebContents to show the devtools in it, including BrowserWindow, BrowserView and <webview> tag.
Note that closing the devtools does not destroy the devToolsWebContents, it is caller's responsibility to destroy devToolsWebContents.
An example of showing devtools in a <webview> tag:
<html>\n<head>\n <style type=\"text/css\">\n * { margin: 0; }\n #browser { height: 70%; }\n #devtools { height: 30%; }\n </style>\n</head>\n<body>\n <webview id=\"browser\" src=\"https://github.com\"></webview>\n <webview id=\"devtools\" src=\"about:blank\"></webview>\n <script>\n const { ipcRenderer } = require('electron')\n const emittedOnce = (element, eventName) => new Promise(resolve => {\n element.addEventListener(eventName, event => resolve(event), { once: true })\n })\n const browserView = document.getElementById('browser')\n const devtoolsView = document.getElementById('devtools')\n const browserReady = emittedOnce(browserView, 'dom-ready')\n const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')\n Promise.all([browserReady, devtoolsReady]).then(() => {\n const targetId = browserView.getWebContentsId()\n const devtoolsId = devtoolsView.getWebContentsId()\n ipcRenderer.send('open-devtools', targetId, devtoolsId)\n })\n </script>\n</body>\n</html>\n// Main process\nconst { ipcMain, webContents } = require('electron')\nipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {\n const target = webContents.fromId(targetContentsId)\n const devtools = webContents.fromId(devtoolsContentsId)\n target.setDevToolsWebContents(devtools)\n target.openDevTools()\n})\nAn example of showing devtools in a BrowserWindow:
const { app, BrowserWindow } = require('electron')\n\nlet win = null\nlet devtools = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n devtools = new BrowserWindow()\n win.loadURL('https://github.com')\n win.webContents.setDevToolsWebContents(devtools.webContents)\n win.webContents.openDevTools({ mode: 'detach' })\n})\ncontents.openDevTools([options])options Object (可选)mode String - Opens the devtools with specified dock state, can be right, bottom, undocked, detach. Defaults to last used dock state. In undocked mode it's possible to dock back. In detach mode it's not.activate Boolean (optional) - Whether to bring the opened devtools window to the foreground. 默认值为 true。Opens the devtools.
\nWhen contents is a <webview> tag, the mode would be detach by default, explicitly passing an empty mode can force using last used dock state.
contents.closeDevTools()关闭开发者工具。
\ncontents.isDevToolsOpened()返回Boolean - 开发者工具是否处于开启状态。
contents.isDevToolsFocused()返回Boolean - 开发者工具是否处于当前执行状态。
contents.toggleDevTools()切换开发工具
\ncontents.inspectElement(x, y)x Integery Integer开始检查位于(x, y) 的元素。
contents.inspectSharedWorker()Opens the developer tools for the shared worker context.
\ncontents.inspectSharedWorkerById(workerId)workerId StringInspects the shared worker based on its ID.
\ncontents.getAllSharedWorkers()Returns SharedWorkerInfo[] - Information about all Shared Workers.
contents.inspectServiceWorker()Opens the developer tools for the service worker context.
\ncontents.send(channel, ...args)channel String...args any[]Send an asynchronous message to the renderer process via channel, along with arguments. 参数将使用 Structured Clone Algorithm进行序列化，就像 postMessage,因此原型链将不会包含在内。 发送 Functions, Promises, Symbols, WeakMaps, 或 WeakSets 将抛出异常
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the ipcRenderer module.
An example of sending messages from the main process to the renderer process:
\n// 在主进程中.\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL(`file://${__dirname}/index.html`)\n win.webContents.on('did-finish-load', () => {\n win.webContents.send('ping', 'whoooooooh!')\n })\n})\n<!-- index.html -->\n<html>\n<body>\n <script>\n require('electron').ipcRenderer.on('ping', (event, message) => {\n console.log(message) // Prints 'whoooooooh!'\n })\n </script>\n</body>\n</html>\ncontents.sendToFrame(frameId, channel, ...args)frameId Integer | [number, number] - the ID of the frame to send to, or a pair of [processId, frameId] if the frame is in a different process to the main frame.channel String...args any[]Send an asynchronous message to a specific frame in a renderer process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\n注意： 发送非标准的 JavaScript 类型，如DOM 对象或特殊Electron 对象将会抛出异常。
\n
The renderer process can handle the message by listening to channel with the ipcRenderer module.
If you want to get the frameId of a given renderer context you should use the webFrame.routingId value. 如下:
// In a renderer process\nconsole.log('My frameId is:', require('electron').webFrame.routingId)\nYou can also read frameId from all incoming IPC messages in the main process.
// In the main process\nipcMain.on('ping', (event) => {\n console.info('Message came from frameId:', event.frameId)\n})\ncontents.postMessage(channel, message, [transfer])Send a message to the renderer process, optionally transferring ownership of zero or more [MessagePortMain][] objects.
The transferred MessagePortMain objects will be available in the renderer process by accessing the ports property of the emitted event. When they arrive in the renderer, they will be native DOM MessagePort objects.
例如：
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\ncontents.enableDeviceEmulation(parameters)parameters ObjectscreenPosition String - Specify the screen type to emulate (default: desktop):desktop - Desktop screen type.mobile - Mobile screen type.screenSize Size - Set the emulated screen size (screenPosition == mobile).viewPosition Point - Position the view on the screen (screenPosition == mobile) (default: { x: 0, y: 0 }).deviceScaleFactor Integer - Set the device scale factor (if zero defaults to original device scale factor) (default: 0).viewSize Size - Set the emulated view size (empty means no override)scale Float - Scale of emulated view inside available space (not in fit to view mode) (default: 1).允许设备模拟给定参数。
\ncontents.disableDeviceEmulation()禁止webContents.enableDeviceEmulation允许的模拟设备
contents.sendInputEvent(inputEvent)inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventSends an input event to the page. Note: The BrowserWindow containing the contents needs to be focused for sendInputEvent() to work.
contents.beginFrameSubscription([onlyDirty ,]callback)onlyDirty Boolean (可选) - 默认值为 false.callback Functionimage NativeImagedirtyRect RectangleBegin subscribing for presentation events and captured frames, the callback will be called with callback(image, dirtyRect) when there is a presentation event.
The image is an instance of NativeImage that stores the captured frame.
The dirtyRect is an object with x, y, width, height properties that describes which part of the page was repainted. If onlyDirty is set to true, image will only contain the repainted area. onlyDirty defaults to false.
contents.endFrameSubscription()End subscribing for frame presentation events.
\ncontents.startDrag(item)item Objectfile String - The path to the file being dragged.files String - The paths to the files being dragged. (files will override file field)icon NativeImage | String - The image must be non-empty on macOS.Sets the item as dragging item for current drag-drop operation, file is the absolute path of the file to be dragged, and icon is the image showing under the cursor when dragging.
contents.savePage(fullPath, saveType)fullPath String - The full file path.saveType String - Specify the save type.HTMLOnly - Save only the HTML of the page.HTMLComplete - Save complete-html page.MHTML - Save complete-html page as MHTML.Returns Promise<void> - resolves if the page is saved.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.loadURL('https://github.com')\n\nwin.webContents.on('did-finish-load', async () => {\n win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {\n console.log('Page was saved successfully.')\n }).catch(err => {\n console.log(err)\n })\n})\ncontents.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\ncontents.isOffscreen()Returns Boolean - Indicates whether offscreen rendering is enabled.
contents.startPainting()If offscreen rendering is enabled and not painting, start painting.
\ncontents.stopPainting()If offscreen rendering is enabled and painting, stop painting.
\ncontents.isPainting()Returns Boolean - If offscreen rendering is enabled returns whether it is currently painting.
contents.setFrameRate(fps)fps IntegerIf offscreen rendering is enabled sets the frame rate to the specified number. Only values between 1 and 240 are accepted.
\ncontents.getFrameRate()Returns Integer - If offscreen rendering is enabled returns the current frame rate.
contents.invalidate()Schedules a full repaint of the window this web contents is in.
\nIf offscreen rendering is enabled invalidates the frame and generates a new one through the 'paint' event.
contents.getWebRTCIPHandlingPolicy()Returns String - Returns the WebRTC IP Handling Policy.
contents.setWebRTCIPHandlingPolicy(policy)policy String - Specify the WebRTC IP Handling Policy.default - Exposes user's public and local IPs. This is the default behavior. When this policy is used, WebRTC has the right to enumerate all interfaces and bind them to discover public interfaces.default_public_interface_only - Exposes user's public IP, but does not expose user's local IP. When this policy is used, WebRTC should only use the default route used by http. This doesn't expose any local addresses.default_public_and_private_interfaces - Exposes user's public and local IPs. When this policy is used, WebRTC should only use the default route used by http. This also exposes the associated default private address. Default route is the route chosen by the OS on a multi-homed endpoint.disable_non_proxied_udp - Does not expose public or local IPs. When this policy is used, WebRTC should only use TCP to contact peers or servers unless the proxy server supports UDP.Setting the WebRTC IP handling policy allows you to control which IPs are exposed via WebRTC. See BrowserLeaks for more details.
\ncontents.getOSProcessId()Returns Integer - The operating system pid of the associated renderer process.
contents.getProcessId()Returns Integer - The Chromium internal pid of the associated renderer. Can be compared to the frameProcessId passed by frame specific navigation events (e.g. did-frame-navigate)
contents.takeHeapSnapshot(filePath)filePath String - 输出文件路径返回 Promise<void> - 指明快捷方式是否被成功创建。
获取V8堆快照并保存到 filePath
contents.getBackgroundThrottling()Returns Boolean - whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
contents.setBackgroundThrottling(allowed)allowed BooleanControls whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
\ncontents.getType()Returns String - the type of the webContent. Can be backgroundPage, window, browserView, remote, webview or offscreen.
contents.setImageAnimationPolicy(policy)policy String - 可以是 animate, animateOnce 或 noAnimation.Sets the image animation policy for this webContents. The policy only affects new images, existing images that are currently being animated are unaffected. This is a known limitation in Chromium, you can force image animation to be recalculated with img.src = img.src which will result in no network traffic but will update the animation policy.
This corresponds to the animationPolicy accessibility feature in Chromium.
\ncontents.audioMutedA Boolean property that determines whether this page is muted.
contents.userAgentA String property that determines the user agent for this web page.
contents.zoomLevelA Number property that determines the zoom level for this web contents.
The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
contents.zoomFactorA Number property that determines the zoom factor for this web contents.
The zoom factor is the zoom percent divided by 100, so 300% = 3.0.
\ncontents.frameRateAn Integer property that sets the frame rate of the web contents to the specified number. Only values between 1 and 240 are accepted.
Only applicable if offscreen rendering is enabled.
\ncontents.id 只读Integer类型，代表WebContents的唯一标识（unique ID）。 每个ID在整个Electron应用程序的所有 WebContents 实例中都是唯一的。
contents.session 只读A Session used by this webContents.
contents.hostWebContents 只读A WebContents instance that might own this WebContents.
contents.devToolsWebContents 只读A WebContents | null property that represents the of DevTools WebContents associated with a given WebContents.
Note: Users should never store this object because it may become null when the DevTools has been closed.
contents.debugger 只读A Debugger instance for this webContents.
contents.backgroundThrottlingA Boolean property that determines whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
contents.mainFrame 只读A WebFrameMain property that represents the top frame of the page's frame hierarchy.
有三种方式可以让你在Electron的BrowserWindow里集成（第三方）web内容，<iframe> 和, <webview> 和 BrowserViews 每个功能都略有不同，适用于不同的情况。 为了帮助您在这些选择之间进行选择，本指南将解释他们之间的差异和功能。
Iframe 在 Electron 中的行为与普通浏览器中类似。 在宿主页面的 Content Security Policy 允许范围内，一个 <iframe> 元素能在页面上显示外部网页。 要限制 <iframe> 标签中站点的功能数量，建议 使用 sandbox 属性 并且只允许您想要支持的功能。
\n\n重要提示： 我们不建议您使用 WebView，因为这个标签会发生剧烈的结构变化，可能会影响您应用程序的稳定性。 考虑切换到其他选择，如
\niframe和Electron的BrowserView，或避免嵌入式内容 设计的架构。
WebViews基于 Chromium 的 WebView，不被 Electron 明确支持。 我们不能保证WebView API 在未来版本的 Electron 中仍然可用。 这就是为什么如果您想要使用<webview>标签，您需要在BrowserWindow 的 webPreferences 中设置 webviewTag 为 true。
WebView是一个自定义元素 (<webview>)，仅在 Electron 内工作。 它们以 \"进程外 iframe\" 实现。 这意味着所有与 <webview> 的通信都是异步使用 IPC 进行的。 <webview>元素有许多自定义方法和事件，类似于webContents，使您能够更多地控制内容。
与 <iframe>，<webview> 相比往往稍慢，但在加载和与第三方内容通信以及处理各种事件方面提供了更大的控制。
BrowserViews 不是 DOM 的一部分，而是由主进程创建和控制。 它们只是现有窗口之上的另一层 Web 内容。 这意味着它们与您自己的 BrowserWindow 内容完全分离，并且它们的位置不受 DOM 或 CSS 的控制，而是通过在主进程中设置边界来控制其位置。 相反，它通过在主进程中设置界面来控制 。
BrowserViews 提供对其内容的最大控制，因为它们实现 webContents 的方式与 BrowserWindow 实现内容的方式类似。 但是，由于 BrowserViews 不是 DOM 的一部分，而是覆盖在它们之上，因此您必须手动管理它们的位置。
\n\n自定义渲染当前网页
\n
进程: Renderer
\nwebFrame export of the Electron module is an instance of the WebFrame class representing the top frame of the current BrowserWindow. Sub-frames can be retrieved by certain properties and methods (e.g. webFrame.firstChild).
将当前页缩放到200% 的示例。
\nconst { webFrame } = require('electron')\nwebFrame.setZoomFactor(2)\nThe WebFrame class has the following instance methods:
webFrame.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\nThe factor must be greater than 0.0.
\nwebFrame.getZoomFactor()Returns Number - 当前的缩放比例。
webFrame.setZoomLevel(level)level Number - 缩放等级。更改缩放等级。 The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively.
\n\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
webFrame.getZoomLevel()Returns Number - The current zoom level.
webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel Number设置最大和最小缩放级别。
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\nwebFrame.setVisualZoomLevelLimits(1, 3)\n
\n\nNOTE: Visual zoom only applies to pinch-to-zoom behavior. Cmd+/-/0 zoom shortcuts are controlled by the 'zoomIn', 'zoomOut', and 'resetZoom' MenuItem roles in the application Menu. To disable shortcuts, manually define the Menu and omit zoom roles from the definition.
\n
webFrame.setSpellCheckProvider(language, provider)language Stringprovider ObjectspellCheck 函数words String[]callback FunctionmisspeltWords String[]Sets a provider for spell checking in input fields and text areas.
\nIf you want to use this method you must disable the builtin spellchecker when you construct the window.
\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: false\n }\n})\nThe provider must be an object that has a spellCheck method that accepts an array of individual words for spellchecking. The spellCheck function runs asynchronously and calls the callback function with an array of misspelt words when complete.
An example of using node-spellchecker as provider:
\nconst { webFrame } = require('electron')\nconst spellChecker = require('spellchecker')\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck (words, callback) {\n setTimeout(() => {\n const spellchecker = require('spellchecker')\n const misspelled = words.filter(x => spellchecker.isMisspelled(x))\n callback(misspelled)\n }, 0)\n }\n})\nwebFrame.insertCSS(css)css String - CSS source code.Returns String - A key for the inserted CSS that can later be used to remove the CSS via webFrame.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\nwebFrame.removeInsertedCSS(key)key StringRemoves the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from webFrame.insertCSS(css).
webFrame.insertText(text)text String插入text 到焦点元素
webFrame.executeJavaScript(code[, userGesture, callback])code StringuserGesture Boolean (optional) - Default is false.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.result Anyerror ErrorReturns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
在页面中执行 code。
在浏览器窗口中，一些HTML API（如requestFullScreen）只能是 由来自用户的手势调用。 将 userGesture 设置为 true 将删除此限制。
webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])worldId Integer - The ID of the world to run the javascript in, 0 is the default main world (where content runs), 999 is the world used by Electron's contextIsolation feature. Accepts values in the range 1..536870911.scripts WebSource[]userGesture Boolean (optional) - Default is false.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.result Anyerror ErrorReturns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution could not start.
Works like executeJavaScript but evaluates scripts in an isolated context.
Note that when the execution of script fails, the returned promise will not reject and the result would be undefined. This is because Chromium does not dispatch errors of isolated worlds to foreign worlds.
webFrame.setIsolatedWorldInfo(worldId, info)worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electrons contextIsolation feature. Chrome extensions reserve the range of IDs in [1 << 20, 1 << 29). You can provide any integer here.info ObjectsecurityOrigin String (optional) - Security origin for the isolated world.csp String (optional) - Content Security Policy for the isolated world.name String (optional) - Name for isolated world. Useful in devtools.Set the security origin, content security policy and name of the isolated world. Note: If the csp is specified, then the securityOrigin also has to be specified.
webFrame.getResourceUsage()返回 Object:
images MemoryUsageDetailsscripts MemoryUsageDetailscssStyleSheets MemoryUsageDetailsxslStyleSheets MemoryUsageDetailsfonts MemoryUsageDetailsother MemoryUsageDetailsReturns an object describing usage information of Blink's internal memory caches.
\nconst { webFrame } = require('electron')\nconsole.log(webFrame.getResourceUsage())\nThis will generate:
\n{\n images: {\n count: 22,\n size: 2549,\n liveSize: 2542\n },\n cssStyleSheets: { /* same with \"images\" */ },\n xslStyleSheets: { /* same with \"images\" */ },\n fonts: { /* same with \"images\" */ },\n other: { /* same with \"images\" */ }\n}\nwebFrame.clearCache()尝试释放不再使用的内存 (如以前导航中的图像)。
\n请注意, 盲目调用此方法可能使Electron较慢, 因为它将不得不重新填充这些清空的缓存。你应该只在这种情况下调用它, 就是当你的应用程序发生的一个事件, 使你认为你的网页实际只使用了较少的内存 (例如你从一个超级重页跳转到一个基本为空的页面, 并打算留在那)。
\nwebFrame.getFrameForSelector(selector)selector String - CSS selector for a frame element.Returns WebFrame - The frame element in webFrame's document selected by selector, null would be returned if selector does not select a frame or if the frame is not in the current renderer process.
webFrame.findFrameByName(name)name StringReturns WebFrame - A child of webFrame with the supplied name, null would be returned if there's no such frame or if the frame is not in the current renderer process.
webFrame.findFrameByRoutingId(routingId)routingId Integer - An Integer representing the unique frame id in the current renderer process. Routing IDs can be retrieved from WebFrame instances (webFrame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate)Returns WebFrame - that has the supplied routingId, null if not found.
webFrame.isWordMisspelled(word)word String - The word to be spellchecked.Returns Boolean - True if the word is misspelled according to the built in spellchecker, false otherwise. If no dictionary is loaded, always return false.
webFrame.getWordSuggestions(word)word String - The misspelled word.Returns String[] - A list of suggested words for a given word. If the word is spelled correctly, the result will be empty.
webFrame.top 只读A WebFrame | null representing top frame in frame hierarchy to which webFrame belongs, the property would be null if top frame is not in the current renderer process.
webFrame.opener 只读A WebFrame | null representing the frame which opened webFrame, the property would be null if there's no opener or opener is not in the current renderer process.
webFrame.parent 只读A WebFrame | null representing parent frame of webFrame, the property would be null if webFrame is top or parent is not in the current renderer process.
webFrame.firstChild 只读A WebFrame | null representing the first child frame of webFrame, the property would be null if webFrame has no children or if first child is not in the current renderer process.
webFrame.nextSibling 只读A WebFrame | null representing next sibling frame, the property would be null if webFrame is the last frame in its parent or if the next sibling is not in the current renderer process.
webFrame.routingId 只读An Integer representing the unique frame id in the current renderer process. Distinct WebFrame instances that refer to the same underlying frame will have the same routingId.
\n\n控制页面和内联框架(iframes)。
\n
进程：主进程
\nwebFramework 模块可以用来查找现有的 WebContents 实例。 通常在导航事件中使用。
const { BrowserWindow, webFrameMain } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://twitter.com')\n\nwin.webContents.on(\n 'did-frame-navigate',\n (event, url, isMainFrame, frameProcessId, frameRoutingId) => {\n const frame = webFrameMain.fromId(frameProcessId, frameRoutingId)\n if (frame) {\n const code = 'document.body.innerHTML = document.body.innerHTML.replaceAll(\"heck\", \"h*ck\")'\n frame.executeJavaScript(code)\n }\n }\n)\n您还可以通过使用 WebContents的 mainFrame 属性 访问现有页面的框架。
const { BrowserWindow } = require('electron')\n\nasync function main () {\n const win = new BrowserWindow({ width: 800, height: 600 })\n await win.loadURL('https://reddit.com')\n\n const youtubeEmbeds = win.webContents.mainFrame.frames.filter((frame) => {\n try {\n const url = new URL(frame.url)\n return url.host === 'www.youtube.com'\n } catch {\n return false\n }\n })\n\n console.log(youtubeEmbeds)\n}\n\nmain()\n通过webFrameMain模块可以访问以下方法：
webFrameMain.fromId(processId, routingId)processId Integer - 表示拥有此框架的进程的内部 ID。routingId Integer - 表示当前渲染器进程中唯一框架的 ID 。 Routing IDs can be retrieved from WebFrameMain instances (frame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate).Returns WebFrameMain | undefined - A frame with the given process and routing IDs, or undefined if there is no WebFrameMain associated with the given IDs.
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emitted when the document is loaded.
\nframe.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (optional) - Default is false.Returns Promise<unknown> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
在页面中执行 code。
在浏览器窗口中，一些HTML API（如requestFullScreen）只能是 由来自用户的手势调用。 将 userGesture 设置为 true 将删除此限制。
frame.reload()Returns boolean - Whether the reload was initiated successfully. Only results in false when the frame has no history.
frame.send(channel, ...args)channel String...args any[]Send an asynchronous message to the renderer process via channel, along with arguments. Arguments will be serialized with the [Structured Clone Algorithm][SCA], just like [postMessage][], so prototype chains will not be included. 发送 Functions, Promises, Symbols, WeakMaps, 或 WeakSets 将抛出异常
The renderer process can handle the message by listening to channel with the ipcRenderer module.
frame.postMessage(channel, message, [transfer])Send a message to the renderer process, optionally transferring ownership of zero or more [MessagePortMain][] objects.
The transferred MessagePortMain objects will be available in the renderer process by accessing the ports property of the emitted event. When they arrive in the renderer, they will be native DOM MessagePort objects.
例如：
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nframe.url ReadonlyA string representing the current URL of the frame.
frame.top ReadonlyA WebFrameMain | null representing top frame in the frame hierarchy to which frame belongs.
frame.parent ReadonlyA WebFrameMain | null representing parent frame of frame, the property would be null if frame is the top frame in the frame hierarchy.
frame.frames ReadonlyA WebFrameMain[] collection containing the direct descendents of frame.
frame.framesInSubtree ReadonlyA WebFrameMain[] collection containing every frame in the subtree of frame, including itself. This can be useful when traversing through all frames.
frame.frameTreeNodeId ReadonlyAn Integer representing the id of the frame's internal FrameTreeNode instance. This id is browser-global and uniquely identifies a frame that hosts content. The identifier is fixed at the creation of the frame and stays constant for the lifetime of the frame. When the frame is removed, the id is not used again.
frame.name ReadonlyA String representing the frame name.
frame.osProcessId ReadonlyAn Integer representing the operating system pid of the process which owns this frame.
frame.processId ReadonlyAn Integer representing the Chromium internal pid of the process which owns this frame. This is not the same as the OS process ID; to read that use frame.osProcessId.
frame.routingId ReadonlyAn Integer representing the unique frame id in the current renderer process. Distinct WebFrameMain instances that refer to the same underlying frame will have the same routingId.
frame.visibilityState 只读A string representing the visibility state of the frame.
See also how the Page Visibility API is affected by other Electron APIs.
", "title": "webFrameMain", "description": "控制页面和内联框架(iframes)。" }, "/docs/api/web-request": { "locale": "zh-CN", "slug": "web-request", "href": "/docs/api/web-request", "crowdinFileId": "256405", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-request.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n在一个请求生命周期的不同阶段，截取和修改其内容。
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
使用 Session 的 WebRequest 属性访问 WebRequest 类的实例。
WebRequest 下的所有方法接收 filter 和 listener 两个参数。 当 API 中有事件被触发时, listener(details) 会被调用， details 中包含了请求的详细信息。
⚠️ Only the last attached listener will be used. Passing null as listener will unsubscribe from the event.
filter 对象具有一个 url 属性, 它是一个 url 模式数组, 用于筛选出与 url 模式不匹配的请求。 如果省略 filter, 则所有请求都将匹配。
对于某些事件, listener 是通过 callback 传递的, 当 listener 完成其工作时, 应使用 response 对象进行调用。
为 requests 添加 User-Agent 头的示例：
const { session } = require('electron')\n\n// Modify the user agent for all requests to the following urls.\nconst filter = {\n urls: ['https://*.github.com/*', '*://electron.github.io']\n}\n\nsession.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {\n details.requestHeaders['User-Agent'] = 'MyAgent'\n callback({ requestHeaders: details.requestHeaders })\n})\n以下事件会在Session实例触发。
webRequest.onBeforeRequest([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (可选)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleuploadData UploadData[]callback Functionresponse Objectcancel Boolean (可选)redirectURL String (可选) - 原始请求被阻止发送或完成，而不是重定向到给定的URL。当请求即将发生时，调用listener(details, callback)。
uploadData 是UploadData对象的一个数组。
必须使用 response 对象调用callback。
Some examples of valid urls:
'http://foo:1234/'\n'http://foo.com/'\n'http://foo:1234/bar'\n'*://*/*'\n'*://example.com/*'\n'*://example.com/foo/*'\n'http://*.foo:1234/'\n'file://foo:1234/bar'\n'http://foo:*/'\n'*://www.foo.com/'\nwebRequest.onBeforeSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (可选)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders Record<string, string>callback FunctionbeforeSendResponse Objectcancel Boolean (可选)requestHeaders Record<string, string | string[]> (optional) - When provided, request will be made with these headers.一旦请求头可用，在发送 HTTP 请求之前，listener 将以 listener(details, callback) 的形式被调用。 这可能发生在对服务器进行 TCP 连接之后，但在发送任何HTTP数据之前。
The callback has to be called with a response object.
webRequest.onSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (可选)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders Record<string, string>在请求发送到服务器之前，listener将以listener(details)的形式被调用，在该侦听器被出发前，上一个对 onBeforeSendHeaders 响应的修改是可见的。
webRequest.onHeadersReceived([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (可选)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublestatusLine StringstatusCode IntegerresponseHeaders Record<string, string[]> (optional)callback FunctionheadersReceivedResponse Objectcancel Boolean (可选)responseHeaders Record<string, string | string[]> (optional) - When provided, the server is assumed to have responded with these headers.statusLine String (optional) - Should be provided when overriding responseHeaders to change header status otherwise original response header's status will be used.当HTTP请求接收到报头后，会通过调用 listener(details, callback)方法来触发listener。
The callback has to be called with a response object.
webRequest.onResponseStarted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (可选)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache Boolean - 表明响应是取自硬盘缓存。statusCode IntegerstatusLine String当收到响应体的第一个字节时， 将以 listener(details) 的形式来调用 listener。 对于 HTTP 请求而言，这意味着此时 HTTP 状态行和回应头已经可以读取了。
webRequest.onBeforeRedirect([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (可选)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleredirectURL StringstatusCode IntegerstatusLine Stringip String (可选) - 请求实际发送到的服务器 IP 地址。fromCache BooleanresponseHeaders Record<string, string[]> (optional)当服务器的初始重定向即将发生时，将以 listener(details)的方式调用listener。
webRequest.onCompleted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (可选)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache BooleanstatusCode IntegerstatusLine Stringerror String当请求完成时，将以 listener(details)的方式调用listener。
webRequest.onErrorOccurred([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objectid Integerurl Stringmethod StringwebContentsId Integer (可选)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublefromCache Booleanerror String - 错误描述.当发生错误时，将以 listener(details)的方式调用listener。
urls String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.code Stringurl String (optional)startLine Integer (optional) - Default is 1.<webview>标签Electron的 webview 标签基于 Chromium webview ，后者正在经历巨大的架构变化。 这将影响 webview 的稳定性，包括呈现、导航和事件路由。 我们目前建议不使用 webview 标签，并考虑其他替代方案，如 iframe ，Electron的 BrowserView 或完全避免嵌入内容的架构。
默认情况下，Electron >= 5禁用 webview 标签。 在构造 BrowserWindow 时，需要通过设置 webviewTag webPreferences选项来启用标签。 更多信息请参看 BrowserWindows 的构造器文档。
\n\n在一个独立的 frame 和进程里显示外部 web 内容。
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
使用 webview 标签将'guest'内容 (例如网页) 嵌入到您的 Electron 应用中。 Guest 内容包含在 webview 容器内。 应用中的嵌入页面可以控制外来内容的布局和重绘。
与 iframe不同， webview 独立于您的应用程序运行。 它拥有和你的页面不一样的权限并且所嵌入的内容和你应用之间的交互都将是异步的。 这将保证你的应用对于嵌入的内容的安全性。 注意: 从宿主页上调用 webview 的方法大多数都需要对主进程进行同步调用。
若要在应用程序中嵌入网页, 请将 webview 标签添加到应用程序的被嵌入页面中 (这是将显示外来内容的应用程序页)。 在最简单的例子中, webview 标签包括网页的 src 和控制 webview 容器外观的 css 样式:
<webview id=\"foo\" src=\"https://www.github.com/\" style=\"display:inline-flex; width:640px; height:480px\"></webview>\n如果要以任何方式控制外来内容, 则可以写用于侦听 webview 事件的 JavaScript, 并使用 webview 方法响应这些事件。 下面是包含两个事件侦听器的示例代码: 一个侦听网页开始加载, 另一个用于网页停止加载, 并在加载时显示 \"loading...\" 消息:
<script>\n onload = () => {\n const webview = document.querySelector('webview')\n const indicator = document.querySelector('.indicator')\n\n const loadstart = () => {\n indicator.innerText = 'loading...'\n }\n\n const loadstop = () => {\n indicator.innerText = ''\n }\n\n webview.addEventListener('did-start-loading', loadstart)\n webview.addEventListener('did-stop-loading', loadstop)\n }\n</script>\n在内部 webview 与 过程外 iframes（OOPIF）一起实施。 webview 标签本质上是一个自定义元素，使用 shadow DOM 将 iframe 元素包裹在里面。
因此， webview 的行为与跨域 iframe 非常相似，例如：
webview 中单击时，页面焦点将从嵌入器移动到 webview。webview。webview 之间的所有反应都是异步的。请注意，webview 标签的样式使用 display:flex; 来确保 iframe在传统和 flex 布局一起使用的情况下填充其 webview 容器的全部高度和宽度。 除非指定内联布局的 display:inline-flex; ，否则请不要 覆盖默认 display:flex; CSS属性。
webview 标签具有以下属性：
src<webview src=\"https://www.github.com/\"></webview>\n表示可见网址的 String 。 Writing to this attribute initiates top-level navigation.
更改 src 的值将重新加载当前页面。
src 属性还可以接受数据 URL, 如 data:text/plain, Hello, world!。
nodeintegration<webview src=\"http://www.google.com/\" nodeintegration></webview>\n一个 Boolean。 当有此属性时, webview 中的访客页（guest page）将具有Node集成, 并且可以使用像 require 和 process 这样的node APIs 去访问低层系统资源。 Node 集成在访客页中默认是禁用的。
nodeintegrationinsubframes<webview src=\"http://www.google.com/\" nodeintegrationinsubframes></webview>\nA Boolean for the experimental option for enabling NodeJS support in sub-frames such as iframes inside the webview. All your preloads will load for every iframe, you can use process.isMainFrame to determine if you are in the main frame or not. Node 集成在访客页中默认是禁用的。
plugins<webview src=\"https://www.github.com/\" plugins></webview>\n一个 Boolean。 When this attribute is present the guest page in webview will be able to use browser plugins. Plugins are disabled by default.
preload<!-- from a file -->\n<webview src=\"https://www.github.com/\" preload=\"./test.js\"></webview>\n<!-- or if you want to load from an asar archive -->\n<webview src=\"https://www.github.com/\" preload=\"./app.asar/test.js\"></webview>\nA String that specifies a script that will be loaded before other scripts run in the guest page. The protocol of script's URL must be file: (even when using asar: archives) because it will be loaded by Node's require under the hood, which treats asar: archives as virtual directories.
当访客页没有 node integration ，这个脚本仍然有能力去访问所有的 Node APIs, 但是当这个脚本执行执行完成之后，通过Node 注入的全局对象（global objects）将会被删除。
\nNote: This option will appear as preloadURL (not preload) in the webPreferences specified to the will-attach-webview event.
httpreferrer<webview src=\"https://www.github.com/\" httpreferrer=\"http://cheng.guru\"></webview>\nA String that sets the referrer URL for the guest page.
useragent<webview src=\"https://www.github.com/\" useragent=\"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko\"></webview>\nA String that sets the user agent for the guest page before the page is navigated to. Once the page is loaded, use the setUserAgent method to change the user agent.
disablewebsecurity<webview src=\"https://www.github.com/\" disablewebsecurity></webview>\n一个 Boolean。 When this attribute is present the guest page will have web security disabled. Web security is enabled by default.
partition<webview src=\"https://github.com\" partition=\"persist:github\"></webview>\n<webview src=\"https://electronjs.org\" partition=\"electron\"></webview>\nA String that sets the session used by the page. 如果 partition 以 persist:开头, 该页面将使用持续的 session，并在所有页面生效，且使用同一个partition. 如果没有 persist: 前缀, 页面将使用 in-memory session. 通过分配相同的 partition, 多个页可以共享同一会话。 如果没有设置partition，app 将会使用默认的session。
This value can only be modified before the first navigation, since the session of an active renderer process cannot change. Subsequent attempts to modify the value will fail with a DOM exception.
\nallowpopups<webview src=\"https://www.github.com/\" allowpopups></webview>\n一个 Boolean。 When this attribute is present the guest page will be allowed to open new windows. Popups are disabled by default.
webpreferences<webview src=\"https://github.com\" webpreferences=\"allowRunningInsecureContent, javascript=no\"></webview>\nString 是一个由逗号分割的字符串列表，其中指定了要设置在 webview 上的 Web 首选项。 支持的首选项字符串的完整列表，请查看 BrowserWindow。
该字符串的格式与 window.open 中的功能字符串( the features string )相同。 只有自己名字的将被赋予 true 布尔值。 可以通过 = 来赋予其他值。 yes 和 1 会被解析成 true，而 no 和 0 解析为 false。
enableblinkfeatures<webview src=\"https://www.github.com/\" enableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be enabled separated by ,. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
disableblinkfeatures<webview src=\"https://www.github.com/\" disableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be disabled separated by ,. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
webview 标签具有以下方法：
注意: 使用方法之前 <0>webview</0> 元素必须已被加载。
\n示例
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('dom-ready', () => {\n webview.openDevTools()\n})\n<webview>.loadURL(url[, options])url URLoptions Object (可选)httpReferrer (String | Referrer) (可选) - 一个 HTTP Referrer url。userAgent String (可选) - 发起请求的 userAgent.extraHeaders String (可选) - 用 \"\\n\" 分割的额外标题postData (UploadRawData | UploadFile)baseURLForDataURL String (可选) - 要加载的数据文件的根 url(带有路径分隔符). 只有当指定的 url是一个数据 url 并需要加载其他文件时，才需要这样做。Returns Promise<void> - The promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load).
webview 中加载目标 url，url 地址必须包含协议前缀，例如：http:// 或 file://。
<webview>.downloadURL(url)url StringInitiates a download of the resource at url without navigating.
<webview>.getURL()返回 String - 访客页的URL。
<webview>.getTitle()返回 String - 访客页的标题。
<webview>.isLoading()返回 Boolean - 访客页是否仍然在加载资源。
<webview>.isLoadingMainFrame()Returns Boolean - Whether the main frame (and not just iframes or frames within it) is still loading.
<webview>.isWaitingForResponse()返回 Boolean - 访客页面是否正在等待页面主资源的第一响应。
<webview>.stop()Stops any pending navigation.
\n<webview>.reload()刷新访客页。
\n<webview>.reloadIgnoringCache()刷新访客页并忽略缓存。
\n<webview>.canGoBack()返回 Boolean - 访客页能否后退。
<webview>.canGoForward()返回 Boolean - 访客页能否前进。
<webview>.canGoToOffset(offset)offset Integer返回 Boolean - 访客页能否前进到 offset。
<webview>.clearHistory()清除定位历史。
\n<webview>.goBack()使访客页后退。
\n<webview>.goForward()使访客页前进。
\n<webview>.goToIndex(index)index Integer定位到指定的绝对索引。
\n<webview>.goToOffset(offset)offset Integer定位到相对于“当前入口”的指定的偏移。
\n<webview>.isCrashed()Returns Boolean - Whether the renderer process has crashed.
<webview>.setUserAgent(userAgent)userAgent String覆盖访客页的用户代理。
\n<webview>.getUserAgent()返回 String - 访客页的用户代理。
<webview>.insertCSS(css)css StringReturns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via <webview>.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\n<webview>.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from <webview>.insertCSS(css).
<webview>.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (可选) - 默认为 false。Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
在页面中执行 code。 如果设置了userGesture，它将在页面中创建用户手势上下文。 像 requestFullScreen 这样的需要用户操作的HTML API可以利用这个选项来实现自动化。
<webview>.openDevTools()打开 guest 页面的 DevTools 窗口。
\n<webview>.closeDevTools()关闭 guest 页面的 DevTools 窗口。
\n<webview>.isDevToolsOpened()返回 Boolean - guest 页面是否打开了 Devtools。
<webview>.isDevToolsFocused()返回 Boolean - guest 页面的 DevTools 窗口是否聚焦。
<webview>.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y) of guest page.
<webview>.inspectSharedWorker()Opens the DevTools for the shared worker context present in the guest page.
\n<webview>.inspectServiceWorker()Opens the DevTools for the service worker context present in the guest page.
\n<webview>.setAudioMuted(muted)muted Boolean设置访客页是否静音。
\n<webview>.isAudioMuted()返回 Boolean - 访客页是否被静音。
<webview>.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
<webview>.undo()在页面中执行编辑命令 undo。
<webview>.redo()在页面中执行编辑命令 redo。
<webview>.cut()在页面中执行编辑命令 cut。
<webview>.copy()在页面中执行编辑命令 copy。
<webview>.paste()在页面中执行编辑命令 paste。
<webview>.pasteAndMatchStyle()在页面中执行编辑命令 pasteAndMatchStyle。
<webview>.delete()在页面中执行编辑命令 delete。
<webview>.selectAll()在页面中执行编辑命令 selectAll。
<webview>.unselect()在页面中执行编辑命令 unselect。
<webview>.replace(text)text String在页面中执行编辑命令 replace。
<webview>.replaceMisspelling(text)text String在页面中执行编辑命令 replaceMisspelling。
<webview>.insertText(text)text String返回 Promise<void>
插入text 到焦点元素
<webview>.findInPage(text[, options])text String - 要搜索的内容，必须非空。options Object (可选)forward Boolean (可选) -向前或向后搜索，默认为 true。findNext Boolean (可选) - 是否使用此请求开始一个新的文本查找会话。 对于初始请求应该为 true ，对后续请求为 false 。 默认值为 false.matchCase Boolean (optional) - Whether search should be case-sensitive, defaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. The result of the request can be obtained by subscribing to found-in-page event.
<webview>.stopFindInPage(action)action String - Specifies the action to take place when ending <webview>.findInPage request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webview with the provided action.
<webview>.print([options])options Object (可选)silent Boolean (optional) - Don't ask user for print settings. 默认值为 false.printBackground Boolean (optional) - Prints the background color and image of the web page. 默认值为 false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. 默认值为 true。margins Object (可选)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. 默认值为 false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. 可以是 simplex、shortEdge 或 longEdge。dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.返回 Promise<void>
Prints webview's web page. 与 webContents.print([options]) 相同.
<webview>.printToPDF(options)选项 对象headerFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin. and width in microns.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print. 在macOS上，只有数组的第一个值被信任。from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing heightprintBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Uint8Array> - Resolves with the generated PDF data.
Prints webview's web page as PDF, Same as webContents.printToPDF(options).
<webview>.capturePage([rect])rect Rectangle (optional) - The area of the page to be captured.返回 Promise<NativeImage> - 完成后返回一个NativeImage
在 rect内捕获页面的快照。 省略 rect 将捕获整个可见页面。
<webview>.send(channel, ...args)channel String...args any[]返回 Promise<void>
通过channel向渲染器进程发送异步消息，可以发送任意参数。 The renderer process can handle the message by listening to the channel event with the ipcRenderer module.
示例请进传送门： webContents.send
\n<webview>.sendToFrame(frameId, channel, ...args)frameId [number, number] - [processId, frameId]channel String...args any[]返回 Promise<void>
通过channel向渲染器进程发送异步消息，可以发送任意参数。 The renderer process can handle the message by listening to the channel event with the ipcRenderer module.
See webContents.sendToFrame for examples.
\n<webview>.sendInputEvent(event)event MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent返回 Promise<void>
Sends an input event to the page.
See webContents.sendInputEvent for detailed description of event object.
<webview>.setZoomFactor(factor)factor Number - 缩放比例Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\n<webview>.setZoomLevel(level)level Number - 缩放等级。更改缩放等级。 The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
<webview>.getZoomFactor()Returns Number - the current zoom factor.
<webview>.getZoomLevel()Returns Number - the current zoom level.
<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel Number返回 Promise<void>
设置最大和最小缩放级别。
\n<webview>.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\n<webview>.getWebContentsId()Returns Number - The WebContents ID of this webview.
webview 标签具有以下有效的 DOM 事件：
返回:
\nurl StringisMainFrame BooleanFired when a load has committed. This includes navigation within the current document as well as subframe document-level loads, but does not include asynchronous resource loads.
\n导航完成时触发，即选项卡的旋转器将停止旋转，并指派onload事件后。（译者：网页加载的过程中，并不是所有的浏览器都是转圈圈，而且浏览器版本不同，加载效果也有可能不一样。其中 ie 和 chrome 是转圈圈，safari 是进度条，firefox是一个小点左右来回移动--20180103）
返回:
\nerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame Boolean这个事件类似于 did-finish-load, 不过是在加载失败或取消后触发，例如调用了 window.stop()
返回:
\nisMainFrame BooleanFired when a frame has done navigation.
\nCorresponds to the points in time when the spinner of the tab starts spinning.
\nCorresponds to the points in time when the spinner of the tab stops spinning.
\nFired when attached to the embedder web contents.
\nFired when document in the given frame is loaded.
\n返回:
\ntitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when title is synthesized from file url.
返回:
\nfavicons String[] - 由连接组成的数组。Fired when page receives favicon urls.
\nFired when page enters fullscreen triggered by HTML API.
\nFired when page leaves fullscreen triggered by HTML API.
\n返回:
\nlevel Integer - The log level, from 0 to 3. 按顺序匹配 verbose, info, warning 和 error.message String - 实际控制台消息line Integer - The line number of the source that triggered this console messagesourceId StringFired when the guest window logs a console message.
\nThe following example code forwards all log messages to the embedder's console without regard for log level or other properties.
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('console-message', (e) => {\n console.log('Guest page logged a message:', e.message)\n})\n返回:
\nresult ObjectrequestId IntegeractiveMatchOrdinal Integer - 当前匹配位置。matches Integer - 符合匹配条件的元素个数。selectionArea Rectangle - Coordinates of first match region.finalUpdate BooleanFired when a result is available for webview.findInPage request.
const webview = document.querySelector('webview')\nwebview.addEventListener('found-in-page', (e) => {\n webview.stopFindInPage('keepSelection')\n})\n\nconst requestId = webview.findInPage('test')\nconsole.log(requestId)\n返回:
\nurl StringframeName Stringdisposition String - 可以被设置为 default, foreground-tab, background-tab, new-window, save-to-disk 及 other.options BrowserWindowConstructorOptions - The options which should be used for creating the new BrowserWindow.Fired when the guest page attempts to open a new browser window.
\nThe following example code opens the new url in system's default browser.
\nconst { shell } = require('electron')\nconst webview = document.querySelector('webview')\n\nwebview.addEventListener('new-window', async (e) => {\n const protocol = (new URL(e.url)).protocol\n if (protocol === 'http:' || protocol === 'https:') {\n await shell.openExternal(e.url)\n }\n})\n返回:
\nurl StringEmitted when a user or the page wants to start navigation. It can happen when the window.location object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with APIs like <webview>.loadURL and <webview>.back.
It is also not emitted during in-page navigation, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Calling event.preventDefault() does NOT have any effect.
返回:
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be true for in-page navigations.
返回:
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\n返回:
\nurl StringEmitted when a navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
返回:
\nurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigations,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
返回:
\nisMainFrame Booleanurl String当发生页内导航时，触发该事件。
\n当发生页内导航时，虽然页面地址发生变化，但它并没有导航到其它页面。 例如，点击锚点链接，或者DOM的 hashchange事件被触发时，都会触发该事件。
Fired when the guest page attempts to close itself.
\nThe following example code navigates the webview to about:blank when the guest attempts to close itself.
const webview = document.querySelector('webview')\nwebview.addEventListener('close', () => {\n webview.src = 'about:blank'\n})\n返回:
\nframeId [number, number] - pair of [processId, frameId].channel Stringargs any[]Fired when the guest page has sent an asynchronous message to embedder page.
\nWith sendToHost method and ipc-message event you can communicate between guest page and embedder page:
// In embedder page.\nconst webview = document.querySelector('webview')\nwebview.addEventListener('ipc-message', (event) => {\n console.log(event.channel)\n // Prints \"pong\"\n})\nwebview.send('ping')\n// In guest page.\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('ping', () => {\n ipcRenderer.sendToHost('pong')\n})\nFired when the renderer process is crashed.
\n返回:
\nname Stringversion StringFired when a plugin process is crashed.
\nFired when the WebContents is destroyed.
\n多媒体开始播放时，触发该事件。
\n当媒体文件暂停或播放完成的时候触发
\n返回:
\nthemeColor StringEmitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\n返回:
\nurl String当鼠标滑到，或者键盘切换到a连接时，触发该事件。
\n当开发者工具被打开时，触发该事件。
\n当开发者工具被关闭时，触发该事件。
\n当开发者工具被选中/打开时，触发该事件。
", "title": "有几种方法可以控制从信任或在渲染器内创建窗口的方式。 可以通过两种方式从渲染进程创建窗口：
\ntarget=_blank，单击链接或提交表格即可创建window.open()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.
When nativeWindowOpen is set to false, window.open instead results in the creation of a BrowserWindowProxy, 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 BrowserWindow in the main process by using webContents.setWindowOpenHandler() for renderer-created windows.
BrowserWindow constructor options are set by, in increasing precedence order: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Note that webContents.setWindowOpenHandler has final say and full privilege because it is invoked in the main process.
window.open(url[, frameName][, features])url StringframeName String（可选）features String（可选）Returns BrowserWindowProxy | Window
features is a comma-separated key-value list, following the standard format of the browser. Electron will parse BrowserWindowConstructorOptions out of this list where possible, for convenience. For full control and better ergonomics, consider using webContents.setWindowOpenHandler to customize the BrowserWindow creation.
A subset of WebPreferences can be set directly, unnested, from the features string: zoomFactor, nodeIntegration, preload, javascript, contextIsolation, and webviewTag.
例如：
\nwindow.open('https://github.com', '_blank', 'top=500,left=200,frame=false,nodeIntegration=no')\n说明：
\nwindow 中将始终被禁用。window 中将始终被启用。window 中将被始终禁用features will be passed to any registered webContents's did-create-window event handler in the options argument.frameName follows the specification of windowName located in the native documentation.To customize or cancel the creation of the window, you can optionally set an override handler with webContents.setWindowOpenHandler() from the main 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.
Window example// main.js\nconst mainWindow = new BrowserWindow()\n\n// In this example, only windows with the `about:blank` url will be created.\n// All other urls will be blocked.\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url === 'about:blank') {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n frame: false,\n fullscreenable: false,\n backgroundColor: 'black',\n webPreferences: {\n preload: 'my-child-window-preload-script.js'\n }\n }\n }\n }\n return { action: 'deny' }\n})\n// renderer process (mainWindow)\nconst childWindow = window.open('', 'modal')\nchildWindow.document.write('<h1>Hello</h1>')\nBrowserWindowProxy example\n// main.js\nconst mainWindow = new BrowserWindow({\n webPreferences: { nativeWindowOpen: false }\n})\n\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url.startsWith('https://github.com/')) {\n return { action: 'allow' }\n }\n return { action: 'deny' }\n})\n\nmainWindow.webContents.on('did-create-window', (childWindow) => {\n // For example...\n childWindow.webContents.on('will-navigate', (e) => {\n e.preventDefault()\n })\n})\n// renderer.js\nconst windowProxy = window.open('https://github.com/', null, 'minimizable=false')\nwindowProxy.postMessage('hi', '*')\n如果您的应用使用Electron 6.0.8及之后的版本，您现在可以在基于ARM的Windows10上构建它。 This considerably improves performance, but requires recompilation of any native modules used in your app. It may also require small fixups to your build and packaging scripts.
\nIf your app doesn't use any native modules, then it's really easy to create an Arm version of your app.
\nnode_modules directory is empty.set npm_config_arch=arm64 before running npm install/yarn install as usual.Lots of Windows-specific code contains if... else logic that selects between either the x64 or x86 architectures.
\nif (process.arch === 'x64') {\n // Do 64-bit thing...\n} else {\n // Do 32-bit thing...\n}\nIf you want to target arm64, logic like this will typically select the wrong architecture, so carefully check your application and build scripts for conditions like this. In custom build and packaging scripts, you should always check the value of npm_config_arch in the environment, rather than relying on the current process arch.
If you use native modules, you must make sure that they compile against v142 of the MSVC compiler (provided in Visual Studio 2017). 您还必须检查 native module 提供或引用的 .dll 或 .lib 文件是否可用于 Arm 上的 Windows。
To test your app, use a Windows on Arm device running Windows 10 (version 1903 or later). Make sure that you copy your application over to the target device - Chromium's sandbox will not work correctly when loading your application assets from a network location.
\nNode.js v12.9.0 or later is recommended. If updating to a new version of Node is undesirable, you can instead update npm's copy of node-gyp manually to version 5.0.2 or later, which contains the required changes to compile native modules for Arm.
\nVisual Studio 2017 (any edition) is required for cross-compiling native modules. You can download Visual Studio Community 2017 via Microsoft's Visual Studio Dev Essentials program. After installation, you can add the Arm-specific components by running the following from a Command Prompt:
\nvs_installer.exe ^\n--add Microsoft.VisualStudio.Workload.NativeDesktop ^\n--add Microsoft.VisualStudio.Component.VC.ATLMFC ^\n--add Microsoft.VisualStudio.Component.VC.Tools.ARM64 ^\n--add Microsoft.VisualStudio.Component.VC.MFC.ARM64 ^\n--includeRecommended\nSetting npm_config_arch=arm64 in the environment creates the correct arm64 .obj files, but the standard Developer Command Prompt for VS 2017 will use the x64 linker. To fix this:
vcvarsamd64_arm64.bat at the end instead of vcvarsamd64_x86.bat.If done successfully, the command prompt should print something similar to this on startup:
\n**********************************************************************\n** Visual Studio 2017 Developer Command Prompt v15.9.15\n** Copyright (c) 2017 Microsoft Corporation\n**********************************************************************\n[vcvarsall.bat] Environment initialized for: 'x64_arm64'\nIf you want to develop your application directly on a Windows on Arm device, substitute vcvarsx86_arm64.bat in Target so that cross-compilation can happen with the device's x86 emulation.
node.libBy default, node-gyp unpacks Electron's node headers and downloads the x86 and x64 versions of node.lib into %APPDATA%\\..\\Local\\node-gyp\\Cache, but it does not download the arm64 version (a fix for this is in development.) To fix this:
node.lib from https://electronjs.org/headers/v6.0.9/win-arm64/node.lib%APPDATA%\\..\\Local\\node-gyp\\Cache\\6.0.9\\arm64\\node.libSubstitute 6.0.9 for the version you're using.
After completing all of the above, open your cross-compilation command prompt and run set npm_config_arch=arm64. Then use npm install to build your project as normal. As with cross-compiling x86 modules, you may need to remove node_modules to force recompilation of native modules if they were previously compiled for another architecture.
Debugging native modules can be done with Visual Studio 2017 (running on your development machine) and corresponding Visual Studio Remote Debugger running on the target device. To debug:
\n.exe 应用(传递 --inspect-brk 参数可以在加载任何 native modules 之前暂停应用)。.pdb symbols under Debugging > Symbols.If you encounter a problem with this documentation, or if your app works when compiled for x86 but not for arm64, please file an issue with \"Windows on Arm\" in the title.
", "title": "Windows on ARM", "description": "" }, "/docs/tutorial/windows-store-guide": { "locale": "zh-CN", "slug": "windows-store-guide", "href": "/docs/tutorial/windows-store-guide", "crowdinFileId": "256273", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-store-guide.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "在 Windows 10 中，一些不错的旧 win32 程序迎来了一个新朋友：通用 Windows 平台。 新的 .appx 格式不仅启用了许多新的强大的 API，如 Cortana 或推送通知，而且通过 Windows 应用商店，也同时简化了安装和更新。
Microsoft 开发了一个工具，将 Electron 应用程序编译为 .appx 软件包，使开发人员能够使用新应用程序模型中的一些好东西。 本指南解释了如何使用它 - 以及 Electron AppX 包的功能和限制。
Windows 10 的 \"周年更新\" 能够运行 win32 .exe 程序并且它们的虚拟化文件系统和注册表跟随一起启动。 两者都是通过在 Windows 容器中运行应用程序和安装器编译后创建的，允许 Windows 在安装过程中正确识别操作系统进行了哪些修改。 将可执行文件和虚拟文件系统与虚拟注册表配对, 允许 Windows 启用一键安装和卸载。
此外，exe 在 appx 模型内启动 - 这意味着它可以使用通用 Windows 平台可用的许多 API。 为了获得更多的功能，Electron 应用程序可以与一个看不见的 UWP 后台任务配合使用，它与 exe 一起启动，作为后台运行任务的接收器，接收推送通知或与其他 UWP 应用程序通信 。
要编译任何现有的 Electron 应用程序，请确保满足以下要求:
\nnode -v 来确认)然后, 安装 electron-windows-store CLI:
npm install -g electron-windows-store\n打包应用程序使用 electron-packager (或类似工具). 确保在最终的应用程序中删除不需要的 node_modules, 因为这些你不需要模块只会额外增加你的应用程序的大小.
结构输出应该看起来大致像这样:
\n├── Ghost.exe\n├── LICENSE\n├── content_resources_200_percent.pak\n├── content_shell.pak\n├── d3dcompiler_47.dll\n├── ffmpeg.dll\n├── icudtl.dat\n├── libEGL.dll\n├── libGLESv2.dll\n├── locales\n│ ├── am.pak\n│ ├── ar.pak\n│ ├── [...]\n├── node.dll\n├── resources\n│ └── app.asar\n├── v8_context_snapshot.bin\n├── squirrel.exe\n└── ui_resources_200_percent.pak\n从提权的 PowerShell(用管理员身份运行它) 中, 以所需的参数运行 electron-windows-store，传递输入和输出目录，应用程序的名称和版本，以及确认 node_modules 应该是扁平的。
electron-windows-store `\n --input-directory C:\\myelectronapp `\n --output-directory C:\\output\\myelectronapp `\n --package-version 1.0.0.0 `\n --package-name myelectronapp\n一旦执行，工具就开始工作：它接受您的 Electron 应用程序作为输入，展平 node_modules。 然后，它将应用程序归档为 app.zip。 使用安装程序和 Windows 容器，该工具创建一个“扩展的” AppX 包 - 包括 Windows 应用程序清单 (AppXManifest.xml)以及虚拟文件系统和输出文件夹中的虚拟注册表。
当创建扩展的 AppX 文件后，该工具使用 Windows App Packager(MakeAppx.exe)将磁盘上的这些文件创建为单文件 AppX 包。 最后，该工具可用于在计算机上创建可信证书，以签署新的 AppX 包。 使用签名的 AppX 软件包，CLI也可以自动在您的计算机上安装软件包。
为了运行您的软件包，您的用户将需要将 Windows 10 安装“周年纪念更新” - 有关如何更新Windows的详细信息可以在这里找到
\n与传统的UWP应用程序不同，打包应用程序目前需要进行手动验证过程，您可以在这里申请. 在此期间，所有用户都能够通过双击安装包来安装您的程序，所以如果您只是寻找一个更简单的安装方法，可能不需要提交到商店。 在受管理的环境中(通常是企业), Add-AppxPackage PowerShell Cmdlet 可用于以自动方式安装它。
另一个重要的限制是编译的 AppX 包仍然包含一个 win32 可执行文件，因此不会在 Xbox，HoloLens 或 Phones 中运行。
\n您可以将 Electron 应用程序与不可见的 UWP 后台任务配对，以充分利用 Windows 10 功能，如推送通知，Cortana 集成或活动磁贴。
\n如何使用 Electron 应用程序通过后台任务发送 Toast 通知和活动磁贴, 请查看微软提供的案例.
\n要生成 AppX 包，electron-windows-store CLI 使用的模板应该适用于大多数 Electron 应用程序。 但是，如果您使用自定义安装程序，或者您遇到生成的包的任何问题，您可以尝试使用 Windows 容器编译创建包 - 在该模式下，CLI 将在空 Windows 容器中安装和运行应用程序，以确定应用程序正在对操作系统进行哪些修改。
在第一次运行 CLI 之前，您必须安装 “Windows Desktop App Converter” 。 这将需要几分钟，但不要担心 - 你只需要这样做一次。 从这里下载 Desktop App Converter 您将得到两个文件： DesktopAppConverter.zip 和 BaseImage-14316.wim.
DesktopAppConverter.zip. 打开提权的 PowerShell (用\"以管理员权限运行\"打开, 确保您的系统执行策略允许我们通过调用 Set-ExecutionPolicy bypass 来运行我们想要运行的一切)..\\DesktopAppConverter.ps1 -Setup -BaseImage .\\BaseImage-14316.wim, 运行 Desktop App Converter 安装，并传递 Windows 基本映像的位置 (下载的 BaseImage-14316.wim).当安装成功后，您可以继续编译你的 Electron 应用程序。
", "title": "Windows 商店指南", "description": "" }, "/docs/tutorial/windows-taskbar": { "locale": "zh-CN", "slug": "windows-taskbar", "href": "/docs/tutorial/windows-taskbar", "crowdinFileId": "256275", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-taskbar.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron有API来配置Windows任务栏中的应用程序图标。 此API 支持windows 专用的功能有： 创建 JumpList, 自定义缩略图和工具栏, 图标覆盖, 和 \"Flash Frame\" 效果, 和跨平台的功能 有：最近打开的文档 和 应用程序进度.
Windows 允许应用程序自定义一个菜单栏，当用户右键单击任务栏中的应用图标及可显示该列表。 该上下文菜单被成为 弹出列表. You specify custom actions in the Tasks category of JumpList, as quoted from MSDN:
\n\n应用程序的“任务”列表的制定是基于程序的功能，用户能用它做一些快捷操作。 任务应当是与上下文无关的，因为它不需要程序运行就可以工作。 而且据统计，它们应该是用户在这个应用上使用最多的操作，例如: 撰写一封邮件或者在邮件程序里打开日历，word处理程序新建一个文档，以某一种模式启动应用程序，或者是启动应用程序的某些子命令。 一个应用程序不应当定义一些用户不需要的高级功能的或者只会使用一次的操作的菜单，以防止将菜单弄得杂乱无章，例如注册。 不要将“任务”功能用于广告操作，例如升级应用或者推广特价产品等等。
\n强烈推荐“任务”列表内容是静态的。 不管什么情形，也不管应用程序是什么状态，它都应该是保持不变的。 尽管这个列表是动态可变的，你应该注意，那些没想过这个列表会变的用户会被这个行为搞糊涂。
\n
\n\n注：上面的屏幕截图是 IE 浏览器的任务栏示例
\n
MacOS里的docker menu是菜单项，然而windows里的user tasks只是一个快捷方式。 举个栗子，当用户点击task的时候，程序将会执行特定的参数。
\n你可以方便在你的application里用app.setUserTasks API 去设置user task。
\n从 Quick Start Guide 中的应用开始，将以下内容更新到 main.js。
const { app } = require('electron')\n\napp.setUserTasks([\n {\n program: process.execPath,\n arguments: '--new-window',\n iconPath: process.execPath,\n iconIndex: 0,\n title: 'New Window',\n description: 'Create a new window'\n }\n])\nTo clear your tasks list, you need to call app.setUserTasks with an empty array in the main.js file.
const { app } = require('electron')\n\napp.setUserTasks([])\n\n\n注意：即使你的应用关闭，用户任务仍然会被显示，因此在你的应用被卸载之前，任务的图标和程序的路径必须是存在的。
\n
在 Windows，你可以在任务栏上添加一个按钮来当作应用的缩略图工具栏。 它为用户提供了一种访问特定窗口命令的方式, 而无需还原或激活该窗口。
\nAs quoted from MSDN:
\n\n\n此工具栏只是常见的标准工具栏控件。 它最多拥有七个按钮。 每个按钮的 ID、图像、工具提示和状态都定义在结构中, 然后传递给任务栏。 应用程序可以根据其当前状态的要求, 显示、启用、禁用或隐藏缩略图工具栏中的按钮。
\n例如, Windows 媒体播放机可能提供标准的媒体传输控制, 如播放、暂停、静音和停止。
\n
\n\n注：上面的屏幕截图是 Windows 媒体播放器的缩略图工具栏示例
\n
To set thumbnail toolbar in your application, you need to use BrowserWindow.setThumbarButtons
\n从 Quick Start Guide 中的应用开始，将以下内容更新到 main.js。
const { BrowserWindow } = require('electron')\nconst path = require('path')\n\nconst win = new BrowserWindow()\n\nwin.setThumbarButtons([\n {\n tooltip: 'button1',\n icon: path.join(__dirname, 'button1.png'),\n click () { console.log('button1 clicked') }\n }, {\n tooltip: 'button2',\n icon: path.join(__dirname, 'button2.png'),\n flags: ['enabled', 'dismissonclick'],\n click () { console.log('button2 clicked.') }\n }\n])\n要清除缩略图工具栏按钮，您需要在 main.js 文件调用 BrowserWindow.setThumbaritons 函数设置为空数组。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.setThumbarButtons([])\n在 Windows，任务栏按钮可以使用小型叠加层显示应用程序状态。
\nAs quoted from MSDN:
\n\n\n图标叠加作为状态的上下文通知, 旨在否定需要一个单独的通知区域状态图标来将该信息传达给用户。 例如, 当前在通知区域中显示的 Microsoft Outlook 中的新邮件状态现在可以通过任务栏按钮上的叠加来表示。 同样, 您必须在开发周期中决定哪个方法最适合您的应用程序。 叠加图标用于提供重要的、长期的状态或通知, 如网络状态、messenger 状态或新邮件。 不应向用户显示不断变化的叠加或动画。
\n
\n\n注：上面的屏幕截图是任务栏按钮叠加的示例
\n
To set the overlay icon for a window, you need to use the BrowserWindow.setOverlayIcon API.
\n从 Quick Start Guide 中的应用开始，将以下内容更新到 main.js。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.setOverlayIcon('path/to/overlay.png', 'Description for overlay')\n在Windows上，你可以突出显示任务栏按钮以获得用户的关注。 这与在 macOS 上 dock 弹跳图标相似。
\nAs quoted from MSDN:
\n\n\n通常, 会闪现一个窗口, 通知用户该窗口需要注意, 但是该窗口当前没有键盘焦点。
\n
To flash the BrowserWindow taskbar button, you need to use the BrowserWindow.flashFrame API.
\n从 Quick Start Guide 中的应用开始，将以下内容更新到 main.js。
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.once('focus', () => win.flashFrame(false))\nwin.flashFrame(true)\n\n", "title": "Taskbar Customization (Windows)", "description": "应用程序的“任务”列表的制定是基于程序的功能，用户能用它做一些快捷操作。 任务应当是与上下文无关的，因为它不需要程序运行就可以工作。 而且据统计，它们应该是用户在这个应用上使用最多的操作，例如: 撰写一封邮件或者在邮件程序里打开日历，word处理程序新建一个文档，以某一种模式启动应用程序，或者是启动应用程序的某些子命令。 一个应用程序不应当定义一些用户不需要的高级功能的或者只会使用一次的操作的菜单，以防止将菜单弄得杂乱无章，例如注册。 不要将“任务”功能用于广告操作，例如升级应用或者推广特价产品等等。\n强烈推荐“任务”列表内容是静态的。 不管什么情形，也不管应用程序是什么状态，它都应该是保持不变的。 尽管这个列表是动态可变的，你应该注意，那些没想过这个列表会变的用户会被这个行为搞糊涂。" } }, "fr-FR": { "/docs/api/accelerator": { "locale": "fr-FR", "slug": "accelerator", "href": "/docs/api/accelerator", "crowdinFileId": "256277", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/accelerator.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "注意：别忘了调用
\nwin.flashFramework(false)来关闭闪烁。 在上面的示例中, 当窗口进入焦点时会调用它, 但您可能会使用超时或其他一些事件来禁用它。
\n\nDéfinit des raccourcis clavier.
\n
Les accélérations sont des chaînes de caractères pouvant contenir plusieurs modificateurs et touches, combinés avec le caractère +. Ils sont utilisés pour définir des raccourcis clavier dans votre application.
Exemples:
\nCommandOrControl+ACommandOrControl+Shift+ZLes raccourcis sont enregistrés avec le module globalShortcut en utilisant la méthode register, c.-à-d.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+Y' shortcut listener.\n globalShortcut.register('CommandOrControl+Y', () => {\n // Lance le code ici quand les touches Y et Command/Control sont pressés en même temps.\n })\n})\nSur Linux et Windows, la touche Command n'a aucun effet, donc utilisez CommandOrControl qui représente Command sur macOS et Control sur Linux et Windows pour définir certaines accélérations.
Utilisez Alt au lieu de Option. Utilisez Alt au lieu de Option. La touche Option n’existe que sur macOS, tandis que la touche Alt est disponible sur toutes les plateformes.
The Super (or Meta) key is mapped to the Windows key on Windows and Linux and Cmd on macOS.
Command (ou Cmd pour faire court)Control (ou Ctrl pour faire court)CommandOrControl (ou CmdOrCtrl pour faire court)AltOptionAltGrShiftSuperMeta0 à 9A à ZF1 à F24~, !, @, #, $, etc.PlusSpaceTabCapslockNumlockDéfilementBackspaceDeleteInsertReturn (ou Enter comme alias)Up, Down, Left et RightHome et EndPageUp et PageDownEscape (ou Esc pour faire court)VolumeUp, VolumeDown et VolumeMuteMediaNextTrack, MediaPreviousTrack, MediaStop et MediaPlayPausePrintScreennum0 - num9numdec - clé décimalenumadd - numpad + keynumsub - numpad - keynummult - numpad * keynumdiv - numpad ÷ keyRéaliser des applications accessibles est important et nous sommes heureux de fournir une fonctionnalité à Devtron et Spectron qui donne aux développeurs la possibilité d'améliorer leurs applications pour tout le monde.
\nL'accessibilité de développement avec l'application Electron est similaire à la création d'un site web, car les deux fonctionnent avec de L'HTML . Avec les applications Electron, cependant, vous ne pouvez pas utiliser de ressources en ligne afin de mesurer l'accessibilité de votre application, parce qu'elle ne possède pas d'URL sur laquelle ces outils pourraient pointer.
\nThese features bring those auditing tools to your Electron app. You can choose to add audits to your tests with Spectron or use them within DevTools with Devtron. Continuez pour lire une brève introduction de ces outils.
\nIn the testing framework Spectron, you can now audit each window and <webview> tag in your application. Par exemple :
app.client.auditAccessibility().then(function (audit) {\n if (audit.failed) {\n console.error(audit.message)\n }\n})\nVous pouvez en savoir plus sur cette fonctionnalité dans la documentation de Spectron.
\nIn Devtron, there is an accessibility tab which will allow you to audit a page in your app, sort and filter the results.
\n
Ces deux outils utilisent la bibliothèque Outils d'accessibilité pour les développeurs faite par Google pour Chrome. Vous pouvez en apprendre d'avantage sur les règles sur l’audit de l'accessibilité que cette bibliothèque utilise sur ce wiki du répertoire git.
\nSi vous connaissez d'autres outils d'accessibilité pour Electron, ajoutez les à cette documentation avec une pull request.
\nElectron applications will automatically enable accessibility features in the presence of assistive technology (e.g. JAWS on Windows or VoiceOver on macOS). Consultez la documentation d’accessibilité de Chrome pour plus de détails.
\nYou can also manually toggle these features either within your Electron application or by setting flags in third-party native software.
\nBy using the app.setAccessibilitySupportEnabled(enabled) API, you can manually expose Chrome's accessibility tree to users in the application preferences. Note that the user's system assistive utilities have priority over this setting and will override it.
On macOS, third-party assistive technology can toggle accessibility features inside Electron applications by setting the AXManualAccessibility attribute programmatically:
CFStringRef kAXManualAccessibility = CFSTR(\"AXManualAccessibility\");\n\n+ (void)enableAccessibility:(BOOL)enable inElectronApplication:(NSRunningApplication *)app\n{\n AXUIElementRef appRef = AXUIElementCreateApplication(app.processIdentifier);\n if (appRef == nil)\n return;\n\n CFBooleanRef value = enable ? kCFBooleanTrue : kCFBooleanFalse;\n AXUIElementSetAttributeValue(appRef, kAXManualAccessibility, value);\n CFRelease(appRef);\n}\n\n\nContrôle le cycle de vie des événements de votre application.
\n
Processus : Main
\nL’exemple suivant montre comment quitter l’application lorsque la dernière fenêtre est fermée :
\nconst { app } = require('electron')\napp.on('window-all-closed', () => {\n app.quit()\n})\nL'objet app émet les événements suivants :
Émis lorsque l'application a terminé son démarrage de base. Sur Windows et Linux, l'événement will-finish-launching est le même que l'événement ready. Sur macOS, cet événement représente la notification applicationWillFinishLaunching de NSApplication. Vous allez habituellement mettre en place des listeners pour les événements open-file et open-url ici, et lancer le reporteur d'incident et la mise à jour automatique.
Dans la plupart des cas, vous devriez pouvoir tout faire dans l'évènement ready.
Retourne :
\nevent EventlaunchInfo Record<string, any> | NotificationResponse macOSÉmis lorsqu'Electron a terminé l’initialisation. Sur macOS, launchInfo contient le userInfo de la NSUserNotification ou les informations de UNNotificationResponse qui ont été utilisés pour ouvrir l'application , si elle a été lancée à partir du centre de notification. Vous pouvez également appeler app.isReady() pour vérifier si cet événement a déjà été émis et app.whenReady() pour obtenir une Promesse qui sera résolue Electron sera initialisé.
Émis lorsque toutes les fenêtres ont été fermées.
\nSi vous n'être pas abonné à cet événement et que toutes les fenêtres sont fermées, le comportement par défaut consiste à quitter l'application. Toutefois, si vous vous abonnez, vous pouvez contrôler le fait que l'application se ferme ou non. Si l'utilisateur appuie sur Cmd + Q, ou le développeur appelle app.quit(), Electron essaie d'abord de fermer toutes les fenêtres et puis émet l'événement will-quit et dans ce cas, l'événement window-all-closed ne sera pas émis.
Retourne :
\nevent EventÉmis avant que l'application ne commence à fermer ses fenêtres. Appeler event.preventDefault() empêchera le comportement par défaut, qui est de terminer l'application.
Remarque : Si l'application a été quittée par autoUpdater.quitAndInstall(), puis before-quit est émise après émettant un événement close sur toutes les fenêtres et les fermant.
Note: Sous Windows, cet événement ne sera pas émit si l'application est fermée à cause d'un extinction du système/re-démarrage ou une déconnexion de l'utilisateur.
\nRetourne :
\nevent EventÉmis lorsque toutes les fenêtres ont été fermées et que l'application va se fermer. Appeler event.preventDefault() empêchera le comportement par défaut, qui est de terminer l'application.
Consultez la description de l’événement window-all-closed pour voir les différences entre les événements will-quit et window-all-closed.
Note: Sous Windows, cet événement ne sera pas émit si l'application est fermée à cause d'un extinction du système/re-démarrage ou une déconnexion de l'utilisateur.
\nRetourne :
\nevent EventexitCode IntegerÉmis lorsque l'application se quitte.
\nNote: Sous Windows, cet événement ne sera pas émit si l'application est fermée à cause d'un extinction du système/re-démarrage ou une déconnexion de l'utilisateur.
\nRetourne :
\nevent Eventpath StringÉmis lorsque l’utilisateur souhaite ouvrir un fichier avec l’application. L’événement open-file est habituellement émis lorsque l’application est déjà ouvert et le système d’exploitation souhaite réutiliser l’application pour ouvrir le fichier. open-file est également émis lorsqu’un fichier est déposé sur le dock et l’application n’est pas encore en cours d’exécution. Assurez-vous d’écouter l’événement open-file très tôt dans le démarrage votre l’application pour gérer ce cas (même avant que l’événement ready soit émis).
Vous devrez appeler event.preventDefault() si vous souhaitez gérer cet événement.
Sur Windows, vous devrez analyser process.argv (dans le main process) pour obtenir le chemin d'accès.
Retourne :
\nevent Eventurl StringÉmis lorsque l’utilisateur souhaite ouvrir une URL avec l’application. Le fichier de votre application Info.plist doit définir le schéma d'URL dans la touche CFBundleURLTypes et définir NSPrincipalClass à AtomApplication.
Vous devrez appeler event.preventDefault() si vous souhaitez gérer cet événement.
Retourne :
\nevent EventhasVisibleWindows BooleanÉmis lorsque l'application est activée. Différentes actions peuvent déclencher cet événement, comme le lancement de l’application pour la première fois, essayer de relancer l’application lorsqu’elle est déjà en cours d’exécution, ou en cliquant sur l'icône du dock de l’application ou de l’icône de la barre des tâches.
\nRetourne :
\nevent EventÉmis lorsque l'application est activée. Contrairement à l'événement activate, l'événement did-become-active est émit à chaque fois que l'application devient active, et pas seulement sur l'icône du Dock de l'application ou quand l'application est relancée.
Retourne :
\nevent Eventtype String - Une chaîne de caractère identifiant l'activité. Mappé sur NSUserActivity.activityType.userInfo inconnu - Contient l'état spécifique de l'application stocké par l'activité sur un autre appareil.detailswebpageURL String (optional) - A string identifying the URL of the webpage accessed by the activity on another device, if available.Émis au cours de la procédure de transfert quand une activité depuis un périphérique différent veut reprendre. Vous devrez appeler event.preventDefault() si vous souhaitez gérer cet événement.
Une activité d'utilisateur peut être poursuivie seulement dans une application qui a le même identifiant d'équipe développeur que l'application d'origine de la source d'activité et qui prend en charge le type d'activité. La prise en charge d’activité types est spécifiée dans le Info.plist de l'application sous la clé NSUserActivityType.
Retourne :
\nevent Eventtype String - Une chaîne de caractère identifiant l'activité. Mappé sur NSUserActivity.activityType.Émis au cours de la procédure de transfert quand une activité depuis un périphérique différent veut reprendre. Vous devrez appeler event.preventDefault() si vous souhaitez gérer cet événement.
Retourne :
\nevent Eventtype String - Une chaîne de caractère identifiant l'activité. Mappé sur NSUserActivity.activityType.error String - Une chaîne de caractères avec la description localisée de l'erreur.Émis au cours de la procédure de transfert quand une activité depuis un périphérique différent n'arrive pas à reprendre.
\nRetourne :
\nevent Eventtype String - Une chaîne de caractère identifiant l'activité. Mappé sur NSUserActivity.activityType.userInfo inconnu - Contient l'état spécifique de l'application stocké par l'activité.Émis au cours de la procédure de transfertaprès qu'une activité depuis un périphérique différent a bien repris.
\nRetourne :
\nevent Eventtype String - Une chaîne de caractère identifiant l'activité. Mappé sur NSUserActivity.activityType.userInfo inconnu - Contient l'état spécifique de l'application stocké par l'activité.Émis lorsque la procédure de transfert va être repris par un autre appareil. Si vous avez besoin de mettre à jour l'état à transférer, vous devez appeler event.preventDefault() immédiatement, construire un nouveau dictionnaire userInfo et appeler app.updateCurrentActivity() en suivant. Sinon, l'opération échouera et continue-activity-error sera appelée.
Retourne :
\nevent EventÉmis lorsque l'utilisateur clique sur le bouton natif de nouvel onglet de macOS. Le bouton de nouvel onglet n'est visible que si la BrowserWindow actuelle possède un tabbingIdentifier
Retourne :
\nevent Eventwindow BrowserWindowÉmis lorsqu'un browserWindow perd le focus.
\nRetourne :
\nevent Eventwindow BrowserWindowÉmis lorsqu'un browserWindow gagne le focus.
\nRetourne :
\nevent Eventwindow BrowserWindowÉmis lorsqu'un nouveau browserWindow est créé.
\nRetourne :
\nevent EventwebContents WebContentsÉmis lorsqu'un nouveau webContents est créé.
\nRetourne :
\nevent EventwebContents WebContentsurl Stringerror String - Le code d'erreurcertificate Certificatecallback FunctionisTrusted Boolean - Détermine si le certificat doit être considéré comme digne de confianceisMainFrame BooleanÉmis lorsque la vérification du certificate pour l'url a échouée. Pour approuver le certificat, vous devez empêcher le comportement par défaut avec event.preventDefault() et appeler callback(true).
const { app } = require('electron')\n\napp.on('certificate-error', (event, webContents, url, error, certificate, callback) => {\n if (url === 'https://github.com') {\n // Logique de vérification.\n event.preventDefault()\n callback(true)\n } else {\n callback(false)\n }\n})\nRetourne :
\nevent EventwebContents WebContentsurl URLcertificateList Certificate[]callback Functioncertificate Certificate (facultatif)Émis lorsqu'un certificat client est demandé.
\nL' url correspondant à l’entrée de navigation demande le certificat client et le callback peut être appelée avec une entrée filtrée dans la liste. L’utilisation de event.preventDefault() empêche l’application d’utiliser le premier certificat du store.
const { app } = require('electron')\n\napp.on('select-client-certificate', (event, webContents, url, list, callback) => {\n event.preventDefault()\n callback(list[0])\n})\nRetourne :
\nevent EventwebContents WebContentsauthenticationResponseDetailsurl URLauthInfoisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionnom d'utilisateur String (facultatif)mot de passe String (facultatif)Émis lorsque webContents veut faire une authentification normale.
Le comportement par défaut est d'annuler toutes les authentifications. Pour remplacer cela vous devez empêcher le comportement par défaut avec event.preventDefault() et appeler callback(username, password) avec les identifiants.
const { app } = require('electron')\n\napp.on('login', (event, webContents, details, authInfo, callback) => {\n event.preventDefault()\n callback('username', 'secret')\n})\nSi callback est appelé sans nom d'utilisateur ou mot de passe, la demande d'authentification sera annulée et l'erreur d'authentification sera renvoyée à la page .
Émis chaque fois qu'il y a une mise à jour d'informations GPU.
\nRetourne :
\nevent Eventkilled BooleanÉmis lorsque le processus GPU plante ou est tué.
\nDeprecated: Cet événement est remplacé par l'événement child-process-gone qui contient plus d'informations à propos de la raison du plantage du processus enfant. Ceci n'est pas toujours causé par un plantage. Le booléen killed peut être remplacé par la vérification de reason === 'killed' lorsque vous passez à l'utilisation de cet événement.
Retourne :
\nevent EventwebContents WebContentskilled BooleanÉmis lorsque le processus de rendu de webContents plante ou est tué.
Deprecated: Cet événement est remplacé par l'événement render-process-gone qui contient plus d'informations à propos de la raison du plantage du processus enfant. Ceci n'est pas toujours causé par un plantage. Le booléen killed peut être remplacé par la vérification de reason === 'killed' lorsque vous passez à l'utilisation de cet événement.
Retourne :
\nevent EventwebContents WebContentsdetailsreason String - La raison pour laquelle le processus de rendu a disparu. Valeurs possibles :anormal-exit - Le Processus s'est terminé avec un code de sortie différent de zérokilled - Le processus a reçu un SIGTERM ou a été tué autrement de l'extérieurcrashed - Processus s'est plantéoom - Le processus est tombé à cours de mémoirelaunch-failed - Le processus ne s'est pas lancé avec succèsintegrity-failure - Les vérifications d'intégrité du code Windows ont échouéesexitCode Integer - Le code de sortie du proces, sauf si reason est launch-failed, dans ce cas là exitCode sera specifique per plateforme.Émis lorsque le processus de rendu plante de manière inattendue. C'est normalement dans les cas où il s'est planté ou qu'il a été tué.
\nRetourne :
\nevent Eventdetailstype String - Type de processus. Une des valeurs suivantes:UtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownreason String - La raison pour laquelle le processus enfant s'est terminé. Valeurs possibles :anormal-exit - Le Processus s'est terminé avec un code de sortie différent de zérokilled - Le processus a reçu un SIGTERM ou a été tué autrement de l'extérieurcrashed - Processus s'est plantéoom - Le processus est tombé à cours de mémoirelaunch-failed - Le processus ne s'est pas lancé avec succèsintegrity-failure - Les vérifications d'intégrité du code Windows ont échouéesexitCode Number - Le code de sortie du processus (cad: l'état de waitpid sur posix, de GetExitCodeProcess sur Windows).serviceName String (optional) - The non-localized name of the process.name String (facultatif) - Le nom du processus. Examples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.Émis lorsque le processus enfant plante de manière inattendue. C'est normalement dans les cas où il s'est planté ou qu'il a été tué. Cela n'inclut pas le processus de rendu.
\nRetourne :
\nevent EventaccessibilitySupportEnabled Boolean - true quand le support de l'accessibilité de Chrome est activé, sinon false.Émis lorsque le support de l’accessibilité du Chrome change. Cet événement se déclenche lorsque les technologies d’assistance, tels que les lecteurs d’écran sont activés ou désactivés. Voir https://www.chromium.org/developers/design-documents/accessibility pour plus de détails.
\nRetourne :
\nsession SessionÉmis lorsque Electron vient de créer une nouvelle session.
const { app } = require('electron')\n\napp.on('session-created', (session) => {\n console.log(session)\n})\nRetourne :
\nevent Eventargv String[] - un tableau d’arguments de la deuxième instance de la ligne de commandeworkingDirectory String - Le répertoire de travail de la deuxième instanceCet événement sera émis dans l'instance principale de votre application quand une seconde instance a été exécutée et appelle app.requestSingleInstanceLock().
argv est un tableau des arguments de la ligne de commande de la seconde instance, et workingDirectory est son répertoire de travail actuel. Les applications répondent habituellement à cela en faisant de leur fenêtre principale, une fenêtre centrée et non réduite au minimum.
Note: Si la seconde instance a été lancée par un utilisateur différent du premier, le tableau argv ne va pas inclure les arguments.
Cet évènement est garanti d'être émis après que l'évènement ready de app soit émis.
Remarque : Des arguments supplémentaires en ligne de commande peuvent être ajoutés par Chromium, tels que --original-process-start-time.
Retourne :
\nevent EventwebContents WebContentsÉmis lors de l'appel à desktopCapturer.getSources() dans le processus de rendu de webContents. L' Appel à event.preventDefault() lui fera retourner des sources vides.
L'objet app dispose des méthodes suivantes :
Remarque : Certaines méthodes sont seulement disponibles sur des systèmes d'exploitation spécifiques et sont étiquetés comme tels.
\napp.quit()Essayez de fermer toutes les fenêtres. L’événement before-quit sera émis d’abord. Si toutes les fenêtres sont fermées avec succès, l’événement will-quit sera émis et éteindra l’application.
Cette méthode garantit que tous les écouteurs d’événements de beforeunload et unload seront correctement exécutées. Il est possible qu’une fenêtre annule la fermeture en retournant false dans l'écouteur d’événement beforeunload.
app.exit([exitCode])exitCode Integer (facultatif)Sort immédiatement avec exitCode. exitCode est par défaut à 0.
Toutes les fenêtres seront fermées immédiatement sans demander à l'utilisateur, et les événements before-quit et will-quit ne seront pas émis.
app.relaunch([options])options Object (facultatif)args String[] - (facultatif)execPath String (facultatif)Relance l’application lorsque l’instance en cours se termine.
\nPar défaut, la nouvelle instance utilisera le même répertoire de travail et les mêmes arguments de la ligne de commande avec l'instance actuelle. Si args est spécifié, args sera passé comme argument de ligne de commande à la place. Lorsque execPath est spécifié, execPath sera exécuté pour redémarrer à la de l’application actuelle.
Notez bien que cette méthode ne ferme pas l'application, vous devez appeler app.quit ou app.exit après avoir appelé app.relaunch pour faire redémarrer votre application.
Quand app.relaunch est appelé plusieurs fois, plusieurs instances vont être appelées après que l'instance actuelle soit fermée.
Voici un exemple qui redémarre une nouvelle instance immédiatement en ajoutant un nouvel argument de ligne de commande à la nouvelle instance :
\nconst { app } = require('electron') app.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) }) app.exit(0)\napp.isReady()Retourne Boolean - true si Electron a fini de s'initialiser, false sinon. Voir également app.whenReady().
app.whenReady()Returns Promise<void> - Remplie quand Electron est initialisé. Peut astucieusement remplacer la vérification de app.isReady() et l'abonnement à l'événement ready si l'application n'est pas encore prête.
app.focus([options])options Object (facultatif)steal Boolean macOS - Destiner l'action à l'application active même si il s'agit d'une autre application.Sous Linux, donne le focus à la première fenêtre visible. Sur macOS, fait de l'application l'application active. Sous Windows, donne le focus à la première fenêtre de l'application.
\nIl vaut mieux utiliser l'option steal aussi parcimonieusement que possible.
app.hide() macOSMasque toutes les fenêtres d’application sans les minimiser.
\napp.show() macOSAffiche les fenêtres de l'application après qu'elles aient été occultées. Ne leur pas automatiquement le focus. .
\nchemin app.setAppLogsPath([path])path String (facultatif) - Un chemin personnalisé pour vos logs. Doit être absolu.Définit ou crée un répertoire qui peut être manipulé par app.getPath() ou app.setPath(pathName, newPath).
Appeler app. etAppLogsPath() sans paramètre path fera que ce répertoire sera réglé sur ~/Library/Logs/YourAppName sur macOS, et dans le répertoire userData sur Linux et Windows.
app.getAppPath()Retourne String - Répertoire courant de l'application.
app.getPath(name)name String - Nom pour lequel vous pouvez demander le chemin nom:home Répertoire d'accueil de l'utilisateur.appData Répertoire de données par utilisateur de l'application, pointant par défaut sur:%APPDATA% sur Windows$XDG_CONFIG_HOME ou ~/.config sur Linux~/Library/Application Support sur macOSuserData Le dossier pour stocker les fichiers de configuration de votre application, qui par défaut est le dossier appData avec le nom de votre application.cachetemp Dossier temporaire.exe Le fichier exécutable actuel.module La bibliothèque de libchromiumcontent.desktop Le dossier du Bureau de l’utilisateur actuel.documents Dossier \"Mes Documents\" d'un utilisateur.downloads Dossier pour les téléchargements de l’utilisateur.music Dossier de musique de l’utilisateur.pictures Dossier des images de l’utilisateur.videos Dossier des vidéos de l’utilisateur.recent Dossier des fichiers récents de l'utilisateur (Windows seulement).logs Répertoire du dossier de log de votre application.crashDumps Dossier où les rapports d'incidents sont stockés.Retourne String - Un chemin vers le répertoire spécial ou le fichier associé à nom. En cas d'échec, une Error sera levée.
Si app.getPath('logs') est appelé sans que app.setAppLogsPath() soit appelé en premier, un répertoire de logs par défaut sera créé équivalent à un appel app.setAppLogsPath() sans paramètre path.
app.getFileIcon(path[, options])path Stringoptions Object (facultatif)size Stringsmall - 16x16normal - 32x32large - 48x48 sur Linux, 32x32 sur Windows, non pris en charge sur macOS.Retourne Promise<NativeImage> - rempli avec l'icône de l'application, qui est une NativeImage.
Récupère une icône associée à un chemin.
\nSous Windows, il y a 2 sortes d’icônes :
\n.mp3, .png, etc..exe, .dll, .ico.Sur Linux et macOS, les icônes dépendent de l'application associée au type Mime de fichier.
\napp.setPath(name, path)name Stringpath StringRemplace le chemin path par un répertoire spécial ou un fichier associé à name. Si le chemin spécifie un répertoire qui n'existe pas, une Erreur est levée. Dans ce cas, le répertoire doit être créé avec fs.mkdirSync ou similaire.
Vous pouvez remplacer uniquement les chemins d’un name défini dans app.getPath.
Par défaut, les cookies et la cache des pages web seront stockés dans le répertoire userData. Si vous voulez changer cet emplacement, vous devez remplacer le chemin userData avant que l'événement ready du module app soit émis.
app.getVersion()Retourne String - La version de l'application chargée. Si aucune version n'est trouvée dans le fichier package.json de l'application, la version du bundle courant ou de l'exécutable est renvoyée.
app.getName()Retourne String - Le nom de l'application, qui est écrit dans le fichier package.json .
Habituellement, le champ name de package.json est un nom court en minuscule, selon la spécification des modules npm. Vous devriez dans la plupart des cas renseigner également un champ productName, qui contient le nom complet et capitalisé de votre application, et qui sera préféré à name par Electron.
app.setName(name)name StringRemplace le nom de l'application actuelle.
\nNote: Cette fonction remplace le nom utilisé en interne par Electron; elle n'affecte pas le nom que l'OS utilise.
\napp.getLocale()Renvoie String - Les paramètres régionaux actuels de l'application, récupérés à l'aide de la librairie l10n_util de Chromium. Les valeurs de retour possibles sont documentées ici.
To set the locale, you'll want to use a command line switch at app startup, which may be found here.
\nRemarque : À la distribution de votre application empaquetée, vous devrez également inclure le dossier locales.
Remarque : Sous Windows, vous devez l'appeler après que les événements prêts soient émis.
app.getLocaleCountryCode()Retourne String - Les deux lettres de la locale du système d'exploitation de l'utilisateur selon le codage ISO 3166 . La valeur est tirée des API natives d'OS.
Note: Quand il est impossible de détecter le code du pays de la localisation, il renvoie une chaîne vide.
\napp.addRecentDocument(path) macOS Windowspath StringAjoute le path à la liste des documents récents.
Cette liste est gérée par l'OS. Cette liste est gérée par l'Os. Sous Windows, vous pouvez scruter la liste à partir de la barre des tâches et sur macOS à partir du menu du dock.
\napp.clearRecentDocuments() macOS WindowsEfface la liste des documents récents.
\napp.setAsDefaultProtocolClient(protocol[, path, args])protocol String - Le nom de votre protocole, sans le préfixe ://. Par exemple, si vous souhaitez que votre application gère les liens electron://, appelez cette méthode avec electron comme paramètre.path String (facultatif) Windows -Chemin vers l'exécutable d'Electron. Par défaut process.execPathargs String Windows - Arguments transmis à l'exécutable. Par défaut, un tableau videReturns Boolean - Si l'appel a réussi.
Définit l'exécutable courant comme gestionnaire par défaut pour un protocole (alias le schéma URI). Il vous permet d'intégrer votre application plus profondément dans le système d'exploitation. Une fois enregistré, tous les liens avec votre-protocole:// seront ouverts avec l'exécutable courant. L'ensemble du lien, y compris le protocole, sera transmis à votre application comme paramètre.
Remarque: Sur macOS, vous ne pouvez enregistrer que les protocoles qui ont été ajoutés à votre application info.plist, qui ne peut pas être modifié au moment de l'exécution. Cependant, vous pouvez changer le fichier pendant la construction via Electron Forge, Electron Packager, ou en modifiant info.plist avec un éditeur de texte. Veuillez vous référer à la documentation d'Apple pour plus de détails.
Remarque : Dans un environnement Windows Store (lorsque empaqueté en tant qu'appx) cette API retournera true pour tous les appels, mais la clé de registre qu'elle définit ne sera pas accessible par d'autres applications. Afin d'enregistrer votre application Windows Store comme gestionnaire de protocole par défaut, vous devez déclarer le protocole dans votre manifest.
L'API utilise le registre Windows et LSSetDefaultHandlerForURLScheme en interne.
app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windowsprotocol String - Le nom de votre protocole, sans le préfixe ://.path String (facultatif) Windows - process.execPath par défautargs String Windows - Un tableau vide par défautReturns Boolean - Si l'appel a réussi.
Cette méthode vérifie si l'exécutable courant est le gestionnaire par défaut pour un protocole (aka le schéma URI). Si c'est le cas, cela supprimera l'application comme gestionnaire par défaut.
\napp.isDefaultProtocolClient(protocol[, path, args])protocol String - Le nom de votre protocole, sans le préfixe ://.path String (facultatif) Windows - process.execPath par défautargs String Windows - Un tableau vide par défautRetourne Boolean - Si l'exécutable actuel et le gestionnaire par défaut d'un protocole (schéma URI).
Remarque: Sur macOS, vous pouvez utiliser cette méthode pour vérifier si l'application a bien été enregistré comme gestionnaire de protocole par défaut pour un protocole. Vous pouvez également confirmer cela en vérifiant ~/Library/Preferences/com.apple.LaunchServices.plist sur votre machine macOS. Veuillez vous référer à la documentation d'Apple pour plus de détails.
L'API utilise le registre Windows et LSCopyDefaultHandlerForURLScheme en interne.
app.getApplicationNameForProtocol(url)url String - une URL avec le nom du protocole à vérifier. Contrairement aux autre méthodes de cette famille, celle-ci accepte un URL en entier, y compris :// au minimum (par exemple : https://).Retourne String - Nom de l'application qui gère le protocole, ou un <0>String</0> vide s'il n'y a pas de gestionnaire. Par exemple, si Electron est le gestionnaire par défaut de l'URL, il pourrait s'agit de Electron sur Windows et Mac. Par contre, ne vous fiez pas au format précis qui ne garantit pas de ne pas changer. Attendez-vous à un format différent sur Linux, probablement avec un préfixe .desktop.
Cette méthode retourne le nom de l'application du gestionnaire par défaut pour le protocole d'une URL (schéma d'URI).
\napp.getApplicationInfoForProtocol(url) macOS Windowsurl String - une URL avec le nom du protocole à vérifier. Contrairement aux autre méthodes de cette famille, celle-ci accepte un URL en entier, y compris :// au minimum (par exemple : https://).Retourne Promise<Object> - Résoudre avec un objet contenant les éléments suivants :
icon NativeImage - l’icône d’affichage de l’application qui gère le protocole.path String - chemin d’installation de l’application qui gère le protocole.name String - nom complet de l’application qui gère le protocole.This method returns a promise that contains the application name, icon and path of the default handler for the protocol (aka URI scheme) of a URL.
\napp.setUserTasks(tasks) Windowstasks Task[] - Tableau d'objets TaskAjoute tâches à la catégorie Tâches de la liste de sauts sur Windows.
tasks est un tableau d’objets Task.
Returns Boolean - Si l'appel a réussi.
Remarque : Si vous souhaitez personnaliser encore plus la JumpList, utilisez app.setJumpList(categories) à la place.
app.getJumpListSettings() WindowsRetourne Object:
minItems Integer - Le nombre minimum d'éléments qui seront affichés dans la JumpList (pour une description plus détaillée de cette valeur, voir les documentations MSDN).removedItems JumpListItem[] - Tableau des objets JumpListItem qui correspondent aux éléments que l'utilisateur a explicitement retirés des catégories personnalisées dans la liste de saut de . Ces éléments ne doivent pas être ajoutés de nouveau à la JumpList dans l'appel suivant à app.setJumpList(), Windows n'affichera aucune catégorie personnalisée qui contient les éléments supprimés.app.setJumpList(categories) Windowscatégories JumpListCategory[] | null - Tableau d'objets JumpListCategory.Définit ou supprime une JumpList personnalisée pour l'application et renvoie l'une des chaînes de caractères suivantes :
\nok - Tout s'est bien passé.error - Une ou plusieurs erreurs se sont produites, activez la journalisation de la durée d'exécution pour déterminer la cause probable.invalidSeparatorError - An attempt was made to add a separator to a custom category in the Jump List. Separators are only allowed in the standard Tasks category.fileTypeRegistrationError - Tentative d'ajout d'un lien de fichier dans la JumpList pour un type de fichier que l'application n'est pas enregistrée pour gérer.customCategoryAccessDeniedError - Les catégories personnalisées ne peuvent pas être ajoutées à la JumpList en raison de la confidentialité de l'utilisateur ou des paramètres de politique de groupe.Si cetagories est null, la JumpList personnalisée précédemment définie (si existante) sera remplacée par la JumpList standard de l'application (gérée par Windows).
Remarque : Si un objet JumpListCategory n'a ni de type ni de propriété name définie le type est donc supposé être tasks. Si la propriété name est définie mais que le type est omis, alors le type est assumé être custom.
Remarque : Les utilisateurs peuvent supprimer des éléments des catégories personnalisées, et Windows n'autorisera pas l'ajout d'un élément supprimé dans une catégorie personnalisée avant le prochain appel réussi à app.setJumpList(categories). Toute tentative de réajouter un élément supprimé à une catégorie personnalisée plus tôt, cela entraînera l'omission de toute la catégorie personnalisée dans la JumpList. La liste des éléments supprimés peut être obtenue à l'aide de app.getJumpListSettings().
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
Voici un exemple très simple de la création d'une JumpList personnalisé :
\nconst { app } = require('electron')\n\napp.setJumpList([\n {\n type: 'custom',\n name: 'Recent Projects',\n items: [\n { type: 'file', path: 'C:\\\\Projects\\\\project1.proj' },\n { type: 'file', path: 'C:\\\\Projects\\\\project2.proj' }\n ]\n },\n { // has a name so `type` is assumed to be \"custom\"\n name: 'Tools',\n items: [\n {\n type: 'task',\n title: 'Tool A',\n program: process.execPath,\n args: '--run-tool-a',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool A'\n },\n {\n type: 'task',\n title: 'Tool B',\n program: process.execPath,\n args: '--run-tool-b',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool B'\n }\n ]\n },\n { type: 'frequent' },\n { // has no name and no type so `type` is assumed to be \"tasks\"\n items: [\n {\n type: 'task',\n title: 'New Project',\n program: process.execPath,\n args: '--new-project',\n description: 'Create a new project.'\n },\n { type: 'separator' },\n {\n type: 'task',\n title: 'Recover Project',\n program: process.execPath,\n args: '--recover-project',\n description: 'Recover Project'\n }\n ]\n }\n])\napp.request SingleInstanceLock()Retourne Boolean
La valeur renvoyée par cette méthode indique si cette instance de votre application a obtenu le verrou ou non. S'il n'a pas réussi à obtenir le verrou vous pouvez supposer qu'une autre instance de votre application est déjà en cours d'exécution avec le verrou et quitter immédiatement.
\nI.e. This method returns true if your process is the primary instance of your application and your app should continue loading. Elle renvoie false si votre process devrait quitter immédiatement, puisqu'il a envoyé ses paramètres à une instance qui possède déjà le verrou.
Sur macOS, le système impose automatiquement une instance unique lorsque les utilisateurs essaient d'ouvrir une seconde instance de votre application dans Finder, et les événements open-file et open-url seront émis pour cela. Cependant, lorsque les utilisateurs démarrent votre application en ligne de commande , le mécanisme d'instance unique du système sera contourné, et vous devez utiliser cette méthode pour assurer une seule instance.
Un exemple d'activation de la fenêtre de l'instance primaire lorsqu'une seconde instance démarre :
\nconst { app } = require('electron')\nlet myWindow = null\n\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Quelqu'un a tenté d'exécuter une seconde instance. Nous devrions focus la fenêtre.\n if (myWindow) {\n if (myWindow.isMinimized()) myWindow.restore()\n myWindow.focus()\n }\n })\n\n // Créer myWindow, charger le reste de l'app, etc...\n app.whenReady().then(() => {\n myWindow = createWindow()\n })\n}\napp.hasSingleInstanceLock()Retourne Boolean
Cette méthode retourne un booléen indiquant si cette instance de votre application détient actuellement le verrou d'instance unique. Vous pouvez demander le verrou avec app.requestSingleInstanceLock() et le débloquer avec app.releaseSingleInstanceLock()
app.releaseSingleInstanceLock()Releases all locks that were created by requestSingleInstanceLock. This will allow multiple instances of the application to once again run side by side.
app.setUserActivity(type, userInfo[, webpageURL]) macOStype String - Identifie de façon unique l'activité. Mappé sur NSUserActivity.activityType.userInfo n'importe quel - état spécifique à l'application à stocker pour utilisation par un autre appareil.webpageURL String (optional) - The webpage to load in a browser if no suitable app is installed on the resuming device. Le schéma doit être http ou https.Créée un NSUserActivity et le défini en tant qu'activité courante. Après cela, l'activité devient éligible à la fonction Handoff sur l'autre périphérique.
app.getCurrentActivityType() macOSRetourne String - le type de l’activité en cours d’exécution.
app.invalidateCurrentActivity() macOSInvalide l'activité Handoff courante de l'utilisateur.
\napp.resignCurrentActivity() macOSMarque l'activité actuelle de l'utilisateur Handoff comme inactive sans l'invalider.
\napp.updateCurrentActivity(type, userInfo) macOStype String - Identifie de façon unique l'activité. Mappé sur NSUserActivity.activityType.userInfo n'importe quel - état spécifique à l'application à stocker pour utilisation par un autre appareil.Modifie l'activité en cours si son type correspond à type, en fusionnant les entrées de userInfo dans son dictionnaire userInfo courant.
app.setAppUserModelId(id) Windowsid StringChange le Application User Model ID à id.
app.setActivationPolicy(policy) macOSpolicy String - Can be 'regular', 'accessory', or 'prohibited'.Sets the activation policy for a given app.
\nActivation policy types:
\napp.importCertificate(options, callback) Linuxoptionscertificate String - Chemin pour le fichier pkcs12.password String - La Passphrase pour le certificat.callback Functionresult Integer - Résultat de l'importation.Importe le certificat au format pkcs12 dans l'entrepôt de certificats de la plateforme. callback est appelé avec le retour result de l'opération d'import, une valeur 0 indique un succès alors que toute autre valeur signale un problème, telle que décrite par la net_error_list de Chromium.
app.configureHostResolver(options)optionsenableBuiltInResolver Boolean (optional) - Whether the built-in host resolver is used in preference to getaddrinfo. When enabled, the built-in resolver will attempt to use the system's DNS settings to do DNS lookups itself. Enabled by default on macOS, disabled by default on Windows and Linux.secureDnsMode String (optional) - Can be \"off\", \"automatic\" or \"secure\". Configures the DNS-over-HTTP mode. When \"off\", no DoH lookups will be performed. When \"automatic\", DoH lookups will be performed first if DoH is available, and insecure DNS lookups will be performed as a fallback. When \"secure\", only DoH lookups will be performed. Defaults to \"automatic\".secureDnsServers String[] (optional) - A list of DNS-over-HTTP server templates. See RFC8484 § 3 for details on the template format. Most servers support the POST method; the template for such servers is simply a URI. Note that for some DNS providers, the resolver will automatically upgrade to DoH unless DoH is explicitly disabled, even if there are no DoH servers provided in this list.enableAdditionalDnsQueryTypes Boolean (optional) - Controls whether additional DNS query types, e.g. HTTPS (DNS type 65) will be allowed besides the traditional A and AAAA queries when a request is being made via insecure DNS. Has no effect on Secure DNS which always allows additional types. Defaults to true.Configures host resolution (DNS and DNS-over-HTTPS). By default, the following resolvers will be used, in order:
\ngetaddrinfo).This can be configured to either restrict usage of non-encrypted DNS (secureDnsMode: \"secure\"), or disable DNS-over-HTTPS (secureDnsMode: \"off\"). It is also possible to enable or disable the built-in resolver.
To disable insecure DNS, you can specify a secureDnsMode of \"secure\". If you do so, you should make sure to provide a list of DNS-over-HTTPS servers to use, in case the user's DNS configuration does not include a provider that supports DoH.
app.configureHostResolver({\n secureDnsMode: 'secure',\n secureDnsServers: [\n 'https://cloudflare-dns.com/dns-query'\n ]\n})\nCette API doit être appelée après l'émission de l'événement ready .
app.disableHardwareAcceleration()Désactive l'accélération matérielle pour l'application courante.
\nCette méthode peut seulement être appelée avant que app soit prêt.
\napp.disableDomainBlockingFor3DAPIs()By default, Chromium disables 3D APIs (e.g. WebGL) until restart on a per domain basis if the GPU processes crashes too frequently. Cette fonction désactive ce comportement.
\nCette méthode peut seulement être appelée avant que app soit prêt.
\napp.getAppMetrics()Retourne ProcessMetric[] : Tableau d'objets ProcessMetric correspondant aux statistiques d'utilisation de la mémoire et du processeur de tous les processus associés à l'application.
app.getGPUFeatureStatus()Returns GPUFeatureStatus - L'état des fonctions graphiques de chrome://gpu/.
Remarque : Cette information n'est utilisable qu'après l'émission de l'événement gpu-info-update.
app.getGPUInfo(infoType)infoType String - Peut être basique ou complete.Retourne Promise<unknown>
Si infoType vaut complete : La Promise est remplie avec Object contenant toutes les informations sur le GPU, comme pour l'objet GPUInfo de Chromium. Cela inclut les informations de version et driver montrées sur la page chrome://gpu.
Si infoType vaut basic : La Promise est remplie avec Object contenant moins d'attributs que si l'on utilise complete. Voilà un exemple de réponse basique :
{\n auxAttributes:\n {\n amdSwitchable: true,\n canSupportThreadedTextureMailbox: false,\n directComposition: false,\n directRendering: true,\n glResetNotificationStrategy: 0,\n inProcessGpu: true,\n initializationTime: 0,\n jpegDecodeAcceleratorSupported: false,\n optimus: false,\n passthroughCmdDecoder: false,\n sandboxed: false,\n softwareRendering: false,\n supportsOverlays: false,\n videoDecodeAcceleratorFlags: 0\n },\n gpuDevice:\n [{ active: true, deviceId: 26657, vendorId: 4098 },\n { active: false, deviceId: 3366, vendorId: 32902 }],\n machineModelName: 'MacBookPro',\n machineModelVersion: '11.5'\n}\nbasic devrait être priorisé si vous n'avez besoin que d'informations basiques telles que vendorId ou driverId.
app.setBadgeCount([count]) Linux macOScount Integer (optional) - If a value is provided, set the badge to the provided value otherwise, on macOS, display a plain white dot (e.g. unknown number of notifications). Sous Linux, si aucune valeur n'est fournie, le badge ne s'affichera pas.Returns Boolean - Si l'appel a réussi.
Sets the counter badge for current app. Setting the count to 0 will hide the badge.
Sur macOS, il s'affiche sur l'icône du dock. Sous Linux, il ne fonctionne que pour le lanceur Unity.
\nRemarque : Le lanceur Unity nécessite un fichier .desktop pour fonctionner. Pour plus d’informations, lisez la documentation d’intégration Unity.
app.getBadgeCount() Linux macOSRetourne Integer - La valeur actuelle affichée sur le badge du compteur.
app.isUnityRunning() LinuxRetourne Boolean - Si l'environnement de bureau actuel est Unity launcher.
app.getLoginItemSettings([options]) macOS Windowsoptions Object (facultatif)Si vous avez fourni des options path et args à app.setLoginItemSettings, vous devez passer les mêmes arguments ici pour que openAtLogin soit défini correctement.
Retourne Object:
openAtLogin Boolean - true si l'application est configurée pour démarrer à l'ouverture de session.openAsHidden Boolean macOS - true if the app is set to open as hidden at login. Ce paramètre n'est pas disponible sur les MAS builds.wasOpenedAtLogin Boolean macOS - true if the app was opened at login automatically. Ce paramètre n'est pas disponible sur les MAS builds.wasOpenedAsHidden Boolean macOS - true if the app was opened as a hidden login item. Cela indique que l'application ne devrait pas ouvrir la moindre fenêtre au démarrage. Ce paramètre n'est pas disponible sur les MAS builds.restoreState Boolean macOS - true if the app was opened as a login item that should restore the state from the previous session. Cela indique que l'application devrait restaurer les fenêtres qui étaient ouvertes lorsque celle-ci a été précédemment fermée. Ce paramètre n'est pas disponible sur les MAS builds.executableWillLaunchAtLogin Boolean Windows - true if app is set to open at login and its run key is not deactivated. This differs from openAtLogin as it ignores the args option, this property will be true if the given executable would be launched at login with any arguments.launchItems Object[] Windowsname String Windows - name value of a registry entry.path String Windows - The executable to an app that corresponds to a registry entry.args String[] Windows - the command-line arguments to pass to the executable.scope String Windows - one of user or machine. Indicates whether the registry entry is under HKEY_CURRENT USER or HKEY_LOCAL_MACHINE.enabled Boolean Windows - true if the app registry key is startup approved and therefore shows as enabled in Task Manager and Windows settings.app.setLoginItemSettings(settings) macOS Windowssettings ObjectopenAtLogin Boolean (optional) - true to open the app at login, false to remove the app as a login item. Par défaut, faux.openAsHidden Boolean (optional) macOS - true to open the app as hidden. false par défaut. L'utilisateur peut éditer ce paramètre depuis les Préférences Système, alors app.getLoginItemSettings().wasOpenedAsHidden va être vérifié lorsque l'app sera ouverte pour connaître la valeur actuelle. Ce paramètre n'est pas disponible sur les MAS builds.path String (optional) Windows - The executable to launch at login. Defaults to process.execPath.args String Windows - The command-line arguments to pass to the executable. Defaults to an empty array. Take care to wrap paths in quotes.enabled Boolean (optional) Windows - true will change the startup approved registry key and enable / disable the App in Task Manager and Windows Settings. Par défaut, true.name String (optional) Windows - value name to write into registry. Defaults to the app's AppUserModelId(). Configurer les paramètres de l'application lors de l'ouverture de session.Pour fonctionner avec autoUpdater d'Electron sur Windows, qui utilise Squirrel, vous aurez besoin de configurer le chemin de démarrage de Update.exe et de lui passer les arguments qui définissent le nom de votre application. Par exemple :
const appFolder = path.dirname(process.execPath)\nconst updateExe = path.resolve(appFolder, '..', 'Update.exe')\nconst exeName = path.basename(process.execPath)\n\napp.setLoginItemSettings({\n openAtLogin: true,\n path: updateExe,\n args: [\n '--processStart', `\"${exeName}\"`,\n '--process-start-args', `\"--hidden\"`\n ]\n})\napp.isAccessibilitySupportEnabled() macOS WindowsRetourne Boolean - true si le support des fonctionnalités d'accessibilité de Chrome est activé, false sinon. Cette API retournera true si les technologies d'assistance, comme les lecteurs d'écran, sont détectées. Voir https://www.chromium.org/developers/design-documents/accessibility pour de plus amples informations.
app.setAccessibilitySupportEnabled(enabled) macOS Windowsenabled Boolean - Active ou désactive le rendu de l'arbre d'accessibilitéActive manuellement le support de l'accessibilité de Chrome, permettant de mettre à disposition des utilisateurs les commutateurs d'accessibilité dans les paramètres de l'application. Consultez les documents d'accessibilité de Chromium pour plus de détails. Désactivé par défaut.
\nCette API doit être appelée après l'émission de l'événement ready .
Note: Rendering accessibility tree can significantly affect the performance of your app. Il ne doit pas être activé par défaut.
\napp.showAboutPanel()Show the app's about panel options. These options can be overridden with app.setAboutPanelOptions(options).
app.setAboutPanelOptions(options)optionsapplicationName String (optional) - Nom de l'application.applicationVersion String (optional) - Version de l'application.copyright String (optional) - Information copyright.version String (optional) macOS - The app's build version number.credits String (optional) macOS Windows - Credit information.authors String Linux - List of app authors.website String (optional) Linux - The app's website.iconPath String (optional) Linux Windows - Path to the app's icon in a JPEG or PNG file format. Sous Linux, sera affiché en 64x64 pixels tout en conservant le ratio.Configure les options de la fenêtre À propos de. This will override the values defined in the app's .plist file on macOS. Voir la documentation Apple pour de plus amples informations. Sous Linux, les valeurs doivent être définies pour être affichées ; il n'y a pas de valeurs par défaut.
Si vous ne définissez pas credits mais vous souhaitez quand même les afficher dans votre app, AppKit cherchera un fichier nommé \"Credits.html\", \"Credits.rtf\", et \"Credits.rtfd\", dans cet ordre, dans le bundle retourné par la méthode la classe main de NSBundle. Le premier fichier trouvé est utilisé, et si aucun n'est trouvé, la zone info est laissée vide. Consultez la documentation Apple pour plus d'informations.
app.isEmojiPanelSupported()Retourne Boolean - que la version actuelle de l'OS autorise ou non les sélecteurs natifs d'émojis.
app.showEmojiPanel() macOS WindowsMontrer le sélecteur d'émoji natif de la plateforme.
\napp.startAccessingSecurityScopedResource(bookmarkData) masbookmarkData String - Les données de marque-page encodées en base64 renvoyées par les méthodes dialog.showOpenDialog où dialog.showSaveDialog.Returns Function - This function must be called once you have finished accessing the security scoped file. If you do not remember to stop accessing the bookmark, kernel resources will be leaked and your app will lose its ability to reach outside the sandbox completely, until your app is restarted.
// Commence à accéder au fichier.\nconst stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)\n// You can now access the file outside of the sandbox 🎉\n\n// Remember to stop accessing the file once you've finished with it.\nstopAccessingSecurityScopedResource()\nCommencez à accéder à une ressource périmée de sécurité. Avec cette méthode, les applications Electron qui sont empaquetées pour le Mac App Store peuvent atteindre en dehors de leur sandbox pour accéder aux fichiers choisis par l'utilisateur. Voir la documentation de Apple pour une description du fonctionnement de ce système.
\napp.enableSandbox()Active le mode \"full sandbox\" dans l'application. This means that all renderers will be launched sandboxed, regardless of the value of the sandbox flag in WebPreferences.
Cette méthode peut seulement être appelée avant que app soit prêt.
\napp.isInApplicationsFolder() macOSReturns Boolean - Whether the application is currently running from the systems Application folder. Use in combination with app.moveToApplicationsFolder()
app.moveToApplicationsFolder([options]) macOSoptions Object (facultatif)conflictHandler Function\\conflictType String - Le type de conflit de déplacement rencontré par le gestionnaire ; peut être exists ou existsAndRunning, où existe signifie qu'une application du même nom est présente dans le répertoire Applications et existsAndRunning signifie à la fois qu'elle existe et qu'elle est actuellement en cours d'exécution.Returns Boolean - Whether the move was successful. Please note that if the move is successful, your application will quit and relaunch.
No confirmation dialog will be presented by default. If you wish to allow the user to confirm the operation, you may do so using the dialog API.
NOTE: This method throws errors if anything other than the user causes the move to fail. Par exemple, si l'utilisateur annule la boîte de dialogue d'autorisation, cette méthode renvoie false. Si nous ne réussissons pas à effectuer la copie, alors cette méthode lancera une erreur. The message in the error should be informative and tell you exactly what went wrong.
\nBy default, if an app of the same name as the one being moved exists in the Applications directory and is not running, the existing app will be trashed and the active app moved into its place. If it is running, the pre-existing running app will assume focus and the previously active app will quit itself. Ce comportement peut être modifié en fournissant le gestionnaire de conflits facultatif, où le booléen retourné par le gestionnaire détermine si le conflit de déplacement est résolu avec le comportement par défaut. c'est-à-dire que retourner false ne garantira aucune action supplémentaire, retourner true entraînera le comportement par défaut et la méthode continuera.
Par exemple :
\napp.moveToApplicationsFolder({\n ConftHandler: (conflictType) => {\n if (conflictType === 'exiss') {\n dialogue de retour. howMessageBoxSync({\n type: 'question',\n boutons: ['Halter le déplacement', 'Continuer le déplacement'],\n defaultId: 0,\n message : 'Une application de ce nom existe déjà'\n }) === 1\n }\n }\n})\nCela signifierait que si une application existe déjà dans le répertoire de l'utilisateur, si l'utilisateur choisit de \"Continuer le déplacement\", alors la fonction continuera avec son comportement par défaut et l'application existante sera mise à la corbeille et l'application active sera déplacée à sa place.
\napp.isSecureKeyboardEntryEnabled() macOSReturns Boolean - whether Secure Keyboard Entry is enabled.
Par défaut cette API retournera false.
app.setSecureKeyboardEntryEnabled(enabled) macOSenabled Boolean - Enable or disable Secure Keyboard EntrySet the Secure Keyboard Entry is enabled in your application.
By using this API, important information such as password and other sensitive information can be prevented from being intercepted by other processes.
\nSee Apple's documentation for more details.
\nNote: Enable Secure Keyboard Entry only when it is needed and disable it when it is no longer needed.
app.accessibilitySupportEnabled macOS WindowsUne propriété Booléen qui est vraie si le support d'accessibilité de Chrome est activé, faux sinon. Cette propriété sera true si l'utilisation de technologies d'assistance, telles que les lecteurs d'écran, a été détectée. Définir cette propriété à true active manuellement la prise en charge de l'accessibilité de Chrome, permettant aux développeurs d'exposer le basculement d'accessibilité aux utilisateurs dans les paramètres de l'application.
See Chromium's accessibility docs for more details. Désactivé par défaut.
\nCette API doit être appelée après l'émission de l'événement ready .
Note: Rendering accessibility tree can significantly affect the performance of your app. Il ne doit pas être activé par défaut.
\napp.applicationMenuUne propriété Menu | null qui renvoie Menu si on a été défini et null autrement. Les utilisateurs peuvent passer un Menu pour définir cette propriété.
app.badgeCount Linux macOSAn Integer property that returns the badge count for current app. Setting the count to 0 will hide the badge.
On macOS, setting this with any nonzero integer shows on the dock icon. On Linux, this property only works for Unity launcher.
\nRemarque : Le lanceur Unity nécessite un fichier .desktop pour fonctionner. Pour plus d’informations, lisez la documentation d’intégration Unity.
Note: On macOS, you need to ensure that your application has the permission to display notifications for this property to take effect.
\napp.commandLine ReadonlyUn objet CommandLine qui vous permet de lire et de manipuler les arguments de ligne de commande que Chromium utilise.
app.dock macOS ReadonlyA Dock | undefined object that allows you to perform actions on your app icon in the user's dock on macOS.
app.isPackaged ReadonlyUne propriété Boolean qui renvoie true si l'application est packagée, false sinon. Pour de nombreuses applications, cette propriété peut être utilisée pour distinguer les environnements de développement et de production.
nom de l'applicationUne propriété String qui indique le nom de l'application courante, qui est le nom dans le fichier package.json de l'application.
Habituellement, le champ name de package.json est un nom court en minuscule, selon la spécification des modules npm. Vous devriez dans la plupart des cas renseigner également un champ productName, qui contient le nom complet et capitalisé de votre application, et qui sera préféré à name par Electron.
format@@0 app.userAgentFallbackUne String qui est la chaîne d'agent utilisateur que Electron utilisera comme solution de repli global.
C'est l'agent utilisateur qui sera utilisé quand aucun agent utilisateur n'est défini au niveau webContents ou session. Il est utile pour s'assurer que l'ensemble de votre application a le même agent utilisateur. Définissez une valeur personnalisée dès que possible dans l'initialisation de votre application pour vous assurer que votre valeur remplacée est utilisée.
app.runningUnderRosettaTranslation macOS Readonly DeprecatedA Boolean which when true indicates that the app is currently running under the Rosetta Translator Environment.
You can use this property to prompt users to download the arm64 version of your application when they are running the x64 version under Rosetta incorrectly.
\nDeprecated: This property is superceded by the runningUnderARM64Translation property which detects when the app is being translated to ARM64 in both macOS and Windows.
app.runningUnderARM64Translation Readonly macOS WindowsA Boolean which when true indicates that the app is currently running under an ARM64 translator (like the macOS Rosetta Translator Environment or Windows WOW).
You can use this property to prompt users to download the arm64 version of your application when they are running the x64 version under Rosetta incorrectly.
", "title": "app", "description": "Contrôle le cycle de vie des événements de votre application." }, "/docs/tutorial/application-debugging": { "locale": "fr-FR", "slug": "application-debugging", "href": "/docs/tutorial/application-debugging", "crowdinFileId": "256175", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/application-debugging.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Chaque fois que votre application Electron ne se comporte pas comme vous le souhaitez, un panel d'outils de débogage peut vous aider à trouver des erreurs de code, des goulots d’étranglement ou possibilités d’optimisation.
\nL’outil le plus complet pour déboguer les processus individuels de rendu est le Chromium Developer Toolset. Il est disponible pour tous les processus de rendu, y compris les instances de BrowserWindow, BrowserView et WebView. Vous pouvez les ouvrir en appelant l'API openDevTools() sur le webContents de l’instance :
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.webContents.openDevTools()\nGoogle offre une excellente documentation pour leurs outils de développement. Nous vous recommandons que vous vous familiariser avec eux - ils sont généralement un des utilitaires plus puissants dans le panel d’outil à disposition des développeur Electron.
\nDéboguer le processus principal est un peu plus compliqué, car vous ne pouvez pas ouvrir les outils de développement. Le Chromium Developer Tool peut être utilisé pour déboguer le processus principal d'Electron grâce à une collaboration plus étroite entre Google / Chrome et Node.js, mais vous risquez de rencontrer des étrangetés comme require n’étant pas présent dans la console.
Pour plus d'informations, voir la documentation sur le Débogage du processus principal.
\nIf the V8 context crashes, the DevTools will display this message.
\nDevTools was disconnected from the page. Once page is reloaded, DevTools will automatically reconnect.
Chromium logs can be enabled via the ELECTRON_ENABLE_LOGGING environment variable. For more information, see the environment variables documentation.
Alternatively, the command line argument --enable-logging can be passed. Plus d'informations sont disponibles dans la documentation des commutateurs de ligne de commande.
Pour distribuer votre application avec Electron, vous devez l’empaqueter et la rebaptiser. Pour ce faire, vous pouvez utiliser des outils spécialisés ou une approche manuelle.
\nVous pouvez utiliser les outils suivants pour distribuer votre application :
\n\nCes outils se chargeront des différentes opérations nécessaires à l'obtention d'une application Electron distribuable telles que l'empaquetage, le renommage de l'exécutable et l'initialisation des icones.
\nVous pouvez consulter un exemple de la façon d’empaquetage d'une application avec electron-forge dans le guide de démarrage rapide.
To distribute your app manually, you need to download Electron's prebuilt binaries. Ensuite, le dossier qui contient votre application devrait être nommé app et placé dans le répertoire de ressources d'Electron, comme illustré dans les exemples suivants.
\n\nNOTE: the location of Electron's prebuilt binaries is indicated with
\nelectron/in the examples below.
Sur macOS :
\nelectron/Electron.app/Contents/Resources/app/\n├── package.json\n├── main.js\n└── index.html\nSur Windows et Linux :
\nelectron/resources/app\n├── package.json\n├── main.js\n└── index.html\nExécutez ensuite Electron.app sous macOS, electron sous Linux ou electron.exe sous Windows, et Electron démarrera en tant qu'application. The electron directory will then be your distribution to deliver to users.
Instead of from shipping your app by copying all of its source files, you can package your app into an asar archive to improve the performance of reading files on platforms like Windows, if you are not already using a bundler such as Parcel or Webpack.
\nPour utiliser une archive asar au lieu du dossier app, vous devez renommer l'archive en app.asar et la placer dans le dossier ressources d'Electron comme ci-dessous. Ainsi, Electron va essayer de lire l'archive et de se lancer à partir de celle-ci.
Sur macOS :
\nelectron/Electron.app/Contents/Resources/\n└── app.asar\nSur Windows et Linux :
\nelectron/resources/\n└── app.asar\nYou can find more details on how to use asar in the electron/asar repository.
Après avoir empaqueté votre application dans Electron, vous voudrez renommer votre application avant de la distribuer aux utilisateurs.
\nVous pouvez renommer Electron.app en n'importe quel nom qui vous plaît, et vous devrez aussi renommer les champs CFBundleDisplayName, CFBundleIdentifier and CFBundleName dans les fichiers suivants :
Electron.app/Contents/Info.plistElectron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plistVous pouvez aussi renommer l'application d'aide pour éviter d'afficher Electron Helper dans le moniteur d'activité, mais assurez vous d'avoir renommé le nom du fichier exécutable de l'application d'aide.
La structure d'une application renommée serait comme :
\nMyApp.app/Contents\n├── Info.plist\n├── MacOS/\n│ └── MyApp\n└── Frameworks/\n └── MyApp Helper.app\n ├── Info.plist\n └── MacOS/\n └── MyApp Helper\nVous pouvez renommer electron.exe en n'importe quel nom qui vous plaît, et modifier son icône et d'autres informations avec des outils tels que rcedit.
Vous pouvez renommer l'exécutable electron par ce que vous voulez.
Il est aussi possible de renommer Electron par le nom du produit et le compiler depuis le code source. Pour faire cela, vous devez définir les arguments de compilation correspondant au nom du produit (electron_product_name = \"LeNomDeVotreProduit\") dans le fichier args.gn et recompiler.
\n\nPermet aux application de se mettre à jour automatiquement d'elles-mêmes.
\n
Processus : Main
\nVoir aussi : Un guide détaillé à propos de l’implémentation des mises à jour dans votre application.
\nautoUpdater est un EventEmitter.
Pour le moment, seuls macOS et Windows sont supportés. Il n'y a aucune prise en charge de l'auto-update sur Linux, il est donc recommandé d'utiliser le gestionnaire de paquets de votre distribution afin de mettre à jour votre application.
\nEn outre, il y a quelques différences subtiles sur chaque plateforme :
\nSur macOS, le module autoUpdater repose sur Squirrel.Mac, ce qui signifie que vous n'avez pas besoin d'une installation spécifique pour le faire fonctionner. Pour les besoins du côté serveur, vous pouvez lire Le support du serveur. Notez que l'App Transport Securité (ATS) s'applique à toutes les demandes formulées dans le cadre du processus de mise à jour. Les applications qui ont besoin de désactiver l'ATS peut ajouter la clé NSAllowsArbitraryLoads à leur fichier plist.
Note: Votre application doit-être signée pour les mises à jour automatiques sur macOS. C'est un pré-requis de Squirrel.Mac.
Sur Windows, vous devrez installer votre application sur la machine d'un utilisateur avant de pouvoir utiliser autoUpdater. Il est donc recommandé d'utiliser electron-winstaller, electron-forge ou le package grunt-electron-installer pour générer un installateur Windows.
Lorsque vous utilisez electron-winstaller ou electron-forge, assurez-vous de ne pas essayer de mettre à jour votre application à sa première exécution (voir aussi ce problème pour plus d'information). Il est également recommandé d'utiliser electron-squirrel-startup pour avoir les raccourcis bureau pour votre application.
\nThe installer generated with Squirrel will create a shortcut icon with an Application User Model ID in the format of com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE, examples are com.squirrel.slack.Slack and com.squirrel.code.Code. Vous devez utiliser le même ID pour votre application qu'avec l'API app.setAppUserModelId, sinon Windows ne sera pas en mesure d'épingler correctement votre application dans la barre des tâches.
Comme Squirrel.Mac, Windows peut héberger des mises à jour sur S3 ou tout autre hôte de fichiers statiques. You can read the documents of Squirrel.Windows to get more details about how Squirrel.Windows works.
\nL'objet autoUpdater émet les événements suivants :
Retourne :
\nerror ErrorÉmis lorsqu’il y a une erreur pendant la mise à jour.
\nÉmis lors de la vérification du commencement d'une mise à jour.
\nÉmis lorsqu'une mise à jour est disponible. La mise à jour est téléchargée automatiquement.
\nÉmis quand il n’y a aucune mise à jour disponible.
\nRetourne :
\nevent EventreleaseNotes StringreleaseName StringreleaseDate DateupdateURL StringÉmis lorsqu'une mise à jour a été téléchargée.
\nSur Windows, seulement releaseName est disponible.
Note: It is not strictly necessary to handle this event. A successfully downloaded update will still be applied the next time the application starts.
\nCet événement est émis après qu'un utilisateur appelle quitAndInstall().
Quand cette API est appelée, l'événement before-quit n'est pas émis avant que toutes les fenêtres soient fermées. Ainsi vous devriez écouter cet évènement si vous voulez effectuer des actions avant que les fenêtres soient fermées et qu'un processus est entrain d'être arrêté, est écouter aussi before-quit.
L'objet autoUpdater dispose des méthodes suivantes :
autoUpdater.setFeedURL(options)optionsurl Stringheaders Record<String, String> (optional) macOS - HTTP request headers.serverType String (optional) macOS - Can be json or default, see the Squirrel.Mac README for more information.Définit l'url et initialise l'auto updater.
autoUpdater.getFeedURL()Retourne String - L'URL de flux des mises à jour.
autoUpdater.checkForUpdates()Demande au serveur s'il y a une mise à jour. You must call setFeedURL before using this API.
Note: If an update is available it will be downloaded automatically. Calling autoUpdater.checkForUpdates() twice will download the update two times.
autoUpdater.quitAndInstall()Redémarre l'application et installe la mise à jour après son téléchargement. It should only be called after update-downloaded has been emitted.
Derrière l'appel de autoUpdater.quitAndInstall() fermera toutes les applications windows en premier, appellera automatiquement app.quit() après que toutes les fenêtres aient été fermées.
Note: It is not strictly necessary to call this function to apply an update, as a successfully downloaded update will always be applied the next time the application starts.
", "title": "autoUpdater", "description": "Permet aux application de se mettre à jour automatiquement d'elles-mêmes." }, "/docs/tutorial/automated-testing-with-a-custom-driver": { "locale": "fr-FR", "slug": "automated-testing-with-a-custom-driver", "href": "/docs/tutorial/automated-testing-with-a-custom-driver", "crowdinFileId": "256179", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/automated-testing-with-a-custom-driver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Afin d'écrire des tests automatisés pour votre application Electron, vous aurez besoin d'un moyen de \"piloter\" votre application. Spectron est une solution usuelle, qui vous laisse émuler des actions utilisateur avec WebDriver. Toutefois, il est également possible d'écrire votre propre driver personnalisé avec l'IPC-over-STDIO intégré à node.js. L'avantage d'un driver personnalisé est qu'il demande moins de ressources que Spectron, et qu'il vous laisse éprouver des méthodes personnalisées à votre suite de tests.
\nTo create a custom driver, we'll use Node.js' child_process API. La suite de tests fera apparaître le processus Electron, puis établira un protocole de messagerie basique :
\nconst childProcess = require('child_process')\nconst electronPath = require('electron')\n\n// spawn the process\nconst env = { /* ... */ }\nconst stdio = ['inherit', 'inherit', 'inherit', 'ipc']\nconst appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })\n\n// listen for IPC messages from the app\nappProcess.on('message', (msg) => {\n // ...\n})\n\n// send an IPC message to the app\nappProcess.send({ my: 'message' })\nFrom within the Electron app, you can listen for messages and send replies using the Node.js process API:
\n// listen for IPC messages from the test suite\nprocess.on('message', (msg) => {\n // ...\n})\n\n// send an IPC message to the test suite\nprocess.send({ my: 'message' })\nWe can now communicate from the test suite to the Electron app using the appProcess object.
For convenience, you may want to wrap appProcess in a driver object that provides more high-level functions. Here is an example of how you can do this:
class TestDriver {\n constructor ({ path, args, env }) {\n this.rpcCalls = []\n\n // start child process\n env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages\n this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })\n\n // handle rpc responses\n this.process.on('message', (message) => {\n // pop the handler\n const rpcCall = this.rpcCalls[message.msgId]\n if (!rpcCall) return\n this.rpcCalls[message.msgId] = null\n // reject/resolve\n if (message.reject) rpcCall.reject(message.reject)\n else rpcCall.resolve(message.resolve)\n })\n\n // wait for ready\n this.isReady = this.rpc('isReady').catch((err) => {\n console.error('Application failed to start', err)\n this.stop()\n process.exit(1)\n })\n }\n\n // simple RPC call\n // to use: driver.rpc('method', 1, 2, 3).then(...)\n async rpc (cmd, ...args) {\n // send rpc request\n const msgId = this.rpcCalls.length\n this.process.send({ msgId, cmd, args })\n return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))\n }\n\n stop () {\n this.process.kill()\n }\n}\nIn the app, you'd need to write a simple handler for the RPC calls:
\nif (process.env.APP_TEST_DRIVER) {\n process.on('message', onMessage)\n}\n\nasync function onMessage ({ msgId, cmd, args }) {\n let method = METHODS[cmd]\n if (!method) method = () => new Error('Invalid method: ' + cmd)\n try {\n const resolve = await method(...args)\n process.send({ msgId, resolve })\n } catch (err) {\n const reject = {\n message: err.message,\n stack: err.stack,\n name: err.name\n }\n process.send({ msgId, reject })\n }\n}\n\nconst METHODS = {\n isReady () {\n // do any setup needed\n return true\n }\n // define your RPC-able methods here\n}\nThen, in your test suite, you can use your test-driver as follows:
\nconst test = require('ava')\nconst electronPath = require('electron')\n\nconst app = new TestDriver({\n path: electronPath,\n args: ['./app'],\n env: {\n NODE_ENV: 'test'\n }\n})\ntest.before(async t => {\n await app.isReady\n})\ntest.after.always('cleanup', async t => {\n await app.stop()\n})\nElectron CI on Windows uses AppVeyor, which in turn uses Azure VM images to run. Occasionally, these VM images need to be updated due to changes in Chromium requirements. In order to update you will need PowerShell and the Azure PowerShell module.
\nOccasionally we need to update these images owing to changes in Chromium or other miscellaneous build requirement changes.
\nExemple de cas d'utilisation :\n* We need VS15.9 and we have VS15.7 installed; this would require us to update an Azure image.
Identifiez l'image que vous souhaitez modifier.
\nGet the Azure storage account key
\nappveyorlibccbuilds Disk Storage Account Name you'd look for appveyorlibccbuilds in the list of storage accounts @ Home < Storage AccountsAccess Keys, and then you can use any of the keys present in the list.Obtenir l'URI complet de l'image de la machine virtuelle à partir d'Azure
\n$ACCT_NAME < Blobs < ImagesCopy the image using the Copy Master Image PowerShell script.
\n(images)libcc-20core-vs2017-15.9-2019-04-15.vhdSpin up a new VM using the Create Master VM from VHD PowerShell.
\nps1 avec ./create_master_vm_from_vhd.ps1Standard_F32s_v2East USReconnectez-vous à Azure et trouvez la VM que vous venez de créer dans Home < Virtual Machines < $YOUR_NEW_VM
Using Microsoft Remote Desktop, click Connect to connect to the VM.
AppVeyor Enterprise master VM credentials.Modifier la VM si nécessaire.
\nShut down the VM and then delete it in Azure.
\nAdd the new image to the Appveyor Cloud settings or modify an existing image to point to the new VHD.
\ndeviceName StringdeviceId StringLe développement avec Electron est sans parti pris - il n'y a pas \"un unique chemin\" pour développer, construire, packager, ou sortir une application Electron. Des fonctionnalités supplémentaires pour Electron, à la fois pour la construction et l'exécution, peuvent généralement être trouvées sur npm dans des paquets individuels, permettant aux développeurs de construire l'application et de construire le pipeline dont ils ont besoin.
\nCe niveau de modularité et d'extensibilité garantit que tous les développeurs travaillant avec Electron, que ce soit dans de grandes ou de petites équipes, ne sont jamais limités dans ce qu'ils peuvent ou ne peuvent pas faire pendant leur cycle de vie de développement. Cependant, pour de nombreux développeurs, l'un des boilerplates communautaires ou un outil en ligne de commande peut rendre la compilation, le paquetage et la publication d'une application extrêmement faciles.
\nUn \"Boilerplate\" n'est qu'un point de départ - une toile, pour ainsi dire - à partir de laquelle vous construisez votre application. Ils se présentent généralement sous la forme d'un dossier que vous pouvez cloner et personnaliser.
\nUn outil en ligne de commande quant à lui est à vos côtés durant tout le processus de développement et de déploiement. Ils sont plus assistants et utiles mais imposent une ligne de conduite sur la manière dont votre code doit être structuré et construit. Pour les débutants utiliser un outil en ligne de commande peut-être utile.
\nUn \"outil complet pour construire des applications Electron modernes\". Electron Forge unifie l'actuel outil de build (déjà bien maintenu) pour le développement sous Electron en un paquet afin que chacun puisse se lancer rapidement dans le développement sous Electron.
\nForge est livré avec un template prêt à l'usage, reposant sur Webpack. Il comprend un exemple de configuration typescript et offre deux fichiers de configuration pour permettre une customisation aisée. It uses the same core modules used by the greater Electron community (like electron-packager) – changes made by Electron maintainers (like Slack) benefit Forge's users, too.
Vous pouvez trouver plus d'information et de documentation sur electronforge.io.
\nUne «solution complète pour emballer et construire une application Electron prête à être distribuée» qui se concentre sur une expérience intégrée. électron-builder ajoute une dépendance unique axée sur la simplicité et gère toutes les autres exigences en interne.
\nelectron-builder remplace les fonctionnalités et modules utilisés par les mainteneurs Electron (tels que la mise à jour automatique) par des modules personnalisés. Ils sont généralement plus intégrés, mais auront moins de points communs avec les applications Electron populaires comme Atom, Visual Studio Code ou Slack.
\nVous pouvez trouver plus d'information et de documentation ici.
\nSi vous ne voulez pas d'outils, mais seulement un passe-partout solide à partir duquel construire, CT Lin's electron-react-boilerplate pourrait valoir un coup d'œil. Il est assez populaire dans la communauté et utilise electron-builder en interne.
La liste \"Awesome Electron\" contient plus d'outils et de passe-partout. Si vous trouvez la longueur de la liste intimidante, n'oubliez pas que l'ajout d'outils au fur et à mesure est également une approche valable.
", "title": "Les Boilerplates et CLIs", "description": "" }, "/docs/breaking-changes": { "locale": "fr-FR", "slug": "breaking-changes", "href": "/docs/breaking-changes", "crowdinFileId": "256117", "githubUrl": "https://github.com/electron/electron/tree/main/docs/breaking-changes.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Les changements cassants seront documentés ici, et des avertissements de dépréciations ajoutés au code JS quand possible, au moins une version majeur avant que le changement soit fait.
\nCe document utilise la convention suivante pour catégoriser les modifications majeures :
\nremote moduleLe module remote a été déprécié dans Electron 12, et sera supprimé dans Electron 14. Il est remplacé par le module @electron/remote.
// Déprécié dans Electron 12 :\nconst { BrowserWindow } = require('electron').remote\nRemplacer par :\nconst { BrowserWindow } = require('@electron/remote')\n\n// Dans le processus principal:\nrequire('@electron/remote/main').initialize()\napp.allowRendererProcessReuseLa propriété app.allowRendererProcessReuse sera supprimée dans le cadre de notre plan visant à être le plus étroitement alignées sur le modèle de processus de Chromium en matière de sécurité, de performance et de maintenabilité.
Pour des informations plus détaillées, voir #18397.
\nL'option affinity lors de l'instanciation d'une nouvelle BrowserWindow sera supprimée dans le cadre de notre plan d'alignement sur le modèle de processus de Chromium à des fins de sécurité, performances et maintenabilité.
Pour des informations plus détaillées, voir #18397.
\nwindow.open()Le paramètre optionnel frameName ne définira plus le titre de la fenêtre. Ceci conformément à la spécification décrite par la documentation native sous le paramètre correspondant windowName.
Si vous utilisiez ce paramètre pour définir le titre d'une fenêtre, vous devez utiliser à la place: win.setTitle(title).
\nworldSafeExecuteJavaScriptDans Electron 14, worldSafeExecuteJavaScript sera supprimé. Il n'y a pas d'alternative, s'il vous plaît assurez-vous que votre code fonctionne avec cette propriété activée. Il a été activé par défaut depuis Electron\n12.
Vous serez affecté par ce changement si vous utilisez webFrame.executeJavaScript ou webFrame.executeJavaScriptInIsolatedWorld. Changements de rupture.
nativeWindowOpenest par défaut à truePrior to Electron 14, window.open was by default shimmed to use BrowserWindowProxy. This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. nativeWindowOpen is no longer experimental, and is now the default.
See the documentation for window.open in Electron for more details.
\nPrior to Electron 14, windows opened with window.open would inherit BrowserWindow constructor options such as transparent and resizable from their parent window. À partir d'Electron 14, ce comportement est supprimé et les fenêtres n'hériteront d'aucune option du constructeur BrowserWindow de leurs parents.
Instead, explicitly set options for the new window with setWindowOpenHandler:
webContents.setWindowOpenHandler((details) => {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n // ...\n }\n }\n})\nadditionalFeaturesThe deprecated additionalFeatures property in the new-window and did-create-window events of WebContents has been removed. Since new-window uses positional arguments, the argument is still present, but will always be the empty array []. (Notez toutefois que l’événement new-window lui-même est déprécié et remplacé par setWindowOpenHandler.) Bare keys in window features will now present as keys with the value true in the options object.
// Removed in Electron 14\n// Triggered by window.open('...', '', 'my-key')\nwebContents.on('did-create-window', (window, details) => {\n if (details.additionalFeatures.includes('my-key')) {\n // ...\n }\n})\n\n// Replace with\nwebContents.on('did-create-window', (window, details) => {\n if (details.options['my-key']) {\n // ...\n }\n})\nsession.setPermissionCheckHandler(handler)Le premier paramètre handler des méthodes était auparavant toujours un webContents, il peut maintenant parfois être null. Vous devez utiliser les propriétés requestingOrigin, embeddingOrigin et securityOrigin pour répondre correctement à la vérification des permissions. Comme le webContents peut être désormais null , on ne peut plus s'y fier.
// Ancien code:\nsession.setPermissionCheckHandler((webContents, permission) => {\n if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {\n return true\n }\n return false\n})\n\n// A remplacer par:\nsession.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {\n return true\n }\n return false\n})\nshell.moveItemToTrash()L’API shell.moveItemToTrash() synchrone qui était dépréciée a été supprimée. Utilisez shell.trashItem() asynchrone à la place.
// Supprimé dans Electron 13\nshell.moveItemToTrash(path)\n// Remplacer par\nshell.trashItem(path).then(/* ... */)\nBrowserWindow extension APIsLes API d'extension obsolètes ont été supprimées :
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()Utilisez plutôt les API de session :
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Supprimé dans Electron 13\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Remplacer par\nsession.defaultSession.loadExtension(path)\nSupprimé dans Electron 13\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// Remplacer par\nsession.defaultSession.removeExtension(extension_id)\nSupprimé dans Electron 13\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Remplacer par\nsession.defaultSession.getAllExtensions()\nsystemPreferencesLes méthodes suivantes de systemPreferences ont été dépréciées :
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()Veuillez utiliser à la place les propriétés de nativeTheme suivantes :
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Supprimée dans Electron 13\nsystemPreferences.isDarkMode()\n// Remplacée par\nnativeTheme.shouldUseDarkColors\n\n// Supprimée dans Electron 13\nsystemPreferences.isInvertedColorScheme()\n// Remplacée par\nnativeTheme.shouldUseInvertedColorScheme\n\n// Supprimée dans Electron 13\nsystemPreferences.isHighContrastColorScheme()\n// Remplacée par\nnativeTheme.shouldUseHighContrastColors\nnew-windowL'événement new-window de WebContents est déprécié. Il est remplacé par webContents.setWindowOpenHandler().
// Déprécié dans Electron 13\nwebContents.on('new-window', (event) => {\n event.preventDefault()\n})\n\n// Remplacer par\nwebContents.setWindowOpenHandler((details) => {\n return { action: 'deny' }\n})\nChromium a supprimé la prise en charge de Flash, nous devons donc emboîter le pas. Consultez la feuille de route Flash de Chromium pour plus de détails.
\ntrueDans Electron 12, worldSafeExecuteJavaScript sera activé par défaut. Restaurer le comportement précédent, worldSafeExecuteJavaScript: false doit être spécifié dans WebPreferences. Veuillez noter que définir cette option sur false est non sécurisé.
Cette option sera supprimée dans Electron 14, veuillez donc migrer votre code pour prendre en charge la valeur par défaut.
\ncontextIsolationest par défaut à trueDans Electron 12, contextIsolation sera activé par défaut. Restaurer le comportement précédent, contextIsolation: false doit être spécifié dans WebPreferences.
Nous recommandons que contextIsolation soit activé pour la sécurité de votre application.
\nEn conséquence require() ne peut pas être utilisé dans le processus de rendu à sauf si nodeIntegration est à true et contextIsolation à false.
Pour plus de détails, voir : https://github.com/electron/electron/issues/23506
\ncrashReporter.getCrashesDirectory()La méthode crashReporter.getCrashesDirectory a été supprimée. Usage Devrait être remplacé par app.getPath('crashDumps').
// Supprimé dans Electron 12\ncrashReporter.getCrashesDirectory()\n// Remplacé par\napp.getPath('crashDumps')\ncrashReporter dans le processus de renduLes méthodes crashReporter suivantes ne sont plus disponibles dans le processus de rendu :
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryIls ne doivent être appelés qu'à partir du processus principal.
\nVoir #23265 pour plus de détails.
\ncrashReporter.start({ compress: true })La valeur par défaut de l'option compress en crashReporter.start a changé de false à true. Cela signifie que les rapports de plantage seront envoyés au serveur d'ingestion de plantage avec l'en-tête Content-Encoding: gzip et le corps sera compressé.
Si votre serveur d'ingestion de plantage ne supporte pas les payloads compressées, vous pouvez désactiver la compression en spécifiant { compress: false } dans les options du rapporteur de plantage.
remoteLe module remote est déprécié dans Electron 12, et sera supprimé dans Electron 14. Il est remplacé par le module @electron/remote.
// Déprécié dans Electron 12 :\nconst { BrowserWindow } = require('electron').remote\nRemplacer par :\nconst { BrowserWindow } = require('@electron/remote')\n\n// Dans le processus principal:\nrequire('@electron/remote/main').initialize()\nshell.moveItemToTrash()La méthode synchrone shell.moveItemToTrash() a été remplacée par une asynchrone shell.trashItem() .
Déprécié dans Electron 12\nshell.moveItemToTrash(path)\n// Remplacer par\nshell.trashItem(path).then(/* ... */)\nBrowserView.{destroy, fromId, fromWebContents, getAllViews} et id propriété de BrowserViewLes API expérimentales BrowserView.{destroy, fromId, fromWebContents, getAllViews} ont maintenant été supprimées. De plus, la propriété id de BrowserView a également été supprimée.
Pour des informations plus détaillées, voir #23578.
\ncompanyName de crashReporter.start()L'argument companyName de crashReporter.start(), qui était auparavant requis, est maintenant optionnel et de plus déprécié. Pour obtenir le même comportement de manière non dépréciée, vous pouvez passer une valeur companyName dans globalExtra.
// Déprécié dans Electron 10\ncrashReporter.start({ companyName: 'Umbrella Corporation' })\n// Remplacé par\ncrashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' }})\ncrashReporter.getCrashesDirectory()La méthode crashReporter.getCrashesDirectory a été dépréciée. Usage Devrait être remplacé par app.getPath('crashDumps').
// Déprécié dans Electron 10\ncrashReporter.getCrashesDirectory()\n// Remplacé par\napp.getPath('crashDumps')\ncrashReporter dans le processus de renduL'appel des méthodes crashReporter suivantes à partir du processus de rendu est déprécié :
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryLes seules méthodes non obsolètes restantes dans le module crashReporter du renderer sont addExtraParameter, removeExtraParameter et getParameters.
Toutes les méthodes ci-dessus restent non dépréciées lorsqu'elles sont appelées à partir du processus principal.
\nVoir #23265 pour plus de détails.
\ncrashReporter.start({ compress: false })La configuration { compress: false } dans crashReporter.start est obsolète. Presque tous les serveurs d'ingestion de plantages supportent la compression gzip. Cette option sera supprimée dans une future version d’Electron.
enableRemoteModuleest par défaut à falseDans Electron 9, l'utilisation du module remote sans l'activer explicitement via l'option enableRemoteModule de WebPreferences émet dès maintenant un avertissement. Avec Electron 10, le module remote est dès maintenant désactivé par défaut. Pour utiliser le module remote, on doit spécifier enableRemoteModule : true dans les WebPreferences:
const w = new BrowserWindow({\n webPreferences: {\n enableRemoteModule: true\n }\n})\nNous vous recommandons d'éviter d'utiliser le module distant.
\nprotocol.unregisterProtocolprotocol.uninterceptProtocolLes API sont désormais synchrones donc la callback qui était facultative n'est plus nécessaire.
\n// Déprécié\nprotocol.unregisterProtocol(scheme, () => { /* ... */ })\n// Remplacer par\nprotocol.unregisterProtocol(scheme)\nprotocol.registerFileProtocolprotocol.registerBufferProtocolprotocol.registerStringProtocolprotocol.registerHttpProtocolprotocol.registerStreamProtocolprotocol.interceptFileProtocolprotocol.interceptStringProtocolprotocol.interceptBufferProtocolprotocol.interceptHttpProtocolprotocol.interceptStreamProtocolLes API sont désormais synchrones donc la callback qui était facultative n'est plus nécessaire.
\n// Déprécié\nprotocol.registerFileProtocol(scheme, handler, () => { /* ... */ })\n// Remplacer par\nprotocol.registerFileProtocol(scheme, handler)\nLe protocole enregistré ou intercepté n'a pas d'effet sur la page actuelle tant que la navigation n'a pas eu lieu.
\nprotocol.isProtocolHandledCette API est dépréciée et les utilisateurs doivent utiliser à la place protocol.isProtocolRegistered et protocol.isProtocolIntercepted.
// Déprécié\nprotocol.isProtocolHandled(scheme).then(() => { /* ... */ })\n// Remplacer par\nconst isRegistered = protocol.isProtocolRegistered(scheme)\nconst isIntercepted = protocol.isProtocolIntercepted(scheme)\nÀ partir d’Electron 9, nous n’autorisons plus le chargement de modules natifs insensibles au contexte dans le processus de rendu. Ceci est pour améliorer la sécurité, les performances et la maintenabilité d'Electron en tant que projet.
\nSi cela vous affecte, vous pouvez définir temporairement app.allowRendererProcessReuse pour faux pour revenir à l’ancien comportement. Ce drapeau ne sera une option que jusqu'à Electron 11 donc vous devriez planifier de mettre à jour vos modules natifs pour être sensible au contexte.
Pour des informations plus détaillées, voir #18397.
\nBrowserWindowLes API d'extension suivantes sont obsolètes :
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()Utilisez plutôt les API de session :
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Déprécié dans Electron 9\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Remplacer par\nsession.defaultSession.loadExtension(path)\n// Déprécié dans Electron 9\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// Remplacer par\nsession.defaultSession.removeExtension(extension_id)\n// Déprécié dans Electron 9\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Remplacé par\nsession.defaultSession.getAllExtensions()\n<webview>.getWebContents()Cette API, qui a été dépréciée dans Electron 8.0, est désormais supprimée.
\n// Supprimé dans Electron 9.0\nwebview.getWebContents()\n// Remplacé par\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chrome a supprimé la prise en charge pour modifier les limites de niveau de zoom de mise en page et il n'est plus possible pour Electron de le maintenir. La fonction a été dépréciée dans Electron 8.x, et supprimée dans Electron 9.x. Les limites de niveau de zoom de mise en page sont maintenant fixées à un minimum de 0. 5 et un maximum de 5.0, tel que défini ici.
\nDans Electron 8.0, l'IPC a été modifié pour utiliser l'algorithme Structured Clone , apportant des améliorations significatives des performances. Pour aider à faciliter la transition, l'ancien algorithme de sérialisation IPC a été conservé et utilisé pour certains objets qui ne sont pas sérialisables avec Structured Clone. In particular, DOM objects (e.g. Element, Location and DOMMatrix), Node.js objects backed by C++ classes (e.g. process.env, some members of Stream), and Electron objects backed by C++ classes (e.g. WebContents, BrowserWindow and WebFrame) are not serializable with Structured Clone. Chaque fois que l'ancien algorithme était invoqué, un un avertissement de dépréciation a été imprimé.
In Electron 9.0, the old serialization algorithm has been removed, and sending such non-serializable objects will now throw an \"object could not be cloned\" error.
\nshell.openItem est désormais shell.openPathL'API shell.openItem a été remplacée par une API shell.openPath asynchrone. Vous pouvez voir la proposition initiale de l'API et le raisonnement ici.
L'algorithme utilisé pour sérialiser les objets envoyés par IPC (via ipcRenderer.send, ipcRenderer.sendSync, WebContents. les méthodes de fin et associées) est passé d'un algorithme personnalisé à l'algorithme intégré de V8 Structured Clone Algorithm qui est déja utilisé pour sérialiser les messages dans postMessage. Cela entraîne une amélioration dans un rapport 2 des performances en ce qui concerne les messages de grande taille, mais apporte également quelques changements de rupture dans le comportement.
undefined.// Previously:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => results in { value: 3 } arriving in the main process\n\n// From Electron 8:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => throws Error(\"() => {} could not be cloned.\")\nNaN, Infinity et -Infinity seront désormais correctement sérialisés à la place d'être converti en null.null.Set, Map, Error et RegExp seront correctement sérialisées, au lieu d'être converti en {}.BigInt seront correctement sérialisées, au lieu d'être converties en null.nulls.Date objects will be transferred as Date objects, instead of being converted to their ISO string representation.Uint8Array, Uint16Array, Uint32Array and so on) will be transferred as such, instead of being converted to Node.js Buffer.Buffer objects will be transferred as Uint8Arrays. You can convert a Uint8Array back to a Node.js Buffer by wrapping the underlying ArrayBuffer:Buffer.from(value.buffer, value.byteOffset, value.byteLength)\nSending any objects that aren't native JS types, such as DOM objects (e.g. Element, Location, DOMMatrix), Node.js objects (e.g. process.env, Stream), or Electron objects (e.g. WebContents, BrowserWindow, WebFrame) is deprecated. In Electron 8, these objects will be serialized as before with a DeprecationWarning message, but starting in Electron 9, sending these kinds of objects will throw a 'could not be cloned' error.
<webview>.getWebContents()Cette API est implémentée à l'aide du module remote, qui a à la fois des performances et les implications en matière de sécurité. Par conséquent, son utilisation doit être explicite.
// Déprécié\nwebview.getWebContents()\n// Remplacé par\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nCependant, il est recommandé d'éviter d'utiliser le module remote.
// main\nconst { ipcMain, webContents } = require('electron')\n\nconst getGuestForWebContents = (webContentsId, contents) => {\n const guest = webContents. romId(webContentsId)\n si (! uest) {\n throw new Error(`Invalid webContentsId: ${webContentsId}`)\n }\n if (invité. ostWebContents ! = contents) {\n throw new Error('Accès refusé à webContents')\n }\n return guest\n}\n\nipcMain. handle('openDevTools', (event, webContentsId) => {\n const guest = getGuestForWebContents(webContentsId, event.sender)\n invité. penDevTools()\n})\n\n// moteur de rendu\nconst { ipcRenderer } = require('electron')\n\nipcRenderer.invoke('openDevTools', webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chrome a supprimé la prise en charge pour modifier les limites de niveau de zoom de mise en page et il n'est plus possible pour Electron de le maintenir. La fonction émettra un avertissement dans Electron 8.x, et cessent d'exister dans Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.
\nsystemPreferencesLes événements systemPreferences suivants ont été dépréciés :
inverted-color-scheme-changedhigh-contrast-color-scheme-changedUtilisez à la place le nouvel événement updated sur le module nativeTheme.
// Deprécié\nsystemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })\nsystemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })\n\n// Replacer avec\nnativmeTheme.on('updated', () => { /* ... */ })\nsystemPreferencesLes méthodes suivantes de systemPreferences ont été dépréciées :
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()Veuillez utiliser à la place les propriétés de nativeTheme suivantes :
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Depreciée\nsystemPreferences.isDarkMode()\n// Remplacer par\nnativeTheme.shouldUseDarkColors\n\n// Depreciée\nsystemPreferences.isInvertedColorScheme()\n// Remplacer par\nnativeTheme.shouldUseInvertedColorScheme\n\n// Depreciée\nsystemPreferences.isHighContrastColorScheme()\n// Remplacer par\nnativeTheme.shouldUseHighContrastColors\nIl s’agit de l’URL spécifiée comme disturl dans un fichier .npmrc ou le flag --dist-url en ligne de commande lors de la compilation des modules natifs de Node. Both will be supported for the foreseeable future but it is recommended that you switch.
Déprécié : https://atom.io/download/electron
\nRemplacer par : https://electronjs.org/headers
\nsession.clearAuthCache() n'accepte plus les optionsThe session.clearAuthCache API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.
// Déprécié\nsession.clearAuthCache({ type: 'password' })\n// Remplacer par\nsession.clearAuthCache()\npowerMonitor.querySystemIdleState est désormais powerMonitor.getSystemIdleState// Removed in Electron 7.0\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime est désormais powerMonitor.getSystemIdleTime// Removed in Electron 7.0\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\nwebFrame.setIsolatedWorldInfo replaces separate methods// Supprimé dans Electron 7.0\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Remplacer par\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nmarked property on getBlinkMemoryInfoCette propriété a été supprimée dans Chromium 77 et n'est donc plus disponible.
\nwebkitdirectory attribute for <input type=\"file\"/> now lists directory contentsThe webkitdirectory property on HTML file inputs allows them to select folders. Dans les versions précédentes d'Electron l'implémentation était incorrecte et la propriété event.target.files de l'input retournait une FileList qui retournait un objet File correspondant au dossier sélectionné.
As of Electron 7, that FileList is now list of all files contained within the folder, similarly to Chrome, Firefox, and Edge (link to MDN docs).
En guise d'illustration, considérez un dossier avec cette structure :
\ndossier\n├── fichier1\n├── fichier2\n└── fichier3\nDans Electron < 6, cela renverrait une FileList avec un objetFilepour :
chemin/vers/dossier\nDans Electron 7, cela renvoie maintenant une FileList avec un objetFilepour :
/chemin/vers/dossier/fichier3\n/chemin/vers/dossier/fichier2\n/chemin/vers/dossier/fichier1\nNote that webkitdirectory no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).
Electron 5 et Electron 6 ont introduit des versions des API asynchrones existantes basées sur les promise et déprécié leurs homologues basées sur les callback. Dans Electron 7, toutes les APIs obsolètes basées sur les callback sont maintenant supprimées.
\nLes fonctions suivantes ne retournent plus que des promesses :
\napp.getFileIcon() #15742app.dock.show() #16904contentTracing.getCategories() #16583contentTracing.getTraceBufferUsage() #16600contentTracing.startRecording() #16584contentTracing.stopRecording() #16584contents.executeJavaScript() #17312cookies.flushStore() #16464cookies.get() #16464cookies.remove() #16464cookies.set() #16464debugger.sendCommand() #16861dialog.showCertificateTrustDialog() #17181inAppPurchase.getProducts() #17355inAppPurchase.purchaseProduct()#17355netLog.stopLogging() #16862session.clearAuthCache() #17259session.clearCache() #17185session.clearHostResolverCache() #17229session.clearStorageData() #17249session.getBlobData() #17303session.getCacheSize() #17185session.getCacheSize() #17185session.setProxy() #17222shell.openExternal() #16176() #15855() #15855webContents.hasServiceWorker() #16535webContents.printToPDF() #16795webContents.savePage() #16742webFrame.executeJavaScript() #17312webFrame.executeJavaScriptInIsolatedWorld() #17312webviewTag.executeJavaScript() #17312win.capturePage() #15743Ces fonctions ont maintenant deux formes, synchrone et asynchrone basées sur Promise :
\ndialog.showMessageBox()/dialog.showMessageBoxSync() #17298dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054win.setMenu(null) est désormais win.removeMenu()// Déprécié\nwin.setMenu(null)\n// Remplacé par\nwin.removeMenu()\nelectron.screen dans le processus de rendu doit être accédé via remote// Déprécié\nrequire('electron').screen\n// Remplacé par\nrequire('electron').remote.screen\nrequire()ing node builtins in sandboxed renderers no longer implicitly loads the remote version// Deprecated\nrequire('child_process')\n// Replace with\nrequire('electron').remote.require('child_process')\n\n// Deprecated\nrequire('fs')\n// Replace with\nrequire('electron').remote.require('fs')\n\n// Deprecated\nrequire('os')\n// Replace with\nrequire('electron').remote.require('os')\n\n// Deprecated\nrequire('path')\n// Replace with\nrequire('electron').remote.require('path')\npowerMonitor.querySystemIdleState remplacé par powerMonitor.getSystemIdleState// Deprecated\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime remplacé par powerMonitor.getSystemIdleTime// Deprecated\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\napp.enableMixedSandbox() n'est plus nécessaire// Déprécié\napp.enableMixedSandbox()\nLe mode bac à sable mixte est désormais activé par défaut.
\nTray.setHighlightModeSous macOS Catalina, notre ancienne implémentation de Tray est interrompue. Le substitut natif d'Apple ne prend pas en charge la modification du comportement de mise en évidence.
\n// Déprécié\ntray.setHighlightMode(mode)\n// L'API sera supprimée dans la v7.0 sans remplacement.\nnodeIntegration and webviewTag default to false, contextIsolation defaults to trueLes options suivantes de webPreferences seront dépréciées en faveur de nouvelles valeurs par défaut listées ci-dessous.
| Propriétés | Valeur par défaut dépréciée | Nouvelle valeur par défaut |
|---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration si mis sinon true | false |
Exemple : Re-enabling the webviewTag
\nconst w = new BrowserWindow({\n webPreferences: {\n webviewTag: true\n }\n})\nnodeIntegration dans les fenêtres enfants ouvertes via nativeWindowOpenLes fenêtres enfants ouvertes avec l'option nativeWindowOpen auront toujours Node.js integration désactivée, sauf si nodeIntegrationInSubFrames est à true.
Renderer process APIs webFrame.registerURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. A new API, protocol.registerSchemesAsPrivileged has been added and should be used for registering custom schemes with the required privileges. Les schémas personnalisés doivent être enregistrés avant que l'application soit prête.
webFrame.setIsolatedWorld* remplacé par webFrame.setIsolatedWorldInfo// Deprecated\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Replace with\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nwebFrame.setSpellCheckProvider prend désormais un rappel asynchroneLe rappel spellCheck est désormais asynchrone et le paramètre autoCorrectWord a été supprimé.
// Deprecated\nwebFrame.setSpellCheckProvider('en-US', true, {\n spellCheck: (text) => {\n return !spellchecker.isMisspelled(text)\n }\n})\n// Replace with\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck: (words, callback) => {\n callback(words.filter(text => spellchecker.isMisspelled(text)))\n }\n})\nwebContents.getZoomLevel et webContents.getZoomFactor sont désormais synchroneswebContents.getZoomLevel et webContents.getZoomFactor n'ont plus de callback en paramètre et retournent directement leurs valeur numérique.
// Déprécié:\nwebContents.getZoomLevel((level) => {\n console.log(level)\n})\n// Remplacer par\nconst level = webContents.getZoomLevel()\nconsole.log(level)\n// Déprécié:\nwebContents.getZoomLevel((level) => {\n console.log(factor)\n})\n// Remplacer par\nconst level = webContents.getZoomLevel()\nconsole.log(factor)\nThe following list includes the breaking API changes made in Electron 4.0.
\napp.makeSingleInstance// Deprecated\napp.makeSingleInstance((argv, cwd) => {\n /* ... */\n})\n// Replace with\napp.requestSingleInstanceLock()\napp.on('second-instance', (event, argv, cwd) => {\n /* ... */\n})\napp.releaseSingleInstance// Déprécié\napp.releaseSingleInstance()\n// Remplacé par\napp.releaseSingleInstanceLock()\napp.getGPUInfoapp.getGPUInfo('complete')\n// Now behaves the same with `basic` on macOS\napp.getGPUInfo('basic')\nwin_delay_load_hookQuand vous compilez des modules natifs sous Windows, la variable win_delay_load_hook dans le fichier binding.gyp doit être mise à vrai (qui l'est par défaut). Si cet accroche n'est pas présente, l'exécution du module natif échouera sur Windows, avec un message d'erreur comme Cannot find module. Voir le Guide des modules natifs pour plus d'informations.
La liste suivante inclut les changements majeurs pour Electron 3.0.
\napp// Deprecated\napp.getAppMemoryInfo()\n// Replace with\napp.getAppMetrics()\n\n// Deprecated\nconst metrics = app.getAppMetrics()\nconst { memory } = metrics[0] // Deprecated property\nBrowserWindow// Déprécié\nconst optionsA = { webPreferences: { blinkFeatures: '' } }\nconst windowA = new BrowserWindow(optionsA)\n// Remplacer par\nconst optionsB = { webPreferences: { enableBlinkFeatures: '' } }\nconst windowB = new BrowserWindow(optionsB)\n\n// Déprécié\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play_pause') {\n // fait quelque chose\n }\n})\n// Remplacer par\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play-pause') {\n // fait quelque chose\n }\n})\nclipboard// Déprécié\nclipboard.readRtf()\n// Remplacé par\nclipboard.readRTF()\n\n// Déprécié\nclipboard.writeRtf()\n// Remplacé par\nclipboard.writeRTF()\n\n// Déprécié\nclipboard.readHtml()\n// Remplacé par\nclipboard.readHTML()\n\n// Déprécié\nclipboard.writeHtml()\n// Remplacé par\nclipboard.writeHTML()\ncrashReporter// Déprécié\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n autoSubmit: true\n})\n// Remplacé par\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n uploadToServer: true\n})\nnativeImage// Déprécié\nnativeImage.createFromBuffer(buffer, 1.0)\n// Remplacé par\nnativeImage.createFromBuffer(buffer, {\n scaleFactor: 1.0\n})\nprocessus (process)// Déprécié\nconst info = process.getProcessMemoryInfo()\nscreen// Déprécié\nscreen.getMenuBarHeight()\n// Remplacé par\nscreen.getPrimaryDisplay().workArea\nsession// Deprecated\nses.setCertificateVerifyProc((hostname, certificate, callback) => {\n callback(true)\n})\n// Replace with\nses.setCertificateVerifyProc((request, callback) => {\n callback(0)\n})\nTray// Déprécié\ntray.setHighlightMode(true)\n// Remplacé par\ntray.setHighlightMode('on')\n\n// Déprécié\ntray.setHighlightMode(false)\n// Remplacé par\ntray.setHighlightMode('off')\nwebContents// Déprécié\nwebContents.openDevTools({ detach: true })\n// Remplacé par\nwebContents.openDevTools({ mode: 'detach' })\n\n// Supprimé\nwebContents.setSize(options)\n// Il n'y a pas de remplacement prévu\nwebFrame// Deprecated\nwebFrame.registerURLSchemeAsSecure('app')\n// Replace with\nprotocol.registerStandardSchemes(['app'], { secure: true })\n\n// Deprecated\nwebFrame.registerURLSchemeAsPrivileged('app', { secure: true })\n// Replace with\nprotocol.registerStandardSchemes(['app'], { secure: true })\n<webview>// Supprimé\nwebview.setAttribute('disableguestresize', '')\n// There is no replacement for this API\n\n// Supprimé\nwebview.setAttribute('guestinstance', instanceId)\n// There is no replacement for this API\n\n// Les écouteurs d'événements ne marchent plus sur les tags webview\nwebview.onkeydown = () => { /* handler */ }\nwebview.onkeyup = () => { /* handler */ }\nIl s’agit de l’URL spécifiée comme disturl dans un fichier .npmrc ou le flag --dist-url en ligne de commande lors de la compilation des modules natifs de Node.
Déprécié : https://atom.io/download/atom-shell
\nRemplacé par : https://atom.io/download/electron
\nLa liste suivant inclut les changements majeurs faits dans Electron 2.0.
\nBrowserWindow// Déprécié\nconst optionsA = { titleBarStyle: 'hidden-inset' }\nconst windowA = new BrowserWindow(optionsA)\n// Remplacer par\nconst optionsB = { titleBarStyle: 'hiddenInset' }\nconst windowB = new BrowserWindow(optionsB)\nmenu// Supprimé\nmenu.popup(browserWindow, 100, 200, 2)\n// Remplacé par\nmenu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })\nnativeImage// Supprimé\nnativeImage.toPng()\n// Remplacé par\nnativeImage.toPNG()\n\n// Supprimé\nnativeImage.toJpeg()\n// Remplacé par\nnativeImage.toJPEG()\nprocessus (process)process.versions.electron et process.version.chrome seront mis en lecture seule par souci de cohérence avec la propriété process.versions définie par Node.webContents// Supprimé\nwebContents.setZoomLevelLimits(1, 2)\n// Remplacé par\nwebContents.setVisualZoomLevelLimits(1, 2)\nwebFrame// Supprimé\nwebFrame.setZoomLevelLimits(1, 2)\n// Remplacé par\nwebFrame.setVisualZoomLevelLimits(1, 2)\n<webview>// Supprimé\nwebview.setZoomLevelLimits(1, 2)\n// Remplacé par\nwebview.setVisualZoomLevelLimits(1, 2)\nChaque version d'Electron contient deux versions ARM identiques avec des noms légèrement différents, comme electron-v1.7.3-linux-arm.zip et electron-v1.7.3-linux-armv7l.zip. Celui avec le préfixe v7l a été ajouté pour clarifier aux utilisateurs quelle version ARM elle supporte, et supprimer les ambiguïtés des prochains paquets armv6l et arm64 qui pourraient être produites.
The file without the prefix is still being published to avoid breaking any setups that may be consuming it. À partir de la 2.0, le fichier sans préfixe ne sera plus publié.
\nPour plus de détails, voir 6986 et 7189.
", "title": "Changements de rupture", "description": "" }, "/docs/api/browser-view": { "locale": "fr-FR", "slug": "browser-view", "href": "/docs/api/browser-view", "crowdinFileId": "256283", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-view.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Un BrowserView peut être utilisé pour intégrer des contenus web supplémentaires dans un BrowserWindow. C'est comme une fenêtre enfant, sauf qu'il est positionné par rapport à sa fenêtre propriétaire. Il se veut être une alternative à la balise webview.
\n\nCréer et contrôle les fenêtres.
\n
Processus : Main
\n// Dans le processus main.\nconst { BrowserView, BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nconst view = new BrowserView()\nwin.setBrowserView(view)\nview.setBounds({ x: 0, y: 0, width: 300, height: 300 })\nview.webContents.loadURL('https://electronjs.org')\nnew BrowserView([options]) Experimentaloptions Object (facultatif)webPreferences Object (facultatif) - Voir BrowserWindow.Les objets créés avec new BrowserView ont les propriétés suivantes :
view.webContents ExperimentalUn objet WebContents appartient à cette vue.
Les objets créés avec new BrowserView ont les méthodes d’instance suivant :
view.setAutoResize(options) Experimentaloptionswidth Boolean (optional) - If true, the view's width will grow and shrink together with the window. false by default.height Boolean (optional) - If true, the view's height will grow and shrink together with the window. false by default.horizontal Boolean (optional) - If true, the view's x position and width will grow and shrink proportionally with the window. false by default.vertical Boolean (optional) - If true, the view's y position and height will grow and shrink proportionally with the window. false by default.view.setBounds(bounds) Experimentalbounds RectangleRedimensionne et déplace la vue vers les limites fournies par rapport à la fenêtre.
\nview.getBounds() ExpérimentalRetourne Rectangle
Les limites de cette instance BrowserView comme Object.
view.setBackgroundColor(color) Experimentalcolor String - Color in #aarrggbb or #argb form. The alpha channel is optional.\n\nCréer et gérer des fenêtres navigateur.
\n
Processus : Main
\n// Dans le processus main.\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\n// Load a remote URL\nwin.loadURL('https://github.com')\n\n// Or load a local HTML file\nwin.loadFile('index.html')\nPour créer une fenêtre sans chrome, ou une fenêtre transparente de forme arbitraire, vous pouvez utiliser l'API Frameless Window.
\nWhen loading a page in the window directly, users may see the page load incrementally, which is not a good experience for a native app. To make the window display without a visual flash, there are two solutions for different situations.
\nready-to-show eventPendant le chargement de la page, l'événement ready-to-show sera émis lorsque le process de rendu aura rendu la page pour la première fois si la fenêtre n'a pas encore été rendue. Afficher la page une fois que l'event a été trigger rendra la page sans ce processus de chargement au fur et à mesure:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ show: false })\nwin.once('ready-to-show', () => {\n win.show()\n})\nCet événement est généralement émis après l’événement did-finish-load, mais pour les pages avec beaucoup de ressources distantes, il peut être émis avant l’événement did-finish-load.
Veuillez noter que l'utilisation de cet événement implique que le moteur de rendu sera considéré comme \"visible\" et peinture, même si show est faux. Cet événement ne se déclenchera jamais si vous utilisez paintWhenInitiallyHidden: false
backgroundColor propertyPour une application complexe, l’événement ready-to-show pourrait être émis trop tard, donnant une impression de lenteur. Dans ce cas, il est recommandé d'afficher la fenêtre immédiatement et d'utiliser un backgroundColor proche de la couleur de fond de votre application :
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ backgroundColor: '#2e2c29' })\nwin.loadURL('https://github.com')\nNotez que même pour les applications qui utilisent l'évènement ready-to-show, il est toujours recommandé de définir backgroundColor pour avoir un rendu plus naturel.
En utilisant l'option parent, vous pouvez créer une fenêtre enfant:
const { BrowserWindow } = require('electron')\n\nconst top = new BrowserWindow()\nconst child = new BrowserWindow({ parent: top })\nchild.show()\ntop.show()\nLa fenêtre child sera toujours au dessus de la fenêtre top.
Une fenêtre modale est une fenêtre enfant qui désactive la fenêtre parent. Pour créer une fenêtre modale, il faut définir les options parent et modal :
const { BrowserWindow } = require('electron')\n\nconst child = new BrowserWindow({ parent: top, modal: true, show: false })\nchild.loadURL('https://github.com')\nchild.once('ready-to-show', () => {\n child.show()\n})\nL'API de visibilité de la page fonctionne comme ci-dessous :
\nhidden. Sur les autres plateformes, l'état de visibilité sera hidden seulement lorsque la fenêtre est minimisée ou cachée explicitement avec win.hide().BrowserWindow est crée avec show:false, l'état de visibilité initial sera visible même si la fenêtre est cachée.backgroundThrottling est désactivé, l'état de visibilité restera visible même si la fenêtre est minimisée, obstruée ou cachée.Il est recommandé de mettre en pause les opérations coûteuse lorsque l'état de visibilité est hidden afin de minimiser la consommation d'énergie.
dialog.\n\nCréer et gérer des fenêtres navigateur.
\n
Processus : Main
\nBrowserWindow est un EventEmitter.
Cela crée une nouvelle BrowserWindow avec les propriétés natives définies par les options.
new BrowserWindow([options])options Object (facultatif)width Entier (facultatif) - Largeur de la fenêtre en pixels. Le Defaut est800.height Entier (facultatif) - Hauteur de la fenêtre en pixels. Defaut es 600.x Entier (optionel) - (obligatoire si y n'est pas utilise) Le décalage de la fenêtre a été effacé de l'écran. Le defaut est de centrer la fenetre.y Entier (optionel) - (obligatoire si x est utilisé) Le décalage de la partie supérieure de la fenêtre a été efface de l'écran. Le defaut est de centrer la fenetre.useContentSize Boolean (facultatif) - La largeur et la hauteur (width et height) seront utilisées pour définir la taille de la page Web, ce qui signifie que la taille de la fenêtre réelle inclura la taille du cadre de celle-ci. La fenêtre complète sera donc légèrement plus grande que la taille de son contenu. Par défaut la valeur est false.center Boolean (facultatif) - afficher la fenêtre dans le centre de l’écran.LargeurminIntegre (optionel)-La largeur minimum de la Fenetre. La valeur par defaut en est ``.minHeight Integer (facultatif) - Hauteur minimale de la fenêtre en pixels. La valeur par defaut en est ``.maxWidth Integer (optional) - Window's maximum width. Default is no limit.maxHeight Integer (optional) - Window's maximum height. Default is no limit.resizable Boolean (optional) - Whether window is resizable. La valeur par défaut est vraie.movable Boolean (optional) - Whether window is movable. Ceci n'est pas implémenté sur Linux. La valeur par défaut est vraie.minimizable Boolean (optional) - Whether window is minimizable. Ceci n'est pas implémenté sous Linux. La valeur par défaut est vraie.maximizable Boolean (optional) - Whether window is maximizable. Ceci n'est pas implémenté sous Linux. La valeur par défaut est vraie.closable Boolean (optional) - Whether window is closable. Ceci n'est pas implémenté sur Linux. La valeur par défaut est vraie.focusable Boolean (facultatif) - Si la fenêtre peut avoir le focus. La valeur par défaut est true. Sur Windows, mettre focusable: false implique également le réglage skipTaskbar: true. Sur Linux, mettre focusable: false fait que la fenêtre arrête d'interragir avec wm, par conséquent la fenêtre restera toujours au dessus dans tous les espaces de travail.alwaysOnTop Boolean (optional) - Whether the window should always stay on top of other windows. Par défaut la valeur est false.fullscreen Boolean (facultatif) - Est-ce que la fenêtre doit s'afficher en plein écran. Quand explicitement mit a false, le bouton plein écran sera caché ou désactivé sur macOS. Par défaut la valeur est false.fullscreenable Boolean (facultatif) - Est-ce que la fenêtre peut s'afficher en plein écran. Sur macOS, indiquez également si le bouton de maximizer/zoom doit basculer en mode plein écran ou agrandir la fenêtre. La valeur par défaut est vraie.simpleFullscreen Boolean (optional) - Use pre-Lion fullscreen on macOS. Par défaut la valeur est false.skipTaskbar Boolean (optional) - Whether to show the window in taskbar. La valeur par défaut est false.kiosk Boolean (optional) - Whether the window is in kiosk mode. Par défaut la valeur est false.titre String (facultatif) - Titre par défaut de la fenêtre. La valeur par défaut est \"Electron\". Si la balise HTML <title> est définie dans le fichier HTML chargé par loadURL(), cette propriété sera ignorée.icon (NativeImage | String) (facultatif) - L'icône de la fenêtre. Sur Windows, il est recommandé d'utiliser le format ICO pour un rendu optimal. Si non défini, l'icone de l’exécutable sera utilisé.show Boolean (optional) - Whether window should be shown when created. La valeur par défaut est true.paintWhenInitiallyHidden Boolean (facultatif) - Si le moteur de rendu doit être actif lorsque show est false et qu'il vient d'être créé. Afin que document.visibilityState fonctionne correctement lors du premier chargement avec show: false vous devez définir ceci à false. Mettre ceci à false fera que l'événement prêt-à-montrer ne sera pas déclenché. La valeur par défaut est vraie.frame Boolean (optional) - Specify false to create a Frameless Window. La valeur par défaut est vraie.parent BrowserWindow (optional) - Specify parent window. Par défaut la valeur est null.modal Boolean (optional) - Whether this is a modal window. This only works when the window is a child window. Par défaut la valeur est false.acceptFirstMouse Boolean (facultatif) - Un click sur une fenêtre inactive passera à travers jusqu'au contenu Web. La valeur par défaut est false sur macOS. Cette option n'est pas configurable sur les autres plateformes.disableAutoHideCursor Boolean (optional) - Whether to hide cursor when typing. Par défaut la valeur est false.autoHideMenuBar Boolean (optional) - Auto hide the menu bar unless the Alt key is pressed. Par défaut la valeur est false.enableLargerThanScreen Booléen (facultatif) - Permet à la fenêtre d'être redimensionnée plus grande que l'écran. Seulement pertinent pour macOS, car les autres systèmes d'exploitation autorisent par défaut des fenêtres plus grandes qu'écran par défaut. Par défaut la valeur est false.BackgroundColor String (facultatif) - Couleur d'arrière-plan de la fenêtre en valeur hexadécimale, comme #66CD00 ou #FFF ou #80FFFFFF (alpha au format #AARRGGBB est supporté si transparent est défini à true). La valeur par défaut est #FFF (white).hasShadow Boolean (optional) - Whether window should have a shadow. La valeur par défaut est vraie.opacity Number (optional) - Set the initial opacity of the window, between 0.0 (fully transparent) and 1.0 (fully opaque). Ceci n'est implémenté que sur Windows et macOS.darkTheme Boolean (optionnel) - Force l'utilisation du thème sombre pour la fenêtre, fonctionne uniquement sur certains environnements de bureau GTK+3. Par défaut la valeur est false.transparent Boolean (facultatif) - Rend la fenêtre transparente. Par défaut la valeur est false. Sous Windows, ne fonctionne pas à moins que la fenêtre ne soit sans cadres.type String (optional) - The type of window, default is normal window. See more about this below.visualEffectState String (optional) - Specify how the material appearance should reflect window activity state on macOS. Must be used with the vibrancy property. Les valeurs possibles sont :followWindow - The backdrop should automatically appear active when the window is active, and inactive when it is not. This is the default.active - The backdrop should always appear active.inactive - The backdrop should always appear inactive.titleBarStyle String (optional) macOS Windows - The style of window title bar. Par défaut la valeur est default. Les valeurs possibles sont :default - Results in the standard title bar for macOS or Windows respectively.hidden - Results in a hidden title bar and a full size content window. On macOS, the window still has the standard window controls (“traffic lights”) in the top left. On Windows, when combined with titleBarOverlay: true it will activate the Window Controls Overlay (see titleBarOverlay for more information), otherwise no window controls will be shown.hiddenInset - Only on macOS, results in a hidden title bar with an alternative look where the traffic light buttons are slightly more inset from the window edge.customButtonsOnHover - Only on macOS, results in a hidden title bar and a full size content window, the traffic light buttons will display when being hovered over in the top left of the window. Note: Cette option est actuellement expérimentale.trafficLightPosition Point (optional) - Set a custom position for the traffic light buttons in frameless windows.roundedCorners Boolean (optional) - Whether frameless window should have rounded corners on macOS. La valeur par défaut est vraie.fullscreenWindowTitle Boolean (optional) Deprecated - Shows the title in the title bar in full screen mode on macOS for hiddenInset titleBarStyle. Par défaut la valeur est false.thickFrame Boolean (facultatif) - Utilisez le style WS_THICKFRAME pour les fenêtres sans cadre sur Windows, qui ajoute une image standard de fenêtre. Le définir à false supprimera les animations de fenêtre et de fenêtre. La valeur par défaut est vraie.vibrancy String (facultatif) - Ajoute un type d'effet de vibrance à la fenêtre, uniquement sur macOS. Peut être appearance-based, light, dark, titlebar, selection, menu, popover, , <code>sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, outil>, <code>content<code>, <0>sous-window. Please note that appearance-based, light, dark, medium-light, and ultra-dark are deprecated and have been removed in macOS Catalina (10.15).zoomToPageWidth Boolean (optional) - Controls the behavior on macOS when option-clicking the green stoplight button on the toolbar or by clicking the Window > Zoom menu item. Si true, la fenêtre grandira à la largeur préférée de la page web lors du zoom, false le fera zoomer sur la largeur de l'écran. Cela affectera également le comportement lorsque vous appelez maximize() directement. Par défaut la valeur est false.tabbingIdentifier String (facultatif) - Nom du groupe d'onglets, permet d'ouvrir la fenêtre sous la forme d'un onglet natif sur macOS 10.12+. Les fenêtres avec le même identifiant de tabulation seront regroupées. Cela ajoute également un nouveau bouton d'onglet natif à la barre d'onglets de votre fenêtre et permet à votre app et fenêtre de recevoir l'événement new-window-for-tab.webPreferences Object (optional) - Settings of web page's features.devTools Boolean (facultatif) - Activer ou non DevTools. Si elle est définie à false, ne peut pas utiliser BrowserWindow.webContents.openDevTools() pour ouvrir DevTools. La valeur par défaut est vraie.nodeIntegration Boolean (optional) - Whether node integration is enabled. Par défaut la valeur est false.nodeIntegrationInWorker Boolean (facultatif) - Si l'intégration de nœuds est activée dans les workflows web. Par défaut la valeur est false. Plus d'informations peuvent être trouvée dans Multithreading.nodeIntegrationInSubFrames Boolean (facultatif) - Option expérimentale pour activer le support de Node.js dans les sous-cadres tels que les iframes et les fenêtres enfants. Tous vos préchargements seront chargés pour chaque iframe, vous pouvez utiliser process.isMainFrame pour déterminer si vous êtes dans le cadre principal ou non.preload String (facultatif) - Spécifie un script qui sera chargé avant les autres scripts exécutés dans la page. Ce script aura toujours accès aux API de noeuds peu importe que l'intégration de noeuds soit activée ou désactivée. La valeur doit être le chemin absolu vers le script. Lorsque l'intégration des nœuds est désactivée, le script de préchargement peut réintroduire les symboles globaux de nœud dans la portée globale. Voir l'exemple ici.sandbox Booléen (facultatif) - Si défini, le moteur de rendu associé à la fenêtre, la rendre compatible avec le bac à sable Chromium au niveau du système d'exploitation et la désactivation du nœud. s moteur. Ce n'est pas la même chose que l'option nodeIntegration et les API disponibles pour le script de préchargement sont plus limitées. En savoir plus sur l'option ici.session Session (facultatif) - Définit la session utilisée par la page . Au lieu de passer l'objet Session directement, vous pouvez également choisir d'utiliser l'option partition à la place, qui accepte une chaîne de partition. Lorsque session et partition sont fournies, session sera préférée. La session par défaut est celle par défaut.partition String (facultatif) - Définit la session utilisée par la page en fonction de la chaîne de partition de la session . Si partition commence par persist:, la page utilisera une session persistante disponible pour toutes les pages de l'application avec le même partition. S'il n'y a pas de préfixe persistant:, la page utilisera une session en mémoire . En assignant la même partition, plusieurs pages peuvent partager la même session. La session par défaut est celle par défaut.zoomFactor Number (optional) - The default zoom factor of the page, 3.0 represents 300%. Par défaut la valeur est 1.0.javascript Boolean (optional) - Enables JavaScript support. La valeur par défaut est vraie.webSecurity Boolean (facultatif) - Lorsque false, il désactivera la politique de même origine (généralement en utilisant des sites de test par des personnes), et définissez allowRunningInsecureContent à true si cette option n'a pas été définie par l'utilisateur. La valeur par défaut est vraie.allowRunningInsecureContent Boolean (optional) - Allow an https page to run JavaScript, CSS or plugins from http URLs. Par défaut la valeur est false.images Boolean (optional) - Enables image support. La valeur par défaut est vraie.imageAnimationPolicy String (optional) - Specifies how to run image animations (E.g. GIFs). Can be animate, animateOnce or noAnimation. La valeur par défaut est animate.textAreasAreResizable Boolean (optional) - Make TextArea elements resizable. Default is true.webgl Boolean (optional) - Enables WebGL support. La valeur par défaut est vraie.plugins Boolean (optional) - Whether plugins should be enabled. Par défaut la valeur est false.experimentalFeatures Boolean (optional) - Enables Chromium's experimental features. Par défaut la valeur est false.scrollBounce Boolean (optional) - Enables scroll bounce (rubber banding) effect on macOS. Par défaut la valeur est false.enableBlinkFeatures String (facultatif) - Une liste de chaînes de caractères séparées par ,, comme CSSVariables,KeyEventKey pour activer. La liste complète des chaînes de caractères supportées peut être trouvée dans le fichier RuntimeEnabledFeatures.json5 .disableBlinkFeatures String (facultatif) - Une liste de chaînes de caractères séparées par ,, comme CSSVariables,KeyEventKey pour désactiver. La liste complète des chaînes de fonctionnalités supportées peut être trouvée dans le fichier RuntimeEnabledFeatures.json5 .defaultFontFamily Object (optional) - Sets the default font for the font-family.standard String (facultatif) - Par défaut Times New Roman.serif String (facultatif) - Par défaut Times New Roman.sansSerif String (facultatif) - Arial.monospace String (facultatif) - Courrier New.cursive String (facultatif) - Script.fantasy String (facultatif) - Impact.defaultFontSize Integer (facultatif) - 16.defaultMonospaceFontSize Integer (facultatif) - 13.minimumFontSize Integer (facultatif) - 0.defaultEncoding String (facultatif) - ISO-8859-1.backgroundThrottling Boolean (facultatif) - Si vous voulez maîtriser les animations et les minuteurs lorsque la page devient en arrière-plan. Cela affecte également l'API Visibilité de la page. Par défaut, true.Offscreen Boolean (facultatif) - Activer le rendu hors écran pour la fenêtre du navigateur. Par défaut, faux. Voir le tutoriel de rendu hors écran pour plus de détails.contextIsolation Boolean (facultatif) - Exécuter les API Electron et le script preload spécifié dans un contexte JavaScript séparé. Est à true par défaut. Le contexte dans lequel le script preload s’exécute n’aura accès qu'à ses propres document , globales de window et ensemble de types JavaScript intégrés (Array, Object, JSON, etc.), qui seront tous invisibles pour le contenu chargé. L'API Electron ne sera disponible que dans le script de préchargement de `et pas dans la page chargée. Cette option doit être utilisée lors du chargement de contenu distant potentiellement non fiable afin de se prémunit de toute utilisation frauduleuse du scriptpreload` ou des APIs Electron. Cette option utilise la même technique que celle utilisée par les Chrome Content Scripts. Vous pouvez accéder à ce contexte dans les outils de développement en sélectionnant l'entrée 'Electron Isolated Context' de la liste déroulante en haut de l'onglet Console.nativeWindowOpen Boolean (facultatif) - Utiliser natif window.open(). Par défaut, true. Les fenêtres enfants auront toujours l'intégration du nœud désactivée sauf si nodeIntegrationInSubFrames est vrai.webviewTag Boolean (facultatif) - Activer la balise < webview>. Par défaut, faux. Remarque : Le script preload configuré pour le < webview> aura une intégration de nœuds activée lorsqu'il est exécuté, donc vous devez vous assurer que le contenu distant/non fiable n'est pas en mesure de créer une balise <webview> avec un préchargement de potentiellement malveillant script. Vous pouvez utiliser l'événement will-attach-webview sur webContents pour supprimer le script preload et valider ou modifier les paramètres initiaux de < webview>.additionalArguments String - Liste de chaînes qui seront ajoutées au process.argv dans le processus de rendu de cette application. Utile afin de transmettre de petites informations aux scripts de préchargement du processus de rendu.safeDialogs Boolean (facultatif) - Indique s’il faut activer la protection pour les boîtes de dialogue consécutives à la mode \"navigateur\". Par défaut la valeur est false.safeDialogsMessage String (facultatif) - Le message à afficher lorsque la protection consécutive des dialogues est déclenchée. Si non défini, le message par défaut serait utilisé, notez que le message par défaut est actuellement en anglais et non localisé.disableDialogs Boolean (optional) - Whether to disable dialogs completely. Overrides safeDialogs. Par défaut la valeur est false.navigateOnDragDrop Boolean (optional) - Whether dragging and dropping a file or link onto the page causes a navigation. Par défaut la valeur est false.autoplayPolicy String (facultatif) - La politique de lecture automatique à appliquer au contenu dans la fenêtre, peut être no-user-gesture-required, user-gesture-required, document-user-activation-required. Par défaut, no-user-gesture-required.disableHtmlFullscreenWindowResize Boolean (optional) - Whether to prevent the window from resizing when entering HTML Fullscreen. Default is false.accessibleTitle String (optional) - An alternative title string provided only to accessibility tools such as screen readers. This string is not directly visible to users.spellcheck Boolean (optional) - Whether to enable the builtin spellchecker. La valeur par défaut est vraie.enableWebSQL Boolean (optional) - Whether to enable the WebSQL api. La valeur par défaut est vraie.v8CacheOptions String (optional) - Enforces the v8 code caching policy used by blink. Les valeurs acceptées sontnone - Disables code cachingcode - Heuristic based code cachingbypassHeatCheck - Bypass code caching heuristics but with lazy compilationbypassHeatCheckAndEagerCompile - Same as above except compilation is eager. Default policy is code.enablePreferredSizeMode Boolean (optional) - Whether to enable preferred size mode. The preferred size is the minimum size needed to contain the layout of the document—without requiring scrolling. Enabling this will cause the preferred-size-changed event to be emitted on the WebContents when the preferred size changes. Par défaut la valeur est false.titleBarOverlay Object | Boolean (optional) - When using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS or using a titleBarStyle so that the standard window controls (\"traffic lights\" on macOS) are visible, this property enables the Window Controls Overlay JavaScript APIs and CSS Environment Variables. Specifying true will result in an overlay with default system colors. Par défaut la valeur est false.color String (optional) Windows - The CSS color of the Window Controls Overlay when enabled. Default is the system color.symbolColor String (optional) Windows - The CSS color of the symbols on the Window Controls Overlay when enabled. Default is the system color.Lorsque l'on définie une taille minimum ou maximum pour la fenêtre avec minWidth/maxWidth/ minHeight/maxHeight, cela contraint les utilisateurs uniquement. Cela ne vous empêche pas de passer une taille qui ne suit pas les contraintes de tailles à setBounds/setSize ou au constructeur de BrowserWindow.
The possible values and behaviors of the type option are platform dependent. Les valeurs possibles sont :
desktop, dock, toolbar, splash, notification.desktop, textured.textured ajoute un aspect métal dégradé (NSTexturedBackgroundWindowMask).desktop place les fenêtre au niveau de l'arière plan. (kCGDesktopWindowLevel - 1). Remarque, la fenêtre du Bureau ne recevra pas le focus ni les évennements souris ou clavier, mais il est possible d'utiliser globalShortcut pour recevoir des entrées avec modération.toolbar.Les objets crées avec new BrowserWindow émettent les évennements suivants :
Remarque : Certains événements sont seulement disponibles sur des systèmes d'exploitation spécifiques et sont étiquetés comme tels.
\nRetourne :
\nevent Eventtitle StringexplicitSet BooleanÉmis lorsque le document a changé son titre, appeler event.preventDefault() empêchera le titre de la fenêtre native de changer. explicitSet est faux lorsque le titre est synthétisé à partir de l'URL du fichier.
Retourne :
\nevent EventEmis lorsque la fenêtre va être fermée. Émis avant les événements beforeunload et unload du DOM. Appeler event.preventDefault() annulera la fermeture.
Normalement, vous voudriez utiliser le gestionnaire beforeunload pour décider si une fenêtre doit être fermée, ce qui sera aussi appelé lorsque la fenêtre est rechargée. Dans Electron, n'importe quelle valeur retournée autre que undefined annulera la fermeture. Par exemple :
window.onbeforeunload = (e) => { console.log('I do not want to be closed') \n\n// A la différence des navigateurs web, un message sera affiché aux utilisateurs, retourner\n// une valeur non-nulle annulera la fermeture.\n // Il est recommandé d'utiliser l'API de dialogue afin de laisser l'utilisateur confirmer la fermeture de\n// l'application.\n e.returnValue = false // Equivaut à un `return false` mais ce n'est pas recommandé\n}\nNote: Il y a une subtile différence entre le comportement de window.onbeforeunload = handler et window.addEventListener('beforeunload', handler). Il est recommendé de toujours spécifier l' event.returnValue explicitement, plutôt que de seulement retourner une valeur, cette méthode fonctionne mieux avec Electron.
Emitted when the window is closed. After you have received this event you should remove the reference to the window and avoid using it any more.
\nÉmis lorsque la session va se terminer à cause d'une redémarage, un éteignage forcé ou une déconnexion.
\nÉmis lorsque la page web cesse de répondre.
\nÉmis lorsque la page web répond à nouveau.
\nÉmis lorsque la fenêtre perd le focus.
\nÉmis lorsque la fenêtre obtient le focus.
\nÉmis lorsque la fenêtre est affichée.
\nÉmis lorsque la fenêtre est masquée.
\nÉmis lorsque la page web à été chargée (tout en n'était pas affichée) et la fenêtre peut être affichée sans flash visuel.
\nVeuillez noter que l'utilisation de cet événement implique que le moteur de rendu sera considéré comme \"visible\" et peinture, même si show est faux. Cet événement ne se déclenchera jamais si vous utilisez paintWhenInitiallyHidden: false
Émis lorsque la fenêtre est agrandie.
\nÉmis lorsque la fenêtre quitte un état maximisé.
\nÉmis lorsque la fenêtre est réduite.
\nÉmis lorsque la fenêtre est restaurée à partir d’un état réduit.
\nRetourne :
\nevent EventnewBounds Rectangle - Taille de la fenêtre en cours de redimensionnage.detailsedge (String) - The edge of the window being dragged for resizing. Can be bottom, left, right, top-left, top-right, bottom-left or bottom-right.Emitted before the window is resized. Calling event.preventDefault() will prevent the window from being resized.
Note that this is only emitted when the window is being resized manually. Resizing the window with setBounds/setSize will not emit this event.
The possible values and behaviors of the edge option are platform dependent. Les valeurs possibles sont :
bottom, top, left, right, top-left, top-right, bottom-left, bottom-right.bottom and right.bottom is used to denote vertical resizing.right is used to denote horizontal resizing.Émis après que la fenêtre soit redimensionnée.
\nEmitted once when the window has finished being resized.
\nThis 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.
Retourne :
\nevent EventnewBounds Rectangle - Emplacement où la fenêtre est en cours de déplacement.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 resized manually. Resizing the window with setBounds/setSize will not emit this event.
Émis lorsque la fenêtre est déplacée vers une nouvelle position.
\nÉmis une fois lorsque la fenêtre est déplacée vers une nouvelle position.
\nNote : Sous macOS, cet événement est un alias de move.
Émis lorsque la fenêtre passe à un état de plein écran.
\nÉmis lorsque la fenêtre revient d'un état de plein écran.
\nÉmis lorsque la fenêtre entre dans un état de plein écran déclenchée par l’API HTML.
\nÉmis lorsque la fenêtre revient d'un état de plein écran déclenchée par l’API HTML.
\nRetourne :
\nevent EventisAlwaysOnTop BooleanÉmis lorsque la fenêtre est définie ou non définie pour toujours afficher au dessus des autres fenêtres.
\nRetourne :
\nevent Eventcommand StringÉmis lorsqu'une App Command est appelée. Elles sont généralement liées aux touches multimédia du clavier ou aux commandes du navigateur, ainsi que le bouton \"Retour\" intégré à certaines souris sous Windows.
\nLes commandes sont en minuscules, les traits de soulignement sont remplacés par des traits d'union, et le préfixe APPCOMMAND_ est supprimé. par exemple APPCOMMAND_BROWSER_BACKWARD est émise en tant que browser-backward.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.on('app-command', (e, cmd) => {\n // Navigate the window back when the user hits their mouse back button\n if (cmd === 'browser-backward' && win.webContents.canGoBack()) {\n win.webContents.goBack()\n }\n})\nLes commandes d'application suivantes sont explicitement prises en charge sur Linux :
\nretour en arrière du navigateurnavigateur-transfertÉmis lorsque l’événement scroll de la souris a commencé.
\nÉmis lorsque l’événement scroll de la souris est terminée.
\nÉmis lorsque l’événement scroll de la souris arrive au bord d'un élément.
\nRetourne :
\nevent Eventdirection StringEmitted on 3-finger swipe. Possible directions are up, right, down, left.
The method underlying this event is built to handle older macOS-style trackpad swiping, where the content on the screen doesn't move with the swipe. Most macOS trackpads are not configured to allow this kind of swiping anymore, so in order for it to emit properly the 'Swipe between pages' preference in System Preferences > Trackpad > More Gestures must be set to 'Swipe with two or three fingers'.
Retourne :
\nevent Eventrotation FloatÉmis lors du mouvement de rotation du trackpad. Émission continue jusqu'à la fin du geste de rotation. La valeur rotation sur chaque émission est l'angle en degrés tourné depuis la dernière émission. Le dernier événement émis lors d'un geste de rotation sera toujours de la valeur 0. Les valeurs de rotation dans le sens inverse des aiguilles d'une montre sont positives, tandis que les valeurs dans le sens horaire sont négatives.
Émis lorsque la fenêtre ouvre une feuille.
\nÉmis lorsque la fenêtre a fermé une feuille.
\nÉmis lorsque le bouton natif du nouvel onglet est cliqué.
\nRetourne :
\nevent Eventpoint Point - The screen coordinates the context menu was triggered atEmitted when the system context menu is triggered on the window, this is normally only triggered when the user right clicks on the non-client area of your window. This is the window titlebar or any area you have declared as -webkit-app-region: drag in a frameless window.
Calling event.preventDefault() will prevent the menu from being displayed.
La classe BrowserWindow a les méthodes statiques suivantes :
BrowserWindow.getAllWindows()Retourne BrowserWindow[] - Un tableau de toutes les fenêtres ouvertes.
BrowserWindow.getFocusedWindow()Retourne BrowserWindow | null - La fenêtre qui est concentrée dans cette application, sinon retourne null.
BrowserWindow.fromWebContents(webContents)webContents WebContentsReturns BrowserWindow | null - The window that owns the given webContents or null if the contents are not owned by a window.
BrowserWindow.fromBrowserView(browserView)browserView BrowserViewRetourne BrowserWindow | null - La fenêtre qui possède le browserView. If the given view is not attached to any window, returns null.
BrowserWindow.fromId(id)id IntegerRetourne BrowserWindow | null - La fenêtre avec l'id donné.
Les objets créés avec nouveau BrowserWindow ont les propriétés suivantes :
const { BrowserWindow } = require('electron')\n// In this example `win` is our instance\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('https://github.com')\nwin.webContents ReadonlyA WebContents object this window owns. All web page related events and operations will be done via it.
Voir la webContents documentation pour ses méthodes et ses événements.
win.id ReadonlyUne propriété Integer représentant l'ID unique de la fenêtre. Chaque ID est unique parmi ceux des instances de BrowserWindow de l'application Electron.
format@@0 win.autoHideMenuBarA Boolean property that determines whether the window menu bar should hide itself automatically. Once set, the menu bar will only show when users press the single Alt key.
Si la barre de menu est déjà visible, le réglage de cette propriété sur true ne le fera pas le cacher immédiatement.
win.simpleFullScreenA Boolean property that determines whether the window is in simple (pre-Lion) fullscreen mode.
win.fullScreenA Boolean property that determines whether the window is in fullscreen mode.
win.focusable Windows macOSA Boolean property that determines whether the window is focusable.
win.visibleOnAllWorkspacesA Boolean property that determines whether the window is visible on all workspaces.
Note: Always returns false on Windows.
\nwin.shadowA Boolean property that determines whether the window has a shadow.
win.menuBarVisible Windows LinuxA 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.kioskA Boolean property that determines whether the window is in kiosk mode.
win.documentEdited macOSA 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 macOSA 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.titleA 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.
\nwin.minimizableUne propriété Boolean qui détermine si la fenêtre peut être minimisée manuellement par l'utilisateur.
Sur Linux, le setter est un no-op, bien que le getter retourne true.
win.maximizableUne propriété Boolean qui détermine si la fenêtre peut être agrandie manuellement par l'utilisateur.
Sur Linux, le setter est un no-op, bien que le getter retourne true.
win.fullScreenableUne propriété Boolean qui détermine si le bouton maximiser/zoom de la fenêtre active le mode plein écran ou maximise la fenêtre.
win.resizableUne propriété Boolean qui détermine si la fenêtre peut être redimensionnée manuellement par l'utilisateur.
win.closableUne propriété Boolean qui détermine si la fenêtre peut être fermée manuellement par l'utilisateur.
Sur Linux, le setter est un no-op, bien que le getter retourne true.
win.movableUne propriété Boolean qui détermine si la fenêtre peut être déplacée par l'utilisateur.
Sur Linux, le setter est un no-op, bien que le getter retourne true.
win.excludedFromShownWindowsMenu macOSA Boolean property that determines whether the window is excluded from the application’s Windows menu. false par défaut.
const win = new BrowserWindow({ height: 600, width: 600 })\n\nconst template = [\n {\n role: 'windowmenu'\n }\n]\n\ngagne. xcludedFromShownWindowsMenu = true\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nwin.accessibleTitleA String property that defines an alternative title provided only to accessibility tools such as screen readers. This string is not directly visible to users.
Les objets créés avec nouveau BrowserWindow ont les méthodes d'instance suivantes :
Remarque : Certaines méthodes sont seulement disponibles sur des systèmes d'exploitation spécifiques et sont étiquetés comme tels.
\nwin.destroy()Forcer la fermeture de la fenêtre, les unload et beforeunload événement ne seront pas émises pour la page web, et l'évènement close ne sera pas non plus émise pour cette fenêtre, mais il garantit que l'événement closed sera émis.
win.close()Try to close the window. This has the same effect as a user manually clicking the close button of the window. The web page may cancel the close though. See the close event.
\nwin.focus()Ramène la fenêtre au premier plan.
\nwin.blur()Supprime le focus de la fenêtre.
\nwin.isFocused()Retourne Boolean - Si la fenêtre est mise au point.
win.isDestroyed()Retourne Boolean - Si la fenêtre est détruite.
win.show()Affiche la fenêtre et la ramène au premier plan.
\nwin.showInactive()Affiche la fenêtre, mais ne la ramène pas au premier plan.
\nwin.hide()Masque la fenêtre.
\nwin.isVisible()Retourne Boolean - Si la fenêtre est visible pour l'utilisateur ou non.
win.isModal()Retourne Boolean - Si la fenêtre actuelle est une fenêtre modale ou non.
win.maximize()Maximizes the window. This will also show (but not focus) the window if it isn't being displayed already.
\nwin.unmaximize()Réduit la fenêtre à sa taille initiale.
\nwin.isMaximized()Retourne Boolean - Si la taille de la fenêtre est maximisée ou non.
win.minimize()Minimizes the window. On some platforms the minimized window will be shown in the Dock.
\nwin.restore()Restaure la fenêtre depuis l'état réduit à son état précédent.
\nwin.isMinimized()Retourne Boolean - Si la taille de la fenêtre est minimisée ou non.
win.setFullScreen(flag)flag BooleanDéfinit si la fenêtre doit être en mode plein écran.
\nwin.isFullScreen()Retourne Boolean - Si la fenêtre est en plein écran ou non.
win.setSimpleFullScreen(flag) macOSflag BooleanEntre ou sort du mode plein-écran simple.
\nSimple fullscreen mode emulates the native fullscreen behavior found in versions of macOS prior to Lion (10.7).
\nwin.isSimpleFullScreen() macOSRetourne Boolean - Si la fenêtre est en mode plein-écran simple (pré-Lion) ou non.
win.isNormal()Retourne Boolean - Si la fenêtre est dans son état normal (ni maximisée, ni minimisée, ni en plein écran).
win.setAspectRatio(aspectRatio[, extraSize])aspectRatio Float - L'aspect ratio à maintenir pour une partie de la vue de contenu .extraSize Size (optional) macOS - The extra size not to be included while maintaining the aspect ratio.Cela fera que la fenêtre maintient un ratio d'aspect. La taille supplémentaire permet à un développeur d'avoir de l'espace, spécifié en pixels, non inclus dans les calculs de ratio de l'aspect. Cette API prend déjà en compte la différence entre la taille d'une fenêtre et sa taille de contenu.
\nConsidérez une fenêtre normale avec un lecteur vidéo HD et des commandes associées. Il y a peut-être 15 pixels de contrôles sur le bord gauche, 25 pixels de contrôles sur le bord droit et 50 pixels de contrôles sous le joueur. In order to maintain a 16:9 aspect ratio (standard aspect ratio for HD @1920x1080) within the player itself we would call this function with arguments of 16/9 and\n{ width: 40, height: 50 }. Le deuxième argument ne se soucie pas du fait que la largeur et la hauteur supplémentaires sont dans la vue de contenu --seulement qu'elles existent. Sommez toute la largeur supplémentaire et les zones de hauteur que vous avez dans la vue de contenu globale.
\nThe aspect ratio is not respected when window is resized programmatically with APIs like win.setSize.
win.setBackgroundColor(backgroundColor)backgroundColor String - Couleur d'arrière-plan de la fenêtre sous la forme d'une valeur hexadécimale, comme #66CD00 ou #FFF ou #80FFFFFF (l'alpha est supporté si transparent est true). La valeur par défaut est #FFF (white).Sets the background color of the window. See Setting backgroundColor.
win.previewFile(path[, displayName]) macOSpath String - Le chemin absolu vers le fichier à prévisualiser avec QuickLook. Ceci est important car Quick Look utilise le nom de fichier et l'extension de fichier sur le chemin pour déterminer le type de contenu du fichier à ouvrir.displayName String (facultatif) - Le nom du fichier à afficher dans la vue modale de Quick Look . Ceci est purement visuel et n'affecte pas le type de contenu du fichier. Par défaut, chemin.Utilise Aperçu rapide pour prévisualiser un fichier à un chemin donné.
\nwin.closeFilePreview() macOSFerme le panneau Aperçu rapide actuellement ouvert.
\nwin.setBounds(bounds[, animate])limites Partielanimate Boolean (facultatif) macOSRedimensionne et déplace la fenêtre vers les limites fournies. Any properties that are not supplied will default to their current values.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\n// définit toutes les propriétés limites\ngagner. etBounds({ x: 440, y: 225, width: 800, height: 600 })\n\n// a fixé une propriété de simples limites\ngagner. etBounds({ width: 100 })\n\n// { x: 440, y: 225, width: 100, height: 600 }\nconsole.log(win.getBounds())\nwin.getBounds()Retourne Rectangle - Les limites de la fenêtre comme Object.
win.getBackgroundColor()Returns String - Gets the background color of the window. See Setting backgroundColor.
win.setContentBounds(bounds[, animate])bounds Rectangleanimate Boolean (facultatif) macOSRedimensionne et déplace la zone client de la fenêtre (par exemple la page web) vers les limites fournies.
\nwin.getContentBounds()Retourne Rectangle - Les limites de la zone client de la fenêtre comme Object.
win.getNormalBounds()Retourne Rectangle - Contient les limites de la fenêtre de l'état normal
Remarque : quel que soit l'état actuel de la fenêtre : maximisé, minimisé ou en plein écran, retourne toujours la position et la taille de la fenêtre en état normal. En état normal, getBounds et getNormalBounds renvoient le même Rectangle.
win.setEnabled(enable)enable BooleanActive ou désactive la fenêtre.
\nwin.isEnabled()Retourne Boolean - Si la fenêtre est activée.
win.setSize(width, height[, animate])width Integerheight Integeranimate Boolean (facultatif) macOSRedimensionne la fenêtre à width x height. Si la largeur width ou la hauteur height sont inférieures aux minima définis, la fenêtre se limitera à sa taille minimale.
win.getSize()Retourne Integer[] - Contient la largeur et la hauteur de la fenêtre.
win.setContentSize(width, height[, animate])width Integerheight Integeranimate Boolean (facultatif) macOSRedimensionne la zone client de la fenêtre (par exemple la page web) à largeur et hauteur.
win.getContentSize()Retourne Integer[] - Contient la largeur et la hauteur de la zone client de la fenêtre.
win.setMinimumSize(width, height)width Integerheight IntegerDéfinit la taille minimale de la fenêtre à width et height.
win.getMinimumSize()Retourne Integer[] - Contient la largeur et la hauteur minimale de la fenêtre.
win.setMaximumSize(width, height)width Integerheight IntegerDéfinit la taille maximale de la fenêtre à width et height.
win.getMaximumSize()Retourne Integer[] - Contient la largeur et la hauteur maximale de la fenêtre.
win.setResizable(resizable)resizable BooleanDéfinit si la fenêtre peut être redimensionnée ou pas par l’utilisateur.
\nwin.isResizable()Retourne Boolean - Si la fenêtre peut être redimensionnée manuellement par l'utilisateur.
win.setMovable(movable) macOS Windowsmovable BooleanDéfinit si la fenêtre peut être déplacée par l’utilisateur. N'a aucun effet sous Linux.
\nwin.isMovable() macOS WindowsRetourne Boolean - Si la fenêtre peut être déplacée par l'utilisateur.
Sous Linux, retourne toujours true.
win.setMinimizable(minimizable) macOS Windowsminimizable BooleanDéfinit si la fenêtre peut être minimisée par l’utilisateur. N'a aucun effet sous Linux.
\nwin.isMinimizable() macOS WindowsRetourne Boolean - Si la fenêtre peut être minimisée par l'utilisateur.
Sous Linux, retourne toujours true.
win.setMaximizable(maximizable) macOS Windowsmaximizable BooleanDéfinit si la fenêtre peut être maximalisée par l’utilisateur. N'a aucun effet sous Linux.
\nwin.isMaximizable() macOS WindowsRetourne Boolean - Si la fenêtre peut être agrandie manuellement par l'utilisateur.
Sous Linux, retourne toujours true.
win.setFullScreenable(fullscreenable)fullscreenable BooleanDéfinit si le bouton agrandir/zoom de la fenêtre active/désactive le mode plein écran ou agrandit la fenêtre.
\nwin.isFullScreenable()Returns Boolean - Whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
win.setClosable(closable) macOS Windowsclosable BooleanSets whether the window can be manually closed by user. N'a aucun effet sous Linux.
\nwin.isClosable() macOS WindowsRetourne Boolean - Si la fenêtre peut être fermée manuellement par l'utilisateur.
Sous Linux, retourne toujours true.
win.setAlwaysOnTop(flag[, level][, relativeLevel])flag Booleanlevel String (facultatif) macOS Windows - Les valeurs incluent normal, floating, torn-off-menu, modal-panel, main-menu, statuus, pop-up-menu, screen-saver, et ~dock~~ (obsolète). La valeur par défaut est floating lorsque flag est vrai. Le niveau est réinitialisé à normal lorsque le drapeau est faux. Notez que de flottant à statut inclus, la fenêtre est placée sous le Dock sur macOS et sous la barre des tâches sous Windows. De pop-up-menu à une valeur supérieure, il est affiché au-dessus du Dock sur macOS et au-dessus de la barre des tâches sur Windows. Voir la documentation macOS pour plus de détails.relativeLevel Integer (facultatif) macOS - Le nombre de calques supérieur à définir cette fenêtre par rapport au level. Par défaut, 0. Notez que Apple décourage le réglage de niveaux supérieurs à 1 au-dessus de économiseur d'écran.Sets whether the window should show always on top of other windows. After setting this, the window is still a normal window, not a toolbox window which can not be focused on.
\nwin.isAlwaysOnTop()Retourne Boolean - Si la fenêtre est toujours au-dessus des autres fenêtres ou non.
win.moveAbove(mediaSourceId)mediaSourceId String - Window id in the format of DesktopCapturerSource's id. Par exemple \"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()Déplace la fenêtre sur le dessus (dans l'ordre z) peu importe qu'elle ait le focus ou non
\nwin.center()Déplace la fenêtre vers le centre de l’écran.
\nwin.setPosition(x, y[, animate])x Integery Integeranimate Boolean (facultatif) macOSDéplace la fenêtre à la position x et y.
win.getPosition()Retourne Integer[] - Contient la position actuelle de la fenêtre.
win.setTitle(title)title StringRemplace le titre de la fenêtre native par title.
win.getTitle()Retourne String - le titre de la fenêtre native.
Remarque : Le titre de la page web peut être différent du titre de la fenêtre native .
\nwin.setSheetOffset(offsetY[, offsetX]) macOSoffsetY FloatoffsetX Float (facultatif)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. Par exemple :
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nconst toolbarRect = document.getElementById('toolbar').getBoundingClientRect()\nwin.setSheetOffset(toolbarRect.height)\nwin.flashFrame(flag)flag BooleanDémarre ou arrête de flasher la fenêtre pour attirer l'attention de l'utilisateur.
\nwin.setSkipTaskbar(skip)skip BooleanFait que la fenêtre ne soit pas affichée dans la barre des tâches.
\nwin.setKiosk(flag)flag BooleanEnters or leaves kiosk mode.
\nwin.isKiosk()Retourne Boolean - Si la fenêtre est en mode kiosque.
win.isTabletMode() WindowsReturns Boolean - Whether the window is in Windows 10 tablet mode.
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.
\nThis API returns whether the window is in tablet mode, and the resize event can be be used to listen to changes to tablet mode.
win.getMediaSourceId()Returns String - Window id in the format of DesktopCapturerSource's id. Par exemple \"window:1324:0\".
More precisely the format is window:id:other_id where id is HWND on Windows, CGWindowID (uint64_t) on macOS and Window (unsigned long) on Linux. other_id is used to identify web contents (tabs) so within the same top level window.
win.getNativeWindowHandle()Retourne Buffer - Le gestionnaire spécifique à la plate-forme de la fenêtre.
Le type natif du handle est HWND sous Windows, NSView* sur macOS, et Window (longnon signé</0>) sous Linux.
win.hookWindowMessage(message, callback) Windowsmessage Integercallback FunctionwParam any - The wParam provided to the WndProclParam any - The lParam provided to the WndProcHooks a windows message. La callback est appelée lorsque le message est reçu dans le WndProc.
win.isWindowMessageHooked(message) Windowsmessage IntegerRetourne Boolean - true ou false selon que le message est accroché.
win.unhookWindowMessage(message) Windowsmessage IntegerDébranchez le message de la fenêtre.
\nwin.unhookAllWindowMessages() WindowsDécroche tous les messages de la fenêtre.
\nwin.setRepresentedFilename(filename) macOSfilename StringDéfinit le chemin d'accès du fichier que la fenêtre représente, et l'icône du fichier s'affichera dans la barre de titre de la fenêtre.
\nwin.getRepresentedFilename() macOSRetourne String - Le chemin du fichier que la fenêtre représente.
win.setDocumentEdited(edited) macOSedited BooleanSpécifie si le document de la fenêtre a été modifié, et l'icône dans la barre de titre deviendra grise lorsque réglé sur true.
win.isDocumentEdited() macOSRetourne Boolean - Si le document de la fenêtre a été modifié.
win.focusOnWebView()win.blurWebView()win.capturePage([rect])rect Rectangle (facultatif) - Les limites à capturerRetourne Promise<NativeImage> - résout avec une NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page. Si la page n'est pas visible, rect peut être vide.
win.loadURL(url[, options])url Stringoptions Object (facultatif)httpReferrer (String | Referrer) (facultatif) - Une URL de référence HTTP.userAgent String (optionnel) - Un agent utilisateur d'où provient la requête.extraHeaders String (optionnel) - Headers supplémentaires séparés par \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (facultatif) - URL de base (avec séparateur de chemin de pointe) pour que les fichiers soient chargés par l'URL de données. Ceci n'est nécessaire que si l'url spécifiée est une URL de données et a besoin de charger d'autres fichiers.Retourne Promise<void> - la promesse se résoudra lorsque la page aura terminé le chargement (voir did-finish-load), et rejette si la page ne parvient pas à se charger (voir did-fail-load).
Même que webContents.loadURL(url[, options]).
L'url peut être une adresse distante (par exemple http://) ou un chemin vers un fichier HTML local en utilisant le file:// protocole.
Pour s'assurer que les URL de fichier sont correctement formatées, il est recommandé d'utiliser la méthode Node's url.format :
const url = require('url').format({\n protocol: 'file',\n slashes: true,\n pathname: require('path').join(__dirname, 'index.html')\n})\n\nwin.loadURL(url)\nVous pouvez charger une URL en utilisant une requête POST avec des données encodées par URL en faisant ce qui suit :
win.loadURL('http://localhost:8000/post', {\n postData: [{\n type: 'rawData',\n bytes: Buffer.from('hello=world')\n }],\n extraHeaders: 'Content-Type: application/x-www-form-urlencoded'\n})\nwin.loadFile(filePath[, options])filePath Stringoptions Object (facultatif)query Enregistrement<String, String> (facultatif) - Passé à url.format().search String (facultatif) - Passé à url.format().hash String (facultatif) - Passé à url.format().Retourne Promise<void> - la promesse se résoudra lorsque la page aura terminé le chargement (voir did-finish-load), et rejette si la page ne parvient pas à se charger (voir did-fail-load).
Same as webContents.loadFile, filePath should be a path to an HTML file relative to the root of your application. See the webContents docs for more information.
win.reload()Identique à webContents.reload.
win.setMenu(menu) Linux Windowsmenu Menu | nullDéfinit le menu comme barre de menu de la fenêtre.
win.removeMenu() Linux WindowsRetirez la barre de menu de la fenêtre.
\nwin.setProgressBar(progress[, options])progress Doubleoptions Object (facultatif)mode String Windows - Mode for the progress bar. Can be none, normal, indeterminate, error or paused.Définit la valeur de progression dans la barre de progression. La plage valide est [0, 1.0].
\nSupprimer la barre de progression lorsque la progression < 0 ; Passer en mode indéterminé lorsque la progression > 1.
\nSur la plate-forme Linux, ne prend en charge que l'environnement de bureau Unity, vous devez spécifier le nom du fichier *.desktop au champ desktopName dans package.json. Par défaut, il assumera {app.name}.desktop.
Sous Windows, un mode peut être passé. Les valeurs acceptées sont none, normal, indeterminate, erreur, et paused. Si vous appelez setProgressBar sans mode défini (mais avec une valeur dans la plage valide), normal sera utilisé.
win.setOverlayIcon(overlay, description) Windowsoverlay NativeImage | null - l'icône à afficher en bas à droite de l'icône de la barre des tâches. Si ce paramètre est null, l'overlay est effacédescription Chaîne - une description qui sera fournie aux lecteurs d'écran d'accessibilitéDéfinit une superposition de 16 x 16 pixels sur l'icône actuelle de la barre des tâches, généralement utilisé pour transmettre une sorte de statut d'application ou pour notifier passivement l'utilisateur.
\nwin.setHasShadow(hasShadow)hasShadow BooleanDéfinit si la fenêtre doit avoir une ombre.
\nwin.hasShadow()Retourne Boolean - Si la fenêtre a une ombre.
win.setOpacity(opacity) Windows macOSopacité Nombre - entre 0.0 (entièrement transparent) et 1.0 (entièrement opaque)Définit l'opacité de la fenêtre. Sur Linux, n'a aucun effet. Out of bound number values are clamped to the [0, 1] range.
\nwin.getOpacity()Returns Number - between 0.0 (fully transparent) and 1.0 (fully opaque). Sur Linux, renvoie toujours 1.
win.setShape(rects) Windows Linux Experimentalrects Rectangle[] - Sets a shape on the window. Passing an empty list reverts the window to being rectangular.Définir une forme de fenêtre détermine la zone dans la fenêtre où le système permet de dessiner et d'interagir avec l'utilisateur. En dehors de la région donnée, aucun pixel ne sera dessiné et aucun événement de souris ne sera enregistré. Les événements de souris en dehors de la région ne seront pas reçus par cette fenêtre, mais passeront à tout ce qui se trouve derrière la fenêtre.
\nwin.setThumbarButtons(buttons) Windowsbuttons ThumbarButton[]Retourne Boolean - Si les boutons ont été ajoutés avec succès
Ajouter une barre d'outils miniature avec un ensemble de boutons spécifié à l'image de miniature d'une fenêtre dans la disposition d'un bouton de la barre des tâches. Renvoie un objet Booléen indique si la vignette a été ajoutée avec succès.
Le nombre de boutons dans la barre d'outils miniature ne doit pas dépasser 7 en raison de la salle limitée. Une fois que vous avez configuré la barre d'outils miniature, la barre d'outils ne peut pas être retirée en raison de la limitation de la plateforme. Mais vous pouvez appeler l'API avec un tableau vide pour nettoyer les boutons.
\nLe boutons est un tableau d'objets Bouton :
Buttonicon NativeImage - L'icône s'affichant dans la miniature dans la barre d'outils.click Functiontooltip String (facultatif) - Le texte dans l'info-bulle du bouton.flags String - Contrôle les états et comportements spécifiques du bouton. Par défaut, il est ['activé'].Le flags est un tableau pouvant inclure ces Strings suivant :
enabled - Le bouton est actif et disponible à l'utilisateur.désactivé - Le bouton est désactivé. Il est présent, mais a un état visuel indiquant qu'il ne répondra pas à l'action de l'utilisateur.dismissonclick - Lorsque le bouton est cliqué, la fenêtre de miniature se ferme immédiatement.nobackground - Utilise uniquement l'image et ne dessine pas de bordure sur le bouton.hidden - Le bouton n'est pas affiché à l'utilisateur.non interactif - Le bouton est activé mais non interactif ; aucun état de bouton n'est dessiné. Cette valeur est destinée aux cas où le bouton est utilisé dans une notification.win.setThumbnailClip(region) Windowsregion Rectangle - La région de la fenêtreDéfinit la région de la fenêtre à afficher comme image de miniature affichée lorsque survole la fenêtre dans la barre des tâches. Vous pouvez réinitialiser la miniature en toute la fenêtre en spécifiant une région vide : { x: 0, y: 0, width: 0, height: 0 }.
win.setThumbnailToolTip(toolTip) WindowstoolTip StringDéfinit l'infobulle qui s'affiche en survolant la vignette de la fenêtre dans la barre des tâches.
\nwin.setAppDetails(options) WindowsoptionsappId String (facultatif) - Fenêtre App User Model ID. Elle doit être définie, sinon les autres options n'auront aucun effet.appIconPath String (facultatif) - Fenêtre Icône de relance.appIconIndex Integer (optional) - Index of the icon in appIconPath. Ignored when appIconPath is not set. La valeur par defaut en est ``.relaunchCommand String (facultatif) - La Relaunch Commandde Windows.relaunchDisplayName String (facultatif) - Window's Relaunch Display Name.Définit les propriétés du bouton de la barre des tâches de la fenêtre.
\nNote: relaunchCommand and relaunchDisplayName must always be set together. Si l'une de ces propriétés n'est pas définie, aucune ne sera utilisée.
win.showDefinitionForSelection() macOSIdentique à webContents.showDefinitionForSelection().
win.setIcon(icon) Windows Linuxicon NativeImage | ChaîneChange l'icône de la fenêtre.
\nwin.setWindowButtonVisibility(visible) macOSvisible BooleanDéfinit si les boutons du feu de la fenêtre doivent être visibles.
\nwin.setAutoHideMenuBar(hide)hide BooleanDéfinit si la barre de menus de la fenêtre doit se cacher automatiquement. 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()Retourne Boolean - Si la barre de menu se cache automatiquement.
win.setMenuBarVisibility(visible) Windows Linuxvisible BooleanSets whether the menu bar should be visible. If the menu bar is auto-hide, users can still bring up the menu bar by pressing the single Alt key.
win.isMenuBarVisible()Retourne Boolean - Si la barre de menu est visible.
win.setVisibleOnWorkspaces(visible[, options])visible Booleanoptions Object (facultatif)visibleOnFullScreen Booléen (facultatif) macOS - Définit si la fenêtre doit être visible au-dessus des fenêtres plein écran.skipTransformProcessType Boolean (optional) macOS - Calling setVisibleOnAllWorkspaces will by default transform the process type between UIElementApplication and ForegroundApplication to ensure the correct behavior. However, this will hide the window and dock for a short time every time it is called. If your window is already of type UIElementApplication, you can bypass this transformation by passing true to skipTransformProcessType.Définit si la fenêtre doit être visible sur tous les espaces de travail.
\nRemarque : Cette API ne fonctionne pas sous Windows.
\nwin.isVisibleOnAllWorkspaces()Retourne Boolean - Si la fenêtre est visible sur tous les espaces de travail.
Remarque : Cette API retourne toujours false sur Windows.
\nwin.setIgnoreMouseEvents(ignore[, options])ignore Booleanoptions Object (facultatif)Avancer Boolean (facultatif) macOS Windows - Si vrai, transférez la souris messages vers Chromium, en activant les événements liés à la souris tels que souris. Utilisé uniquement lorsque ignore est vrai. Si ignore est faux, le transfert est toujours désactivé quelle que soit cette valeur.Fait que la fenêtre ignore tous les événements de la souris.
\nTous les événements survenus dans cette fenêtre seront passés à la fenêtre ci-dessous cette fenêtre, mais si cette fenêtre a le focus, elle recevra toujours les événements du clavier .
\nwin.setContentProtection(enable) macOS Windowsenable BooleanEmpêche le contenu de la fenêtre d'être capturé par d'autres applications.
\nOn 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 Windowsfocusable BooleanModifie si la fenêtre peut être mise au point.
\nSur macOS, il ne supprime pas le focus de la fenêtre.
\nwin.isFocusable() macOS WindowsReturns whether the window can be focused.
\nwin.setParentWindow(parent)parent BrowserWindow | nullDéfinit parent comme la fenêtre parent de la fenêtre actuelle, en passant null transformera la fenêtre actuelle en une fenêtre de niveau supérieur.
win.getParentWindow()Retourne BrowserWindow - La fenêtre parent.
win.getChildWindows()Retourne BrowserWindow[] - Toutes les fenêtres enfants.
win.setAutoHideCursor(autoHide) macOSautoHide BooleanContrôle s'il faut masquer le curseur lors de la saisie.
\nwin.selectPreviousTab() macOSSélectionne l'onglet précédent lorsque les onglets natifs sont activés et il y a d'autres onglets dans la fenêtre.
\nwin.selectNextTab() macOSSélectionne l'onglet suivant lorsque les onglets natifs sont activés et il y a d'autres onglets dans la fenêtre.
\nwin.mergeAllWindows() macOSFusionne toutes les fenêtres dans une seule fenêtre avec plusieurs onglets lorsque les onglets natifs sont activés et qu'il y a plus d'une fenêtre ouverte.
\nwin.moveTabToNewWindow() macOSDéplace l'onglet actuel dans une nouvelle fenêtre si les onglets natifs sont activés et il y a plus d'un onglet dans la fenêtre actuelle.
\nwin.toggleTabBar() macOSActive/désactive la visibilité de la barre d’onglets si les onglets natifs sont activés et il n’y a qu’un seul onglet dans la fenêtre actuelle.
\nwin.addTabbedWindow(browserWindow) macOSbrowserWindow BrowserWindowAjoute une fenêtre sous la forme d'un onglet sur cette fenêtre, après l'onglet de l'instance de fenêtre.
\nwin.setVibrancy(type) macOStype String | null - Peut être appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, sous-window, ou sous-page. Voir la documentation macOS pour plus de détails.Adds a vibrancy effect to the browser window. Passing null or an empty string will remove the vibrancy effect on the window.
Notez que appearance-based, light, dark, medium-light, et ultra-dark ont été obsolètes et seront supprimées dans une prochaine version de macOS.
win.setTrafficLightPosition(position) macOSposition PointSet a custom position for the traffic light buttons in frameless window.
\nwin.getTrafficLightPosition() macOSReturns Point - The custom position for the traffic light buttons in frameless window.
win.setTouchBar(touchBar) macOStouchBar TouchBar | nullDéfinit la disposition de la barre tactile pour la fenêtre actuelle. La spécification null ou undefined efface la barre de contact. Cette méthode n'a d'effet que si la machine a une barre tactile et est en cours d'exécution sur macOS 10.12.1+.
Remarque : L’API TouchBar est actuellement expérimentale et peut changer ou être supprimée dans les futures mises à jour d'Electron.
\nwin.setBrowserView(browserView) ExperimentalbrowserView BrowserView | null - Attache une browserView à win. Si d'autres BrowserViewsont déjà attachées, elles seront supprimés de cette fenêtre.win.getBrowserView() ExpérimentalRetourne BrowserView | null - La BrowserView attachée à win. Retourne null si aucune n'est attachée. Lance une erreur si plusieurs BrowserView sont attachées.
win.addBrowserView(browserView) ExpérimentalbrowserView BrowserViewRemplacement de l'API pour setBrowserView prenant en charge le travail avec des vues multi navigateurs.
\nwin.removeBrowserView(browserView) ExpérimentalbrowserView BrowserViewwin.setTopBrowserView(browserView) ExpérimentalbrowserView BrowserViewRaises browserView above other BrowserViews attached to win. Lance une erreur si browserView n'est pas attaché à win.
win.getBrowserViews() ExpérimentalRetourne BrowserView[] - un tableau de toutes les BrowserViews qui ont été attachées avec addBrowserView ou setBrowserView.
Remarque : L’API BrowserView est actuellement expérimentale et peut changer ou être supprimée dans les futures mises à jour d'Electron.
", "title": "BrowserWindow", "description": "Créer et gérer des fenêtres navigateur." }, "/docs/api/browser-window-proxy": { "locale": "fr-FR", "slug": "browser-window-proxy", "href": "/docs/api/browser-window-proxy", "crowdinFileId": "256285", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-window-proxy.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nManipule la fenêtre enfant
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
L'objet BrowserWindowProxy est retournée par window.open et fournit les fonctionnalités limitées avec la fenêtre enfant.
L’objet BrowserWindowProxy dispose des méthodes d’instance suivantes :
win.blur()Retire le focus de la fenêtre enfant.
\nwin.close()Force la fermeture de la fenêtre enfant sans appeler l'événement unload.
\nwin.eval(code)code StringÉvalue le code dans la fenêtre enfant.
\nwin.focus()Donne le focus à la fenêtre enfant (met la fenêtre au premier-plan).
\nwin.print()Appelle la boîte de dialogue Impression sur la fenêtre enfant.
\nwin.postMessage(message, targetOrigin)message toustargetOrigin StringEnvoie un message à la fenêtre enfant avec l'origine spécifié ou * pour aucune préférence d'origine.
En plus de ces méthodes, la fenêtre enfant implémente l'objet window.opener avec aucune propriété et une méthode unique.
L’objet BrowserWindowProxy dispose des propriétés d’instance suivantes :
win.closedUn Boolean qui a la valeur true après que la fenêtre enfant soit fermée.
Suivez les instructions ci-dessous pour compiler Electron, afin de créer une version compilée personnalisée d'Electron. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nVérifiez les prérequis de build pour votre plateforme avant de continuer
\n\nElectron's Build Tools automate much of the setup for compiling Electron from source with different configurations and build targets. If you wish to set up the environment manually, the instructions are listed below.
\nVous devrez installer depot_tools, l'ensemble d'outils utilisé pour récupérer Chromium et ses dépendances.
De plus, sous Windows, vous devrez définir la variable d'environnement DEPOT_TOOLS_WIN_TOOLCHAIN=0. Pour ce faire, ouvrez Panneau de configuration → Système et Sécurité → Système → Paramètres système avancés et ajouter une variable système DEPOT_TOOLS_WIN_TOOLCHAIN avec la valeur 0. Cela indique au depot_tools d’utiliser votre version locale de Visual Studio (par défaut, depot_tools essaiera de télécharger une version interne de Google uniquement accessible à ses utilisateurs).
If you plan on checking out Electron more than once (for example, to have multiple parallel directories checked out to different branches), using the git cache will speed up subsequent calls to gclient. To do this, set a GIT_CACHE_PATH environment variable:
$ export GIT_CACHE_PATH=\"${HOME}/.git_cache\"\n$ mkdir -p \"${GIT_CACHE_PATH}\"\n# This will use about 16G.\n$ mkdir electron && cd electron\n$ gclient config --name \"src/electron\" --unmanaged https://github.com/electron/electron\n$ gclient sync --with_branch_heads --with_tags\n# This will take a while, go get a coffee.\n\n\nAu lieu de
\nhttps://github.com/electron/electron, vous pouvez utiliser votre propre fork ici (quelque chose commehttps://github.com/<username>/electron).
If you intend to git pull or git push from the official electron repository in the future, you now need to update the respective folder's origin URLs.
$ cd src/electron\n$ git remote remove origin\n$ git remote add origin https://github.com/electron/electron\n$ git checkout main\n$ git branch --set-upstream-to=origin/main\n$ cd -\n📝 gclient works by checking a file called DEPS inside the src/electron folder for dependencies (like Chromium or Node.js). Running gclient sync -f ensures that all dependencies required to build Electron match that file.
So, in order to pull, you'd run the following commands:
\n$ cd src/electron\n$ git pull\n$ gclient sync -f\n$ cd src\n$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nOu sous Windows (sans l'argument optionnel) :
\n$ cd src\n$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\\buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\")\"\nThis will generate a build directory out/Testing under src/ with the testing build configuration. You can replace Testing with another name, but it should be a subdirectory of out. Also you shouldn't have to run gn gen again—if you want to change the build arguments, you can run gn args out/Testing to bring up an editor.
To see the list of available build configuration options, run gn args out/Testing --list.
For generating Testing build config of Electron:
\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nFor generating Release (aka \"non-component\" or \"static\") build config of Electron:
\n$ gn gen out/Release --args=\"import(\\\"//electron/build/args/release.gn\\\") $GN_EXTRA_ARGS\"\nTo build, run ninja with the electron target: Nota Bene: This will also take a while and probably heat up your lap.
Pour la configuration de test :
\n$ ninja -C out/Testing electron\nFor the release configuration:
\n$ ninja -C out/Release electron\nThis will build all of what was previously 'libchromiumcontent' (i.e. the content/ directory of chromium and its dependencies, incl. WebKit and V8), so it will take a while.
The built executable will be under ./out/Testing:
$ ./out/Testing/Electron.app/Contents/MacOS/Electron\n# or, on Windows\n$ ./out/Testing/electron.exe\n# or, on Linux\n$ ./out/Testing/electron\nSous Linux, supprimez d'abord les informations de débogage et de symbole :
\nelectron/script/strip-binaries.py -d out/Release\nTo package the electron build as a distributable zip file:
\nninja -C out/Release electron:electron_dist_zip\nTo compile for a platform that isn't the same as the one you're building on, set the target_cpu and target_os GN arguments. For example, to compile an x86 target from an x64 host, specify target_cpu = \"x86\" in gn args.
$ gn gen out/Testing-x86 --args='... target_cpu = \"x86\"'\nNot all combinations of source and target CPU/OS are supported by Chromium.
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Host | Target | Notice |
|---|---|---|
| Windows x64 | Windows arm64 | Expérimental |
| Windows x64 | Windows x86 | Automatically tested |
| Linux x64 | Linux x86 | Automatically tested |
Si vous testez d'autres combinaisons et trouvez qu'elles fonctionnent, veuillez mettre à jour ce document :)
\nSee the GN reference for allowable values of target_os and target_cpu.
To cross-compile for Windows on Arm, follow Chromium's guide to get the necessary dependencies, SDK and libraries, then build with ELECTRON_BUILDING_WOA=1 in your environment before running gclient sync.
set ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nOu (si vous utilisez PowerShell) :
\n$env:ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nNext, run gn gen as above with target_cpu=\"arm64\".
To run the tests, you'll first need to build the test modules against the same version of Node.js that was built as part of the build process. To generate build headers for the modules to compile against, run the following under src/ directory.
$ ninja -C out/Testing third_party/electron_node:headers\nVous pouvez maintenant exécuter les tests.
\nIf you're debugging something, it can be helpful to pass some extra flags to the Electron binary:
\n$ npm run test -- \\\n --enable-logging -g 'BrowserWindow module'\nIt is possible to share the gclient git cache with other machines by exporting it as SMB share on linux, but only one process/machine can be using the cache at a time. The locks created by git-cache script will try to prevent this, but it may not work perfectly in a network.
\nOn Windows, SMBv2 has a directory cache that will cause problems with the git cache script, so it is necessary to disable it by setting the registry key
\nHKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\\DirectoryCacheLifetime\nà 0. Plus d'informations : https://stackoverflow.com/a/9935126
\nCela peut être défini rapidement dans powershell (exécuté en tant qu'administrateur) :
\nNew-ItemProperty -Path \"HKLM:\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force\nIf gclient sync is interrupted the git tree may be left in a bad state, leading to a cryptic message when running gclient sync in the future:
2> Conflict while rebasing this branch.\n2> Fix the conflict and run gclient again.\n2> See man git-rebase for details.\nIf there are no git conflicts or rebases in src/electron, you may need to abort a git am in src:
$ cd ../\n$ git am --abort\n$ cd electron\n$ gclient sync -f\nSi vous voyez une invite pour nom d'utilisateur pour 'https://chrome-internal.googlesource. om': lorsque vous exécutez gclient sync sous Windows, c'est probablement parce que la variable d'environnement DEPOT_TOOLS_WIN_TOOLCHAIN n'est pas définie à 0. Ouvrez Control Panel → System and Security → System → Advanced system settings et ajoutez une variable système DEPOT_TOOLS_WIN_TOOLCHAIN avec comme valeur 0. Cela indique au depot_tools d’utiliser votre version locale de Visual Studio (par défaut, depot_tools essaiera de télécharger une version interne de Google uniquement accessible à ses utilisateurs).
Follow the guidelines below for building Electron itself on Linux, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nAt least 25GB disk space and 8GB RAM.
\nPython 2.7.x. Some distributions like CentOS 6.x still use Python 2.6.x so you may need to check your Python version with python -V.
Please also ensure that your system and Python version support at least TLS 1.2. For a quick test, run the following script:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, use your system's package manager to update Python to the latest version in the 2.7.x branch. Alternatively, visit https://www.python.org/downloads/ for detailed instructions.
\nNode.js. There are various ways to install Node. You can download source code from nodejs.org and compile it. Doing so permits installing Node on your own home directory as a standard user. Or try repositories such as NodeSource.
\nclang 3.4 or later.
\nDevelopment headers of GTK 3 and libnotify.
\nOn Ubuntu, install the following libraries:
\n$ sudo apt-get install build-essential clang libdbus-1-dev libgtk-3-dev \\\n libnotify-dev libgnome-keyring-dev \\\n libasound2-dev libcap-dev libcups2-dev libxtst-dev \\\n libxss1 libnss3-dev gcc-multilib g++-multilib curl \\\n gperf bison python-dbusmock openjdk-8-jre\nOn RHEL / CentOS, install the following libraries:
\n$ sudo yum install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Fedora, install the following libraries:
\n$ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Arch Linux / Manjaro, install the following libraries:
\n$ sudo pacman -Syu base-devel clang libdbus gtk2 libnotify \\\n libgnome-keyring alsa-lib libcap libcups libxtst \\\n libxss nss gcc-multilib curl gperf bison \\\n python2 python-dbusmock jdk8-openjdk\nOther distributions may offer similar packages for installation via package managers such as pacman. Or one can compile from source code.
\nIf you want to build for an arm target you should also install the following dependencies:
$ sudo apt-get install libc6-dev-armhf-cross linux-libc-dev-armhf-cross \\\n g++-arm-linux-gnueabihf\nSimilarly for arm64, install the following:
$ sudo apt-get install libc6-dev-arm64-cross linux-libc-dev-arm64-cross \\\n g++-aarch64-linux-gnu\nAnd to cross-compile for arm or ia32 targets, you should pass the target_cpu parameter to gn gen:
$ gn gen out/Testing --args='import(...) target_cpu=\"arm\"'\nPrebuilt clang will try to link to libtinfo.so.5. Depending on the host architecture, symlink to appropriate libncurses:
$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5\nThe default building configuration is targeted for major desktop Linux distributions. To build for a specific distribution or device, the following information may help you.
\nclang instead of downloaded clang binariesBy default Electron is built with prebuilt clang binaries provided by the Chromium project. If for some reason you want to build with the clang installed in your system, you can specify the clang_base_path argument in the GN args.
For example if you installed clang under /usr/local/bin/clang:
$ gn gen out/Testing --args='import(\"//electron/build/args/testing.gn\") clang_base_path = \"/usr/local/bin\"'\nclangBuilding Electron with compilers other than clang is not supported.
Follow the guidelines below for building Electron itself on macOS, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nPlease also ensure that your system and Python version support at least TLS 1.2. Cela dépend à la fois de votre version de macOS et de Python. For a quick test, run:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, you can either update macOS to High Sierra or install a new version of Python 2.7.x. Pour mettre à jour Python, utilisez Homebrew :
\n$ brew install python@2 && brew link python@2 --force\nSi vous utilisez le Python fournit par Homebrew, vous devez également installer les modules Python suivants:
\nVous pouvez utiliser pip pour l'installer :
$ pip install pyobjc\nSi vous développez Electron et ne prévoyez pas de redistribuer votre version d'Electron vous pouvez sauter cette section.
\nOfficial Electron builds are built with Xcode 12.2, and the macOS 11.0 SDK. Compiler avec des nouvelles version du SDK marche aussi, mais les releases utilisent actuellement le SDK 11.0.
\nVoir les Instructions de compilation : GN.
", "title": "Instructions de Build (macOS)", "description": "" }, "/docs/development/build-instructions-windows": { "locale": "fr-FR", "slug": "build-instructions-windows", "href": "/docs/development/build-instructions-windows", "crowdinFileId": "256137", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/build-instructions-windows.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Follow the guidelines below for building Electron itself on Windows, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nvs2019_install = DRIVE:\\path\\to\\Microsoft Visual Studio\\2019\\Community, remplaçant 2019 et Communauté par vos versions installées et remplaçant DRIVE: par le lecteur sur lequel Visual Studio est allumé. Souvent, ce sera C:.WINDOWSSDKDIR = DRIVE:\\path\\to\\Windows Kits\\10, replacing DRIVE: with the drive that Windows Kits is on. Souvent, ce sera C:.symstore.exe is used for creating a symbol store from .pdb files.Modify → Composants individuels, faites défiler vers le bas et sélectionnez le SDK Windows approprié à installer. Une autre option serait de regarder la Windows SDK et l'archive émulateur et de télécharger la version autonome du SDK respectivement.Panneau de configuration → Programmes → Programmes et fonctionnalités → Sélectionnez le \"Kit de développement du logiciel Windows\" → Changement → Changement → Vérifiez \"Outils de débogage pour Windows\" → Changement. Ou, vous pouvez télécharger l'installateur SDK autonome et l'utiliser pour installer les outils de débogage.Si vous ne disposez pas d’une installation Windows, dev.microsoftedge.com propose des versions de Windows qui vous permets de compiler Electron.
\nLa compilation d'Electron se fait entièrement avec des scripts en ligne de commande et ne peut se faire avec Visual Studio. Vous pouvez développer Electron avec n’importe quel éditeur, mais le support de la compilation avec Visual Studio viendra dans le futur.
\nRemarque : Même si Visual Studio n’est pas utilisé pour la compilation, il est toujours nécessaire car nous avons besoin du build toolchains qu'il fournit.
\nWindows Security doesn't like one of the files in the Chromium source code (see https://crbug.com/441184), so it will constantly delete it, causing gclient sync issues. You can exclude the source tree from being monitored by Windows Security by following these instructions.
Pour construire pour la cible 32 bits, vous devez passer target_cpu = \"x86\" en tant qu'arg. GN. Vous pouvez construire la cible 32 bits à côté de la cible 64 bits en utilisant un répertoire de sortie différent pour GN, par exemple out/Release-x86, avec des arguments différents.
$ gn gen out/Release-x86 --args=\"import(\\\"//electron/build/args/release.gn\\\") target_cpu=\\\"x86\\\"\"\nLes autres étapes pour la compilation sont exactement les mêmes.
\nPour générer un projet Visual Studio, vous pouvez passer le paramètre --ide=vs2017 à gn gen:
$ gn gen out/Testing --ide=vs2017\nSi vous avez rencontré une erreur comme commande xxxx introuvable, vous pouvez essayez la console de ligne de commande VS2015 pour exécuter les scripts de compilation.
Assurez-vous d'avoir la dernière mise à jour de Visual Studio installé.
\nEssayez de réinstaller Node.js 32bit.
\nLa création du répertoire suivant devrait corriger le problème :
\n$ mkdir ~\\AppData\\Roaming\\npm\nCette erreur peut se produire si vous utilisez Git Bash pour la compilation, vous devez utiliser PowerShell ou l'invite de commande de VS2015 à la place.
\nnode.js a quelques noms de chemin extrêmement longs, et par défaut git sur windows ne gère pas correctement les chemins longs (même si Windows les supporte). Cela devrait être réparé :
\n$ git config --system core.longpaths true\nThis can happen during build, when Debugging Tools for Windows has been installed with Windows Driver Kit. Uninstall Windows Driver Kit and install Debugging Tools with steps described above.
\nAssurez-vous d'avoir installé pywin32 avec pip install pywin32.
Ce bug est une « fonctionnalité » de l'invite de commande de Windows. Cela se produit lorsque vous cliquez dans la fenêtre d'invite avec l'option Édition rapide et est destiné à permettre la sélection et la copie du texte de sortie facilement. Puisque chaque clic accidentel met en pause le processus de construction, vous pouvez désactiver cette fonctionnalité dans les propriétés de l'invite de commande.
Electron utilise GN pour la génération de projet et ninja pour la construction. Les configurations du projet peuvent être trouvées dans les fichiers .gn et .gni .
Les fichiers gn suivants contiennent les règles principales pour la construction d'Electron :
BUILD.gn définit comment Electron lui-même est construit et inclut les configurations par défaut pour se connecter avec Chromium.build/args/{debug,release,all}.gn contient les arguments de construction par défaut pour compilant Electron.Étant donné que Chrome est un sacré gros projet, la dernière étape de reliage (linking) peut prendre quelques minutes, ce qui rend le développement difficile. Afin de résoudre ce problème, Chrome a introduit le « component build », qui compile chaque composant comme une bibliothèque partagée distincte, faisant le lien très rapidement mais sacrifie la taille de fichier et la performance.
\nElectron hérite de cette option de compilation de Chromium. Dans les versions Debug, le binaire sera lié à une version partagée de la bibliothèque des composants de Chromium pour obtenir un temps de liaison rapide ; pour les versions Release, le binaire sera lié à les versions statiques de la bibliothèque, pour que nous puissions avoir la meilleure taille binaire possible et les meilleures performances .
NB cette section est obsolète et contient des informations qui ne sont plus pertinentes pour l'électronique GN.
\nPour tester que vos changements soient conforme avec le code style du projet :
\n$ npm run lint\nPour tester les fonctionnalités :
\n$ npm test\nChaque fois que vous apportez des modifications au code source d'Electron, vous devez ré-exécuter la compilation avant les tests :
\n$ npm run build && npm test\nVous pouvez rendre la suite de tests plus rapide en isolant le test spécifique ou bloc que vous travaillez actuellement à l’aide de la fonctionnalité tests exclusifs de Mocha. Ajoutez .only pour chaque appel aux fonctions describe ou it:
describe.only('some feature', () => {\n // ... Seuls les tests de ce bloc seront exécutés\n})\nAlternativement, vous pouvez utiliser l'option grep de Mocha pour exécuter uniquement les tests correspondant au modèle d’expression régulière donnée :
$ npm test -- --grep child_process\nLes tests qui incluent des modules natifs (par exemple runas) ne peuvent être exécutées avec le débogage (voir #2558 pour plus de détails), mais ils fonctionneront avec la version Release.
Pour exécuter les tests avec le build release :
\n$ npm test -- -R\ndata String - PEM encoded dataissuer CertificatePrincipal - Issuer principalissuerName String - Issuer's Common NameissuerCert Certificate - Issuer certificate (if not self-signed)subject CertificatePrincipal - Subject principalsubjectName String - Subject's Common NameserialNumber String - Hex value represented stringvalidStart Number - Start date of the certificate being valid in secondsvalidExpiry Number - End date of the certificate being valid in secondsfingerprint String - Fingerprint of the certificatecommonName String - Common Name.organizations String[] - Organization names.organizationUnits String[] - Organization Unit names.locality String - Locality.state String - State or province.country String - Country or region.\n\nUne collection de ressources pour l’apprentissage à propos de Chromium et pour suivre son développement
\n
Voir aussi Développement V8
", "title": "Développement Chromium", "description": "Une collection de ressources pour l’apprentissage à propos de Chromium et pour suivre son développement" }, "/docs/development/clang-format": { "locale": "fr-FR", "slug": "clang-format", "href": "/docs/development/clang-format", "crowdinFileId": "256143", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/clang-format.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Clang-format est un outil pour formater le code C/C++/Objective-C permettant aux développeurs de ne pas se soucier des problèmes de style au cours de la révision du code.
Il est fortement recommandé de formater votre code C++ avant d'ouvrir des pull requests afin de vous faire gagner du temps ainsi qu'aux réviseurs.
\nVous pouvez installer clang-format et git-clang-format via npm install -g clang-format.
To automatically format a file according to Electron C++ code style, run clang-format -i path/to/electron/file.cc. It should work on macOS/Linux/Windows.
Suivez ces étapes pour changer votre code :
\ngit add votre_fichier.cc.git-clang-format et vous verrez probablement des modifications dans votre_fichier.cc, ces modifications sont générées à partir de clang-format.git add votre_fichier.cc et commitez vos modifications.If you want to format the changed code on your latest git commit (HEAD), you can run git-clang-format HEAD~1. See git-clang-format -h for more details.
You can also integrate clang-format directly into your favorite editors. For further guidance on setting up editor integration, see these pages:
clang-tidy is a tool to automatically check C/C++/Objective-C code for style violations, programming errors, and best practices.
Electron's clang-tidy integration is provided as a linter script which can be run with npm run lint:clang-tidy. While clang-tidy checks your on-disk files, you need to have built Electron so that it knows which compiler flags were used. There is one required option for the script --output-dir, which tells the script which build directory to pull the compilation information from. Une utilisation typique serait : npm run lint:clang-tidy --out-dir ../out/Testing
With no filenames provided, all C/C++/Objective-C files will be checked. Vous pouvez fournir une liste de fichiers à vérifier en passant les noms de fichiers après les options : npm run lint:clang-tidy --out-dir ../out/Testing shell/browser/api/electron_api_app.cc
While clang-tidy has a long list of possible checks, in Electron only a few are enabled by default. At the moment Electron doesn't have a .clang-tidy config, so clang-tidy will find the one from Chromium at src/.clang-tidy and use the checks which Chromium has enabled. Vous pouvez modifier les vérifications exécutées en utilisant le l'option --checks=. Ceci est transmis directement à clang-tidy, alors voyez sa documentation pour plus de détails. Wildcards can be used, and checks can be disabled by prefixing a -. By default any checks listed are added to those in .clang-tidy, so if you'd like to limit the checks to specific ones you should first exclude all checks then add back what you want, like --checks=-*,performance*.
Running clang-tidy is rather slow - internally it compiles each file and then runs the checks so it will always be some factor slower than compilation. While you can use parallel runs to speed it up using the --jobs|-j option, clang-tidy also uses a lot of memory during its checks, so it can easily run into out-of-memory errors. En tant que tel, le nombre de tâches par défaut est un.
\n\nFaire des requêtes HTTP/HTTPS.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
ClientRequest implémente l'interface de Writable Stream et, du coup, elle est un EventEmitter.
new ClientRequest(options)options (Object | String) - If options is a String, it is interpreted as the request URL. If it is an object, it is expected to fully specify an HTTP request via the following properties:method String (optional) - The HTTP request method. Defaults to the GET method.url String (optional) - The request URL. Must be provided in the absolute form with the protocol scheme specified as http or https.session Session (facultatif) - l'instance Session avec à laquelle la requête est associée.partition String (facultatif) - Le nom de la partition avec laquelle la requête est associée. Par défaut, la chaîne vide est utilisée. The session option supersedes partition. Ainsi, si une session est explicitement spécifiée , partition est ignorée.credentials String (optional) - Can be include or omit. Whether to send credentials with this request. If set to include, credentials from the session associated with the request will be used. If set to omit, credentials will not be sent with the request (and the 'login' event will not be triggered in the event of a 401). This matches the behavior of the fetch option of the same name. If this option is not specified, authentication data from the session will be sent, and cookies will not be sent (unless useSessionCookies is set).useSessionCookies Boolean (optional) - Whether to send cookies with this request from the provided session. If credentials is specified, this option has no effect. Par défaut la valeur est false.protocol String (optional) - Can be http: or https:. The protocol scheme in the form 'scheme:'. Defaults to 'http:'.host String (facultatif) - L'hôte du serveur fourni en concaténation de le nom d'hôte et le numéro de port 'hostname:port'.hostname String (facultatif) - Le nom d'hôte du serveur.port Integer (facultatif) - Le numéro de port d'écoute du serveur.path String (facultatif) - La partie chemin de l'URL de la requête.redirect String (facultatif) -Peut être follow, error ou manual. The redirect mode for this request. When mode is error, any redirection will be aborted. When mode is manual the redirection will be cancelled unless request.followRedirect is invoked synchronously during the redirect event. Par défaut, follow.origin String (optional) - The origin URL of the request.options propriétés telles que protocole, host, hostname, port et path suivent strictement le modèle Node.js comme décrit dans le module URL.
Par exemple, nous aurions pu créer la même requête à 'github.com' comme suit:
\nconst request = net.request({\n method: 'GET',\n protocol: 'https:',\n hostname: 'github.com',\n port: 443,\n path: '/'\n})\nRetourne :
\nresponse IncomingMessage - Un objet représentant le message de réponse HTTP.Retourne :
\nauthInfoisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionnom d'utilisateur String (facultatif)mot de passe String (facultatif)Émis lorsqu'un proxy d'authentification demande les identifiants de l'utilisateur.
\nLa fonction callback est censée être rappelée avec les identifiants de l'utilisateur :
username Stringpassword Stringrequest.on('login', (authInfo, callback) => {\n callback('username', 'password')\n})\nFournir des identifiants vides annulera la demande et signalera une erreur d'authentification sur l'objet de réponse :
\nrequest.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`);\n response.on('error', (error) => {\n console.log(`ERROR: ${JSON.stringify(error)}`)\n })\n})\nrequest.on('login', (authInfo, callback) => {\n callback()\n})\nÉmis juste après le dernier chunk de l'objet request a été écrit dans l'objet request.
Emitted when the request is aborted. The abort event will not be fired if the request is already closed.
Retourne :
\nerror Erreur - un objet d'erreur fournissant des informations sur l'échec.Émis lorsque le module net ne parvient pas à émettre une requête réseau. Généralement lorsque l'objet request émet un événement error, un événement close sera ensuite suivi et aucun objet de réponse ne sera fourni.
Émis en tant que dernier événement dans la transaction de réponse de requête HTTP. L'événement close indique qu'aucun événement ne sera émis sur les objets request ou response.
Retourne :
\nstatusCode Integermethod StringredirectUrl StringEn-têtes de réponse<String, String[]>Émis lorsque le serveur renvoie une réponse de redirection (par exemple 301 Déplacé de manière permanente). Appeler request.followRedirect va continuer avec la redirection. Si cet événement est géré, request.followRedirect doit être appelé synchrones, sinon la requête sera annulée.
request.chunkedEncodingUn Booléen spécifiant si la requête utilisera l'encodage de transfert HTTP chunked ou non. Par défaut, faux. La propriété est lisible et en écriture, Cependant, il ne peut être défini que avant la première opération d'écriture car les en-têtes HTTP ne sont pas encore mis sur le fil. Tenter de définir la propriété chunkedEncoding après la première écriture lancera une erreur.
L'utilisation de l'encodage chunked est fortement recommandée si vous avez besoin d'envoyer un grand corps de requête car les données seront diffusées en petits morceaux au lieu d'être en mémoire tampon interne dans la mémoire de processus d'Electron.
\nrequest.setHeader(name, value)name String - Un nom d'en-tête HTTP supplémentaire.valeur String - Une valeur d'en-tête HTTP supplémentaire.Ajoute un en-tête HTTP supplémentaire. Le nom de l'en-tête sera publié tel quel sans minuscules. Il peut être appelé seulement avant d'écrire en premier. Appeler cette méthode après la première écriture lancera une erreur. Si la valeur passée n'est pas une String, sa méthode toString() sera appelée pour obtenir la valeur finale.
Certain headers are restricted from being set by apps. These headers are listed below. More information on restricted headers can be found in Chromium's header utils.
\nContent-LengthHostTrailer or TeUpgradeCookie2Keep-AliveTransfer-EncodingAdditionally, setting the Connection header to the value upgrade is also disallowed.
request.getHeader(name)name Chaîne - Spécifie un nom d'en-tête supplémentaire.Retourne String - La valeur d'un nom d'en-tête supplémentaire précédemment défini.
request.removeHeader(name)name Chaîne - Spécifie un nom d'en-tête supplémentaire.Removes a previously set extra header name. This method can be called only before first write. Trying to call it after the first write will throw an error.
\nrequest.write(chunk[, encoding][, callback])chunk (String | Buffer) - A chunk of the request body's data. If it is a string, it is converted into a Buffer using the specified encoding.encoding String (optional) - Used to convert string chunks into Buffer objects. Defaults to 'utf-8'.callback Fonction (facultatif) - Appelée après la fin de l'opération d'écriture.callback est essentiellement une fonction factice introduite dans le but de conserver la similarité avec l'API Node.js. Il est appelé de manière asynchrone dans le prochain tick après que le contenu chunk ait été livré à la couche de réseau Chromium. Contrairement à l'implémentation de Node.js, il n'est pas garanti que le contenu chunk ait été vidé sur le fil avant que callback ne soit appelé.
Ajoute un morceau de données au corps de la requête. La première opération d'écriture peut causer la publication des en-têtes de la requête sur le fil. Après la première opération d'écriture, il n'est pas autorisé d'ajouter ou de supprimer un en-tête personnalisé.
\nrequest.end([chunk][, encoding][, callback])chunk (String | Buffer) (facultatif)encoding String (facultatif)callback Function (facultatif)Sends the last chunk of the request data. Subsequent write or end operations will not be allowed. The finish event is emitted just after the end operation.
request.abort()Annule une transaction HTTP en cours. Si la requête a déjà émis l'événement close , l'opération d'abandon n'aura aucun effet. Sinon, un événement en cours émettra des événements abandon et close . De plus, s'il y a un objet de réponse en cours, il émettra l'évènement abandonné.
request.followRedirect()Continues any pending redirection. Can only be called during a 'redirect' event.
request.getUploadProgress()Retourne Object:
active Boolean - Whether the request is currently active. If this is false no other properties will be setstarted Boolean - Whether the upload has started. If this is false both current and total will be set to 0.current Integer - Le nombre d'octets qui ont été téléchargés jusqu'à présenttotal Integer - Le nombre d'octets qui seront chargés dans cette requêteVous pouvez utiliser cette méthode en conjonction avec les requêtes POST pour obtenir la progression d'un téléchargement de fichier ou d'un autre transfert de données.
\n\n\nPermet d'effectuer les opérations copier et coller dans le presse-papiers.
\n
On Linux, there is also a selection clipboard. To manipulate it you need to pass selection to each method:
const { clipboard } = require('electron')\n\nclipboard.writeText('Mon exemple', 'selection') console.log(clipboard.readText('selection'))\nLe module clipboard dispose des méthodes suivantes :
Remarque : Les APIs expérimentales sont marquées comme telles et sont susceptibles d'être supprimés à l'avenir.
\nclipboard.readText([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Retourne String - Le contenu du presse-papiers en tant que texte brut.
const { clipboard } = require('electron')\n\nclipboard.writeText('hello i am a bit of text!')\n\nconst text = clipboard.readText()\nconsole.log(text)\n// hello i am a bit of text!'\nclipboard.writeText(text[, type])text Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Écrit le text dans le presse-papiers au format texte brut.
const { clipboard } = require('electron')\n\nconst text = 'bonjour je suis un peu de texte!'\nclipboard.writeText(text)\nclipboard.readHTML([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Retourne String - Le contenu du presse-papiers en tant que balisage.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b>')\nconst html = clipboard.readHTML()\n\nconsole.log(html)\n// <meta charset='utf-8'><b>Hi</b>\nclipboard.writeHTML(markup[, type])markup Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Écrit le markup dans le presse-papiers.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Bonjour</b')\nclipboard.readImage([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Retourne NativeImage - Le contenu de l'image du presse-papiers.
clipboard.writeImage(image[, type])image NativeImagetype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Écrit l'image dans le presse-papiers.
clipboard.readRTF([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Retourne String - Le contenu presse-papiers en RTF.
const { clipboard } = require('electron')\n\nclipboard.writeRTF('{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nCeci est du texte {\\\\b bold}. \\par\\n}')\n\nconst rtf = clipboard.readRTF()\nconsole.log(rtf)\n// {\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nIl s'agit de quelques {\\\\b bold} text.\\\\par\\n\nclipboard.writeRTF(text[, type])text Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Écrit le text dans le presse-papiers en RTF.
const { clipboard } = require('electron')\n\nconst rtf = '{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nCeci est un peu {\\\\b bold} text.\\\\par\\n}'\nclipboard.writeRTF(rtf)\nclipboard.readBookmark() macOS WindowsRetourne Object:
title Stringurl StringRetourne un objet contenant les clés title et url représentant le marque-page du presse-papiers. La valeur des clés title et url sera une chaîne de caractères vide si le marque-page n'est pas disponible.
clipboard.writeBookmark(title, url[, type]) macOS Windowstitle Stringurl Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Écrit le title et url dans le presse-papiers comme marque-page.
Remarque : La plupart des applications sur Windows ne supportent pas le format marque-page, du coup vous pouvez utiliser clipboard.write pour écrire un marque-page et un texte de secours dans le presse-papiers.
const { clipboard } = require('electron')\n\nclipboard.writeBookmark({\n text: 'https://electronjs.org',\n signet: 'Page d'accueil Electron'\n})\nclipboard.readFindText() macOSRetourne Chaîne de caractères - Le texte sur le tableau de bord, qui est le presse-papier qui contient des informations sur l'état actuel du panneau de recherche de l'application active.
Cette méthode utilise un IPC synchronisé lorsqu'il est appelé depuis le processus de rendu. The cached value is reread from the find pasteboard whenever the application is activated.
\nclipboard.writeFindText(text) macOStext StringÉcrit le texte dans le presse-papier find (le presse-papier qui contient des informations sur l'état actuel du panneau de recherche de l'application active) en texte brut. Cette méthode utilise un IPC synchronisé lorsqu'il est appelé depuis le processus de rendu.
clipboard.clear([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Efface le contenu du presse-papiers.
\nclipboard.availableFormats([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Retourne String[] - Un tableau de format pris en charge pour le type du presse-papiers.
const { clipboard } = require('electron')\n\nformats const = clipboard.availableFormats()\nconsole.log(formats)\n// [ 'text/plain', 'text/html' ]\nclipboard.has(format[, type]) Experimentalformat Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Retourne Boolean - Si le presse-papiers prend en charge le format spécifié.
const { clipboard } = require('electron')\n\nconst hasFormat = clipboard.has('<p>selection</p>')\nconsole.log(hasFormat)\n// 'true' ou 'false'\nclipboard.read(format) Expérimentalformat StringRetourne String - Lit le type de format depuis le presse-papiers.
format should contain valid ASCII characters and have / separator. a/c, a/bc are valid formats while /abc, abc/, a/, /a, a are not valid.
clipboard.readBuffer(format) Expérimentalformat StringRetourne un Buffer - Lit le type de format depuis le presse-papiers.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('this is binary', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\n\nconst ret = clipboard.readBuffer('public/utf8-plain-text')\n\nconsole.log(buffer.equals(out))\n// true\nclipboard.writeBuffer(format, buffer[, type]) Experimentalformat Stringbuffer Buffertype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Écrit le buffer dans le presse-papiers comme format.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('writeBuffer', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\nclipboard.write(data[, type])datatext String (facultatif)html String (facultatif)image NativeImage (facultatif)rtf String (facultatif)marque-page String (facultatif) - Le titre de l'URL à text.type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection n'est disponible que sur Linux.Écrit data dans le presse-papiers.
const { clipboard } = require('electron')\n\npresse-papiers. rite({\n text: 'test',\n html: '<b>Hi</b>',\n rtf: '{\\\\rtf1\\\\utf8 text}',\n marque-page : 'un titre'\n})\n\nconsole. og(presse-papiers. eadText())\n// 'test'\n\nconsole.log(clipboard.readHTML())\n// <meta charset='utf-8'><b>Hi</b>\n\nconsole.log(clipboard.readRTF())\n// '{\\\\rtf1\\\\utf8 text}'\n\nconsole.log(clipboard.readBookmark())\n// { title: 'a title', url: 'test' }\nLa signature de code est une technologie de sécurité que vous utilisez pour certifier qu'une application a bien été créée par vous.
\nSur macOS le système peut détecter tout changement apporté à l'application, qu'il s'agisse d'une modification introduite accidentellement ou par du code malicieux.
\nSous Windows, le système assigne un niveau de confiance à votre certificat de signature de code, les utilisateurs seront avisés par des affichages de sécurité au démarrage de votre application si vous n'en possédez pas ou si votre niveau de confiance est faible . Le niveau de confiance s'établit au fil du temps, il est donc préférable de signer le code le plus tôt possible.
\nBien qu'il soit possible de distribuer des applications non signées, cela n'est pas recommandé. Windows et macOS empêcheront par défaut le téléchargement ou l'exécution d'applications non signées. À partir de macOS Catalina (version 10.15), les utilisateurs doivent passer par plusieurs étapes manuelles pour ouvrir des applications non signées.
\n
Comme vous pouvez le voir, les utilisateurs ont deux options : déplacez l'application directement dans la corbeille ou annulez son exécution. Vous ne voulez pas que vos utilisateurs voient cette boîte de dialogue.
\nSi vous développez une application Electron destinée à être empaquetée et distribuée, son code devra être signé.
\nUne bonne préparation des applications macOS pour la publication nécessite deux étapes : tout d'abord, l'application doit être signée. Then, the app needs to be uploaded to Apple for a process called \"notarization\", where automated systems will further verify that your app isn't doing anything to endanger its users.
\nPour démarrer le processus, assurez-vous que vous remplissez les conditions pour signer et certifier votre application :
\nL'écosystème d'Electron donne priorité à la configuration et a la liberté et bien sur donc il y a plusieurs moyens de signer et certifier votre application.
\nelectron-forgeSi vous utilisez l'outil de génération d'Electron vous devrez faire quelques ajouts à votre configuration pour signer et certifier votre application. Forge is a collection of the official Electron tools, using electron-packager, electron-osx-sign, and electron-notarize under the hood.
Regardons un exemple de configuration comportant tous les champs obligatoires. Not all of them are required: the tools will be clever enough to automatically find a suitable identity, for instance, but we recommend that you are explicit.
{\n \"name\": \"my-app\",\n \"version\": \"0.0.1\",\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"osxSign\": {\n \"identity\": \"Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)\",\n \"hardened-runtime\": true,\n \"entitlements\": \"entitlements.plist\",\n \"entitlements-inherit\": \"entitlements.plist\",\n \"signature-flags\": \"library\"\n },\n \"osxNotarize\": {\n \"appleId\": \"felix@felix.fun\",\n \"appleIdPassword\": \"my-apple-id-password\",\n }\n }\n }\n }\n}\nLe fichier plist référencé ici a besoin des habilitations spécifiques à macOS suivantes pour certifier aux mécanismes de sécurité d'Apple que votre application agit sans risque :
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nNote that up until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required as well. Cependant, il ne doit plus être utilisé s'il peut être évité.
Pour voir tout cela en action, consultez le code source d'Electron Fiddle, en particulier son fichier de configuration pour electron-forge .
Si vous prévoyez dans votre application d'accéder au microphone ou à la caméra à l'aide des API d'Electron, vous devrez également ajouter les droits suivants :
\n<key>com.apple.security.device.audio-input</key>\n<true/>\n<key>com.apple.security.device.camera</key>\n<true/>\nIf these are not present in your app's entitlements when you invoke, for example:
\nconst { systemPreferences } = require('electron')\n\nconst microphone = systemPreferences.askForMediaAccess('microphone')\nVotre application peut planter. See the Resource Access section in Hardened Runtime for more information and entitlements you may need.
\nelectron-builderElectron Builder comes with a custom solution for signing your application. You can find its documentation here.
\nelectron-packagerIf you're not using an integrated build pipeline like Forge or Builder, you are likely using electron-packager, which includes electron-osx-sign and electron-notarize.
Si vous utilisez l'API de Packager, vous pouvez fournit une configuration qui signera et certifiera votre application.
\nconst packager = require('electron-packager')\n\npackager({\n dir: '/path/to/my/app',\n osxSign: {\n identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',\n 'hardened-runtime': true,\n entitlements: 'entitlements.plist',\n 'entitlements-inherit': 'entitlements.plist',\n 'signature-flags': 'library'\n },\n osxNotarize: {\n appleId: 'felix@felix.fun',\n appleIdPassword: 'my-apple-id-password'\n }\n})\nLe fichier plist référencé ici a besoin des habilitations spécifiques à macOS suivantes pour certifier aux mécanismes de sécurité d'Apple que votre application agit sans risque :
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nUp until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required as well. Cependant, il ne doit plus être utilisé s'il peut être évité.
See the Mac App Store Guide.
\nAvant de signer les versions pour Windows, vous devez faire ce qui suit :
\nVous pouvez obtenir un certificat de signature de code auprès de nombreux revendeurs. Les prix varient, donc il peut valoir la peine que vous compariez. Popular resellers include:
\nIl existe un certain nombre d’outils pour la signature de votre application empaquetée :
\nelectron-winstaller génére un installateur pour Windowq et le signe pour vouselectron-forge peut signer les installateurs qu'il génère à travers des cibles Squirrel.Windows ou MSI.électron-builder peut signer certaines de ses cibles WindowsConsultez le Guide Windows Store.
", "title": "Signature de code", "description": "" }, "/docs/development/coding-style": { "locale": "fr-FR", "slug": "coding-style", "href": "/docs/development/coding-style", "crowdinFileId": "256147", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/coding-style.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Ce sont les règles de style pour coder dans Electron.
\nVous pouvez exécuter npm run lint pour montrer tous les problèmes de style détectés par cpplint et eslint.
path)ipc, app)@)path.join() pour concaténer les noms de fichiers.os.tmpdir() au lieu de /tmp lorsque vous devez référencer le répertoire temporaire.return when returning explicitly at the end of a function.return null, return undefined, null ou undefinedPour C++ et Python, nous suivons le Style de codage de Chromium. Vous pouvez utiliser clang-format pour formatter le code C++ automatiquement. Il y a aussi un script script/cpplint.py pour vérifier si tous les fichiers sont conformes.
La version de Python que nous utilisons est Python 2.7.
\nLe code C++ utilise beaucoup d’abstractions et de types de Chromium, il est donc recommandé de se familiariser avec eux. Un bon endroit pour commencer est : Abstractions Importantes et Structure des Données de Chromium. Le document mentionne certains types spéciaux, les types de portée limitées (qui libère automatiquement leur mémoire en allant hors de portée), mécanismes de journalisation etc.
\nVous pouvez exécuter npm run lint-docs pour vous assurer que vos modifications de documentation sont formatés correctement.
– au lieu de _, par exemple : fichier-name.js plutôt que file_name.js, parce que dans github/atome les noms de modules sont généralement sous la forme nom-du-module. Cette règle s’applique uniquement aux fichiers .js.const pour les exigences et d'autres constantes. Si la valeur est une primitive, utilisez un nom en majuscules (par ex. const NUMBER_OF_RETRIES = 5).let pour définir des variablesfunction () { }+L'API Electron utilise le même système de capitalisation que Node.js :
\nBrowserWindow, utilisez le PascalCase.globalShortcut, utilisez le camelCase.win.webContents, utilisez mixedCase.<webview>Tag ou Process Object.Lorsque vous créez une nouvelle API, il est préférable d’utiliser des getters et setters au lieu du style une-fonction de jQuery. Par exemple, .getText() et .setText(text) sont préférés aux .text([text]). Il y a une discussion là-dessus.
\n\nManipulate the command line arguments for your app that Chromium reads
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
L'exemple suivant montre comment vérifier si l'indicateur --disable-gpu est défini.
const { app } = require('electron')\napp.commandLine.hasSwitch('disable-gpu')\nFor more information on what kinds of flags and switches you can use, check out the Command Line Switches document.
\ncommandLine.appendSwitch(switch[, value])switch String - A command-line switch, without the leading --value String (optional) - A value for the given switchAppend a switch (with optional value) to Chromium's command line.
Note: Ceci n'affecte pas process.argv. The intended usage of this function is to control Chromium's behavior.
commandLine.appendArgument(value)value String - L'argument à ajouter à la ligne de commandeAppend an argument to Chromium's command line. The argument will be quoted correctly. Switches will precede arguments regardless of appending order.
\nIf you're appending an argument like --switch=value, consider using appendSwitch('switch', 'value') instead.
Note: Ceci n'affecte pas process.argv. The intended usage of this function is to control Chromium's behavior.
commandLine.hasSwitch(switch)switch String - A command-line switchReturns Boolean - Whether the command-line switch is present.
commandLine.getSwitchValue(switch)switch String - A command-line switchReturns String - The command-line switch value.
Note: When the switch is not present or has no value, it returns empty string.
", "title": "CommandLine", "description": "Manipulate the command line arguments for your app that Chromium reads" }, "/docs/api/command-line-switches": { "locale": "fr-FR", "slug": "command-line-switches", "href": "/docs/api/command-line-switches", "crowdinFileId": "256293", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/command-line-switches.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nParamètres de ligne de commande pris en charge par Electron.
\n
Vous pouvez utiliser app.commandLine.appendSwitch pour l'ajouter au script principal de votre application avant que l'événement ready du module app soit émis :
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('remote-debugging-port', '8315')\napp.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')\n\napp.whenReady().then(() => {\n // Your code here\n})\nurlUne liste de serveurs séparés par des virgules pour lesquels l'authentification intégrée est activée.
\nPar exemple :
\n--auth-server-whitelist='*example.com, *foobar.com, *baz'\npuis toute url finissant par example.com, foobar.com, baz se verra appliquer une authentification intégrée. Sans le préfixe * l'URL doit correspondre exactement.
urlA comma-separated list of servers for which delegation of user credentials is required. Sans le préfixe * l'URL doit correspondre exactement.
Disables NTLM v2 for posix platforms, no effect elsewhere.
\nDésactive le cache disque pour les requêtes HTTP.
\nDésactive les protocoles HTTP/2 et SPDY/3.1.
\nEmpêche Chromium d'abaisser la priorité des processus de rendu des pages invisibles.
\nCe commutateur est global à tous les processus de rendu, si vous voulez seulement désactiver l'ajustement d'une fenêtre, vous pouvez passer par la modification de playing silent audio.
\nsizeForce l'espace disque maximum à utiliser par le cache disque, en octets.
\nEnables caller stack logging for the following APIs (filtering events):
\ndesktopCapturer.getSources() / desktop-capturer-get-sourcesPrints Chromium's logging to stderr (or a log file).
\nThe ELECTRON_ENABLE_LOGGING environment variable has the same effect as passing --enable-logging.
Passing --enable-logging will result in logs being printed on stderr. Passing --enable-logging=file will result in logs being saved to the file specified by --log-file=..., or to electron_debug.log in the user-data directory if --log-file is not specified.
\n\nNote: On Windows, logs from child processes cannot be sent to stderr. Logging to a file is the most reliable way to collect logs on Windows.
\n
See also --log-file, --log-level, --v, and --vmodule.
trialsLes essais sur le terrain doivent être activés ou désactivés de force.
\nFor example: WebRTC-Audio-Red-For-Opus/Enabled/
rulesUne liste séparée par des virgules de rules qui contrôle comment les noms d'hôtes sont mappés.
Par exemple :
\nMAP * 127.0.0.1 Force tous les noms d'hôtes à être mappés à 127.0.0.1MAP *.google.com proxy Force tous les sous-domaines google.com à être résolus en \"proxy\".MAP test.com [::1]:77 Forces \"test.com\" to resolve to IPv6 loopback. Will also force the port of the resulting socket address to be 77.MAP * baz, EXCLUDE www.google.com Remappe tout à \"baz\", sauf pour \"www.google.com\".Ces mappages s'appliquent à l'hôte ciblé dans une requête réseau (le résolveur de connexion et d'hôte TCP dans une connexion directe, et l'hôte CONNECT dans une connexion avec proxy HTTP, et l'hôte du point terminal dans une connexion proxy SOCKS).
rulesComme --host-rules mais ces rules ne s'appliquent qu'au résolveur hôte.
Ignore les erreurs relatives au certificat.
\ndomainsIgnore la limite de connexion pour la liste de domains séparés par ,.
flagsSpecifies the flags passed to the Node.js engine. It has to be passed when starting Electron if you want to enable the flags in the main process.
$ electron --js-flags=\"--harmony_proxies --harmony_collections\" votre-app\nConsultez la documentation Node.js ou exécutez node --help dans votre terminal pour une liste des drapeaux disponibles. De plus, exécutez node --v8-options pour voir une liste de drapeaux qui se réfèrent spécifiquement au moteur JavaScript V8 de Node.js.
Permet de mettre une langue personnalisée.
\npathIf --enable-logging is specified, logs will be written to the given path. The parent directory must exist.
Setting the ELECTRON_LOG_FILE environment variable is equivalent to passing this flag. If both are present, the command-line switch takes precedence.
pathPermet que les événements réseau net log soient sauvés et les écrit dans path.
NSets the verbosity of logging when used together with --enable-logging. N should be one of Chrome's LogSeverities.
Note that two complimentary logging mechanisms in Chromium -- LOG() and VLOG() -- are controlled by different switches. --log-level controls LOG() messages, while --v and --vmodule control VLOG() messages. So you may want to use a combination of these three switches depending on the granularity you want and what logging calls are made by the code you're trying to watch.
See Chromium Logging source for more information on how LOG() and VLOG() interact. Loosely speaking, VLOG() can be thought of as sub-levels / per-module levels inside LOG(INFO) to control the firehose of LOG(INFO) data.
See also --enable-logging, --log-level, --v, and --vmodule.
N'utilisez pas de serveur proxy et établissez toujours des connexions directes. Overrides any other proxy server flags that are passed.
\nDésactive le bac à sable Chromium. Force le processus de rendu et les processus d'assistance Chromium à s'exécuter sans bac à sable. Ne doit être utilisé que pour les tests.
\nhostsInstructs Electron to bypass the proxy server for the given semi-colon-separated list of hosts. This flag has an effect only if used in tandem with --proxy-server.
Par exemple :
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')\nUtilise le serveur proxy pour tous les hôtes sauf les adresses locales (localhost, 127.0.0.1, etc.), les sous-domaines google.com, les hôtes qui contiennent le suffixe foo. com et tout ce qui est à 1.2.3.4:5678.
urlUtilise le script PAC à l'url spécifiée.
address:portUtilise le serveur proxy spécifié, qui remplace le paramètre système. Cet indicateur n'affecte que les requêtes avec le protocole HTTP, y compris les requêtes HTTPS et WebSocket. Il est également intéressant de noter que tous les serveurs proxy ne supportent pas les requêtes HTTPS et WebSocket. L'url du proxy ne supporte pas l'authentification par nom d'utilisateur et mot de passe selon un bug Chronium.
\nportActive le débogage distant via HTTP sur le port spécifié.
log_levelGives the default maximal active V-logging level; 0 is the default. Normally positive values are used for V-logging levels.
\nCe commutateur ne fonctionne que si --enable-logging est également fourni.
See also --enable-logging, --log-level, and --vmodule.
patternPermet que les niveaux maximum par module de V-logging puisse dépasser la valeur donnée par --v. Exemple : my_module=2,foo*=3 would change the logging level for all code in source files my_module.* and foo*.*.
Tout pattern contenant un slash ou un anti-slash sera testé pour tout le chemin et pas seulement le module. Exemple : */foo/bar/*=2 would change the logging level for all code in the source files under a foo/bar directory.
Ce commutateur ne fonctionne que si --enable-logging est également fourni.
See also --enable-logging, --log-level, and --v.
Force using discrete GPU when there are multiple GPUs available.
\nForce using integrated GPU when there are multiple GPUs available.
\nElectron prend en charge certains des drapeaux CLI pris en charge par Node.js.
\nRemarque : Le passage d'options de ligne de commande non supportées n'aura aucun effet lorsque Electron ne s'exécute pas en mode ELECTRON_RUN_AS_NODE.
Activate inspector on host:port and break at start of user script. Configuration par défaut pour host:port 127.0.0.1:9229.
\nAliased to --debug-brk=[host:]port.
Set the host:port to be used when the inspector is activated. Utile lors de l’activation de l’inspecteur en envoyant le signal SIGUSR1. L'hôte par défaut est 127.0.0.1.
Aliased to --debug-port=[host:]port.
Activate inspector on host:port. Par défaut la valeur est 127.0.0.1:9229.
V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug and profile Electron instances. The tools attach to Electron instances via a TCP port and communicate using the Chrome DevTools Protocol.
\nSee the Debugging the Main Process guide for more details.
\nAliased to --debug[=[host:]port.
Specify ways of the inspector web socket url exposure.
\nPar défaut, l'url du websocket de l'inspecteur est disponible dans stderr et dans /json/list endpoint sur http://host:port/json/list.
", "title": "Commandes Supportées", "description": "Paramètres de ligne de commande pris en charge par Electron." }, "/docs/api/content-tracing": { "locale": "fr-FR", "slug": "content-tracing", "href": "/docs/api/content-tracing", "crowdinFileId": "256297", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/content-tracing.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCollecter des données de traçage de Chromium pour trouver des goulets d'étranglement de performance et des opérations lentes.
\n
Processus : Main
\nCe module n'inclut pas d'interface web. Pour afficher les traces enregistrées, utilisez visionneuse de traces, disponible sur chrome://tracing dans Chrome.
Remarque : Vous ne devriez pas utiliser ce module tant que l'événement ready du module de l'application n'est pas émis.
const { app, contentTracing } = require('electron')\n\napp.whenReady().then(() => {\n (async () => {\n await contentTracing.startRecording({\n included_categories: ['*']\n })\n console.log('Tracing started')\n await new Promise(resolve => setTimeout(resolve, 5000))\n const path = await contentTracing.stopRecording()\n console.log('Tracing data recorded to ' + path)\n })()\n})\nLe module contentTracing a les méthodes suivantes :
contentTracing.getCategories()Retourne Promise<String[]> - résout avec un tableau de groupes de catégories une fois que tous les processus enfants ont reconnu la requête getCategories
Obtenir un ensemble de groupes de catégories. Les groupes de catégories peuvent changer lorsque de nouveaux chemins de code sont atteints. Voir aussi la liste des catégories de traçage intégrées.
\n\n\nNOTE: Electron adds a non-default tracing category called
\n\"electron\". This category can be used to capture Electron-specific tracing events.
contentTracing.startRecording(options)options (TraceConfig | TraceCategoriesAndOptions)Retourne Promise<void> - résolu une fois que tous les processus enfants ont reconnu la requête startRecording.
Commencez à enregistrer sur tous les processus.
\nL'enregistrement commence immédiatement localement et de manière asynchrone sur les processus enfants dès qu'il reçoit la demande EnableRecording.
\nSi un enregistrement est déjà en cours, la promesse sera immédiatement résolue, car seule une opération de trace peut être en cours à la fois.
\ncontentTracing.stopRecording([resultFilePath])resultFilePath String (facultatif)Retourne Promise<String> - résout avec un chemin vers un fichier qui contient les données tracées une fois que tous les processus enfants ont reconnu la requête stopRecording
Arrêter l'enregistrement sur tous les processus.
\nLes processus fils mettent généralement en cache les données de trace et ne suppriment que rarement et envoient données de trace au processus principal. Cela aide à minimiser les frais d'exécution de traçage puisque l'envoi de données de traces via IPC peut être une opération coûteuse. Ainsi, pour terminer le traçage, Chromium demande asynchrone à tous les processus enfants de vider les données de traces en attente.
\nLes données de trace seront écrites dans resultFilePath. Si resultFilePath est vide ou non fourni, les données de trace seront écrites dans un fichier temporaire, et le chemin sera retourné dans la promesse.
contentTracing.getTraceBufferUsage()Retourne Promise<Object> - Résolution avec un objet contenant la valeur et pourcentage d'utilisation maximale du tampon de trace
value Numberpercentage NumberRécupère l'utilisation maximale sur les processus de mémoire tampon trace en pourcentage de l'état complet de .
", "title": "contentTracing", "description": "Collecter des données de traçage de Chromium pour trouver des goulets d'étranglement de performance et des opérations lentes." }, "/docs/api/context-bridge": { "locale": "fr-FR", "slug": "context-bridge", "href": "/docs/api/context-bridge", "crowdinFileId": "256299", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/context-bridge.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCrée un pont synchrone sécurisé, bidirectionnel entre des contextes isolés
\n
Processus : Renderer
\nExemple d’une API exposée à un rendu à partir d’un script de preload:
\n// Preload (Isolated World)\nconst { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing')\n }\n)\n// Renderer (Main World)\n\nwindow.electron.doThing()\n« Main World » est le contexte JavaScript dans lequel votre code de rendu principal s'exécute. Par défaut, la page que vous chargez dans votre moteur de rendu exécute son code dans cet univers.
\nVotre script preload s'exécute dans un \"Isolated World\" lorsque contextIsolation est activé dans votre webPreferences (ce qui est le comportement par défaut depuis Electron 12.0.0). Vous pourrez en savoir plus sur l'isolement du contexte et ce qu'il affecte dans la partie sécurité de la documentation. .
Le module contextBridge possède les méthodes suivantes :
contextBridge.exposeInMainWorld(apiKey, api)apiKey String - La clé à utiliser pour injecter l'API dans fenêtre. L’API sera accessible par window[apiKey].api any- Votre API, plus d'informations sur ce que peut être cette API et son fonctionnement est disponible ci-dessous.L' api fourni à exposeInMainWorld peut être du type Function, String, Number, Array, Boolean ou un objet dont les clés sont des chaînes de caractères et les valeurs du type Function, String, Number, Array, Boolean ou un autre objet imbriqué qui remplit les mêmes conditions.
Function values are proxied to the other context and all other values are copied and frozen. Toutes les données ou primitives envoyées par l'API deviennent immuables et les mises à jour de chaque côté du pont de connexion ne donnent pas lieu à une mise à jour de l'autre côté.
Exemple d’API complexe:
\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing'),\n myPromises: [Promise.resolve(), Promise.reject(new Error('whoops'))],\n anAsyncFunction: async () => 123,\n data: {\n myFlags: ['a', 'b', 'c'],\n bootTime: 1234\n },\n nestedAPI: {\n evenDeeper: {\n youCanDoThisAsMuchAsYouWant: {\n fn: () => ({\n returnData: 123\n })\n }\n }\n }\n }\n)\nLes valeurs Function que vous liez à travers le contextBridge sont servies par l'intermédiaire d'Electron pour s'assurer que les contextes restent isolés. Ceci entraîne certaines limitations clés décrites ci-dessous.
Étant donné que les paramètres, erreurs et valeurs de retour sont copiés lors de leur transmission par le pont, seuls certains types peuvent être utilisés. Mais si le type que vous voulez utiliser peut être sérialisé et désérialisé dans le même objet cela fonctionnera. Une table des types supportés est incluse en complément:
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Type | Complexité | Parameter Support | Return Value Support | Limitations |
|---|---|---|---|---|
String | Simple | ✅ | ✅ | N/A |
Number | Simple | ✅ | ✅ | N/A |
Boolean | Simple | ✅ | ✅ | N/A |
Objet | Complexe | ✅ | ✅ | Keys must be supported using only \"Simple\" types in this table. Values must be supported in this table. Prototype modifications are dropped. Sending custom classes will copy values but not the prototype. |
Array | Complexe | ✅ | ✅ | Same limitations as the Object type |
Erreur | Complexe | ✅ | ✅ | Errors that are thrown are also copied, this can result in the message and stack trace of the error changing slightly due to being thrown in a different context |
Promise | Complexe | ✅ | ✅ | Promises are only proxied if they are the return value or exact parameter. Promises nested in arrays or objects will be dropped. |
Function | Complexe | ✅ | ✅ | Prototype modifications are dropped. Sending classes or constructors will not work. |
| Cloneable Types | Simple | ✅ | ✅ | See the linked document on cloneable types |
Élément | Complexe | ✅ | ✅ | Prototype modifications are dropped. L'envoi d'éléments personnalisés ne fonctionnera pas. |
Objet blob | Complexe | ✅ | ✅ | N/A |
Symbole | N/A | ❌ | ❌ | Symbols cannot be copied across contexts so they are dropped |
If the type you care about is not in the above table, it is probably not supported.
\nThe contextBridge can be used by the preload script to give your renderer access to Node APIs. The table of supported types described above also applies to Node APIs that you expose through contextBridge. Please note that many Node APIs grant access to local system resources. Be very cautious about which globals and APIs you expose to untrusted remote content.
const { contextBridge } = require('electron')\nconst crypto = require('crypto')\ncontextBridge.exposeInMainWorld('nodeCrypto', {\n sha256sum (data) {\n const hash = crypto.createHash('sha256')\n hash.update(data)\n return hash.digest('hex')\n }\n})\nL'isolement du contexte est une fonctionnalité qui garantit l'exécution dans des contextes différents de vos scripts preload avec la logique interne d'Electron et du site Web que vous chargez dans un webContents. Ceci est important pour des raisons de sécurité car cela empêcher le site Web d'accéder aux fonctionalités d'Electron ou aux API puissantes auxquelles votre script preload accède.
Cela signifie que l'objet window auquel votre script de préchargement a accès est un objet différent de celui auquel que le site Web a accès. For example, if you set window.hello = 'wave' in your preload script and context isolation is enabled, window.hello will be undefined if the website tries to access it.
Context isolation has been enabled by default since Electron 12, and it is a recommended security setting for all applications.
\n\n\nWithout context isolation, I used to provide APIs from my preload script using
\nwindow.X = apiObject. Now what?
Exposing APIs from your preload script to a loaded website in the renderer process is a common use-case. With context isolation disabled, your preload script would share a common global window object with the renderer. You could then attach arbitrary properties to a preload script:
// preload with contextIsolation disabled\nwindow.myAPI = {\n doAThing: () => {}\n}\nThe doAThing() function could then be used directly in the renderer process:
// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nThere is a dedicated module in Electron to help you do this in a painless way. The contextBridge module can be used to safely expose APIs from your preload script's isolated context to the context the website is running in. L'API sera également accessible depuis le site web sur window.myAPI comme avant.
// preload with contextIsolation enabled\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n doAThing: () => {}\n})\n// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nPlease read the contextBridge documentation linked above to fully understand its limitations. For instance, you can't send custom prototypes or symbols over the bridge.
L'activation de contextIsolation et l'utilisation de contextBridge ne signifie pas automatiquement que tout ce que vous faites est sûr. For instance, this code is unsafe.
// ❌ Bad code\ncontextBridge.exposeInMainWorld('myAPI', {\n send: ipcRenderer.send\n})\nIt directly exposes a powerful API without any kind of argument filtering. This would allow any website to send arbitrary IPC messages, which you do not want to be possible. The correct way to expose IPC-based APIs would instead be to provide one method per IPC message.
\n// ✅ Good code\ncontextBridge.exposeInMainWorld('myAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nIf you're building your Electron app with TypeScript, you'll want to add types to your APIs exposed over the context bridge. The renderer's window object won't have the correct typings unless you extend the types with a declaration file.
For example, given this preload.ts script:
contextBridge.exposeInMainWorld('electronAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nYou can create a renderer.d.ts declaration file and globally augment the Window interface:
export interface IElectronAPI {\n loadPreferences: () => Promise<void>,\n}\n\ndeclare global {\n interface Window {\n electronAPI: IElectronAPI\n }\n}\nDoing so will ensure that the TypeScript compiler will know about the electronAPI property on your global window object when writing scripts in your renderer process:
window.electronAPI.loadPreferences()\nname String - The name of the cookie.value String - The value of the cookie.domain String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains.hostOnly Boolean (optional) - Whether the cookie is a host-only cookie; this will only be true if no domain was passed.path String (optional) - The path of the cookie.secure Boolean (optional) - Whether the cookie is marked as secure.httpOnly Boolean (optional) - Whether the cookie is marked as HTTP only.session Boolean (optional) - Whether the cookie is a session cookie or a persistent cookie with an expiration date.expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.sameSite String - The Same Site policy applied to this cookie. Can be unspecified, no_restriction, lax or strict.\n\nInterroger et modifier la session des cookies.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Les instances de la classe Cookies sont accessibles à l'aide de la propriété cookies d'une Session.
Par exemple :
\nconst { session } = require('electron')\n\n// Récupère tous les cookies.\nsession.defaultSession.cookies.get({})\n .then((cookies) => {\n console.log(cookies)\n }). atch((error) => {\n console.log(error)\n })\n\n// Interroge tous les cookies associés à une Url spécifique.\nsession.defaultSession.cookies.get({ url: 'http://www.github.com' })\n .then((cookies) => {\n console.log(cookies)\n }). atch((erreur) => {\n console. og(error)\n })\n\n// Définit un cookie avec les données de cookie spécifiées;\n// peut écraser les cookies équivalents s'ils existent.\nconst cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }\nsession.defaultSession.cookies.set(cookie)\n . hen(() => {\n // succès\n }, (erreur) => {\n console. rror(erreur)\n})\nLes événements suivants sont disponibles pour les instances de Cookies :
Retourne :
\nevent Eventcookie Cookie - Le cookie qui a été changé.cause String - The cause of the change with one of the following values:explicit - Le cookie a été modifié directement par l'action du consommateur.overwrite - Le cookie a été supprimé automatiquement a cause d'une insertion écrasante.expired - Le cookie a été supprimé automatiquement par expiration.evicted - Le cookie a été expulsée automatiquement par le ramasse-miettes.expired-overwrite - Le cookie a été écrasé avec une date d'expiration dépassée.removed Boolean - true si le cookie a été supprimé, false autrement.Émis lorsqu’un cookie a été changé car il a été ajouté, édité, enlevé ou a expiré.
\nLes méthodes suivants sont disponibles pour les instances de Cookies :
cookies.get(filter)filterurl String (optional) - Retrieves cookies which are associated with url. Empty implies retrieving cookies of all URLs.name String (facultatif) - Filtre les cookies par nom.domain String (facultatif) - Récupère les cookies dont les domaines correspondent ou sont des sous-domaines de domains.path String (facultatif) - Récupère les cookies dont le chemin correspond à path.secure Boolean (facultatif) - Filtre les cookies par leur propriété de sécuritée.session Boolean (facultatif) - filtre les session ou les cookies persistants.Retourne Promise<Cookie[]> - Une promesse qui résout un tableau d'objets de cookies.
Envoie une demande pour obtenir tous les cookies correspondant à filter, et résout une promesse avec la réponse.
cookies.set(détails)detailsurl String - The URL to associate the cookie with. The promise will be rejected if the URL is invalid.name String (optional) - The name of the cookie. Empty by default if omitted.value String (optional) - The value of the cookie. Empty by default if omitted.domain String (facultatif) - Le nom de domaine du cookie; ce dernier sera normalisé par un point le précédent pour qu'il soit valide pour les sous-domaines. Empty by default if omitted.path String (facultatif) - Le chemin du cookie. Empty by default if omitted.secure Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to false unless Same Site=None attribute is used.httpOnly Boolean (optional) - Whether the cookie should be marked as HTTP only. Par défaut, faux.expirationDate Double (facultatif) - La date d'expiration du cookie en nombre de secondes depuis l'epoch UNIX. Si omis, le cookie devient alors un cookie de session et ne sera pas conservé entre deux sessions.sameSite String (optional) - The Same Site policy to apply to this cookie. Peut être unspecified, no_restriction, lax ou strict. Par défaut la valeur est no_restriction.Retourne Promise<void> - Une promesse qui résout lorsque le cookie a été défini
Définit un cookie avec détails.
cookies.remove(url, nom)url String - L'url associée au cookie.name String - Le nom du cookie à supprimer.Retourne Promise<void> - Une promesse qui résout lorsque le cookie a été supprimé
Supprime les cookies correspondant à url et name
cookies.flushStore()Retourne Promise<void> - Une promesse qui résout lorsque la boutique de cookies a été vidée
Écrit toutes les données des cookies non écrites sur le disque.
", "title": "Classe : Cookies", "description": "Interroger et modifier la session des cookies." }, "/docs/api/structures/cpu-usage": { "locale": "fr-FR", "slug": "cpu-usage", "href": "/docs/api/structures/cpu-usage", "crowdinFileId": "256419", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/cpu-usage.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "percentCPUUsage Number - Percentage of CPU used since the last call to getCPUUsage. First call returns 0.idleWakeupsPerSecond Number - The number of average idle CPU wakeups per second since the last call to getCPUUsage. First call returns 0. Will always return 0 on Windows.date Dateid String\n\n\nSoumet un rapport de plantage à un serveur distant.
\n
The following is an example of setting up Electron to automatically submit crash reports to a remote server:
\nconst { crashReporter } = require('electron')\n\ncrashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })\nPour configurer un serveur pour accepter et traiter les rapports de plantage, vous pouvez utiliser les projets suivants :
\n\nOu utilisez une solution hébergée par un tiers :
\nCrash reports are stored temporarily before being uploaded in a directory underneath the app's user data directory (called 'Crashpad' on Windows and Mac, or 'Crash Reports' on Linux). You can override this directory by calling app.setPath('crashDumps', '/path/to/crashes') before starting the crash reporter.
On Windows and macOS, Electron uses crashpad to monitor and report crashes. Sous Linux, Electron utilise breakpad. This is an implementation detail driven by Chromium, and it may change in future. In particular, crashpad is newer and will likely eventually replace breakpad on all platforms.
\nIf you are using the Node.js child_process module and want to report crashes from those processes on Linux, there is an extra step you will need to take to properly initialize the crash reporter in the child process. This is not necessary on Mac or Windows, as those platforms use Crashpad, which automatically monitors child processes.
Since require('electron') is not available in Node child processes, the following APIs are available on the process object in Node child processes. Note that, on Linux, each Node child process has its own separate instance of the breakpad crash reporter. This is dissimilar to renderer child processes, which have a \"stub\" breakpad reporter which returns information to the main process for reporting.
process.crashReporter.start(options)process.crashReporter.getParameters()See crashReporter.getParameters().
process.crashReporter.addExtraParameter(key, value)See crashReporter.addExtraParameter(key, value).
process.crashReporter.removeExtraParameter(key)See crashReporter.removeExtraParameter(key).
Le module crashReporter dispose des méthodes suivantes :
crashReporter.start(options)optionssubmitURL String (optional) - URL that crash reports will be sent to as POST. Required unless uploadToServer is false.productName String (facultatif) - app.name.companyName String (optional) Deprecated - Deprecated alias for { globalExtra: { _companyName: ... } }.uploadToServer Boolean (optional) - Whether crash reports should be sent to the server. If false, crash reports will be collected and stored in the crashes directory, but not uploaded. La valeur par défaut est vraie.ignoreSystemCrashHandler Boolean (optional) - If true, crashes generated in the main process will not be forwarded to the system crash handler. Par défaut la valeur est false.rateLimit Boolean (optional) macOS Windows - If true, limit the number of crashes uploaded to 1/hour. Par défaut la valeur est false.compress Boolean (optional) - If true, crash reports will be compressed and uploaded with Content-Encoding: gzip. La valeur par défaut est vraie.extra Record<String, String> (optional) - Extra string key/value annotations that will be sent along with crash reports that are generated in the main process. Only string values are supported. Crashes generated in child processes will not contain these extra parameters to crash reports generated from child processes, call addExtraParameter from the child process.globalExtra Record<String, String> (optional) - Extra string key/value annotations that will be sent along with any crash reports generated in any process. These annotations cannot be changed once the crash reporter has been started. If a key is present in both the global extra parameters and the process-specific extra parameters, then the global one will take precedence. By default, productName and the app version are included, as well as the Electron version.This method must be called before using any other crashReporter APIs. Once initialized this way, the crashpad handler collects crashes from all subsequently created processes. The crash reporter cannot be disabled once started.
This method should be called as early as possible in app startup, preferably before app.on('ready'). If the crash reporter is not initialized at the time a renderer process is created, then that renderer process will not be monitored by the crash reporter.
Note: You can test out the crash reporter by generating a crash using process.crash().
Note: If you need to send additional/updated extra parameters after your first call start you can call addExtraParameter.
Note: Parameters passed in extra, globalExtra or set with addExtraParameter have limits on the length of the keys and values. Key names must be at most 39 bytes long, and values must be no longer than 127 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated.
Note: This method is only available in the main process.
\ncrashReporter.getLastCrashReport()Returns CrashReport - The date and ID of the last crash report. Only crash reports that have been uploaded will be returned; even if a crash report is present on disk it will not be returned until it is uploaded. Dans le cas où il n'y a pas de rapports téléchargés, null est retourné.
Note: This method is only available in the main process.
\ncrashReporter.getUploadedReports()Retourne CrashReport[] :
Returns all uploaded crash reports. Each report contains the date and uploaded ID.
\nNote: This method is only available in the main process.
\ncrashReporter.getUploadToServer()Returns Boolean - Whether reports should be submitted to the server. Set through the start method or setUploadToServer.
Note: This method is only available in the main process.
\ncrashReporter.setUploadToServer(uploadToServer)uploadToServer Boolean - Whether reports should be submitted to the server.This would normally be controlled by user preferences. This has no effect if called before start is called.
Note: This method is only available in the main process.
\ncrashReporter.addExtraParameter(key, value)key String - Parameter key, must be no longer than 39 bytes.value String - Parameter value, must be no longer than 127 bytes.Définit un paramètre supplémentaire à envoyer avec le rapport de plantage. The values specified here will be sent in addition to any values set via the extra option when start was called.
Parameters added in this fashion (or via the extra parameter to crashReporter.start) are specific to the calling process. Adding extra parameters in the main process will not cause those parameters to be sent along with crashes from renderer or other child processes. Similarly, adding extra parameters in a renderer process will not result in those parameters being sent with crashes that occur in other renderer processes or in the main process.
Note: Parameters have limits on the length of the keys and values. Key names must be no longer than 39 bytes, and values must be no longer than 20320 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated.
\nNote: On linux values that are longer than 127 bytes will be chunked into multiple keys, each 127 bytes in length. Exemple : addExtraParameter('foo', 'a'.repeat(130)) will result in two chunked keys foo__1 and foo__2, the first will contain the first 127 bytes and the second will contain the remaining 3 bytes. On your crash reporting backend you should stitch together keys in this format.
crashReporter.removeExtraParameter(key)key String - Parameter key, must be no longer than 39 bytes.Remove an extra parameter from the current set of parameters. Future crashes will not include this parameter.
\ncrashReporter.getParameters()Returns Record<String, String> - The current 'extra' parameters of the crash reporter.
Le rapporteur de plantage enverra les données suivantes à submitURL comme un POST en multipart/form-data :
ver String - La version d'Electron.platform String - Par exemple 'win32'.process_type String - Par exemple 'renderer'.guid String - Par exemple '5e1286fc-da97-479e-918b-6bfb0c3d1c72'._version String - La version dans package.json._productName String - Le nom du produit dans l'objet options de crashReporter.prod String - Name of the underlying product. In this case Electron._companyName String - Le nom de l'entreprise dans l'objet options de crashReporter.upload_file_minidump File - Le rapport d'incident dans le format minidump.extra dans l'objet options de crashReporter.scheme String - Custom schemes to be registered with options.privileges Object (optional)standard Boolean (optional) - Default false.secure Boolean (optional) - Default false.bypassCSP Boolean (optional) - Default false.allowServiceWorkers Boolean (optional) - Default false.supportFetchAPI Boolean (optional) - Default false.corsEnabled Boolean (optional) - Default false.stream Boolean (optional) - Default false.\"Native interfaces\" include the file picker, window border, dialogs, context menus, and more - anything where the UI comes from your operating system and not from your app. The default behavior is to opt into this automatic theming from the OS.
\nIf your app has its own dark mode, you should toggle it on and off in sync with the system's dark mode setting. You can do this by using the [prefer-color-scheme] CSS media query.
\nIf you want to manually switch between light/dark modes, you can do this by setting the desired mode in the themeSource property of the nativeTheme module. This property's value will be propagated to your Renderer process. Any CSS rules related to prefers-color-scheme will be updated accordingly.
In macOS 10.14 Mojave, Apple introduced a new system-wide dark mode for all macOS computers. If your Electron app has a dark mode, you can make it follow the system-wide dark mode setting using the nativeTheme api.
In macOS 10.15 Catalina, Apple introduced a new \"automatic\" dark mode option for all macOS computers. In order for the nativeTheme.shouldUseDarkColors and Tray APIs to work correctly in this mode on Catalina, you need to use Electron >=7.0.0, or set NSRequiresAquaSystemAppearance to false in your Info.plist file for older versions. Electron Packager et Electron Forge ont une option darwinDarkModeSupport pour automatiser les infos Info.plist modifications pendant la compilation de l'application.
If you wish to opt-out while using Electron > 8.0.0, you must set the NSRequiresAquaSystemAppearance key in the Info.plist file to true. Please note that Electron 8.0.0 and above will not let you opt-out of this theming, due to the use of the macOS 10.14 SDK.
This example demonstrates an Electron application that derives its theme colors from the nativeTheme. Additionally, it provides theme toggle and reset controls using IPC channels.
Starting with the index.html file:
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n <link rel=\"stylesheet\" type=\"text/css\" href=\"./styles.css\">\n</head>\n<body>\n <h1>Hello World!</h1>\n <p>Current theme source: <strong id=\"theme-source\">System</strong></p>\n\n <button id=\"toggle-dark-mode\">Toggle Dark Mode</button>\n <button id=\"reset-to-system\">Reset to System Theme</button>\n\n <script src=\"renderer.js\"></script>\n </body>\n</body>\n</html>\nEt le fichier styles.css:
@media (prefers-color-scheme: dark) {\n body { background: #333; color: white; }\n}\n\n@media (prefers-color-scheme: light) {\n body { background: #ddd; color: black; }\n}\nL'exemple produit une page HTML avec quelques éléments. The <strong id=\"theme-source\"> element shows which theme is currently selected, and the two <button> elements are the controls. The CSS file uses the prefers-color-scheme media query to set the <body> element background and text colors.
The preload.js script adds a new API to the window object called darkMode. This API exposes two IPC channels to the renderer process, 'dark-mode:toggle' and 'dark-mode:system'. It also assigns two methods, toggle and system, which pass messages from the renderer to the main process.
const { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld('darkMode', {\n toggle: () => ipcRenderer.invoke('dark-mode:toggle'),\n system: () => ipcRenderer.invoke('dark-mode:system')\n})\nNow the renderer process can communicate with the main process securely and perform the necessary mutations to the nativeTheme object.
The renderer.js file is responsible for controlling the <button> functionality.
document.getElementById('toggle-dark-mode').addEventListener('click', async () => {\n const isDarkMode = await window.darkMode.toggle()\n document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'\n})\n\ndocument.getElementById('reset-to-system').addEventListener('click', async () => {\n await window.darkMode.system()\n document.getElementById('theme-source').innerHTML = 'System'\n})\nUsing addEventListener, the renderer.js file adds 'click' event listeners to each button element. Each event listener handler makes calls to the respective window.darkMode API methods.
Finally, the main.js file represents the main process and contains the actual nativeTheme API.
const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n\n ipcMain.handle('dark-mode:toggle', () => {\n if (nativeTheme.shouldUseDarkColors) {\n nativeTheme.themeSource = 'light'\n } else {\n nativeTheme.themeSource = 'dark'\n }\n return nativeTheme.shouldUseDarkColors\n })\n\n ipcMain.handle('dark-mode:system', () => {\n nativeTheme.themeSource = 'system'\n })\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate' , () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nThe ipcMain.handle methods are how the main process responds to the click events from the buttons on the HTML page.
The 'dark-mode:toggle' IPC channel handler method checks the shouldUseDarkColors boolean property, sets the corresponding themeSource, and then returns the current shouldUseDarkColors property. Looking back on the renderer process event listener for this IPC channel, the return value from this handler is utilized to assign the correct text to the <strong id='theme-source'> element.
The 'dark-mode:system' IPC channel handler method assigns the string 'system' to the themeSource and returns nothing. This also corresponds with the relative renderer process event listener as the method is awaited with no return value expected.
Run the example using Electron Fiddle and then click the \"Toggle Dark Mode\" button; the app should start alternating between a light and dark background color.
\n
Si vous rencontrez des crash ou des problèmes dans Electron et que vous croyez qu'il ne viennent pas de votre app JavaScript, mais plutôt d'Electron lui-même, alors le débogage peut être un peu difficile, surtout pour les développeurs peu expérimentés pour le débogage natif/C++. However, using Visual Studio, Electron's hosted Symbol Server, and the Electron source code, you can enable step-through debugging with breakpoints inside Electron's source code.
\nVoir aussi : Il y a une richesse d'information sur le débogage de Chronium, la plupart s'appliquant aussi pour Electron, sur le site developpeur de Chronium : Debugging Chromium on Windows.
\nUn debug build d'Electron : le moyen le plus simple est généralement de le compiler vous-même, en utilisant les outils et prérequis énumérées dans les instructions de compilation pour Windows. Tandis que vous pouvez facilement déboguer Electron puisque vous pouvez le télécharger directement, vous trouverez qu’il est fortement optimisé, ce qui rend le débogage sensiblement plus difficile : le débogueur ne sera pas en mesure de vous montrer le contenu de toutes les variables et le chemin d’exécution peut sembler étrange à cause de l’inlining, liste des appels qui s’enchaînent et d'autres optimisations du compilateur.
\nOutils Visual Studio C++ : les éditions de la communauté gratuite de Visual Studio 2013 et Visual Studio 2015 fonctionnent tous les deux. Once installed, configure Visual Studio to use Electron's Symbol server. Il permettra à Visual Studio d’acquérir une meilleure compréhension de ce qui se passe à l’intérieur d'Electron, rendant plus facile l'affichage des variables dans un format lisible par l’homme.
\nProcMon : l'outil gratuit de SysInternals vous permet d’inspecter un paramètres de processus, gère les fichiers et les opérations de registre.
\nPour démarrer une session de débogage, ouvrez PowerShell/CMD et exécutez votre version debug d'Electron, utilisant votre application comme paramètre.
\n$ ./out/Testing/electron.exe ~/my-electron-app/\nVous pouvez ouvrir Visual Studio. Electron n’est pas compilé avec Visual Studio et par conséquent ne contient pas de fichier de projet - vous pouvez cependant ouvrir les fichiers de code source « Comme fichier », ce qui signifie que Visual Studio va les ouvrir par eux-mêmes. Vous pouvez quand même définir des points d’arrêt - Visual Studio cherchera automatiquement le code source correspond au code qui s’exécute dans le processus attaché et le stopper en conséquence.
\nLes fichiers de code pertinents peuvent être trouvés dans ./shell/.
Vous pouvez attacher le débogueur Visual Studio à un processus en cours d’exécution sur un ordinateur local ou distant. Lorsque le processus est en cours d’exécution, cliquez sur déboguer/attacher au processus (ou appuyez sur CTRL+ALT+P) pour ouvrir la boîte de dialogue « Attacher au processus ». Vous pouvez utiliser cette fonctionnalité pour déboguer des applications qui s'exécutent sur un ordinateur local ou distant, déboguer plusieurs processus simultanément.
Si Electron s’exécute sous un compte d’utilisateur différent, sélectionnez la case afficher les processus de tous les utilisateurs. Notez que selon le nombre de BrowserWindows ouvert de votre application, vous verrez plusieurs processus. Une application typique avec une seule fenêtre se traduira dans Visual Studio par présenter juste deux entrées d'Electron.exe - l'un pour le processus principal et l’autre pour le processus de rendu. Étant donné que la liste vous donne seulement des noms, il n’y a actuellement aucun moyen fiable de savoir qui est qui.
Le code exécuté dans le processus principal (qui est le code se trouvant ou est lancé par votre fichier JavaScript main) s'exécutera à l’intérieur du processus principal, tandis que les autres morceaux de code s’exécuteront à l’intérieur de leur processus de rendu respectif.
\nVous pouvez être attaché à plusieurs programmes lorsque vous déboguez, mais un seul programme est actif dans le débogueur à tout moment. Vous pouvez configurer le programme actif dans la barre d’outils Emplacement de débogage ou de la fenêtre de processus.
Alors que Visual Studio est fantastique pour l’inspection de code spécifiques, la force de ProcMon est vraiment dans l'observation de tout ce que fait votre application avec le système d’exploitation - il capture les fichiers, registre, réseau, processus et fait un profilage des processus. Il tente de logguer tous les événements qui se produisent et peut être assez écrasant, mais si vous cherchez à comprendre pourquoi et comment votre application fonctionne avec le système d’exploitation, il peut être une ressource précieuse.
\nPour une introduction aux fonctionnalités de débogage de base et avancées de ProcMon, allez voir ce tutoriel vidéo fourni par Microsoft.
", "title": "Débogage sur Windows", "description": "" }, "/docs/api/debugger": { "locale": "fr-FR", "slug": "debugger", "href": "/docs/api/debugger", "crowdinFileId": "256305", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/debugger.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nUn transport alternatif pour le protocole de débogage distant de Chrome.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Chrome Developer Tools possède une liaison spéciale disponible à l'exécutable JavaScript qui permet d'interagir avec les pages et de les instrumentaliser.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\ntry {\n win.webContents.debugger.attach('1.1')\n} catch (err) {\n console.log('Debugger attach failed : ', err)\n}\n\nwin.webContents.debugger.on('detach', (event, reason) => {\n console.log('Debugger detached due to : ', reason)\n})\n\nwin.webContents.debugger.on('message', (event, method, params) => {\n if (method === 'Network.requestWillBeSent') {\n if (params.request.url === 'https://www.github.com') {\n win.webContents.debugger.detach()\n }\n }\n})\n\nwin.webContents.debugger.sendCommand('Network.enable')\nRetourne :
\nevent Eventreason String - Motif du retrait du débogueur.Emitted when the debugging session is terminated. This happens either when webContents is closed or devtools is invoked for the attached webContents.
Retourne :
\nevent Eventmethod String - Nom de la méthode.params any - Event parameters defined by the 'parameters' attribute in the remote debugging protocol.sessionId String - Unique identifier of attached debugging session, will match the value sent from debugger.sendCommand.Émis chaque fois que la cible de débogage émet un événement d'instrumentation.
\ndebugger.attach([protocolVersion])protocolVersion String (facultatif) - Version de protocole de débogage demandée.Attache le débogueur au webContents.
debugger.isAttached()Retourne Boolean - Si un débogueur est attaché au webContents.
debugger.detach()Détache le débogueur depuis le webContents.
debugger.sendCommand(method[, commandParams, sessionId])method String - Method name, should be one of the methods defined by the remote debugging protocol.commandParams n'importe quel objet (facultatif) - JSON avec les paramètres de la requête.sessionId String (optional) - send command to the target with associated debugging session id. The initial value can be obtained by sending Target.attachToTarget message.Retourne Promise<any> - Une promesse qui se résout avec la réponse définie par l'attribut 'returns' de la description de la commande dans le protocole de débogage distant ou qui est rejetée indiquant l'échec de la commande.
Envoi une commande au débogueur.
", "title": "Classe : Debugger", "description": "Un transport alternatif pour le protocole de débogage distant de Chrome." }, "/docs/development/debugging-instructions-macos": { "locale": "fr-FR", "slug": "debugging-instructions-macos", "href": "/docs/development/debugging-instructions-macos", "crowdinFileId": "256153", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Si vous rencontrez des crash ou des problèmes dans Electron et que vous croyez qu'il ne viennent pas de votre app JavaScript, mais plutôt d'Electron lui-même, alors le débogage peut être un peu difficile, surtout pour les développeurs peu expérimentés pour le débogage natif/C++. Toutefois, en utilisant Ildb, et le code source d'Electron, il est assez facile d'activer le débogage avec des points d’arrêt dans le code source d'Electron. Vous pouvez également utiliser XCode pour le débogage si vous préférez une interface graphique.
\nUne compilation debug d'Electron : le moyen le plus simple est généralement de le compiler vous-même, en utilisant les outils et prérequis énumérées dans les instructions de compilation pour macOS. Tandis que vous pouvez facilement déboguer Electron puisque vous pouvez le télécharger directement, vous trouverez qu’il est fortement optimisé, ce qui rend le débogage sensiblement plus difficile : le débogueur ne sera pas en mesure de vous montrer le contenu de toutes les variables et le chemin d’exécution peut sembler étrange à cause de l’inlining, liste des appels qui s’enchaînent et d'autres optimisations du compilateur.
\nXcode: En plus de Xcode, vous devez aussi installer les outils de ligne de commande de Xcode. Ils incluent LLDB, le débogueur par défaut dans Xcode sur macOS. Il prend en charge le débogage en C, Objectif-C et Cm sur les appareils et simulateurs de bureau et d’iOS.
\n.lldbinit : Créez ou éditez ~/.lldbinit pour permettre au code Chromium d'être correctement source-mappé.
# e.g: ['~/electron/src/tools/lldb']\nscript sys.path[:0] = ['<...path/to/electron/src/tools/lldb>']\nscript import lldbinit\nPour démarrer une session de débogage, ouvrez le Terminal et démarrez lldb, en passant une version non-version d'Electron en paramètre.
$ lldb ./out/Testing/Electron.app\n(lldb) target create \"./out/Testing/Electron.app\"\nCurrent executable set to './out/Testing/Electron.app' (x86_64).\nLLDB est un outil puissant et supporte plusieurs stratégies d'inspection de code. Pour cette introduction basique, assumons que vous exécutez une commande JavaScript qui ne se comporte pas correctement - donc vous aimeriez voir l'equivalent de cette commande en C++.
\nLes fichiers de code pertinents peuvent être trouvés dans ./shell/.
Supposons que vous souhaitez déboguer app.setName(), qui est définie dans browser.cc comme Browser::SetName(). Définissez le point d’arrêt à l’aide de la commande de breakpoint, en spécifiant le fichier et la ligne à couper :
(lldb) breakpoint set --file browser.cc --line 117\nBreakpoint 1: where = Electron Framework`atom::Browser::SetName(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) + 20 at browser.cc:118, address = 0x000000000015fdb4\nEnsuite, démarrez Electron :
\n(lldb) run\nL’app sera immédiatement suspendu, puisque l’électron définit le nom de l’application au lancement :
\n(lldb) run\nProcess 25244 launched: '/Users/fr/Code/electron/out/Testing/Electron. pp/Contents/MacOS/Electron' (x86_64)\nLe processus 25244 s'est arrêté\n* thread #1: tid = 0x839a4c, 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 au navigateur. c:118, queue = 'com.apple.main-thread', stop reason = point d'arrêt 1.\n frame #0: 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 dans le navigateur. c:118\n 115 }\n 116\n 117 void Browser::SetName(const std::string& name) {\n-> 118 name_override_ = name;\n 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n(lldb)\nPour afficher les arguments et les variables locales pour le frame en cours, exécutez frame variable (ou fr v), qui vous montrera que l'app est en train de mettre le nom à \"Electron\".
(lldb) frame variable\n(atom::Browser *) this = 0x0000000108b14f20\n(const string &) name = \"Electron\": {\n [...]\n}\nPour faire une étape au niveau source dans le thread actuellement sélectionné, exécutez step (ou s). Cela vous amènerait dans name_override_.empty(). Pour continuer et refaire une étape, exécutez next (ou n).
(lldb) step\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119, queue = 'com.apple.main-thread', stop reason = step in\n frame #0: 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119\n 116\n 117 void Browser::SetName(const std::string& name) {\n 118 name_override_ = name;\n-> 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n 122 return badge_count_;\nNOTE: If you don't see source code when you think you should, you may not have added the ~/.lldbinit file above.
Pour terminer de déboguer à ce stade, exécutez : process continue. Vous pouvez également continuer jusqu'à ce que la ligne soit frappée dans ce thread (thread jusqu'à 100). Cette commande exécutera le thread dans le frame actif jusqu'à ce qu’il atteigne la ligne 100 dans cette trame ou s’arrête si elle quitte le frame en cours.
Maintenant, si vous ouvrez les outils de développement d'Electron et appelez setName, vous frapperez une fois de plus le point d’arrêt.
LLDB est un outil puissant, avec une excellente documentation. To learn more about it, consider Apple's debugging documentation, for instance the LLDB Command Structure Reference or the introduction to Using LLDB as a Standalone Debugger.
\nYou can also check out LLDB's fantastic manual and tutorial, which will explain more complex debugging scenarios.
", "title": "Débogage sur macOS", "description": "" }, "/docs/development/debugging-instructions-macos-xcode": { "locale": "fr-FR", "slug": "debugging-instructions-macos-xcode", "href": "/docs/development/debugging-instructions-macos-xcode", "crowdinFileId": "256151", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos-xcode.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Run gn gen with the --ide=xcode argument.
$ gn gen out/Testing --ide=xcode\nCela générera le electron.ninja.xcworkspace. Vous devrez ouvrir cet espace de travail pour définir des points d'arrêt et inspecter.
\nSee gn help gen for more information on generating IDE projects with GN.
Launch Electron app after build. You can now open the xcode workspace created above and attach to the Electron process through the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug the renderer process, you need to attach to the Electron Helper as well.]
\nVous pouvez maintenant définir des points d'arrêt dans l'un des fichiers indexés. However, you will not be able to set breakpoints directly in the Chromium source. To set break points in the Chromium source, you can choose Debug > Breakpoints > Create Symbolic Breakpoint and set any function name as the symbol. This will set the breakpoint for all functions with that name, from all the classes if there are more than one. You can also do this step of setting break points prior to attaching the debugger, however, actual breakpoints for symbolic breakpoint functions may not show up until the debugger is attached to the app.
", "title": "Débogage avec XCode", "description": "" }, "/docs/tutorial/debugging-main-process": { "locale": "fr-FR", "slug": "debugging-main-process", "href": "/docs/tutorial/debugging-main-process", "crowdinFileId": "256189", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/debugging-main-process.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Les DevTools dans une fenêtre de navigateur d’Electron peut seulement débogguer le JavaScript qui est exécuté dans cette fenêtre (c'est-à-dire les pages web). Pour débogguer le code JavaScript qui s’exécute dans le main process, vous devrez utiliser un déboggueur externe et lancer Electron avec les variables d'environnement --inspect ou --inspect-brk.
Utilisez une des variables d'environnement de ligne de commande suivantes pour activer le déboggage du main process :
\n--inspect=[port]Electron will listen for V8 inspector protocol messages on the specified port, an external debugger will need to connect on this port. The default port is 5858.
electron --inspect=5858 votre/app\n--inspect-brk=[port]Comme --inspect mais interrompt l'exécution sur la première ligne de JavaScript.
Vous devrez utiliser un débogueur supportant le protocole de l'inspecteur V8.
\nchrome://inspect et sélectionnez inspecter l'application Electron lancé présente ici.Ce guide explique comment configurer le débogage de VSCode pour votre propre projet Electron ainsi que pour la base de code natif d'Electron.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json avec la configuration suivante :{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"Debug Main Process\",\n \"type\": \"node\",\n \"request\": \"launch\",\n \"cwd\": \"${workspaceFolder}\",\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron\",\n \"windows\": {\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron.cmd\"\n },\n \"args\" : [\".\"],\n \"outputCapture\": \"std\"\n }\n ]\n}\nSet some breakpoints in main.js, and start debugging in the Debug View. You should be able to hit the breakpoints.
Voici un projet pré-configuré que vous pouvez télécharger et déboguer directement dans VSCode : https://github.com/octref/vscode-electron-debug/tree/master/electron-quick-start
\nCette section vous aidera à tester vos modifications si vous souhaitez générer Electron à partir des sources et modifier le code natif de base d'Electron. .
\nSi vous ne savez pas où aller chercher ce code ce code ou comment le générer, Electron's Build Tools automatise et explique la plupart de ce processus. Si vous souhaitez configurer manuellement l’environnement, vous pouvez utiliser ces instructions de génération.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json avec la configuration suivante :{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"(Windows) Launch\",\n \"type\": \"cppvsdbg\",\n \"request\": \"launch\",\n \"program\": \"${workspaceFolder}\\\\out\\\\your-executable-location\\\\electron.exe\",\n \"args\": [\"your-electron-project-path\"],\n \"stopAtEntry\": false,\n \"cwd\": \"${workspaceFolder}\",\n \"environment\": [\n {\"name\": \"ELECTRON_ENABLE_LOGGING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_ENABLE_STACK_DUMPING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_RUN_AS_NODE\", \"value\": \"\"},\n ],\n \"externalConsole\": false,\n \"sourceFileMap\": {\n \"o:\\\\\": \"${workspaceFolder}\",\n },\n },\n ]\n}\nConfiguration Notes
\ncppvsdbg requires the built-in C/C++ extension be enabled.${workspaceFolder} is the full path to Chromium's src directory.your-executable-location will be one of the following depending on a few items:Testing: If you are using the default settings of Electron's Build-Tools or the default instructions when building from source.Release: If you built a Release build rather than a Testing build.your-directory-name: If you modified this during your build process from the default, this will be whatever you specified.args array string \"your-electron-project-path\" should be the absolute path to either the directory or main.js file of the Electron project you are using for testing. In this example, it should be your path to electron-quick-start.Définissez quelques points d'arrêt dans le code natif Electron C++ et commencez à déboguer dans la Vue débogage.
", "title": "Débogage dans VSCode", "description": "" }, "/docs/api/desktop-capturer": { "locale": "fr-FR", "slug": "desktop-capturer", "href": "/docs/api/desktop-capturer", "crowdinFileId": "256307", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/desktop-capturer.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n\nAccess information about media sources that can be used to capture audio and video from the desktop using the
\nnavigator.mediaDevices.getUserMediaAPI.
L'exemple suivant montre comment faire pour capturer la vidéo à partir d'une fenêtre dont le titre est Electron :
// Dans le processus renderer.\nconst { desktopCapturer } = require('electron')\n\ndesktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources => {\n for (const source of sources) {\n if (source.name === 'Electron') {\n try {\n const stream = await navigator.mediaDevices.getUserMedia({\n audio: false,\n video: {\n mandatory: {\n chromeMediaSource: 'desktop',\n chromeMediaSourceId: source.id,\n minWidth: 1280,\n maxWidth: 1280,\n minHeight: 720,\n maxHeight: 720\n }\n }\n })\n handleStream(stream)\n } catch (e) {\n handleError(e)\n }\n return\n }\n }\n})\n\nfunction handleStream (stream) {\n const video = document.querySelector('video')\n video.srcObject = stream\n video.onloadedmetadata = (e) => video.play()\n}\n\nfunction handleError (e) {\n console.log(e)\n}\nTo capture video from a source provided by desktopCapturer the constraints passed to navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop', and audio: false.
To capture both audio and video from the entire desktop the constraints passed to navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop', for both audio and video, but should not include a chromeMediaSourceId constraint.
const constraints = {\n audio: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n },\n video: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n }\n}\nLe module desktopCapturer dispose des méthodes suivantes :
desktopCapturer.getSources(options)optionstypes String[] - un tableau de Chaîne de caractères qui répertorie les types de sources bureau à être capturé, les types disponibles sont screen et window.thumbnailSize Size (facultatif) - La taille de la miniature de la source de média doit être redimensionnée. La valeur par défaut est 150 x 150. Définissez la largeur ou la hauteur à 0 lorsque vous n'avez pas besoin de les vignettes. Cela permettra de gagner le temps de traitement nécessaire pour capturer le contenu de chaque fenêtre et écran.fetchWindowIcons Boolean (facultatif) - Définir à true pour activer la récupération des icônes de fenêtre. La valeur par défaut est faux. Lorsque false la propriété appIcon des sources retourne null. Même si une source a l'écran de type.Retourne Promise<DesktopCapturerSource[]> - Résout avec un tableau de DesktopCapturerSource, chaque DesktopCapturerSource représente un écran ou une fenêtre individuelle qui peut être capturée.
Note Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher, which can detected by systemPreferences.getMediaAccessStatus.
navigator.mediaDevices. etUserMedia ne fonctionne pas sur macOS pour la capture audio en raison d'une limitation fondamentale par laquelle les applications qui veulent accéder à l'audio du système nécessitent une extension du noyau signée. Chromium, et par extension Electron, ne le fournit pas.
Il est possible de contourner cette limitation en capturant le système audio avec une autre application macOS comme Soundflower et en le passant par un périphérique d'entrée audio virtuel. Ce périphérique virtuel peut ensuite être interrogé avec navigator.mediaDevices.getUserMedia.
id String - The identifier of a window or screen that can be used as a chromeMediaSourceId constraint when calling [navigator.webkitGetUserMedia]. The format of the identifier will be window:XX:YY or screen:ZZ:0. XX is the windowID/handle. YY is 1 for the current process, and 0 for all others. ZZ is a sequential number that represents the screen, and it does not equal to the index in the source's name.name String - A screen source will be named either Entire Screen or Screen <index>, while the name of a window source will match the window title.thumbnail NativeImage - A thumbnail image. Note: There is no guarantee that the size of the thumbnail is the same as the thumbnailSize specified in the options passed to desktopCapturer.getSources. The actual size depends on the scale of the screen or window.display_id String - A unique identifier that will correspond to the id of the matching Display returned by the Screen API. On some platforms, this is equivalent to the XX portion of the id field above and on others it will differ. It will be an empty string if not available.appIcon NativeImage - An icon image of the application that owns the window or null if the source has a type screen. The size of the icon is not known in advance and depends on what the application provides.Comme les navigateurs basés sur Chromium, Electron fournit un accès au matériel du périphérique via des API Web. Ces API fonctionnent pour la plupart, comme dans un navigateur, mais il y a quelques différences qui doivent être prises en compte. La principale différence entre Electron et les navigateurs est ce qui se passe lorsque l'accès à l'appareil est demandé . Dans un navigateur, les utilisateurs se voient présenter une popup où ils peuvent accorder l' accès à un appareil individuel. Dans Electron des APIsont fournies pouvant être utilisées par un développeur pour choisir automatiquement un périphérique ou demander aux utilisateurs de choisir un périphérique via une interface créée par un développeur.
\nL’API Web Bluetooth peut être utilisée pour communiquer avec des périphériques Bluetooth. Afin d'utiliser cette API dans Electron, les développeurs devront gérer l'événement select-bluetooth-device sur le webContents associé à la demande de périphérique.
Cet exemple montre une application Electron qui sélectionne automatiquement le premier périphérique Bluetooth disponible lorsque le bouton Test Bluetooth est cliqué.
The WebHID API can be used to access HID devices such as keyboards and gamepads. Electron provides several APIs for working with the WebHID API:
\nselect-hid-device event on the Session can be used to select a HID device when a call to navigator.hid.requestDevice is made. Additionally the hid-device-added and hid-device-removed events on the Session can be used to handle devices being plugged in or unplugged during the navigator.hid.requestDevice process.ses.setDevicePermissionHandler(handler) can be used to provide default permissioning to devices without first calling for permission to devices via navigator.hid.requestDevice. Additionally, the default behavior of Electron is to store granted device permision through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.ses.setPermissionCheckHandler(handler) can be used to disable HID access for specific origins.By default Electron employs the same blocklist used by Chromium. If you wish to override this behavior, you can do so by setting the disable-hid-blocklist flag:
app.commandLine.appendSwitch('disable-hid-blocklist')\nThis example demonstrates an Electron application that automatically selects HID devices through ses.setDevicePermissionHandler(handler) and through select-hid-device event on the Session when the Test WebHID button is clicked.
The Web Serial API can be used to access serial devices that are connected via serial port, USB, or Bluetooth. In order to use this API in Electron, developers will need to handle the select-serial-port event on the Session associated with the serial port request.
There are several additional APIs for working with the Web Serial API:
\nserial-port-added and serial-port-removed events on the Session can be used to handle devices being plugged in or unplugged during the navigator.serial.requestPort process.ses.setPermissionCheckHandler(handler) can be used to disable serial access for specific origins.This example demonstrates an Electron application that automatically selects the first available Arduino Uno serial device (if connected) through select-serial-port event on the Session when the Test Web Serial button is clicked.
Electron prend en charge les Chrome DevTools extensions, qui peuvent être utilisées pour étendre les capacités des devtools de Chrome pour le débogage des framework les plus populaires.
\nLa façon la plus simple de charger une extension DevTools est l'utilisation d'outil tiers pour automatiser à votre place le processus. Le package electron-devtools-installer disponible via NPM correspond exactement à cela.
\nSi vous ne voulez pas utiliser l'approche outillage, vous pouvez de toute façon effectuer toutes les opérations nécessaires à la main. Pour charger une extension dans Electron, vous devez tout d'abord la télécharger via Chrome puis localiser son chemin dans le système de fichiers et la charger enfin dans votre Session en appelant l'API [ses.loadExtension].
Exemple utilisant React Developer Tools :
\nInstallez l'extension dans Google Chrome.
\nAccédez à chrome://extensions et trouvez son ID d’extension, qui est une chaîne de hachage comme fmkadmapgofadopljbjfkapdkoienihi.
Découvrez l'emplacement utilisé par Chrome dans le système de fichiers pour stocker les extensions :
\n%LOCALAPPDATA%\\Google\\Chrome\\User Data\\Default\\Extensions ;~/.config/google-chrome/Default/Extensions/~/.config/google-chrome-beta/Default/Extensions/~/.config/google-chrome-canary/Default/Extensions/~/.config/chromium/Default/Extensions/~/Library/Application Support/Google/Chrome/Default/Extensions.Transmettre l'emplacement de l'extension à l'API ses.loadExtension . Pour les outils de développement React v4.9.0, cela ressemble à quelque chose comme :
const { app, session } = require('electron')\n const path = require('path')\n const os = require('os')\n\n // sur macOS\n const reactDevToolsPath = path.join(\n os.homedir(),\n '/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.9.0_0'\n )\n\n app.whenReady().then(async () => {\n await session.defaultSession.loadExtension(reactDevToolsPath)\n })\nRemarque :
\nloadExtension retourne une Promise avec un objet de type Extension contenant des métadonnées à propos de l'extension qui a été chargée. Cette promesse doit être résolue (par exemple avec une expression await ) avant de charger une page. Sinon il n'est pas garanti que l'extension se charge.loadExtension ne doit pas être invoquée avant que l'évènement ready du module app ne soit émis, ni lors de sessions en mémoire (non persistantes).loadExtension devrat être invoquée à chaque démarrage de votre application.Afin de supprimer une extension vous devez passer l'ID de l'extension à l'API ses.removeExtension. Les extensions chargées ne persistent s pas entre deux lancements d’application.
Electron ne prend en charge qu'un ensemble limité des APIs chrome. , donc les extensions utilisant les APIs non supportées sous le capot peuvent ne pas fonctionner.
Les Extensions Devtools suivantes ont été testées et sont garanties de fonctionner dans Electron :
\nTout d'abord, assurez-vous que l'extension est toujours maintenue, et qu'elle est compatible avec la dernière version de Google Chrome. Nous ne pouvons pas fournir de support supplémentaire pour les extensions non prises en charge.
\nSi l'extension fonctionne sur Chrome mais pas sur Electron, signalez une bug dans le traqueur de tickets d'Electron en décrivant quelle partie de l'extension ne fonctionne pas comme prévu.
", "title": "Extension DevTools", "description": "" }, "/docs/api/dialog": { "locale": "fr-FR", "slug": "dialog", "href": "/docs/api/dialog", "crowdinFileId": "256309", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/dialog.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nAffiche une boîte de dialogue du système natif pour ouvrir et enregistrer des fichiers, alertes, etc...
\n
Processus : Main
\nUn exemple d'afficher une boîte de dialogue pour sélectionner plusieurs fichiers :
\nconst { dialog } = require('electron')\nconsole.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))\nLe module dialog dispose des méthodes suivantes :
dialog.showOpenDialogSync([browserWindow, ]options)browserWindow BrowserWindow (facultatif)optionstitle String (facultatif)defaultPath String (facultatif)buttonLabel String (facultatif) - Étiquette personnalisé pour le bouton de confirmation. Si laissé vide, l'étiquette par défaut sera utilisé.filters FileFilter[] (facultatif)properties String[] (facultatif) - Contient les fonctionnalités que la boîte de dialogue doit utiliser. Les valeurs suivantes sont prises en charge :openFile - Permet la sélection de fichiers.openDirectory - Permet la sélection de dossiers.multiSelections - Permet la sélection de multiples chemins.showHiddenFiles - Affiche les fichiers cachés dans la boîte de dialogue.createDirectory macOS - Permet la création de nouveaux dossiers depuis la boîte de dialogue.promptToCreate Windows - Demande la création du dossier si le chemin d'accès du fichier entré dans la boîte de dialogue n'existe pas. Cela ne créer par réellement le fichier dans le chemin d'accès mais permet de donner des chemins d'accès inexistant qui devraient être créés par l'application.noResolveAliases macOS - Désactive la résolution de l'alias automatique (lien symbolique) . Les alias sélectionnés retourneront alors le chemin de l'alias au lieu de celui de leur cible.treatPackageAsDirectory macOS - Considérer les paquets, tels que les dossiers .app, comme des dossiers plutôt que des fichiers.dontAddToRecent Windows - N'ajoutez pas l'élément en cours d'ouverture à la liste des documents récents.message String (facultatif) macOS - Message à afficher au-dessus des zones de saisie.securityScopedBookmarks Boolean (facultatif) macOS mas - Créez signets à portée de sécurité lorsqu'ils sont empaquetés pour le Mac App Store.Retourne String[] | undefined - le chemin du fichier choisi par l'utilisateur ; si la boîte de dialogue est annulée retourne undefined.
L'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale.
The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Par exemple :
{\n filtres: [\n { name : 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Films', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Type de fichier personnalisé', extensions: ['as'] },\n { name: 'Tous les fichiers', extensions: ['*'] }\n ]\n}\nLe tableau d'extensions devrait contenir les extensions sans caractères génériques ou de point (par exemple 'png' est correct, mais '.png' et '*.png' ne l'est pas). Pour afficher tous les fichiers, utilisez le caractère générique '*' (aucun autre caractère générique n'est pris en charge).
Remarque : Sur Windows et Linux, une boîte de dialogue ne peux pas être à la fois une sélection de fichier et une sélection de dossier, donc si vous définissez properties à ['openFile', 'openDirectory'] sur ces plateformes, c'est la sélection de dossier qui s'affichera.
dialog.showOpenDialogSync(mainWindow, {\n propriétés: ['openFile', 'openDirectory']\n})\ndialog.showOpenDialog([browserWindow, ]options)browserWindow BrowserWindow (facultatif)optionstitle String (facultatif)defaultPath String (facultatif)buttonLabel String (facultatif) - Étiquette personnalisé pour le bouton de confirmation. Si laissé vide, l'étiquette par défaut sera utilisé.filters FileFilter[] (facultatif)properties String[] (facultatif) - Contient les fonctionnalités que la boîte de dialogue doit utiliser. Les valeurs suivantes sont prises en charge :openFile - Permet la sélection de fichiers.openDirectory - Permet la sélection de dossiers.multiSelections - Permet la sélection de multiples chemins.showHiddenFiles - Affiche les fichiers cachés dans la boîte de dialogue.createDirectory macOS - Permet la création de nouveaux dossiers depuis la boîte de dialogue.promptToCreate Windows - Demande la création du dossier si le chemin d'accès du fichier entré dans la boîte de dialogue n'existe pas. Cela ne créer par réellement le fichier dans le chemin d'accès mais permet de donner des chemins d'accès inexistant qui devraient être créés par l'application.noResolveAliases macOS - Désactive la résolution de l'alias automatique (lien symbolique) . Les alias sélectionnés retourneront alors le chemin de l'alias au lieu de celui de leur cible.treatPackageAsDirectory macOS - Considérer les paquets, tels que les dossiers .app, comme des dossiers plutôt que des fichiers.dontAddToRecent Windows - N'ajoutez pas l'élément en cours d'ouverture à la liste des documents récents.message String (facultatif) macOS - Message à afficher au-dessus des zones de saisie.securityScopedBookmarks Boolean (facultatif) macOS mas - Créez signets à portée de sécurité lorsqu'ils sont empaquetés pour le Mac App Store.Retourne Promise<Object> - Résoudre avec un objet contenant les éléments suivants :
annulé Booléen - que la boîte de dialogue ait été annulée ou non.filePaths String[] - Un tableau de chemins d'accès choisi par l'utilisateur. If the dialog is cancelled this will be an empty array.signets String[] (facultatif) macOS mas - Un tableau correspondant au tableau filePaths de chaînes encodées en base64 qui contient des données de marque-pages à portée de sécurité. securityScopedBookmarks doit être activé pour que ceci soit rempli. (Pour les valeurs de retour, voir la table ici.)L'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale.
The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Par exemple :
{\n filtres: [\n { name : 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Films', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Type de fichier personnalisé', extensions: ['as'] },\n { name: 'Tous les fichiers', extensions: ['*'] }\n ]\n}\nLe tableau d'extensions devrait contenir les extensions sans caractères génériques ou de point (par exemple 'png' est correct, mais '.png' et '*.png' ne l'est pas). Pour afficher tous les fichiers, utilisez le caractère générique '*' (aucun autre caractère générique n'est pris en charge).
Remarque : Sur Windows et Linux, une boîte de dialogue ne peux pas être à la fois une sélection de fichier et une sélection de dossier, donc si vous définissez properties à ['openFile', 'openDirectory'] sur ces plateformes, c'est la sélection de dossier qui s'affichera.
dialog.showOpenDialog(mainWindow, {\n properties: ['openFile', 'openDirectory']\n}).then(result => {\n console.log(result.canceled)\n console.log(result.filePaths)\n}).catch(err => {\n console.log(err)\n})\ndialog.showSaveDialogSync([browserWindow, ]options)browserWindow BrowserWindow (facultatif)optionstitle String (optional) - The dialog title. Ne peut pas être affiché sur certains environnements de bureau Linux.defaultPath String (facultatif) - Chemin d'accès absolu, le chemin d'accès absolu du fichier, ou le nom du fichier à utiliser par défaut.buttonLabel String (facultatif) - Étiquette personnalisé pour le bouton de confirmation. Si laissé vide, l'étiquette par défaut sera utilisé.filters FileFilter[] (facultatif)message String (facultatif) macOS - Message à afficher au-dessus des champs de texte.nameFieldLabel String (facultatif) macOS - Étiquette personnalisé pour le texte affiché dans la zone de texte du nom de fichier.showsTagField Boolean (facultatif) macOS - Affiche le champ de texte. true par défaut.properties String[] (facultatif)showHiddenFiles - Affiche les fichiers cachés dans la boîte de dialogue.createDirectory macOS - Permet la création de nouveaux dossiers depuis la boîte de dialogue.treatPackageAsDirectory macOS - Considérer les paquets, tels que les dossiers .app, comme des dossiers plutôt que des fichiers.showOverwriteConfirmation Linux - Définit si une boîte de dialogue de confirmation sera affichée lorsque l’utilisateur tape un nom de fichier déjà existant.dontAddToRecent Windows - N'ajoutez pas l'élément en cours d'ouverture à la liste des documents récents.securityScopedBookmarks Boolean (facultatif) macOS mas - Créez un marque-page à portée de sécurité lorsque empaqueté pour le Mac App Store. Si cette option est activée et que le fichier n'existe pas encore, un fichier vide sera créé dans le chemin choisi.Retourne String | undefined, le chemin du fichier choisi par l'utilisateur ; si la boîte de dialogue est annulée, elle retourne undefined.
L'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale.
Les filters spécifie un tableau de types de fichiers qui peuvent être affichés, allez voir dialog.showOpenDialog pour un exemple.
dialog.showSaveDialog([browserWindow, ]options)browserWindow BrowserWindow (facultatif)optionstitle String (optional) - The dialog title. Ne peut pas être affiché sur certains environnements de bureau Linux.defaultPath String (facultatif) - Chemin d'accès absolu, le chemin d'accès absolu du fichier, ou le nom du fichier à utiliser par défaut.buttonLabel String (facultatif) - Étiquette personnalisé pour le bouton de confirmation. Si laissé vide, l'étiquette par défaut sera utilisé.filters FileFilter[] (facultatif)message String (facultatif) macOS - Message à afficher au-dessus des champs de texte.nameFieldLabel String (facultatif) macOS - Étiquette personnalisé pour le texte affiché dans la zone de texte du nom de fichier.showsTagField Boolean (facultatif) macOS - Affiche le champ de texte, par défaut à true.properties String[] (facultatif)showHiddenFiles - Affiche les fichiers cachés dans la boîte de dialogue.createDirectory macOS - Permet la création de nouveaux dossiers depuis la boîte de dialogue.treatPackageAsDirectory macOS - Considérer les paquets, tels que les dossiers .app, comme des dossiers plutôt que des fichiers.showOverwriteConfirmation Linux - Définit si une boîte de dialogue de confirmation sera affichée lorsque l’utilisateur tape un nom de fichier déjà existant.dontAddToRecent Windows - N'ajoutez pas l'élément en cours d'ouverture à la liste des documents récents.securityScopedBookmarks Boolean (facultatif) macOS mas - Créez un marque-page à portée de sécurité lorsque empaqueté pour le Mac App Store. Si cette option est activée et que le fichier n'existe pas encore, un fichier vide sera créé dans le chemin choisi.Retourne Promise<Object> - Résoudre avec un objet contenant les éléments suivants :
annulé Booléen - que la boîte de dialogue ait été annulée ou non.filePath String (optional) - If the dialog is canceled, this will be undefined.bookmark String (optional) macOS mas - Base64 encoded string which contains the security scoped bookmark data for the saved file. securityScopedBookmarks must be enabled for this to be present. (Pour les valeurs de retour, voir la table ici.)L'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale.
Les filters spécifie un tableau de types de fichiers qui peuvent être affichés, allez voir dialog.showOpenDialog pour un exemple.
Remarque : Sur macOS, l'utilisation de la version asynchrone est recommandée pour éviter les problèmes lorsque étend et réduit la boîte de dialogue.
\ndialog.showMessageBoxSync([browserWindow, ]options)browserWindow BrowserWindow (facultatif)optionsmessage Chaîne - Contenu de la boîte de message.type String (facultatif) - Peut être \"none\", \"info\", \"error\", \"question\" ou \"warning\". Sur Windows, \"question\" affiche la même icône que \"info\", sauf si vous définissez une icône en utilisant l'option \"icône\". Sur macOS, \"avertissement\" et \"erreur\" affichent la même icône d'avertissement.boutons String[] (facultatif) - Tableau de textes pour les boutons. On Windows, an empty array will result in one button labeled \"OK\".defaultId Integer (facultatif) - Index du bouton dans le tableau des boutons qui seront sélectionnés par défaut lorsque la boîte de message s'ouvrira.title String (facultatif) - Titre de la boîte de message, certaines plateformes ne l'afficheront pas.detail String (facultatif) - Informations supplémentaires du message.icon (NativeImage | String) (facultatif)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (facultatif) - L'index du bouton à utiliser pour annuler la boîte de dialogue, via la touche Esc. Par défaut, ceci est assigné au premier bouton avec l'étiquette \"annuler\" ou \"non\". Si aucun bouton de ce type n'existe et que cette option n'est pas définie, 0 sera utilisé comme valeur de retour .noLink Booléen (optionnel) - Sous Windows, Electron essaiera de déterminer lequel des les boutons `sont des boutons courants (comme \"Annuler\" ou \"Oui\"), et affichent le d'autres comme liens de commande dans le dialogue. Cela peut faire apparaître la boîte de dialogue dans le style des applications Windows modernes. Si vous n'aimez pas ce comportement, vous pouvez définirnoLinkàtrue`.normalizeAccessKeys Boolean (facultatif) - Normalise les clés d'accès au clavier sur toutes les plateformes. Par défaut la valeur est false. Activer ceci suppose que & est utilisé dans les étiquettes des boutons pour le placement de la touche d'accès du raccourci clavier et les étiquettes seront converties pour qu'elles fonctionnent correctement sur chaque plateforme, & les caractères sont supprimés sur macOS, convertis en _ sous Linux, et intactés sur Windows. Par exemple, une étiquette de bouton de Vie&w sera converti en Vie_w sous Linux et Vie sous macOS et peut être sélectionné via Alt-W sur Windows et Linux.Retourne Integer - l'index du bouton cliqué.
Affiche une boîte de message, elle bloque le processus jusqu'à ce que la boîte de message soit fermée. It returns the index of the clicked button.
\nL'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale. If browserWindow is not shown dialog will not be attached to it. In such case it will be displayed as an independent window.
dialog.showMessageBox([browserWindow, ]options)browserWindow BrowserWindow (facultatif)optionsmessage Chaîne - Contenu de la boîte de message.type String (facultatif) - Peut être \"none\", \"info\", \"error\", \"question\" ou \"warning\". Sur Windows, \"question\" affiche la même icône que \"info\", sauf si vous définissez une icône en utilisant l'option \"icône\". Sur macOS, \"avertissement\" et \"erreur\" affichent la même icône d'avertissement.boutons String[] (facultatif) - Tableau de textes pour les boutons. On Windows, an empty array will result in one button labeled \"OK\".defaultId Integer (facultatif) - Index du bouton dans le tableau des boutons qui seront sélectionnés par défaut lorsque la boîte de message s'ouvrira.signal AbortSignal (optional) - Pass an instance of AbortSignal to optionally close the message box, the message box will behave as if it was cancelled by the user. On macOS, signal does not work with message boxes that do not have a parent window, since those message boxes run synchronously due to platform limitations.title String (facultatif) - Titre de la boîte de message, certaines plateformes ne l'afficheront pas.detail String (facultatif) - Informations supplémentaires du message.checkboxLabel String (facultatif) - Si fourni, la case de message inclura une case à cocher avec l'étiquette donnée.checkboxChecked Boolean (optional) - Initial checked state of the checkbox. false par défaut.icon NativeImage (facultatif)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (facultatif) - L'index du bouton à utiliser pour annuler la boîte de dialogue, via la touche Esc. Par défaut, ceci est assigné au premier bouton avec l'étiquette \"annuler\" ou \"non\". Si aucun bouton de ce type n'existe et que cette option n'est pas définie, 0 sera utilisé comme valeur de retour .noLink Booléen (optionnel) - Sous Windows, Electron essaiera de déterminer lequel des les boutons `sont des boutons courants (comme \"Annuler\" ou \"Oui\"), et affichent le d'autres comme liens de commande dans le dialogue. Cela peut faire apparaître la boîte de dialogue dans le style des applications Windows modernes. Si vous n'aimez pas ce comportement, vous pouvez définirnoLinkàtrue`.normalizeAccessKeys Boolean (facultatif) - Normalise les clés d'accès au clavier sur toutes les plateformes. Par défaut la valeur est false. Activer ceci suppose que & est utilisé dans les étiquettes des boutons pour le placement de la touche d'accès du raccourci clavier et les étiquettes seront converties pour qu'elles fonctionnent correctement sur chaque plateforme, & les caractères sont supprimés sur macOS, convertis en _ sous Linux, et intactés sur Windows. Par exemple, une étiquette de bouton de Vie&w sera converti en Vie_w sous Linux et Vie sous macOS et peut être sélectionné via Alt-W sur Windows et Linux.Retourne Promise<Object> - résout avec une promesse contenant les propriétés suivantes :
response Number - The index of the clicked button.checkboxChecked Boolean - The checked state of the checkbox if checkboxLabel was set. Sinon false.Shows a message box.
\nL'argument browserWindow permet à la boîte de dialogue de s'attacher elle-même à la fenêtre parent, la rendant modale.
dialog.showErrorBox(title, content)titre Chaîne - Le titre à afficher dans la boîte d'erreur.contenu Chaîne - Le contenu du texte à afficher dans la boîte d'erreur.Affiche une boîte de dialogue modale qui affiche un message d'erreur.
\nCette API peut être appelée en toute sécurité avant l'évènement prêt que le module app émet, il est généralement utilisé pour signaler des erreurs au début du démarrage. Si appelé avant l'application prêtévénement sous Linux, le message sera émis sur stderr, et aucune fenêtre GUI n'apparaîtra.
dialog.showCertificateTrustDialog([browserWindow, ]options) macOS WindowsbrowserWindow BrowserWindow (facultatif)optionscertificat certificat - Le certificat de confiance/importation.message String - Le message à afficher à l'utilisateur.Retourne Promise<void> - résout lorsque la boîte de dialogue de confiance du certificat est affichée.
Sur macOS, ceci affiche une boîte de dialogue modale présentant un message, les informations du certificat et donnant à l'utilisateur la possibilité de se fier/importer le certificat. Si vous fournissez une argument browserWindow, la boîte de dialogue sera attachée à la fenêtre parente.
Sous Windows, les options sont plus limitées, en raison des API Win32 utilisées:
\nmessage n'est pas utilisé, car l'OS fournit sa propre boîte de dialogue de confirmation.browserWindow est ignoré car il n'est pas possible de rendre cette fenêtre de confirmation modale.showOpenDialog, showOpenDialogSync, showSaveDialog, and showSaveDialogSync will return a bookmarks array.
| Type de compilation | securityScopedBookmarks boolean | Return Type | Return Value |
|---|---|---|---|
| macOS mas | True | Succès | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | Erreur | [''] (array of empty string) |
| macOS mas | False | NA | [] (empty array) |
| non mas | any | NA | [] (empty array) |
Sur macOS, les dialogues sont présentés comme des feuilles attachées à une fenêtre si vous fournissez une référence BrowserWindow dans le paramètre browserWindow, ou modales si aucune fenêtre n'est fournie.
Vous pouvez appeler BrowserWindow.getCurrentWindow().setSheetOffset(offset) pour changer le décalage depuis la fenêtre où les feuilles sont attachées.
id Number - Unique identifier associated with the display.rotation Number - Can be 0, 90, 180, 270, represents screen rotation in clock-wise degrees.scaleFactor Number - Output device's pixel scale factor.touchSupport String - Can be available, unavailable, unknown.monochrome Boolean - Whether or not the display is a monochrome display.accelerometerSupport String - Can be available, unavailable, unknown.colorSpace String - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversionscolorDepth Number - The number of bits per pixel.depthPerComponent Number - The number of bits per color component.displayFrequency Number - The display refresh rate.bounds Rectangle - the bounds of the display in DIP points.size SizeworkArea Rectangle - the work area of the display in DIP points.workAreaSize Sizeinternal Boolean - true for an internal display and false for an external displayThe Display object represents a physical display connected to the system. A fake Display may exist on a headless system, or a Display may correspond to a remote, virtual display.
\n\nControl your app in the macOS dock
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The following example shows how to bounce your icon on the dock.
\nconst { app } = require('electron')\napp.dock.bounce()\ndock.bounce([type]) macOStype String (optional) - Can be critical or informational. The default is informationalReturns Integer - an ID representing the request.
Lorsque la critical est passé, l’icône du dock rebondira jusqu'à ce que l’application redevienne active ou que la requête est annulée.
When informational is passed, the dock icon will bounce for one second. However, the request remains active until either the application becomes active or the request is canceled.
Nota Bene: This method can only be used while the app is not focused; when the app is focused it will return -1.
\ndock.cancelBounce(id) macOSid IntegerAnnule le rebond de l'id.
dock.downloadFinished(filePath) macOSfilePath StringFait rebondir la pile de téléchargements si le chemin d'accès se trouve le dossier Téléchargements.
\ndock.setBadge(text) macOStext StringDéfinit la chaîne de caractères à afficher dans la zone du badge du dock.
\ndock.getBadge() macOSRetourne String - Le texte du badge du dock.
dock.hide() macOSMasque l’icône du dock.
\ndock.show() macOSReturns Promise<void> - Resolves when the dock icon is shown.
dock.isVisible() macOSReturns Boolean - Whether the dock icon is visible.
dock.setMenu(menu) macOSmenu MenuSets the application's [dock menu][dock-menu].
\ndock.getMenu() macOSReturns Menu | null - The application's [dock menu][dock-menu].
dock.setIcon(image) macOSimage (NativeImage | String)Définit l’image associée à l'icône du dock.
\n\nGère les téléchargements de fichiers depuis des sources distantes.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
DownloadItem est un EventEmitter qui représente un élément de téléchargement dans Electron. Il est utilisé dans l'événement will-download de la classe Session, et permet aux utilisateurs de gérer les fichiers en cours de téléchargement.
// Dans le processus main.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.session.on('will-download', (event, item, webContents) => {\n // Set the save path, making Electron not to prompt a save dialog.\n item.setSavePath('/tmp/save.pdf')\n\n item.on('updated', (event, state) => {\n if (state === 'interrupted') {\n console.log('Le téléchargement est interrompu mais peut être redémarrer')\n } else if (state === 'progressing') {\n if (item.isPaused()) {\n console.log('Le téléchargement est en pause')\n } else {\n console.log(`Received bytes: ${item.getReceivedBytes()}`)\n }\n }\n })\n item.once('done', (event, state) => {\n if (state === 'completed') {\n console.log('Téléchargement réussi')\n } else {\n console.log(`Téléchargement échoué : ${state}`)\n }\n })\n})\nRetourne :
\nevent Eventstate Chaîne de caratères - Peut être progressing ou interrupted.Émis lorsque le téléchargement a été mis à jour et n'est pas fini.
\nLe state peut être un de ces cas :
progressing - Le téléchargement est en cours.interrupted - Le téléchargement a été interrompu et peut être repris.Retourne :
\nevent Eventstate Chaîne de caratères - Peut être completed, cancelled ou interrupted.Emitted when the download is in a terminal state. This includes a completed download, a cancelled download (via downloadItem.cancel()), and interrupted download that can't be resumed.
Le state peut être un de ces cas :
completed - Le téléchargement s'est terminé avec succès.cancelled - Le téléchargement a été annulé.interrupted - Le téléchargement a été interrompu et ne peux pas être repris.L'objet downloadItem dispose des méthodes suivantes :
downloadItem.setSavePath(path)path String - Définit le chemin d'accès pour le téléchargement.Cet API est seulement disponible dans la fonction de rappel de will-download dans session. If path doesn't exist, Electron will try to make the directory recursively. Si l'utilisateur ne définit pas le chemin de sauvegarde via l'API, Electron utilisera la routine d'origine pour déterminer le chemin de sauvegarde ; cela demande généralement une boîte de dialogue de sauvegarde.
downloadItem.getSavePath()Returns String - The save path of the download item. This will be either the path set via downloadItem.setSavePath(path) or the path selected from the shown save dialog.
downloadItem.setSaveDialogOptions(options)options SaveDialogOptions - Définit les options de la boîte de dialogue de sauvegarde des fichiers. Cet objet a la même comme le paramètre options de dialog.showSaveDialog().This API allows the user to set custom options for the save dialog that opens for the download item by default. Cet API est seulement disponible dans la fonction de rappel de will-download dans session.
downloadItem.getSaveDialogOptions()Retourne SaveDialogOptions - Retourne l'objet précédemment défini par downloadItem.setSaveDialogOptions(options).
downloadItem.pause()Met en pause le téléchargement.
\ndownloadItem.isPaused()Retourne Boolean - Si le téléchargement est en pause.
downloadItem.resume()Reprend le téléchargement qui a été mis en pause.
\nNote: To enable resumable downloads the server you are downloading from must support range requests and provide both Last-Modified and ETag header values. Sinon resume() va rejeter les octets reçus précédemment et redémarrer le téléchargement depuis le début.
downloadItem.canResume()Retourne Boolean - Si le téléchargement peut être repris.
downloadItem.cancel()Annule le téléchargement.
\ndownloadItem.getURL()Retourne String - L'URL d'origine d'où l'élément est téléchargé.
downloadItem.getMimeType()Retourne String - Le mime type du fichier.
downloadItem.hasUserGesture()Retourne Boolean - Si le téléchargement à des gestures.
downloadItem.getFilename()Retourne String - le nom du fichier du téléchargement.
Note: The file name is not always the same as the actual one saved in local disk. Si l'utilisateur modifie le nom du fichier dans la boîte de dialogue de sauvegarde, alors le nom actuel et le nom du fichier sauvegardé seront différent.
\ndownloadItem.getTotalBytes()Retourne Integer - La taille totale en octets du téléchargement.
Si la taille est inconnue, retourne 0.
\ndownloadItem.getReceivedBytes()Retourne Integer - Le nombre d'octets reçu du téléchargement.
downloadItem.getContentDisposition()Retourne String - Le champ Content-Disposition venant de l'en-tête de la réponse.
downloadItem.getState()Returns String - The current state. Can be progressing, completed, cancelled or interrupted.
Note: The following methods are useful specifically to resume a cancelled item when session is restarted.
downloadItem.getURLChain()Retourne String[] - La chaîne d'URL complète de l'élément incluant toutes les redirections.
downloadItem.getLastModifiedTime()Retourne String - La valeur de l'en-tête Last-Modified.
downloadItem.getETag()Retourne String - La valeur de l'en-tête ETag.
downloadItem.getStartTime()Retourne Double - Le nombre de secondes depuis l'époch UNIX lorsque le téléchargement s'est lancé.
chemin d'accès à la sauvegardeUne propriété String qui détermine le chemin du fichier de sauvegarde de l'élément téléchargé.
La propriété n'est disponible que dans la fonction de rappel will-download de la session. Si l'utilisateur ne définit pas le chemin de sauvegarde via la propriété, Electron utilisera la routine d'origine pour déterminer le chemin de sauvegarde ; cela demande généralement une boîte de dialogue de sauvegarde.
Remarques particulières:
\n-beta.1 et stables sont nos dates de sortie.| Electron | Alpha | Beta | Stable | Chrome | Node |
|---|---|---|---|---|---|
| 2.0.0 | -- | 2018-Feb-21 | 2018-May-01 | M61 | v8.9 |
| 3.0.0 | -- | 2018-Jun-21 | 2018-Sep-18 | M66 | v10.2 |
| 4.0.0 | -- | 2018-Oct-11 | 2018-Dec-20 | M69 | v10.11 |
| 5.0.0 | -- | 2019-Jan-22 | 2019-Apr-24 | M73 | v12.0 |
| 6.0.0 | -- | 2019-May-01 | 2019-Jul-30 | M76 | v12.4 |
| 7.0.0 | -- | 2019-Aug-01 | 2019-Oct-22 | M78 | v12.8 |
| 8.0.0 | -- | 2019-Oct-24 | 2020-Feb-04 | M80 | v12.13 |
| 9.0.0 | -- | 2020-Feb-06 | 2020-May-19 | M83 | v12.14 |
| 10.0.0 | -- | 2020-May-21 | 2020-Aug-25 | M85 | v12.16 |
| 11.0.0 | -- | 2020-Aug-27 | 2020-Nov-17 | M87 | v12.18 |
| 12.0.0 | -- | 2020-Nov-19 | 2021-Mar-02 | M89 | v14.16 |
| 13.0.0 | -- | 2021-Mar-04 | 2021-May-25 | M91 | v14.16 |
| 14.0.0 | -- | 2021-May-27 | 2021-Aug-31 | M93 | v14.17 |
| 15.0.0 | 2021-Jul-20 | 2021-Sep-01 | 2021-Sep-21 | M94 | v16.5 |
| 16.0.0 | -- | 2021-Sep-23 | 2021-Nov-16 | M96 | TBD |
\n\nUn descriptif de la politique de gestion de version et d'implémentation.
\n
As of version 2.0.0, Electron follows SemVer. The following command will install the most recent stable build of Electron:
\nnpm install --save-dev electron\nPour mettre à jour un projet existant afin d'utiliser la dernière version stable :
\nnpm install --save-dev electron@latest\nElectron versions < 2.0 did not conform to the SemVer spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. Bien que pratique pour les développeurs qui fusionnent des fonctionnalités, cela crée des problèmes pour les développeurs d'applications côté client. Les cycles de tests QA d'applications majeures comme Slack, Stride, Teams, Skype, VS Code, Atom et Desktop peuvent être longs et la stabilité est un résultat très attendu. Il y a un grand risque d'inclure de nouvelles fonctionnalités en tentant de récupérer des correctifs.
\nVoici un exemple de la stratégie 1.x :
\n
Une application développée avec la 1.8.1 ne peut pas avoir les corrections d'anomalies de la 1.8.3 sans inclure la fonctionnalité de la 1.8.2, ou faire un rétroportage de la correction tout en maintenant une nouvelle ligne de versionnage.
There are several major changes from our 1.x strategy outlined below. Each change is intended to satisfy the needs and priorities of developers/maintainers and app developers.
\n-betamaster est sans version; seules les branches de stabilisation contiennent des informations de versionNous expliquerons en détail comment les branches de git fonctionnent, comment le tagging npm fonctionne, ce que les développeurs devraient d'attendre à voir, et comment l'on peut rapporter les changements antérieurement.
\nFrom 2.0 onward, Electron will follow SemVer.
\nBelow is a table explicitly mapping types of changes to their corresponding category of SemVer (e.g. Major, Minor, Patch).
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Incréments de version Majeure | Incréments de version mineure | Incréments de version de Correctifs |
|---|---|---|
| changement Electron qui altère l'API | changement Electron n'altérant pas l'API | Electron bug fixes |
| Mises à jour de la version majeure de Node.js | Mises à jour mineure de la version de Node.js | Mises à jour des correctifs de Node.js |
| mises à jour de version Chromium | mises à jour de correctifs Chromium |
Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
\nStabilization branches are branches that run parallel to master, taking in only cherry-picked commits that are related to security or stability. These branches are never merged back to master.
\n
Since Electron 8, stabilization branches are always major version lines, and named against the following template $MAJOR-x-y e.g. 8-x-y. Prior to that we used minor version lines and named them as $MAJOR-$MINOR-x e.g. 2-0-x
Nous permettons à plusieurs branches de stabilisation d'exister simultanément, et ont l'intention de supporter au moins deux en parallèle en tout temps, en rétroportant les correctifs de sécurité si nécessaire.
Les anciennes lignes ne seront pas supportées par GitHub, mais d'autres groupes peuvent prendre possession et rétroporter des correctifs de stabilité et de sécurité par eux-mêmes. Nous décourageons cela, mais reconnaissons que cela facilite la vie de nombreux développeurs d'applications.
\nLes développeurs veulent savoir quelles versions sont fiables (safe). Même des fonctionnalités apparemment innocentes peuvent introduire des régressions dans des applications complexes. En même temps, verrouiller une version corrigée est dangereux parce que vous ignorez les correctifs de sécurité et les corrections de bogues qui sont peut-être apparues depuis votre version. Notre objectif est d'autoriser les plages de semver standards suivantes dans package.json :
~2.0.0 pour admettre que les corrections liées à la stabilité ou à la sécurité dans votre version 2.0.0.^2.0.0 pour admettre que la fonctionnalité raisonnablement stable ne soit pas cassée, ainsi que la sécurité et les corrections de bogues.Ce qui est important dans le deuxième point, c'est que les applications utilisant ^ devraient quand même pouvoir s'attendre à un niveau raisonnable de stabilité. To accomplish this, SemVer allows for a pre-release identifier to indicate a particular version is not yet safe or stable.
Quoi que vous choisissiez, vous devrez périodiquement remonter la version dans votre package.json car les changements cassés sont un fait de la vie de Chromium.
Le processus est le suivant:
\nbeta.N, e.g. 2.0.0-beta.1. After the first beta, subsequent beta releases must meet all of the following conditions:2.0.0-beta.2.2.0.0. Après la première stable, tous les changements doivent être des bogues rétrocompatibles ou des corrections de sécurité.2.0.1.Plus précisément, ce qui précède signifie :
\nPour chaque bosse majeure et mineure, vous devriez vous attendre à voir quelque chose comme ceci:
\n2.0.0-beta.1\n2.0.0-beta.2\n2.0.0-beta.3\n2.0.0\n2.0.1\n2.0.2\nUn exemple de cycle de vie dans les images :
\n2.0.0-beta.1. 2.0.0-beta.2. 2.0.0. 2-0-x line and release 2.0.1. A few examples of how various SemVer ranges will pick up new releases:
\n
Notre stratégie comporte quelques compromis qui, pour l'instant, nous semblent appropriés. Le plus important est que les nouvelles fonctionnalités dans master peuvent prendre un certain temps avant d'atteindre une ligne de publication stable. Si vous voulez essayer une nouvelle fonctionnalité immédiatement, vous devrez construire Electron vous-même.
\nÀ l'avenir, nous pourrions introduire l'un ou l'autre des éléments suivants:
\nLes drapeaux de fonctionnalités sont une pratique courante dans Chromium, et sont bien établis dans l'écosystème de développement Web. Dans le contexte d'Electron, une fonctionnalité ou une branche soft doit avoir les propriétés suivantes :
\nNous cherchons à accroître la clarté à tous les niveaux du processus de mise à jour et de publication. À partir de 2.0.0 nous aurons besoin que les demandes de fusion adhèrent à la spécification Engagements conventionnels, qui peut être résumée comme suit :
Commits that would result in a SemVer major bump must start their body with BREAKING CHANGE:.
Commits that would result in a SemVer minor bump must start with feat:.
Commits that would result in a SemVer patch bump must start with fix:.
We allow squashing of commits, provided that the squashed message adheres to the above message format.
\nIl est acceptable pour certains commits dans une pull request de ne pas inclure un préfixe sémantique, aussi longtemps que le titre de la demande d'ajout contient un message sémantique significatif.
\nmastermaster contiendra toujours la prochaine version majeure X.0.0-nightly.DATE dans son package.jsonpackage.jsonmaster is always versioned as the next theoretical release branchComme NW.js, Electron fournit une plate-forme pour développer des applications de bureau avec des technologies web. Les deux plates-formes permettent aux développeurs d'utiliser du HTML, JavaScript et Node.js. En surface, ils semblent très similaires.
\nIl existe cependant des différences fondamentales entre les deux projets qui font d'Electron un produit complètement distinct de NW.js.
\nDans NW.js, le point d'entrée principal d'une application peut être une page Web HTML. Dans dans ce cas, NW.js ouvrira le point d'entrée donné dans une fenêtre de navigateur.
\nDans Electron, le point d'entrée est toujours un script JavaScript. Au lieu de fournir un URL directement, vous créez manuellement une fenêtre de navigateur et chargez un fichier HTML en utilisant l'API. Vous devez également écouter les événements de fenêtre pour décider quand quitter l'application.
\nElectron fonctionne plus comme le runtime Node.js. Electron's APIs are lower level so you can use it for browser testing in place of PhantomJS.
\nDans NW.js, l'intégration de node dans les pages web requière de patcher Chronium pour fonctionner, alors que dans Electron nou avons choisi une approche différente d'intégrer la boucle libuv avec le protocole de communication de chaque plateforme pour éviter le piratage de Chronium. Voir le code node_bindings pour comprendre comment cela a été fait.
Si vous êtes un utilisateur expérimenté de NW.js, vous devez être familiarisé avec le concept de contexte de Node et contexte Web. Ces concepts ont été inventés à cause de la manière dont NW.js a été implémenté.
\nEn utilisant le multi-contexte fonctionnalité de Node, Electron n'introduit pas de nouveau contexte JavaScript dans les pages web.
\nRemarque : NW.js supporte éventuellement le multi-contexte depuis la v0.13.
\nNW.js offre quand même de la rétrocompatibilité jusque sur Windows XP. Il ne reçoit pas les mises à jour de sécurité.
\nEtant donné que les fabriquants de matériel, Microsoft, Chronium, et Node.js n'ont pas réalisés de mise à jour de sécurité pour Windows XP, nous devons vous avertir que l'utiliser sur cette plateforme est totallement non sécurisé et très irresponsable.
\nCependant, nous comprenons que des exigences en dehors de notre imagination la plus folle peuvent exister, donc si vous recherchez quelque chose comme Electron qui fonctionne sous Windows XP, la version héritée de NW.js pourrait vous convenir.
\nIl existe de nombreuses différences dans la quantité de fonctionnalités prises en charge. Electron a une plus grande communauté, plus d'application sur le marché, et une grande quantité de librairies disponibles sur npm.
\nÀ titre d'exemple, Electron a un support intégré pour les mises à jour automatiques et d'innombrables outils qui facilitent la création d'installateurs. A titre d'exemple en faveur de NW.js, NW.js prend en charge davantage d'API Chrome.* pour le développement d'applications Chrome.
Naturellement, nous pensons qu'Electron est la meilleure plate-forme pour les applications de production construites avec les technologies Web (comme Visual Studio Code, Slack ou Facebook Messenger); cependant, nous voulons être équitables envers notre technologie Web copain. Si vous avez des besoins en fonctionnalités auxquels Electron ne répond pas, vous voudrez peut-être essayer NW.js.
", "title": "Différences techniques entre Electron et NW.js", "description": "" }, "/docs/api/environment-variables": { "locale": "fr-FR", "slug": "environment-variables", "href": "/docs/api/environment-variables", "crowdinFileId": "256315", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/environment-variables.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nContrôle la configuration et le comportement de l'application sans modifier le code.
\n
Certains comportements d'Electron sont contrôlés par les variables d'environnement car ils sont initialisés avant les indicateurs de ligne de commande et le code de l'application.
\nExemple sur un shell POSIX :
\n$ export ELECTRON_ENABLE_LOGGING=true\n$ electron\nExemple sur la console Windows :
\n> set ELECTRON_ENABLE_LOGGING=true\n> electron\nLes variables d'environnement suivantes sont destinés principalement à l'exécution des applications Electron empaquetées.
\nNODE_OPTIONSElectron inclut le support pour un sous-ensemble des NODE_OPTIONS de Node. La majorité sont supportés à l'exception de celles qui rentrent en conflit avec l'utilisation de BoringSSL dans Chronium.
Exemple :
\nexport NODE_OPTIONS=\"--no-warnings --max-old-space-size=2048\"\nLes options non supportées sont :
\n--use-bundled-ca\n--force-fips\n--enable-fips\n--openssl-config\n--use-openssl-ca\nLes NODE_OPTIONS sont strictement interdites dans les applications compilées :
--max-http-header-size\n--http-parser\nGOOGLE_API_KEYGeolocation support in Electron requires the use of Google Cloud Platform's geolocation webservice. To enable this feature, acquire a Google API key and place the following code in your main process file, before opening any browser windows that will make geolocation requests:
\nprocess.env.GOOGLE_API_KEY = 'VOTRE_CLE_ICI'\nBy default, a newly generated Google API key may not be allowed to make geolocation requests. To enable the geolocation webservice for your project, enable it through the API library.
\nN.B. You will need to add a Billing Account to the project associated to the API key for the geolocation webservice to work.
\nELECTRON_NO_ASARDisables ASAR support. This variable is only supported in forked child processes and spawned child processes that set ELECTRON_RUN_AS_NODE.
ELECTRON_RUN_AS_NODEDémarre le processus comme un processus normal de Node.js.
\nIn this mode, you will be able to pass cli options to Node.js as you would when running the normal Node.js executable, with the exception of the following flags:
\nThese flags are disabled owing to the fact that Electron uses BoringSSL instead of OpenSSL when building Node.js' crypto module, and so will not work as designed.
ELECTRON_NO_ATTACH_CONSOLE WindowsNe s'attache pas la session courante de la console.
\nELECTRON_FORCE_WINDOW_MENU_BAR LinuxN'utilise pas la bar de menu global sur Linux.
\nELECTRON_TRASH LinuxSet the trash implementation on Linux. Par défaut la valeur est gio.
Options :
\ngvfs-trashtrash-clikioclient5kioclientLes variables d'environnement suivantes sont destinés principalement pour le développement et le débogage.
\nELECTRON_ENABLE_LOGGINGPrints Chromium's internal logging to the console.
\nSetting this variable is the same as passing --enable-logging on the command line. For more info, see --enable-logging in command-line switches.
ELECTRON_LOG_FILESets the file destination for Chromium's internal logging.
\nSetting this variable is the same as passing --log-file on the command line. For more info, see --log-file in command-line switches.
ELECTRON_DEBUG_DRAG_REGIONSAdds coloration to draggable regions on BrowserViews on macOS - draggable regions will be colored green and non-draggable regions will be colored red to aid debugging.
ELECTRON_DEBUG_NOTIFICATIONSAdds extra logs to Notification lifecycles on macOS to aid in debugging. Extra logging will be displayed when new Notifications are created or activated. They will also be displayed when common a tions are taken: a notification is shown, dismissed, its button is clicked, or it is replied to.
Sample output:
\nNotification created (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification displayed (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification activated (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification replied to (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nELECTRON_LOG_ASAR_READSWhen Electron reads from an ASAR file, log the read offset and file path to the system tmpdir. The resulting file can be provided to the ASAR module to optimize file ordering.
ELECTRON_ENABLE_STACK_DUMPINGAffiche la stack trace sur la console lorsqu'Electron plante.
\nCette variable d'environnement ne fonctionnera pas si vous avez démarré crashReporter.
ELECTRON_DEFAULT_ERROR_MODE WindowsAffiche la boite de dialogue de plantage lorsqu'Electron plante.
\nCette variable d'environnement ne fonctionnera pas si vous avez démarré crashReporter.
ELECTRON_OVERRIDE_DIST_PATHQuand lancée depuis le paquet electron , cette variable dit à la commande d'electron d'utiliser la version spécifiée au lieu de celle intallée avec npm install. Utilisation:
export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing\nElectron sets some variables in your environment at runtime.
\nORIGINAL_XDG_CURRENT_DESKTOPThis variable is set to the value of XDG_CURRENT_DESKTOP that your application originally launched with. Electron sometimes modifies the value of XDG_CURRENT_DESKTOP to affect other logic within Chromium so if you want access to the original value you should look up this environment variable instead.
GlobalEventpreventDefault VoidFunctionSome of Electrons APIs are tagged with _Experimental_ in the documentation. This tag indicates that the API may not be considered stable and the API may be removed or modified more frequently than other APIs with less warning.
Anyone can request an API be tagged as experimental in a feature PR, disagreements on the experimental nature of a feature can be discussed in the API WG if they can't be resolved in the PR.
\nOnce an API has been stable and in at least two major stable release lines it can be nominated to have its experimental tag removed. This discussion should happen at an API WG meeting. Things to consider when discussing / nominating:
\nid Stringmanifest any - Copy of the extension's manifest data.name Stringpath String - The extension's file path.version Stringurl String - The extension's chrome-extension:// URL.name Stringversion StringElectron supports a subset of the Chrome Extensions API, primarily to support DevTools extensions and Chromium-internal extensions, but it also happens to support some other extension capabilities.
\n\n\nNote: Electron does not support arbitrary Chrome extensions from the store, and it is a non-goal of the Electron project to be perfectly compatible with Chrome's implementation of Extensions.
\n
Electron only supports loading unpacked extensions (i.e., .crx files do not work). Extensions are installed per-session. To load an extension, call ses.loadExtension:
const { session } = require('electron')\n\nsession.loadExtension('path/to/unpacked/extension').then(({ id }) => {\n // ...\n})\nLoaded extensions will not be automatically remembered across exits; if you do not call loadExtension when the app runs, the extension will not be loaded.
Notez que le chargement d'extensions n'est pris en charge que dans les sessions persistantes. Tenter de charger une extension dans une session en mémoire générera une erreur.
\nSee the session documentation for more information about loading, unloading, and querying active extensions.
Nous prenons en charge les API d'extensions suivantes, avec quelques mises en garde. Other APIs may additionally be supported, but support for any APIs not listed here is provisional and may be removed.
\nchrome.devtools.inspectedWindowToutes les fonctionnalités de cette API sont prises en charge.
\nchrome.devtools.networkToutes les fonctionnalités de cette API sont prises en charge.
\nchrome.devtools.panelsToutes les fonctionnalités de cette API sont prises en charge.
\nchrome.extensionLes propriétés suivantes de chrome.extension sont prises en charge :
chrome.extension.lastErrorLes méthodes suivantes de chrome.extension sont prises en charge :
chrome.extension.getURLchrome.extension.getBackgroundPagechrome.runtimeLes propriétés suivantes de chrome.runtime sont prises en charge :
chrome.runtime.lastErrorchrome.runtime.idLes méthodes suivantes de chrome.runtime sont prises en charge :
chrome.runtime.getBackgroundPagechrome.runtime.getManifestchrome.runtime.getPlatformInfochrome.runtime.getURLchrome.runtime.connectchrome.runtime.sendMessagechrome.runtime.reloadLes événements suivants de chrome.runtime sont pris en charge :
chrome.runtime.onStartupchrome.runtime.onInstalledchrome.runtime.onSuspendchrome.runtime.onSuspendCanceledchrome.runtime.onConnectchrome.runtime.onMessagechrome.storageOnly chrome.storage.local is supported; chrome.storage.sync and chrome.storage.managed are not.
chrome.tabsLes méthodes suivantes de chrome.tabs sont prises en charge :
chrome.tabs.sendMessagechrome.tabs.executeScript\n\nNote: In Chrome, passing
\n-1as a tab ID signifies the \"currently active tab\". Since Electron has no such concept, passing-1as a tab ID is not supported and will raise an error.
chrome.managementLes méthodes suivantes de chrome.management sont prises en charge :
chrome.management.getAllchrome.management.getchrome.management.getSelfchrome.management.getPermissionWarningsByIdchrome.management.getPermissionWarningsByManifestchrome.management.onEnabledchrome.management.onDisabledchrome.webRequestToutes les fonctionnalités de cette API sont prises en charge.
\n\n", "title": "Chrome Extension Support", "description": "Note: Electron does not support arbitrary Chrome extensions from the store, and it is a non-goal of the Electron project to be perfectly compatible with Chrome's implementation of Extensions." }, "/docs/faq": { "locale": "fr-FR", "slug": "faq", "href": "/docs/faq", "crowdinFileId": "256121", "githubUrl": "https://github.com/electron/electron/tree/main/docs/faq.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "REMARQUE : Le module
\nwebRequestd’Electron est prioritaire surchrome.webRequesten cas de conflit de gestionnaires.
Lorsque vous exécutez npm install electron, certains utilisateurs rencontrent parfois des erreurs d'installation.
Dans la plupart des cas, ces erreurs sont le résultat d'un problème de réseau et non un soucis avec le packet npm electron. Les erreurs comme ELIFECYCLE, EAI_AGAIN, ECONNRESET et ETIMEDOUT sont toutes des indications d'un problème de réseau. La meilleure solution est d'essayer en changeant de réseau ou juste d'attendre un peu et de réessayer l'installation.
Vous pouvez également essayer de télécharger Electron directement depuis electron/electron/releases si l'installation via npm ne marche pas.
La version Chrome d'Electron est généralement mise à jour entre une et deux semaines après qu'une nouvelle mise à jour stable de Chrome soit disponible. Cette estimation n'est toutefois pas garantie et dépend de l'effort nécessaire pour faire la mise à jour.
\nSeul le canal stable de Chrome est utilisé. If an important fix is in beta or dev channel, we will back-port it.
\nPour plus d'informations, veuillez voir l'introduction à la sécurité.
\nQuand une nouvelle version de Node.js est disponible, nous attendons généralement un mois avant de faire la mise à jour du Node.js d'Electron. Ainsi nous évitons d'être affectés par des bugs introduits dans les nouvelles versions de Node.js, ce qui arrive très souvent.
\nLes nouvelles fonctionnalités de Node.js sont généralement ajoutées dans les mises à jour de V8. Depuis qu'Electron utilise la V8 du navigateur Chrome, les nouvelles fonctionnalités JavaScript d'une nouvelle version de Node.js sont généralement déjà dans Electron.
\nPour partager des données entre les pages web (les processus de rendu), le moyen le plus simple est d'utiliser les APIs HTML5 qui sont déjà disponibles dans les navigateurs. Les bons candidats sont API Storage, localStorage, sessionStorage et IndexedDB.
Alternatively, you can use the IPC primitives that are provided by Electron. To share data between the main and renderer processes, you can use the ipcMain and ipcRenderer modules. To communicate directly between web pages, you can send a MessagePort from one to the other, possibly via the main process using ipcRenderer.postMessage(). Subsequent communication over message ports is direct and does not detour through the main process.
Cela se produit lorsque la variable qui sert à stocker la fenêtre/icône est détruite par le ramasse-miettes.
\nSi vous rencontrez ce problème, les articles suivants peuvent s'avérer utiles :
\n\nSi vous voulez une solution rapide, vous pouvez mettre les variables en globale en changeant votre code comme celui-ci :
\nconst { app, Tray } = require('electron')\napp.whenReady().then(() => {\n const tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\npour cela :
\nconst { app, Tray } = require('electron')\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\nEn raison de l'intégration de Node.js dans Electron, il y a quelques symboles supplémentaires insérés dans le DOM comme module, exports, require. Cela pose des problèmes pour certaines bibliothèques, puisqu'ils veulent insérer des symboles avec les mêmes noms.
Pour résoudre ce problème, vous pouvez désactiver l'intégration de node dans Electron :
\n// Dans le processus main.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n webPreferences: {\n nodeIntegration: false\n }\n})\nwin.show()\nMais si vous voulez garder la possibilité d'utiliser Node.js et l'API Electron, vous devez renommer les symboles dans la page avant d’inclure d'autres bibliothèques :
\n<head>\n<script>\nwindow.nodeRequire = require;\ndelete window.require;\ndelete window.exports;\ndelete window.module;\n</script>\n<script type=\"text/javascript\" src=\"jquery.js\"></script>\n</head>\nrequire('electron').xxx is undefined.Lorsque vous utilisez le module intégré d'Electron, vous pouvez obtenir une erreur comme celle-ci :
\n> require('electron').webFrame.setZoomFactor(1.0)\nUncaught TypeError: Cannot read property 'setZoomLevel' of undefined\nIl est très probable que vous utilisez le module dans le mauvais processus. Par exemple electron.app peut seulement être utilisé dans le processus principal, tandis que electron.webFrame n'est disponible que dans les processus de rendu.
Si sub-pixel anti-aliasing est désactivé sur les écrans LCD les polices peuvent être floues. Exemple . Exemple :
\n
L'anticrénelage des sous-pixels nécessite un fond non transparent pour la fenêtre contenant les glyphes d'une police d'écriture. (Voir cette issue pour plus d'infos).
\nTo achieve this goal, set the background in the constructor for BrowserWindow:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n backgroundColor: '#fff'\n})\nL'effet n'est visible que sur (certains?) Écrans LCD. Even if you don't see a difference, some of your users may. It is best to always set the background this way, unless you have reasons not to do so.
\nVeuillez noter que simplement paramétrer la couleur de fond avec le CSS ne donnera pas l'effet souhaité.
", "title": "FAQ Electron", "description": "" }, "/docs/api/structures/file-filter": { "locale": "fr-FR", "slug": "file-filter", "href": "/docs/api/structures/file-filter", "crowdinFileId": "256435", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/file-filter.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "name Stringextensions String[]File\n\nUse the HTML5
\nFileAPI to work natively with files on the filesystem.
L'interface de fichier du DOM fournit une abstraction autour des fichiers natifs afin de permettre aux utilisateurs de travailler sur des fichiers natifs directement avec l'API HTML5 File. Electron a ajouté un attribut path à l'interface File qui expose le chemin réel du fichier sur le système de fichiers.
Exemple pour obtenir le chemin réel d'un fichier glissé dans l'application :
\n<div id=\"holder\">\n Faites glisser votre fichier ici\n</div>\n\n<script>\n document. ddEventListener('drop', (e) => {\n e. reventDefault();\n e.stopPropagation();\n\n for (const f of e. ataTransfer.files) {\n console. og('Fichier(s) que vous avez glissé ici : ', f.path)\n }\n });\n document. ddEventListener('dragover', (e) => {\n e.preventDefault();\n e.stopPropagation();\n });\n</script>\npath String - The path to the file to send.headers Record<string, string> (optional) - Additional headers to be sent.\n\nOuvre une fenêtre sans barre d'outils, sans bordures ou autre \"chrome\" graphique.
\n
Une fenêtre sans cadre est une fenêtre qui n'a pas de chrome, les parties de la fenêtre, comme des barres d'outils, qui ne font pas partie de la page Web. Ce sont des options dans la classe BrowserWindow.
Pour créer une fenêtre sans cadre, vous devez définir frame à false dans BrowserWindow's options:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600, frame: false })\nwin.show()\nThere's an alternative way to specify a chromeless window on macOS and Windows. Instead of setting frame to false which disables both the titlebar and window controls, you may want to have the title bar hidden and your content extend to the full window size, yet still preserve the window controls (\"traffic lights\" on macOS) for standard window actions. Vous pouvez le faire en spécifiant l'option titleBarStyle :
hiddenResults in a hidden title bar and a full size content window. On macOS, the title bar still has the standard window controls (“traffic lights”) in the top left.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hidden' })\nwin.show()\nhiddenInsetRésultats dans une barre de titre cachée avec un aspect alternatif où les boutons de feux de circulation sont un peu plus intégrés à partir du bord de la fenêtre.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })\nwin.show()\ncustomButtonsOnHoverUtilise les boutons personnalisés de fermeture dessinée, et miniaturise les boutons qui affichent en survolant en haut à gauche de la fenêtre. The fullscreen button is not available due to restrictions of frameless windows as they interface with Apple's macOS window masks. Ces boutons personnalisés empêchent les problèmes liés aux événements de la souris qui se produisent avec les boutons standard de la barre d'outils de la fenêtre. Cette option n'est applicable que pour les fenêtres sans cadres.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover', frame: false })\nwin.show()\nWhen using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS, using one of the titleBarStyles as described above so that the traffic lights are visible, or using titleBarStyle: hidden on Windows, you can access the Window Controls Overlay JavaScript APIs and CSS Environment Variables by setting the titleBarOverlay option to true. Specifying true will result in an overlay with default system colors.
On Windows, you can also specify the color of the overlay and its symbols by setting titleBarOverlay to an object with the options color and symbolColor. If an option is not specified, the color will default to its system color for the window control buttons:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: true\n})\nwin.show()\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: {\n color: '#2f3241',\n symbolColor: '#74b1be'\n }\n})\nwin.show()\nEn définissant l'option transparente à true, vous pouvez également rendre la fenêtre sans cadre transparente :
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ transparent: true, frame: false })\nwin.show()\nresizable to true may make a transparent window stop working on some platforms.flur ne s'applique qu'à la page web, donc il n'y a aucun moyen d'appliquer l'effet de flou au contenu en dessous de la fenêtre (i. . d'autres applications s'ouvrent sur le système de l'utilisateur).--enable-transparent-visuals --disable-gpu dans la ligne de commande pour désactiver le GPU et permettre à ARGB de rendre une fenêtre transparente, ceci est causé par un bogue amont que canal alpha ne fonctionne pas sur certains pilotes NVidia sur Linux.Pour créer une fenêtre non cliquable, c'est-à-dire faire en sorte que la fenêtre ignore tous les événements de la souris, vous pouvez appeler l'API win.setIgnoreMouseEvents(ignore) :
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.setIgnoreMouseEvents(true)\nIgnorer les messages de la souris rend la page Web inaccessible au mouvement de la souris, ce qui signifie que les événements de déplacement de la souris ne seront pas émis. Sur les systèmes d'exploitation Windows, un paramètre optionnel peut être utilisé pour déplacer les messages de la souris vers la page web, permettant d'émettre des événements tels que souris :
const { ipcRenderer } = require('electron')\nconst el = document.getElementById('clickThroughElement')\nel.addEventListener('mouseenter', () => {\n ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })\n})\nel.addEventListener('mouseleave', () => {\n ipcRenderer.send('set-ignore-mouse-events', false)\n})\n\n// Main process\nconst { ipcMain } = require('electron')\nipcMain.on('set-ignore-mouse-events', (event, ...args) => {\n BrowserWindow.fromWebContents(event.sender).setIgnoreMouseEvents(...args)\n})\nCela rend la page web cliquante quand plus de el, et retourne à la normale en dehors de elle.
Par défaut, la fenêtre sans cadre ne peut pas être déplacée. Les applications doivent spécifier -webkit-app-region: glisser dans CSS pour dire à Electron quelles régions sont glissables (comme la barre de titre standard de l'OS), et les applications peuvent également utiliser -webkit-app-region : no-drag pour exclure la zone non glissable de la région glissable. Notez que seules les formes rectangulaires sont actuellement prises en charge.
Remarque : -webkit-app-region: drag est connu pour avoir des problèmes pendant que les outils de développement sont ouverts. Voir ceci Problème GitHub pour plus d'informations, y compris une solution de contournement.
Pour que toute la fenêtre puisse être déplacée, vous pouvez ajouter -webkit-app-region : glisser comme body's style :
<body style=\"-webkit-app-region: drag\">\n</body>\nEt notez que si vous avez rendu toute la fenêtre déplaçable, vous devez également marquer les boutons comme non glissables, sinon il serait impossible pour les utilisateurs de cliquer sur eux :
\nbutton {\n -webkit-app-region: no-drag;\n}\nSi vous définissez seulement une barre de titre personnalisée comme glissable, vous devez également rendre tous les boutons de la barre de titre non glissables.
\nIn a frameless window the dragging behavior may conflict with selecting text. Par exemple, lorsque vous faites glisser la fenêtre depuis la barre de titre, vous pouvez accidentellement sélectionner son texte. Afin d'éviter cela, vous devez désactiver la sélection de texte dans une zone déplaçable. Comme ceci :
\n.titlebar {\n -webkit-user-select: none;\n -webkit-app-region: drag;\n}\nSur certaines plateformes, la zone glissable sera traitée comme une image non-client, donc lorsque vous faites un clic droit dessus un menu système apparaîtra. Pour que le menu contextuel se comporte correctement sur toutes les plates-formes, vous ne devriez jamais utiliser un menu contextuel personnalisé sur zones glissables.
", "title": "Fenêtre sans bords", "description": "Ouvre une fenêtre sans barre d'outils, sans bordures ou autre \"chrome\" graphique." }, "/docs/tutorial/fuses": { "locale": "fr-FR", "slug": "fuses", "href": "/docs/tutorial/fuses", "crowdinFileId": "256201", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/fuses.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nActivation de fonctionnalités au moment du packaging
\n
Pour n'utiliser qu'un sous-ensemble de fonctionnalités d'Electron, il semble logique de désactiver certaines fonctionnalités pour l'ensemble d'une application. Par exemple, 99% des applications n'utilisent pas ELECTRON_RUN_AS_NODE, leurs concepteurs veulent être en mesure de livrer un exécutable qui n'utilise pas cette fonctionnalité. Nous ne voulons pas non plus que les utilisateurs d'Electron génère Electron à partir des sources car ce serait à la fois un défi technique énorme et aurait un coût élevé que ce soit en temps ou en argent.
Les fuses sont la solution à ce problème, à un haut niveau, ils sont des \"bits magiques\" dans l'exécutable d'Electron qui peuvent être activés ou non au moment du packaging de votre application Electron pour activer ou désactiver certaines fonctionnalités ou restrictions. Comme ils sont activés au moment du packaging et donc avant que vous ne signiez votre application, l'OS devient responsable de s'assurer que ces bits n'ont pas été désactivés via la validation du code du système d'exploitation (Gatekeeper / App Locker).
\nNous avons créé un module pratique @electron/fuses pour faciliter l'activation de ces fuses. Consultez le README de ce module pour plus de détails sur l'utilisation et les éventuels cas d'erreur.
require('@electron/fuses').flipFuses(\n // Chemin vers electron\n require('electron'),\n // Les Fuses à activer\n {\n runAsNode: false\n }\n)\nPour activer les fuses manuellement, il est nécessaire d'éditer le binaire d'Electron et modifier la séquence d'octets du fuse wire pour qu'elle représente l'état des fuses désiré.
\nQuelque part dans le binaire Electron, il y a une séquence d'octets qui ressembler à ceci :
\n| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |\nsentinel_bytes est toujours exactement cette chaîne dL7pKGdnNz796PbbjQWNKmHXBZaB9tsXfuse_version est un seul octet dont la valeur de type unsigned integer représente la version du schéma du fusefuse_wire_length est un seul octet dont la valeur de type unsigned integer représente le nombre de fuses dans le fuse wirefuse_wire est une séquence de N octets, chaque octet représentant un seul fuse et son état.Pour actionner un fuse, vous devez trouver sa position dans le fuse wire et le mettre à \"0\" ou \"1\" selon l'état que vous désirez.
\nVous pouvez voir le schéma actuel ici.
", "title": "Electron Fuses", "description": "Activation de fonctionnalités au moment du packaging" }, "/docs/api/global-shortcut": { "locale": "fr-FR", "slug": "global-shortcut", "href": "/docs/api/global-shortcut", "crowdinFileId": "256323", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/global-shortcut.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nDétecte les événements de clavier lorsque l'application n'a pas le focus du clavier.
\n
Processus : Main
\nLe module globalShortcut peut inscrire/désinscrire un raccourci clavier global avec le système d'exploitation afin que vous puissiez personnaliser les opérations pour les différents raccourcis.
Remarque : Le raccourci est global; il fonctionnera même si l'application n'a pas le focus du clavier. This module cannot be used before the ready event of the app module is emitted.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+X' shortcut listener.\n const ret = globalShortcut.register('CommandOrControl+X', () => {\n console.log('CommandOrControl+X is pressed')\n })\n\n if (!ret) {\n console.log('enregistrement échoué')\n }\n\n // Check si le raccourci est enregistré.\n console.log(globalShortcut.isRegistered('CommandOrControl+X'))\n})\n\napp.on('will-quit', () => {\n // Retire le raccourci.\n globalShortcut.unregister('CommandOrControl+X')\n\n // Supprime tous les raccourcis.\n globalShortcut.unregisterAll()\n})\nLe module globalShortcut dispose des méthodes suivantes :
globalShortcut.register(accelerator, callback)accelerator Acceleratorcallback FunctionRetourne Boolean - Si le raccourci a été enregistré avec succès.
Registers a global shortcut of accelerator. The callback is called when the registered shortcut is pressed by the user.
Lorsque l'accélérateur est déjà utilisé par d'autres applications, cet appel échouera silencieusement. Ce comportement est prévu par les systèmes d'exploitation, car ils ne veulent pas que les applications se battent pour des raccourcis globaux.
\nLes accélérateurs suivants ne seront pas enregistrés correctement sur macOS 10.14 Mojave à moins que l'application ait été autorisée en tant qu'application client approuvée :
\nglobalShortcut.registerAll(accélérateurs, callback)accélérateur String[] - un tableau de Accelerators.callback FunctionRegisters a global shortcut of all accelerator items in accelerators. The callback is called when any of the registered shortcuts are pressed by the user.
Lorsqu'un accélérateur donné est déjà pris par d'autres applications, cet appel échouera silencieusement. Ce comportement est prévu par les systèmes d'exploitation, car ils ne veulent pas que les applications se battent pour des raccourcis globaux.
\nLes accélérateurs suivants ne seront pas enregistrés correctement sur macOS 10.14 Mojave à moins que l'application ait été autorisée en tant qu'application client approuvée :
\nglobalShortcut.isRegistered(accelerator)accelerator AcceleratorRetourne un Boolean - Si l'application à enregistrer l'accelerator.
Lorsque l'accelerator est déjà utilisé par d'autres applications, cet appel retournera toujours false. Ce comportement est prévu par les systèmes d'exploitation, car ils ne veulent pas que les applications se battent pour des raccourcis globaux.
globalShortcut.unregister(accelerator)accelerator AcceleratorSupprime le raccourci global de l'accelerator.
globalShortcut.unregisterAll()Supprime tous les raccourcis globaux.
", "title": "globalShortcut", "description": "Détecte les événements de clavier lorsque l'application n'a pas le focus du clavier." }, "/docs/glossary": { "locale": "fr-FR", "slug": "glossary", "href": "/docs/glossary", "crowdinFileId": "256123", "githubUrl": "https://github.com/electron/electron/tree/main/docs/glossary.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Cette page définit certaines terminologies qui sont couramment utilisées dans le développement d'Electron.
\nASAR signifie Atom Shell Archive Format. Une archive asar est un simple fichier .tar, comme le format de compression de fichiers. Electron peut lire les fichiers sans avoir à décompresser l'archive.
Le format ASAR a été créé principalement pour améliorer les performances sous Windows lorsque il y a de grandes quantités de petits fichiers ( par ex. lors du chargement de l'arborescence des dépendances JavaScript de votre application depuis node_modules).
La signature de code est un processus où un développeur d'applications signe numériquement son code pour assurer qu'il n'a pas été altéré après l'empaquetage. Windows et macOS implémentent leur propre version de signature de code. En tant que développeur d'applications de bureau, il est important que vous signiez votre code si vous prévoyez de le distribuer au grand public.
\nPour plus d'informations, lisez le tutoriel Signature de code.
\nL’isolation de contexte est une mesure de sécurité d'Electron qui garantit que votre script de préchargement(preload) ne peut pas permettre que le site web contenu dans le WebContent n'accède aux API d’Électron ou de Node.js. Avec l'isolement de contexte activé, le seul moyen d'exposer les API de votre script de préchargement est de passer par l'API contextBridge.
Pour plus d'informations, lisez le tutoriel Isolation du contexte.
\nVoir aussi: script preload, processus de rendu
\nLa bibliothèque de Runtime C (CRT) est la partie de la bibliothèque Standard C++ intégrant la bibliothèque standard ISO C99. Les bibliothèques Visual C++ qui implémentent le CRT supportent le développement de code natif, de code mixte natif et managé ainsi que le code managé pur pour le développement .NET.
\nUne Image disque Apple est un format de package utilisé par macOS. Les fichiers DMG sont couramment utilisés pour distribuer un « installateur » d'une application.
\nÉditeur de méthode d'entrée (Input Method Editor). Un programme qui permet aux utilisateurs d'entrer des caractères et des symboles n'existant pas sur leur clavier. Par exemple, cela permet aux utilisateurs de clavier Latin d'entrer des caractères chinois, japonais, coréen et hindi.
\nInterface description language. Décrit les signatures des fonctions et des types de données dans un format qui peut être utilisé pour générer des interfaces en Java, C++, JavaScript, etc.
\nIPC signifie communication inter-processus. Electron utilise les IPC pour envoyer des messages sérialisés en JSON entre le processus principal et les processus de rendu.
\nvoir aussi : processus principal, processus de rendu
\nLe processus principal, généralement un fichier nommé main.js, est le point d'entrée de chaque application Electron. Il contrôle la vie de l'application, de l'ouverture à la fermeture. Il gère également les éléments natifs tels que le Menu, Menu Bar, Dock, Tray, etc. The main process is responsible for creating each new renderer process in the app. L'API complète de Node est intégrée.
Every app's main process file is specified in the main property in package.json. This is how electron . knows what file to execute at startup.
In Chromium, this process is referred to as the \"browser process\". It is renamed in Electron to avoid confusion with renderer processes.
\nVoir aussi : processus, processus de rendu
\nAcronym for Apple's Mac App Store. Pour plus de détails sur la soumission de votre application au MAS, consultez le Guide de soumission du Mac App Store.
\nUn système IPC pour la communication intra - ou inter-processus, et c’est important car Chrome a tendance à diviser ses tâches dans des processus distincts ou non, en fonction des contraintes de mémoire etc.
\nVoir https://chromium.googlesource.com/chromium/src/+/master/mojo/README.md
\nVoir aussi: IPC
\nSous Windows, les paquets MSI sont utilisés par le service Windows Installer (également connu sous le nom d'installateur Microsoft) pour installer et configurer des applications .
\nPlus d'informations peuvent être trouvées dans la documentation de Microsoft.
\nLes modules natifs (également appelés addons dans Node.js) sont des modules écrits en C ou C++ qui peuvent être chargés dans Node.js ou Electron à l'aide de la fonction require() et sont utilisés comme si ils étaient des modules ordinaires de Node.js. Ils sont utilisés principalement pour fournir une interface entre JavaScript s’exécutant dans les librairies Node.js et C/C++.
\nLes modules natifs de Node sont pris en charge par Electron, mais étant donné qu'Electron est très susceptible d'utiliser une version différente de V8 du binaire Node installée sur votre système. Vous devez spécifier manuellement l'emplacement des en-têtes d'Electron, lors de la compilation de modules natifs.
\nPour plus d'informations, lisez le tutoriel [Modules de Node Natif].
\nNotarization is a macOS-specific process where a developer can send a code-signed app to Apple servers to get verified for malicious components through an automated service.
\nSee also: code signing
\nOSR (offscreen rendering) can be used for loading heavy page in background and then displaying it after (it will be much faster). It allows you to render page without showing it on screen.
\nFor more information, read the Offscreen Rendering[osr] tutorial.
\nPreload scripts contain code that executes in a renderer process before its web contents begin loading. These scripts run within the renderer context, but are granted more privileges by having access to Node.js APIs.
\nSee also: renderer process, context isolation
\nUn processus est une instance d'un programme d'ordinateur en execution. Les apps Electron qui utilisent le processus principal et un ou plusieurs processus de rendu font tourner plusieurs programmes en même temps.
\nDans Node.js et Electron, chaque processus en execution ont un objet processus. Cet objet global donne des informations et permet de contrôler le processus current. Comme une variable global, cet objet est disponible dans l'application sans utiliser require().
Voir aussi : processus principal, processus de rendu
\nLe processus de rendu est une fenêtre de navigateur dans votre application. Contrairement au processus principal, il peut y en avoir plusieurs et chacun est exécuté dans un processus distinct. Ils peuvent également être cachés.
\nVoir aussi : processus, processus principal
\nLe bac à sable est une fonctionnalité de sécurité héritée de Chromium qui limite vos processus de rendu à un ensemble limité d'autorisations.
\nFor more information, read the Process Sandboxing tutorial.
\nSee also: process
\nSquirrel est un framework open-source permettant aux apps Electron de se mettre à jour automatiquement quand une nouvelle version est disponible. Voir l'API autoUpdater pour plus d’informations sur comment démarrer avec Squirrel.
\nCe terme provient de la communauté Unix, où « userland » ou « userspace » fait référence aux programmes qui s’exécutent en dehors du noyau de système d’exploitation. Plus récemment, le terme a été popularisé dans Node et la communauté npm afin d’établir une distinction entre les fonctionnalités disponibles dans « Node core » par rapport aux paquets publié au registre npm par une grande majorité « d'utilisateurs » de la communauté.
\nComme Node, Electron se concentre sur le fait d'avoir un petit ensemble d'APIs qui fournissent tout le nécessaire primaire pour développer des applications de bureau multiplateformes. Cette philosophie de conception permet à Electron de rester un outil souple sans être trop normative sur la façon dont il doit être utilisé. L'Userland permet aux utilisateurs de créer et partager des outils qui fournissent des fonctionnalités supplémentaires au dessus de ce qui est disponible dans le « noyau ».
\nV8 est le moteur JavaScript open source de Google. Il est écrit en C++ et est utilisé dans Google Chrome. V8 can run standalone, or can be embedded into any C++ application.
\nElectron compile V8 de Chromium et fait pointer Node à ce V8 pendant la compilation.
\nV8's version numbers always correspond to those of Google Chrome. Chrome 59 includes V8 5.9, Chrome 58 includes V8 5.8, etc.
\n\nwebview tags are used to embed 'guest' content (such as external web pages) in your Electron app. They are similar to iframes, but differ in that each webview runs in a separate process. Il n’a pas les mêmes autorisations que votre page web et toutes les interactions entre votre application et le contenu incorporé seront asynchrones. Cela protège votre application du contenu incorporé.
\n\nGoma est un service de compilation distribué pour les projets open source tels que Chrome et Android.
\n
Electron has a deployment of a custom Goma Backend that we make available to all Electron Maintainers. See the Access section below for details on authentication. There is also a cache-only Goma endpoint that will be used by default if you do not have credentials. Requests to the cache-only Goma will not hit our cluster, but will read from our cache and should result in significantly faster build times.
Currently the only supported way to use Goma is to use our Build Tools. La configuration de Goma est automatiquement incluse lorsque vous configurez build-tools.
If you are a maintainer and have access to our cluster, please ensure that you run e init with --goma=cluster in order to configure build-tools to use the Goma cluster. If you have an existing config, you can just set \"goma\": \"cluster\" in your config file.
When you are using Goma you can run ninja with a substantially higher j value than would normally be supported by your machine.
Veuillez ne pas définir une valeur supérieure à 200 sous Windows ou Linux et 50 sur macOS. We monitor Goma system usage, and users found to be abusing it with unreasonable concurrency will be de-activated.
\nninja -C out/Testing electron -j 200\nIf you're using build-tools, appropriate -j values will automatically be used for you.
Si vous accédez à http://localhost:8088 sur votre machine, vous pouvez surveiller les tâches de compilation au fur et à mesure qu'elles transitent par le système goma.
\nPour des raisons de sécurité et de coût, l'accès au cluster Goma d'Electron est actuellement restreint aux mainteneurs d'Electron. Si vous souhaitez y accéder, rendez-vous sur #access-requests dans Slack et ping @goma-squad pour demander l'accès. Please be aware that being a maintainer does not automatically grant access and access is determined on a case by case basis.
Nous avons une surveillance automatisée de notre cluster et de notre cache Goma sur https://status.notgoma.com
\nWe do not provide support for usage of Goma and any issues raised asking for help / having issues will probably be closed without much reason, we do not have the capacity to handle that kind of support.
", "title": "Goma", "description": "Goma est un service de compilation distribué pour les projets open source tels que Chrome et Android." }, "/docs/api/structures/gpu-feature-status": { "locale": "fr-FR", "slug": "gpu-feature-status", "href": "/docs/api/structures/gpu-feature-status", "crowdinFileId": "256439", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/gpu-feature-status.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "2d_canvas String - Canvas.flash_3d String - Flash.flash_stage3d String - Flash Stage3D.flash_stage3d_baseline String - Flash Stage3D Baseline profile.gpu_compositing String - Compositing.multiple_raster_threads String - Multiple Raster Threads.native_gpu_memory_buffers String - Native GpuMemoryBuffers.rasterization String - Rasterization.video_decode String - Video Decode.video_encode String - Video Encode.vpx_decode String - VPx Video Decode.webgl String - WebGL.webgl2 String - WebGL2.Valeurs possibles :
\ndisabled_software - Software only. Hardware acceleration disabled (yellow)disabled_off - Disabled (red)disabled_off_ok - Disabled (yellow)unavailable_software - Software only, hardware acceleration unavailable (yellow)unavailable_off - Unavailable (red)unavailable_off_ok - Unavailable (yellow)enabled_readback - Hardware accelerated but at reduced performance (yellow)enabled_force - Hardware accelerated on all pages (green)enabled - Hardware accelerated (green)enabled_on - Enabled (green)enabled_force_on - Force enabled (green)deviceId String - Unique identifier for the device.name String - Name of the device.vendorId Integer - The USB vendor ID.productId Integer - The USB product ID.serialNumber String (optional) - The USB device serial number.guid String (optional) - Unique identifier for the HID interface. A device may have multiple HID interfaces.\n\nAchats inApp sur l'Apple Store.
\n
Processus : Main
\nLe module inAppPurchase émet les événements suivants :
Émis lorsqu’une ou plusieurs transactions ont été mises à jour.
\nRetourne :
\nevent Eventtransactions Transaction[] - Tableau d'objets Transaction.Le module inAppPurchase possède les méthodes suivantes :
inAppPurchase.purchaseProduct(productID[, quantity])productID String - Les identifiants du produit à acheter. (L'identifiant de com.example.app.product1 est product1).quantity Integer (optionnel) - Le nombre d'items que l'utilisateur veut acheter.Returns Promise<Boolean> - Returns true if the product is valid and added to the payment queue.
Tu devrais écouter l'événement transactions-updated dès que possible et surement avant d'appeler purchaseProduct.
inAppPurchase.getProducts(productIDs)productIDs String[] - Les identifiants des produits à recevoir.Returns Promise<Product[]> - Resolves with an array of Product objects.
Retourne les descriptions des produits.
\ninAppPurchase.canMakePayments()Returns Boolean - whether a user can make a payment.
inAppPurchase.restoreCompletedTransactions()Restores finished transactions. This method can be called either to install purchases on additional devices, or to restore purchases for an application that the user deleted and reinstalled.
\nThe payment queue delivers a new transaction for each previously completed transaction that can be restored. Each transaction includes a copy of the original transaction.
\ninAppPurchase.getReceiptURL()Returns String - the path to the receipt.
inAppPurchase.finishAllTransactions()Termine toutes les transactions en cours.
\ninAppPurchase.finishTransactionByDate(date)date String - La date sous format ISO de la fin de la transaction.Termine les transactions correspondantes à la date.
", "title": "Achat inApp", "description": "Achats inApp sur l'Apple Store." }, "/docs/tutorial/in-app-purchases": { "locale": "fr-FR", "slug": "in-app-purchases", "href": "/docs/tutorial/in-app-purchases", "crowdinFileId": "256203", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/in-app-purchases.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "If you haven't already, you’ll need to sign the Paid Applications Agreement and set up your banking and tax information in iTunes Connect.
\niTunes Connect Developer Help: Agreements, tax, and banking overview
\nThen, you'll need to configure your in-app purchases in iTunes Connect, and include details such as name, pricing, and description that highlights the features and functionality of your in-app purchase.
\niTunes Connect Developer Help: Create an in-app purchase
\nTo test In-App Purchase in development with Electron you'll have to change the CFBundleIdentifier in node_modules/electron/dist/Electron.app/Contents/Info.plist. You have to replace com.github.electron by the bundle identifier of the application you created with iTunes Connect.
<key>CFBundleIdentifier</key>\n<string>com.example.app</string>\nHere is an example that shows how to use In-App Purchases in Electron. You'll have to replace the product ids by the identifiers of the products created with iTunes Connect (the identifier of com.example.app.product1 is product1). Note that you have to listen to the transactions-updated event as soon as possible in your app.
// Processus principal\nconst { inAppPurchase } = require('electron')\nconst PRODUCT_IDS = ['id1', 'id2']\n\n// Écouter les transactions dès que possible.\ninAppPurchase.on('transactions-updated', (event, transactions) => {\n if (!Array.isArray(transactions)) {\n return\n }\n\n // Check each transaction.\n transactions.forEach(function (transaction) {\n const payment = transaction.payment\n\n switch (transaction.transactionState) {\n case 'purchasing':\n console.log(`Purchasing ${payment.productIdentifier}...`)\n break\n\n case 'purchased': {\n console.log(`${payment.productIdentifier} purchased.`)\n\n // Get the receipt url.\n const receiptURL = inAppPurchase.getReceiptURL()\n\n console.log(`Receipt URL: ${receiptURL}`)\n\n // Submit the receipt file to the server and check if it is valid.\n // @see https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html\n // ...\n // If the receipt is valid, the product is purchased\n // ...\n\n // Terminer la transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n }\n\n case 'failed':\n\n console.log(`Failed to purchase ${payment.productIdentifier}.`)\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n case 'restored':\n\n console.log(`The purchase of ${payment.productIdentifier} has been restored.`)\n\n break\n case 'deferred':\n\n console.log(`The purchase of ${payment.productIdentifier} has been deferred.`)\n\n break\n default:\n break\n }\n })\n})\n\n// Check if the user is allowed to make in-app purchase.\nif (!inAppPurchase.canMakePayments()) {\n console.log('The user is not allowed to make in-app purchase.')\n}\n\n// Retrieve and display the product descriptions.\ninAppPurchase.getProducts(PRODUCT_IDS).then(products => {\n // Check the parameters.\n if (!Array.isArray(products) || products.length <= 0) {\n console.log('Unable to retrieve the product informations.')\n return\n }\n\n // Display the name and price of each product.\n products.forEach(product => {\n console.log(`The price of ${product.localizedTitle} is ${product.formattedPrice}.`)\n })\n\n // Ask the user which product he/she wants to purchase.\n const selectedProduct = products[0]\n const selectedQuantity = 1\n\n // Purchase the selected product.\n inAppPurchase.purchaseProduct(selectedProduct.productIdentifier, selectedQuantity).then(isProductValid => {\n if (!isProductValid) {\n console.log('The product is not valid.')\n return\n }\n\n console.log('The payment has been added to the payment queue.')\n })\n})\n\n\nGère les réponses aux requêtes HTTP/HTTPS.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
IncomingMessage Implémente l'interface Readable Stream et est donc un EventEmitter.
Retourne :
\nchunk Buffer - Un segment de données du corps de réponse.L'événement data est la méthode habituelle de transfert des données de réponse dans le code applicatif.
Indique que le corps de réponse est terminée. Must be placed before 'data' event.
\nÉmis lorsqu’une requête a été annulée lors d’une transaction HTTP en cours.
\nRetourne :
\nerror Error - Retourne généralement une chaîne de caractères d’erreur identifiant les causes d’échec.
Émis lorsqu’une erreur s’est produite pendant le transfert d’événements de données de réponse. Par exemple, si le serveur ferme la connexion alors que la réponse est toujours en transfert, un événement error retentit sur l’objet de réponse et un événement close suivra par la suite sur l’objet de la demande.
Une instance IncomingMessage possède les propriétés suivantes :
response.statusCodeUn Integer indiquant le code d'état de la réponse HTTP.
response.statusMessageUn String représentant le message d'état HTTP.
response.headersA Record<string, string | string[]> representing the HTTP response headers. The headers object is formatted as follows:
age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, server, or user-agent are discarded.set-cookie is always an array. Duplicates are added to the array.cookie headers, the values are joined together with '; '.response.httpVersionUn String indiquant le numéro de version du protocole HTTP. Les valeurs habituelles sont '1.0' ou '1.1'. De plus, httpVersionMajor et httpVersionMinor sont deux propriétés entières lisibles qui retournent respectivement les numéros de version principale et secondaire de HTTP.
response.httpVersionMajorUn Integerindiquant le numéro de version majeur du protocol HTTP.
response.httpVersionMinorUn Integer indiquant le numéro de version mineur du protocol HTTP.
modifiers String - An array of modifiers of the event, can be shift, control, ctrl, alt, meta, command, cmd, isKeypad, isAutoRepeat, leftButtonDown, middleButtonDown, rightButtonDown, capsLock, numLock, left, right.To install prebuilt Electron binaries, use npm. The preferred method is to install Electron as a development dependency in your app:
npm install electron --save-dev\nVoir la documentation du versionnage pour plus d'informations sur la façon de gérer différentes versions d'Electron dans vos applications.
\nIf you're in a pinch and would prefer to not use npm install in your local project, you can also run Electron ad-hoc using the npx command runner bundled with npm:
npx electron .\nLa commande ci-dessus exécutera le répertoire de travail actuel avec Electron. Note that any dependencies in your app will not be installed.
\nSi vous souhaitez modifier l'architecture qui est téléchargée (par exemple, ia32 sur une machine x64), vous pouvez utiliser le paramètre --arch avec npm install ou définir la variable d'environnement npm_config_arch :
npm install --arch=ia32 electron\nEn plus de modifier l'architecture, vous pouvez également spécifier la platforme (par exemple, win32, linux, etc.) en utilisant le paramètre --platform :
npm install --platform=win32 electron\nIf you need to use an HTTP proxy, you need to set the ELECTRON_GET_USE_PROXY variable to any value, plus additional environment variables depending on your host system's Node version:
Lors de l’installation, le module electron appellera @electron/get pour télécharger les binaires précompilés d’Electron pour votre plate-forme. Cela se fera en se connectant à la page GitHub des release (https://github.com/electron/electron/releases/tag/v$VERSION, ou $VERSION est la version exacte d'Electron).
Si vous êtes dans l'incapacité d'accéder à github ou si vous avez besoin de fournir un binaire personnalisé, vous pouvez aussi le faire en mettant à disposition un miroir ou un répertoire de cache existant.
\nVous pouvez utiliser des variables d’environnement pour substituer l’URL de base, le chemin d’accès où chercher les binaires d'Electron, et le nom du fichier binaire. The URL used by @electron/get is composed as follows:
url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME\nFor instance, to use the China CDN mirror:
\nELECTRON_MIRROR=\"https://cdn.npm.taobao.org/dist/electron/\"\nPar défaut, ELECTRON_CUSTOM_DIR est défini sur v$VERSION. To change the format, use the {{ version }} placeholder. For example, version-{{ version }} resolves to version-5.0.0, {{ version }} resolves to 5.0.0, and v{{ version }} is equivalent to the default. As a more concrete example, to use the China non-CDN mirror:
ELECTRON_MIRROR=\"https://npm.taobao.org/mirrors/electron/\"\nELECTRON_CUSTOM_DIR=\"{{ version }}\"\nLa configuration ci-dessus sera téléchargée à partir d'URL telles que https://npm.taobao.org/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip.
Si votre serveur miroir délivre des artefacts avec des checksums différentes de celles de la version officielle d'Electron, vous devrez définir ELECTRON_USE_REMOTE_CHECKSUMS=1 afin forcer Electron à utiliser le fichier distant SHASUMS256.txt pour vérifier la somme de contrôle au lieu de celles intégrées.
Egalement vous pouvez, surcharger le cache local. @electron/get mettra en cache le téléchargement des binaires dans un répertoire local afin d'économiser de la bande passante. Vous pouvez utiliser ce répertoire de cache pour fournir des binaires personnalisés d'Electron ou pour éviter d'utiliser le réseau.
$XDG_CACHE_HOME or ~/.cache/electron/~/Library/Caches/electron/$LOCALAPPDATA/electron/Cache or ~/AppData/Local/electron/Cache/Sur les environnements qui utilisent des versions plus anciennes d’électron, vous pourriez trouver le cache aussi dans ~/.electron.
Vous pouvez également substituer l’emplacement du cache local en fournissant une variable d’environnement electron_config_cache.
The cache contains the version's official zip file as well as a checksum, stored as a text file. A typical cache might look like this:
\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9electron-v1.7.9-darwin-x64.zip\n│ └── electron-v1.7.9-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1electron-v1.8.1-darwin-x64.zip\n│ └── electron-v1.8.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1electron-v1.8.2-beta.1-darwin-x64.zip\n│ └── electron-v1.8.2-beta.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2electron-v1.8.2-beta.2-darwin-x64.zip\n│ └── electron-v1.8.2-beta.2-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3electron-v1.8.2-beta.3-darwin-x64.zip\n│ └── electron-v1.8.2-beta.3-darwin-x64.zip\n└── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3SHASUMS256.txt\n └── SHASUMS256.txt\nSous le capot, l'API JavaScript d'Electron est rattachée à un binaire contenant son implémentation. Ce binaire est indispensable au fonctionnement de toute application Electron, il est donc téléchargé par défaut dans l’étape du postinstall chaque fois que vous installez electron à partir du dépôt npm.
Toutefois, si vous souhaitez installer les dépendances de votre projet sans avoir besoin d’utiliser les fonctionnalité d'Electron, vous pouvez définir la variable d’environnement ELECTRON_SKIP_BINARY_DOWNLOAD pour empêcher le téléchargement du fichier binaire. Ce peut être utile, par exemple dans les environnements d’intégration continue lors de l’exécution de tests unitaires qui simulent le module electron .
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install\nLorsque vous exécutez npm install electron, certains utilisateurs rencontrent parfois des erreurs d'installation.
Dans la plupart des cas, ces erreurs sont le résultat d'un problème de réseau et non un soucis avec le packet npm electron. Les erreurs comme ELIFECYCLE, EAI_AGAIN, ECONNRESET et ETIMEDOUT sont toutes des indications d'un problème de réseau. La meilleure solution est d'essayer en changeant de réseau ou juste d'attendre un peu et de réessayer l'installation.
Vous pouvez également essayer de télécharger Electron directement depuis electron/electron/releases si l'installation via npm ne marche pas.
If installation fails with an EACCESS error you may need to fix your npm permissions.
If the above error persists, the unsafe-perm flag may need to be set to true:
\nsudo npm install electron --unsafe-perm=true\nSur des réseaux plus lents, il est plus souhaitable d'utiliser le paramètre --verbose pour afficher la progression du téléchargement :
npm install --verbose electron\nSi vous devez forcer le re-téléchargement de l'asset et du fichier SHASUM, mettez la variable d'environnement force_no_cache à true.
Bienvenue sur la documentation d'Electron ! Si c'est la première fois que vous développez une application Electron, lisez cette section Getting Started pour vous familiariser avec les bases. Sinon, n'hésitez pas à explorer nos guides et notre documentation sur l'API !
\nElectron est un framework pour construire des applications de bureau en utilisant JavaScript, HTML et CSS. En intégrant Chromium et Node.js dans son binaire, Electron vous permet de maintenir une base de code JavaScript et de créer des applications multi-plateformes qui fonctionnent sous Windows, MacOS et Linux — aucune expérience de développement natif requise.
\nCes docs fonctionnent en supposant que le lecteur est familier avec Node.js et le développement web général. Si vous avez besoin d'être plus à l'aise avec l'un ou l'autre de ces domaines, nous vous recommandons les ressources suivantes :
\n\nDe plus, vous comprendrez mieux comment fonctionne Electron si vous vous familiarisé avec le modèle de processus de Chromium. Vous pouvez obtenir un bref aperçu de l'architecture Chrome avec la bande dessinée Chrome , qui a été publiée en même temps que le lancement de Chrome en 2008. Bien que cela fait plus d’une décennie depuis, les principes de base introduits dans la bande dessinée restent utiles pour comprendre Electron.
\nElectron Fiddle est une application de type bac à sable écrite avec Electron et supportée par les contributeurs d'Electron. Nous recommandons fortement de l'installer comme outil d'apprentissage pour expérimenter avec les API d'Electron ou pour prototyper des fonctionnalités pendant le développement.
\nFiddle s'intègre également parfaitement à notre documentation. Lorsque vous parcourrez des exemples dans nos tutoriels, vous verrez fréquemment un bouton \"Ouvrir dans Electron Fiddle\" sous un bloc de code. Si vous avez Fiddle installé, ce bouton ouvrira un lien fiddle.electronjs.org qui chargera automatiquement l'exemple dans Fiddle, pas de copier-coller requis.
Êtes-vous coincé quelque part ? Voici quelques liens vers des endroits où chercher :
\nelectron , veuillez consulter le suivi de tickets GitHub pour voir si des problèmes existants correspondent au votre. Si ce n'est pas le cas, n'hésitez pas à remplir notre modèle de rapport de bug et à nous le soumettre.readOperationCount Number - The number of I/O read operations.writeOperationCount Number - The number of I/O write operations.otherOperationCount Number - Then number of I/O other operations.readTransferCount Number - The number of I/O read transfers.writeTransferCount Number - The number of I/O write transfers.otherTransferCount Number - Then number of I/O other transfers.\n\nCommuniquer de manière asynchrone depuis le processus main aux processus renderer.
\n
Processus : Main
\nLe module ipcMain est un Event Emitter. Lorsqu'il est utilisé dans le processus main, il gère les messages asynchrones et synchrones envoyés à partir d'un processus renderer (page web). Les messages envoyés par un renderer seront émis vers ce module.
Il est également possible d'envoyer des messages depuis le processus main pour le processus renderer. Voir webContents.send pour plus d'information.
\nchannel.event.returnValue.event.reply(...). Cette méthode d'aide gérera automatiquement les messages provenant des images qui ne sont pas le cadre principal (e. . iframes) alors que event.sender.send(...) enverra toujours au cadre principal.Un exemple d'envoi et de gestion des messages entre le processus main et renderer :
\n// Dans le processus principal .\nconst { ipcMain } = require('electron')\nipcMain.on('asynchronous-message', (event, arg) => {\n console.log(arg) // affiche \"ping\"\n event.reply('asynchronous-reply', 'pong')\n})\n\nipcMain.on('synchronous-message', (event, arg) => {\n console.log(arg) // affiche \"ping\"\n event.returnValue = 'pong'\n})\n// Dans le processus de rendu (page web).\n// NB. Electron APIs are only accessible from preload, unless contextIsolation is disabled.\n// Voir https://www.electronjs.org/docs/tutorial/process-model#preload-scripts pour plus de détails.\nconst { ipcRenderer } = require('electron')\nconsole.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // affiche \"pong\"\n\nipcRenderer.on('asynchronous-reply', (event, arg) => {\n console.log(arg) // affiche \"pong\"\n})\nipcRenderer.send('asynchronous-message', 'ping')\nLe module de ipcMain possède les méthodes suivantes pour écouter les événements :
ipcMain.on(channel, listener)channel Stringlistener Functionévénement IpcMainEvent...args any[]En écoutant channel, lorsqu'un nouveau message arrive, listener sera appelé comme ceci listener(event, args...).
ipcMain.once(channel, listener)channel Stringlistener Functionévénement IpcMainEvent...args any[]Ajoute un listener à déclenchement unique pour l’événement. Ce listener sera appelé uniquement lors de la prochaine émission d'un message sur le channel, après quoi il sera supprimé.
ipcMain.removeListener(channel, listener)channel Stringlistener Function...args any[]Supprime le listener spécifié du tableau d'écouteurs pour le channel spécifié.
ipcMain.removeAllListeners([channel])channel String (facultatif)Supprime tous les écouteurs du channel spécifié.
ipcMain.handle(canal, écouteur)channel Stringlistener Function<Promise\\événement IpcMainInvokeEvent...args any[]Adds a handler for an invokeable IPC. This handler will be called whenever a renderer calls ipcRenderer.invoke(channel, ...args).
Si listener renvoie une Promise, le résultat final de la promesse sera retourné en réponse à l'appelant distant. Sinon, la valeur de retour de l'écouteur sera utilisée comme valeur de la réponse.
// Processus principal\nipcMain.handle('my-invokable-ipc', async (event, ...args) => {\n const result = wait somePromise(... rgs)\n return result\n})\n\n\n\n // Processus de rendu\nasync () => {\n const result = wait ipcRenderer. nvoke('my-invokable-ipc', arg1, arg2)\n // ...\n}\nLe event qui est passé comme premier argument au gestionnaire est le même que que celui passé à un event listener régulier. Il contient des informations sur lequel WebContents est la source de la demande d'appel.
Errors thrown through handle in the main process are not transparent as they are serialized and only the message property from the original error is provided to the renderer process. Please refer to #24427 for details.
ipcMain.handleOnce(channel, listener)channel Stringlistener Function<Promise\\événement IpcMainInvokeEvent...args any[]Handles a single invokeable IPC message, then removes the listener. See ipcMain.handle(channel, listener).
ipcMain.removeHandler(channel)channel StringSupprime tout gestionnaire pour canal, si présent.
La documentation de l'objet événement passé à la callback peut être trouvée dans la documentation de la structure ipc-main-event.
La documentation de l'objet événement passé à handle callbacks peut être trouvée dans la documentation de la structure ipc-main-invoke-event .
EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagereturnValue any - Set this to the value to be returned in a synchronous messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this messageports MessagePortMain[] - A list of MessagePorts that were transferred with this messagereply Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to \"reply\" to the sent message in order to guarantee the reply will go to the correct process and frame.channel String...args any[]EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this message\n\nCommuniquer de manière asynchrone depuis le processus renderer au processus main.
\n
Processus : Renderer
\nLe module ipcRender est un EventEmitter. Il fournit quelques méthodes pour pouvoir envoyer des messages synchrones et asynchrones depuis le processus render (page web) pour le processus main. Vous pouvez également recevoir des réponses du processus main.
Voir ipcMain pour des exemples de code.
\nLe module de ipcRenderer possède les méthodes suivantes pour écouter les événements et envoyer des messages :
ipcRenderer.on(channel, listener)channel Stringlistener Functionévénement IpcRendererEvent...args any[]En écoutant channel, lorsqu'un nouveau message arrive, listener sera appelé comme ceci listener(event, args...).
ipcRenderer.once(channel, listener)channel Stringlistener Functionévénement IpcRendererEvent...args any[]Ajoute un listener à déclenchement unique pour l’événement. Ce listener sera appelé uniquement lors de la prochaine émission d'un message sur le channel, après quoi il sera supprimé.
ipcRenderer.removeListener(channel, listener)channel Stringlistener Function...args any[]Supprime le listener spécifié du tableau d'écouteurs pour le channel spécifié.
ipcRenderer.removeAllListeners(channel)channel StringSupprime tous les écouteurs, ou ceux du channel spécifié.
ipcRenderer.send(channel, ...args)channel String...args any[]Envoyez un message asynchrone au processus principal via channel, ainsi que des arguments. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
Le processus principal le gère en écoutant le canal avec le module ipcMain.
If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you want to receive a single response from the main process, like the result of a method call, consider using ipcRenderer.invoke.
ipcRenderer.invoke(channel, ...args)channel String...args any[]Retourne Promise<any> - résout avec la réponse du processus principal.
Envoie un message au processus principal via channel et attend un résultat asynchrone. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
Le processus principal devrait écouter le canal avec ipcMain.handle().
Par exemple :
\n// Processus de rendu\nipcRenderer.invoke('some-name', someArgument).then((result) => {\n // ...\n})\n\n// Processus principal\nipcMain.handle('some-name', async (event, someArgument) => {\n const result = wait doSomeWork(someArgument)\n return result\n})\nIf you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you do not need a response to the message, consider using ipcRenderer.send.
ipcRenderer.sendSync(canal, ...args)channel String...args any[]Retourne any - La valeur renvoyé par l'écouteur du ipcMain.
Envoyez un message au processus principal via channel et attendez un résultat de manière synchrone. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
Le processus principal le gère en écoutant le canal avec le module ipcMain , et répond en définissant event.returnValue.
\n\n⚠️ WARNING: Sending a synchronous message will block the whole renderer process until the reply is received, so use this method only as a last resort. It's much better to use the asynchronous version,
\ninvoke().
ipcRenderer.postMessage(channel, message, [transfer])Send a message to the main process, optionally transferring ownership of zero or more MessagePort objects.
The transferred MessagePort objects will be available in the main process as MessagePortMain objects by accessing the ports property of the emitted event.
Par exemple :
\n// Renderer process\nconst { port1, port2 } = new MessageChannel()\nipcRenderer.postMessage('port', { message: 'hello' }, [port1])\n\n// Main process\nipcMain.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nFor more information on using MessagePort and MessageChannel, see the MDN documentation.
ipcRenderer.sendTo(webContentsId, channel, ...args)webContentsId Numberchannel String...args any[]Envoie un message à une fenêtre avec webContentsId via canal.
ipcRenderer.sendToHost(canal, ...args)channel String...args any[]Comme ipcRenderer.send, mais l'événement sera envoyé à l'élément <webview> dans la page hôte au lieu du processus main.
La documentation de l'objet événement passé à la callback peut être trouvée dans la documentation de la structure ipc-renderer-event.
Eventsender IpcRenderer - The IpcRenderer instance that emitted the event originallysenderId Integer - The webContents.id that sent the message, you can call event.sender.sendTo(event.senderId, ...) to reply to the message, see ipcRenderer.sendTo for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set event.senderId to 0.ports MessagePort[] - A list of MessagePorts that were transferred with this messagePour toute question, il y a fondamentalement trois façons pour une personne de Contribuer:
\nelectron/electron issue tracker.electron/electron d'une manière concrète et vérifiable.\"Trouver un soutien\" a un liste de ressources pour obtenir de l’aide à la programmation, signaler les problèmes de sécurité, contribuer, et plus encore. Veuillez utiliser le gestionnaire de tickets uniquement pour les bugs !
\nTo submit a bug report:
\nWhen opening a new issue in the electron/electron issue tracker, users will be presented with a template that should be filled in.
If you believe that you have found a bug in Electron, please fill out the template to the best of your ability.
\nThe two most important pieces of information needed to evaluate the report are a description of the bug and a simple test case to recreate it. It is easier to fix a bug if it can be reproduced.
\nSee How to create a Minimal, Complete, and Verifiable example.
\nIl est fréquent que les questions ouvertes impliquent des discussions. Certains contributeurs peuvent avoir des opinions différentes, y compris si le comportement est un bogue ou une fonctionnalité. This discussion is part of the process and should be kept focused, helpful, and professional.
\nTerse responses that provide neither additional context nor supporting detail are not helpful or professional. Pour beaucoup, de telles réponses sont ennuyeuses et peu amicales.
\nContributors are encouraged to solve issues collaboratively and help one another make progress. If you encounter an issue that you feel is invalid, or which contains incorrect information, explain why you feel that way with additional supporting context, and be willing to be convinced that you may be wrong. By doing so, we can often reach the correct outcome faster.
\nLa plupart des issues sont résolus en ouvrant une pull request. The process for opening and reviewing a pull request is similar to that of opening and triaging issues, but carries with it a necessary review and approval workflow that ensures that the proposed changes meet the minimal quality and functional guidelines of the Electron project.
", "title": "Les issues dans Electron", "description": "" }, "/docs/api/structures/jump-list-category": { "locale": "fr-FR", "slug": "jump-list-category", "href": "/docs/api/structures/jump-list-category", "crowdinFileId": "256451", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/jump-list-category.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "type String (optional) - One of the following:tasks - Items in this category will be placed into the standard Tasks category. There can be only one such category, and it will always be displayed at the bottom of the Jump List.frequent - Displays a list of files frequently opened by the app, the name of the category and its items are set by Windows.recent - Displays a list of files recently opened by the app, the name of the category and its items are set by Windows. Items may be added to this category indirectly using app.addRecentDocument(path).custom - Displays tasks or file links, name must be set by the app.name String (optional) - Must be set if type is custom, otherwise it should be omitted.items JumpListItem - Array of JumpListItem objects if type is tasks or custom, otherwise it should be omitted.Note: If a JumpListCategory object has neither the type nor the name property set then its type is assumed to be tasks. If the name property is set but the type property is omitted then the type is assumed to be custom.
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
type String (optional) - One of the following:task - A task will launch an app with specific arguments.separator - Can be used to separate items in the standard Tasks category.file - A file link will open a file using the app that created the Jump List, for this to work the app must be registered as a handler for the file type (though it doesn't have to be the default handler).path String (optional) - Path of the file to open, should only be set if type is file.program String (optional) - Path of the program to execute, usually you should specify process.execPath which opens the current program. Should only be set if type is task.args String (optional) - The command line arguments when program is executed. Should only be set if type is task.title String (optional) - The text to be displayed for the item in the Jump List. Should only be set if type is task.description String (optional) - Description of the task (displayed in a tooltip). Should only be set if type is task. Maximum length 260 characters.iconPath String (optional) - The absolute path to an icon to be displayed in a Jump List, which can be an arbitrary resource file that contains an icon (e.g. .ico, .exe, .dll). You can usually specify process.execPath to show the program icon.iconIndex Number (optional) - The index of the icon in the resource file. If a resource file contains multiple icons this value can be used to specify the zero-based index of the icon that should be displayed for this task. If a resource file contains only one icon, this property should be set to zero.workingDirectory String (optional) - The working directory. Default is empty.ctrlKey Boolean (optional) - whether the Control key was used in an accelerator to trigger the EventmetaKey Boolean (optional) - whether a meta key was used in an accelerator to trigger the EventshiftKey Boolean (optional) - whether a Shift key was used in an accelerator to trigger the EventaltKey Boolean (optional) - whether an Alt key was used in an accelerator to trigger the EventtriggeredByAccelerator Boolean (optional) - whether an accelerator was used to trigger the event as opposed to another user gesture like mouse clickInputEventtype String - The type of the event, can be keyDown, keyUp or char.keyCode String - The character that will be sent as the keyboard event. Should only use the valid key codes in Accelerator.Cette fonctionnalité vous permet de configurer les raccourcis clavier locaux et globaux de votre application Electron.
\nLes raccourcis clavier locaux ne sont déclenchés que lorsque l'application a le focus. To configure a local keyboard shortcut, you need to specify an accelerator property when creating a MenuItem within the Menu module.
Commençons avec une application fonctionnelle issue du Quick Start Guide, mettez à jour le fichier main.js avec les lignes suivantes :
const { Menu, MenuItem } = require('electron')\n\nconst menu = new Menu()\nmenu.append(new MenuItem({\n label: 'Electron',\n submenu: [{\n role: 'help',\n accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Alt+Shift+I',\n click: () => { console.log('Electron rocks!') }\n }]\n}))\n\nMenu.setApplicationMenu(menu)\n\n\nREMARQUE : Dans le code ci-dessus, vous pouvez voir que l'accélérateur diffère selon le système d'exploitation de l'utilisateur . Pour MacOS, c'est
\nAlt+Cmd+I, alors que pour Linux et Windows, c'estAlt+Shift+I.
Après avoir lancé l'application Electron, vous devriez voir le menu de l'application avec le raccourci local que vous venez de définir:
\n
Si vous cliquez sur Aide ou appuyez sur l'accélérateur défini, puis ouvrez le terminal depuis lequel vous avez exécuté votre application Electron, vous verrez le message qui a été généré après avoir déclenché l'événement click : \"Electron rocks!\".
Pour configurer un raccourci clavier global, vous devez utiliser le module globalShortcut pour détecter les événements du clavier même si l'application n'a pas le focus.
\nCommençons avec une application fonctionnelle issue du Quick Start Guide, mettez à jour le fichier main.js avec les lignes suivantes :
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n globalShortcut.register('Alt+CommandOrControl+I', () => {\n console.log('Electron loves global shortcuts!')\n })\n}).then(createWindow)\n\n\nNOTE: Dans le code ci-dessus, la combinaison
\nCommandOrControlutiliseCommandsur macOS etControlsur Windows/Linux.
Après avoir lancé l'application Electron, si vous appuyez sur la combinaison de touches définie puis que vous ouvrez le terminal depuis lequel vous avez exécuté votre application Electron, vous verrez Electron loves global shortcuts!
\nSi vous voulez gérer les raccourcis clavier dans une BrowserWindow, vous pouvez écouter les keyup et keydown DOM events dans le processus de rendu en utilisant l'API addEventListener().
function handleKeyPress(event) {\n // Vous pouvez mettre ici du code de gestion des touches.\n document.getElementById(\"last-keypress\").innerText = event.key;\n console.log(`You pressed ${event.key}`);\n}\n\nwindow.addEventListener('keyup', handleKeyPress, true);\n\n\nNote: le troisième paramètre
\ntruesignifie que l'écouteur recevra toujours les actions des touches avant les autres écouteurs d'événement afin qu'ils ne puissent pas appeler eux-mêmestopPropagation().
L’événement before-input-event est émis avant d’envoyer les événements keydown et keyup dans la page. Il peut être utilisé pour intercepter et gérer des raccourcis personnalisés qui ne sont pas visibles dans le menu.
Commençons avec une application fonctionnelle issue du Quick Start Guide, mettez à jour le fichier main.js avec les lignes suivantes :
const { app, BrowserWindow } = require('electron')\n\napp.whenReady().then(() => {\n const win = new BrowserWindow({ width: 800, height: 600 })\n\n win.loadFile('index.html')\n win.webContents.on('before-input-event', (event, input) => {\n if (input.control && input.key.toLowerCase() === 'i') {\n console.log('Pressed Control+I')\n event.preventDefault()\n }\n })\n})\nAprès avoir lancé l'application Electron, si vous ouvrez le terminal depuis lequel vous avez exécuté votre application Electron et appuyez sur la combinaison de touches Ctrl+I , vous allez voir que cette combinaison de touches a été interceptée avec succès.
Si vous ne voulez pas analyser manuellement les raccourcis, il existe des bibliothèque qui font de la détection avancée comme par exemple mousetrap. Voici des exemples d’utilisation de mousetrap s'exécutant dans le processus Renderer :
Mousetrap.bind('4', () => { console.log('4') })\nMousetrap.bind('?', () => { console.log('show shortcuts!') })\nMousetrap.bind('esc', () => { console.log('escape') }, 'keyup')\n\n// combinations\nMousetrap.bind('command+shift+k', () => { console.log('command shift k') })\n\n// map multiple combinations to the same callback\nMousetrap.bind(['command+k', 'ctrl+k'], () => {\n console.log('command k or control k')\n\n // return false to prevent default behavior and stop event from bubbling\n return false\n})\n\n// gmail style sequences\nMousetrap.bind('g i', () => { console.log('go to inbox') })\nMousetrap.bind('* a', () => { console.log('select all') })\n\n// konami code!\nMousetrap.bind('up up down down left right left right b a enter', () => {\n console.log('konami code')\n})\ntitle: Lancement de votre application Electron depuis une URL dans une autre application\ndescription: This guide will take you through the process of setting your electron app as the default handler for a specific protocol.\nslug: launch-app-from-url-in-another-app
\nCe guide vous guidera à travers le processus de configuration de votre application Electron comme gestionnaire par défaut pour un protocol spécifique.
\nÀ la fin de ce tutoriel, nous aurons configuré notre application pour intercepter et gérer toutes les URL qui commençant par un protocole spécifique. Dans ce guide, le protocole utilisé sera \"electron-fiddle://\".
Importons tout d'abord les modules requis depuis electron. Ces modules aident à gérer le cycle de notre application et à créer une fenêtre de navigateur native.
const { app, BrowserWindow, shell } = require('electron')\nconst path = require('path')\nEnsuite, déclarons application comme gestionnaire des protocoles \"electron-fiddle://\".
if (process.defaultApp) {\n if (process.argv.length >= 2) {\n app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])\n }\n} else {\n app.setAsDefaultProtocolClient('electron-fiddle')\n}\nNous allons maintenant définir la fonction chargée de la création de notre fenêtre de navigateur et charger le fichier index.html de notre application.
const createWindow = () => {\n // Créer la fenêtre du navigateur.\n mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n mainWindow.loadFile('index.html')\n}\nDans l'étape suivante , nous allons créer notre BrowserWindow et dire à notre application comment gérer un événement venant d'un lien vers un protocole externe.
Ce code sera différent selon le système d'exploitation : WindowsOS, MacOS ou Linux. Cela est dû au fait que Windows a besoin de code supplémentaire pour ouvrir le contenu du lien de protocole dans la même instance Electron. Pour en savoir plus à ce sujet ici.
\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Someone tried to run a second instance, we should focus our window.\n if (mainWindow) {\n if (mainWindow.isMinimized()) mainWindow.restore()\n mainWindow.focus()\n }\n })\n\n // Create mainWindow, load the rest of the app, etc...\n app.whenReady().then(() => {\n createWindow()\n})\n\n// gestion du protocole. In this case, we choose to show an Error Box.\n app.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n })\n}\n// Cette méthode sera appelée quant Electron aura fini\n// de s'initialiser et sera prêt à créer des fenêtres de navigation.\n// Certaines APIs peuvent être utilisées uniquement quant cet événement est émit.\napp.whenReady().then(() => {\n createWindow()\n})\n\n// gestion du protocole. In this case, we choose to show an Error Box.\napp.on('open-url', (event, url) => {\n dialog.showErrorBox('Content de vous revoir ', `Vous venez de: ${url}`)\n})\nEnfin, nous ajouterons du code supplémentaire pour gérer la fermeture de notre application par l'utilisateur.
\n// Quit when all windows are closed, except on macOS. Là, il est courant\n/ pour les applications et leur barre de menus de rester actives jusqu’à ce que l’utilisateur quitte\n/ explicitement avec Cmd + Q.\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') app.quit()\n})\nSous macOS et Linux, cette fonctionnalité ne fonctionnera que si votre application est empaquetée. Cela ne fonctionne pas lorsque vous le lancez en développement à partir de la ligne de commande. Lorsque vous empaquetez votre application, vous devrez vous assurer que les fichiers Info.plist sur macOS et le Linux .desktop sur Linux sont mis à jour pour inclure le nouveau gestionnaire de protocole. Certains des outils d'Electron pour regrouper et distribuer des applications gèrent cela pour vous.
If you're using Electron Forge, adjust packagerConfig for macOS support, and the configuration for the appropriate Linux makers for Linux support, in your Forge configuration (please note the following example only shows the bare minimum needed to add the configuration changes):
{\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"protocols\": [\n {\n \"name\": \"Electron Fiddle\",\n \"schemes\": [\"electron-fiddle\"]\n }\n ]\n },\n \"makers\": [\n {\n \"name\": \"@electron-forge/maker-deb\",\n \"config\": {\n \"mimeType\": [\"x-scheme-handler/electron-fiddle\"]\n }\n }\n ]\n }\n }\n}\nFor macOS support:
\nIf you're using Electron Packager's API, adding support for protocol handlers is similar to how Electron Forge is handled, except protocols is part of the Packager options passed to the packager function.
const packager = require('electron-packager')\n\npackager({\n // ...other options...\n protocols: [\n {\n name: 'Electron Fiddle',\n schemes: ['electron-fiddle']\n }\n ]\n\n}).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))\n .catch(err => console.error(`ERROR: ${err.message}`))\nIf you're using Electron Packager's CLI, use the --protocol and --protocol-name flags. Par exemple :
npx electron-packager . --protocol=electron-fiddle --protocol-name=\"Electron Fiddle\"\nAfter you start your Electron app, you can enter in a URL in your browser that contains the custom protocol, for example \"electron-fiddle://open\" and observe that the application will respond and show an error dialog box.
Sur de nombreux environnements Linux, vous pouvez ajouter des entrées personnalisées à son lanceur d'application en modifiant le fichier .desktop. For Canonical's Unity documentation, see Adding Shortcuts to a Launcher. For details on a more generic implementation, see the freedesktop.org Specification.
\n\nNOTE: The screenshot above is an example of launcher shortcuts in Audacious audio player
\n
To create a shortcut, you need to provide Name and Exec properties for the entry you want to add to the shortcut menu. Unity will execute the command defined in the Exec field after the user clicked the shortcut menu item. Un exemple du fichier .desktop peut ressembler à ceci :
Actions=PlayPause;Next;Previous\n\n[Desktop Action PlayPause]\nName=Play-Pause\nExec=audacious -t\nOnlyShowIn=Unity;\n\n[Desktop Action Next]\nName=Next\nExec=audacious -f\nOnlyShowIn=Unity;\n\n[Desktop Action Previous]\nName=Previous\nExec=audacious -r\nOnlyShowIn=Unity;\nThe preferred way for Unity to instruct your application on what to do is using parameters. Vous pouvez les trouver dans votre application dans la variable globale process.argv.
Ce guide fournit des informations sur :
\nPour signer des applications Electron, les outils suivants doivent d'abord être installés :
\nVous devez également créer un compte Apple Developer et rejoindre le Apple Developper Program.
\nLes applications Electron peuvent être distribuées via le Mac App Store ou en dehors de celui-ci. Chaque moyen de distribution nécessite différentes façons de signer et de tester. Ce guide se concentre sur la distribution via le Mac App Store, mais mentionnera également d'autres méthodes.
\nLes étapes suivantes décrivent comment obtenir les certificats d'Apple, comment signer des applications Electron, et comment les tester.
\nLa façon la plus simple d’obtenir des certificats de signature est d’utiliser Xcode :
\nThe \"Apple Development\" certificate is used to sign apps for development and testing, on machines that have been registered on Apple Developer website. The method of registration will be described in Prepare provisioning profile.
\nApps signed with the \"Apple Development\" certificate cannot be submitted to Mac App Store. For that purpose, apps must be signed with the \"Apple Distribution\" certificate instead. But note that apps signed with the \"Apple Distribution\" certificate cannot run directly, they must be re-signed by Apple to be able to run, which will only be possible after being downloaded from the Mac App Store.
\nVous remarquerez peut-être qu'il existe également d'autres types de certificats.
\nThe \"Developer ID Application\" certificate is used to sign apps before distributing them outside the Mac App Store.
\nThe \"Developer ID Installer\" and \"Mac Installer Distribution\" certificates are used to sign the Mac Installer Package instead of the app itself. Most Electron apps do not use Mac Installer Package so they are generally not needed.
\nLa liste complète des types de certificats peut être trouvée ici.
\nApps signed with \"Apple Development\" and \"Apple Distribution\" certificates can only run under App Sandbox, so they must use the MAS build of Electron. However, the \"Developer ID Application\" certificate does not have this restrictions, so apps signed with it can use either the normal build or the MAS build of Electron.
\nApple has been changing the names of certificates during past years, you might encounter them when reading old documentations, and some utilities are still using one of the old names.
\nIf you want to test your app on your local machine before submitting your app to the Mac App Store, you have to sign the app with the \"Apple Development\" certificate with the provisioning profile embedded in the app bundle.
\nTo create a provisioning profile, you can follow the below steps:
\n/path/to/yourapp.provisionprofile.Apps submitted to the Mac App Store must run under Apple's App Sandbox, and only the MAS build of Electron can run with the App Sandbox. The standard darwin build of Electron will fail to launch when run under App Sandbox.
\nWhen signing the app with electron-osx-sign, it will automatically add the necessary entitlements to your app's entitlements, but if you are using custom entitlements, you must ensure App Sandbox capacity is added:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n </dict>\n</plist>\nelectron-osx-signSi vous signez votre application sans utiliser electron-osx-sign, vous devez vous assurer les droits du bundle d'applications ont au moins les clés suivantes :
\n\n<plist version=\"1.0\">\n <dict>\n <key>com. pple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security. groupes de pplication</key>\n <array>\n <string>TEAM_ID. notre.bundle.id</string>\n </array>\n </dict>\n</plist>\nThe TEAM_ID should be replaced with your Apple Developer account's Team ID, and the your.bundle.id should be replaced with the App ID of the app.
And the following entitlements must be added to the binaries and helpers in the app's bundle:
\n\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.inherit</key>\n <true/>\n </dict>\n</plist>\nAnd the app bundle's Info.plist must include ElectronTeamID key, which has your Apple Developer account's Team ID as its value:
<plist version=\"1.0\">\n<dict>\n ...\n <key>ElectronTeamID</key>\n <string>TEAM_ID</string>\n</dict>\n</plist>\nWhen using electron-osx-sign the ElectronTeamID key will be added automatically by extracting the Team ID from the certificate's name. You may need to manually add this key if electron-osx-sign could not find the correct Team ID.
To sign an app that can run on your development machine, you must sign it with the \"Apple Development\" certificate and pass the provisioning profile to electron-osx-sign.
electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile\nIf you are signing without electron-osx-sign, you must place the provisioning profile to YourApp.app/Contents/embedded.provisionprofile.
The signed app can only run on the machines that registered by the provisioning profile, and this is the only way to test the signed app before submitting to Mac App Store.
\nTo sign an app that will be submitted to Mac App Store, you must sign it with the \"Apple Distribution\" certificate. Note that apps signed with this certificate will not run anywhere, unless it is downloaded from Mac App Store.
\nelectron-osx-sign YourApp.app --identity='Apple Distribution'\nIf you don't plan to submit the app to Mac App Store, you can sign it the \"Developer ID Application\" certificate. In this way there is no requirement on App Sandbox, and you should use the normal darwin build of Electron if you don't use App Sandbox.
\nelectron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess\nBy passing --no-gatekeeper-assess, the electron-osx-sign will skip the macOS GateKeeper check as your app usually has not been notarized yet by this step.
This guide does not cover App Notarization, but you might want to do it otherwise Apple may prevent users from using your app outside Mac App Store.
\nAfter signing the app with the \"Apple Distribution\" certificate, you can continue to submit it to Mac App Store.
\nHowever, this guide do not ensure your app will be approved by Apple; you still need to read Apple's Submitting Your App guide on how to meet the Mac App Store requirements.
\nThe Application Loader should be used to upload the signed app to iTunes Connect for processing, making sure you have created a record before uploading.
\nIf you are seeing errors like private APIs uses, you should check if the app is using the MAS build of Electron.
\nAfter uploading, you should submit your app for review.
\nAfin de satisfaire toutes les exigences pour l'app sandboxing, les modules suivants ont été désactivé dans la compilation MAS :
\ncrashReporterautoUpdateret les comportements suivants ont été modifiés :
\nDe plus, en raison de l'utilisation de l'app sandboxing, les ressources étant accessibles par l'application sont strictement limitées. Vous pouvez lire App Sandboxing pour plus d'informations.
\nDepending on which Electron APIs your app uses, you may need to add additional entitlements to your app's entitlements file. Otherwise, the App Sandbox may prevent you from using them.
\nActivez les connexions sortantes du réseau pour permettre votre application de se connecter à un serveur :
\n<key>com.apple.security.network.client</key>\n<true/>\nActivez les connexion entrantes du réseau pour permettre votre application d'ouvrir un système d'écoute socket :
\n<key>com.apple.security.network.server</key>\n<true/>\nVoir la documentation Activer les accès réseaux pour plus de détails.
\n<key>com.apple.security.files.user-selected.read-only</key>\n<true/>\nVoir la documentation Activer les fichiers sélectionnés par l'utilisateur pour plus de détails.
\n<key>com.apple.security.files.user-selected.read-write</key>\n<true/>\nVoir la documentation Activer les fichiers sélectionnés par l'utilisateur pour plus de détails.
\nSelon les pays dans lesquels vous publiez votre application, vous pourriez être requis pour fournir des informations sur les algorithmes de chiffrement utilisés dans votre logiciel . Voir la documentation de conformité à l'exportation de chiffrement pour plus d'informations.
\nElectron utilise ces algorithmes de chiffrement suivants :
\nElectron a des APIs pour configurer l'icône de l'application dans le macOS Dock. A macOS-only API exists to create a custom dock menu, but Electron also uses the app dock icon as the entry point for cross-platform features like recent documents and application progress.
\nLe dock personnalisé est généralement utilisé pour ajouter des raccourcis aux tâches pour lesquelles l'utilisateur ne voudrait pas ouvrir toute la fenêtre de l'application.
\nMenu du Dock de Terminal.app :
\n
To set your custom dock menu, you need to use the app.dock.setMenu API, which is only available on macOS.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, BrowserWindow, Menu } = require('electron')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n })\n\n win.loadFile('index.html')\n}\n\nconst dockMenu = Menu.buildFromTemplate([\n {\n label: 'New Window',\n click () { console.log('New Window') }\n }, {\n label: 'New Window with Settings',\n submenu: [\n { label: 'Basic' },\n { label: 'Pro' }\n ]\n },\n { label: 'New Command...' }\n])\n\napp.whenReady().then(() => {\n if (process.platform === 'darwin') {\n app.dock.setMenu(dockMenu)\n }\n}).then(createWindow)\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n\nAfter launching the Electron application, right click the application icon. You should see the custom menu you just defined:
\n
workingSetSize Integer - The amount of memory currently pinned to actual physical RAM.peakWorkingSetSize Integer - The maximum amount of memory that has ever been pinned to actual physical RAM.privateBytes Integer (optional) Windows - The amount of memory not shared by other processes, such as JS heap or HTML content.Note that all statistics are reported in Kilobytes.
", "title": "MemoryInfo Object", "description": "" }, "/docs/api/structures/memory-usage-details": { "locale": "fr-FR", "slug": "memory-usage-details", "href": "/docs/api/structures/memory-usage-details", "crowdinFileId": "256461", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/memory-usage-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "count Numbersize NumberliveSize Number\n\nCrée des menus d'applications natifs et des menus contextuels.
\n
Processus : Main
\nnew Menu()Créer un nouveau menu.
\nLa classe Menu a les méthodes statiques suivantes :
Menu.setApplicationMenu(menu)menu Menu | nullDéfinit le menu comme le menu d'application sur macOS. Sous Windows et Linux, le menu sera défini comme le menu supérieur de chaque fenêtre.
Aussi sous Windows et Linux, vous pouvez utiliser un & dans le nom de l'élément de niveau supérieur pour indiquer quelle lettre doit obtenir un accélérateur généré. Par exemple, en utilisant &Fichier pour le menu de fichiers, l'accélérateur Alt-F généré qui ouvre le menu associé. The indicated character in the button label then gets an underline, and the & character is not displayed on the button label.
In order to escape the & character in an item name, add a proceeding &. For example, &&File would result in &File displayed on the button label.
Passing null will suppress the default menu. Sous Windows et Linux, cela a pour effet supplémentaire de supprimer la barre de menu de la fenêtre.
Note: Le menu par défaut sera créé automatiquement si l'application ne le définit pas. Il contient des éléments standard tels que Fichier, Modifier, Voir, Window et Aide.
Menu.getApplicationMenu()Retourne Menu | null - Le menu de l’application, si défini, ou null, si non défini.
Remarque : L'instance du Menu retourné, ne supporte pas l'ajout ou la suppression dynamique d’éléments de menu. Les propriétés de l’instance peuvent encore être modifiées dynamiquement.
Menu.sendActionToFirstResponder(action) macOSaction StringEnvoie action au premier répondant de l'application. Ceci est utilisé pour émuler les comportements du menu de macOS par défaut. Habituellement, vous utiliseriez la propriété rôle d'un MenuItem.
Voir le Guide de gestion des événements Cocoa de macOS pour plus d'informations sur les actions natives de macOS.
\nMenu.buildFromTemplate(template)template (MenuItemConstructorOptions | MenuItem)[]Retourne Menu
Généralement, le paramètre template est un tableau d' options pour construire un MenuItem. L’utilisation peut être référencée ci-dessus. L'utilisation peut être référencée ci-dessus.
Vous pouvez également attacher d'autres champs à l'élément du template et ils deviendront des propriétés des éléments de menu construits.
L'objet menu a les méthodes d'instance suivantes:
menu.popup([options])options Object (facultatif)window BrowserWindow (facultatif) - La fenêtre focalisée est par défaut.x Number (facultatif) - C'est par défaut la position actuelle du curseur de la souris. Doit être déclaré si y est déclaré.x Number (facultatif) - C'est par défaut la position actuelle du curseur de la souris. Doit être déclaré si x est déclaré.positioningItem Number (facultatif) macOS - L'index de l'élément de menu à positionner sous le curseur de la souris aux coordonnées spécifiées. est. La valeur par défaut est -1.callback Fonction (facultatif) - Appelée lorsque le menu est fermé.Dépile ce menu sous la forme d'un menu contextuel dans la BrowserWindow.
menu.closePopup([browserWindow])browserWindow BrowserWindow (facultatif) - La fenêtre focalisée est par défaut.Ferme le menu contextuel dans la browserWindow.
menu.append(menuItem)menuItem MenuItemAjoute le menuItem au menu.
menu.getMenuItemById(id)id StringRetourne MenuItem | null l'élément avec le id spécifié
menu.insert(pos, menuItem)pos IntegermenuItem MenuItemInsère le menuItem à la position pos du menu.
Les objets créés avec nouveau Menu ou retournés par Menu.buildFromTemplate émettent les événements suivants :
Remarque : Certains événements sont seulement disponibles sur des systèmes d'exploitation spécifiques et sont étiquetés comme tels.
\nRetourne :
\nevent EventÉmis lorsque menu.popup() est appelé.
Retourne :
\nevent EventÉmis lorsqu'un popup est fermé manuellement ou avec menu.closePopup().
Les objets menu ont également les propriétés suivantes :
menu.itemsUn tableau MenuItem[] contenant les éléments du menu.
Chaque Menu consiste en plusieurs MenuItems et chaque MenuItem peut avoir un sous-menu.
Un exemple de création du menu de l'application avec l'API de modèle simple :
\nconst { app, Menu } = require('electron')\n\nconst isMac = process.platform === 'darwin'\n\nconst template = [\n // { role: 'appMenu' }\n ...(isMac ? [{\n label: app. ame,\n sous-menu : [\n { role: 'about' },\n { type: 'separator' },\n { role: 'services' },\n { type: 'separator' },\n { role: 'hide' },\n { role: 'hideOthers' },\n { role: 'unhide' },\n { type: 'separator' },\n { role: 'quit' }\n ]\n }] : []),\n // { role: 'fileMenu' }\n {\n label: 'Fichier',\n sous-menu : [\n isMac ? { role: 'close' } : { role: 'quit' }\n ]\n },\n // { role: 'editMenu' }\n {\n label: 'Modifier',\n sous-menu : [\n { role: 'undo' },\n { role: 'redo' },\n { type: 'separator' },\n { role: 'cut' },\n { role: 'copy' },\n { role: 'paste' },\n . .(isMac ? [\n { role: 'pasteAndMatchStyle' },\n { role: 'delete' },\n { role: 'selectAll' },\n { type: 'separator' },\n {\n label: 'Speech',\n submenu: [\n { role: 'startSpeaking' },\n { role: 'stopSpeaking' }\n ]\n }\n ] : [\n { role: 'delete' },\n { type: 'separator' },\n { role: 'selectAll' }\n ])\n ]\n },\n // { role: 'viewMenu' }\n {\n label: 'View',\n submenu: [\n { role: 'reload' },\n { role: 'forceReload' },\n { role: 'toggleDevTools' },\n { type: 'separator' },\n { role: 'resetZoom' },\n { role: 'zoomIn' },\n { role: 'zoomOut' },\n { type: 'separator' },\n { role: 'togglefullscreen' }\n ]\n },\n // { role: 'windowMenu' }\n {\n label: 'Window',\n submenu: [\n { role: 'minimize' },\n { role: 'zoom' },\n ...(isMac ? [\n { type: 'separator' },\n { role: 'front' },\n { type: 'separator' },\n { role: 'window' }\n ] : [\n { role: 'close' }\n ])\n ]\n },\n {\n rôle: 'help',\n sous-menu : [\n {\n label: 'En savoir plus',\n clic : async () => {\n const { shell } = require('electron')\n attendent shell. penExternal('https://electronjs. rg')\n }\n\n ]\n }\n]\n\nconst menu = Menu. uildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nTo create menus initiated by the renderer process, send the required information to the main process using IPC and have the main process display the menu on behalf of the renderer.
\nVoici un exemple d'affichage d'un menu lorsque l'utilisateur clique avec le bouton droit sur la page :
\n// renderer\nwindow.addEventListener('contextmenu', (e) => {\n e.preventDefault()\n ipcRenderer.send('show-context-menu')\n})\n\nipcRenderer.on('context-menu-command', (e, command) => {\n // ...\n})\n\n// main\nipcMain.on('show-context-menu', (event) => {\n const template = [\n {\n label: 'Menu Item 1',\n click: () => { event.sender.send('context-menu-command', 'menu-item-1') }\n },\n { type: 'separator' },\n { label: 'Menu Item 2', type: 'checkbox', checked: true }\n ]\n const menu = Menu.buildFromTemplate(template)\n menu.popup(BrowserWindow.fromWebContents(event.sender))\n})\nmacOS a un style de menu d'application complètement différent de Windows et Linux. Voici quelques notes pour rendre le menu de votre application plus natif.
\nSur macOS, il y a beaucoup de menus standards définis par le système, comme les Services et Windows. Pour faire de votre menu un menu standard, vous devriez définir le rôle de votre menu à l'un des rôles suivants et Electron les reconnaîtra et les fera devenir des menus standard :
windowhelpservicesmacOS a fourni des actions standard pour certains liens de menu, comme À propos de xxx, Cacher xxx, et Cacher les autres. Pour définir l'action d'un lien de menu à une action standard , vous devez définir l'attribut rôle de l'élément de menu.
Sur macOS, l'étiquette du premier élément du menu de l'application est toujours le nom de votre application, quel que soit le libellé que vous avez défini. Pour le modifier, modifiez le fichier Info.plist de votre pack d'applications. See About Information Property List Files for more information.
La setMenu méthode des fenêtres du navigateur peut définir le menu de certaines fenêtres de navigateur .
Vous pouvez utiliser avant, after, beforeGroupContaining, afterGroupContaining et id pour contrôler comment l'élément sera placé lors de la construction d'un menu avec Menu.buildFromTemplate.
avant - Insère cet élément avant l'élément avec l'étiquette spécifiée. Si l'élément référencé n'existe pas, l'élément sera inséré à la fin de le menu. Implique également que le lien de menu en question doit être placé dans le même « groupe » que l’élément.après - Insère cet élément après l'élément avec l'étiquette spécifiée. Si l'élément référencé n'existe pas, l'élément sera inséré à la fin de le menu. Implique également que le lien de menu en question doit être placé dans le même « groupe » que l’élément.beforeGroupContaining - Fournit un moyen pour un seul menu contextuel de déclarer le placement de leur groupe contenant avant le groupe contenant de l'élément avec l'étiquette spécifiée.afterGroupContaining - Fournit un moyen pour un seul menu contextuel de déclarer le placement de leur groupe contenant après le groupe contenant de l'élément avec l'étiquette spécifiée.Par défaut, les éléments seront insérés dans l'ordre dans lequel ils existent dans le modèle, sauf si l'un des mots-clés de positionnement spécifiés est utilisé.
\nModèle :
\n[\n { id: '1', label: 'one' },\n { id: '2', label: 'two' },\n { id: '3', label: 'three' },\n { id: '4', label: 'four' }\n]\nMenu :
\n- 1\n- 2\n- 3\n- 4\nModèle :
\n[\n { id: '1', label: 'one' },\n { type: 'separator' },\n { id: '3', label: 'three', beforeGroupContaining: ['1'] },\n { id: '4', label: 'four', afterGroupContaining: ['2'] },\n { type: 'separator' },\n { id: '2', label: 'two' }\n]\nMenu :
\n- 3\n- 4\n- ---\n- 1\n- ---\n- 2\nModèle :
\n[\n { id: '1', label: 'one', after: ['3'] },\n { id: '2', label: 'two', before: ['1'] },\n { id: '3', label: 'three' }\n]\nMenu :
\n- ---\n- 3\n- 2\n- 1\n\n\nAjoute des éléments aux menus et menus contextuels de l’application native.
\n
Processus : Main
\nVoir Menu pour des exemples.
new MenuItem(options)optionsclick Function (optional) - Will be called with click(menuItem, browserWindow, event) when the menu item is clicked.menuItem MenuItembrowserWindow BrowserWindow | undefined - This will not be defined if no window is open.event KeyboardEventrole String (optional) - Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu - Define the action of the menu item, when specified the click property will be ignored. Voir rôles.type String (facultatif) - Peut être normal, séparateur, sous-menu, checkbox ou radio.label String (optionnel)sublabel String (optionnel)toolTip String (optional) macOS - Hover text for this menu item.accélérateur Accelerator (facultatif)icon (NativeImage | String) (facultatif)activé Booléen (facultatif) - Si faux, l'élément de menu sera grisé et non cliquable.acceleratorWorksWhenHidden Boolean (optional) macOS - default is true, and when false will prevent the accelerator from triggering the item if the item is not visible`.visible Boolean (facultatif) - Si false, l'élément de menu sera entièrement masqué.coché Booléen (facultatif) - Ne doit être spécifié que pour case à cocher ou radio type des liens de menu .registerAccelerator Boolean (optional) Linux Windows - If false, the accelerator won't be registered with the system, but it will still be displayed. Defaults to true.sharingItem SharingItem (optional) macOS - The item to share when the role is shareMenu.sous-menu (MenuItemConstructorOptions[] | Menu) (facultatif) - Doit être spécifié pour sous-menu type éléments de menu. Si sous-menu est spécifié, le type: 'submenu' peut être omis. Si la valeur n'est pas un Menu alors elle sera automatiquement convertie en un en utilisant Menu.buildFromTemplate.id String (optional) - Unique within a single menu. If defined then it can be used as a reference to this item by the position attribute.avant String - Insère cet élément avant l'élément avec le libellé spécifié. Si l'élément référencé n'existe pas, l'élément sera inséré à la fin du menu. Implique également que l'élément de menu en question doit être placé dans le même « groupe » que l'élément.after String - Inserts this item after the item with the specified label. Si l'élément référencé n'existe pas, l'élément sera inséré à la fin de le menu.beforeGroupContaining String - Fournit un moyen pour un seul menu contextuel de déclarer le placement de leur groupe contenant avant le groupe contenant l'élément avec l'étiquette spécifiée.afterGroupContaining String - Fournit un moyen pour un seul menu contextuel de déclarer le placement de leur groupe contenant après le groupe contenant de l'élément avec l'étiquette spécifiée.Note: acceleratorWorksWhenHidden is specified as being macOS-only because accelerators always work when items are hidden on Windows and Linux. L'option est exposée aux utilisateurs pour leur donner la possibilité de la désactiver, car cela est possible dans le développement natif de macOS. Cette propriété n'est utilisable que sur macOS Haute Sierra 10.13 ou plus récente.
Les rôles permettent à des éléments du menu d'avoir des comportements prédéfinis.
\nIl est préférable de spécifier rôle pour tout élément de menu qui correspond à un rôle standard, plutôt que d'essayer d'implémenter manuellement le comportement dans une fonction clic. Le comportement rôle intégré donnera la meilleure expérience native.
Les valeurs label et accélérateur sont optionnelles lorsque vous utilisez un rôle et par défaut des valeurs appropriées pour chaque plateforme.
Chaque lien de menu doit avoir soit un rôle, label, soit dans le cas d'un séparateur un type.
La propriété role peut avoir les valeurs suivantes :
undoabout - Trigger a native about panel (custom message box on Window, which does not provide its own).redocutcopypastepasteAndMatchStyleselectAlldeleteminimize - Minimize current window.close - Close current window.quitter - Quitter l'application.reload - Reload the current window.forceReload - Recharge la fenêtre courante ignorant le cache.toggleDevTools - Bascule les outils de développement dans la fenêtre actuelle.togglefullscreen - Basculer en mode plein écran dans la fenêtre actuelle.resetZoom - Réinitialise le niveau de zoom de la page ciblée à la taille d'origine.zoomIn - Zoom sur la page ciblée par 10%.zoomOut - Zoom arrière de la page ciblée de 10%.toggleSpellChecker - Enable/disable builtin spell checker.fileMenu - Menu par défaut entier \"Fichier\" (Close / Quitter)editMenu - Tout le menu \"Edit\" par défaut (Annuler, Copier, etc.).viewMenu - Menu \"Affichage\" par défaut (Recharger, Activer/désactiver les outils de développement, etc.)windowMenu - Menu par défaut entier \"Windows\" (Minimize, Zoom, etc.).The following additional roles are available on macOS:
\nappMenu - Tout le menu \"App\" par défaut (About, Services, etc.)hide - Mappez à l'action caché.hideOthers - Mappez à l'action hideOtherApplications.unhide - Mappez à l'action unhideAllApplications.startSpeaking - Carte à l'action startSpeaking.stopSpeaking - Carte à l'action stopSpeaking.front - Mappez à l'action arrangeInFront.zoom - Mappez à l'action performZoom.toggleTabBar - Mappez à l'action toggleTabBar.selectNextTab - Mappez à l'action selectNextTab.selectPreviousTab - Mappez à l'action selectPreviousTab.mergeAllWindows - Mappez à l'action mergeAllWindows.moveTabToNewWindow - Mappez à l'action moveTabToNewWindow.window - Le sous-menu est un menu \"Windows\".help - Le sous-menu est un menu \"Aide\".services - Le sous-menu est un menu \"Services\". This is only intended for use in the Application Menu and is not the same as the \"Services\" submenu used in context menus in macOS apps, which is not implemented in Electron.recentDocuments - Le sous-menu est un menu \"Ouvrir Récents\".clearRecentDocuments - Carte à l'action clearRecentDocuments.shareMenu - The submenu is share menu. The sharingItem property must also be set to indicate the item to share.Lorsque vous spécifiez un rôle sur macOS, label et accélérateur sont les seules options qui affecteront l'élément de menu. Toutes les autres options seront ignorées. La minuscule rôle, par exemple toggledevtools, est toujours supportée.
Nota Bene: The enabled and visibility properties are not available for top-level menu items in the tray on macOS.
Les propriétés suivantes sont disponibles pour les instances de MenuItem :
menuItem.idUne String indiquant l'identifiant unique de l'élément, cette propriété peut être modifiée dynamiquement.
menuItem.labelA String indicating the item's visible label.
menuItem.clickA Function that is fired when the MenuItem receives a click event. It can be called with menuItem.click(event, focusedWindow, focusedWebContents).
event KeyboardEventfocusedWindow BrowserWindowfocusedWebContents WebContentsmenuItem.submenuUn Menu (facultatif) contenant le sous-menu de l'élément de menu s'il est présent.
menuItem.typeA String indicating the type of the item. Can be normal, separator, submenu, checkbox or radio.
menuItem.roleUn String (facultatif) indiquant le rôle de l'élément, si défini. Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu
menuItem.acceleratorAn Accelerator (optional) indicating the item's accelerator, if set.
menuItem.userAccelerator Readonly macOSAn Accelerator | null indicating the item's user-assigned accelerator for the menu item.
Note: This property is only initialized after the MenuItem has been added to a Menu. Either via Menu.buildFromTemplate or via Menu.append()/insert(). Accessing before initialization will just return null.
menuItem.iconA NativeImage | String (facultatif) indiquant l'icône de l'élément , si défini.
menuItem.sublabelA String indicating the item's sublabel.
menuItem.toolTip macOSUne Chaîne indiquant le texte du survol de l'élément.
menuItem.enabledUn Booléen indiquant si l'élément est activé, cette propriété peut être modifiée dynamiquement.
menuItem.visibleUn Booléen indiquant si l'élément est visible, cette propriété peut être modifiée dynamiquement.
menuItem.checkedUn Booléen indiquant si l'élément est vérifié, cette propriété peut être modifiée dynamiquement.
Une case à cocher lien de menu activera et éteindra la propriété cochée lorsque sera sélectionné.
Un lien de menu radio activera sa propriété cochée une fois cliqué, et désactivera cette propriété pour tous les éléments adjacents du même menu.
Vous pouvez ajouter une fonction clic pour un comportement supplémentaire.
menuItem.registerAcceleratorA Boolean indicating if the accelerator should be registered with the system or just displayed.
This property can be dynamically changed.
\nmenuItem.sharingItem macOSA SharingItem indicating the item to share when the role is shareMenu.
This property can be dynamically changed.
\nmenuItem.commandIdUn Nombre indiquant l'identifiant unique d'un élément.
menuItem.menuUn Menu dont l'item fait partie.
MessagePortMain est l’équivalent coté processus principal de MessagePort du DOM . Son unique fonction est de créer une paire d'objets MessagePortMain connectés .
Pour plus d'informations sur son utilisation consultez la documentation de Channel Messaging API.
\n\n\nInterface de canal pour la messagerie de canal dans le processus principal.
\n
Processus : Main
\nExemple :
\n// processus principal\nconst { MessageChannelMain } = require('electron')\nconst { port1, port2 } = new MessageChannelMain()\nw.webContents.postMessage('port', null, [port2])\nport1.postMessage({ some: 'message' })\n\n// processus de rendu\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('port', (e) => {\n // e.ports est une liste de ports envoyée conjointement avec ce message\n e.ports[0].on('message', (messageEvent) => {\n console.log(messageEvent.data)\n })\n})\nchannel.port1Une propriété MessagePortMain.
channel.port2Une propriété MessagePortMain.
MessagePortMain est l’équivalent de MessagePort du DOM mais coté processus principal. Il se comporte de la même manière que la version DOM, sauf qu'il utilise le système d'événements de Node.js EventEmitter au lieu du système EventTarget du DOM. Cela signifie que vous devrez utiliser port.on('message', ...) pour écouter les événements, au lieu de port. nmessage = ... ou port.addEventListener('message', ...)
Pour plus d'informations sur son utilisation consultez la documentation de Channel Messaging API.
\nMessagePortMain est un [EventEmitter][event-emitter].
\n\nPort interface for channel messaging in the main process.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
port.postMessage(message, [transfer])Envoie un message depuis le port, et le cas échéant, transfère la propriété d'objets à d’autres contextes de navigation.
\nport.start()Démarre l'envoi de messages en file d'attente sur le port. Les messages seront mis en file d'attente jusqu'à ce que cette méthode soit appelée.
\nport.close()Déconnecte le port qui ne sera donc plus actif.
\nRetourne :
\nmessageEventdata {any}ports MessagePortMain[]Émis lorsqu'un objet MessagePortMain reçoit un message.
\nÉmis lorsque l’extrémité distante d’un objet MessagePortMain devient déconnectée.
", "title": "MessagePortMain", "description": "Port interface for channel messaging in the main process." }, "/docs/tutorial/message-ports": { "locale": "fr-FR", "slug": "message-ports", "href": "/docs/tutorial/message-ports", "crowdinFileId": "256219", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/message-ports.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Un MessagePorts est une fonctionnalité web permettant l'échange de messages entre différents contextes. C'est un peu comme window.postMessage, mais sur différents canaux. The goal of this document is to describe how Electron extends the Channel Messaging model, and to give some examples of how you might use MessagePorts in your app.
Voici un petit exemple de MessagePort et de son fonctionnement:
\n// rendererer.js ///////////////////////////////////////////////////////////////////\n// Les MessagePorts sont créés par paires. On appelle canal une paire de MessagePort connectés .\nconst channel = new MessageChannel()\n\n// La seule différence entre port1 et port2 est dans la façon dont vous les utilisez. Les messages envoyés à port1 seront reçus par port2 et vice-versa.\nconst port1 = channel.port1\nconst port2 = channel. ort2\n\n// Il est possible d'envoyer un message sur le canal avant que l'autre extrémité n'ait enregistré un écouteur. Les messages seront dans ce cas mis en file d'attente jusqu'à ce qu'un écouteur soit enregistré.\nport2.postMessage({ answer: 42 })\n\n// Ici nous envoyons l'autre extrémité du canal, port1, au processus principal. //Il est également possible d'envoyer des MessagePorts à d'autres frames, Web Workers, etc.\nipcRenderer.postMessage('port', null, [port1])\n// main.js ///////////////////////////////////////////////////////////////////////////\n// Dans le processus principal, nous recevons le port.\nipcMain.on('port', (event) => {\n // Lorsque nous recevons un MessagePort dans le processus principal, il devient un\n // MessagePortMain.\n const port = event.ports[0]\n\n // MessagePortMain utilise une API des événements du style Node.js plutôt que web. So .on('message', ...) instead of .onmessage = ...\n port.on('message', (event) => {\n // data is { answer: 42 }\n const data = event.data\n })\n\n // MessagePortMain met les messages en attente jusqu'à ce que la méthode .start() soit invoquée.\n port.start()\n})\nLa documentation de Channel Messaging API est un excellent moyen d'en apprendre plus sur le fonctionnement des MessagePorts.
\nDans le moteur de rendu, la classe MessagePort se comporte exactement comme pour le Web. Le processus principal n'étant pas pas une page web, il n'y a pas l'intégration de Blink — et donc pas de classe MessagePort ou MessageChannel. Afin de gérer et interagir à l'aide de MessagePorts avec le processus principal, Electron ajoute deux nouvelles classes : MessagePortMain et MessageChannelMain. Celles-ci se comportent comme les classes analogues dans le moteur de rendu.
Les objets de type MessagePort peuvent être créés soit dans le moteur de rendu soit dans le processus principal, et passés dans les deux sens en utilisant les méthodes ipcRenderer. ostMessage et WebContents.postMessage . Notez bien que les méthodes IPC usuelles telles que send et invoke ne peuvent pas être utilisées pour transférer des MessagePort, seules la méthode postMessage le peut pour transférer des MessagePort.
En transmettant un MessagePorts via le processus principal, vous pouvez connecter deux pages qui sans cela n'auraient pas été en mesure de communiquer (par ex à cause de restrictions sur une même origine).
close eventElectron ajoute une fonctionnalité à MessagePort non présente pour le web afin de rendre MessagePorts plus utile. Il s'agit de l'événement close , qui est émis lorsque l'autre extrémité du canal est fermée. Les ports peuvent également être implicitement fermés par une purge du garbage-collector.
Dans le moteur de rendu, vous pouvez ajouter des écouteurs sur l'événement close soit par assignation avec port.onclose ou en invoquant la méthode port.addEventListener('close', ...). Dans le processus , vous pouvez le faire appelant port.on ('close',...).
In this example, your app has a worker process implemented as a hidden window. You want the app page to be able to communicate directly with the worker process, without the performance overhead of relaying via the main process.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, ipcMain, MessageChannelMain } = require('electron')\n\napp.whenReady().then(async () => {\n // The worker process is a hidden BrowserWindow, so that it will have access\n // to a full Blink context (including e.g. <canvas>, audio, fetch(), etc.)\n const worker = new BrowserWindow({\n show: false,\n webPreferences: { nodeIntegration: true }\n })\n await worker.loadFile('worker.html')\n\n // The main window will send work to the worker process and receive results\n // over a MessagePort.\n const mainWindow = new BrowserWindow({\n webPreferences: { nodeIntegration: true }\n })\n mainWindow.loadFile('app.html')\n\n // We can't use ipcMain.handle() here, because the reply needs to transfer a\n // MessagePort.\n ipcMain.on('request-worker-channel', (event) => {\n // For security reasons, let's make sure only the frames we expect can\n // access the worker.\n if (event.senderFrame === mainWindow.webContents.mainFrame) {\n // Create a new channel ...\n const { port1, port2 } = new MessageChannelMain()\n // ... send one end to the worker ...\n worker.webContents.postMessage('new-client', null, [port1])\n // ... and the other end to the main window.\n event.senderFrame.postMessage('provide-worker-channel', null, [port2])\n // Now the main window and the worker can communicate with each other\n // without going through the main process!\n }\n })\n})\n<!-- worker.html ------------------------------------------------------------>\n<script>\nconst { ipcRenderer } = require('electron')\n\nfunction doWork(input) {\n // Something cpu-intensive.\n return input * 2\n}\n\n// We might get multiple clients, for instance if there are multiple windows,\n// or if the main window reloads.\nipcRenderer.on('new-client', (event) => {\n const [ port ] = event.ports\n port.onmessage = (event) => {\n // The event data can be any serializable object (and the event could even\n // carry other MessagePorts with it!)\n const result = doWork(event.data)\n port.postMessage(result)\n }\n})\n</script>\n<!-- app.html --------------------------------------------------------------->\n<script>\nconst { ipcRenderer } = require('electron')\n\n// We request that the main process sends us a channel we can use to\n// communicate with the worker.\nipcRenderer.send('request-worker-channel')\n\nipcRenderer.once('provide-worker-channel', (event) => {\n // Once we receive the reply, we can take the port...\n const [ port ] = event.ports\n // ... register a handler to receive results ...\n port.onmessage = (event) => {\n console.log('received result:', event.data)\n }\n // ... and start sending it work!\n port.postMessage(21)\n})\n</script>\nElectron's built-in IPC methods only support two modes: fire-and-forget (e.g. send), or request-response (e.g. invoke). Using MessageChannels, you can implement a \"response stream\", where a single request responds with a stream of data.
// renderer.js ///////////////////////////////////////////////////////////////\n\nfunction makeStreamingRequest (element, callback) {\n // MessageChannels are lightweight--it's cheap to create a new one for each\n // request.\n const { port1, port2 } = new MessageChannel()\n\n // We send one end of the port to the main process ...\n ipcRenderer.postMessage(\n 'give-me-a-stream',\n { element, count: 10 },\n [port2]\n )\n\n // ... and we hang on to the other end. The main process will send messages\n // to its end of the port, and close it when it's finished.\n port1.onmessage = (event) => {\n callback(event.data)\n }\n port1.onclose = () => {\n console.log('stream ended')\n }\n}\n\nmakeStreamingRequest(42, (data) => {\n console.log('got response data:', event.data)\n})\n// We will see \"got response data: 42\" 10 times.\n// main.js ///////////////////////////////////////////////////////////////////\n\nipcMain.on('give-me-a-stream', (event, msg) => {\n // The renderer has sent us a MessagePort that it wants us to send our\n // response over.\n const [replyPort] = event.ports\n\n // Here we send the messages synchronously, but we could just as easily store\n // the port somewhere and send messages asynchronously.\n for (let i = 0; i < msg.count; i++) {\n replyPort.postMessage(msg.element)\n }\n\n // We close the port when we're done to indicate to the other end that we\n // won't be sending any more messages. This isn't strictly necessary--if we\n // didn't explicitly close the port, it would eventually be garbage\n // collected, which would also trigger the 'close' event in the renderer.\n replyPort.close()\n})\nWhen context isolation is enabled, IPC messages from the main process to the renderer are delivered to the isolated world, rather than to the main world. Sometimes you want to deliver messages to the main world directly, without having to step through the isolated world.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, MessageChannelMain } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(async () => {\n // Create a BrowserWindow with contextIsolation enabled.\n const bw = new BrowserWindow({\n webPreferences: {\n contextIsolation: true,\n preload: path.join(__dirname, 'preload.js')\n }\n })\n bw.loadURL('index.html')\n\n // We'll be sending one end of this channel to the main world of the\n // context-isolated page.\n const { port1, port2 } = new MessageChannelMain()\n\n // It's OK to send a message on the channel before the other end has\n // registered a listener. Messages will be queued until a listener is\n // registered.\n port2.postMessage({ test: 21 })\n\n // We can also receive messages from the main world of the renderer.\n port2.on('message', (event) => {\n console.log('from renderer main world:', event.data)\n })\n port2.start()\n\n // The preload script will receive this IPC message and transfer the port\n // over to the main world.\n bw.webContents.postMessage('main-world-port', null, [port1])\n})\n// preload.js ////////////////////////////////////////////////////////////////\nconst { ipcRenderer } = require('electron')\n\n// We need to wait until the main world is ready to receive the message before\n// sending the port. We create this promise in the preload so it's guaranteed\n// to register the onload listener before the load event is fired.\nconst windowLoaded = new Promise(resolve => {\n window.onload = resolve\n})\n\nipcRenderer.on('main-world-port', async (event) => {\n await windowLoaded\n // We use regular window.postMessage to transfer the port from the isolated\n // world to the main world.\n window.postMessage('main-world-port', '*', event.ports)\n})\n<!-- index.html ------------------------------------------------------------->\n<script>\nwindow.onmessage = (event) => {\n // event.source === window means the message is coming from the preload\n // script, as opposed to from an <iframe> or other source.\n if (event.source === window && event.data === 'main-world-port') {\n const [ port ] = event.ports\n // Once we have the port, we can communicate directly with the main\n // process.\n port.onmessage = (event) => {\n console.log('from main process:', event.data)\n port.postMessage(event.data * 2)\n }\n }\n}\n</script>\nmimeType String (optional) - MIME type of the buffer.charset String (optional) - Charset of the buffer.data Buffer - The actual Buffer content.InputEventtype String - The type of the event, can be mouseDown, mouseUp, mouseEnter, mouseLeave, contextMenu, mouseWheel or mouseMove.x Integery Integerbutton String (optional) - The button pressed, can be left, middle, right.globalX Integer (optional)globalY Integer (optional)movementX Integer (optional)movementY Integer (optional)clickCount Integer (optional)MouseInputEventtype String - The type of the event, can be mouseWheel.deltaX Integer (optional)deltaY Integer (optional)wheelTicksX Integer (optional)wheelTicksY Integer (optional)accelerationRatioX Integer (optional)accelerationRatioY Integer (optional)hasPreciseScrollingDeltas Boolean (optional)canScroll Boolean (optional)Avec Web Workers, il est possible d'exécuter du code JavaScript au niveau du système d'exploitation.
\nIl est possible d’utiliser des fonctionnalités de Node.js dans les Web Workers d'Electron, pour ce faire, l’option nodeIntegrationInWorker doit être définie à true dans webPreferences.
const win = new BrowserWindow({\n webPreferences: {\n nodeIntegrationInWorker: true\n }\n})\nLe nodeIntegrationInWorker peut être utilisé indépendamment de nodeIntegration, mais le sandbox ne doit pas être défini sur true.
Tous les modules intégrés de Node.js sont pris en charge dans les Web Workers, et les archives asar peuvent encore être lues avec les API de Node.js. Toutefois, aucun des modules intégrés d'Electron peut être utilisé dans un environnement multithread.
N’importe quel module de Node.js natif peut être chargé directement dans les Web Workers, mais il est fortement recommandé de ne pas le faire. La plupart des modules natifs existants ont été écrits en supposant un environnement mono-thread, leur utilisation dans les Web Workers peut entrainer des crash et corruptions de mémoire.
\nNotez que même si un module natif de Node.js est thread-safe, il n’est toujours pas sûr de le charger dans un Web Worker car la fonction process.dlopen n’est pas thread-safe.
La seule façon de charger un module natif en toute sécurité pour l’instant, est de s’assurer que l’application ne charge aucun module natif après que les Web Workers aient démarré.
\nprocess.dlopen = () => {\n throw new Error('Load native module is not safe')\n}\nconst worker = new Worker('script.js')\nCertains types d'applications manipulant des fichiers peuvent prendre en charge la fonction de glisser-déplacer native du système d'exploitation. Le déplacement de fichiers dans le contenu Web est courant et est supporté par de nombreux sites Web. Electron prend également en charge le déplacement des fichiers et du contenu du contenu Web vers le monde du système d'exploitation.
\nPour implémenter cette fonctionnalité dans votre application, vous devez appeler l'API webContents.startDrag(item) dans la réponse à l'événement ondragstart.
An example demonstrating how you can create a file on the fly to be dragged out of the window.
\nIn preload.js use the contextBridge to inject a method window.electron.startDrag(...) that will send an IPC message to the main process.
const { contextBridge, ipcRenderer } = require('electron')\nconst path = require('path')\n\ncontextBridge.exposeInMainWorld('electron', {\n startDrag: (fileName) => {\n ipcRenderer.send('ondragstart', path.join(process.cwd(), fileName))\n }\n})\nAdd a draggable element to index.html, and reference your renderer script:
<div style=\"border:2px solid black;border-radius:3px;padding:5px;display:inline-block\" draggable=\"true\" id=\"drag\">Drag me</div>\n<script src=\"renderer.js\"></script>\nIn renderer.js set up the renderer process to handle drag events by calling the method you added via the contextBridge above.
document.getElementById('drag').ondragstart = (event) => {\n event.preventDefault()\n window.electron.startDrag('drag-and-drop.md')\n}\nIn the Main process (main.js file), expand the received event with a path to the file that is being dragged and an icon:
const { ipcMain } = require('electron')\n\nipcMain.on('ondragstart', (event, filePath) => {\n event.sender.startDrag({\n file: filePath,\n icon: '/path/to/icon.png'\n })\n})\nAfter launching the Electron application, try dragging and dropping the item from the BrowserWindow onto your desktop. Dans ce guide, l'élément est un fichier Markdown situé à la racine du projet :
\n
\n\n\nCréez des icônes de bac, d'ancrage et d'application à l'aide de fichiers PNG ou JPG.
\n
Dans Electron, pour les API d'acquisition d'images, vous pouvez passer des chemins de fichiers ou des instances de tyipe NativeImage. Une image vide sera utilisée lorsque null sera transmise.
For example, when creating a tray or setting a window's icon, you can pass an image file path as a String:
const { BrowserWindow, Tray } = require('electron')\n\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconst win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })\nconsole.log(appIcon, win)\nOr read the image from the clipboard, which returns a NativeImage:
const { clipboard, Tray } = require('electron')\nconst image = clipboard.readImage()\nconst appIcon = new Tray(image)\nconsole.log(appIcon)\nActuellement, les formats d'image PNG et JPEG sont pris en charge. PNG est recommandé en raison de son support de la transparence et de la compression sans perte.
Sous Windows, vous pouvez également charger les icônes ICO à partir de chemins de fichier. Pour une meilleure qualité visuelle , il est recommandé d'inclure au moins les tailles suivantes dans les :
Consultez la section Taille requise dans cet article.
\nOn platforms that have high-DPI support such as Apple Retina displays, you can append @2x after image's base filename to mark it as a high resolution image.
For example, if icon.png is a normal image that has standard resolution, then icon@2x.png will be treated as a high resolution image that has double DPI density.
Si vous voulez prendre en charge simultanément les écrans avec des densités DPI différentes, vous pouvez mettre des images de tailles différentes dans le même dossier et utiliser le nom de fichier sans le suffixe des DPI. Par exemple :
\nimages/\n├── icon.png\n├── icon@2x.png\n└── icon@3x.png\nconst { Tray } = require('electron')\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconsole.log(appIcon)\nLes suffixes suivants pour le DPI sont également pris en charge :
\n@1x@1.25x@1.33x@1.4x@1.5x@1.8x@2x@2.5x@3x@4x@5xLes templates d'image sont constituées de noir et d'un canal alpha. Elles ne sont pas destinées à être utilisées comme des images autonomes mais sont généralement mélangées avec d'autres contenus pour créer l'apparence finale désirée.
\nThe most common case is to use template images for a menu bar icon, so it can adapt to both light and dark menu bars.
\nRemarque : Les template d'image ne sont pas prise en charge que sur macOS.
\nTo mark an image as a template image, its filename should end with the word Template. Par exemple :
xxxTemplate.pngxxxTemplate@2x.pngThe nativeImage module has the following methods, all of which return an instance of the NativeImage class:
nativeImage.createEmpty()Retourne NativeImage
Crée une instance NativeImage vide.
nativeImage.createThumbnailFromPath(path, maxSize) macOS Windowspath String - path to a file that we intend to construct a thumbnail out of.maxSize Size - the maximum width and height (positive numbers) the thumbnail returned can be. The Windows implementation will ignore maxSize.height and scale the height according to maxSize.width.Returns Promise<NativeImage> - fulfilled with the file's thumbnail preview image, which is a NativeImage.
nativeImage.createFromPath(path)path StringRetourne NativeImage
Creates a new NativeImage instance from a file located at path. This method returns an empty image if the path does not exist, cannot be read, or is not a valid image.
const nativeImage = require('electron').nativeImage\n\nconst image = nativeImage.createFromPath('/Users/somebody/images/icon.png')\nconsole.log(image)\nnativeImage.createFromBitmap(buffer, options)buffer Bufferoptionswidth Integerheight IntegerscaleFactor Double (facultatif) - 1.0 par défaut.Retourne NativeImage
Creates a new NativeImage instance from buffer that contains the raw bitmap pixel data returned by toBitmap(). The specific format is platform-dependent.
nativeImage.createFromBuffer(buffer[, options])buffer Bufferoptions Object (facultatif)width Integer (optional) - Required for bitmap buffers.height Integer (optional) - Required for bitmap buffers.scaleFactor Double (facultatif) - 1.0 par défaut.Retourne NativeImage
Crée une nouvelle instance NativeImage à partir de buffer. Tries to decode as PNG or JPEG first.
nativeImage.createFromDataURL(dataURL)dataURL StringRetourne NativeImage
Crée une nouvelle instance NativeImage à partir de dataURL.
nativeImage.createFromNamedImage(imageName[, hslShift]) macOSRetourne NativeImage
Creates a new NativeImage instance from the NSImage that maps to the given image name. See System Icons for a list of possible values.
The hslShift is applied to the image with the following rules:
hsl_shift[0] (hue): The absolute hue value for the image - 0 and 1 map to 0 and 360 on the hue color wheel (red).hsl_shift[1] (saturation): A saturation shift for the image, with the following key values: 0 = remove all color. 0.5 = leave unchanged. 1 = fully saturate the image.hsl_shift[2] (lightness): A lightness shift for the image, with the following key values: 0 = remove all lightness (make all pixels black). 0.5 = leave unchanged. 1 = full lightness (make all pixels white).This means that [-1, 0, 1] will make the image completely white and [-1, 1, 0] will make the image completely black.
In some cases, the NSImageName doesn't match its string representation; one example of this is NSFolderImageName, whose string representation would actually be NSFolder. Par conséquent, vous devrez déterminer la bonne représentation de votre image avant de la passer. Cela peut être fait avec les éléments suivants :
echo -e '#import <Cocoa/Cocoa.h>\\nint main() { NSLog(@\"%@\", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test
where SYSTEM_IMAGE_NAME should be replaced with any value from this list.
\n\nNatively wrap images such as tray, dock, and application icons.
\n
Process: Main, Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The following methods are available on instances of the NativeImage class:
image.toPNG([options])options Object (facultatif)scaleFactor Double (facultatif) - 1.0 par défaut.Retourne Buffer - Un tampon qui contient les données encodées PNG de l'image.
image.toJPEG(quality)qualité Entier - Entre 0 - 100.Retourne Buffer - Un tampon qui contient les données encodées en JPEG de l'image.
image.toBitmap([options])options Object (facultatif)scaleFactor Double (facultatif) - 1.0 par défaut.Retourne Buffer - Un tampon qui contient une copie des données du pixel brut bitmap de l'image.
image.toDataURL([options])options Object (facultatif)scaleFactor Double (facultatif) - 1.0 par défaut.Retourne String - L'URL des données de l'image.
image.getBitmap([options])options Object (facultatif)scaleFactor Double (facultatif) - 1.0 par défaut.Retourne Buffer - Un tampon qui contient les données brutes des pixels bitmap de l'image.
The difference between getBitmap() and toBitmap() is that getBitmap() does not copy the bitmap data, so you have to use the returned Buffer immediately in current event loop tick; otherwise the data might be changed or destroyed.
image.getNativeHandle() macOSRetourne Buffer - Un tampon qui stocke le pointeur C sur la gestion native sous-jacente de l'image . Sur macOS, un pointeur vers NSImage serait retourné.
Note que le pointeur retourné est un pointeur faible vers l'image native sous-jacente au lieu d'une copie, donc vous devez vous assurer que l'instance associée nativeImage est conservée.
image.isEmpty()Retourne Boolean - Si l'image est vide.
image.getSize([scaleFactor])scaleFactor Double (facultatif) - 1.0 par défaut.Retourne Size.
If scaleFactor is passed, this will return the size corresponding to the image representation most closely matching the passed value.
image.setTemplateImage(option)option BooleanMarque l'image comme une image de modèle.
\nimage.isTemplateImage()Retourne Boolean - Si l'image est une image de modèle.
image.crop(rect)rect Rectangle - L'aire de l'image à recadrer.Retourne NativeImage - L'image recadrée.
image.resize(options)optionswidth Integer (optional) - Defaults to the image's width.height Integer (facultatif) - La hauteur de l'image par défaut.Qualité String (facultatif) - La qualité souhaitée de l'image de retaille. Les valeurs possibles sont good, better, ou best. La valeur par défaut est meilleur. Ces valeurs expriment un compromis qualité/vitesse souhaité. They are translated into an algorithm-specific method that depends on the capabilities (CPU, GPU) of the underlying platform. It is possible for all three methods to be mapped to the same algorithm on a given platform.Retourne NativeImage - L'image redimensionnée.
Si seulement la hauteur ou la largeur sont spécifiées, alors le ratio d'aspect actuel sera préservé dans l'image redimensionnée.
image.getAspectRatio([scaleFactor])scaleFactor Double (facultatif) - 1.0 par défaut.Retourne Float - Le ratio d'aspect de l'image.
If scaleFactor is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value.
image.getScaleFactors()Returns Float[] - An array of all scale factors corresponding to representations for a given nativeImage.
image.addRepresentation(options)optionsscaleFactor Double - The scale factor to add the image representation for.largeur Integer (facultatif) - 0 par défaut. Required if a bitmap buffer is specified as buffer.height Integer (facultatif) - 0 par défaut. Required if a bitmap buffer is specified as buffer.tampon Buffer (facultatif) - Le tampon contenant les données de l'image brute.dataURL String (optional) - The data URL containing either a base 64 encoded PNG or JPEG image.Add an image representation for a specific scale factor. This can be used to explicitly add different scale factor representations to an image. This can be called on empty images.
\nnativeImage.isMacTemplateImage macOSUne propriété Boolean qui détermine si l'image est considérée comme une image de modèle.
Veuillez noter que cette propriété n'a qu'un effet sur macOS.
", "title": "nativeImage", "description": "Créez des icônes de bac, d'ancrage et d'application à l'aide de fichiers PNG ou JPG." }, "/docs/api/native-theme": { "locale": "fr-FR", "slug": "native-theme", "href": "/docs/api/native-theme", "crowdinFileId": "256343", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/native-theme.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nConsulte et réagit aux changements du thème de couleur natif de Chromium.
\n
Processus : Main
\nLe module nativeTheme déclenche les événements suivants :
Émis lorsque quelque chose dans le NativeTheme sous-jacent a changé. This normally means that either the value of shouldUseDarkColors, shouldUseHighContrastColors or shouldUseInvertedColorScheme has changed. You will have to check them to determine which one has changed.
Le module nativeTheme dispose des propriétés suivantes :
nativeTheme.shouldUseDarkColors Lecture seuleA Boolean for if the OS / Chromium currently has a dark mode enabled or is being instructed to show a dark-style UI. If you want to modify this value you should use themeSource below.
nativeTheme.themeSourceUne propriété String qui peut être system, light ou dark. It is used to override and supersede the value that Chromium has chosen to use internally.
Setting this property to system will remove the override and everything will be reset to the OS default. By default themeSource is system.
Settings this property to dark will have the following effects:
nativeTheme.shouldUseDarkColors will be true when accessedprefers-color-scheme CSS query will match dark mode.updated event will be emittedSettings this property to light will have the following effects:
nativeTheme.shouldUseDarkColors will be false when accessedprefers-color-scheme CSS query will match light mode.updated event will be emittedL'utilisation de cette propriété devrait s'accorder avec le \"mode sombre\" classique du système dans votre application où l'utilisateur a trois options.
\nSuivant OS --> themeSource = 'system'Mode sombre --> themeSource = 'dark'Mode clair --> themeSource = 'light'Votre application devrait alors toujours utiliser shouldUseDarkColors pour déterminer quel CSS appliquer.
nativeTheme.shouldUseHighContrastColors macOS Windows Lecture seuleUn booléen pour déterminer si le système d'exploitation / Chromium a actuellement un mode de couleurs à contraste élevé activé ou est applique une interface à contraste élevé.
nativeTheme.shouldUseInvertedColorScheme macOS Windows Lecture seuleUn booléen pour déterminer si le système d'exploitation / Chromium a actuellement un mode de couleurs inversé ou commence à utiliser un modèle de couleurs inversé.
\n\nÉmet des requêtes HTTP/HTTPS à l'aide de la bibliothèque réseau natif de Chromium
\n
Processus : Main
\nLe module net est une API côté client pour émettre des requêtes HTTP(S). Il est semblable aux modules HTTP et HTTPS de Node.js, mais utilise la bibliothèque réseau natif de Chromium au lieu de l'implémentation de Node.js, offrant un meilleur support pour les proxy web. It also supports checking network status.
Voici une liste non exhaustive de pourquoi vous devriez utiliser le module net plutôt que les modules natifs de Node.js :
Les composants de l'API (y compris les classes, méthodes, propriétés et noms d'événements) sont similaires à ceux utilisés dans Node.js.
\nExemple d'utilisation :
\nconst { app } = require('electron')\napp.whenReady().then(() => {\n const { net } = require('electron')\n const request = net.request('https://github.com')\n request.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`)\n console.log(`HEADERS: ${JSON.stringify(response.headers)}`)\n response.on('data', (chunk) => {\n console.log(`BODY: ${chunk}`)\n })\n response.on('end', () => {\n console.log('No more data in response.')\n })\n })\n request.end()\n})\nL'API net ne peut être utilisée qu'après que l'application ait émit un événement ready. Trying to use the module before the ready event will throw an error.
Le module net dispose des méthodes suivantes :
net.request(options)options (ClientRequestConstructorOptions | String) - Les `options du constructeur.Retourne ClientRequest`
\nCréer une instance de ClientRequest avec les options founies qui sont directement transmis au constructor de ClientRequest. La méthode net.request doit être utilisée pour émettre des requêtes HTTP sécurisés et non sécurisés selon le schéma de protocole spécifié dans l'objet options.
\nnet.isOnline()
\nReturns Boolean - Whether there is currently internet connection.
\nA return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
\nPropriétés
\nnet.online Lecture seule
\nUne propriété Boolean. Whether there is currently internet connection.
\nA return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
",
"title": "net",
"description": "Émet des requêtes HTTP/HTTPS à l'aide de la bibliothèque réseau natif de Chromium"
},
"/docs/api/net-log": {
"locale": "fr-FR",
"slug": "net-log",
"href": "/docs/api/net-log",
"crowdinFileId": "256345",
"githubUrl": "https://github.com/electron/electron/tree/main/docs/api/net-log.md",
"category": "api",
"categoryFancy": "API",
"isTutorial": false,
"isApiDoc": true,
"isApiStructureDoc": false,
"isDevTutorial": false,
"html": "\n\nLog d'évènements de réseau lors d'une session.
\n
Processus : Main
\nconst { netLog } = require('electron')\n\napp.whenReady().then(async () => {\n await netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nVoir --log-net-log pour log les évènement réseau à travers le cycle de vie de l'application.
Note : Toutes les méthodes si non spécifiées ne peuvent être utilisées qu'après que l'évènement ready de l' app ne soit émis.
netLog.startLogging(path[, options])path String - Chemin du fichier où sera enregistré le log.options Object (facultatif)captureMode String (optional) - What kinds of data should be captured. By default, only metadata about requests will be captured. Setting this to includeSensitive will include cookies and authentication data. Setting it to everything will include all bytes transferred on sockets. Can be default, includeSensitive or everything.maxFileSize Number (optional) - When the log grows beyond this size, logging will automatically stop. Defaults to unlimited.Returns Promise<void> - resolves when the net log has begun recording.
Commence d'enregistrer les évènements de réseau dans path .
netLog.stopLogging()Returns Promise<void> - resolves when the net log has been flushed to disk.
Arrête d'enregistrer les évènements réseau. Si elle n'est pas appelée, elle sera automatiquement arrêtée quand l'application s'arrêtera.
\nnetLog.currentlyLogging Lecture seuleA Boolean property that indicates whether network logs are currently being recorded.
EventnewGuest BrowserWindow (optional)\n\nCréer des notifications bureau spécifique à l'OS
\n
Processus : Main
\nSI vous voulez afficher des notifications depuis un processus de rendu, vous devez utiliser l'API HTML5 de notification
\n\n\nCréer des notifications bureau spécifique à l'OS
\n
Processus : Main
\nNotification est un EventEmitter.
Cela crée une nouvelle Notification avec les propriétés natives définies par les options.
La classe Notification dispose des méthodes statiques suivantes :
Notification.isSupported()Retourne Boolean - Si le système actuel prend en charge les notification bureau ou non
new Notification([options])options Object (facultatif)title String (optional) - A title for the notification, which will be shown at the top of the notification window when it is shown.subtitle String (facultatif) macOS - Un sous-titre pour la notification, qui sera affiché sous le titre.body String (optional) - The body text of the notification, which will be displayed below the title or subtitle.silent Boolean (facultatif) - Émet ou non un bruit de notification lors de l'affichage de la notification.icône (String | NativeImage) (facultatif) - Une icône à utiliser dans la notification.hasReply Boolean (facultatif) macOS - Ajout ou non d'une option de réponse en ligne à la notification.timeoutType String (optional) Linux Windows - The timeout duration of the notification. Can be 'default' or 'never'.replyPlaceholder String (facultatif) macOS - L'espace réservé à écrire dans le champ de saisie de réponse en ligne.sound String (facultatif) macOS - Le nom du fichier audio à jouer lorsque la notification est affichée.urgency String (optional) Linux - The urgency level of the notification. Can be 'normal', 'critical', or 'low'.actions NotificationAction[] (optional) macOS - Actions to add to the notification. Please read the available actions and limitations in the NotificationAction documentation.closeButtonText String (optional) macOS - A custom title for the close button of an alert. An empty string will cause the default localized text to be used.toastXml String (optional) Windows - A custom description of the Notification on Windows superseding all properties above. Provides full customization of design and behavior of the notification.Les objets créés avec new Notification émettent les événements suivants :
Remarque : Certains événements sont seulement disponibles sur des systèmes d'exploitation spécifiques et sont étiquetés comme tels.
\nRetourne :
\nevent EventÉmis lorsque la notification est affiché à l'utilisateur, notez que cet événement peut être émis plusieurs fois du fait qu'une notification peut être affichée plusieurs fois par le biais de la méthode show().
Retourne :
\nevent EventÉmis lorsque l'utilisateur clique sur la notification.
\nRetourne :
\nevent EventÉmis lorsque la notification est fermée manuellement par l'utilisateur.
\nCet événement ne garantit pas d'être émis dans tous les cas de fermeture de la notification.
\nRetourne :
\nevent Eventreply String - La chaîne de caractères que l'utilisateur a écrite dans le champ de réponse.Émis lorsque l'utilisateur clique sur le bouton \"Reply\" sur une notification avec hasReply: true.
Retourne :
\nevent Eventindex Number - L'indice de l'action qui a été activée.Retourne :
\nevent Eventerror String - The error encountered during execution of the show() method.Emitted when an error is encountered while creating and showing the native notification.
\nLes objets créés avec new Notification ont les méthodes d'instance suivantes :
notification.show()Montre immédiatement la notification à l'utilisateur, veuillez noter que cela signifie que contrairement à la Mise en œuvre de la notification HTML5, instanciation d'une nouvelle notification fait ne pas le montrer immédiatement à l'utilisateur, vous devez appeler cette méthode avant le système d'exploitation l'affichera.
Si la notification a déjà été affichée auparavant, cette méthode rejettera la notification précédemment affichée et en créera une nouvelle avec des propriétés identiques.
\nnotification.close()Rejette la notification.
\nnotification.titleUne propriété String représentant le titre de la notification.
notification.subtitleUne propriété String représentant le sous-titre de la notification.
notification.bodyUne propriété String représentant le corps de la notification.
notification.replyPlaceholderUne propriété String représentant le placeholder de la réponse de la notification.
notification.soundUne propriété String représentant le son de la notification.
notification.closeButtonTextUne propriété String représentant le texte du bouton de fermeture de la notification.
notification.silentUne propriété Boolean qui indique si la notification est silencieuse.
notification.hasReplyUne propriété Booléenne qui indique si la notification a une action de réponse.
notification.urgency LinuxA String property representing the urgency level of the notification. Can be 'normal', 'critical', or 'low'.
Default is 'low' - see NotifyUrgency for more information.
\nnotification.timeoutType Linux WindowsA String property representing the type of timeout duration for the notification. Can be 'default' or 'never'.
If timeoutType is set to 'never', the notification never expires. It stays open until closed by the calling API or the user.
notification.actionsUne propriété NotificationAction[] représentant les actions de la notification.
notification.toastXml WindowsA String property representing the custom Toast XML of the notification.
Sur macOS, vous pouvez spécifier le nom du son que vous voulez jouer lors de l'affichage de la notification. Any of the default sounds (under System Preferences > Sound) can be used, in addition to custom sound files. Assurez-vous que le fichier audio soit copié dans l'\"app bundle\" (par exemple, VotreApp.app/Contents/Resources), ou l'un des emplacements suivants :
~/Library/Sounds/Library/Sounds/Network/Library/Sounds/System/Library/SoundsConsultez la documentation de NSSound pour plus d'informations.
type String - The type of action, can be button.text String (optional) - The label for the given action.| Action Type | Platform Support | Usage of text | Default text | Limitations |
|---|---|---|---|---|
button | macOS | Used as the label for the button | \"Show\" (or a localized string by system default if first of such button, otherwise empty) | Only the first one is used. If multiple are provided, those beyond the first will be listed as additional actions (displayed when mouse active over the action button). Any such action also is incompatible with hasReply and will be ignored if hasReply is true. |
In order for extra notification buttons to work on macOS your app must meet the following criteria.
\nNSUserNotificationAlertStyle set to alert in the Info.plist.If either of these requirements are not met the button won't appear.
", "title": "NotificationAction Object", "description": "" }, "/docs/api/structures/notification-response": { "locale": "fr-FR", "slug": "notification-response", "href": "/docs/api/structures/notification-response", "crowdinFileId": "256473", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/notification-response.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "actionIdentifier String - The identifier string of the action that the user selected.date Number - The delivery date of the notification.identifier String - The unique identifier for this notification request.userInfo Record<String, any> - A dictionary of custom information associated with the notification.userText String (optional) - The text entered or chosen by the user.All three operating systems provide means for applications to send notifications to the user. The technique of showing notifications is different for the Main and Renderer processes.
\nFor the Renderer process, Electron conveniently allows developers to send notifications with the HTML5 Notification API, using the currently running operating system's native notification APIs to display it.
\nTo show notifications in the Main process, you need to use the Notification module.
\nEn partant d'une application fonctionnelle du Guide de démarrage rapide, ajoutez les lignes suivantes au fichier index.html avant la balise de fermeture </body> :
<script src=\"renderer.js\"></script>\n... et ajoutez le fichier renderer.js :
const NOTIFICATION_TITLE = 'Titre'\nconst NOTIFICATION_BODY = 'Notification du Processus de rendu. Cliquez pour écrire dans la console.'\nconst CLICK_MESSAGE = 'Notification cliquée'\n\nnew Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY })\n .onclick = () => console.log(CLICK_MESSAGE)\nAfter launching the Electron application, you should see the notification:
\n
De plus, si vous cliquez sur la notification, le DOM se mettra à jour pour afficher \"Notification cliquée!\".
\nÀ partir d’une application fonctionnelle du Guide de démarrage rapide, mettez à jour le fichier main.js avec les lignes suivantes :
const { Notification } = require('electron')\n\nconst NOTIFICATION_TITLE = 'Basic Notification'\nconst NOTIFICATION_BODY = 'Notification from the Main process'\n\nfunction showNotification () {\n new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()\n}\n\napp.whenReady().then(createWindow).then(showNotification)\nAprès avoir lancé l'application Electron, vous devriez voir la notification système :
\n
Le code et l’expérience utilisateur sur les différents systèmes d’exploitation sont semblables, mais il y a des différences.
\nnode_modules\\electron\\dist\\electron.exe to your Start Menu also does the trick. Naviguez vers le fichier dans l'explorateur, cliquez avec le bouton droit de la souris et 'Épingler pour démarrer le menu'. Vous devrez ensuite ajouter la ligne app.setAppUserModelId(process.execPath) à votre processus principal pour voir les notifications.Electron tente d'automatiser le travail autour de l'ID du modèle utilisateur de l'application. Quand Electron est utilisé conjointement avec l'installation et la mise à jour du framework Squirrel, raccourcis seront automatiquement configurés correctement. De plus, Electron détectera que Squirrel a été utilisé et appellera automatiquement app.setAppUserModelId() avec la valeur correcte. Pendant le développement, vous pouvez avoir pour appeler app.setAppUserModelId() vous-même.
En outre, dans Windows 8, la longueur maximale pour le corps de notification est de 250 caractères, l'équipe Windows recommande que les notifications fassent jusqu'à 200 caractères. Cela dit, la limitation a été retiré sur Windows 10. L'équipe Windows demandant aux développeurs de rester raisonnable. Essayer d'envoyer des quantités gigantesques de textes à l'API (milliers de caractères) peut entraîner une instabilité.
\nLes versions ultérieures de Windows permettent aux notifications enrichies, avec des modèles personnalisés, des images et autres éléments. Pour envoyer ces notifications (depuis processus principal ou le processus de rendu), utilisez le \"userland\" module electron-windows-notifications, qui utilise un addons natif de Node pour envoyer des objets ToastNotification et TileNotification.
Bien que les notifications incluant des boutons fonctionnent avec electron-windows-notifications, la gestion des réponses nécessite l'utilisation de electron-windows-interactive-notification, qui aide à l'enregistrement des composants COM requis et fait l'appel à votre application Electron avec les données saisies par l'utilisateur.
Utilisez le module userland electron-notification-state afin de détecter si vous êtes autorisé à envoyer une notification, .
\nCela permet de déterminer à l'avance si Windows supprimera silencieusement la notification.
\nLes notifications sont simples sur macOS, mais vous devriez être au courant de Directives de l'interface humaine d'Apple concernant les notifications.
\nNotez que les notifications sont limitées à 256 octets de taille et risque d’être tronquées si vous dépassez cette limite.
\nPour détecter si oui ou non vous êtes autorisé à envoyer une notification, utilisez module \"userland\" electron-notification-state.
\nCela vous permettra de détecter si la notification sera affichée ou pas.
\nLes notifications sont envoyées à l'aide de libnotify qui permet l'affichage de notifications sur n'importe quel environnement bureau suivant Desktop Notifications Specification, comme Cinnamon, Enlightenment, Unity, GNOME et KDE.
Le Rendu hors-écran vous permet de récupérer le contenu d’une BrowserWindow dans un fichier bitmap, donc il pourra être restitué n’importe où, par exemple une texture dans une scène 3D. Le rendu hors-écran d'Electron utilise une approche comparable au projet Chromium Embedded Framework.
Notes :
\npaint pour plus d'efficacité.Le rendu par l'acceleration GPU signifie que le GPU est utilisé pour la composition. A cause de cela, cette fenêtre doit être copiée depuis le GPU et cela nécessite plus de performances. Donc ce mode est légèrement plus lent que l'autre. L’avantage de ce mode est que WebGL et les animations CSS 3D sont prises en charge.
\nCe mode utilise un périphérique d'affichage logiciel pour le rendu du CPU, donc la génération de l'image est beaucoup plus rapide. Par conséquent, ce mode est préférable au mode d'accélération GPU.
\nPour activer ce mode, l'accélération GPU doit être désactivée en appelant l'API app.disableHardwareAcceleration().
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\n\napp.disableHardwareAcceleration()\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ webPreferences: { offscreen: true } })\n\n win.loadURL('https://github.com')\n win.webContents.on('paint', (event, dirty, image) => {\n fs.writeFileSync('ex.png', image.toPNG())\n })\n win.webContents.setFrameRate(60)\n})\nAprès avoir lancé l'application Electron, accédez au dossier contenant votre application, où vous trouverez l'image affichée.
", "title": "Rendu hors de l'écran", "description": "" }, "/docs/tutorial/online-offline-events": { "locale": "fr-FR", "slug": "online-offline-events", "href": "/docs/tutorial/online-offline-events", "crowdinFileId": "256229", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/online-offline-events.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "La détection des événements Online et offline peut être implémentée dans le processus de rendu en utilisant l'attribut navigator.onLine, faisant partie de l'API HTML5 standard.
L'attribut navigator.onLine renvoie :
false si toute requête réseau est garantie vouée à l'échec (par exemple, lors de la déconnexion du réseau).true dans tous les autres cas.Puisque de nombreux cas retournent true, vous devriez traiter avec précaution les cas pouvant être des faux positifs, car la valeur true ne signifie pas toujours qu'Electron puisse accéder à Internet. Par exemple, dans les cas où l'ordinateur exécute un logiciel de virtualisation qui a des adaptateurs Ethernet virtuels avec l'état « toujours connecté ». Par conséquent, si vous voulez déterminer le statut de l'accès à Internet d'Electron, vous devrez mettre en œuvre des moyens supplémentaires de vérification.
En partant d'un fichier HTML index.html, cet exemple démontrera comment l'API navigator.onLine peut être utilisée pour construire un indicateur d'état de connexion.
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n</head>\n<body>\n <h1>Connection status: <strong id='status'></strong></h1>\n <script src=\"renderer.js\"></script>\n</body>\n</html>\nIn order to mutate the DOM, create a renderer.js file that adds event listeners to the 'online' and 'offline' window events. The event handler sets the content of the <strong id='status'> element depending on the result of navigator.onLine.
function updateOnlineStatus () {\n document.getElementById('status').innerHTML = navigator.onLine ? 'online' : 'offline'\n}\n\nwindow.addEventListener('online', updateOnlineStatus)\nwindow.addEventListener('offline', updateOnlineStatus)\n\nupdateOnlineStatus()\nFinally, create a main.js file for main process that creates the window.
const { app, BrowserWindow } = require('electron')\n\nfunction createWindow () {\n const onlineStatusWindow = new BrowserWindow({\n width: 400,\n height: 100\n })\n\n onlineStatusWindow.loadFile('index.html')\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nAfter launching the Electron application, you should see the notification:
\n
\n", "title": "Détection des événements en ligne/hors ligne", "description": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API." }, "/docs/development/patches": { "locale": "fr-FR", "slug": "patches", "href": "/docs/development/patches", "crowdinFileId": "256161", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/patches.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API.
\n
Electron is built on two major upstream projects: Chromium and Node.js. Chacun de ces projets a également plusieurs de ses propres dépendances. Nous faisons de notre mieux pour utiliser ces dépendances exactement telles qu'elles sont, mais parfois nous ne pouvons pas atteindre nos objectifs sans corriger ces dépendances en amont pour les adapter à nos cas d'utilisation.
\nChaque patch dans Electron est une charge de maintenance. When upstream code changes, patches can break—sometimes without even a patch conflict or a compilation error. It's an ongoing effort to keep our patch set up-to-date and effective. Nous nous efforçons donc de maintenir notre nombre de patchs au minimum. À cette fin, chaque patch doit décrire sa raison d'être dans son message de commit. Cette raison doit être l'une des suivantes :
\nProfile). Include reasoning about why the change cannot be implemented without a patch (e.g. by subclassing or copying the code).In general, all the upstream projects we work with are friendly folks and are often happy to accept refactorings that allow the code in question to be compatible with both Electron and the upstream project. (See e.g. this change in Chromium, which allowed us to remove a patch that did the same thing, or this change in Node, which was a no-op for Node but fixed a bug in Electron.) We should aim to upstream changes whenever we can, and avoid indefinite-lifetime patches.
\nIf you find yourself in the unfortunate position of having to make a change which can only be made through patching an upstream project, you'll need to know how to manage patches in Electron.
\nAll patches to upstream projects in Electron are contained in the patches/ directory. Each subdirectory of patches/ contains several patch files, along with a .patches file which lists the order in which the patches should be applied. Think of these files as making up a series of git commits that are applied on top of the upstream project after we check it out.
patches\n├── config.json <-- this describes which patchset directory is applied to what project\n├── chromium\n│ ├── .patches\n│ ├── accelerator.patch\n│ ├── add_contentgpuclient_precreatemessageloop_callback.patch\n│ ⋮\n├── node\n│ ├── .patches\n│ ├── add_openssl_is_boringssl_guard_to_oaep_hash_check.patch\n│ ├── build_add_gn_build_files.patch\n│ ⋮\n⋮\nTo help manage these patch sets, we provide two tools: git-import-patches and git-export-patches. git-import-patches imports a set of patch files into a git repository by applying each patch in the correct order and creating a commit for each one. git-export-patches does the reverse; it exports a series of git commits in a repository into a set of files in a directory and an accompanying .patches file.
\n\nSide note: the reason we use a
\n.patchesfile to maintain the order of applied patches, rather than prepending a number like001-to each file, is because it reduces conflicts related to patch ordering. It prevents the situation where two PRs both add a patch at the end of the series with the same numbering and end up both getting merged resulting in a duplicate identifier, and it also reduces churn when a patch is added or deleted in the middle of the series.
$ cd src/third_party/electron_node\n$ vim some/code/file.cc\n$ git commit\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\n\n\nNOTE:
\ngit-export-patchesignores any uncommitted files, so you must create a commit if you want your changes to be exported. The subject line of the commit message will be used to derive the patch file name, and the body of the commit message should include the reason for the patch's existence.
Re-exporting patches will sometimes cause shasums in unrelated patches to change. This is generally harmless and can be ignored (but go ahead and add those changes to your PR, it'll stop them from showing up for other people).
\n$ cd src/v8\n$ vim some/code/file.cc\n$ git log\n# Find the commit sha of the patch you want to edit.\n$ git commit --fixup [COMMIT_SHA]\n$ git rebase --autosquash -i [COMMIT_SHA]^\n$ ../electron/script/git-export-patches -o ../electron/patches/v8\n$ vim src/electron/patches/node/.patches\n# Delete the line with the name of the patch you want to remove\n$ cd src/third_party/electron_node\n$ git reset --hard refs/patches/upstream-head\n$ ../../electron/script/git-import-patches ../../electron/patches/node\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\nNote that git-import-patches will mark the commit that was HEAD when it was run as refs/patches/upstream-head. This lets you keep track of which commits are from Electron patches (those that come after refs/patches/upstream-head) and which commits are in upstream (those before refs/patches/upstream-head).
When updating an upstream dependency, patches may fail to apply cleanly. Often, the conflict can be resolved automatically by git with a 3-way merge. You can instruct git-import-patches to use the 3-way merge algorithm by passing the -3 argument:
$ cd src/third_party/electron_node\n# If the patch application failed midway through, you can reset it with:\n$ git am --abort\n# And then retry with 3-way merge:\n$ ../../electron/script/git-import-patches -3 ../../electron/patches/node\nIf git-import-patches -3 encounters a merge conflict that it can't resolve automatically, it will pause and allow you to resolve the conflict manually. Once you have resolved the conflict, git add the resolved files and continue to apply the rest of the patches by running git am --continue.
Developers frequently ask about strategies to optimize the performance of Electron applications. Software engineers, consumers, and framework developers do not always agree on one single definition of what \"performance\" means. This document outlines some of the Electron maintainers' favorite ways to reduce the amount of memory, CPU, and disk resources being used while ensuring that your app is responsive to user input and completes operations as quickly as possible. Furthermore, we want all performance strategies to maintain a high standard for your app's security.
\nWisdom and information about how to build performant websites with JavaScript generally applies to Electron apps, too. To a certain extent, resources discussing how to build performant Node.js applications also apply, but be careful to understand that the term \"performance\" means different things for a Node.js backend than it does for an application running on a client.
\nThis list is provided for your convenience – and is, much like our security checklist – not meant to exhaustive. It is probably possible to build a slow Electron app that follows all the steps outlined below. Electron is a powerful development platform that enables you, the developer, to do more or less whatever you want. All that freedom means that performance is largely your responsibility.
\nThe list below contains a number of steps that are fairly straightforward and easy to implement. However, building the most performant version of your app will require you to go beyond a number of steps. Instead, you will have to closely examine all the code running in your app by carefully profiling and measuring. Where are the bottlenecks? When the user clicks a button, what operations take up the brunt of the time? While the app is simply idling, which objects take up the most memory?
\nTime and time again, we have seen that the most successful strategy for building a performant Electron app is to profile the running code, find the most resource-hungry piece of it, and to optimize it. Repeating this seemingly laborious process over and over again will dramatically increase your app's performance. Experience from working with major apps like Visual Studio Code or Slack has shown that this practice is by far the most reliable strategy to improve performance.
\nTo learn more about how to profile your app's code, familiarize yourself with the Chrome Developer Tools. For advanced analysis looking at multiple processes at once, consider the Chrome Tracing tool.
\nChances are that your app could be a little leaner, faster, and generally less resource-hungry if you attempt these steps.
\nBefore adding a Node.js module to your application, examine said module. How many dependencies does that module include? What kind of resources does it need to simply be called in a require() statement? You might find that the module with the most downloads on the NPM package registry or the most stars on GitHub is not in fact the leanest or smallest one available.
The reasoning behind this recommendation is best illustrated with a real-world example. During the early days of Electron, reliable detection of network connectivity was a problem, resulting many apps to use a module that exposed a simple isOnline() method.
That module detected your network connectivity by attempting to reach out to a number of well-known endpoints. For the list of those endpoints, it depended on a different module, which also contained a list of well-known ports. This dependency itself relied on a module containing information about ports, which came in the form of a JSON file with more than 100,000 lines of content. Whenever the module was loaded (usually in a require('module') statement), it would load all its dependencies and eventually read and parse this JSON file. Parsing many thousands lines of JSON is a very expensive operation. On a slow machine it can take up whole seconds of time.
In many server contexts, startup time is virtually irrelevant. A Node.js server that requires information about all ports is likely actually \"more performant\" if it loads all required information into memory whenever the server boots at the benefit of serving requests faster. The module discussed in this example is not a \"bad\" module. Electron apps, however, should not be loading, parsing, and storing in memory information that it does not actually need.
\nIn short, a seemingly excellent module written primarily for Node.js servers running Linux might be bad news for your app's performance. In this particular example, the correct solution was to use no module at all, and to instead use connectivity checks included in later versions of Chromium.
\nWhen considering a module, we recommend that you check:
\nrequire()) itGenerating a CPU profile and a heap memory profile for loading a module can be done with a single command on the command line. In the example below, we're looking at the popular module request.
node --cpu-prof --heap-prof -e \"require('request')\"\nExecuting this command results in a .cpuprofile file and a .heapprofile file in the directory you executed it in. Both files can be analyzed using the Chrome Developer Tools, using the Performance and Memory tabs respectively.
Dans cet exemple, sur la machine de l'auteur, nous avons vu que le chargement du module Request `a pris près d'une demi-seconde, alors quenode-fetch` a pris beaucoup moins de mémoire et moins de 50ms.
If you have expensive setup operations, consider deferring those. Inspect all the work being executed right after the application starts. Instead of firing off all operations right away, consider staggering them in a sequence more closely aligned with the user's journey.
\nIn traditional Node.js development, we're used to putting all our require() statements at the top. If you're currently writing your Electron application using the same strategy and are using sizable modules that you do not immediately need, apply the same strategy and defer loading to a more opportune time.
Loading modules is a surprisingly expensive operation, especially on Windows. When your app starts, it should not make users wait for operations that are currently not necessary.
\nThis might seem obvious, but many applications tend to do a large amount of work immediately after the app has launched - like checking for updates, downloading content used in a later flow, or performing heavy disk I/O operations.
\nLet's consider Visual Studio Code as an example. When you open a file, it will immediately display the file to you without any code highlighting, prioritizing your ability to interact with the text. Once it has done that work, it will move on to code highlighting.
\nLet's consider an example and assume that your application is parsing files in the fictitious .foo format. In order to do that, it relies on the equally fictitious foo-parser module. In traditional Node.js development, you might write code that eagerly loads dependencies:
const fs = require('fs')\nconst fooParser = require('foo-parser')\n\nclass Parser {\n constructor () {\n this.files = fs.readdirSync('.')\n }\n\n getParsedFiles () {\n return fooParser.parse(this.files)\n }\n}\n\nconst parser = new Parser()\n\nmodule.exports = { parser }\nIn the above example, we're doing a lot of work that's being executed as soon as the file is loaded. Do we need to get parsed files right away? Could we do this work a little later, when getParsedFiles() is actually called?
// \"fs\" is likely already being loaded, so the `require()` call is cheap\nconst fs = require('fs')\n\nclass Parser {\n async getFiles () {\n // Touch the disk as soon as `getFiles` is called, not sooner.\n // Also, ensure that we're not blocking other operations by using\n // the asynchronous version.\n this.files = this.files || await fs.readdir('.')\n\n return this.files\n }\n\n async getParsedFiles () {\n // Our fictitious foo-parser is a big and expensive module to load, so\n // defer that work until we actually need to parse files.\n // Since `require()` comes with a module cache, the `require()` call\n // will only be expensive once - subsequent calls of `getParsedFiles()`\n // will be faster.\n const fooParser = require('foo-parser')\n const files = await this.getFiles()\n\n return fooParser.parse(files)\n }\n}\n\n// This operation is now a lot cheaper than in our previous example\nconst parser = new Parser()\n\nmodule.exports = { parser }\nIn short, allocate resources \"just in time\" rather than allocating them all when your app starts.
\nElectron's main process (sometimes called \"browser process\") is special: It is the parent process to all your app's other processes and the primary process the operating system interacts with. It handles windows, interactions, and the communication between various components inside your app. It also houses the UI thread.
\nUnder no circumstances should you block this process and the UI thread with long-running operations. Blocking the UI thread means that your entire app will freeze until the main process is ready to continue processing.
\nThe main process and its UI thread are essentially the control tower for major operations inside your app. When the operating system tells your app about a mouse click, it'll go through the main process before it reaches your window. If your window is rendering a buttery-smooth animation, it'll need to talk to the GPU process about that – once again going through the main process.
\nElectron and Chromium are careful to put heavy disk I/O and CPU-bound operations onto new threads to avoid blocking the UI thread. You should do the same.
\nElectron's powerful multi-process architecture stands ready to assist you with your long-running tasks, but also includes a small number of performance traps.
\n1) For long running CPU-heavy tasks, make use of worker threads, consider moving them to the BrowserWindow, or (as a last resort) spawn a dedicated process.
\n2) Avoid using the synchronous IPC and the remote module as much as possible. While there are legitimate use cases, it is far too easy to unknowingly block the UI thread using the remote module.
3) Avoid using blocking I/O operations in the main process. Bref, chaque fois que des modules coeur de Node.js (comme fs ou child_process) offrent une version synchrone ou une version asynchrone vous devriez préférer la variante asynchrone et non-bloquant .
Since Electron ships with a current version of Chrome, you can make use of the latest and greatest features the Web Platform offers to defer or offload heavy operations in a way that keeps your app smooth and responsive.
\nYour app probably has a lot of JavaScript to run in the renderer process. The trick is to execute operations as quickly as possible without taking away resources needed to keep scrolling smooth, respond to user input, or animations at 60fps.
\nOrchestrating the flow of operations in your renderer's code is particularly useful if users complain about your app sometimes \"stuttering\".
\nGenerally speaking, all advice for building performant web apps for modern browsers apply to Electron's renderers, too. The two primary tools at your disposal are currently requestIdleCallback() for small operations and Web Workers for long-running operations.
requestIdleCallback() allows developers to queue up a function to be executed as soon as the process is entering an idle period. It enables you to perform low-priority or background work without impacting the user experience. For more information about how to use it, check out its documentation on MDN.
Web Workers are a powerful tool to run code on a separate thread. There are some caveats to consider – consult Electron's multithreading documentation and the MDN documentation for Web Workers. They're an ideal solution for any operation that requires a lot of CPU power for an extended period of time.
\nOne of Electron's great benefits is that you know exactly which engine will parse your JavaScript, HTML, and CSS. If you're re-purposing code that was written for the web at large, make sure to not polyfill features included in Electron.
\nWhen building a web application for today's Internet, the oldest environments dictate what features you can and cannot use. Even though Electron supports well-performing CSS filters and animations, an older browser might not. Where you could use WebGL, your developers may have chosen a more resource-hungry solution to support older phones.
\nWhen it comes to JavaScript, you may have included toolkit libraries like jQuery for DOM selectors or polyfills like the regenerator-runtime to support async/await.
It is rare for a JavaScript-based polyfill to be faster than the equivalent native feature in Electron. Do not slow down your Electron app by shipping your own version of standard web platform features.
\nOperate under the assumption that polyfills in current versions of Electron are unnecessary. If you have doubts, check caniuse.com and check if the version of Chromium used in your Electron version supports the feature you desire.
\nIn addition, carefully examine the libraries you use. Are they really necessary? jQuery, for example, was such a success that many of its features are now part of the standard JavaScript feature set available.
If you're using a transpiler/compiler like TypeScript, examine its configuration and ensure that you're targeting the latest ECMAScript version supported by Electron.
\nAvoid fetching rarely changing resources from the internet if they could easily be bundled with your application.
\nMany users of Electron start with an entirely web-based app that they're turning into a desktop application. As web developers, we are used to loading resources from a variety of content delivery networks. Now that you are shipping a proper desktop application, attempt to \"cut the cord\" where possible and avoid letting your users wait for resources that never change and could easily be included in your app.
\nA typical example is Google Fonts. Many developers make use of Google's impressive collection of free fonts, which comes with a content delivery network. The pitch is straightforward: Include a few lines of CSS and Google will take care of the rest.
\nWhen building an Electron app, your users are better served if you download the fonts and include them in your app's bundle.
\nIn an ideal world, your application wouldn't need the network to operate at all. To get there, you must understand what resources your app is downloading - and how large those resources are.
\nTo do so, open up the developer tools. Navigate to the Network tab and check the Disable cache option. Then, reload your renderer. Unless your app prohibits such reloads, you can usually trigger a reload by hitting Cmd + R or Ctrl + R with the developer tools in focus.
The tools will now meticulously record all network requests. In a first pass, take stock of all the resources being downloaded, focusing on the larger files first. Are any of them images, fonts, or media files that don't change and could be included with your bundle? If so, include them.
\nAs a next step, enable Network Throttling. Find the drop-down that currently reads Online and select a slower speed such as Fast 3G. Reload your renderer and see if there are any resources that your app is unnecessarily waiting for. In many cases, an app will wait for a network request to complete despite not actually needing the involved resource.
As a tip, loading resources from the Internet that you might want to change without shipping an application update is a powerful strategy. For advanced control over how resources are being loaded, consider investing in Service Workers.
\nAs already pointed out in \"Loading and running code too soon\", calling require() is an expensive operation. If you are able to do so, bundle your application's code into a single file.
Modern JavaScript development usually involves many files and modules. While that's perfectly fine for developing with Electron, we heavily recommend that you bundle all your code into one single file to ensure that the overhead included in calling require() is only paid once when your application loads.
There are numerous JavaScript bundlers out there and we know better than to anger the community by recommending one tool over another. We do however recommend that you use a bundler that is able to handle Electron's unique environment that needs to handle both Node.js and browser environments.
\nAs of writing this article, the popular choices include Webpack, Parcel, and rollup.js.
", "title": "Performance", "description": "" }, "/docs/api/structures/point": { "locale": "fr-FR", "slug": "point", "href": "/docs/api/structures/point", "crowdinFileId": "256475", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/point.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "x Numbery NumberNote: Both x and y must be whole integers, when providing a point object as input to an Electron API we will automatically round your x and y values to the nearest whole integer.
data (UploadRawData | UploadFile)[] - The post data to be sent to the new window.contentType String - The content-type header used for the data. One of application/x-www-form-urlencoded or multipart/form-data. Corresponds to the enctype attribute of the submitted HTML form.boundary String (optional) - The boundary used to separate multiple parts of the message. Only valid when contentType is multipart/form-data.Note that keys starting with -- are not currently supported. For example, this will errantly submit as multipart/form-data when nativeWindowOpen is set to false in webPreferences:
<form\n target=\"_blank\"\n method=\"POST\"\n enctype=\"application/x-www-form-urlencoded\"\n action=\"https://postman-echo.com/post\"\n>\n <input type=\"text\" name=\"--theKey\">\n <input type=\"submit\">\n</form>\n\n\nSurveille les changements d'état de puissance.
\n
Processus : Main
\nLe module powerMonitor émet les événements suivants :
Émis lorsque le système est suspendu.
\nÉmis lorsque le système reprend.
\nÉmis lorsque le système est branché sur prise.
\nÉmis lorsque le système passe sur batterie.
\nÉmis lorsque le système est sur le point de redémarrer ou d'arrêter. Si le gestionnaire d'événements appelle e.preventDefault(), Electron tentera de retarder l'arrêt du système dans afin que l'application se ferme proprement. Si e.preventDefault() est appelé, l'application devrait quitter dès que possible en appelant quelque chose comme app.quit().
Émis lorsque le système est sur le point de verrouiller l'écran.
\nÉmis dès que l'écran du système est déverrouillé.
\nEmitted when a login session is activated. See documentation for more information.
\nEmitted when a login session is deactivated. See documentation for more information.
\nLe module powerMonitor a les méthodes suivantes :
format@@0 powerMonitor.getSystemIdleState(idleThreshold)idleThreshold EntierReturns String - The system's current state. Peut être active, idle, locked ou unknown.
Calculate the system idle state. idleThreshold is the amount of time (in seconds) before considered idle. locked is available on supported systems only.
getSystemIdleTime()Retourne Integer - Temps d'inactivité en secondes
Calculer le temps d'inactivité du système en secondes.
\npowerMonitor.isOnBatteryPower()Returns Boolean - Whether the system is on battery power.
To monitor for changes in this property, use the on-battery and on-ac events.
powerMonitor.onBatteryPowerUne propriété Boolean. True if the system is on battery power.
See powerMonitor.isOnBatteryPower().
\n\nBloquer le système de passer en mode de faible puissance (sommeil).
\n
Processus : Main
\nPar exemple :
\nconst { powerSaveBlocker } = require('electron')\n\nconst id = powerSaveBlocker.start('prevent-display-sleep')\nconsole.log(powerSaveBlocker.isStarted(id))\n\npowerSaveBlocker.stop(id)\nLe module powerSaveBlocker dispose des méthodes suivantes :
powerSaveBlocker.start(type)type String - Power save blocker type.prevent-app-suspension - Prevent the application from being suspended. Keeps system active but allows screen to be turned off. Example use cases: downloading a file or playing audio.prevent-display-sleep - Prevent the display from going to sleep. Keeps system and screen active. Example use case: playing video.Retourne Integer - L'ID du blocage assigné à ce power blocker.
Starts preventing the system from entering lower-power mode. Returns an integer identifying the power save blocker.
\nRemarque : prevent-display-sleep a une priorité plus élevée que prevent-app-suspension. Seulement le type de priorité le plus élevé prendra effet. En d'autres termes, prevent-display-sleep a toujours la priorité sur prevent-app-suspension.
Par exemple, une API requête A pour prevent-app-suspension, et un autre requête B pour prevent-display-sleep. prevent-display-sleep sera utilisé jusqu’à ce que la requête B se stoppe. Après cela, prevent-app-suspension est utilisé.
powerSaveBlocker.stop(id)id Integer - L'id du bloqueur d'économie d'énergie renvoyé par powerSaveBlocker.start.Arrête le bloqueur d'économie d'énergie spécifié.
\npowerSaveBlocker.isStarted(id)id Integer - L'id du bloqueur d'économie d'énergie renvoyé par powerSaveBlocker.start.Returns Boolean - Si le powerSaveBlocker correspondant a démarré.
name String - the name of the printer as understood by the OS.displayName String - the name of the printer as shown in Print Preview.description String - a longer description of the printer's type.status Number - the current status of the printer.isDefault Boolean - whether or not a given printer is set as the default printer on the OS.options Object - an object containing a variable number of platform-specific printer information.The number represented by status means different things on different platforms: on Windows its potential values can be found here, and on Linux and macOS they can be found here.
Below is an example of some of the additional options that may be set which may be different on each platform.
\n{\n name: 'Austin_4th_Floor_Printer___C02XK13BJHD4',\n displayName: 'Austin 4th Floor Printer @ C02XK13BJHD4',\n description: 'TOSHIBA ColorMFP',\n status: 3,\n isDefault: false,\n options: {\n copies: '1',\n 'device-uri': 'dnssd://Austin%204th%20Floor%20Printer%20%40%20C02XK13BJHD4._ipps._tcp.local./?uuid=71687f1e-1147-3274-6674-22de61b110bd',\n finishings: '3',\n 'job-cancel-after': '10800',\n 'job-hold-until': 'no-hold',\n 'job-priority': '50',\n 'job-sheets': 'none,none',\n 'marker-change-time': '0',\n 'number-up': '1',\n 'printer-commands': 'ReportLevels,PrintSelfTestPage,com.toshiba.ColourProfiles.update,com.toshiba.EFiling.update,com.toshiba.EFiling.checkPassword',\n 'printer-info': 'Austin 4th Floor Printer @ C02XK13BJHD4',\n 'printer-is-accepting-jobs': 'true',\n 'printer-is-shared': 'false',\n 'printer-is-temporary': 'false',\n 'printer-location': '',\n 'printer-make-and-model': 'TOSHIBA ColorMFP',\n 'printer-state': '3',\n 'printer-state-change-time': '1573472937',\n 'printer-state-reasons': 'offline-report,com.toshiba.snmp.failed',\n 'printer-type': '10531038',\n 'printer-uri-supported': 'ipp://localhost/printers/Austin_4th_Floor_Printer___C02XK13BJHD4',\n system_driverinfo: 'T'\n }\n}\n\n\n\nExtension de l'objet process.
\n
L'objet process d'Electron une extension de l'objet process de Node.js. Cela ajoute les événements, propriétés et méthodes suivantes :
Dans les moteurs de rendu en bac à sable, l'objet process ne contient qu'un sous-ensemble des APIs :
crash()hang()getCreationTime()getHeapStatistics()getBlinkMemoryInfo()getProcessMemoryInfo()getSystemMemoryInfo()getSystemVersion()getCPUUsage()getIOCounters()uptime()argvexecPathenvpidarcplateformebac à sablecontextIsolatedtypeversionversionsmaswindowsStorecontextIdÉmis lorsque Electron a chargé son script d'initialisation interne et que commence à charger la page web ou le script principal.
\nprocess.defaultApp ReadonlyA Boolean. When app is started by being passed as parameter to the default app, this property is true in the main process, otherwise it is undefined.
process.isMainFrame ReadonlyA Boolean, true when the current renderer context is the \"main\" renderer frame. If you want the ID of the current frame you should use webFrame.routingId.
process.mas ReadonlyA Boolean. For Mac App Store build, this property is true, for other builds it is undefined.
process.noAsarA Boolean that controls ASAR support inside your application. Setting this to true will disable the support for asar archives in Node's built-in modules.
process.noDeprecationUn Booléen qui contrôle si oui ou non les avertissements de dépréciation sont imprimés sur stderr. Mettre ceci à true fera taire les avertissements de dépréciation. Cette propriété est utilisée à la place du drapeau --no-deprecation.
process.resourcesPath ReadonlyUne String représentant le chemin vers le répertoire des ressources.
process.sandboxed ReadonlyA Boolean. When the renderer process is sandboxed, this property is true, otherwise it is undefined.
process.contextIsolated Lecture seuleA Boolean that indicates whether the current renderer context has contextIsolation enabled. It is undefined in the main process.
process.throwDeprecationUn Booléen qui contrôle si oui ou non les avertissements de dépréciation seront lancés sous forme d'exceptions . En définissant cette valeur à true lancera des erreurs pour les dépréciations. Cette propriété est utilisée à la place du drapeau de ligne de commande --throw-deprecation.
process.traceDeprecationUn Booléen qui contrôle si les dépréciations affichées sur stderr incluent leur trace de pile. En définissant cette valeur à true affichera les traces de piles pour les dépréciations. Cette propriété est à la place du drapeau --trace-deprecation.
process.traceProcessWarningsUn Booléen qui contrôle si oui ou non les avertissements affichés sur stderr incluent leur trace de pile. En définissant cette valeur à true affichera les traces de piles pour les avertissements de processus (y compris les dépréciations). Cette propriété est à la place du drapeau de ligne --trace-warnings de la commande .
process.type ReadonlyA String representing the current process's type, can be:
browser - The main processrenderer - A renderer processworker - In a web workerprocess.versions.chrome ReadonlyUn String représentant la version de Chrome.
process.versions.electron ReadonlyUn String représentant la version d'Electron.
process.windowsStore ReadonlyA Boolean. If the app is running as a Windows Store app (appx), this property is true, for otherwise it is undefined.
process.contextId Lecture seuleA String (optional) representing a globally unique ID of the current JavaScript context. Each frame has its own JavaScript context. When contextIsolation is enabled, the isolated world also has a separate JavaScript context. This property is only available in the renderer process.
L'objet process dispose des méthodes suivantes :
process.crash()Cause le thread principal du processus en cours de plantage.
\nprocess.getCreationTime()Retourne Nombre | null - Le nombre de millisecondes depuis Epoch, ou null si l'information est indisponible
Indicates the creation time of the application. Le temps est représenté par le nombre de millisecondes depuis l'epoch. It returns null if it is unable to get the process creation time.
\nprocess.getCPUUsage()Retourne CPUUsage
process.getIOCounters() Windows LinuxRetourne IOCounters
process.getHeapStatistics()Retourne Object:
totalHeapSize IntegertotalHeapSizeExecutable EntierTaillephysique EntierTaille totale EntierusedHeapSize IntegerheapSizeLimit IntegerMémoire de malloced EntierpeakMallocedMemory IntegerdoesZapGarbage BooleanReturns an object with V8 heap statistics. Notez que toutes les statistiques sont en kilo-octets.
\nprocess.getBlinkMemoryInfo()Retourne Object:
alloué Integer - Taille de tous les objets alloués dans Kilobytes.marked Integer - Taille de tous les objets marqués dans Kilobytes.total Integer - Espace total alloué en kilobytes.Returns an object with Blink memory information. It can be useful for debugging rendering / DOM related memory issues. Note that all values are reported in Kilobytes.
\nprocess.getProcessMemoryInfo()Retourne Promise<ProcessMemoryInfo> - résout avec un ProcessMemoryInfo
Returns an object giving memory usage statistics about the current process. Note that all statistics are reported in Kilobytes. This api should be called after app ready.
\nChromium ne fournit pas de valeur residentSet pour macOS. Ceci est dû au fait que macOS effectue une compression en mémoire des pages qui n'ont pas été récemment utilisées. En tant que résultat la valeur de la taille de la définition résident n'est pas celle qu'on pourrait attendre. la mémoire privé est plus représentative de l'utilisation réelle de la mémoire de pré-compression du processus sur macOS.
process.getSystemMemoryInfo()Retourne Object:
total Integer - La quantité totale de mémoire physique dans Kilobytes disponibles pour le système .libre Integer - La quantité totale de mémoire non utilisée par les applications ou le cache du disque.swapTotal Integer Windows Linux - La quantité totale de mémoire swap dans Kilobytes disponible pour le système .swapFree Integer Windows Linux - La quantité gratuite de mémoire swap dans Kilobytes disponible pour le système .Returns an object giving memory usage statistics about the entire system. Note that all statistics are reported in Kilobytes.
\nprocess.getSystemVersion()Retourne String - La version du système d'exploitation hôte.
Exemple :
\nconst version = process.getSystemVersion()\nconsole.log(version)\n// Sur macOS -> '10. 3.6'\n// Sous Windows -> '10.0.17763'\n// Sous Linux -> '4.15.0-45-générique'\nRemarque : Il retourne la version réelle du système d'exploitation au lieu de la version du noyau sur macOS contrairement à os.release().
process.takeHeapSnapshot(filePath)filePath String - Chemin vers le fichier de sortie.Retourne Boolean - Indique si l'instantané a été créé avec succès.
Prend un instantané de tas V8 et l'enregistre dans filePath.
process.hang()Cause le fil de discussion principal du processus actuel.
\nprocess.setFdLimit(maxDescriptors) macOS LinuxmaxDescriptors IntegerDéfinit la limite de programmation du descripteur de fichier à maxDescriptors ou la limite de dur de l'OS, quelle que soit la plus faible pour le processus en cours.
residentSet Integer Linux Windows - The amount of memory currently pinned to actual physical RAM in Kilobytes.private Integer - The amount of memory not shared by other processes, such as JS heap or HTML content in Kilobytes.shared Integer - The amount of memory shared between processes, typically memory consumed by the Electron code itself in Kilobytes.pid Integer - Process id of the process.type String - Type de processus. Une des valeurs suivantes:BrowserTabUtilitaireZygoteAssistant bac à sableGPUPlugin PepperBroker de plugin PepperInconnuserviceName String (optional) - The non-localized name of the process.name String (optional) - The name of the process. Examples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.cpu CPUUsage - CPU usage of the process.creationTime Number - Creation time for this process. The time is represented as number of milliseconds since epoch. Since the pid can be reused after a process dies, it is useful to use both the pid and the creationTime to uniquely identify a process.memory MemoryInfo - Memory information for the process.sandboxed Boolean (optional) macOS Windows - Whether the process is sandboxed on OS level.integrityLevel String (optional) Windows - One of the following values:untrustedlowmediumhighunknownElectron hérite de son architecture multi-processus de Chromium, ce qui rend le framework architecturalement très similaire à un navigateur web moderne. Dans ce guide, nous allons exposer connaissances conceptuelles d’Electron que nous avons appliquées dans l’application de démarrage rapide minimale [][].
\nWeb browsers are incredibly complicated applications. Aside from their primary ability to display web content, they have many secondary responsibilities, such as managing multiple windows (or tabs) and loading third-party extensions.
\nDans les jours précédents, les navigateurs ont généralement utilisé un processus unique pour toutes ces fonctionnalités . Bien que ce modèle signifiait moins de frais pour chaque onglet, vous aviez ouverts, cela signifiait également qu'un site Web plantait ou suspendait affecterait l'ensemble du navigateur.
\nPour résoudre ce problème, l'équipe de Chrome a décidé que chaque onglet serait rendu dans son propre processus , limiter les dommages que le code bogué ou malveillant sur une page web pourrait causer à l'application dans son ensemble. Un seul processus de navigateur contrôle ensuite ces processus, ainsi que que le cycle de vie de l'application dans son ensemble. Ce diagramme ci-dessous de la Bd Chrome visualise ce modèle :
\n
Electron applications are structured very similarly. En tant que développeur d'applications, vous contrôlez deux types de processus : principal et moteur de rendu. These are analogous to Chrome's own browser and renderer processes outlined above.
\nEach Electron app has a single main process, which acts as the application's entry point. The main process runs in a Node.js environment, meaning it has the ability to require modules and use all of Node.js APIs.
The main process' primary purpose is to create and manage application windows with the BrowserWindow module.
Each instance of the BrowserWindow class creates an application window that loads a web page in a separate renderer process. You can interact with this web content from the main process using the window's webContents object.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\n\n\nNote: A renderer process is also created for web embeds such as the
\nBrowserViewmodule. ThewebContentsobject is also accessible for embedded web content.
Because the BrowserWindow module is an EventEmitter, you can also add handlers for various user events (for example, minimizing or maximizing your window).
When a BrowserWindow instance is destroyed, its corresponding renderer process gets terminated as well.
The main process also controls your application's lifecycle through Electron's app module. This module provides a large set of events and methods that you can use to add custom application behaviour (for instance, programatically quitting your application, modifying the application dock, or showing an About panel).
As a practical example, the app shown in the quick start guide uses app APIs to create a more native application window experience.
// fermeture de l'application lrsqu'aucune fenêtre n'est ouverte et ce sur les plateformes non-macOS.\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nTo extend Electron's features beyond being a Chromium wrapper for web contents, the main process also adds custom APIs to interact with the user's operating system. Electron exposes various modules that control native desktop functionality, such as menus, dialogs, and tray icons.
\nFor a full list of Electron's main process modules, check out our API documentation.
\nEach Electron app spawns a separate renderer process for each open BrowserWindow (and each web embed). As its name implies, a renderer is responsible for rendering web content. For all intents and purposes, code ran in renderer processes should behave according to web standards (insofar as Chromium does, at least).
Therefore, all user interfaces and app functionality within a single browser window should be written with the same tools and paradigms that you use on the web.
\nAlthough explaining every web spec is out of scope for this guide, the bare minimum to understand is:
\n<script> elements.Moreover, this also means that the renderer has no direct access to require or other Node.js APIs. In order to directly include NPM modules in the renderer, you must use the same bundler toolchains (for example, webpack or parcel) that you use on the web.
\n\nNote: Renderer processes can be spawned with a full Node.js environment for ease of development. Historiquement, c'était la valeur par défaut, mais cette fonctionnalité a été désactivée pour des raisons de sécurité.
\n
At this point, you might be wondering how your renderer process user interfaces can interact with Node.js and Electron's native desktop functionality if these features are only accessible from the main process. In fact, there is no direct way to import Electron's content scripts.
\nA preload script can be attached to the main process in the BrowserWindow constructor's webPreferences option.
const { BrowserWindow } = require('electron')\n//...\nconst win = new BrowserWindow({\n webPreferences: {\n preload: 'path/to/preload.js'\n }\n})\n//...\nBecause the preload script shares a global Window interface with the renderers and can access Node.js APIs, it serves to enhance your renderer by exposing arbitrary APIs in the window global that your web contents can then consume.
Although preload scripts share a window global with the renderer they're attached to, you cannot directly attach any variables from the preload script to window because of the contextIsolation default.
window.myAPI = {\n desktop: true\n}\nconsole.log(window.myAPI)\n// => undefined\nContext Isolation means that preload scripts are isolated from the renderer's main world to avoid leaking any privileged APIs into your web content's code.
\nInstead, use the contextBridge module to accomplish this securely:
const { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n desktop: true\n})\nconsole.log(window.myAPI)\n// => { desktop: true }\nCette fonctionnalité est incroyablement utile pour deux objectifs principaux :
\nipcRenderer helpers to the renderer, you can use inter-process communication (IPC) to trigger main process tasks from the renderer (and vice-versa).window global that can be used for desktop-only logic on the web client's side.productIdentifier String - The string that identifies the product to the Apple App Store.localizedDescription String - A description of the product.localizedTitle String - The name of the product.contentVersion String - A string that identifies the version of the content.contentLengths Number[] - The total size of the content, in bytes.price Number - The cost of the product in the local currency.formattedPrice String - The locale formatted price of the product.currencyCode String - 3 character code presenting a product's currency based on the ISO 4217 standard.isDownloadable Boolean - A Boolean value that indicates whether the App Store has downloadable content for this product. true if at least one file has been associated with the product.Une barre de progression permet à une fenêtre de fournir une informations à l'utilisateur sur la progression sans avoir besoin de basculer sur cette même fenêtre.
\nSous Windows, vous pouvez utiliser un bouton de la barre des tâches pour afficher une barre de progression.
\n![Windows Progress Bar][https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png\\]
\nSous macOS, la barre de progression s'affichera dans le cadre de l'icône du dock.
\n
Sur Linux, l’interface graphique Unity dispose également d’une fonctionnalité similaire qui vous permet de spécifier la barre de progression dans le lanceur.
\n
\n\nREMARQUE : sur Windows, chaque fenêtre peut avoir sa propre barre de progression, tandis que sur macOS et Linux (Unity) il ne peut y avoir qu’une seule barre de progression pour l’application.
\n
Les trois cas sont couverts par la même API - la méthode setProgressBar() disponible sur une instance de BrowserWindows. Pour indiquer l'état de la progression vous devez appeler cette méthode avec un nombre entre 0 et 1. Par exemple: Si vous avez une tâche qui dure relativement longtemps et qui est en est actuellement à 63% avant sa finalisation, vous l'appelleriez avec setProgressBar(0.63).
Si le paramètre à une valeur négative (par exemple -1) cela supprimera la barre de progression. . Une valeur supérieure à 1 indiquera sous Windows une barre de progression indéfinie et la verrouillera à 100% avec les autres systèmes d'exploitation. Une barre de progression indéterminée reste active mais n’affiche pas de pourcentage réel et est utilisée pour les situations où on ne sait pas combien de temps une opération prendra pour se terminer.
Voir la documentation API pour plus d'options et de modes.
\nDans cet exemple, nous ajoutons une barre de progression à la fenêtre principale qui s’incrémente au fil du temps à l’aide des timers de Node.js.
\nconst { app, BrowserWindow } = require('electron')\n\nlet progressInterval\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n\n const INCREMENT = 0.03\n const INTERVAL_DELAY = 100 // ms\n\n let c = 0\n progressInterval = setInterval(() => {\n // update progress bar to next value\n // values between 0 and 1 will show progress, >1 will show indeterminate or stick at 100%\n win.setProgressBar(c)\n\n // increment or reset progress bar\n if (c < 2) c += INCREMENT\n else c = 0\n }, INTERVAL_DELAY)\n}\n\napp.whenReady().then(createWindow)\n\n// before the app is terminated, clear both timers\napp.on('before-quit', () => {\n clearInterval(progressInterval)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nAprès le lancement de l’application Electron, le dock (macOS) ou la barre des tâches (Windows, Unity) affichera une barre de progression qui commence à zéro et progresse jusqu’à 100 % à la fin. Cela devrait alors s'afficher brièvement en indéterminé (Windows) ou vérouillé à 100% (autres systèmes d'exploitation), puis boucler.
\n
Pour macOS, la barre de progression de votre application sera également indiquée lors de l'utilisation de Mission Control:
\n
\n\nEnregistrez un protocole personnalisé et interceptez les requêtes de protocole existantes.
\n
Processus : Main
\nUn exemple d'implémentation d'un protocole qui a le même effet que le protocole file:// :
const { app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n})\nNote : Toutes les méthodes si non spécifiées ne peuvent être utilisées qu'après que l'évènement ready de l' app ne soit émis.
protocole avec une partition personnalisée ou sessionA protocol is registered to a specific Electron session object. If you don't specify a session, then your protocol will be applied to the default session that Electron uses. However, if you define a partition or session on your browserWindow's webPreferences, then that window will use a different session and your custom protocol will not work if you just use electron.protocol.XXX.
To have your custom protocol work in combination with a custom session, you need to register it to that session explicitly.
\nconst { session, app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const partition = 'persist:example'\n const ses = session.fromPartition(partition)\n\n ses.protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n\n mainWindow = new BrowserWindow({ webPreferences: { partition } })\n})\nLe module protocol dispose des méthodes suivantes :
protocol.registerSchemesAsPriviled(customSchemes)customSchemes CustomScheme[]Note: Cette méthode ne peut être utilisée qu'avant l'événement ready du app est émis et ne peut être appelé qu'une seule fois.
Registers the scheme as standard, secure, bypasses content security policy for resources, allows registering ServiceWorker, supports fetch API, and streaming video/audio. Specify a privilege with the value of true to enable the capability.
An example of registering a privileged scheme, that bypasses Content Security Policy:
\nconst { protocol } = require('electron')\nprotocol.registerSchemesAsPrivileged([\n { scheme: 'foo', privilèges: { bypassCSP: true } }\n])\nUn schéma standard adhère à ce que la RFC 3986 appelle la syntaxe générique de l'URI . Par exemple http et https sont des schémas standard, alors que file ne l'est pas.
Registering a scheme as standard allows relative and absolute resources to be resolved correctly when served. Sinon, le schéma se comportera comme le protocole fichier, mais sans la possibilité de résoudre les URL relatives.
Par exemple lorsque vous chargez la page suivante avec un protocole personnalisé sans l'enregistrer en tant que schéma standard, l'image ne sera pas chargée car les schémas non standards ne peuvent pas reconnaître les URL relatives :
\n<body>\n <img src='test.png'>\n</body>\nL'enregistrement d'un schéma en tant que standard permettra l'accès aux fichiers via l'API FileSystem API. Sinon, le moteur de rendu lancera une erreur de sécurité pour le schéma.
\nBy default web storage apis (localStorage, sessionStorage, webSQL, indexedDB, cookies) are disabled for non standard schemes. So in general if you want to register a custom protocol to replace the http protocol, you have to register it as a standard scheme.
Protocols that use streams (http and stream protocols) should set stream: true. The <video> and <audio> HTML elements expect protocols to buffer their responses by default. The stream flag configures those elements to correctly expect streaming responses.
protocol.registerFileProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a file as the response. The handler will be called with request and callback where request is an incoming request for the scheme.
Pour gérer la requête, la callback doit être appelée soit avec le chemin du fichier, soit avec un objet qui a une propriété chemin. . callback(filePath) ou callback({ path: filePath }). The filePath must be an absolute path.
By default the scheme is treated like http:, which is parsed differently from protocols that follow the \"generic URI syntax\" like file:.
protocol.registerBufferProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Enregistre un protocole de schéma qui enverra un Buffer en tant que réponse.
The usage is the same with registerFileProtocol, except that the callback should be called with either a Buffer object or an object that has the data property.
Exemple :
\nprotocol.registerBufferProtocol('atom', (request, callback) => {\n callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })\n})\nprotocol.registerStringProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Enregistre un protocole de schéma qui enverra une String en tant que réponse.
The usage is the same with registerFileProtocol, except that the callback should be called with either a String or an object that has the data property.
protocol.registerHttpProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully registered
Enregistre un protocole de schéma qui enverra une requête HTTP en réponse.
The usage is the same with registerFileProtocol, except that the callback should be called with an object that has the url property.
protocol.registerStreamProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a stream as a response.
The usage is the same with registerFileProtocol, except that the callback should be called with either a ReadableStream object or an object that has the data property.
Exemple :
\nconst { protocol } = require('electron')\nconst { PassThrough } = require('stream')\n\nfunction createStream (text) {\n const rv = new PassThrough() // PassThrough is also a Readable stream\n rv.push(text)\n rv.push(null)\n return rv\n}\n\nprotocol.registerStreamProtocol('atom', (request, callback) => {\n callback({\n statusCode: 200,\n headers: {\n 'content-type': 'text/html'\n },\n data: createStream('<h5>Response</h5>')\n })\n})\nIt is possible to pass any object that implements the readable stream API (emits data/end/error events). For example, here's how a file could be returned:
protocol.registerStreamProtocol('atom', (request, callback) => {\n callback(fs.createReadStream('index.html'))\n})\nprotocol.unregisterProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unregistered
Enregistre le protocole personnalisé de schéma.
protocol.isProtocolRegistered(scheme)scheme StringReturns Boolean - Whether scheme is already registered.
protocol.interceptFileProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepte le protocole schéma et utilise handler comme nouveau gestionnaire du protocole, qui envoie un fichier comme réponse.
protocol.interceptStringProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepte le protocole schéma et utilise handler comme nouveau gestionnaire du protocole, qui envoie une String comme réponse.
protocol.interceptBufferProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepte le protocole schéma et utilise handler comme nouveau gestionnaire du protocole, qui envoie un Buffer comme réponse.
protocol.interceptHttpProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully intercepted
Intercepte le protocole schéma et utilise handler comme nouveau gestionnaire du protocole, qui envoie une nouvelle requête HTTP comme réponse.
protocol.interceptStreamProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Identique à protocol.registerStreamProtocol, excepté qu'il remplace un gestionnaire de protocole existant.
protocol.uninterceptProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unintercepted
Retirez l'intercepteur installé pour schéma et restaurez son gestionnaire d'origine.
protocol.isProtocolIntercepted(scheme)scheme StringReturns Boolean - Whether scheme is already intercepted.
url Stringreferrer Stringmethod StringuploadData UploadData[] (optional)headers Record<String, String>error Integer (optional) - When assigned, the request will fail with the error number . For the available error numbers you can use, please see the net error list.statusCode Number (optional) - The HTTP response code, default is 200.charset String (optional) - The charset of response body, default is \"utf-8\".mimeType String (optional) - The MIME type of response body, default is \"text/html\". Setting mimeType would implicitly set the content-type header in response, but if content-type is already set in headers, the mimeType would be ignored.headers Record<string, string | string[]> (optional) - An object containing the response headers. The keys must be String, and values must be either String or Array of String.data (Buffer | String | ReadableStream) (optional) - The response body. When returning stream as response, this is a Node.js readable stream representing the response body. When returning Buffer as response, this is a Buffer. When returning String as response, this is a String. This is ignored for other types of responses.path String (optional) - Path to the file which would be sent as response body. This is only used for file responses.url String (optional) - Download the url and pipe the result as response body. This is only used for URL responses.referrer String (optional) - The referrer URL. This is only used for file and URL responses.method String (optional) - The HTTP method. This is only used for file and URL responses.session Session (optional) - The session used for requesting URL, by default the HTTP request will reuse the current session. Setting session to null would use a random independent session. This is only used for URL responses.uploadData ProtocolResponseUploadData (optional) - The data used as upload data. This is only used for URL responses when method is \"POST\".contentType String - MIME type of the content.data String | Buffer - Content to be sent.Fork the project on GitHub and clone your fork locally.
\n$ git clone git@github.com:username/electron.git\n$ cd electron\n$ git remote add upstream https://github.com/electron/electron.git\n$ git fetch upstream\nLe type de système d'exploitation peut faire varier les étapes de construction et les dépendances. Reportez vous au guide dédié pour compiler Electron:
\n\nDès que le projet est construit, vous pouvez apporter des modifications !
\nPour un environnement de développement ordonné, créez une branche locale qui contiendra votre travail. Votre branche doit être crée directement à partir de la branche main.
$ git checkout -b my-branch -t upstream/main\nMost pull requests opened against the electron/electron repository include changes to either the C/C++ code in the shell/ folder, the JavaScript code in the lib/ folder, the documentation in docs/api/ or tests in the spec/ folder.
Penser à lancer régulièrement npm run lint après chaque évolution du code, pour en garantir la conformité de style du projet.
Voir coding style pour plus d'informations sur les meilleurs usages lors de modification de code dans les différentes parties du projet.
\nIl est recommandé de regrouper logiquement les modifications dans des commit dédiés. La plus-part des contributeurs préfèrent passer en revue les changements faits de plusieurs commit. Il est possible d'avoir autant de commit que nécessaire lors d'une proposition d'évolution - demande de Pull - .
\n$ git add my/changed/files\n$ git commit\nAu final lorsqu'ils sont revus, de nombreux commit sont fusionnés.
\nUn bon message de modification/commit doit décrire le changement et sa raison. The Electron project uses semantic commit messages to streamline the release process.
\nBefore a pull request can be merged, it must have a pull request title with a semantic prefix.
\nExemples de messages de commit avec préfixes sémantiques :
\nfix: don't overwrite prevent_default if default wasn't preventedfeat: add app.isPackaged() methoddocs: app.isDefaultProtocolClient is now available on LinuxCommon prefixes:
\nAutres choses à garder à l'esprit lors de la rédaction d'un message de commit :
\nA commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with Major in semantic versioning). A breaking change can be part of commits of any type. e.g., a fix:, feat: & chore: types would all be valid, in addition to any other type.
Voir conventionalcommits.org pour plus de détails.
\nUne fois vos changements livrés-\"committés\", il est recommander d'utiliser git rebase plutôt que git merge pour réintégrer l'historique général dans votre branche de travail.
$ git fetch upstream\n$ git rebase upstream/main\nCela garantit que votre branche de travail a les dernières modifications de electron/electron main.
Corrections et fonctionnalités doivent toujours être accompagnées de tests. Un guide du test est fourni pour rendre le travail plus facile. S'inspirer d'autres tests peut aussi aider.
\nExécutez toujours la suite de tests complète avant de soumettre une contribution. Pour exécuter les tests:
\n$ npm run test\nAssurez-vous que linter ne renvoie aucun problème et que tous les tests passent. Ne soumettez aucun patch ne passant pas l'un des tests.
\nIf you are updating tests and want to run a single spec to check it:
\n$ npm run test -match=menu\nThe above would only run spec modules matching menu, which is useful for anyone who's working on tests that would otherwise be at the very end of the testing cycle.
Dès que vos commit sont prêts -- tests et lint inclus --, la procédure de soumission commence par un push de votre branche vers votre fork sur Github.
\n$ git push origin my-branch\nDepuis GitHub, en ouvrant une proposition de contribution dite --pull request--, vous aurez à remplir un caneva :
\n<!--\nThank you for your pull request. Please provide a description above and review\nthe requirements below.\n\nBug fixes and new features should include tests and possibly benchmarks.\n\nContributors guide: https://github.com/electron/electron/blob/main/CONTRIBUTING.md\n-->\nYou will probably get feedback or requests for changes to your pull request. Ceci est une grande partie du processus de soumission, donc ne soyez pas découragé ! Some contributors may sign off on the pull request right away. Others may have detailed comments or feedback. This is a necessary part of the process in order to evaluate whether the changes are correct and necessary.
\nTo make changes to an existing pull request, make the changes to your local branch, add a new commit with those changes, and push those to your fork. GitHub will automatically update the pull request.
\n$ git add my/changed/files\n$ git commit\n$ git push origin my-branch\nThere are a number of more advanced mechanisms for managing commits using git rebase that can be used, but are beyond the scope of this guide.
Feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer on something. If you encounter words or acronyms that seem unfamiliar, refer to this glossary.
\nToutes les demandes de pull nécessitent l'approbation d'un propriétaire de code Code Owner de la zone que vous avez modifiée. Whenever a maintainer reviews a pull request they may request changes. These may be small, such as fixing a typo, or may involve substantive changes. Such requests are intended to be helpful, but at times may come across as abrupt or unhelpful, especially if they do not include concrete suggestions on how to change them.
\nEssayez de ne pas vous décourager. If you feel that a review is unfair, say so or seek the input of another project contributor. Often such comments are the result of a reviewer having taken insufficient time to review and are not ill-intended. Such difficulties can often be resolved with a bit of patience. That said, reviewers should be expected to provide helpful feedback.
\nIn order to land, a pull request needs to be reviewed and approved by at least one Electron Code Owner and pass CI. After that, if there are no objections from other contributors, the pull request can be merged.
\nFélicitations et merci pour votre contribution !
\nEvery pull request is tested on the Continuous Integration (CI) system to confirm that it works on Electron's supported platforms.
\nIdeally, the pull request will pass (\"be green\") on all of CI's platforms. This means that all tests pass and there are no linting errors. However, it is not uncommon for the CI infrastructure itself to fail on specific platforms or for so-called \"flaky\" tests to fail (\"be red\"). Each CI failure must be manually inspected to determine the cause.
\nCI starts automatically when you open a pull request, but only core maintainers can restart a CI run. If you believe CI is giving a false negative, ask a maintainer to restart the tests.
", "title": "Pull Requests", "description": "" }, "/docs/tutorial/quick-start": { "locale": "fr-FR", "slug": "quick-start", "href": "/docs/tutorial/quick-start", "crowdinFileId": "256237", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/quick-start.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Ce tutoriel vous guidera dans le processus de création d'une application Hello World dans Electron, similaire à electron/electron-quick-start.
À la fin de ce tutoriel, votre application ouvrira une fenêtre de navigateur qui affichera une page web avec des informations sur quelles versions de Chromium, de Node.js et d'Electron sont en cours d'exécution.
\nPour utiliser Electron, vous devez installer Node.js. Nous vous recommandons d'utiliser la dernière version LTS disponible.
\n\nPlease install Node.js using pre-built installers for your platform. You may encounter incompatibility issues with different development tools otherwise.
\n
Pour vérifier que Node.js a été installé correctement, tapez les commandes suivantes dans votre terminal client :
\nnode -v\nnpm -v\nLes commandes devraient imprimer respectivement les versions de Node.js et npm.
\nRemarque : Puisque Electron embarque Node.js dans son binaire, la version de Node.js exécutant votre code n'est pas lié à la version en cours d'exécution sur votre système.
\nLes applications Electron suivent la même structure générale que les autres projets Node.js. Commencez par créer un dossier et initialiser un package npm.
\nmkdir my-electron-app && cd my-electron-app\nnpm init\nLa commande interactive init vous demandera de définir quelques champs dans votre configuration. Il y a quelques règles à suivre pour les besoins de ce didacticiel :
entry point devrait être main.js.author et description peuvent être n’importe quelle valeur, mais sont nécessaires pour le packaging de l'application.Votre fichier package.json devrait ressembler à ceci :
{\n \"name\": \"my-electron-app\",\n \"version\": \"1.0.0\",\n \"description\": \"Hello World!\",\n \"main\": \"main.js\",\n \"author\": \"Jane Doe\",\n \"license\": \"MIT\"\n}\nEnsuite, installez le package electron dans les devDependencies de votre application.
$ npm install --save-dev electron\n\n\nRemarque : Si vous rencontrez des problèmes avec l'installation d'Electron, veuillez consulter le guide Installation avancée.
\n
Enfin, vous voulez pouvoir exécuter Electron. Dans le champ scripts de votre fichier de configuration package.json , ajoutez une commande start comme suit :
{\n \"scripts\": {\n \"start\": \"electron .\"\n }\n}\nCette commande start vous permettra d'ouvrir votre application en mode développement.
npm start\n\n\nRemarque : Ce script indique à Electron de s’exécuter à la racine du dossier de votre projet. À ce stade, votre application va immédiatement lancer une erreur vous disant qu'elle ne trouve pas d'application à exécuter.
\n
Le point d’entrée de toute application Electron est son script main. Ce script contrôle le processus principal, qui s'exécute dans un environnement Node.js et est responsable de contrôler le cycle de vie de votre application, d'afficher les interfaces natives, d'effectuer des opérations privilégiées et de gérer les processus de rendu (plus d'information à ce sujet par la suite).
Pendant l’exécution, Electron va chercher ce script dans le champ main du fichier de configuration package.json de l’application que vous devriez avoir configuré lors de l’étape Initialisation du projet.
Pour initialiser le script main, créez un fichier vide nommé main.js dans le dossier racine de votre projet.
\n\nRemarque : Si vous exécutez à nouveau le script
\nstartà ce stade, votre application ne lancera plus d'erreur ! Cependant, il ne fera rien pour le moment parce que nous n'avons pas ajouté de code dansmain.js.
Avant de pouvoir créer une fenêtre pour notre application, nous devons créer le contenu qui sera chargé dedans. Dans Electron, chaque fenêtre affiche le contenu Web qui peut être chargé à partir d'un fichier HTML local ou d'une URL distante.
\nPour ce tutoriel, vous allez faire le premier. Créez un fichier index.html à la racine de votre projet :
\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n Nous utilisons Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n et Electron <span id=\"electron-version\"></span>.\n </body>\n</html>\n\n\nRemarque : en regardant ce document HTML, vous pouvez observer que les numéros de version sont manquants du texte du body. Nous les insérerons manuellement plus tard à l’aide de JavaScript.
\n
Maintenant que vous avez une page web, chargez-la dans une fenêtre d'application. Pour ce faire, vous aurez besoin de deux modules Electron :
\napp, qui contrôle le cycle de vie des événements de votre application.BrowserWindow, qui crée et gère les fenêtres d’application.Étant donné que le processus principal exécute Node.js, vous pouvez importer ces derniers en tant que modules CommonJS en haut de votre fichier :
\nconst { app, BrowserWindow } = require('electron')\nEnsuite, ajoutez une fonction createWindow() qui charge index.html dans une nouvelle instance BrowserWindow.
function createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\nEnsuite, appelez cette fonction createWindow() pour ouvrir votre fenêtre.
Dans Electron, les fenêtres du navigateur ne peuvent être créées qu'après que l’événement ready du module app est déclenché. Vous pouvez attendre cet événement en utilisant l'API app.whenReady(). Appelez createWindow() après que whenReady() a résolu sa Promise.
app.whenReady().then(() => {\n createWindow()\n})\n\n\nRemarque : À ce stade, votre application Electron devrait ouvrir avec succès une fenêtre qui affiche votre page web !
\n
Bien que vous puissiez maintenant ouvrir une fenêtre de navigateur, vous aurez besoin de code boilerplate supplémentaire pour le rendre plus natif de chaque plate-forme. Les fenêtres d’application se comportent différemment sur chaque système d’exploitation et Electron met la responsabilité sur les développeurs d’implémenter ces conventions dans leur application.
\nEn général, vous pouvez utiliser l'attribut platform de la variable globale process pour exécuter du code spécifiquement pour certains systèmes d’exploitation.
Sur Windows et Linux, quitter toutes les fenêtres quitte généralement une application entièrement.
\nTo implement this, listen for the app module's 'window-all-closed' event, and call app.quit() if the user is not on macOS (darwin).
app.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nAlors que les applications Linux et Windows se ferment lorsqu'elles n'ont pas de fenêtres ouvertes, les applications macOS continuent généralement de s'exécuter même sans aucune fenêtre ouverte et activer l'application lorsqu'aucune fenêtre n'est disponible devrait en ouvrir une nouvelle.
\nTo implement this feature, listen for the app module's activate event, and call your existing createWindow() method if no browser windows are open.
Étant donné que les fenêtres ne peuvent pas être créées avant l'événement ready , vous ne devriez écouter l'événement activate qu'après l'initialisation de votre application. Pour ce faire, attachez votre event listener à partir de votre callback whenReady() existant.
app.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n\nRemarque: À ce stade, vos contrôles de fenêtre doivent être entièrement fonctionnels!
\n
Maintenant, la dernière chose à faire est d'afficher les numéros de version pour Electron et ses dépendances sur votre page web.
\nL’accès à ces informations est trivial à faire dans le processus principal via l’objet global process de Node. Cependant, vous ne pouvez pas simplement modifier le DOM à partir du processus principal car il n'a pas accès au contexte du document du moteur de rendu. Ils sont dans des processus entièrement différents!
\n\nNote: If you need a more in-depth look at Electron processes, see the Process Model document.
\n
C'est là que l'attachement d'un script preload à votre moteur de rendu est pratique. Un script de préchargement s'exécute avant que le processus de rendu soit chargé, et a accès aux deux renderer globals (e. window et document) et environnement Node.js.
Créer un nouveau script nommé preload.js :
window.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\nLe code ci-dessus accède à l'objet process.versions de Node.js et exécute une fonction d'aide de replaceText de base pour insérer les numéros de version dans le document HTML.
Pour attacher ce script à votre processus de rendu, passez le chemin d’accès à votre script de préchargement à l’option webPreferences.preload dans votre constructeur BrowserWindow existant.
// inclus le module 'path' tout en haut du fichier\nconst path = require('path')\n\n// modifier votre fonction createWindow()\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n}\n// ...\nIl y a deux concepts Node.js qui sont utilisés ici :
\n__dirname string points to the path of the currently executing script (in this case, your project's root folder).path.join API joins multiple path segments together, creating a combined path string that works across all platforms.Nous utilisons un chemin relatif au fichier JavaScript en cours d'exécution afin que votre chemin relatif fonctionne en mode développement et en mode packaged.
\nÀ ce stade, vous pourriez vous demander comment ajouter plus de fonctionnalités à votre application.
\nPour toute interaction avec votre contenu web, vous souhaitez ajouter des scripts à votre processus de rendu. Parce que le moteur de rendu fonctionne dans un environnement web normal, vous pouvez ajouter une balise <script> juste avant votre balise de fermeture </body> du fichier index.html pour inclure n'importe quel script de votre choix :
<script src=\"./renderer.js\"></script>\nThe code contained in renderer.js can then use the same JavaScript APIs and tooling you use for typical front-end development, such as using webpack to bundle and minify your code or React to manage your user interfaces.
Après avoir suivi les étapes ci-dessus, vous devriez avoir une application Electron entièrement fonctionnelle qui ressemble à ceci :
\n
Le code complet est disponible ci-dessous :
\n// main.js\n\n// Modules pour controler la vie de l'application et créer une fenêtre de navigation native\nconst { app, BrowserWindow } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n // Créer la fenêtre de navigation.\n const mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n // et charger l'index.html de l'application.\n mainWindow.loadFile('index.html')\n\n // Ouvrir les outils de développement.\n // mainWindow.webContents.openDevTools()\n}\n\n// Cette méthode sera appelée quand Electron aura fini\n// de s'initialiser et sera prêt à créer des fenêtres de navigation.\n// Certaines APIs peuvent être utilisées uniquement quant cet événement est émit.\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n // Sur macOS il est d'usage de recréer une fenêtre dans l'application quand\n // l'icône du dock est cliquée et qu'il n'y a pas d'autre fenêtre ouverte.\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n// Quitter quand toutes les fenêtres sont fermées, sauf sur macOS. Sur macOS, il est courant\n// pour les applications et leur barre de menu de rester actives jusqu’à ce que l’utilisateur quitte\n// explicitement avec Cmd + Q.\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\n\n// Dans ce fichier, vous pouvez inclure le reste du code spécifique du\n// processus principal de votre application. Vous pouvez également le mettre dans des fichiers séparés et les inclure ici.\n// preload.js\n\n// Toutes les APIs Node.js sont disponibles dans le processus de préchargement.\n// Il a la même sandbox qu'une extension Chrome.\nwindow.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\n<!--index.html-->\n\n\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n Nous utilisons Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n et Electron <span id=\"electron-version\"></span>.\n\n <!-- Vous pouvez également requérir que d’autres fichiers s’exécutent dans ce processus -->\n <script src=\"./renderer.js\"></script>\n </body>\n</html>\nPour résumer toutes les étapes que nous avons effectuées :
\nNous avons amorcé une application Node.js et ajouté Electron en tant que dépendance.
\nNous avons créé un script main.js qui exécute notre processus principal, qui contrôle notre application et s'exécute dans un environnement Node.js. Dans ce script, nous avons utilisé les modules d'Electron app et BrowserWindow pour créer une fenêtre de navigateur qui affiche le contenu web dans un processus séparé (le moteur de rendu).
Afin d'accéder à certaines fonctionnalités de Node.js dans le moteur de rendu, nous avons attaché un script de préchargement à notre constructeur BrowserWindow.
Le moyen le plus rapide de distribuer votre application nouvellement créée est d'utiliser\nElectron Forge.
\nAjouter Electron Forge comme dépendance de développement de votre application et utiliser sa commande import pour commencer l'initialisation de Forge :
npm install --save-dev @electron-forge/cli\nnpx electron-forge import\n\n✔ Checking your system\n✔ Initializing Git Repository\n✔ Writing modified package.json file\n✔ Installing dependencies\n✔ Writing modified package.json file\n✔ Fixing .gitignore\n\nWe have ATTEMPTED to convert your app to be in a format that electron-forge understands.\n\nThanks for using \"electron-forge\"!!!\nCréez une distribution en utilisant la commande make de Forge :
npm run make\n\n> my-electron-app@1.0.0 make /my-electron-app\n> electron-forge make\n\n✔ Checking your system\n✔ Resolving Forge Config\nWe need to package your application before we can make it\n✔ Preparing to Package Application for arch: x64\n✔ Preparing native dependencies\n✔ Packaging Application\nMaking for the following targets: zip\n✔ Making for target: zip - On platform: darwin - For arch: x64\nElectron Forge crée le dossier out où se trouvera votre paquet:
// Exemple pour macOS\nout/\n├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip\n├── ...\n└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app\nVeuillez vous assurer d'utiliser la documentation qui correspond à votre version d'Electron. Le numéro de version doit être une partie de l'URL de la page. Si ce n'est pas le cas, vous utilisez probablement la documentation d'une branche de développement pouvant contenir des modifications de l'API qui ne sont pas compatibles avec votre version d'Electron. Pour consulter les anciennes versions de la documentation, vous pouvez Parcourir par tag sur GitHub en ouvrant la liste déroulante « Switch branches/tags » et sélectionnez le tag qui correspond à votre version.
\nCaertaines questions qui sont assez souvent posées. Vérifiez ceci avant de déclarer un problème:
\nCes tutoriels individuels développent les sujets abordés dans le guide ci-dessus.
\nCes guides sont destinés aux personnes travaillant sur le projet Electron lui-même. Pour des guides sur le développement d'applications Electron, voir /docs/README.md.
\nWindows et macOS permettent d’accéder facilement à la liste des documents récemment ouverts par l'application respectivement via JumpList ou dock menu.
\nJumpList :
\n
Menu application du dock :
\n
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\n\nconst fileName = 'recently-used.md'\nfs.writeFile(fileName, 'Lorem Ipsum', () => {\n app.addRecentDocument(path.join(__dirname, fileName))\n})\n\napp.whenReady().then(createWindow)\n\napp.on('window-all-closed', () => {\n app.clearRecentDocuments()\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nUtilisez l'API app.addRecentDocument pour ajouter un fichier aux documents récents .
\nAfter launching the Electron application, right click the application icon. Dans ce guide, l'élément est un fichier Markdown situé à la racine du projet. Vous devriez voir recently-used.md ajouté à la liste des fichiers récents :
Pour effacer la liste des documents récents, utilisez l'API app.clearRecentDocuments. Dans ce guide, la liste des documents est effacée lorsque toutes les fenêtres ont été fermées.
\nPour utiliser cette fonctionnalité sur Windows, votre application doit être enregistrée en tant que gestionnaire/responsable du type de fichier du document, sinon le fichier n’apparaîtra pas dans la JumpList même après l'avoir ajouté. Vous trouverez tout l'enregistrement de votre application dans Enregistrement de l'application.
\nLorsqu’un utilisateur clique sur un fichier à partir de la JumpList, cela démarre une nouvelle instance de votre application avec le chemin d’accès du fichier ajouté comme un argument de ligne de commande.
\nVous pouvez ajouter des éléments de menu pour accéder et supprimer les documents récents en ajoutant le code suivant à votre template de menu :
\n{\n \"submenu\":[\n {\n \"label\":\"Ouvrir récent\",\n \"role\":\"recentdocuments\",\n \"submenu\":[\n {\n \"label\":\"Effacer récent\",\n \"role\":\"clearrecentdocuments\"\n }\n ]\n }\n ]\n}\nAssurez-vous que le menu de l'application soit ajouté après l'événement 'ready' et pas avant, ou l'élément de menu sera désactivé :
const { app, Menu } = require('electron')\n\nconst template = [\n // Modèle de Menu \n]\nconst menu = Menu.buildFromTemplate(template)\n\napp.whenReady().then(() => {\n Menu.setApplicationMenu(menu)\n})\n
Lorsqu’un fichier est demandé dans le menu documents récents, l’événement open-file du module app sera émit.
x Number - The x coordinate of the origin of the rectangle (must be an integer).y Number - The y coordinate of the origin of the rectangle (must be an integer).width Number - The width of the rectangle (must be an integer).height Number - The height of the rectangle (must be an integer).url String - HTTP Referrer URL.policy String - Can be default, unsafe-url, no-referrer-when-downgrade, no-referrer, origin, strict-origin-when-cross-origin, same-origin or strict-origin. See the Referrer-Policy spec for more details on the meaning of these values.Read-Eval-Print-Loop (REPL) is a simple, interactive computer programming environment that takes single user inputs (i.e. single expressions), evaluates them, and returns the result to the user.
\nElectron exposes the Node.js repl module through the --interactive CLI flag. Assuming you have electron installed as a local project dependency, you should be able to access the REPL with the following command:
./node_modules/.bin/electron --interactive\nNote: electron --interactive is not available on Windows (see electron/electron#5776 for more details).
You can use the DevTools Console tab to get a REPL for any renderer process. Pour en savoir plus, lisez la documentation Chrome.
", "title": "REPL", "description": "" }, "/docs/tutorial/represented-file": { "locale": "fr-FR", "slug": "represented-file", "href": "/docs/tutorial/represented-file", "crowdinFileId": "256243", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/represented-file.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "On macOS, you can set a represented file for any window in your application. The represented file's icon will be shown in the title bar, and when users Command-Click or Control-Click, a popup with a path to the file will be shown.
\n\nNOTE : La capture d'écran ci-dessus est un exemple où cette fonctionnalité est utilisée pour indiquer le fichier actuellement ouvert dans l'éditeur de texte Atom.
\n
You can also set the edited state for a window so that the file icon can indicate whether the document in this window has been modified.
\nTo set the represented file of window, you can use the BrowserWindow.setRepresentedFilename and BrowserWindow.setDocumentEdited APIs.
\nconst { app, BrowserWindow } = require('electron')\nconst os = require('os');\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n}\n\napp.whenReady().then(() => {\n const win = new BrowserWindow()\n\n win.setRepresentedFilename(os.homedir())\n win.setDocumentEdited(true)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nAprès avoir lancé l'application Electron, cliquez sur le titre en pressant sur la touche Command ou Control. Vous devriez voir une popup avec le fichier représenté en haut. En ce qui concerne ce guide, il s'agit du répertoire home de l'utilisateur actuel:
\n\nAllows access to simple encryption and decryption of strings for storage on the local machine.
\n
Processus : Main
\nThis module protects data stored on disk from being accessed by other applications or users with full disk access.
\nNote that on Mac, access to the system Keychain is required and these calls can block the current thread to collect user input. The same is true for Linux, if a password management tool is available.
\nLe module safeStorage possède les méthodes suivantes :
safeStorage.isEncryptionAvailable()Returns Boolean - Whether encryption is available.
On Linux, returns true if the secret key is available. On MacOS, returns true if Keychain is available. On Windows, returns true with no other preconditions.
\nsafeStorage.encryptString(plainText)plainText StringReturns Buffer - An array of bytes representing the encrypted string.
This function will throw an error if encryption fails.
\nsafeStorage.decryptString(encrypted)encrypted BufferReturns String - the decrypted string. Decrypts the encrypted buffer obtained with safeStorage.encryptString back into a string.
This function will throw an error if decryption fails.
", "title": "safeStorage", "description": "Allows access to simple encryption and decryption of strings for storage on the local machine." }, "/docs/tutorial/sandbox": { "locale": "fr-FR", "slug": "sandbox", "href": "/docs/tutorial/sandbox", "crowdinFileId": "256245", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/sandbox.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "L'une des principales fonctionnalités de sécurité de Chromium est que les processus peuvent être exécutés dans un bac à sable. The sandbox limits the harm that malicious code can cause by limiting access to most system resources — sandboxed processes can only freely use CPU cycles and memory. Afin d’effectuer des opérations nécessitant un privilège supplémentaire, les processus mis en bac à sable utilisent des canaux de communication dédiés pour déléguer des tâches à des processus plus privilégiés.
\nDans Chromium, le bac à sable est appliqué à la plupart des processus autres que le processus principal. Cela inclut les processus de rendu, ainsi que les processus utilitaires tels que le service audio, le service GPU et le service réseau.
\nReportez-vous au document Conception du bac à sable pour plus d'informations.
\nElectron est livré avec un environnement de bac à sable mixte, ce qui signifie que les processus s'y exécutant peuvent fonctionner aux côtés de processus privilégiés. Par défaut, les processus de rendu ne sont pas en bac à sable mais les processus utilitaires le sont. Notez que dans Chromium le processus principal (navigateur) est privilégié et ne peut pas être mis en bac à sable.
\nHistoriquement, cette approche du bac à sable mixte a été établie car la disponibilité de Node.js dans le moteur de rendu est un outil extrêmement puissant pour les développeurs d'applications. Malheureusement cette fonctionnalité est également une vulnérabilité de sécurité tout aussi massive.
\nThéoriquement les rendus hors bac à sable ne sont pas un problème pour les applications de bureau qui affichent uniquement du code de confiance mais ils rendent Electron moins sûr que Chromium pour afficher du contenu Web non fiable. Cependant même du code prétendument fiable peut être dangereux - il existe d’innombrables vecteurs d’attaque utilisables par des acteurs malveillants, du script cross-site à l’injection de contenu aux attaques \"man-in-the-middle\" sur des sites Web distants chargés pour n’en nommer que quelques-uns. Pour cette raison, nous recommandons d'être très prudent et d’activer le bac à sable pour les rendus dans la grande majorité des cas.
\n\nNotez qu'il y a une discussion active dans le gestionnaire de tickets au sujet de l'activation par défaut de la mise en bac à sable des rendus . Voir #28466) pour plus de détails.
\nDans Electron les processus mis en bac à sable se comportent principalement de la même manière qu'avec Chromium mais il y a quelques concepts supplémentaires à considérer puisque Electron s’interface avec Node.js.
\nLorsque les processus de rendu dans Electron sont en bac à sable, ils se comportent de la même manière qu'un moteur de rendu Chrome régulier le ferait. Un moteur de rendu en bac à sable n'aura pas d'environnement Node.js initialisé.
\n\nPar conséquent, lorsque le bac à sable est activé, les processus de rendu ne peuvent effectuer des tâches privilégiées (telles que l’interaction avec le système de fichiers, apporter des modifications au système ou engendrer des sous-processus) qu'en déléguant ces tâches au processus principal par la communication inter-processus (IPC).
\nAfin de permettre aux processus de rendu de communiquer avec le processus principal, les scripts de préchargement attachés aux rendus en bac à sable auront toujours un sous-ensemble polyfill de l'API Node.js disponible. Une fonction require similaire au module require de Node module est exposée mais ne peut importer qu'un sous-ensemble des modules intégrés d'Electron et de Node :
electron (uniquement les modules de processus de rendu)événementstimersurlEn outre, le script de préchargement simule également certaines primitives Node.js en tant que globales :
\n\nÉtant donné que la fonction require est un polyfill avec des fonctionnalités limitées, vous ne serez pas en mesure d’utiliser modules CommonJS pour séparer votre script de préchargement en plusieurs fichiers . Si vous avez besoin de diviser votre code de préchargement, utilisez un groupeur de module tel que webpack ou Parcel.
Note that because the environment presented to the preload script is substantially more privileged than that of a sandboxed renderer, it is still possible to leak privileged APIs to untrusted code running in the renderer process unless contextIsolation is enabled.
Dans Electron, la mise en bac à sable d'un rendu peut être activé par processus avec la préférence sandbox: true dans le constructeur de la BrowserWindow.
// main.js\napp.whenReady().then(() => {\n const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n })\n win.loadURL('https://google.com')\n})\nSi vous souhaitez activer de force le bac à sable pour tous les rendus, vous pouvez également utiliser l' app.enableSandbox API. Notez que cette API doit être appelée avant l'événement ready de l’application.
// main.js\napp.enableSandbox()\napp.whenReady().then(() => {\n // inutile de passer `sandbox: true` puisque `app.enableSandbox()` a été appelé.\n const win = new BrowserWindow()\n win.loadURL('https://google.com')\n})\nVous pouvez également désactiver entièrement le bac à sable de Chromium avec le drapeau CLI --no-sandbox , qui le désactivera pour tous les processus (y compris les processus utilitaires). Nous vous recommandons fortement d'utiliser ce drapeau uniquement à des fins de test, et jamais en production.
Notez que l'option sandbox : true désactivera toujours l'environnement Node.js du moteur de rendu .
Le rendu de contenu non fiable dans Electron est encore un territoire quelque peu inconnu, bien que certaines applications trouvent le succès (par exemple. Beaker Browser). Notre objectif est de nous rapprocher le plus possible de Chrome en termes de sécurité des contenus en bac à sable, mais en fin de compte, nous serons toujours à la traîne en raison de quelques problèmes fondamentaux :
\nAlors que nous faisons de notre mieux pour rétroporter les correctifs de sécurité Chromium vers d'anciennes versions d'Electron, nous ne garantissons pas que chaque correctif sera rétroporté. Votre meilleure chance de rester en sécurité est d'être sur la dernière version stable d'Electron.
", "title": "Mise en bac à sable de processus", "description": "" }, "/docs/api/screen": { "locale": "fr-FR", "slug": "screen", "href": "/docs/api/screen", "crowdinFileId": "256361", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/screen.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRécupère les informations sur la taille, l'écran, la position du curseur, etc.
\n
Processus : Main
\nCe module ne peut pas être utilisé tant que l'événement prêt du module app n'est pas émis.
screen est un EventEmitter.
Remarque : Dans le renderer / DevTools, window.screen est une propriété réservée au DOM, alors écrire let { screen } = require('electron') ne fonctionnera pas.
Un exemple de création d'une fenêtre qui prendra tout l'écran :
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\napp.whenReady().then(() => {\n const { width, height } = screen.getPrimaryDisplay().workAreaSize\n win = new BrowserWindow({ width, height })\n win.loadURL('https://github.com')\n})\nUn autre exemple de création d'une fenêtre dans l'écran externe :
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n const displays = screen.getAllDisplays()\n const externalDisplay = displays.find((display) => {\n return display.bounds.x !== 0 || display.bounds.y !== 0\n })\n\n if (externalDisplay) {\n win = new BrowserWindow({\n x: externalDisplay.bounds.x + 50,\n y: externalDisplay.bounds.y + 50\n })\n win.loadURL('https://github.com')\n }\n})\nLe module screen émet les événements suivants :
Retourne :
\nevent EventnewDisplay DisplayÉmis lorsque newDisplay a été ajouté.
Retourne :
\nevent EventoldDisplay DisplayÉmis lorsque oldDisplay a été retiré.
Retourne :
\nevent Eventdisplay DisplaychangedMetrics String[]Émis lorsqu’un ou plusieurs métrics changent dans un display. changedMetrics est un tableau de chaîne de caractères décrivant les modifications. Les modifications possibles sont bounds, workArea, scaleFactor et rotation.
Le module screen dispose des méthodes suivantes :
screen.getCursorScreenPoint()Retourne Point
La position absolue du pointeur de la souris.
\nNote: The return value is a DIP point, not a screen physical point.
\nscreen.getPrimaryDisplay()Retourne Display - L'écran principal.
screen.getAllDisplays()Retourne Display[] - Un tableau d'écrans qui sont actuellement disponibles.
screen.getDisplayNearestPoint(point)point PointRetourne Display - L'écran le plus proche du point spécifié.
screen.getDisplayMatching(rect)rect RectangleRetourne Display - L'écran qui croise le plus les limites d'intersection données.
screen.screenToDipPoint(point) Windowspoint PointRetourne Point
Converts a screen physical point to a screen DIP point. The DPI scale is performed relative to the display containing the physical point.
\nscreen.dipToScreenPoint(point) Windowspoint PointRetourne Point
Converts a screen DIP point to a screen physical point. The DPI scale is performed relative to the display containing the DIP point.
\nscreen.screenToDipRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleRetourne Rectangle
Converts a screen physical rect to a screen DIP rect. The DPI scale is performed relative to the display nearest to window. If window is null, scaling will be performed to the display nearest to rect.
screen.dipToScreenRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleRetourne Rectangle
Converts a screen DIP rect to a screen physical rect. The DPI scale is performed relative to the display nearest to window. If window is null, scaling will be performed to the display nearest to rect.
label String (optional) - The text to appear in this item.icon NativeImage (optional) - The image to appear in this item.En tant que développeurs web, nous apprécions généralement le réseau de sécurité du navigateur - les risques associés au code que nous écrivons sont relativement faibles. Nos sites Web bénéficient de pouvoirs limités dans un bac à sable, et nous sommes convaincus que nos utilisateurs bénéficient d'un navigateur construit par une grande équipe d'ingénieurs capables de répondre rapidement aux menaces de sécurité récemment découvertes.
\nLorsque vous travaillez avec Electron, il est important de comprendre que l’Electron n’est pas un navigateur web. Il vous permet de developper des applications de bureau riche en fonctionnalités avec des technologies web familières, mais votre code exerce un pouvoir beaucoup plus grand. JavaScript peut accéder au système de fichiers, au shell et bien plus. Cela vous permet de développer des applications natives de haute qualité, mais les risques de sécurité inhérents évoluent avec les pouvoirs supplémentaires accordés à votre code.
\nDans cet esprit, sachez qu’afficher un contenu arbitraire de sources peu fiables est un grave risque pour la sécurité qu'Electron n’est pas destiné à gérer. En fait, les applications les plus populaires Electron (Atom, Slack, Visual Studio Code, etc.) affichent principalement du contenu local (ou un contenu distant fiable et sécurisé sans intégration de Node) – si votre application exécute le code provenant d’une source en ligne, il est de votre responsabilité de vous assurer que le code n’est pas malveillant.
\nPour plus d’informations sur la façon de communiquer correctement une vulnérabilité d'Electron, voir SECURITY.md
\nElectron keeps up to date with alternating Chromium releases. For more information, see the Electron Release Cadence blog post.
\nIl est important de se rappeler que la sécurité de votre application Electron dépend de la sécurité globalement de la fondation du framework (Chromium, Node.js), Electron lui-même, toutes les dépendances NPM et votre code. Ainsi, il est de votre responsabilité de suivre quelques pratiques essentielles de test :
\nGardez votre application à jour avec la dernière version de framework Electron. Lorsque vous libérez votre produit, vous expédiez également un paquet composé d'Electron, bibliothèque partagée Chromium et Node.js. Les vulnérabilités affectant ces composants peuvent affecter la sécurité de votre application. En mettant à jour Electron vers la dernière version vous vous assurez que les vulnérabilités critiques (telles que nodeIntegration bypasses) sont déjà corrigées et ne peuvent pas être exploitées dans votre application. Pour plus d'informations, voir \"Utiliser une version actuelle d'Electron\".
\nÉvaluez vos dépendances. Alors que NPM fournit un demi-million de paquets réutilisables, il est de votre responsabilité de choisir des bibliothèques de tiers de confiance. Si vous utilisez des bibliothèques obsolètes affectées par des vulnérabilités connues ou si vous êtes dépendants d'un code mal géré, la sécurité de votre application pourrait être compromise.
\nAdoptez des pratiques de codage sécurisées. La première ligne de défense pour votre application est votre propre code. Des vulnérabilités web courantes, telles que le cross-site scripting (XSS), ont un impact de sécurité plus élevé sur les applications Electron, c'est pourquoi il est fortement recommandé d'adopter des meilleures pratiques de développement de logiciel sécurisé et d'effectuer des tests de sécurité.
\nUn problème de sécurité existe chaque fois que vous recevez du code d'une source non fiable (par exemple, un serveur distant) et que vous l'exécutez localement. À titre d'exemple, considérez qu'un site Web distant est affiché à l'intérieur d'un BrowserWindow par défaut. Si un attaquant parvient d'une manière ou d'une autre à modifier ledit contenu (soit en s'attaquant directement à la source, ou en se plaçant entre votre application et la destination voulue), il sera en mesure d'exécuter le code natif sur la machine de l'utilisateur.
\n\n⚠️ en aucune circonstance vous devriez charger et exécuter du code distant avec l'intégration de Node.js activé. Utilisez plutôt les fichiers locaux (empaquetés avec votre application) pour exécuter le code de Node. Pour afficher du contenu à distance, utilisez le tag
\n<webview>ouBrowserView, assurez-vous de désactivernodeIntegrationet d'activercontextIsolation.
A partir d'Electron 2.0, les développeurs recevront des avertissements et recommandations directement dans la console de développement. Ils n'apparaissent que lorsque le nom du binaire est Electron, indiquant qu'un développeur regarde actuellement la console.
\nVous pouvez forcer l'activation ou la désactivation ces avertissements en définissant ELECTRON_ENABLE_SECURITY_WARNINGS ou ELECTRON_DISABLE_SECURITY_WARNINGS sur process.env ou sur l’objet window.
Vous devriez au moins suivre ces étapes pour améliorer la sécurité de votre application :
\nses.setPermissionRequestHandler() dans toutes les sessions qui se chargent de contenu distantwebSecurityContent-Security-Policy et utilisez des règles restrictives (c.-à-d. script-src 'self')allowRunningInsecureContent à trueenableBlinkFeatures<webview> : N'utilisez pas allowpopups<webview>: Vérifier les options et les paramètresopenExternal avec un contenu non fiablePour automatiser la détection de mauvaises configurations et de patrons non sécurisés, il est possible d'utiliser electronegativity. Pour plus de détails sur les faiblesses potentielles et les bogues d'implémentation lorsque développant des applications utilisant Electron, veuillez vous référer à ce guide pour développeurs et auditeurs
\nToutes les ressources non incluses avec votre application doivent être téléchargées à l’aide d’un protocole sécurisé HTTPS. En d’autres termes, n’utilisez pas de protocoles non sécurisés tels que HTTP. De même, nous vous recommandons d’utiliser WSS plutôt WS, FTPS par FTP et ainsi de suite.
HTTPS a trois principaux avantages :
1) Il authentifie le serveur distant, ce qui certifie que votre application se connecte au bon hôte plutôt qu'a un imitateur. 2) Il assure l'intégrité des données, certifiant que les données n'ont pas été modifiées durant le transit entre l'application et l'hôte. 3) Il encrypte le trafic entre votre l'utilisateur et l'hôte de destination, ce qui complique la tâche de quiconque voudrait épier les informations échangées entre l'hôte et votre application.
\n// Incorrect\nbrowserWindow.loadURL('http://example.com')\n\n// Correct\nbrowserWindow.loadURL('https://example.com')\n<!-- Incorrect -->\n<script crossorigin src=\"http://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"http://example.com/style.css\">\n\n<!-- Correct -->\n<script crossorigin src=\"https://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"https://example.com/style.css\">\nCette recommandation est le comportement par défaut d'Electron depuis la version 5.0.0.
\nIl est primordial que vous n'activiez pas l'intégration de Node.js dans aucun moteur de rendu (BrowserWindow, BrowserView, ou <webview><3></2>) qui charge le contenu distant. Le but est de limiter les permissions accordées aux contenus distants, ce qui complique drastiquement la tâche pour un attaquant qui souhaiterait nuire à vos utilisateurs (si jamais cet attaquant réussissait à exécuter du javascript sur votre site).
Une fois cela fait, vous pouvez accorder des permissions supplémentaires à des hôtes spécifiques. Par exemple, si vous ouvrez un BrowserWindow pointé sur https://example. om/, vous pouvez donner à ce site exactement les capacités dont il a besoin, mais pas plus.
Une attaque cross-site-scripting (XSS) est plus dangereuse si un attaquant peut sortir du processus de rendu et exécuter du code sur l'ordinateur de l'utilisateur. Les attaques de type cross-site-scripting sont assez courantes - et tant qu'un problème, leur pouvoir se limite généralement à gâcher avec le site Web sur lequel ils sont exécutés. La désactivation de l'intégration de Node.js aide à empêcher un XSS d'être escaladé pour devenir une attaque appelée \"Exécution de Code distant\" (RCE).
\n// Mauvais\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n nodeIntegration: true,\n nodeIntegrationInWorker: true\n }\n})\n\nmainWindow.loadURL('https://example.com')\n// Bon\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n preload: path.join(app.getAppPath(), 'preload.js')\n }\n})\n\nmainWindow.loadURL('https://example.com')\n<!-- Incorrect -->\n<webview nodeIntegration src=\"page.html\"></webview>\n\n<!-- Correct -->\n<webview src=\"page.html\"></webview>\nLors de la désactivation de l'intégration de Node.js, vous pouvez toujours exposer des API à votre site web qui consomment des modules ou des fonctionnalités de Node.js. Les scripts de préchargement continuent d'avoir accès à require et aux autres fonctionnalités de Node.js, permettant aux développeurs d'exposer une API personnalisée au contenu chargé à distance.
Dans l'exemple suivant du script de préchargement, le site web chargé plus tard aura accès à une méthode window.readConfig(), mais aucune fonctionnalité Node.js.
const { readFileSync } = require('fs')\n\nwindow.readConfig = function () {\n const data = readFileSync('./config.json')\n return data\n}\nL'isolement du contexte est une fonctionnalité d'Electron qui permet aux développeurs d'exécuter du code dans les scripts de préchargement et dans les API Electron dans un contexte JavaScript dédié. Dans la pratique cela signifie que les objets globaux comme Array.prototype.push ou JSON.parse ne peuvent pas être modifiés par les scripts exécutés dans le processus de rendu.
L'électron utilise la même technologie que le chrome Content Scripts pour permettre ce comportement.
\nMême lorsque nodeIntegration: false est utilisé, pour vraiment appliquer une isolation forte et empêcher l'utilisation de Node primitives contextIsolation doivent également être utilisées.
For more information on what contextIsolation is and how to enable it please see our dedicated Context Isolation document.
Sandboxing est une fonctionnalité de Chromium qui utilise le système d’exploitation pour limiter considérablement ce à quoi les processus de rendu ont accès. Vous devez activer le bac à sable dans tous les moteurs de rendu. Charger, lire ou traiter tout contenu non fiable dans un processus non protégé par le bac à sable, y compris le processus principal, n'est pas conseillé.
\nLors de la création d'une fenêtre, passez l'option sandbox : true dans webPreferences:
const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n})\nVous avez peut-être vu des demandes d'autorisation lors de l'utilisation de Chrome : elles apparaissent chaque fois que le site Web tente d'utiliser une fonctionnalité que l'utilisateur doit approuver manuellement ( comme les notifications).
\nL'API se base sur l'API de permissions Chromium et implémente le même type de permissions.
\nPar défaut, Electron approuvera automatiquement toutes les demandes de permission, sauf si le développeur a manuellement configuré un gestionnaire personnalisé. Bien que la valeur par défaut soit solide, les développeurs soucieux de la sécurité pourraient vouloir assumer le contraire.
\nconst { session } = require('electron')\n\nsession\n .fromPartition('some-partition')\n .setPermissionRequestHandler((webContents, permission, callback) => {\n const url = webContents.getURL()\n\n if (permission === 'notifications') {\n // Approves the permissions request\n callback(true)\n }\n\n // Verify URL\n if (!url.startsWith('https://example.com/')) {\n // Denies the permissions request\n return callback(false)\n }\n })\nCette recommandation est appliquée par défaut sur Electron
\nVous avez peut-être déjà deviné que la désactivation de la propriété webSecurity sur un processus de rendu (BrowserWindow, BrowserView, ou <webview>) désactive les fonctionnalités de sécurité cruciales. .
Ne pas désactiver webSecurity dans les applications de production.
Désactiver webSecurity désactivera la politique de même origine et définira la propriété allowRunningInsecureContent à true. En d'autres termes, il permet l'exécution de code non sécurisé à partir de différents domaines.
// Incorrect\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n webSecurity: false\n }\n})\n// Correct\nconst mainWindow = new BrowserWindow()\n<!-- Incorrect -->\n<webview disablewebsecurity src=\"page.html\"></webview>\n\n<!-- Correct -->\n<webview src=\"page.html\"></webview>\nUne politique de sécurité de contenu (CSP) est une couche supplémentaire de protection contre des attaques cross-site-scripting et des attaques d'injection de données. Nous recommandons qu'ils soient activés par n'importe quel site Web que vous chargez dans Electron.
\nCSP permet au serveur servant le contenu de restreindre et de contrôler les ressources Electron peut charger pour cette page web. https://example.com devrait être autorisé à charger des scripts depuis les origines que vous avez définies alors que les scripts de https://evil.attacker.com ne devraient pas être autorisés à s'exécuter. Définir un CSP est un moyen facile d'améliorer la sécurité de votre application.
Le CSP suivant permettra à Electron d'exécuter des scripts depuis le site web actuel et depuis apis.example.com.
// Incorrect\nContent-Security-Policy: '*'\n\n// Correct\nContent-Security-Policy: script-src 'self' https://apis.example.com\nElectron respecte le Content-Security-Policy en-tête HTTP qui peut être défini en utilisant le gestionnaire webRequest.onHeadersReceived d'Electron :
const { session } = require('electron')\n\nsession.defaultSession.webRequest.onHeadersReceived((details, callback) => {\n callback({\n responseHeaders: {\n ...details.responseHeaders,\n 'Content-Security-Policy': ['default-src \\'none\\'']\n }\n })\n})\nLe mécanisme de livraison préféré de CSP est un en-tête HTTP, cependant il n'est pas possible d'utiliser cette méthode lors du chargement d'une ressource en utilisant le protocole file://. Il peut être utile dans certains cas, par exemple en utilisant le protocole file:// , pour définir une politique sur une page directement dans le balisage en utilisant une balise < meta> :
<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'\">\nallowRunningInsecureContent à trueCette recommandation est appliquée par défaut sur Electron
\nPar défaut, Electron n'autorisera pas les sites Web chargés sur HTTPS à charger et exécuter des scripts, CSS ou plugins à partir de sources non sécurisées (HTTP). Définir la propriété allowRunningInsecureContent à true désactive cette protection.
Chargement du HTML initial d'un site sur HTTPS et tentative de chargement de ressources ultérieures via HTTP est aussi connu sous le nom de \"contenu mixte\".
Le chargement du contenu sur HTTPS assure l'authenticité et l'intégrité des ressources chargées tout en chiffrant le trafic lui-même. Consultez la section sur l' affichage du contenu sécurisé uniquement pour plus de détails.
// Incorrect\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n allowRunningInsecureContent: true\n }\n})\n// Correct\nconst mainWindow = new BrowserWindow({})\nCette recommandation est appliquée par défaut sur Electron
\nLes utilisateurs avancés d'Electron peuvent activer les fonctionnalités expérimentales de Chromium en utilisant la propriété fonctionnalités expérimentales.
Experimental features are, as the name suggests, experimental and have not been enabled for all Chromium users. Furthermore, their impact on Electron as a whole has likely not been tested.
\nIl est parfois légitime de les implémenter, mais à moins que vous sachiez vraiment ce que vous faites, vous ne devriez pas autoriser ces fonctionnalités.
\n// Incorrect\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n experimentalFeatures: true\n }\n})\n// Correct\nconst mainWindow = new BrowserWindow({})\nenableBlinkFeaturesCette recommandation est appliquée par défaut sur Electron
\nBlink est le nom du moteur de rendu derrière Chromium. Comme pour experimentalFeatures, la propriété enableBlinkFeatures permet aux développeurs d'activer les fonctionnalités qui ont été désactivées par défaut.
De manière générale, il y a probablement de bonnes raisons si une fonctionnalité n'était pas activée par défaut. Il existe des cas d'utilisation légitime pour l'activation de fonctionnalités spécifiques. En tant que développeur , vous devriez savoir exactement pourquoi vous avez besoin d'activer une fonctionnalité, quelles sont les ramifications et comment elles ont un impact sur la sécurité de votre application. En aucune circonstance ne devrait vous permettre d'activer des fonctionnalités de manière spéculative.
\n// Mauvais\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n enableBlinkFeatures: 'ExecCommandInJavaScript'\n }\n})\n// Correct\nconst mainWindow = new BrowserWindow()\nallowpopupsCette recommandation est appliquée par défaut sur Electron
\nSi vous utilisez <webview>, vous aurez peut-être besoin des pages et des scripts chargés dans votre balise <webview> pour ouvrir de nouvelles fenêtres. L'attribut allowpopups leur permet de créer un nouveau BrowserWindows en utilisant la méthode window.open(). Les balises <webview> ne sont pas autorisées à créer de nouvelles fenêtres .
Si vous n'avez pas besoin de popups, il vaut mieux ne pas autoriser la création de nouveaux BrowserWindows par défaut. Cela suit le principe d'accès minimum requis : ne laissez pas un site web créer de nouvelles fenêtres popups à moins que vous sachiez qu'il a besoin de cette fonctionnalité.
<!-- Incorrect -->\n<webview allowpopups src=\"page.html\"></webview>\n\n<!-- Correct -->\n<webview src=\"page.html\"></webview>\nUn WebView créé dans un processus de rendu qui n'a pas d'intégration Node.js activé ne sera pas en mesure d'activer l'intégration elle-même. Cependant, un WebView créera toujours un processus de rendu indépendant avec ses propres webPreferences.
C'est une bonne idée de contrôler la création de nouvelles balises <webview><1></0> depuis le processus principal et de vérifier que leurs préférences web ne désactivent pas les fonctions de sécurité .
Depuis que <webview> vivent dans le DOM, ils peuvent être créés par un script exécuté sur votre site web même si l'intégration de Node.js est désactivée.
Electron permet aux développeurs de désactiver diverses fonctionnalités de sécurité qui contrôlent un processus de rendu. Dans la plupart des cas, les développeurs n'ont pas besoin de désactiver ces fonctionnalités - et vous ne devriez donc pas autoriser différentes configurations pour les balises <webview><1></0> nouvellement créées.
Avant qu'un tag <webview></0> ne soit attaché, Electron lancera l'événement <2>will-attach-webview</2> sur l'hébergement <2>webContents</2>. Utilisez l'événement pour empêcher la création de <code>webViews avec des options potentiellement non sécurisées.
app.on('web-contents-created', (event, contents) => {\n contents.on('will-attach-webview', (event, webPreferences, params) => {\n // Strip away preload scripts if unused or verify their location is legitimate\n delete webPreferences.preload\n delete webPreferences.preloadURL\n\n // Disable Node.js integration\n webPreferences.nodeIntegration = false\n\n // Verify URL being loaded\n if (!params.src.startsWith('https://example.com/')) {\n event.preventDefault()\n }\n })\n})\nAgain, this list merely minimizes the risk, it does not remove it. If your goal is to display a website, a browser will be a more secure option.
\nSi votre application n'a pas besoin de naviguer ou a seulement besoin de naviguer vers des pages connues, c'est une bonne idée de limiter la navigation directement à cette portée connue, interdire tout autre type de navigation.
\nLa navigation est un vecteur d'attaque courant. Si un attaquant peut convaincre votre application de naviguer loin de sa page actuelle, ils peuvent éventuellement forcer votre application à ouvrir sites web sur Internet. Même si vos webContents sont configurés pour être plus sécurisé (comme avoir nodeIntegration désactivé ou contextIsolation activé), pour que votre application ouvre un site web aléatoire rendra le travail d'exploiter votre application beaucoup plus facile.
Un modèle d'attaque courant est que l'attaquant convainc les utilisateurs de votre application d'interagir avec l'application de manière à ce qu'il navigue sur l'une des pages de l'attaquant. Cela se fait généralement par le biais de liens, de plugins, ou d'autres contenus générés par l'utilisateur.
\nSi votre application n'a pas besoin de navigation, vous pouvez appeler event.preventDefault() dans un gestionnaire navigate. Si vous savez vers quelles pages votre application peut naviguer, vérifiez l'URL dans le gestionnaire d'événements et laissez seulement la navigation se produire si elle correspond aux URL que vous attendez.
Nous vous recommandons d'utiliser l'analyseur de Node pour les URL. Des comparaisons simples de chaînes de caractères peuvent parfois être dupliquées - un test startsWith('https://example.com') laisserait pas https://example.com.attacker.com à travers.
const URL = require('url').URL\n\napp.on('web-contents-created', (event, contents) => {\n contenu. n('will-navigate', (event, navigationUrl) => {\n const parsedUrl = new URL(navigationUrl)\n\n if (parsedUrl. rigin !== 'https://example.com') {\n event.preventDefault()\n }\n })\n})\nSi vous avez un ensemble connu de fenêtres, il est bon de limiter la création de fenêtres supplémentaires dans votre application.
\nTout comme la navigation, la création de nouveaux webContents est un vecteur d'attaque commun . Les attaquants tentent de convaincre votre application de créer de nouvelles fenêtres, cadres, ou d'autres processus de rendu avec plus de privilèges qu'avant; ou avec des pages ouvertes qu'ils ne pouvaient pas ouvrir avant.
Si vous n'avez pas besoin de créer des fenêtres en plus de celles que vous savez que vous aurez besoin de créer, la désactivation de la création vous permet d'acheter gratuitement un peu de sécurité supplémentaire. C'est généralement le cas pour les applications qui ouvrent une BrowserWindow et n'ont pas besoin d'ouvrir un nombre arbitraire de fenêtres supplémentaires à l'exécution.
webContents will delegate to its window open handler before creating new windows. The handler will receive, amongst other parameters, the url the window was requested to open and the options used to create it. We recommend that you register a handler to monitor the creation of windows, and deny any unexpected window creation.
const { shell } = require('electron')\n\napp.on('web-contents-created', (event, contents) => {\n contents.setWindowOpenHandler(({ url }) => {\n // In this example, we'll ask the operating system\n // to open this event's url in the default browser.\n //\n // See the following item for considerations regarding what\n // URLs should be allowed through to shell.openExternal.\n if (isSafeForExternalOpen(url)) {\n setImmediate(() => {\n shell.openExternal(url)\n })\n }\n\n return { action: 'deny' }\n })\n})\nopenExternal avec du contenu non fiableLe openExternal de Shell permet d'ouvrir un URI de protocole donné avec les utilitaires natifs du bureau. Sur macOS, par exemple, cette fonction est similaire à l'utilitaire de commande terminal open et ouvrira l'application spécifique basée sur l'URI et l'association de type fichier.
L'utilisation incorrecte de openExternal peut être utilisée pour compromettre l'hôte de l'utilisateur. Lorsque openExternal est utilisé avec du contenu non fiable, il peut être exploité pour exécuter des commandes arbitraires.
// Mauvais\nconst { shell } = require('electron')\nshell.openExternal(USER_CONTROLLED_DATA_HERE)\n// Bon\nconst { shell } = require('electron')\nshell.openExternal('https://example.com/index.html')\nVous devriez toujours vous efforcer d'utiliser la dernière version disponible d'Electron. Chaque fois qu'une nouvelle version majeure est publiée, vous devriez essayer de mettre à jour votre application le plus rapidement possible.
\nUne application construite avec une ancienne version d'Electron, de Chromium ou de Node.js est une cible plus facile qu'une application qui utilise des versions plus récentes de ces composants. De manière générale, les problèmes de sécurité et les exploitation de failles pour les anciennes versions de Chromium et de Node.js sont plus fréquentes.
\nChromium et Node.js représentent des prouesses impressionnantes d'ingénierie produites par des milliers de développeurs talentueux. Compte tenu de leur popularité, leur sécurité est soigneusement testée et analysée par des chercheurs en sécurité tout aussi compétents. Beaucoup de ces chercheurs révèlent des vulnérabilités de manière responsable, ce qui signifie généralement que les chercheurs donnent de leur temps à Chromium et Node.js pour résoudre les problèmes avant de les publier. Votre application sera plus sécurisée si elle exécute une version récente d'Electron (et donc Chromium et Node.js) dont les problèmes de sécurité potentiels ne sont pas aussi connus.
", "title": "Sécurité, fonctionnalités natives et votre responsabilité", "description": "⚠️ en aucune circonstance vous devriez charger et exécuter du code distant avec l'intégration de Node.js activé. Utilisez plutôt les fichiers locaux (empaquetés avec votre application) pour exécuter le code de Node. Pour afficher du contenu à distance, utilisez le taglabel String (optional) - The text to appear in this segment.icon NativeImage (optional) - The image to appear in this segment.enabled Boolean (optional) - Whether this segment is selectable. Default: true.portId String - Unique identifier for the port.portName String - Name of the port.displayName String - A string suitable for display to the user for describing this device.vendorId String - Optional USB vendor ID.productId String - Optional USB product ID.serialNumber String - The USB device serial number.usbDriverName String (optional) - Represents a single serial port on macOS can be enumerated by multiple drivers.deviceInstanceId String (optional) - A stable identifier on Windows that can be used for device permissions.scriptUrl String - The full URL to the script that this service worker runsscope String - The base URL that this service worker is active for.renderProcessId Number - The virtual ID of the process that this service worker is running in. This is not an OS level PID. This aligns with the ID set used for webContents.getProcessId().\n\nQuery and receive events from a sessions active service workers.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Les instances de la classe ServiceWorkers sont accessibles à l'aide de la propriété serviceWorkers d'une Session.
Par exemple :
\nconst { session } = require('electron')\n\n// Get all service workers.\nconsole.log(session.defaultSession.serviceWorkers.getAllRunning())\n\n// Handle logs and get service worker info\nsession.defaultSession.serviceWorkers.on('console-message', (event, messageDetails) => {\n console.log(\n 'Got service worker message',\n messageDetails,\n 'from',\n session.defaultSession.serviceWorkers.getFromVersionID(messageDetails.versionId)\n )\n})\nLes événements suivants sont disponibles pour les instances de ServiceWorkers :
Retourne :
\nevent EventmessageDetails Object - Information about the console messagemessage String - The actual console messageversionId Number - The version ID of the service worker that sent the log messagesource String - The type of source for this message. Can be javascript, xml, network, console-api, storage, app-cache, rendering, security, deprecation, worker, violation, intervention, recommendation or other.level Number - The log level, from 0 to 3. In order it matches verbose, info, warning and error.sourceUrl String - The URL the message came fromlineNumber Number - The line number of the source that triggered this console messageEmitted when a service worker logs something to the console.
\nRetourne :
\nevent Eventdetails Object - Information about the registered service workerscope String - The base URL that a service worker is registered forEmitted when a service worker has been registered. Can occur after a call to navigator.serviceWorker.register('/sw.js') successfully resolves or when a Chrome extension is loaded.
Les méthodes suivants sont disponibles pour les instances de ServiceWorkers :
serviceWorkers.getAllRunning()Returns Record<Number, ServiceWorkerInfo> - A ServiceWorkerInfo object where the keys are the service worker version ID and the values are the information about that service worker.
serviceWorkers.getFromVersionID(versionId)versionId NumberReturns ServiceWorkerInfo - Information about this service worker
If the service worker does not exist or is not running this method will throw an exception.
", "title": "ServiceWorkers", "description": "Query and receive events from a sessions active service workers." }, "/docs/api/session": { "locale": "fr-FR", "slug": "session", "href": "/docs/api/session", "crowdinFileId": "256365", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/session.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nGère les sessions du navigateur, les cookies, le cache, les paramètres de proxy, etc.
\n
Processus : Main
\nLe module session peut être utilisé pour créer des objets Session.
Vous pouvez également accéder à la session des pages existantes à l’aide de la propriété session des WebContents, ou le module session.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nconst ses = win.webContents.session\nconsole.log(ses.getUserAgent())\nLe module session dispose des méthodes suivantes :
session.fromPartition(partition[, options])partition Stringoptions Object (facultatif)cache Boolean - Si vous voulez activer le cache.Retourne Session - Une instance de session de la chaîne de caractères partition. Quand il y a une Session existante avec la même partition, elle sera retournée; sinon une nouvelle instance Session sera créée avec options.
Si partition commence par persist:, la page utilisera une session persistante disponible pour toutes les pages de l'application avec la même partition. s'il n'y a pas de persist: préfixe, la page utilisera une session en mémoire. Si le partition est vide puis la session par défaut de l'application sera retournée.
Pour créer une Session avec options, vous devez vous assurer que la Session avec la partition n'a jamais été utilisée auparavant. Il n'y a pas moyen de changer les options d'un objet Session existant.
Le module session dispose des propriétés suivantes :
session.defaultSessionUn objet Session, l'objet d'une session par défaut de l'application.
\n\nLes propriétés getter et setter d'une session.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Vous pouvez créer un objet Session avec le module session :
const { session } = require('electron')\nconst ses = session.fromPartition('persist:name')\nconsole.log(ses.getUserAgent())\nLes événements suivants sont disponibles pour les instances de Session :
Retourne :
\nevent Eventitem DownloadItemwebContents WebContentsÉmis lorsque Electron est sur le point de télécharger item dans webContents.
Faire appel à Event.preventDefault () annule le téléchargement et item ne sera pas disponible dans le battement suivant du processus.
const { session } = require('electron')\nsession.defaultSession.on('will-download', (event, item, webContents) => {\n event.preventDefault()\n require('got')(item.getURL()).then((response) => {\n require('fs').writeFileSync('/somewhere', response.body)\n })\n})\nRetourne :
\nevent Eventextension ExtensionÉmis après le chargement d’une extension. Cela se produit chaque fois qu’une extension ajoutée à l’ensemble d’extensions « activées ». Ceci comprend :
\nsession.loadExtension.chrome.runtime.reload()).Retourne :
\nevent Eventextension ExtensionEmitted after an extension is unloaded. Cela se produit lorsque Session.removeExtension est appelée.
Retourne :
\nevent Eventextension ExtensionEmitted after an extension is loaded and all necessary browser state is initialized to support the start of the extension's background page.
\nRetourne :
\nevent EventpreconnectUrl String - L'URL demandée pour la préconnexion par le moteur de rendu .allowCredentials Booléen - Vrai si le moteur de rendu demande que la connexion inclue les informations d'identification (voir la spec pour plus de détails.)Émis lorsqu'un processus de rendu demande de préconnexion à une URL, généralement à cause de un hintressource .
\nRetourne :
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file has been successfully initialized. This occurs after the file has been downloaded.
\nRetourne :
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file starts downloading
\nRetourne :
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file has been successfully downloaded
\nRetourne :
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file download fails. For details on the failure you should collect a netlog and inspect the download request.
\nRetourne :
\nevent EventdetailsdeviceList HIDDevice[]frame WebFrameMaincallback FunctiondeviceId String | null (optional)Emitted when a HID device needs to be selected when a call to navigator.hid.requestDevice is made. callback should be called with deviceId to be selected; passing no arguments to callback will cancel the request. Additionally, permissioning on navigator.hid can be further managed by using ses.setPermissionCheckHandler(handler) and ses.setDevicePermissionHandler(handler)`.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nRetourne :
\nevent Eventdetailsdevice HIDDevice[]frame WebFrameMainEmitted when a new HID device becomes available. For example, when a new USB device is plugged in.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
Retourne :
\nevent Eventdetailsdevice HIDDevice[]frame WebFrameMainEmitted when a HID device has been removed. Par exemple, cet événement se déclenchera lorsqu'un périphérique USB est débranché.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
Retourne :
\nevent EventportList SerialPort[]webContents WebContentscallback FunctionportId StringEmitted when a serial port needs to be selected when a call to navigator.serial.requestPort is made. callback should be called with portId to be selected, passing an empty string to callback will cancel the request. Additionally, permissioning on navigator.serial can be managed by using ses.setPermissionCheckHandler(handler) with the serial permission.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({\n width: 800,\n height: 600\n })\n win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {\n event.preventDefault()\n const selectedPort = portList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n if (!selectedPort) {\n callback('')\n } else {\n callback(selectedPort.portId)\n }\n })\n})\nRetourne :
\nevent Eventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a new serial port becomes available. Par exemple, cet événement se déclenchera lorsqu'un nouveau périphérique USB est branché.
Retourne :
\nevent Eventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a serial port has been removed. Par exemple, cet événement se déclenchera lorsqu'un périphérique USB est débranché.
Les méthodes suivantes sont disponibles pour les instances de Session :
ses.getCacheSize()Retourne Promise<Integer> - la taille actuelle du cache de la session, en octets.
ses.clearCache()Retourne Promise<void> - résout lorsque l'opération de nettoyage du cache est terminée.
Efface le cache HTTP de la session.
\nses.clearStorageData([options])options Object (facultatif)origin String (facultatif) - Doit suivre la représentation de window.location.origin scheme://host:port.storages String - Les types de stockage à effacer, peuvent contenir : appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage. Si ce n'est pas spécifié, effacez tous les types de stockage.quotas String - The types of quotas to clear, can contain: temporary, persistent, syncable. S'il n'est pas spécifié, effacez tous les quotas.Returns Promise<void> - resolves when the storage data has been cleared.
ses.flushStorageData()Writes any unwritten DOMStorage data to disk.
\nses.setProxy(config)config Objectmode String (optional) - The proxy mode. Should be one of direct, auto_detect, pac_script, fixed_servers or system. If it's unspecified, it will be automatically determined based on other specified options.direct In direct mode all connections are created directly, without any proxy involved.auto_detect In auto_detect mode the proxy configuration is determined by a PAC script that can be downloaded at http://wpad/wpad.dat.pac_script In pac_script mode the proxy configuration is determined by a PAC script that is retrieved from the URL specified in the pacScript. C'est le mode par défaut si pacScript est spécifié.fixed_servers En mode fixed_servers, la configuration du proxy est spécifiée dans proxyRules. Il s'agit du mode par défaut si proxyRules est spécifié.system In system mode the proxy configuration is taken from the operating system. Note that the system mode is different from setting no proxy configuration. In the latter case, Electron falls back to the system settings only if no command-line options influence the proxy configuration.pacScript String (optional) - The URL associated with the PAC file.proxyRules String (optional) - Rules indicating which proxies to use.proxyBypassRules String (optional) - Rules indicating which URLs should bypass the proxy settings.Returns Promise<void> - Resolves when the proxy setting process is complete.
Indique les paramètres de proxy.
\nWhen mode is unspecified, pacScript and proxyRules are provided together, the proxyRules option is ignored and pacScript configuration is applied.
You may need ses.closeAllConnections to close currently in flight connections to prevent pooled sockets using previous proxy from being reused by future requests.
Les proxyRules doivent suivre les règles ci-dessous :
proxyRules = schemeProxies[\";\"<schemeProxies>]\nschemeProxies = [<urlScheme>\"=\"]<proxyURIList>\nurlScheme = \"http\" | \"https\" | \"ftp\" | \"socks\"\nproxyURIList = <proxyURL>[\",\"<proxyURIList>]\nproxyURL = [<proxyScheme>\"://\"]<proxyHost>[\":\"<proxyPort>]\nPar exemple :
\nhttp=foopy:80;ftp=foopy2 - Use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.foopy:80 - Use HTTP proxy foopy:80 for all URLs.foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing over to bar if foopy:80 is unavailable, and after that using no proxy.socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail over to the SOCKS5 proxy bar.com if foopy is unavailable.http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no proxy if foopy is unavailable.http=foopy;socks=foopy2 - Use HTTP proxy foopy for http URLs, and use socks4://foopy2 for all other URLs.Le proxyBypassRules est une liste de règles séparées par des virgules, comme décrites ci-dessous :
[ URL_SCHEME \"://\" ] HOSTNAME_PATTERN [ \":\" <port> ]
Correspond à tous les noms d'hôte qui correspondent au pattern HOSTNAME_PATTERN.
\nExamples: \"foobar.com\", \"foobar.com\", \".foobar.com\", \"foobar.com:99\", \"https://x..y.com:99\"
\n\".\" HOSTNAME_SUFFIX_PATTERN [ \":\" PORT ]
Correspond à un suffixe de domaine particulier.
\nExemples: \".google.com\", \".com\", \"http://.google.com\"
\n[ SCHEME \"://\" ] IP_LITERAL [ \":\" PORT ]
Correspond aux URLs qui sont des adresses IP littérales.
\nExemples: \"127.0.1\", \"[0:0::1]\", \"[::1]\", \"http://[::1]:99\"
\nIP_LITERAL \"/\" PREFIX_LENGTH_IN_BITS
Match any URL that is to an IP literal that falls between the given range. IP range is specified using CIDR notation.
\nExemples: \"192.168.1.1/16\", \"fefe:13::abc/33\".
\n<local>
Match local addresses. The meaning of <local> is whether the host matches one of: \"127.0.0.1\", \"::1\", \"localhost\".
ses.resolveProxy(url)url URLReturns Promise<String> - Resolves with the proxy information for url.
ses.forceReloadProxyConfig()Returns Promise<void> - Resolves when the all internal states of proxy service is reset and the latest proxy configuration is reapplied if it's already available. Le script pac sera à nouveau extrait de pacScript si le mode proxy est pac_script.
ses.setDownloadPath(path)path String - The download location.Sets download saving directory. By default, the download directory will be the Downloads under the respective app folder.
ses.enableNetworkEmulation(options)optionsoffline Boolean (optional) - Whether to emulate network outage. Defaults to false.latency Double (optional) - RTT in ms. Defaults to 0 which will disable latency throttling.downloadThroughput Double (optional) - Download rate in Bps. Defaults to 0 which will disable download throttling.uploadThroughput Double (optional) - Upload rate in Bps. Defaults to 0 which will disable upload throttling.Emule le réseau avec la configuration donnée pour la session.
// Pour émuler une connexion GPRS avec un débit de 50kbps et une latence de 500 ms.\nwindow.webContents.session.enableNetworkEmulation({\n latency: 500,\n downloadThroughput: 6400,\n uploadThroughput: 6400\n})\n\n// Pour simuler une panne réseau.\nwindow.webContents.session.enableNetworkEmulation({ offline: true })\nses.preconnect(options)optionsurl String - URL for preconnect. Only the origin is relevant for opening the socket.numSockets Number (optional) - number of sockets to preconnect. Must be between 1 and 6. Defaults to 1.Preconnects the given number of sockets to an origin.
\nses.closeAllConnections()Returns Promise<void> - Resolves when all connections are closed.
Note: It will terminate / fail all requests currently in flight.
\nses.disableNetworkEmulation()Disables any network emulation already active for the session. Resets to the original network configuration.
ses.setCertificateVerifyProc(proc)proc Function | nullrequest Objecthostname Stringcertificate CertificatevalidatedCertificate CertificateverificationResult String - Résultat de la vérification par Chromium.errorCode Integer - Code d'erreur.callback FunctionverificationResult Integer - Value can be one of certificate error codes from here. Apart from the certificate error codes, the following special codes can be used.0 - Indique la réussite et désactive la vérification de transparence de certificat.-2 - Indique l'échec.-3 - Utilise le résultat de la vérification de Chromium.Sets the certificate verify proc for session, the proc will be called with proc(request, callback) whenever a server certificate verification is requested. Calling callback(0) accepts the certificate, calling callback(-2) rejects it.
Calling setCertificateVerifyProc(null) will revert back to default certificate verify proc.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.webContents.session.setCertificateVerifyProc((request, callback) => {\n const { hostname } = request\n if (hostname === 'github.com') {\n callback(0)\n } else {\n callback(-2)\n }\n})\n\n\nNOTE: The result of this procedure is cached by the network service.
\n
ses.setPermissionRequestHandler(handler)handler Function | nullwebContents WebContents - WebContents qui demandent la permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.permission String - The type of requested permission.clipboard-read - Demande d'accès à la lecture depuis le presse-papiers.média - Demande l'accès à des périphériques multimédia tels que la caméra, le microphone et les haut-parleurs.afficher-capture Demander acces pour capturer l'ecran.mediaKeysystem - Demande d’accès au contenu protégé par DRM.geolocation - Demande d'accès à l'emplacement actuel de l'utilisateur.notifications - Request notification creation and the ability to display them in the user's system tray.midi - Request MIDI access in the webmidi API.midiSysex - Request the use of system exclusive messages in the webmidi API.pointerLock - Request to directly interpret mouse movements as an input method. Cliquez ici pour en savoir plus.fullscreen - Demande de l'application pour passer en mode plein écran.openExternal - Request to open links in external applications.unknown - An unrecognized permission requestcallback FunctionpermissionGranted Boolean - Allow or deny the permission.details Object - Some properties are only available on certain permission types.externalURL String (optional) - The url of the openExternal request.mediaTypes String - The types of media access being requested, elements can be video or audiorequestingUrl String - The last URL the requesting frame loadedisMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission requests for the session. Calling callback(true) will allow the permission and callback(false) will reject it. Pour effacer le gestionnaire, appelez setPermissionRequestHandler(null). Please note that you must also implement setPermissionCheckHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied.
const { session } = require('electron')\nsession.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {\n if (webContents.getURL() === 'some-host' && permission === 'notifications') {\n return callback(false) // interdit.\n }\n\n callback(true)\n})\nses.setPermissionCheckHandler(handler)handler Function\\webContents (WebContents | null) - WebContents checking the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin. Toutes les frames de cross origin effectuant des vérifications de permission passeront un null webContents à ce gestionnaire, alors que certaines autres vérifications de permissions, telles que notifications , passeront toujours null. You should use embeddingOrigin and requestingOrigin to determine what origin the owning frame and the requesting frame are on respectively.permission String - Type of permission check. Valid values are midiSysex, notifications, geolocation, media,mediaKeySystem,midi, pointerLock, fullscreen, openExternal, hid, or serial.requestingOrigin String - The origin URL of the permission checkdetails Object - Some properties are only available on certain permission types.embeddingOrigin String (optional) - The origin of the frame embedding the frame that made the permission check. Only set for cross-origin sub frames making permission checks.securityOrigin String (optional) - The security origin of the media check.mediaType String (optional) - The type of media access being requested, can be video, audio or unknownrequestingUrl String (optional) - The last URL the requesting frame loaded. This is not provided for cross-origin sub frames making permission checks.isMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission checks for the session. Returning true will allow the permission and false will reject it. Please note that you must also implement setPermissionRequestHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied. Pour effacer le gestionnaire, appelez setPermissionCheckHandler(null).
const { session } = require('electron')\nconst url = require('url')\nsession.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {\n return true // granted\n }\n\n return false // denied\n})\nses.setDevicePermissionHandler(handler)handler Function\\detailsdeviceType String - The type of device that permission is being requested on, can be hid.origin String - The origin URL of the device permission check.device HIDDevice - the device that permission is being requested for.frame WebFrameMain - WebFrameMain checking the device permission.Sets the handler which can be used to respond to device permission checks for the session. Returning true will allow the device to be permitted and false will reject it. To clear the handler, call setDevicePermissionHandler(null). This handler can be used to provide default permissioning to devices without first calling for permission to devices (eg via navigator.hid.requestDevice). If this handler is not defined, the default device permissions as granted through device selection (eg via navigator.hid.requestDevice) will be used. Additionally, the default behavior of Electron is to store granted device permision through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nses.clearHostResolverCache()Returns Promise<void> - Resolves when the operation is complete.
Vide le cache de résolution de l'hôte.
\nses.allowNTLMCredentialsForDomains(domains)domaines String - Une liste de serveurs séparés par des virgules pour lesquels l'authentification intégrée est activée.Définit dynamiquement s'il faut toujours envoyer des identifiants pour l'authentification HTTP NTLM ou Négocier .
\nconst { session } = require('electron')\n// considère n'importe quelle url se terminant par `example.com`, `foobar.com`, `baz`\n// pour une authentification intégrée.\nsession.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')\n\n// considère toutes les urls pour une authentification intégrée.\nsession.defaultSession.allowNTLMCredentialsForDomains('*')\nses.setUserAgent(userAgent[, acceptLanguages])userAgent StringacceptLanguages String (facultatif)Remplace les userAgent et acceptLanguages pour cette session.
Le acceptLanguages doit être une liste ordonnée de codes de langue séparés par des virgules, pour exemple \"en-US,fr,de,ko,zh-CN,ja\".
Cela n'affecte pas les WebContents, et chaque WebContents peut utiliser webContents.setUserAgent pour remplacer l'agent utilisateur à l'échelle de la session.
ses.isPersistent()Returns Boolean - Whether or not this session is a persistent one. The default webContents session of a BrowserWindow is persistent. When creating a session from a partition, session prefixed with persist: will be persistent, while others will be temporary.
ses.getUserAgent()Renvoie String - L'utilisateur de cette session.
ses.setSSLConfig(config)config ObjectminVersion String (optional) - Can be tls1, tls1.1, tls1.2 or tls1.3. The minimum SSL version to allow when connecting to remote servers. tls1 par défaut.maxVersion String (optional) - Can be tls1.2 or tls1.3. The maximum SSL version to allow when connecting to remote servers. Par défaut, tls1.3.disabledCipherSuites Integer - List of cipher suites which should be explicitly prevented from being used in addition to those disabled by the net built-in policy. Supported literal forms: 0xAABB, where AA is cipher_suite[0] and BB is cipher_suite[1], as defined in RFC 2246, Section 7.4.1.2. Unrecognized but parsable cipher suites in this form will not return an error. Ex: To disable TLS_RSA_WITH_RC4_128_MD5, specify 0x0004, while to disable TLS_ECDH_ECDSA_WITH_RC4_128_SHA, specify 0xC002. Note that TLSv1.3 ciphers cannot be disabled using this mechanism.Sets the SSL configuration for the session. All subsequent network requests will use the new configuration. Existing network connections (such as WebSocket connections) will not be terminated, but old sockets in the pool will not be reused for new connections.
\nses.getBlobData(identifier)identifier String - UUID valide.Retourne Promise<Buffer> - résout avec des données Blob.
ses.downloadURL(url)url StringInitiates a download of the resource at url. The API will generate a DownloadItem that can be accessed with the will-download event.
Note: This does not perform any security checks that relate to a page's origin, unlike webContents.downloadURL.
ses.createInterruptedDownload(options)optionspath String - Chemin d'accès absolu pour le téléchargement.urlChain String[] - Chaîne de caractère complète de l'URL du téléchargement.type String (facultatif)offset Integer - Portée de départ pour le téléchargement.length Integer - Longueur totale du le téléchargement.lastModified String (optional) - Last-Modified header value.eTag String (optional) - ETag header value.startTime Double (facultatif) - Heure du début de téléchargement, en nombre de secondes depuis la date initiale UNIX (1er janvier 1970 à 0 heure (UTC)).Autorise la reprise des téléchargements annulés ou interrompus depuis la Sessionprécédente. L'API va générer un DownloadItem accessible avec l'événement will-download . Le DownloadItem n'aura aucun WebContents associé et l'état initial sera interrompu. Le téléchargement ne démarre que lorsque l'API resume est appelée sur DownloadItem.
ses.clearAuthCache()Retourne Promise<void> - résout lorsque le cache d'authentification HTTP de la session a été effacé.
ses.setPreloads(preloads)preloads String[] - Un tableau de chemin absolu pour précharger les scriptsAjoute des scripts qui seront exécutés sur TOUS les contenus web qui sont associés à cette session juste avant l'exécution normale des scripts preload.
ses.getPreloads()Retourne String[] un tableau de chemins pour précharger les scripts qui ont été enregistrés.
ses.setSpellCheckerEnabled(enable)enable BooleanSets whether to enable the builtin spell checker.
\nses.isSpellCheckerEnabled()Returns Boolean - Whether the builtin spell checker is enabled.
ses.setSpellCheckerLanguages(languages)languages String[] - An array of language codes to enable the spellchecker for.The built in spellchecker does not automatically detect what language a user is typing in. In order for the spell checker to correctly check their words you must call this API with an array of language codes. You can get the list of supported language codes with the ses.availableSpellCheckerLanguages property.
Note: On macOS the OS spellchecker is used and will detect your language automatically. This API is a no-op on macOS.
\nses.getSpellCheckerLanguages()Returns String[] - An array of language codes the spellchecker is enabled for. If this list is empty the spellchecker will fallback to using en-US. By default on launch if this setting is an empty list Electron will try to populate this setting with the current OS locale. This setting is persisted across restarts.
Note: On macOS the OS spellchecker is used and has its own list of languages. This API is a no-op on macOS.
\nses.setSpellCheckerDictionaryDownloadURL(url)url String - A base URL for Electron to download hunspell dictionaries from.By default Electron will download hunspell dictionaries from the Chromium CDN. If you want to override this behavior you can use this API to point the dictionary downloader at your own hosted version of the hunspell dictionaries. We publish a hunspell_dictionaries.zip file with each release which contains the files you need to host here, the file server must be case insensitive you must upload each file twice, once with the case it has in the ZIP file and once with the filename as all lower case.
If the files present in hunspell_dictionaries.zip are available at https://example.com/dictionaries/language-code.bdic then you should call this api with ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Please note the trailing slash. The URL to the dictionaries is formed as ${url}${filename}.
Note: On macOS the OS spellchecker is used and therefore we do not download any dictionary files. This API is a no-op on macOS.
\nses.listWordsInSpellCheckerDictionary()Returns Promise<String[]> - An array of all words in app's custom dictionary. Resolves when the full dictionary is loaded from disk.
ses.addWordToSpellCheckerDictionary(word)word String - The word you want to add to the dictionaryReturns Boolean - Whether the word was successfully written to the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be written to the OS custom dictionary as well
\nses.removeWordFromSpellCheckerDictionary(word)word String - The word you want to remove from the dictionaryReturns Boolean - Whether the word was successfully removed from the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be removed from the OS custom dictionary as well
\nses.loadExtension(path[, options])path String - Path to a directory containing an unpacked Chrome extensionoptions Object (facultatif)allowFileAccess Boolean - Whether to allow the extension to read local files over file:// protocol and inject content scripts into file:// pages. This is required e.g. for loading devtools extensions on file:// URLs. Par défaut, faux.Returns Promise<Extension> - resolves when the extension is loaded.
This method will raise an exception if the extension could not be loaded. If there are warnings when installing the extension (e.g. if the extension requests an API that Electron does not support) then they will be logged to the console.
\nNote that Electron does not support the full range of Chrome extensions APIs. See Supported Extensions APIs for more details on what is supported.
\nNote that in previous versions of Electron, extensions that were loaded would be remembered for future runs of the application. This is no longer the case: loadExtension must be called on every boot of your app if you want the extension to be loaded.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.on('ready', async () => {\n await session.defaultSession.loadExtension(\n path.join(__dirname, 'react-devtools'),\n // allowFileAccess is required to load the devtools extension on file:// URLs.\n { allowFileAccess: true }\n )\n // Note that in order to use the React DevTools extension, you'll need to\n // download and unzip a copy of the extension.\n})\nThis API does not support loading packed (.crx) extensions.
\nRemarque : Cette API ne peut pas être appelée avant que l'événement prêt du module app ne soit émis.
Note: Loading extensions into in-memory (non-persistent) sessions is not supported and will throw an error.
\nses.removeExtension(extensionId)extensionId String - ID of extension to removeUnloads an extension.
\nRemarque : Cette API ne peut pas être appelée avant que l'événement prêt du module app ne soit émis.
ses.getExtension(extensionId)extensionId String - ID of extension to queryReturns Extension | null - The loaded extension with the given ID.
Remarque : Cette API ne peut pas être appelée avant que l'événement prêt du module app ne soit émis.
ses.getAllExtensions()Returns Extension[] - A list of all loaded extensions.
Remarque : Cette API ne peut pas être appelée avant que l'événement prêt du module app ne soit émis.
ses.getStoragePath()A String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
Les propriétés suivantes sont disponibles pour les instances de Session :
ses.availableSpellCheckerLanguages Lecture seuleA String[] array which consists of all the known available spell checker languages. Providing a language code to the setSpellCheckerLanguages API that isn't in this array will result in an error.
ses.spellCheckerEnabledA Boolean indicating whether builtin spell checker is enabled.
ses.storagePath Lecture seuleA String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
ses.cookies ReadonlyUn objet Cookies pour cette session.
ses.serviceWorkers Lecture seuleUn objet ServiceWorkers pour cette session.
ses.webRequest ReadonlyUn objet WebRequest pour cette session.
ses.protocol ReadonlyUn objet Protocole pour cette session.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const protocol = session.fromPartition('some-partition').protocol\n if (!protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })) {\n console.error('Failed to register protocol')\n }\n})\nses.netLog ReadonlyUn objet NetLog pour cette session.
const { app, session } = require('electron')\n\napp.whenReady().then(async () => {\n const netLog = session.fromPartition('some-partition').netLog\n netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nLes symboles de déboggage vous permettent d’avoir de meilleurs sessions de déboggage. Ils ont des informations sur les fonctions contenues dans les fichiers exécutables et les bibliothèques dynamiques et vous fournissent des renseignements pour obtenir des piles d’appels propre. Un serveur de symboles permet au déboggueur de charger les symboles appropriés, les fichiers binaires et les fichiers sources automatiquement, sans forcer les utilisateurs à télécharger de gros fichiers de déboggage. Documentation sur Le serveur de symboles de Microsoft.
\nNotez que parce que Electron est fortement optimisé, le déboggage n’est pas toujours facile. Le déboggueur ne sera pas en mesure de vous montrer le contenu de toutes les variables et le chemin d’exécution peut sembler étrange à cause de l’inlining, queue d’appels et autres optimisations du compilateur. La seule solution est de build une version locale non optimisée.
\nL’URL du serveur symbole officiel pour Electron est https://symbols.electronjs.org. Vous ne pouvez pas visiter cette URL directement, vous devez l’ajouter au chemin de symbole de votre outil de déboggage. Dans les exemples ci-dessous, un répertoire de cache local est utilisé pour éviter la lecture à plusieurs reprises du PDB sur le serveur. Remplacez c:\\code\\symbols par un répertoire de cache approprié sur votre ordinateur.
Le chemin de symbole Windbg est configuré avec un string délimité par des : *. Pour utiliser uniquement le serveur de symboles d’Electron, ajoutez l’entrée suivante à votre chemin de symbole (Remarque : vous pouvez remplacer c:\\code\\symbols par n’importe quel répertoire accessible en écriture sur votre ordinateur, si vous préférez un emplacement différent pour les symboles téléchargés) :
SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\nDéfinissez le string à _NT_SYMBOL_PATH dans l’environnement, en utilisant les menus de Windbg, ou en tapant la commande .sympath. Si vous souhaitez obtenir les symboles du serveur de symboles Microsoft, vous devez indiquer cela :
SRV*c:\\code\\symbols\\*https://msdl.microsoft.com/download/symbols;SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\n Options\">
Tapez les commandes suivantes dans Windbg pour savoir pourquoi les symboles ne se chargent pas:
\n> !sym noisy\n> .reload /f electron.exe\nThe ShareMenu class creates Share Menu on macOS, which can be used to share information from the current context to apps, social media accounts, and other services.
For including the share menu as a submenu of other menus, please use the shareMenu role of MenuItem.
\n\nCreate share menu on macOS.
\n
Processus : Main
\nnew ShareMenu(sharingItem)sharingItem SharingItem - The item to share.Creates a new share menu.
\nL’objet shareMenu dispose des méthodes d’instance suivantes :
shareMenu.popup([options])options PopupOptions (optional)browserWindow BrowserWindow (facultatif) - La fenêtre focalisée est par défaut.x Number (facultatif) - C'est par défaut la position actuelle du curseur de la souris. Doit être déclaré si y est déclaré.x Number (facultatif) - C'est par défaut la position actuelle du curseur de la souris. Doit être déclaré si x est déclaré.positioningItem Number (facultatif) macOS - L'index de l'élément de menu à positionner sous le curseur de la souris aux coordonnées spécifiées. est. La valeur par défaut est -1.callback Fonction (facultatif) - Appelée lorsque le menu est fermé.Dépile ce menu sous la forme d'un menu contextuel dans la BrowserWindow.
shareMenu.closePopup([browserWindow])browserWindow BrowserWindow (facultatif) - La fenêtre focalisée est par défaut.Ferme le menu contextuel dans la browserWindow.
id String - The unique id of the shared worker.url String - The url of the shared worker.texts String - An array of text to share.filePaths String - An array of files to share.urls String - An array of URLs to share.\n\nGère des fichiers et URLs à l'aide de leurs applications par défaut.
\n
Process: Main, Renderer (non-sandboxed only)
\nLe module shell fournit des fonctions liées à l'intégration bureau.
Un exemple d'ouverture d'une URL dans le navigateur par défaut de l'utilisateur :
\nconst { shell } = require('electron')\n\nshell.openExternal('https://github.com')\nNote: While the shell module can be used in the renderer process, it will not function in a sandboxed renderer.
Le module shell dispose des méthodes suivantes :
shell.showItemInFolder(fullPath)fullPath StringShow the given file in a file manager. If possible, select the file.
\nshell.openPath(path)path StringReturns Promise<String> - Resolves with a string containing the error message corresponding to the failure if a failure occurred, otherwise \"\".
Ouvre le fichier donné dans la manière par défaut de l'ordinateur.
\nshell.openExternal(url[, options])url String - 2081 caractères max. sur Windows.options Object (facultatif)activate Boolean (optional) macOS - true to bring the opened application to the foreground. Par défaut, true.workingDirectory String (optional) Windows - Le dossier de travail.Retourne Promise<void>
Open the given external protocol URL in the desktop's default manner. (For example, mailto: URLs in the user's default mail agent).
\nshell.trashItem(path)path String - path to the item to be moved to the trash.Returns Promise<void> - Resolves when the operation has been completed. Rejects if there was an error while deleting the requested item.
This moves a path to the OS-specific trash location (Trash on macOS, Recycle Bin on Windows, and a desktop-environment-specific location on Linux).
\nshell.beep()Émet un signal sonore.
\nshell.writeShortcutLink(shortcutPath[, operation], options) WindowsshortcutPath Stringoperation String (optional) - Default is create, can be one of following:create - Créer un nouveau raccourci, écrase si besoin.update - Met à jour les propriétés seulement sur un raccourci existant.replace - Remplace un raccourci existant, échoue si le raccourci n'existe pas.options ShortcutDetailsRetourne Boolean - Si le raccourci a été créé avec succès.
Créer ou met à jour un lien raccourci à shortcutPath.
shell.readShortcutLink(shortcutPath) WindowsshortcutPath StringRetourne ShortcutDetails
Résout le lien raccourci à shortcutPath.
Une exception sera levée lorsqu’une erreur se produit.
", "title": "shell", "description": "Gère des fichiers et URLs à l'aide de leurs applications par défaut." }, "/docs/api/structures/shortcut-details": { "locale": "fr-FR", "slug": "shortcut-details", "href": "/docs/api/structures/shortcut-details", "crowdinFileId": "256509", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/shortcut-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "target String - The target to launch from this shortcut.cwd String (optional) - The working directory. Default is empty.args String (optional) - The arguments to be applied to target when launching from this shortcut. Default is empty.description String (optional) - The description of the shortcut. Default is empty.icon String (optional) - The path to the icon, can be a DLL or EXE. icon and iconIndex have to be set together. Default is empty, which uses the target's icon.iconIndex Number (optional) - The resource ID of icon when icon is a DLL or EXE. Default is 0.appUserModelId String (optional) - The Application User Model ID. Default is empty.toastActivatorClsid String (optional) - The Application Toast Activator CLSID. Needed for participating in Action Center.width Numberheight NumberCe guide fournit des informations sur comment empaqueter votre application Electron pour n’importe quel environnement Snapcraft, y compris l’Ubuntu Software Center.
\nAvec une plus large communauté Linux, Canonical a pour but de corriger de nombreux problèmes d'installation de logiciels courants avec le projet snapcraft . Snaps are containerized software packages that include required dependencies, auto-update, and work on all major Linux distributions without system modification.
Il existe trois méthodes pour créer un fichier .snap :
1) En utilisant electron-forge ou electron-builder, deux outils qui sont livrés en supportant snap par nature. C'est l'option la plus simple. 2) En utilisant electron-installer-snap, qui réceptionne les émissions d'electron-packager. 3) En utilisant un package .deb déjà créé.
In some cases, you will need to have the snapcraft tool installed. Instructions to install snapcraft for your particular distribution are available here.
electron-installer-snapLe module fonctionne comme electron-winstaller et les modules similaires en ce sens que sa portée est limitée à la construction de paquets snap. Vous pouvez installer avec :
npm install --save-dev electron-installer-snap\nEmpaquetez l’application à l’aide de electron-packager (ou d'un outil similaire). Assurez vous de supprimer node_modules dont vous n'avez plus besoin dans votre application finale, puisque tout module dont vous n'avez pas besoin augmentera inutilement la taille de votre application.
La sortie devrait ressembler à peu près à ceci :
\n.\n└── dist\n └── app-linux-x64\n ├── LICENSE\n ├── LICENSES.chromium.html\n ├── content_shell.pak\n ├── app\n ├── icudtl.dat\n ├── libgcrypt.so.11\n ├── libnode.so\n ├── locales\n ├── resources\n ├── v8_context_snapshot.bin\n └── version\nelectron-installer-snapDepuis un terminal qui a snapcraft dans son PATH, exécutez electron-installer-snap avec seulement --src, qui est l'emplacement de votre application Electron créée à la première étape.
npx electron-installer-snap --src=out/myappname-linux-x64\nSi vous avez un pipeline de construction existant, vous pouvez utiliser programmer electron-installer-snap. Pour plus d'informations, voir la doc Snapcraft API.
const snap = require('electron-installer-snap')\n\nsnap(options)\n .then(snapPath => console.log(`Created snap at ${snapPath}!`))\nsnapcraft with electron-packagerCreate your project directory and add the following to snap/snapcraft.yaml:
name: electron-packager-hello-world\nversion: '0.1'\nsummary: Hello World Electron app\ndescription: |\n Simple Hello World Electron app as an example\nbase: core18\nconfinement: strict\ngrade: stable\n\napps:\n electron-packager-hello-world:\n command: electron-quick-start/electron-quick-start --no-sandbox\n extensions: [gnome-3-34]\n plugs:\n - browser-support\n - network\n - network-bind\n environment:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n TMPDIR: $XDG_RUNTIME_DIR\n\nparts:\n electron-quick-start:\n plugin: nil\n source: https://github.com/electron/electron-quick-start.git\n override-build: |\n npm install electron electron-packager\n npx electron-packager . --overwrite --platform=linux --output=release-build --prune=true\n cp -rv ./electron-quick-start-linux-* $SNAPCRAFT_PART_INSTALL/electron-quick-start\n build-snaps:\n - node/14/stable\n build-packages:\n - unzip\n stage-packages:\n - libnss3\n - libnspr4\nIf you want to apply this example to an existing project:
\nsource: https://github.com/electron/electron-quick-start.git with source: ..electron-quick-start with your project's name.$ snapcraft\n\n<output snipped>\nSnapped electron-packager-hello-world_0.1_amd64.snap\nsudo snap install electron-packager-hello-world_0.1_amd64.snap --dangerous\nelectron-packager-hello-world\nSnapcraft est capable de prendre un fichier .deb existant et de le convertir en un fichier .snap. La création d'un snap est configurée via un fichier snapcraft.yaml qui décrit les sources, dépendances, descriptions, et d'autres blocs de construction cruciaux.
Si vous n’avez pas déjà un package .deb, utiliser electron-installer-snap peut être un chemin plus facile pour créer des packages snap. However, multiple solutions for creating Debian packages exist, including electron-forge, electron-builder or electron-installer-debian.
For more information on the available configuration options, see the documentation on the snapcraft syntax. Examinons un exemple :
\nname: myApp\nversion: '2.0.0'\nsummary: Une breve description de mon apli.\ndescription: |\n You know what? This app is amazing! It does all the things\n for you. Some say it keeps you young, maybe even happy.\n\ngrade: stable\nconfinement: classic\n\nparts:\n slack:\n plugin: dump\n source: my-deb.deb\n source-type: deb\n after:\n - desktop-gtk3\n stage-packages:\n - libasound2\n - libnotify4\n - libnspr4\n - libnss3\n - libpcre3\n - libpulse0\n - libxss1\n - libxtst6\n electron-launch:\n plugin: dump\n source: files/\n prepare: |\n chmod +x bin/electron-launch\n\napps:\n myApp:\n command: bin/electron-launch $SNAP/usr/lib/myApp/myApp\n desktop: usr/share/applications/myApp.desktop\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n environment:\n TMPDIR: $XDG_RUNTIME_DIR\nComme vous pouvez le voir, le snapcraft.yaml demande au système d'exécuter le fichier nommé electron-launch. Dans cet exemple, il transmet des informations au code binaire de l'application :
\nexec \"$@\" --executed-from=\"$(pwd)\" --pid=$$ > /dev/null 2>&1 &\nAlternativement, si vous générez votre snap avec la restriction strict , vous pouvez utiliser la commande desktop-launch:
apps:\n myApp:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n command: env TMPDIR=$XDG_RUNTIME_DIR PATH=/usr/local/bin:${PATH} ${SNAP}/bin/desktop-launch $SNAP/myApp/desktop\n desktop: usr/share/applications/desktop.desktop\nLe code source d'Electron est séparé en plusieurs parties, principalement suivant les conventions de séparation de Chromium.
\nVous devrez peut-être vous familiariser avec l'architecture multi-processus de Chromium pour mieux comprendre le code source.
\nElectron\n── build/ - Construire les fichiers de configuration nécessaires pour construire avec GN.\n── buildflags/ - Détermine l'ensemble des fonctionnalités qui peuvent être construites de manière conditionnelle.\n── chromium_src/ - Code source copié à partir de Chromium qui ne fait pas partie de la couche de contenu.\n── default_app/ - Une application par défaut exécutée lorsque Electron est démarré sans\n| fournissant une application consommateur.\n── docs/ - Documentation d'Electron.\n| ── api/ - Documentation pour les modules et les API externes d'Electron.\n| ── development/ - Documentation pour aider au développement pour et avec Electron.\n| ── violondes/ - Un ensemble de snippets de code que l'on peut exécuter dans Electron Fiddle.\n| ── images/ - Images utilisées dans la documentation.\n| <unk> ─ tutorial/ - Documents de tutoriel pour divers aspects d'Electron.\n├── lib/ - JavaScript/TypeScript source code.\n| ── browser/ - Code d'initialisation du processus principal.\n| | | ─ api/ - Implémentation d'API pour les modules de processus principaux.\n| | <unk> ─ remote/ - Code relatif au module distant tel qu'il est\n| | utilisé dans le processus principal.\n| ── common/ - Relating to logic needed by both main and renderer process.\n| | <unk> ─ api/ - Implémentation de l'API pour les modules qui peuvent être utilisés dans\n| | | à la fois les processus principaux et les processus de rendu\n| ── isoated_render/ - Permet la création de processus de rendu isolés lorsque\n| | | contextIsolation est activée.\n| ── render/ - Code d'initialisation du processus de rendu.\n| | | ─ api/ - Implémentation d'API pour les modules de processus de rendu.\n| | | ── extension/ - Code relatif à l'utilisation des extensions Chrome\n| | | dans le processus de rendu d'Electron.\n| | | ─ remote/ - Logique qui gère l'usage du module remote dans\n| | | | le processus principal.\n| | <unk> ─ web-view/ - Logique qui gère l'utilisation des webviews dans le processus\n| | renderer.\n| ── sandboxed_render/ - Logique qui gère la création du moteur de rendu en bac à sable\n| | | processus.\n| | <unk> ─ api/ - Implémentation de l'API pour les processus de rendu bac à sable.\n| <unk> ─ worker/ - Logique qui gère les bonnes fonctionnalités de Node.js\n| environnements dans les Web Workers.\n── patches/ - Des correctifs appliqués au dessus des dépendances principales d'Electron\n| | | afin de gérer les différences entre nos cas d'utilisation et\n| | fonctionnalité par défaut.\n| ── boringssl/ - Patchs appliqués au fork Google d'OpenSSL, BoringSSL.\n| ── chromium/ - Patchs appliqués à Chromium.\n| ── node/ - Patches appliqués au-dessus de Node.js.\n| <unk> ─ v8/ - Patches appliqués au dessus du moteur V8 de Google.\n── shell/ - Code source C++.\n| ├── app/ - Code d'entrée du système.\n| ├── browser/ - Le frontend incluent la fenêtre principale, l'UI et toutes les \n| | | choses du processus principal. Ceci parle au moteur de rendu pour gérer le web\n| | pages.\n| | ├── ui/ - Implementation de l'UI pour différentes plateformes.\n| | | ├── cocoa/ - Code Source spécifique à Cocoa.\n| | | ├── win/ - Code source spécifique pour le GUI Windows.\n| | | └── x/ - Code Source spécifique à X11.\n| | ├── api/ - L'implementation des principales API de processus.\n| | ├── net/ - Code lié au réseau.\n| | ├── mac/ - Code Source Objective-C spécifique à MacOS.\n| | └── resources/ - Icons, platform-dependent files, etc.\n| ├── renderer/ - Code that runs in renderer process.\n| | └── api/ - L'implementation des API de processus de rendu.\n| <unk> ─ common/ - Code qui est utilisé à la fois par les processus principaux et les processus de rendu,\n| | y compris quelques fonctions utilitaires et du code pour intégrer les nœuds\n| | boucle message dans la boucle de message de Chromium.\n| <unk> ─ api/ - Implémentation d'API communes, et fondations de\n| Modules intégrés d'Electron.\n── spec/ - Les composants de la suite de tests d'Electron exécutés dans le processus de rendu.\n── spec-main/ - Les composants de la suite de tests d'Electron s'exécutent dans le processus principal.\n<unk> ─ BUILD.gn - Règles de construction d'Electron.\nscript/create-dist.py lors de la création d'une distribution.ninja.script/ - L'ensemble de tous les scripts que Electron exécute pour une variété de fonctions.\n── codesign/ - Codesign Fakes pour les applications Electron ; utilisé pour les tests.\n── lib/ - Divers scripts python.\n<unk> ─ release/ - Scripts exécutés pendant le processus de publication d'Electron.\n ── notes/ - Génère des notes de publication pour les nouvelles versions d'Electron.\n <unk> ─ ─ uploaders/ - Envoie divers fichiers liés à la version pendant la sortie.\nElectron has built-in support for Chromium's spellchecker since Electron 8. On Windows and Linux this is powered by Hunspell dictionaries, and on macOS it makes use of the native spellchecker APIs.
\nFor Electron 9 and higher the spellchecker is enabled by default. For Electron 8 you need to enable it in webPreferences.
const myWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: true\n }\n})\nOn macOS as we use the native APIs there is no way to set the language that the spellchecker uses. By default on macOS the native spellchecker will automatically detect the language being used for you.
\nFor Windows and Linux there are a few Electron APIs you should use to set the languages for the spellchecker.
\n// Sets the spellchecker to check English US and French\nmyWindow.session.setSpellCheckerLanguages(['en-US', 'fr'])\n\n// An array of all available language codes\nconst possibleLanguages = myWindow.session.availableSpellCheckerLanguages\nBy default the spellchecker will enable the language matching the current OS locale.
\nAll the required information to generate a context menu is provided in the context-menu event on each webContents instance. A small example of how to make a context menu with this information is provided below.
const { Menu, MenuItem } = require('electron')\n\nmyWindow.webContents.on('context-menu', (event, params) => {\n const menu = new Menu()\n\n // Add each spelling suggestion\n for (const suggestion of params.dictionarySuggestions) {\n menu.append(new MenuItem({\n label: suggestion,\n click: () => mainWindow.webContents.replaceMisspelling(suggestion)\n }))\n }\n\n // Allow users to add the misspelled word to the dictionary\n if (params.misspelledWord) {\n menu.append(\n new MenuItem({\n label: 'Add to dictionary',\n click: () => mainWindow.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord)\n })\n )\n }\n\n menu.popup()\n})\nAlthough the spellchecker itself does not send any typings, words or user input to Google services the hunspell dictionary files are downloaded from a Google CDN by default. If you want to avoid this you can provide an alternative URL to download the dictionaries from.
\nmyWindow.session.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/')\nConsultez la documentation de session.setSpellCheckerDictionaryDownloadURL pour plus d'informations sur l'endroit où obtenir les fichiers de dictionnaire et comment vous devez les héberger.
Ce sont les lignes directrices pour la rédaction de la documentation d'Electron.
\n# au début de la page.##.# de leur titre qui augmentent selon leur niveau d'imbrication.Utilisez Démarrage Rapide comme exemple :
# Démarrage rapide\n\n...\n\n## Processus principal\n\n...\n\n## Processus de rendu\n\n...\n\n## Lancez votre application\n\n...\n\n### Exécuter en tant que distribution\n\n...\n\n### Téléchargement manuel du binaire Electron\n\n...\nDans le cas de références de l'API, il existe des exceptions à cette règle.
\nCe dépôt utilise le paquet markdownlint pour imposer un style cohérent au Markdown. Pour les règles exactes, voir le fichier .markdownlint.json dans le dossier racine .
Quelques règles de style non couvertes par les règles de linter :
\n\nsh au lieu de cmd dans les blocs de code (en raison de l'outil de coloration syntaxique).js et javascript sont vérifiés avec le standard-markdown.Les règles suivantes s'appliquent uniquement à la documentation des APIs.
\nLa doc API de chaque module doit utiliser le nom réel de l'objet retourné par require('electron') comme titre (tel que BrowserWindow, autoUpdater ou session).
Directement sous le titre de la page, ajouter une ligne de description du module comme une citation markdown (commençant par >).
En prenant session comme exemple :
# session\n\n> Gère les sessions, les cookies, le cache, les paramètres de proxy, etc. du navigateur.\nPour les modules qui ne sont pas des classes, leurs méthodes et événements doivent figurer sous les chapitres ## Methods et ## Events.
En prenant autoUpdater comme exemple :
# autoUpdater\n\n## Events\n\n### Event: 'error'\n\n## Methods\n\n### `autoUpdater.setFeedURL(url[, requestHeaders])`\n## Class: TheClassName.###.### Méthodes Statiques.### Instance Methods chapter.[TYPE] - [Return description]\"Object, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.### Instance Events.### Instance Properties chapter.En prenant les classes Session et Cookies comme exemple :
# session\n\n## Méthodes\n\n### session.fromPartition(partition)\n\n## Propriétés Statiques\n\n### session.defaultSession\n\n## Classe : Session\n\n### Événements d'instance\n\n#### Événement : 'will-download'\n\n### Méthodes d'instance\n\n#### `ses.getCacheSize()`\n\n### Propriétés d'instance\n\n#### `ses.cookies`\n\n## Classe : Cookies\n\n### Méthodes d'instance\n\n#### `cookies.get(filter, callback)`\nLe chapitre sur les méthodes doit respecter la forme suivante :
\n### `objectName.methodName(required[, optional]))`\n\n* `required` String - A parameter description.\n* `optional` Integer (optional) - Another parameter description.\n\n...\nThe heading can be ### or ####-levels depending on whether the method belongs to a module or a class.
For modules, the objectName is the module's name. For classes, it must be the name of the instance of the class, and must not be the same as the module's name.
Par exemple, les méthodes de la classe Session sous le module session doivent utiliser ses pour le objectName.
Optional arguments are notated by square brackets [] surrounding the optional argument as well as the comma required if this optional argument follows another argument:
required[, optional]\nDes informations plus détaillées sur chacun des arguments sont notées dans une liste non ordonnée en dessous de la méthode. The type of argument is notated by either JavaScript primitives (e.g. String, Promise, or Object), a custom API structure like Electron's Cookie, or the wildcard any.
If the argument is of type Array, use [] shorthand with the type of value inside the array (for example,any[] or String[]).
If the argument is of type Promise, parametrize the type with what the promise resolves to (for example, Promise<void> or Promise<String>).
Si un argument peut être de plusieurs types, séparez les types par |.
La description des arguments de type Function devrait clairement expliquer comment il peut être appelé et lister les types des paramètres qui lui seront transmis.
Si un argument ou une méthode est propre à certaines plateformes, ces plateformes sont listés en italique après le type de données. Les valeurs peuvent être macOS, Windows ou Linux.
* `animate` Boolean (optional) _macOS_ _Windows_ - Animate the thing.\nLe chapitre sur les événements doit être sous la forme suivante :
\n### Event: 'wake-up'\n\nReturns:\n\n* `time` String\n\n...\nL'en-tête peut être de niveau ### ou #### selon que l'événement appartient à un module ou à une classe.
Les arguments d'un événement suivent les mêmes règles que les méthodes.
\nLe chapitre des propriétés doit être sous la forme suivante :
\n### session.defaultSession\n\n...\nL'en-tête peut être de niveau ### ou #### selon que la propriété appartient à un module ou à une classe.
Voir electron/i18n
", "title": "Règles de style pour la documentation d'Electron", "description": "" }, "/docs/tutorial/support": { "locale": "fr-FR", "slug": "support", "href": "/docs/tutorial/support", "crowdinFileId": "256253", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/support.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Si vous avez un problème de sécurité, veuillez consulter le document sur la sécurité.
\nSi vous avez besoin d’aide pour la programmation, de réponses à vos questions, ou pour rejoindre une discussion avec d’autres développeurs qui utilisent Electron, vous pouvez interagir avec la Communauté à ces adresses :
\nElectron's Discord:electronelectron-ru (Russe)electron-br (Brézilien Portugais)electron-kr (Coréen)electron-jp (Japonais)electron-tr (Turque)electron-id (Indonésien)electron-pl (Polonais)Si vous souhaitez contribuer sur Electron, lisez le document de contribution.
\nSi vous découvrez une erreur dans une version supportée d'Electron, veuillez s’il vous plaît la signaler dans notre suivi d'erreurs.
\nawesome-electron regroupe une liste d'exemples d'applications, d'outils et de ressources très utiles, maintenue par la Communauté.
\nNote: Beginning in September 2021 with Electron 15, the Electron team will temporarily support the latest four stable major versions. This extended support is intended to help Electron developers transition to the new eight week release cadence, and will continue until May 2022, with the release of Electron 19. At that time, the Electron team will drop support back to the latest three stable major versions.
\nLes trois dernières versions majeures stables sont prises en charge par l'équipe Electron. For example, if the latest release is 6.1.x, then the 5.0.x as well as the 4.2.x series are supported. We only support the latest minor release for each stable release series. This means that in the case of a security fix 6.1.x will receive the fix, but we will not release a new version of 6.0.x.
\nThe latest stable release unilaterally receives all fixes from main, and the version prior to that receives the vast majority of those fixes as time and bandwidth warrants. The oldest supported release line will receive only security fixes directly.
All supported release lines will accept external pull requests to backport fixes previously merged to main, though this may be on a case-by-case basis for some older supported lines. All contested decisions around release line backports will be resolved by the Releases Working Group as an agenda item at their weekly meeting the week the backport PR is raised.
When an API is changed or removed in a way that breaks existing functionality, the previous functionality will be supported for a minimum of two major versions when possible before being removed. For example, if a function takes three arguments, and that number is reduced to two in major version 10, the three-argument version would continue to work until, at minimum, major version 12. Past the minimum two-version threshold, we will attempt to support backwards compatibility beyond two versions until the maintainers feel the maintenance burden is too high to continue doing so.
\nQuand une branche de version arrive au terme de son cycle de support, les révisions associées sont rendues obsolètes dans NPM et une toute dernière révision de fin de support est mise à disposition. Cette révision signalera alors que la version d'Electron utilisée n'est plus supportée.
\nCes étapes permettent aux développeurs d'applications d'être informés que la branche qu'ils utilisent ne sera bientôt plus supportée, sans toutefois trop importuner l'utilisateur final.
\nSi, pour une raison exceptionnelle, une application nécessite de rester sur une version d'Electron qui n'est plus supportée, les développeurs peuvent désactiver l'avertissement de fin de support en omettant d'ajouter dans la collection devDependencies du fichier package.json la dernière révision de fin de support. Par exemple, comme la version 1.6 est clôturée par la révision de fin de support 1.6.18, les développeurs pourraient choisir de continuer à l'utiliser sans message d'avertissement en précisant, dans devDependency, \"electron\": 1.6.0 - 1.6.17.
Les plateformes suivantes sont prises en charge par Electron :
\nSeul les binaires 64bit sont fournit pour macOs, et la version minimale de macOs supportée est macOS 10.11 (El Capitan).
\nLe support natif des appareils Apple Silicon (arm64) a été ajouté dans Electron 11.0.0.
Windows 7 et versions ultérieures sont pris en charge, les systèmes d’exploitation plus anciens ne sont pas pris en charge (et ne fonctionnent pas).
\nLes deux binaires ia32 (x86) et x64 (amd64) sont fournit pour Windows. Le support natif pour Windows sur les appareils Arm (arm64) a été ajouté dans Electron 6.0.8.. Running apps packaged with previous versions is possible using the ia32 binary.
Les binaires prédéfinis d'Electron sont construits sur Ubuntu 18.04.
\nLe fait qu'un binaire pré-compilé peut ou non s'exécuter sur une distribution dépend si la distribution inclut ou non les librairies qu'Electron utilise pour compiler l'application. Du coup, seulement Ubuntu 18.04 est garanti de fonctionner, ainsi que les distributions suivantes pour faire fonctionner les binaires pré-compilés d'Electron :
\n\n\nComment utiliser les APIs de Nodejs et d'Electron.
\n
Tous les modules intégrés de Node.js sont disponibles dans Electron, ainsi que les modules tiers pour node sont totalement supportés (incluant les modules natifs).
\nElectron fournit également quelques modules supplémentaires intégrés pour le développement d'application de bureau natives. Some modules are only available in the main process, some are only available in the renderer process (web page), and some can be used in either process type.
\nLa règle de base est : si un module est une GUI ou un système de bas niveau est associé, il devrait être disponible dans le processus main. You need to be familiar with the concept of main process vs. renderer process scripts to be able to use those modules.
\nLe script <0>main process</0> ressemble à script Node.js normal :
\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL('https://github.com')\n})\nThe renderer process is no different than a normal web page, except for the extra ability to use node modules if nodeIntegration is enabled:
\n<html>\n<body>\n<script>\n const fs = require('fs')\n console.log(fs.readFileSync(__filename, 'utf8'))\n</script>\n</body>\n</html>\nÀ partir de la 0.37, vous pouvez utiliser l'affectation par décomposition pour rendre l'utilisation des modules intégrés plus simple.
\nconst { app, BrowserWindow } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nSi vous avez besoin la totalité du module electron, vous pouvez faire un require et décomposer ensuite le tout pour accéder aux modules venant d'electron individuellement.
const electron = require('electron')\nconst { app, BrowserWindow } = electron\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nCe qui est équivalent au code suivant :
\nconst electron = require('electron')\nconst app = electron.app\nconst BrowserWindow = electron.BrowserWindow\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\n\n\nRécuperer les préférences système.
\n
Processus : Main
\nconst { systemPreferences } = require('electron')\nconsole.log(systemPreferences.isDarkMode())\nL'objet systemPreferences émet les événements suivants :
Retourne :
\nevent EventnewColor String - La nouvelle couleur RGBA que l'utilisateur à assigné à son système.Retourne :
\nevent EventRetourne :
\nevent EventinvertedColorScheme Boolean - true si un schéma de couleur inversé (un schéma de couleur à contraste élevé avec le texte clair et les fonds sombres) est utilisé, faux sinon.Déprécié : Doit utiliser le nouvel événement mis à jour sur le module nativeTheme.
Retourne :
\nevent EventhighContrastColorScheme Boolean - true si un thème à contraste élevé est utilisé, false sinon.Déprécié : Doit utiliser le nouvel événement mis à jour sur le module nativeTheme.
systemPreferences.isDarkMode() macOS Windows DépréciéRetourne Boolean - Si le système est en mode sombre.
Déprécié : Doit utiliser le nouveau nativeTheme.shouldUseDarkColors API.
systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOSRetourne Boolean - Si l'option Swipe entre les pages est activé.
systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOSevent StringuserInfo<String, any>deliverImmédiately Booléen (facultatif) - true pour publier des notifications immédiatement même lorsque l'application d'abonnement est inactive.Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postLocalNotification(event, userInfo) macOSevent StringuserInfo<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postWorkspaceNotification(event, userInfo) macOSevent StringuserInfo<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.subscribeNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo<String, unknown>objetRetourne Nombre - L'ID de cet abonnement
S'abonne aux notifications natives de macOS, callback sera appelé avec callback(event, userInfo) lorsque le event correspondant se produit. userInfo est un objet qui contient le dictionnaire d'information utilisateur envoyé avec la notification. L'objet object est l'expéditeur de la notification, et ne supporte que les valeurs NSString pour le moment.
Le id de l'abonné est retourné, qui peut être utilisé pour désabonner le événement.
Sous le capot, cette API s'abonne à NSDistributedNotificationCenter, Les valeurs d'exemple de event sont :
AppleInterfaceThemeChangedNotificationAppleAquaColorVariantChangedAppleColorPreferencesChangedNotificationAppleShowScrollBarsSettingChangedsystemPreferences.subscribeLocalNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo<String, unknown>objetRetourne Nombre - L'ID de cet abonnement
Same as subscribeNotification, but uses NSNotificationCenter for local defaults. Ceci est nécessaire pour des événements tels que NSUserDefaultsDidChangeNotification.
systemPreferences.subscribeWorkspaceNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo<String, unknown>objetRetourne Nombre - L'ID de cet abonnement
Identique à subscribeNotification, mais utilise NSWorkspace.sharedWorkspace.notificationCenter. Ceci est nécessaire pour des événements tels que NSWorkspaceDidActivateApplicationNotification.
systemPreferences.unsubscribeNotification(id) macOSid IntegerSupprime l'abonnement avec l'id.
systemPreferences.unsubscribeLocalNotification(id) macOSid IntegerIdentique à unsubscribeNotification, mais supprime l'abonné de NSNotificationCenter.
systemPreferences.unsubscribeWorkspaceNotification(id) macOSid IntegerIdentique à unsubscribeNotification, mais supprime l'abonné de NSWorkspace.sharedWorkspace.notificationCenter.
systemPreferences.registerDefaults(defaults) macOSPar défaut Enregistrement<String, String | Boolean | Number> - un dictionnaire de (clé: valeur) par défaut de l'utilisateurAjoute les valeurs par défaut à NSUserDefaultsde votre application.
systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOSkey Stringtype Type - Can be string, boolean, integer, float, double, url, array or dictionary.Returns UserDefaultTypes[Type] - The value of key in NSUserDefaults.
Certaines clé populaires et types sont:
AppleInterfaceStyle: chaîneAppleAquaColorVariant: integerAppleHighlightColor: chaîneAppleShowScrollBars: stringNSNavRecentPlaces: tableauNSPreferredWebServices: dictionnaireNSUserDictionaryReplacementItems: tableausystemPreferences.setUserDefault(key, type, value) macOSkey Stringtype String - Can be string, boolean, integer, float, double, url, array or dictionary.value StringDéfinit la valeur de clé dans NSUserDefaults.
Note that type should match actual type of value. An exception is thrown if they don't.
Certaines clé populaires et types sont:
ApplePressAndHoldEnabled : booléensystemPreferences.removeUserDefault(key) macOSkey StringRemoves the key in NSUserDefaults. This can be used to restore the default or global value of a key previously set with setUserDefault.
systemPreferences.isAeroGlassEnabled() WindowsRetourne Boolean - true si la composition DWM (Aero Glass) est activée, et false sinon.
Un exemple d'utilisation pour déterminer si vous devez créer une fenêtre transparente ou non (les fenêtres transparentes ne fonctionneront pas correctement lorsque la composition DWM est désactivée) :
\nconst { BrowserWindow, systemPreferences } = require('electron')\nconst browserOptions = { width: 1000, height: 800 }\n\n// Make the window transparent only if the platform supports it.\nif (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {\n browserOptions.transparent = true\n browserOptions.frame = false\n}\n\n// Create the window.\nconst win = new BrowserWindow(browserOptions)\n\n// Navigate.\nif (browserOptions.transparent) {\n win.loadURL(`file://${__dirname}/index.html`)\n} else {\n // Pas de transparence, donc nous chargeons un repli qui utilise des styles de base.\n win.loadURL(`file://${__dirname}/fallback.html`)\n}\nsystemPreferences.getAccentColor() Windows macOSRetourne String - Les utilisateurs du système actuel de préférence de couleur d'accentuation large en RGBA forme hexadécimale.
const color = systemPreferences.getAccentColor() // `\"aabbccdd\"`\nconst red = color.substr(0, 2) // \"aa\"\nconst green = color.substr(2, 2) // \"bb\"\nconst blue = color.substr(4, 2) // \"cc\"\nconst alpha = color.substr(6, 2) // \"dd\"\nCette API n'est disponible que sur macOS 10.14 Mojave ou plus récent.
\nsystemPreferences.getColor(color) Windows macOScolor String - One of the following values:3d-dark-shadow - Ombre noir pour les éléments affichés en trois dimensions.3d-face - Couleur de la face pour les éléments affichés en trois dimensions et le fond des boîtes de dialogue.3d-hihlight - Couleur de surlignage pour les éléments affichés en trois dimensions.3d-light - Couleur de la lumière pour les éléments affichés en trois dimensions.3d-shadow - Couleur d'ombre pour les éléments affichés en trois dimensions.active-border - Bordure de la fenêtre active.active-caption - Active window title bar. Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.active-caption-gradient - Couleur du côté droit du dégradé de couleur de la barre de titre de la fenêtre active.app-workspace - Couleur de fond d'une interface d'application de document multiple (MDI).button-text - Texte sur les boutons d'envoi.caption-text - Texte dans une légende, boîte de dimensions, boîte avec la flèche pour la barre de défilement.desktop - Couleur de fond du bureau.disabled-text - Texte grisé (désactivé).highlight - Élément(s) sélectionné(s) dans un groupe.highlight-text - Texte des éléments sélectionnés dans un contrôle.hotlight - Couleur pour un lien hypertexte ou un élément à suivre.inactive-border - Bordure de fenêtre inactive.inactive-caption - Inactive window caption. Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.inactive-caption-gradient - Couleur du côté droit dans le gradient de couleur d'une barre de titre de la fenêtre inactive.inactive-caption-text - Color of text in an inactive caption.info-background - Background color for tooltip controls.info-text - Text color for tooltip controls.menu - Menu background.menu-highlight - The color used to highlight menu items when the menu appears as a flat menu.menubar - La couleur de fond de la barre de menu lorsque les menus apparaissent sous la forme de menus plats.menu-text - Texte dans les menus.scrollbar - Zone grise de la barre de défilement.window - Fond de la fenêtre.window-frame - Cadre de fenêtres.window-text - Texte dans windows.alternate-selected-control-text - Le texte sur une surface sélectionnée dans une liste ou un tableau. dépréciécontrol-background - L'arrière-plan d'un élément de grande interface, tel qu'un navigateur ou un tableau.control - La surface d'un contrôle.control-text -Le texte d'un contrôle qui n'est pas désactivé.disabled-control-text - Le texte d'un contrôle qui est désactivé.find-highlight - La couleur d'un indicateur de recherche.grille - Les lignes de grilles d'un élément d'interface comme une table.header-text - Le texte d'une cellule d'en-tête dans un tableau.surlignement - La source de lumière virtuelle à l'écran.keyboard-focus-indicator - L'anneau qui apparaît autour du contrôle actuellement focalisé lors de l'utilisation du clavier pour la navigation de l'interface.label - Le texte d'une étiquette contenant le contenu principal.lien - Un lien vers un autre contenu.placeholder-text - Une chaîne de caractères dans une vue de contrôle ou de texte.quaternary-label - Le texte d'une étiquette de moindre importance qu'une étiquette tertiaire telle que le texte du filigrane.scrubber-textured-background - L'arrière-plan d'un scrubber dans la barre tactile.étiquette secondaire - Le texte d'une étiquette de moindre importance qu'une étiquette normale telle qu'une étiquette utilisée pour représenter une sous-rubrique ou des informations complémentaires.selected-content-background - L'arrière-plan du contenu sélectionné dans une fenêtre ou une vue clé.selected-control - La surface d'une commande sélectionnée.selected-control-text - Le texte d'une commande sélectionnée.selected-menu-item-text - Le texte d'un menu sélectionné.selected-text-background - L'arrière-plan du texte sélectionné.texte sélectionné - Texte sélectionné.Séparateur - Un séparateur entre différentes sections de contenu.shadow - L'ombre virtuelle projetée par un objet levé à l'écran.étiquette-tertiaire - Le texte d'une étiquette de moindre importance qu'une étiquette secondaire telle qu'une étiquette utilisée pour représenter le texte désactivé.text-background - Fond d'écran du texte.text - Le texte dans un document.sous-page-background - L'arrière-plan derrière le contenu d'un document.unemphaszed-selected-content-background - Le contenu sélectionné dans une fenêtre ou une vue non-clé.unemphaszed-selected-text-background - Un fond pour le texte sélectionné dans une fenêtre ou une vue non-clé.unemphaszed-selected-text - Texte sélectionné dans une fenêtre ou une vue non-clé.window-background - L'arrière-plan d'une fenêtre.window-frame-text - Le texte dans la barre de titre de la fenêtre.Retourne String - Le paramètre de couleur système sous forme hexadécimale RVB (#ABCDEF). See the Windows docs and the macOS docs for more details.
The following colors are only available on macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, and unemphasized-selected-text.
systemPreferences.getSystemColor(color) macOScolor String - One of the following values:bleumarrongrisvertorangerosevioletrougejauneReturns String - The standard system color formatted as #RRGGBBAA.
Returns one of several standard system colors that automatically adapt to vibrancy and changes in accessibility settings like 'Increase contrast' and 'Reduce transparency'. See Apple Documentation for more details.
\nsystemPreferences.isInvertedColorScheme() Windows DépréciéReturns Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is active, false otherwise.
Déprécié : Doit utiliser le nouveau nativeTheme.shouldUseInvertedColorScheme API.
systemPreferences.isHighContrastColorScheme() macOS Windows DépréciéReturns Boolean - true if a high contrast theme is active, false otherwise.
Déprécié : Doit utiliser le nouveau nativeTheme.shouldUseHighContrastColors API.
systemPreferences.getEffectiveAppearance() macOSReturns String - Can be dark, light or unknown.
Gets the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance
\nsystemPreferences.getAppLevelAppearance() macOS DépréciéReturns String | null - Can be dark, light or unknown.
Gets the macOS appearance setting that you have declared you want for your application, maps to NSApplication.appearance. You can use the setAppLevelAppearance API to set this value.
systemPreferences.setAppLevelAppearance(appearance) macOS Dépréciéappearance String | null - Can be dark or lightSets the appearance setting for your application, this should override the system default and override the value of getEffectiveAppearance.
systemPreferences.canPromptTouchID() macOSReturns Boolean - whether or not this device has the ability to use Touch ID.
NOTE: This API will return false on macOS systems older than Sierra 10.12.2.
systemPreferences.promptTouchID(reason) macOSreason String - The reason you are asking for Touch ID authenticationReturns Promise<void> - resolves if the user has successfully authenticated with Touch ID.
const { systemPreferences } = require('electron')\n\nsystemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {\n console.log('You have successfully authenticated with Touch ID!')\n}).catch(err => {\n console.log(err)\n})\nThis API itself will not protect your user data; rather, it is a mechanism to allow you to do so. Native apps will need to set Access Control Constants like kSecAccessControlUserPresence on their keychain entry so that reading it would auto-prompt for Touch ID biometric consent. This could be done with node-keytar, such that one would store an encryption key with node-keytar and only fetch it if promptTouchID() resolves.
NOTE: This API will return a rejected Promise on macOS systems older than Sierra 10.12.2.
\nsystemPreferences.isTrustedAccessibilityClient(prompt) macOSprompt Boolean - whether or not the user will be informed via prompt if the current process is untrusted.Returns Boolean - true if the current process is a trusted accessibility client and false if it is not.
systemPreferences.getMediaAccessStatus(mediaType) Windows macOSmediaType String -Peut être microphone, camera ou screen.Returns String - Can be not-determined, granted, denied, restricted or unknown.
This user consent was not required on macOS 10.13 High Sierra or lower so this method will always return granted. macOS 10.14 Mojave or higher requires consent for microphone and camera access. macOS 10.15 Catalina or higher requires consent for screen access.
Windows 10 has a global setting controlling microphone and camera access for all win32 applications. It will always return granted for screen and for all media types on older versions of Windows.
systemPreferences.askForMediaAccess(mediaType) macOSmediaType String - the type of media being requested; can be microphone, camera.Returns Promise<Boolean> - A promise that resolves with true if consent was granted and false if it was denied. If an invalid mediaType is passed, the promise will be rejected. If an access request was denied and later is changed through the System Preferences pane, a restart of the app will be required for the new permissions to take effect. If access has already been requested and denied, it must be changed through the preference pane; an alert will not pop up and the promise will resolve with the existing access status.
Important: In order to properly leverage this API, you must set the NSMicrophoneUsageDescription and NSCameraUsageDescription strings in your app's Info.plist file. Les valeurs de ces clés seront utilisées pour remplir les boîtes de dialogue des permissions afin que l'utilisateur soit correctement informé du but de la demande de permission. Voir Electron Application Distribution pour plus d'informations sur la façon de les définir dans le contexte d'Electron.
Ce consentement de l'utilisateur n'était pas requis avant macOS 10. 4 Mojave, donc cette méthode retournera toujours true si votre système fonctionne 10.13 Haute Sierra ou moins.
systemPreferences.getAnimationSettings()Retourne Object:
shouldRenderRichAnimation Boolean - Renvoie vrai si les animations riches doivent être rendues. Regarde le type de session (par exemple, bureau distant) et les paramètres d'accessibilité pour donner des conseils pour les animations lourdes.scrollAnimationsEnabledBySystem Boolean - Détermine par plate-forme si les animations de défilement (par exemple produites par la touche maison/fin) doivent être activées.prefersReducedMotion Booléen - Détermine si l'utilisateur souhaite des mouvements réduits basés sur des API de plate-forme.Retourne un objet avec les paramètres d'animation du système.
\nsystemPreferences.appLevelApparence macOSUne propriété String qui peut être dark, light ou unknown. Il détermine le paramètre d'apparence macOS pour votre application. Cette correspondance aux valeurs dans: NSApplication.appearance. Définir ceci remplacera la valeur par défaut du système ainsi que la valeur de getEffectiveAppearance.
Les valeurs possibles qui peuvent être définies sont dark et light, et les valeurs de retour possibles sont dark, light, et unknown.
Cette propriété n'est disponible que sur macOS 10.14 Mojave ou plus récent.
\nsystemPreferences.effectiveAppearance macOS ReadonlyUne propriété String qui peut être dark, light ou unknown.
Retourne le paramètre d'apparence macOS qui est actuellement appliqué à votre application, correspond à NSApplication.effectiveAppearance
", "title": "systemPreferences", "description": "Récuperer les préférences système." }, "/docs/api/structures/task": { "locale": "fr-FR", "slug": "task", "href": "/docs/api/structures/task", "crowdinFileId": "256513", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/task.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "program String - Path of the program to execute, usually you should specify process.execPath which opens the current program.arguments String - The command line arguments when program is executed.title String - The string to be displayed in a JumpList.description String - Description of this task.iconPath String - The absolute path to an icon to be displayed in a JumpList, which can be an arbitrary resource file that contains an icon. You can usually specify process.execPath to show the icon of the program.iconIndex Number - The icon index in the icon file. If an icon file consists of two or more icons, set this value to identify the icon. If an icon file consists of one icon, this value is 0.workingDirectory String (optional) - The working directory. Default is empty.Notre essayons de garder une couverture de code élevée pour Electron. Nous demandons à ce que toutes les demandes de \"pull\" passent tout les tests existants, mais ajoutent aussi des tests couvrant les changements de codes et les nouveaux scénarios. Cela nous assure ainsi que nous intégrons le plus de code possible tout en étant sûr que Electron soit livré avec le moins de bugs possible.
\nCe dépôt utilise des règles de qualité de code pour JavaScript et C++ ainsi que des tests unitaires et d'intégrations. Pour en apprendre plus sur le style de code d'Electron, référez-vous au document style de code.
\nTo ensure that your JavaScript is in compliance with the Electron coding style, run npm run lint-js, which will run standard against both Electron itself as well as the unit tests. If you are using an editor with a plugin/addon system, you might want to use one of the many StandardJS addons to be informed of coding style violations before you ever commit them.
To run standard with parameters, run npm run lint-js -- followed by arguments you want passed to standard.
To ensure that your C++ is in compliance with the Electron coding style, run npm run lint-cpp, which runs a cpplint script. We recommend that you use clang-format and prepared a short tutorial.
There is not a lot of Python in this repository, but it too is governed by coding style rules. npm run lint-py will check all Python, using pylint to do so.
If you are not using build-tools, ensure that that name you have configured for your local build of Electron is one of Testing, Release, Default, Debug, or you have set process.env.ELECTRON_OUT_DIR. Without these set, Electron will fail to perform some pre-testing steps.
To run all unit tests, run npm run test. The unit tests are an Electron app (surprise!) that can be found in the spec folder. Note that it has its own package.json and that its dependencies are therefore not defined in the top-level package.json.
To run only specific tests matching a pattern, run npm run test -- -g=PATTERN, replacing the PATTERN with a regex that matches the tests you would like to run. As an example: If you want to run only IPC tests, you would run npm run test -- -g ipc.
Visual Studio 2019 must be installed.
\nNode headers have to be compiled for your configuration.
\nninja -C out\\Testing third_party\\electron_node:headers\nThe electron.lib has to be copied as node.lib.
\ncd out\\Testing\nmkdir gen\\node_headers\\Release\ncopy electron.lib gen\\node_headers\\Release\\node.lib\nSome Windows 10 devices do not ship with the Meiryo font installed, which may cause a font fallback test to fail. To install Meiryo:
\nSome tests which rely on precise pixel measurements may not work correctly on devices with Hi-DPI screen settings due to floating point precision errors. To run these tests correctly, make sure the device is set to 100% scaling.
\nTo configure display scaling:
\nÉtant basé sur Chromium, Electron requiert un pilote d’affichage de la fonction. Si Chromium ne peut pas trouver un pilote d’affichage, Electron échouera tout simplement au lancement - et par conséquent, n'exécutera aucun de vos tests, peu importe comment vous les exécutez. Tester les applications Electron sur Travis, Circle, Jenkins ou systèmes similaires exige donc un peu de configuration. En substance, nous devons utiliser un pilote d’affichage virtuel.
\nTout d’abord, installez Xvfb. C’est un framebuffer virtuel, mettant en oeuvre le protocole du serveur d'affichage X11 - il effectue toutes les opérations graphiques en mémoire sans montrer n’importe quel sortie à l'écran, c'est exactement ce dont nous avons besoin.
\nEnsuite, créez un écran virtuel Xvfb et exportez une variable d'environnement appelée DISPLAY qui pointe vers elle. Chromium dans Electron va automatiquement chercher pour $DISPLAY, donc aucune configuration supplémentaire de votre application n’est nécessaire. Cette étape peut être automatisée avec Anaïs Betts xvfb-peut-être : Préfixer vos commandes de test avec xvfb-maybe et le petit outil configurera automatiquement Xvfb, si requis par le système actuel. Sous Windows ou macOS, il ne se passera rien.
## Sous Windows ou macOS, electron-mocha est invoque\n## Sous Linux, si on est dans un environement headless, cela reviendra \n## à xvfb-run electron-mocha ./test/*.js \nxvfb-maybe electron-mocha ./test/*.js\nSur Travis, votre .travis.yml devrait ressembler à peu près à ça :
addons:\n apt:\n packages:\n - xvfb\n\ninstall:\n - export DISPLAY=':99.0'\n - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &\nPour Jenkins, un plugin Xvfb est disponible.
\nCircle CI est génial et a Xvfb et $DISPLAY déjà configuré, donc aucune nouvelle configuration n'est nécessaire.
AppVeyor s'exécute sur Windows, supportant Selenium, Chromium, Electron et outils similaires - aucune configuration n’est requise.
", "title": "Tests sur les systèmes CI Headless (Travis CI, Jenkins)", "description": "" }, "/docs/tutorial/testing-widevine-cdm": { "locale": "fr-FR", "slug": "testing-widevine-cdm", "href": "/docs/tutorial/testing-widevine-cdm", "crowdinFileId": "256257", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/testing-widevine-cdm.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Dans Electron, vous pouvez utiliser le plugin Widevine CDM livré avec le navigateur Chrome.
\nWidevine Content Decryption Modules (CDMs) are how streaming services protect content using HTML5 video to web browsers without relying on an NPAPI plugin like Flash or Silverlight. Widevine support is an alternative solution for streaming services that currently rely on Silverlight for playback of DRM-protected video content. It will allow websites to show DRM-protected video content in Firefox without the use of NPAPI plugins. The Widevine CDM runs in an open-source CDM sandbox providing better user security than NPAPI plugins.
\nAs of Electron v1.8.0 (Chrome v59), the below steps are may only be some of the necessary steps to enable Widevine; any app on or after that version intending to use the Widevine CDM may need to be signed using a license obtained from Widevine itself.
Per Widevine:
\n\n\nChrome 59 (and later) includes support for Verified Media Path (VMP). VMP provides a method to verify the authenticity of a device platform. For browser deployments, this will provide an additional signal to determine if a browser-based implementation is reliable and secure.
\nThe proxy integration guide has been updated with information about VMP and how to issue licenses.
\nWidevine recommends our browser-based integrations (vendors and browser-based applications) add support for VMP.
\n
Pour activer la lecture vidéo avec cette nouvelle restriction, castLabs a créé un fork qui a implémenté les modifications nécessaires pour permettre la lecture de Widevine dans une application Electron si on a obtenu les licences nécessaires de widevine.
\nOpen chrome://components/ in Chrome browser, find Widevine Content Decryption Module and make sure it is up to date, then you can find the library files from the application directory.
Le fichier de bibliothèque widevinecdm.dll sera sous Program Files(x86)/Google/Chrome/Application/CHROME_VERSION/WidevineCdm/_platform_specific/win_(x86|x64)/ dossier
Le fichier de bibliothèque libwidevinecdm.dylib sera sous /Applications/Google Chrome.app/Contents/Versions/CHROME_VERSION/Google Chrome Framework.framework/Versions/A/Libraries/WidevineCdm/_platform_specific/mac_(x86|x64)/ dossier
Remarque:Assurez-vous que la version chromée utilisée par Electron est supérieure ou égale à la valeur min_chrome_version du composant CDM Widevine de Chrome. The value can be found in manifest.json under WidevineCdm directory.
After getting the library files, you should pass the path to the file with --widevine-cdm-path command line switch, and the library's version with --widevine-cdm-version switch. The command line switches have to be passed before the ready event of app module gets emitted.
Exemple de code :
\nconst { app, BrowserWindow } = require('electron')\n\n// You have to pass the directory that contains widevine library here, it is\n// * `libwidevinecdm.dylib` on macOS,\n// * `widevinecdm.dll` on Windows.\napp.commandLine.appendSwitch('widevine-cdm-path', '/path/to/widevine_library')\n// The version of plugin can be got from `chrome://components` page in Chrome.\napp.commandLine.appendSwitch('widevine-cdm-version', '1.4.8.866')\n\nlet win = null\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.show()\n})\nPour vérifier si Widevine fonctionne, vous pouvez utiliser les méthodes suivantes:
\nWidevine.bitdash uses Widevine in your browser, puis lancez la vidéo.icon NativeImage - The icon showing in thumbnail toolbar.click Functiontooltip String (optional) - The text of the button's tooltip.flags String - Control specific states and behaviors of the button. By default, it is ['enabled'].The flags is an array that can include following Strings:
enabled - The button is active and available to the user.disabled - The button is disabled. It is present, but has a visual state indicating it will not respond to user action.dismissonclick - When the button is clicked, the thumbnail window closes immediately.nobackground - Do not draw a button border, use only the image.hidden - The button is not shown to the user.noninteractive - The button is enabled but not interactive; no pressed button state is drawn. This value is intended for instances where the button is used in a notification.\n\nCréer une disposition TouchBar pour les applications natives macOS
\n
Processus : Main
\nnew TouchBar(options)optionsitems (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer)escapeItem (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer | null) (optional)Creates a new touch bar with the specified items. Use BrowserWindow.setTouchBar to add the TouchBar to a window.
Remarque : L’API TouchBar est actuellement expérimentale et peut changer ou être supprimée dans les futures mises à jour d'Electron.
\nTip: If you don't have a MacBook with Touch Bar, you can use Touch Bar Simulator to test Touch Bar usage in your app.
\nTouchBarButtonA typeof TouchBarButton reference to the TouchBarButton class.
TouchBarColorPickerA typeof TouchBarColorPicker reference to the TouchBarColorPicker class.
TouchBarGroupA typeof TouchBarGroup reference to the TouchBarGroup class.
TouchBarLabelA typeof TouchBarLabel reference to the TouchBarLabel class.
TouchBarPopoverA typeof TouchBarPopover reference to the TouchBarPopover class.
TouchBarScrubberA typeof TouchBarScrubber reference to the TouchBarScrubber class.
TouchBarSegmentedControlA typeof TouchBarSegmentedControl reference to the TouchBarSegmentedControl class.
TouchBarSliderA typeof TouchBarSlider reference to the TouchBarSlider class.
TouchBarSpacerA typeof TouchBarSpacer reference to the TouchBarSpacer class.
TouchBarOtherItemsProxyA typeof TouchBarOtherItemsProxy reference to the TouchBarOtherItemsProxy class.
Les propriétés suivantes sont disponibles pour les instances de TouchBar :
touchBar.escapeItemA TouchBarItem that will replace the \"esc\" button on the touch bar when set. Le définir à null restaurera le bouton \"esc\". Changer cette valeur immédiatement met à jour le bouton \"esc\" dans la touch bar.
Voici un exemple d’un jeu de machine à sous dans la touch bar avec un bouton et quelques labels.
\nconst { app, BrowserWindow, TouchBar } = require('electron')\n\nconst { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar\n\nlet spinning = false\n\n// Reel labels\nconst reel1 = new TouchBarLabel()\nconst reel2 = new TouchBarLabel()\nconst reel3 = new TouchBarLabel()\n\n// Spin result label\nconst result = new TouchBarLabel()\n\n// Spin button\nconst spin = new TouchBarButton({\n label: '🎰 Spin',\n backgroundColor: '#7851A9',\n click: () => {\n // Ignore clicks if already spinning\n if (spinning) {\n return\n }\n\n spinning = true\n result.label = ''\n\n let timeout = 10\n const spinLength = 4 * 1000 // 4 seconds\n const startTime = Date.now()\n\n const spinReels = () => {\n updateReels()\n\n if ((Date.now() - startTime) >= spinLength) {\n finishSpin()\n } else {\n // Slow down a bit on each spin\n timeout *= 1.1\n setTimeout(spinReels, timeout)\n }\n }\n\n spinReels()\n }\n})\n\nconst getRandomValue = () => {\n const values = ['🍒', '💎', '7️⃣', '🍊', '🔔', '⭐', '🍇', '🍀']\n return values[Math.floor(Math.random() * values.length)]\n}\n\nconst updateReels = () => {\n reel1.label = getRandomValue()\n reel2.label = getRandomValue()\n reel3.label = getRandomValue()\n}\n\nconst finishSpin = () => {\n const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size\n if (uniqueValues === 1) {\n // All 3 values are the same\n result.label = '💰 Jackpot!'\n result.textColor = '#FDFF00'\n } else if (uniqueValues === 2) {\n // 2 values are the same\n result.label = '😍 Winner!'\n result.textColor = '#FDFF00'\n } else {\n // No values are the same\n result.label = '🙁 Spin Again'\n result.textColor = null\n }\n spinning = false\n}\n\nconst touchBar = new TouchBar({\n items: [\n spin,\n new TouchBarSpacer({ size: 'large' }),\n reel1,\n new TouchBarSpacer({ size: 'small' }),\n reel2,\n new TouchBarSpacer({ size: 'small' }),\n reel3,\n new TouchBarSpacer({ size: 'large' }),\n result\n ]\n})\n\nlet window\n\napp.whenReady().then(() => {\n window = new BrowserWindow({\n frame: false,\n titleBarStyle: 'hiddenInset',\n width: 200,\n height: 200,\n backgroundColor: '#000'\n })\n window.loadURL('about:blank')\n window.setTouchBar(touchBar)\n})\nPour exécuter l’exemple ci-dessus, vous devrez (en supposant que vous avez un terminal ouvert dans le répertoire où vous souhaitez exécuter l’exemple) :
\ntouchbar.jsnpm install electron./node_modules/.bin/electron touchbar.jsVous devriez alors voir une nouvelle fenêtre Electron et l’application en cours d’exécution dans votre touch bar (ou touch bar emulator).
", "title": "TouchBar", "description": "Créer une disposition TouchBar pour les applications natives macOS" }, "/docs/api/touch-bar-button": { "locale": "fr-FR", "slug": "touch-bar-button", "href": "/docs/api/touch-bar-button", "crowdinFileId": "256375", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/touch-bar-button.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCréer un bouton dans la touch bar pour les applications native macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarButton(options)optionslabel String (facultatif) - Texte du bouton.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.backgroundColor String (facultatif) - Couleur de fond hexadécimal du bouton, c.-à-d. #ABCDEF.icon NativeImage | String(facultatif) - Icône du bouton.iconPosition String (facultatif) -Peut être left, right ou overlay. Par défaut, overlay.click Function (facultatif) - Fonction à appeler lorsque le bouton est cliqué.enabled Boolean (optional) - Whether the button is in an enabled state. La valeur par défaut est vraie.When defining accessibilityLabel, ensure you have considered macOS best practices.
Les propriétés suivantes sont disponibles pour les instances de TouchBarButton :
touchBarButton.accessibilityLabelA String representing the description of the button to be read by a screen reader. Will only be read by screen readers if no label is set.
touchBarButton.labelA String representing the button's current text. Changing this value immediately updates the button in the touch bar.
touchBarButton.backgroundColorA String hex code representing the button's current background color. Changing this value immediately updates the button in the touch bar.
touchBarButton.iconA NativeImage representing the button's current icon. Changing this value immediately updates the button in the touch bar.
touchBarButton.iconPositionA String - Can be left, right or overlay. Par défaut, overlay.
touchBarButton.enabledA Boolean representing whether the button is in an enabled state.
\n\nCréer un sélecteur de couleur dans la touch bar pour les applications native macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarColorPicker(options)optionsavailableColors String - Tableau de chaîne de caractères de couleurs en hexadécimal pouvant être choisi.selectedColor String (facultatif) - La couleur en hexadécimal selectionné dans le sélecteur, c.-à-d. #ABCDEF.change Function (optional) - Function to call when a color is selected.color String - La couleur que l'utilisateur a sélectionnée dans le sélecteur.Les propriétés suivantes sont disponibles pour les instances de TouchBarColorPicker :
touchBarColorPicker.availableColorsA String[] array representing the color picker's available colors to select. Changing this value immediately updates the color picker in the touch bar.
touchBarColorPicker.selectedColorA String hex code representing the color picker's currently selected color. Changing this value immediately updates the color picker in the touch bar.
\n\nCréer un groupe dans la touch bar pour les applications native macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarGroup(options)optionsitems TouchBar - Éléments à afficher en tant que groupe.\n\nCréer un label dans la touch bar pour les applications native macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarLabel(options)optionslabel String (facultatif) - Texte à afficher.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.textColor String (facultatif) - Couleur hexadécimal du texte, c.-à-d. #ABCDEF.When defining accessibilityLabel, ensure you have considered macOS best practices.
Les propriétés suivantes sont disponibles pour les instances de TouchBarLabel :
touchBarLabel.labelA String representing the label's current text. Changing this value immediately updates the label in the touch bar.
touchBarLabel.accessibilityLabelA String representing the description of the label to be read by a screen reader.
touchBarLabel.textColorA String hex code representing the label's current text color. Changing this value immediately updates the label in the touch bar.
\n\nInstantiates a special \"other items proxy\", which nests TouchBar elements inherited from Chromium at the space indicated by the proxy. By default, this proxy is added to each TouchBar at the end of the input. For more information, see the AppKit docs on NSTouchBarItemIdentifierOtherItemsProxy
\nNote: Only one instance of this class can be added per TouchBar.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarOtherItemsProxy()\n\nCréer un popover dans la touch bar pour les applications native macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarPopover(options)optionslabel String (facultatif) - Texte du bouton popover.icon NativeImage (facultatif) - Icône du bouton popover.items TouchBar - Items to display in the popover.showCloseButton Boolean (optional) - true to display a close button on the left of the popover, false to not show it. La valeur par défaut est vraie.Les propriétés suivantes sont disponibles pour les instances de TouchBarPopover :
touchBarPopover.labelA String representing the popover's current button text. Changing this value immediately updates the popover in the touch bar.
touchBarPopover.iconA NativeImage representing the popover's current button icon. Changing this value immediately updates the popover in the touch bar.
\n\nCréer un scrubber (un sélecteur de défilement)
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarScrubber(options)optionsitems ScrubberItem[] - Un tableau d'éléments à placer dans ce scrubber.select Function (optional) - Called when the user taps an item that was not the last tapped item.selectedIndex Integer - L'index de l'élément que l'utilisateur a sélectionné.highlight Function (optional) - Called when the user taps any item.highlightedIndex Integer - L'index de l'élément que l'utilisateur a sélectionné.selectedStyle String (optional) - Selected item style. Can be background, outline or none. Par défaut, none.overlayStyle String (optional) - Selected overlay item style. Can be background, outline or none. Par défaut, none.showArrowButtons Boolean (facultatif) - Afficher ou non les boutons flèches. La valeur par défaut est false et n'est affichée que si items n'est pas vide.mode String (optional) - Can be fixed or free. Par défaut, free.continuous Boolean (optionnel) - true par défaut.Les propriétés suivantes sont disponibles pour les instances de TouchBarScrubber :
touchBarScrubber.itemsUn tableau de ScrubberItem[]représentant les éléments dans ce scrubber. Changer cette valeur immédiatement met à jour le contrôle dans la touch bar. Changer une propriété dans le tableau ne met pas à jour la touch bar.
touchBarScrubber.selectedStyleUn String représentant le style des éléments sélectionnés dans le scrubber. Changer cette valeur immédiatement met à jour le contrôle dans la touch bar. Valeurs possibles :
background - Mappé à [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Mappé à [NSScrubberSelectionStyle outlineOverlayStyle].none - Removes all styles.touchBarScrubber.overlayStyleUn String représentant le style des éléments sélectionnés dans le scrubber. Ce style est superposé sur le dessus de l'élément scrubber au lieu d'être placé derrière. Changer cette valeur immédiatement met à jour le contrôle dans la touch bar. Valeurs possibles :
background - Mappé à [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Mappé à [NSScrubberSelectionStyle outlineOverlayStyle].none - Removes all styles.touchBarScrubber.showArrowButtonsA Boolean representing whether to show the left / right selection arrows in this scrubber. Updating this value immediately updates the control in the touch bar.
touchBarScrubber.modeA String representing the mode of this scrubber. Changer cette valeur immédiatement met à jour le contrôle dans la touch bar. Valeurs possibles :
fixed - Mappé à NSScrubberModeFixed.free - Mappé à NSScrubberModeFree.touchBarScrubber.continuousA Boolean representing whether this scrubber is continuous or not. Changer cette valeur immédiatement met à jour le contrôle dans la touch bar.
\n\nCréer un contrôle segmenté (un groupe de bouton) où un seul bouton a un état sélectionné
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSegmentedControl(options)optionssegmentStyle String (optional) - Style of the segments:automatique - Par défaut. The appearance of the segmented control is automatically determined based on the type of window in which the control is displayed and the position within the window. Maps to NSSegmentStyleAutomatic.rounded - Le contrôle est affiché en utilisant le style arrondi. Maps to NSSegmentStyleRounded.textured-rounded - Le contrôle est affiché en utilisant le style arrondi texturé. Maps to NSSegmentStyleTexturedRounded.round-rect - Le contrôle est affiché en utilisant le style arrondi rect. Maps to NSSegmentStyleRoundRect.textured-square - Le contrôle est affiché en utilisant le style carré texturé. Maps to NSSegmentStyleTexturedSquare.capsule - Le contrôle s’affiche selon le style capsule. Maps to NSSegmentStyleCapsule.small-square - Le contrôle est affiché en utilisant le style petit carré. Maps to NSSegmentStyleSmallSquare.separated - Les segments du contrôle sont affichés très proches entre eux, mais ne se touche pas. Maps to NSSegmentStyleSeparated.mode String (optional) - The selection mode of the control:single - Default. One item selected at a time, selecting one deselects the previously selected item. Maps to NSSegmentSwitchTrackingSelectOne.multiple - Plusieurs éléments peuvent être sélectionnés simultanément. Maps to NSSegmentSwitchTrackingSelectAny.buttons - Transforme les segments en boutons, chaque segment peut être pressé et relâché, mais jamais être marqué comme actif. Maps to NSSegmentSwitchTrackingMomentary.segments SegmentedControlSegment[] - Un tableau de segments à placer dans ce contrôle.selectedIndex Integer (facultatif) - L'index du segment actuellement sélectionné, mis automatiquement à jour avec une interaction utilisateur. When the mode is multiple it will be the last selected item.change Function (optional) - Called when the user selects a new segment.selectedIndex Integer - L'index du segment que l'utilisateur a sélectionné.isSelected Boolean - Si après la selection de l'utilisateur, le segment est selectionné ou non.Les propriétés suivantes sont disponibles pour les instances de TouchBarSegmentedControl :
touchBarSegmentedControl.segmentStyleA String representing the controls current segment style. Updating this value immediately updates the control in the touch bar.
touchBarSegmentedControl.segmentsUn tableau de SegmentedControlSegment[], qui représente les segments dans ce contrôle. Changer cette valeur immédiatement met à jour le contrôle dans la touch bar. Changer une propriété dans le tableau ne met pas à jour la touch bar.
touchBarSegmentedControl.selectedIndexUn Integer qui représente le segment sélectionné. Changer cette valeur immédiatement met à jour le contrôle dans la touch bar. Une interaction utilisateur avec la touch bar mettra à jour cette valeur automatiquement.
touchBarSegmentedControl.modeA String representing the current selection mode of the control. Can be single, multiple or buttons.
\n\nCréer un curseur dans la touch bar pour les applications native macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSlider(options)optionslabel String (facultatif) - Texte du label.value Integer (facultatif) - Valeur sélectionnée.minValue Integer (facultatif) - Valeur minimale.maxValue Integer (facultatif) - Valeur maximale.change Function (optional) - Function to call when the slider is changed.newValue Number - La valeur que l'utilisateur a sélectionnée sur le curseur.Les propriétés suivantes sont disponibles pour les instances de TouchBarSlider :
touchBarSlider.labelA String representing the slider's current text. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.valueA Number representing the slider's current value. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.minValueA Number representing the slider's current minimum value. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.maxValueA Number representing the slider's current maximum value. Changing this value immediately updates the slider in the touch bar.
\n\nCréer un espacement entre deux éléments dans la touch bar pour les applications native macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSpacer(options)optionssize String (optional) - Size of spacer, possible values are:small - petit espacement entre les éléments. Maps to NSTouchBarItemIdentifierFixedSpaceSmall. This is the default.large - grand espacement entre les éléments. Maps to NSTouchBarItemIdentifierFixedSpaceLarge.flexible - Prend tout l'espace disponible. Maps to NSTouchBarItemIdentifierFlexibleSpace.Les propriétés suivantes sont disponibles pour les instances de TouchBarSpacer :
touchBarSpacer.sizeA String representing the size of the spacer. Can be small, large or flexible.
categoryFilter String - A filter to control what category groups should be traced. A filter can have an optional '-' prefix to exclude category groups that contain a matching category. Having both included and excluded category patterns in the same list is not supported. Examples: test_MyTest*, test_MyTest*,test_OtherStuff, -excluded_category1,-excluded_category2.traceOptions String - Controls what kind of tracing is enabled, it is a comma-delimited sequence of the following strings: record-until-full, record-continuously, trace-to-console, enable-sampling, enable-systrace, e.g. 'record-until-full,enable-sampling'. The first 3 options are trace recording modes and hence mutually exclusive. If more than one trace recording modes appear in the traceOptions string, the last one takes precedence. If none of the trace recording modes are specified, recording mode is record-until-full. The trace option will first be reset to the default option (record_mode set to record-until-full, enable_sampling and enable_systrace set to false) before options parsed from traceOptions are applied on it.recording_mode String (optional) - Can be record-until-full, record-continuously, record-as-much-as-possible or trace-to-console. Defaults to record-until-full.trace_buffer_size_in_kb number (optional) - maximum size of the trace recording buffer in kilobytes. Defaults to 100MB.trace_buffer_size_in_events number (optional) - maximum size of the trace recording buffer in events.enable_argument_filter boolean (optional) - if true, filter event data according to a specific list of events that have been manually vetted to not include any PII. See the implementation in Chromium for specifics.included_categories String - a list of tracing categories to include. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.excluded_categories String - a list of tracing categories to exclude. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.included_process_ids number - a list of process IDs to include in the trace. If not specified, trace all processes.histogram_names String - a list of histogram names to report with the trace.memory_dump_config Record<String, any> (optional) - if the disabled-by-default-memory-infra category is enabled, this contains optional additional configuration for data collection. See the Chromium memory-infra docs for more information.An example TraceConfig that roughly matches what Chrome DevTools records:
\n{\n recording_mode: 'record-until-full',\n included_categories: [\n 'devtools.timeline',\n 'disabled-by-default-devtools.timeline',\n 'disabled-by-default-devtools.timeline.frame',\n 'disabled-by-default-devtools.timeline.stack',\n 'v8.execute',\n 'blink.console',\n 'blink.user_timing',\n 'latencyInfo',\n 'disabled-by-default-v8.cpu_profiler',\n 'disabled-by-default-v8.cpu_profiler.hires'\n ],\n excluded_categories: ['*']\n}\ntransactionIdentifier String - A string that uniquely identifies a successful payment transaction.transactionDate String - The date the transaction was added to the App Store’s payment queue.originalTransactionIdentifier String - The identifier of the restored transaction by the App Store.transactionState String - The transaction state, can be purchasing, purchased, failed, restored or deferred.errorCode Integer - The error code if an error occurred while processing the transaction.errorMessage String - The error message if an error occurred while processing the transaction.payment ObjectproductIdentifier String - The identifier of the purchased product.quantity Integer - The quantity purchased.\n\nAjoute des icônes et des menus contextuels à la zone de notification du système.
\n
Processus : Main
\nTray est un EventEmitter.
const { app, Menu, Tray } = require('electron')\n\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n ])\n tray.setToolTip('This is my application.')\n tray.setContextMenu(contextMenu)\n})\nLimitations selon les plateformes :
\nGtkStatusIcon sera utilisé à la place.libappindicator1 pour faire fonctionner l'icône.click est ignoré.MenuItems to take effect, you have to call setContextMenu again. Par exemple :const { app, Menu, Tray } = require('electron')\n\nlet appIcon = null\napp.whenReady().then(() => {\n appIcon = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' }\n ])\n\n // Make a change to the context menu\n contextMenu.items[1].checked = false\n\n // Call this again for Linux because we modified the context menu\n appIcon.setContextMenu(contextMenu)\n})\nICO pour obtenir les meilleurs effets visuels.Si vous souhaitez conserver les mêmes comportements sur toutes les plateformes, vous ne devriez pas vous appuyez sur l'événement click et toujours fixer un menu contextuel sur l'icône.
new Tray(image, [guid])image (NativeImage | String)guid String (optional) Windows - Assigns a GUID to the tray icon. If the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. OS level settings like the position of the tray icon in the system tray will persist even if the path to the executable changes. If the executable is not code-signed then the GUID is permanently associated with the path to the executable. Changing the path to the executable will break the creation of the tray icon and a new GUID must be used. However, it is highly recommended to use the GUID parameter only in conjunction with code-signed executable. If an App defines multiple tray icons then each icon must use a separate GUID.Créer une nouvelle icône dans la barre de notification avec l'image.
Le module Tray émet les événements suivants :
Retourne :
\nevent KeyboardEventbounds Rectangle - Les limites de l'icône.position Point - la position de l’événement.Émis lorsque l’utilisateur clique sur l’icône.
\nRetourne :
\nevent KeyboardEventbounds Rectangle - Les limites de l'icône.Émis lorsque l’utilisateur fait un clique droit sur l’icône.
\nRetourne :
\nevent KeyboardEventbounds Rectangle - Les limites de l'icône.Émis lorsque l’utilisateur double clique sur l’icône.
\nÉmis lorsque le ballon de la barre d’État s’affiche.
\nÉmis lorsque l’utilisateur clique sur le ballon de la barre d'État.
\nÉmis lorsque le ballon de la barre d’État est fermé en raison du délai d’attente dépassé ou de l’utilisateur le ferme manuellement.
\nÉmis lorsque un ou des éléments sont glissés et déposés sur l’icône.
\nRetourne :
\nevent Eventfiles String[] - les chemins d’accès des fichiers déposés.Émis lorsque des fichiers sont glissés et déposés sur l’icône.
\nRetourne :
\nevent Eventtext String - le texte déposé.Émis lorsqu'un texte est déposé sur l’icône.
\nÉmis lorsqu’une opération glisser entre dans la zone de l’icône.
\nÉmis lorsqu’une opération glisser sort de la zone de l’icône.
\nÉmis lorsqu’une opération glisser se termine sur l'icône ou à un autre emplacement.
\nRetourne :
\nevent KeyboardEventposition Point - la position de l’événement.Emitted when the mouse is released from clicking the tray icon.
\nNote: This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.
Retourne :
\nevent KeyboardEventposition Point - la position de l’événement.Emitted when the mouse clicks the tray icon.
\nRetourne :
\nevent KeyboardEventposition Point - la position de l’événement.Émis lorsque la souris entre dans la zone de l’icône.
\nRetourne :
\nevent KeyboardEventposition Point - la position de l’événement.Émis lorsque la souris sort de la zone de l’icône.
\nRetourne :
\nevent KeyboardEventposition Point - la position de l’événement.Émis lorsque la souris bouge dans la zone de l’icône.
\nLa classe Tray dispose des méthodes suivantes :
tray.destroy()Détruit l’icône immédiatement.
\ntray.setImage(image)image (NativeImage | String)Définit l’image associée à l'icône.
tray.setPressedImage(image) macOSimage (NativeImage | String)Définit l’image associée à l'icône quand elle est pressée sur macOS.
tray.setToolTip(toolTip)toolTip StringDéfinit le texte au survol pour l'icône.
\ntray.setTitle(title[, options]) macOStitle Stringoptions Object (facultatif)fontType String (optional) - The font family variant to display, can be monospaced or monospacedDigit. monospaced is available in macOS 10.15+ and monospacedDigit is available in macOS 10.11+. When left blank, the title uses the default system font.Définit le titre affiché à côté de l'icône de la barre d'état dans la barre d'état (couleurs support ANSI).
\ntray.getTitle() macOSRetourne String - le titre affiché à côté de l'icône de la barre d'état
tray.setIgnoreDoubleClickEvents(ignore) macOSignore BooleanSets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.
\nCette valeur est définie à <0>false</0> par défaut.
\ntray.getIgnoreDoubleClickEvents() macOSRetourne un Boolean - Si oui ou non les événènements de double clic seront ignorés.
tray.displayBalloon(options) Windowsoptionsicon (NativeImage | String) (optional) - Icon to use when iconType is custom.iconType String (optional) - Can be none, info, warning, error or custom. custom par défaut.title Stringcontent StringlargeIcon Boolean (optional) - The large version of the icon should be used. La valeur par défaut est vraie. Maps to NIIF_LARGE_ICON.noSound Boolean (optional) - Do not play the associated sound. Par défaut la valeur est false. Maps to NIIF_NOSOUND.respectQuietTime Boolean (optional) - Do not display the balloon notification if the current user is in \"quiet time\". Par défaut la valeur est false. Maps to NIIF_RESPECT_QUIET_TIME.Affiche une bulle dans la barre d'État.
\ntray.removeBalloon() WindowsRemoves a tray balloon.
\ntray.focus() WindowsReturns focus to the taskbar notification area. Notification area icons should use this message when they have completed their UI operation. For example, if the icon displays a shortcut menu, but the user presses ESC to cancel it, use tray.focus() to return focus to the notification area.
tray.popUpContextMenu([menu, position]) macOS Windowsmenu Menu (facultatif)position Point (facultatif) - Position du menu.Pops up the context menu of the tray icon. When menu is passed, the menu will be shown instead of the tray icon's context menu.
La position n’est disponible que sur Windows, et c’est (0, 0) par défaut.
tray.closeContextMenu() macOS WindowsCloses an open context menu, as set by tray.setContextMenu().
tray.setContextMenu(menu)menu Menu | nullDéfinit le menu contextuel de l'icône.
\ntray.getBounds() macOS WindowsRetourne Rectangle
Les limites de l'icône de la barre d’État en tant qu'Objet.
tray.isDestroyed()Retourne Boolean - si l’icône est détruite.
title: Tray\ndescription: Ce guide vous guidera tout au long du processus de création d’une icône de la barre d’état avec son propre menu contextuel dans la zone de notification du système.\nslug: tray
\nCe guide vous guidera tout au long du processus de création d’une icône de la barre d’état avec son propre menu contextuel dans la zone de notification du système.
\nSur MacOS et Ubuntu, la zone de notification sera située dans le coin supérieur droit de l'écran, à coté des icônes batterie et wifi. Sous Windows, la barre d'états se trouve généralement dans le coin inférieur droit.
\nNous devons d’abord importer app, Tray, Menu, nativeImage depuis electron.
const { app, Tray, Menu, nativeImage } = require('electron')\nEnsuite, nous allons créer notre Tray. Pour ce faire, nous utiliserons une icône NativeImage , qui peut être créée via l’une de ces méthodes. Notez que nous encapsulons notre code de création du Tray dans un app.whenReady car nous devrons attendre que notre application electron termine de s'initialiser.
let tray\n\napp.whenReady().then(() => {\n const icon = nativeImage.createFromPath('path/to/asset.png')\n tray = new Tray(icon)\n\n // note: votre code contextMenu, Tooltip and Title ira ici!\n})\nGénial! Maintenant nous pouvons commencer à attacher un menu contextuel à notre Tray, comme ceci:
\nconst contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n])\n\ntray.setContextMenu(contextMenu)\nLe code ci-dessus créera 4 éléments distincts de type radio dans le menu contextuel. Pour en savoir plus sur la création de menus natifs, cliquez sur ce lien ici.
\nEnfin, donnons à notre barre d’états une infobulle et un titre.
\ntray.setToolTip('Ceci est mon application')\ntray.setTitle('Ceci est mon titre')\nAprès avoir démarré votre application electron, vous devriez voir le Tray placé en soit haut soit en bas à droite de votre écran, selon votre système d'exploitation.\nfiddle docs/fiddles/native-ui/tray
Il y a plusieurs méthodes pour mettre à jour une application Electron. La plus simple, et celle qui est officiellement supportée, tire parti de l'intégration du framework Squirrel et du module autoUpdater d'Electron.
\nupdate.electronjs.orgThe Electron team maintains update.electronjs.org, a free and open-source webservice that Electron apps can use to self-update. Ce service est conçu pour les applications Electron répondant aux critères suivant:
\nLa façon la plus simple d'utiliser ce service est d'installer update-electron-app, un module Node.js pré-configuré pour être utilisé avec update.electronjs.org.
\nInstaller le module:
\nnpm install update-electron-app\nDéclenchez la mise à jour à partir du processus principal de votre application :
\nrequire('update-electron-app')()\nPar défaut, ce module vérifiera les mises à jour au démarrage de l'application, toutes les dix- minutes. Lorsqu’une mise à jour est trouvée, elle sera automatiquement téléchargée en arrière-plan. Une fois le téléchargement terminé, une boîte de dialogue s’affiche permettant à l’utilisateur de redémarrer l’application.
\nSi vous avez besoin personnaliser votre configuration, vous pouvez passer des paramètres à update-electron-app ou utiliser le service de mise à jour directement.
Si vous développez une application Electron privée, ou si vous ne publiez pas votre application sous GitHub, il peut être nécessaire de mettre en place votre propre serveur de mise à jour.
\nSelon vos besoins, vous pouvez choisir parmi l'un d'entre eux :
\nUne fois que vous avez déployé votre serveur de mise à jour, continuez d'importer les modules requis dans votre code. Le code suivant peut varier pour les différents serveurs, mais il fonctionne comme décrit lors de l'utilisation de Hazel.
\nImportant : Veuillez vous assurer que le code ci-dessous sera exécuté uniquement dans votre application empaquetée, et non dans la version en développement. Vous pouvez utiliser electron-is-dev pour vérifier l'environnement.
\nconst { app, autoUpdater, dialog } = require('electron')\nEnsuite, construisez l'URL du serveur de mise à jour et informez-en autoUpdater:
\nconst server = 'https://your-deployment-url.com'\nconst url = `${server}/update/${process.platform}/${app.getVersion()}`\n\nautoUpdater.setFeedURL({ url })\nComme dernière étape, vérifiez les mises à jour. L'exemple ci-dessous vérifiera chaque minute:
\nsetInterval(() => {\n autoUpdater.checkForUpdates()\n}, 60000)\nUne fois que votre application est empaquetée, elle recevra une mise à jour pour chaque nouvelle version GitHub que vous publierez.
\nMaintenant que vous avez configuré le mécanisme de mise à jour de base de votre application, vous devez vous assurer que l’utilisateur sera notifié quand il y a une mise à jour. Cela peut être réalisé avec les événements de l'API autoUpdater:
\nautoUpdater.on('update-downloaded', (event, releaseNotes, releaseName) => {\n const dialogOpts = {\n type: 'info',\n buttons: ['Restart', 'Later'],\n title: 'Application Update',\n message: process.platform === 'win32' ? releaseNotes : releaseName,\n detail: \"A new version has been downloaded. Restart the application to apply the updates.'\n }\n\n dialog.showMessageBox(dialogOpts).then((returnValue) => {\n if (returnValue.response === 0) autoUpdater.quitAndInstall()\n })\n})\nAssurez-vous également que les erreurs sont gérées. Voici un exemple pour les renvoyer sur stderr:
autoUpdater.on('error', message => {\n console.error('There was a problem updating the application')\n console.error(message)\n})\nBecause the requests made by Auto Update aren't under your direct control, you may find situations that are difficult to handle (such as if the update server is behind authentication). The url field does support files, which means that with some effort, you can sidestep the server-communication aspect of the process. Here's an example of how this could work.
bytes Buffer - Content being sent.file String (optional) - Path of file being uploaded.blobUUID String (optional) - UUID of blob data. Use ses.getBlobData method to retrieve the data.type 'file' - file.filePath String - Path of file to be uploaded.offset Integer - Defaults to 0.length Integer - Number of bytes to read from offset. Defaults to 0.modificationTime Double - Last Modification time in number of seconds since the UNIX epoch.type 'rawData' - rawData.bytes Buffer - Data to be uploaded.string Stringboolean Booleaninteger Numberfloat Numberdouble Numberurl Stringarray Array\\dictionary\\<string, unknown>This type is a helper alias, no object will never exist of this type.
", "title": "UserDefaultTypes Object", "description": "" }, "/docs/tutorial/using-native-node-modules": { "locale": "fr-FR", "slug": "using-native-node-modules", "href": "/docs/tutorial/using-native-node-modules", "crowdinFileId": "256263", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-native-node-modules.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Native Node.js modules are supported by Electron, but since Electron has a different application binary interface (ABI) from a given Node.js binary (due to differences such as using Chromium's BoringSSL instead of OpenSSL), the native modules you use will need to be recompiled for Electron. Sinon, vous obtiendrez l'erreur de classe suivante lorsque vous essaierez d'exécuter votre application :
\nErreur : Le module '/path/to/native/module.node'\na été compilé avec une version de Node.js différente en utilisant\nNODE_MODULE_VERSION $XYZ. Cette version de Node.js nécessite\nNODE_MODULE_VERSION $ABC. Veuillez essayer de re-compiler ou de réinstaller\nle module (par exemple, en utilisant `npm rebuild` ou `npm install`).\nIl y a plusieurs façons d'installer des modules natifs :
\nVous pouvez choisir d'installer les modules comme les autres projets Node, puis recompiler les modules pour Electron avec le paquet electron-rebuild. Ce module peut automatiquement obtenir la version d'Electron et gérer les étapes manuelles de téléchargement des en-têtes, compiler les modules natifs pour votre application. If you are using Electron Forge, this tool is used automatically in both development mode and when making distributables.
For example, to install the standalone electron-rebuild tool and then rebuild modules with it via the command line:
npm install --save-dev electron-rebuild\n\n# Every time you run \"npm install\", run this:\n./node_modules/.bin/electron-rebuild\n\n# If you have trouble on Windows, try:\n.\\node_modules\\.bin\\electron-rebuild.cmd\nFor more information on usage and integration with other tools such as Electron Packager, consult the project's README.
\nnpmEn définissant quelques variables d’environnement, vous pouvez utiliser npm pour installer des modules directement.
Par exemple, pour installer toutes les dépendances d'Electron :
\n# Version d'Electron.\nexport npm_config_target=1.2.3\n# L'architecture d'Electron, consultez\nhttps://electronjs.org/docs/tutorial/support#supported-platforms\n# pour les architectures prises en charge.\nexport npm_config_arch=x64\nexport npm_config_target_arch=x64\n# Télécharge les en-têtes pour Electron.\nexport npm_config_disturl=https://electronjs.org/headers\n# Indique à node-pre-gyp que l'on compile pour Electron.\nexport npm_config_runtime=electron\n# Indique à node-pre-gyp de compiler les modules depuis leur code source.\nexport npm_config_build_from_source=true\n# Installe toutes les dépendances, et met en cache à ~/.electron-gyp.\nHOME=~/.electron-gyp npm install\nSi vous êtes un développeur développant un module natif et que vous voulez le tester avec Electron, vous pouvez recompiler le module pour Electron manuellement. Vous pouvez utiliser node-gyp directement pour compiler pour Electron:
cd /path-to-module/\nHOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://electronjs.org/headers\nHOME=~/.electron-gyp indique où trouver les en-têtes pour le développement.--target=1.2.3 est la version d'Electron.--dist-url=... indique où télécharger les en-têtes.--arch=x64 spécifie que le module est prévu pour un système 64 bits.Pour compiler des modules Node natifs avec une compilation personnalisée d'Electron qui ne correspond pas à une release publique, utilisez la commande npm pour utiliser la version de Node que vous avez empaquetée avec votre compilation personnalisée.
npm rebuild --nodedir=/path/to/src/out/Default/gen/node_headers\nSi vous avez installé un module natif et trouvé que cela ne fonctionnait pas, vous devez vérifier ces éléments suivants :
\nelectron-rebuild.win_delay_load_hook n'est pas défini comme false dans le module binding.gyp.win_delay_load_hookSur Windows, par défaut, node-gyp relie les modules natifs à node.dll. Cependant, dans Electron 4.x et supérieur, les symboles nécessaires aux modules natifs sont exportés par electron.exe, et node.dll n'existe pas. Afin de charger les modules natifs sous Windows, node-gyp installe un delay-load hoook qui déclenche lorsque le module natif est chargé, et redirige le noeud. la référence ll pour utiliser l'exécutable de chargement au lieu de rechercher node.dll dans le chemin de la recherche de bibliothèque (qui n'afficherait rien). Ainsi, sur Electron 4.x et supérieur, 'win_delay_load_hook' : 'true' est requis pour charger les modules natifs.
Si vous obtenez une erreur comme Module ne s'est pas auto-enregistré, ou La procédure spécifiée n'a pas pu être trouvée, cela peut signifier que le module que vous essayez d'utiliser n'a pas inclus correctement le crochet de chargement de retard. Si le module est construit avec node-gyp, assurez-vous que la variable win_delay_load_hook est définie à true dans la liaison . fichier yp et ne se fait pas écrasé partout. Si le module est construit avec un autre système, vous devrez vous assurer que vous construisez avec un crochet de chargement tardif installé dans le principal. fichier ode. Votre invocation link.exe devrait ressembler à ceci :
link.exe /OUT:\"foo.node\" \"...\\node.lib\" delayimp.lib /DELAYLOAD:node.exe /DLL\n \"my_addon.obj\" \"win_delay_load_hook.obj\"\nEn particulier, il est important que :
\nnode.lib from Electron and not Node. If you link against the wrong node.lib you will get load-time errors when you require the module in Electron./DELAYLOAD:node.exe. Si le noeud. Le lien xe n'est pas retardé, alors le crochet de chargement de temps n'aura pas de chance de tirer et les symboles du noeud ne seront pas correctement résolus.win_delay_load_hook.obj is linked directly into the final DLL. If the hook is set up in a dependent DLL, it won't fire at the right time.Voir node-gyp pour un exemple de Hook de chargement à retardement si vous implémentez le vôtre.
prebuildprebuild permet de publier facilement des modules natifs Node avec des binaires précompilés pour plusieurs version de Node et d'Electron.
If the prebuild-powered module provide binaries for the usage in Electron, make sure to omit --build-from-source and the npm_config_build_from_source environment variable in order to take full advantage of the prebuilt binaries.
node-pre-gypnode-pre-gyp tool fournit un moyen de déployer des modules natifs Node avec des binaires précompilés, beaucoup de modules populaires l'utilisent.
Sometimes those modules work fine under Electron, but when there are no Electron-specific binaries available, you'll need to build from source. Because of this, it is recommended to use electron-rebuild for these modules.
If you are following the npm way of installing modules, you'll need to pass --build-from-source to npm, or set the npm_config_build_from_source environment variable.
Electron no longer supports the Pepper Flash plugin, as Chrome has removed support.
\nSee Chromium's Flash Roadmap for more details.
", "title": "Plugin Pepper Flash", "description": "" }, "/docs/tutorial/using-selenium-and-webdriver": { "locale": "fr-FR", "slug": "using-selenium-and-webdriver", "href": "/docs/tutorial/using-selenium-and-webdriver", "crowdinFileId": "256267", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-selenium-and-webdriver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "De ChromeDriver - WebDriver pour Chrome :
\n\n\nWebDriver est un outil open source pour les tests automatisés d'applications web sur plusieurs navigateurs. Il fournit des fonctions pour naviguer vers les pages web, simuler l'input utilisateur, l’exécution de JavaScript, etc... . ChromeDriver est un serveur autonome qui implémente le protocole de WebDriver (WebDriver's wire protocol) pour Chromium. Il est développé par des membres des équipes chrome et WebDriver.
\n
Spectron est le framework ChromeDriver de test officiel pour Electron. Il est basé sur WebdriverIO et a des helpers pour accéder aux APIS d'Electron dans vos tests et bundles ChromeDriver.
\n$ npm install --save-dev spectron\n// Un test simple pour vérifier si une fenêtre visible est ouverte avec un titre\nconst Application = require('spectron').Application\nconst assert = require('assert')\n\nconst myApp = new Application({\n path: '/Applications/MyApp.app/Contents/MacOS/MyApp'\n})\n\nconst verifyWindowIsVisibleWithTitle = async (app) => {\n await app.start()\n try {\n // Vérifie si la fenêtre est visible\n const isVisible = await app.browserWindow.isVisible()\n assert.strictEqual(isVisible, true)\n // Récupère le titre de la fenêtre\n const title = await app.client.getTitle()\n // Vérifie le titre de la fenêtre\n assert.strictEqual(title, 'My App')\n } catch (error) {\n // Note toute erreur rencontrée\n console.error('Test failed', error.message)\n }\n // Arrête l'application\n await app.stop()\n}\n\nverifyWindowIsVisibleWithTitle(myApp)\nWebDriverJs provides a Node package for testing with web driver, we will use it as an example.
\nTout d’abord, téléchargez chromedriver, puis exécutez-le :
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver\nDémarre ChromeDriver (v2.10.291558) sur le port 9515\nSeulement les connexions locales sont autorisées.\nN'oubliez pas le numéro du port 9515, qui servira plus tard
$ npm install selenium-webdriver\nL’utilisation de selenium-webdriver avec Electron est pratiquement la même chose qu'avec upstream, sauf que vous devez spécifier manuellement comment connecter le driver chrome et où trouver le fichier binaire d'Electron :
const webdriver = require('selenium-webdriver')\n\nconst driver = new webdriver.Builder()\n // \"9515\" est le port ouvert par ChromeDriver.\n .usingServer('http://localhost:9515')\n .withCapabilities({\n 'goog:chromeOptions': {\n // Here is the path to your Electron binary.\n binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'\n }\n })\n .forBrowser('chrome') // note: use .forBrowser('electron') for selenium-webdriver <= 3.6.0\n .build()\n\ndriver.get('http://www.google.com')\ndriver.findElement(webdriver.By.name('q')).sendKeys('webdriver')\ndriver.findElement(webdriver.By.name('btnG')).click()\ndriver.wait(() => {\n return driver.getTitle().then((title) => {\n return title === 'webdriver - Google Search'\n })\n}, 1000)\n\ndriver.quit()\nWebdriverIO provides a Node package for testing with web driver.
\nTout d’abord, téléchargez chromedriver, puis exécutez-le :
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver --url-base=wd/hub --port=9515\nDemarre ChromeDriver (v2.10.291558) sur le port 9515\nSeulement les connexions locales sont autorisées.\nN'oubliez pas le numéro du port 9515, qui servira plus tard
$ npm install webdriverio\nconst webdriverio = require('webdriverio')\nconst options = {\n host: 'localhost', // Utilisez localhost comme serveur ChromeDriver\n port: 9515, // \"9515\" est le port ouvert par ChromeDriver.\n desiredCapabilities: {\n browserName: 'chrome',\n chromeOptions: {\n binary: '/Path-to-Your-App/electron', // Chemin vers votre binaire Electron.\n args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/\n }\n }\n}\n\nconst client = webdriverio.remote(options)\n\nclient\n .init()\n .url('http://google.com')\n .setValue('#q', 'webdriverio')\n .click('#btnG')\n .getTitle().then((title) => {\n console.log('Title was: ' + title)\n })\n .end()\nPour tester votre application sans re-compiler Electron, il suffit de placer la source de votre app dans le dossier des ressources d'Electron.
\nAlternatively, 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.
", "title": "Selenium et WebDriver", "description": "WebDriver est un outil open source pour les tests automatisés d'applications web sur plusieurs navigateurs. Il fournit des fonctions pour naviguer vers les pages web, simuler l'input utilisateur, l’exécution de JavaScript, etc... . ChromeDriver est un serveur autonome qui implémente le protocole de WebDriver (WebDriver's wire protocol) pour Chromium. Il est développé par des membres des équipes chrome et WebDriver." }, "/docs/development/v8-development": { "locale": "fr-FR", "slug": "v8-development", "href": "/docs/development/v8-development", "crowdinFileId": "256171", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/v8-development.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "\n\nUne collection de ressources pour l’apprentissage et à l'utilisation de V8
\n
--prof, --trace-ic, --trace-opt, --trace-deopt, --print-bytecode, --print-opt-codeVoir aussi Développement de Chromium
", "title": "Développement V8", "description": "Une collection de ressources pour l’apprentissage et à l'utilisation de V8" }, "/docs/api/web-contents": { "locale": "fr-FR", "slug": "web-contents", "href": "/docs/api/web-contents", "crowdinFileId": "256399", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-contents.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nFait le rendu et contrôle des pages web.
\n
Processus : Main
\nwebContents est un EventEmitter. Il est responsable du rendu et du contrôle d'une page web et est une propriété de l'objet BrowserWindow. Exemple d'accès à l'objet webContents :
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('http://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\nCes méthodes sont accessibles depuis le module webContents :
const { webContents } = require('electron')\nconsole.log(webContents)\nwebContents.getAllWebContents()Retourne WebContents[] - Un tableau de toutes les instances de WebContents. Celui-ci contiendra le contenu web de toutes les fenêtres, webviews, devtools ouvertes et pages d'extention d'arrière-plan des devtools .
webContents.getFocusedWebContents()Retourne WebContents - Le contenu web qui a le focus dans cette application, sinon retourne null.
webContents.fromId(id)id IntegerReturns WebContents | undefined - A WebContents instance with the given ID, or undefined if there is no WebContents associated with the given ID.
webContents.fromDevToolsTargetId(targetId)targetId String - The Chrome DevTools Protocol TargetID associated with the WebContents instance.Returns WebContents | undefined - A WebContents instance with the given TargetID, or undefined if there is no WebContents associated with the given TargetID.
When communicating with the Chrome DevTools Protocol, it can be useful to lookup a WebContents instance based on its assigned TargetID.
\nasync function lookupTargetId (browserWindow) {\n const wc = browserWindow.webContents\n await wc.debugger.attach('1.3')\n const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')\n const { targetId } = targetInfo\n const targetWebContents = await webContents.fromDevToolsTargetId(targetId)\n}\n\n\nAffiche et contrôle le contenu d'une instance de BrowserWindow.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Émis lorsque la navigation a abouti, c'est à dire que le loader de l'onglet a cessé de tourner, et l'événement onload a été émis.
Retourne :
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerCet événement est comme did-finish-load mais émis lorsque le chargement a échoué. La liste complète des codes d'erreur et leur signification est disponible ici.
Retourne :
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerCet événement est comme did-fail-load mais émis lorsque la charge a été annulée (par exemple window.stop() a été appelé).
Retourne :
\nevent EventisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerÉmis lorsqu'un frame a fini sa navigation.
\nCorrespond au moment où le loader de l'onglet commence à tourner.
\nCorrespond au moment où le loader de l'onglet arrête de tourner.
\nRetourne :
\nevent EventEmitted when the document in the top-level frame is loaded.
\nRetourne :
\nevent Eventtitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when title is synthesized from file url.
Retourne :
\nevent Eventfavicons String[] - Tableau d'URLs.Émis lorsque la page reçoit l’url du favicon.
\nRetourne :
\nevent NewWindowWebContentsEventurl StringframeName Stringdisposition String - Peut être default, foreground-tab, background-tab, new-window, save-to-disk et other.options BrowserWindowConstructorOptions - Les options qui seront utilisées pour créer le nouveau BrowserWindow.additionalFeatures String[] - Les fonctionnalités non standards (fonctionnalités non gérés par Chromium ou Electron) donné à window.open(). Deprecated, and will now always be the empty array [].referrer Referrer - Le parrain qui sera passé à la nouvelle fenêtre. Peut ou ne peut pas entraîner l'envoi de l'en-tête Référent en fonction de la politique du référent.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.Obsolète, utiliser webContents.setWindowOpenHandler à la place.
Emitted when the page requests to open a new window for a url. It could be requested by window.open or an external link like <a target='_blank'>.
Un nouveau BrowserWindow sera créé par défaut pour l'url.
L'appel à event.preventDefault() empêchera Electron de créer automatiquement une nouvelle BrowserWindow. Si vous appelez event.preventDefault() et créez manuellement un nouveau BrowserWindow alors vous devez définir événement. ewGuest pour référencer la nouvelle instance BrowserWindow . Si vous ne le faites pas, cela peut entraîner un comportement inattendu. Par exemple :
myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {\n event.preventDefault()\n const win = new BrowserWindow({\n webContents: options.webContents, // use existing webContents if provided\n show: false\n })\n win.once('ready-to-show', () => win.show())\n if (!options.webContents) {\n const loadOptions = {\n httpReferrer: referrer\n }\n if (postBody != null) {\n const { data, contentType, boundary } = postBody\n loadOptions.postData = postBody.data\n loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`\n }\n\n win.loadURL(url, loadOptions) // existing webContents will be navigated automatically\n }\n event.newGuest = win\n})\nRetourne :
\nwindow BrowserWindowdetailsurl String - URL for the created window.frameName String - Name given to the created window in the window.open() call.options BrowserWindowConstructorOptions - The options used to create the BrowserWindow. They are merged in increasing precedence: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Unrecognized options are not filtered out.referrer Referrer - Le parrain qui sera passé à la nouvelle fenêtre. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.Emitted after successful creation of a window via window.open in the renderer. Not emitted if the creation of the window is canceled from webContents.setWindowOpenHandler.
See window.open() for more details and how to use this in conjunction with webContents.setWindowOpenHandler.
Retourne :
\nevent Eventurl StringEmitted when a user or the page wants to start navigation. It can happen when the window.location object is changed or a user clicks a link in the page.
Cet événement ne sera pas émis lorsque la navigation démarre par programmation grâce aux APIs comme webContents.loadURL et webContents.back.
It is also not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Appeler event.preventDefault() permet d'éviter la navigation.
Retourne :
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be true for in-page navigations.
Retourne :
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted as a server side redirect occurs during navigation. For example a 302 redirect.
\nCet événement sera émis après did-start-navigation et pour la même navigation toujours avant l'événement did-redirect-navigation .
L'appel à event.preventDefault() empêchera la navigation (pas seulement la redirection).
Retourne :
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nThis event cannot be prevented, if you want to prevent redirects you should checkout out the will-redirect event above.
Retourne :
\nevent Eventurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigationsÉmis lorsque la navigation d'une fenêtre principale est terminée.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Retourne :
\nevent Eventurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - vide pour les navigations non HTTP,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerÉmis lorsqu'une navigation est terminée.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Retourne :
\nevent Eventurl StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when an in-page navigation happened in any frame.
\nEn cas de navigation dans la page, l'URL de la page change mais ne provoque pas de navigation à l'extérieur de la page. Par exemple, lorsque vous cliquez sur un lien d'ancrage ou lorsque l'événement DOM hashchange est déclenché.
Retourne :
\nevent EventÉmis lorsqu’un écouteur de l'événement beforeunload tente d’annuler un déchargement de la page.
Appeler event.preventDefault() ignorera l'écouteur de l'événement beforeunload et va laisser la page se décharger.
const { BrowserWindow, dialog } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.webContents.on('will-prevent-unload', (event) => {\n const choice = dialog.showMessageBoxSync(win, {\n type: 'question',\n buttons: ['Leave', 'Stay'],\n title: 'Do you want to leave this site?',\n message: 'Changes you made may not be saved.',\n defaultId: 0,\n cancelId: 1\n })\n const leave = (choice === 0)\n if (leave) {\n event.preventDefault()\n }\n})\nNote: This will be emitted for BrowserViews but will not be respected - this is because we have chosen not to tie the BrowserView lifecycle to its owning BrowserWindow should one exist per the specification.
Retourne :
\nevent Eventkilled BooleanÉmis lorsque le processus renderer crash ou est interrompu.
\nDeprecated: Cet événement est remplacé par l'événement render-process-gone qui contient plus d'informations à propos de la raison du plantage du processus enfant. Ceci n'est pas toujours causé par un plantage. Le booléen killed peut être remplacé par la vérification de reason === 'killed' lorsque vous passez à l'utilisation de cet événement.
Retourne :
\nevent Eventdetailsreason String - La raison pour laquelle le processus de rendu a disparu. Valeurs possibles :anormal-exit - Le Processus s'est terminé avec un code de sortie différent de zérokilled - Le processus a reçu un SIGTERM ou a été tué autrement de l'extérieurcrashed - Processus s'est plantéoom - Le processus est tombé à cours de mémoirelaunch-failed - Le processus ne s'est pas lancé avec succèsintegrity-failure - Les vérifications d'intégrité du code Windows ont échouéesexitCode Integer - Le code de sortie du proces, sauf si reason est launch-failed, dans ce cas là exitCode sera specifique per plateforme.Émis lorsque le processus de rendu plante de manière inattendue. C'est normalement dans les cas où il s'est planté ou qu'il a été tué.
\nÉmis lorsque la page web cesse de répondre.
\nÉmis lorsque la page web répond à nouveau.
\nRetourne :
\nevent Eventname Stringversion StringÉmis lorsqu’un processus de plugin crash.
\nÉmis lorsqu'un webContents est détruit.
Retourne :
\nevent Eventinput Object - Input properties.type String - Either keyUp or keyDown.key String - Équivalent à KeyboardEvent.key.code String - Équivalent à KeyboardEvent.code.isAutoRepeat Boolean - Équivalent à KeyboardEvent.repeat.isComposing Boolean - Equivalent to KeyboardEvent.isComposing.shift Boolean - Équivalent à KeyboardEvent.shiftKey.control Boolean - Équivalent à KeyboardEvent.controlKey.alt Boolean - Équivalent à KeyboardEvent.altKey.meta Boolean - Équivalent à KeyboardEvent.metakey.location Number - Equivalent to KeyboardEvent.location.modifiers String[] - See InputEvent.modifiers.Émis avant d'envoyer les événements keydown et keyup dans la page. Appeler event.preventDefault empêchera les événements keydown/keyup et les raccourcis du menu dans la page.
To only prevent the menu shortcuts, use setIgnoreMenuShortcuts:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nwin.webContents.on('before-input-event', (event, input) => {\n // For example, only enable application menu keyboard shortcuts when\n // Ctrl/Cmd are down.\n win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)\n})\nÉmis lorsque la fenêtre entre dans un état de plein écran déclenchée par l’API HTML.
\nÉmis lorsque la fenêtre revient d'un état de plein écran déclenchée par l’API HTML.
\nRetourne :
\nevent EventzoomDirection String - Peut être in ou out.Émis lorsque l'utilisateur demande à changer le niveau de zoom en utilisant la molette de la souris.
\nÉmis lorsque la DevTools est ouverte.
\nÉmis lorsque la DevTools est fermée.
\nÉmis lorsque la DevTools est active / ouverte.
\nRetourne :
\nevent Eventurl Stringerror String - The error code.certificate Certificatecallback FunctionisTrusted Boolean - Indicates whether the certificate can be considered trusted.isMainFrame BooleanÉmis lorsqu'il n'a pas pu vérifier le certificat de l'url.
L'utilisation est pareil que l'événement certificate-error de app.
Retourne :
\nevent Eventurl URLcertificateList Certificate[]callback Functioncertificate Certificate - Must be a certificate from the given list.Émis lorsqu'un certificat client est demandé.
\nL'utilisation est pareil que l'événement select-client-certificate de app.
Retourne :
\nevent EventauthenticationResponseDetailsurl URLauthInfoisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionnom d'utilisateur String (facultatif)mot de passe String (facultatif)Émis lorsque webContents veut faire une authentification normale.
L'utilisation est pareil que l'événement login de app.
Retourne :
\nevent Eventresult ObjectrequestId IntegeractiveMatchOrdinal Integer - Position du résultat actif.matches Integer - Nombre de résultats.sélectionArea Rectangle - Coordonnées de la région de la première correspondance.finalUpdate BooleanÉmis lorsqu'un résultat est disponible pour la requête [webContents.findInPage].
Émis lorsqu'un média se démarre.
\nÉmis lorsque le média est suspendu ou terminé.
\nRetourne :
\nevent Eventcolor (String | null) - Theme color is in format of '#rrggbb'. It is null when no theme color is set.Emitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nRetourne :
\nevent Eventurl StringÉmis lorsque la souris passe sur un lien ou le clavier déplace le focus vers un lien.
\nRetourne :
\nevent Eventtype Stringimage NativeImage (facultatif)scale Float (optional) - scaling factor for the custom cursor.size Size (optional) - the size of the image.hotspot Point (optional) - coordinates of the custom cursor's hotspot.Émis lorsque le type du curseur change. The type parameter can be default, crosshair, pointer, text, wait, help, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ns-resize, ew-resize, nesw-resize, nwse-resize, col-resize, row-resize, m-panning, e-panning, n-panning, ne-panning, nw-panning, s-panning, se-panning, sw-panning, w-panning, move, vertical-text, cell, context-menu, alias, progress, nodrop, copy, none, not-allowed, zoom-in, zoom-out, grab, grabbing or custom.
Si le paramètre type est custom, le paramètre image contiendra l'image du curseur personnalisé dans un NativeImage, et scale, size et hotspot contiendront les informations complémentaires à propos du curseur personnalisé.
Retourne :
\nevent Eventparams Objectx Integer - x coordinate.y Integer - y coordinate.frame WebFrameMain - Frame from which the context menu was invoked.linkURL String - L'URL du lien qui englobe le nœud du menu contextuel.linkText String - Text associated with the link. May be an empty string if the contents of the link are an image.pageURL String - L'URL de la page haut niveau d'où le menu contextuel a été invoqué.frameURL String - L'URL de la subframe d'où le menu contextuel a été invoqué.srcURL String - Source URL for the element that the context menu was invoked on. Elements with source URLs are images, audio and video.mediaType String - Type du nœud sur lequel le menu contextuel a été appelé. Peut être none, image, audio, vidéo, toile, fichier ou plugin.hasImageContents Boolean - Si le menu contextuel a été invoqué sur une image au contenu non-vide ou non.isEditable Boolean - Si le contexte est modifiable ou non.selectionText String - Texte de la sélection sur laquelle le menu contextuel a été invoqué.titleText String - Title text of the selection that the context menu was invoked on.altText String - Alt text of the selection that the context menu was invoked on.suggestedFilename String - Suggested filename to be used when saving file through 'Save Link As' option of context menu.selectionRect Rectangle - Rect representing the coordinates in the document space of the selection.selectionStartOffset Number - Start position of the selection text.referrerPolicy Referrer - The referrer policy of the frame on which the menu is invoked.misspelledWord String - Mot mal orthographié sous le curseur, si applicable.dictionarySuggestions String[] - Un tableau de mots suggérés à montrer à l'utilisateur pour remplacer le misspelledWord. Uniquement disponible si un mot est mal orthographié et que le correcteur orthographique est activé.frameCharset String - L'encodage des caractères de la fenêtre sur lequel le menu a été appelé.inputFieldType String - Si le menu contextuel a été appelé sur un champ modifiable, donne le type de ce champ. Les valeurs possibles sont none, plainText, password, other.spellcheckEnabled Boolean - If the context is editable, whether or not spellchecking is enabled.menuSourceType String - Input source that invoked the context menu. Can be none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, or adjustSelectionReset.mediaFlags Object - The flags for the media element the context menu was invoked on.inError Boolean - Si l'élément multimédia a crash.isPaused Boolean - Si l'élément multimédia est en pause.isMuted Boolean - Si l'élément multimédia est mis en sourdine.hasAudio Boolean - Si l'élément multimédia émet un son audio.isLooping Boolean - Si l'élément multimédia est en boucle.isControlsVisible Boolean - Si les contrôles de l'élément multimédia sont visibles.canToggleControls Boolean - Si les contrôles de l'élément multimédia sont toggleable.canPrint Boolean - Whether the media element can be printed.canSave Boolean - Whether or not the media element can be downloaded.canShowPictureInPicture Boolean - Whether the media element can show picture-in-picture.isShowingPictureInPicture Boolean - Whether the media element is currently showing picture-in-picture.canRotate Boolean - Si l'élément multimédia peut être pivoté.canLoop Boolean - Whether the media element can be looped.editFlags Object - These flags indicate whether the renderer believes it is able to perform the corresponding action.canUndo Boolean - Si le moteur de rendu pense pouvoir aller en arrière.canRedo Boolean - Si le moteur de rendu pense pouvoir aller en avant.canCut Boolean - Si le moteur de rendu pense pouvoir couper.canCopy Boolean - Si le moteur de rendu pense pouvoir copier.canPaste Boolean - Si le moteur de rendu pense pouvoir coller.canDelete Boolean - Si le moteur de rendu pense pouvoir supprimer.canSelectAll Boolean - Si le moteur de rendu pense pouvoir tout sélectionner.canEditRichly Boolean - Whether the renderer believes it can edit text richly.Émis lorsqu'un nouveau menu contextuel a besoin d'être pris en charge.
\nRetourne :
\nevent Eventdevices BluetoothDevice[]callback FunctiondeviceId StringÉmis lorsque le périphérique bluetooth a besoin d'être selectionné lors de l'appel de navigator.bluetooth.requestDevice. Pour utiliser l'api navigator.bluetooth, webBluethooth doit être activé. Si event.preventDefault n'est pas appelé, le premier périphérique disponible sera sélectionné. callback doit être appelé avec deviceId à sélectionner, en passant une chaîne de caractère vide au callback annulera la requête.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\napp.commandLine.appendSwitch('enable-experimental-web-platform-features')\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {\n event.preventDefault()\n const result = deviceList.find((device) => {\n return device.deviceName === 'test'\n })\n if (!result) {\n callback('')\n } else {\n callback(result.deviceId)\n }\n })\n})\nRetourne :
\nevent EventdirtyRect Rectangleimage NativeImage - Les données de l'image du frame entier.Emitted when a new frame is generated. Only the dirty area is passed in the buffer.
\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ webPreferences: { offscreen: true } })\nwin.webContents.on('paint', (event, dirty, image) => {\n // updateBitmap(dirty, image.getBitmap())\n})\nwin.loadURL('http://github.com')\nÉmis quand la fenêtre des outils développeur demande aux webContents de se recharger
\nRetourne :
\nevent EventwebPreferences WebPreferences - The web preferences that will be used by the guest page. This object can be modified to adjust the preferences for the guest page.params Record<string, string> - The other <webview> parameters such as the src URL. This object can be modified to adjust the parameters of the guest page.Emitted when a <webview>'s web contents is being attached to this web contents. Calling event.preventDefault() will destroy the guest page.
This event can be used to configure webPreferences for the webContents of a <webview> before it's loaded, and provides the ability to set settings that can't be set via <webview> attributes.
Note: The specified preload script option will appear as preloadURL (not preload) in the webPreferences object emitted with this event.
Retourne :
\nevent EventwebContents WebContents - Les contenus web invités qui sont utilisés par <webview>.Émis quand un <webview> a été rattaché à ce contenu web.
Retourne :
\nevent Eventlevel Integer - The log level, from 0 to 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Integer - The line number of the source that triggered this console messagesourceId StringEmitted when the associated window logs a console message.
\nRetourne :
\nevent EventpreloadPath Stringerror ErrorEmitted when the preload script preloadPath throws an unhandled exception error.
Retourne :
\nevent Eventchannel String...args any[]Emitted when the renderer process sends an asynchronous message via ipcRenderer.send().
Retourne :
\nevent Eventchannel String...args any[]Emitted when the renderer process sends a synchronous message via ipcRenderer.sendSync().
Retourne :
\nevent EventEmitted when desktopCapturer.getSources() is called in the renderer process. L' Appel à event.preventDefault() lui fera retourner des sources vides.
Retourne :
\nevent EventpreferredSize Size - The minimum size needed to contain the layout of the document—without requiring scrolling.Emitted when the WebContents preferred size has changed.
This event will only be emitted when enablePreferredSizeMode is set to true in webPreferences.
Retourne :
\nevent Eventdetailsframe WebFrameMainEmitted when the mainFrame, an <iframe>, or a nested <iframe> is loaded within the page.
contents.loadURL(url[, options])url Stringoptions Object (facultatif)httpReferrer (String | Referrer) (optional) - An HTTP Referrer url.userAgent String (optionnel) - Un agent utilisateur d'où provient la requête.extraHeaders String (optional) - Extra headers separated by \"\\n\".postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url is a data url and needs to load other files.Returns Promise<void> - the promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load). A noop rejection handler is already attached, which avoids unhandled rejection errors.
Loads the url in the window. The url must contain the protocol prefix, e.g. the http:// or file://. If the load should bypass http cache then use the pragma header to achieve it.
const { webContents } = require('electron')\nconst options = { extraHeaders: 'pragma: no-cache\\n' }\nwebContents.loadURL('https://github.com', options)\ncontents.loadFile(filePath[, options])filePath Stringoptions Object (facultatif)query Enregistrement<String, String> (facultatif) - Passé à url.format().search String (facultatif) - Passé à url.format().hash String (facultatif) - Passé à url.format().Retourne Promise<void> - la promesse se résoudra lorsque la page aura terminé le chargement (voir did-finish-load), et rejette si la page ne parvient pas à se charger (voir did-fail-load).
Loads the given file in the window, filePath should be a path to an HTML file relative to the root of your application. For instance an app structure like this:
| root\n| - package.json\n| - src\n| - main.js\n| - index.html\nWould require code like this
\nwin.loadFile('src/index.html')\ncontents.downloadURL(url)url StringInitiates a download of the resource at url without navigating. The will-download event of session will be triggered.
contents.getURL()Retourne String - l'URL de la page web courante.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com').then(() => {\n const currentURL = win.webContents.getURL()\n console.log(currentURL)\n})\ncontents.getTitle()Retourne String - le titre de la page web courante.
contents.isDestroyed()Retourne Boolean - si la page web est détruite.
contents.focus()Met au premier plan la page web.
\ncontents.isFocused()Retourne Boolean - si la page web est au premier plan.
contents.isLoading()Retourne Boolean - Si la page web est toujours en train de charger des ressources.
contents.isLoadingMainFrame()Retourne Boolean - Si la frame principale (et pas seulement un iframe ou frames qu'il contient) sont toujours en chargement.
contents.isWaitingForResponse()Retourne Boolean - Si la page web est en attente d'une première réponse de la principale ressource de la page.
contents.stop()Arrête toute navigation en attente.
\ncontents.reload()Recharge la page web courante.
\ncontents.reloadIgnoringCache()Recharge la page courante et ignore le cache.
\ncontents.canGoBack()Returns Boolean - Whether the browser can go back to previous web page.
contents.canGoForward()Returns Boolean - Whether the browser can go forward to next web page.
contents.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the web page can go to offset.
contents.clearHistory()Efface l'historique de navigation.
\ncontents.goBack()Makes the browser go back a web page.
\ncontents.goForward()Makes the browser go forward a web page.
\ncontents.goToIndex(index)index IntegerNavigates browser to the specified absolute web page index.
\ncontents.goToOffset(offset)offset IntegerNavigates to the specified offset from the \"current entry\".
\ncontents.isCrashed()Returns Boolean - Whether the renderer process has crashed.
contents.forcefullyCrashRenderer()Forcefully terminates the renderer process that is currently hosting this webContents. Cela provoquera l'émission de l'événement render-process-gone indiquant la cause avec reason=killed || reason=crashed. Please note that some webContents share renderer processes and therefore calling this method may also crash the host process for other webContents as well.
Calling reload() immediately after calling this method will force the reload to occur in a new process. This should be used when this process is unstable or unusable, for instance in order to recover from the unresponsive event.
contents.on('unresponsive', async () => {\n const { response } = await dialog.showMessageBox({\n message: 'App X has become unresponsive',\n title: 'Do you want to try forcefully reloading the app?',\n buttons: ['OK', 'Cancel'],\n cancelId: 1\n })\n if (response === 0) {\n contents.forcefullyCrashRenderer()\n contents.reload()\n }\n})\ncontents.setUserAgent(userAgent)userAgent StringOverrides the user agent for this web page.
\ncontents.getUserAgent()Returns String - The user agent for this web page.
contents.insertCSS(css[, options])css Stringoptions Object (facultatif)cssOrigin String (optional) - Can be either 'user' or 'author'; Specifying 'user' enables you to prevent websites from overriding the CSS you insert. Default is 'author'.Returns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via contents.removeInsertedCSS(key).
Injecte du CSS dans la page Web actuelle et renvoie une clé unique pour la feuille de style insérée .
\ncontents.on('did-finish-load', () => {\n contents.insertCSS('html, body { background-color: #f00; }')\n})\ncontents.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from contents.insertCSS(css).
contents.on('did-finish-load', async () => {\n const key = await contents.insertCSS('html, body { background-color: #f00; }')\n contents.removeInsertedCSS(key)\n})\ncontents.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (facultatif) - false par défaut.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Évalue le code dans la page.
Dans la fenêtre du navigateur, certaines APIs HTML comme requestFullScreen peut être invoqué seulement par un geste de l'utilisateur. Définir userGesture à true supprimera cette limitation.
L'exécution du code sera suspendue jusqu'à la fin du chargement de la page web.
\ncontents.executeJavaScript('fetch(\"https://jsonplaceholder.typicode.com/users/1\").then(resp => resp.json())', true)\n .then((result) => {\n console.log(result) // Will be the JSON object from the fetch call\n })\ncontents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electron's contextIsolation feature. You can provide any integer here.scripts WebSource[]userGesture Boolean (facultatif) - false par défaut.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Works like executeJavaScript but evaluates scripts in an isolated context.
contents.setIgnoreMenuShortcuts(ignore)ignore BooleanIgnore application menu shortcuts while this web contents is focused.
\ncontents.setWindowOpenHandler(handler)handler Function<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>
detailsurlFiche-La _version_resolue du URL envoyee afenetre.ouverte{}. par ex. ouvrir une fenetre avecfenetre.ouverte ('foo')va generer une chose commehttps://the-origin/the/current/path/foo.NommargeFiche-Nom de fenetre fourni a window.open=fenetre.ouverte()traitsFiche-Une liste de traits de fenetre separee par comas, a ete fournie awindow.open().disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk or other.referrer Referrer - Le parrain qui sera passé à la nouvelle fenêtre. Peut ou ne peut pas entraîner l'envoi de l'en-tête Référent en fonction de la politique du référent.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.Va donner {action: 'deny'} | {action: 'permettre', surpasserOptionsduNavigateurFenetreBrowser?: OptionsConstructeurNavigateursFenetre}- - refuser va supprimer la creation dans la fenetre nouvelle. permettreva permettre la creation d'une fenetre nouvelle. Specifying overrideBrowserWindowOptions allows customization of the created window. Returning an unrecognized value such as a null, undefined, or an object without a recognized 'action' value will result in a console error and have the same effect as returning {action: 'deny'}.
Called before creating a window a new window is requested by the renderer, e.g. by window.open(), a link with target=\"_blank\", shift+clicking on a link, or submitting a form with <form target=\"_blank\">. See window.open() for more details and how to use this in conjunction with did-create-window.
contents.setAudioMuted(muted)muted BooleanMute the audio on the current web page.
\ncontents.isAudioMuted()Returns Boolean - Whether this page has been muted.
contents.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
contents.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Modifie le facteur de zoom en utilisant le facteur spécifié. Le Zoom factor est égal à la valeur du zoom exprimée en pourcent divisée par 100, donc 300% = 3.0.
\nLe rapport doit être supérieur à 0.0.
\ncontents.getZoomFactor()Returns Number - the current zoom factor.
contents.setZoomLevel(level)level Number - Niveau de zoom.Modifie le niveau de zoom jusqu'au niveau spécifié. La taille originale est de 0 et chaque incrément au-dessus ou en dessous représente un zoom de 20% supérieur ou inférieure jusqu'au limites de 300% et 50% de la taille originale, respectivement. La formule pour cela est 'scale:= 1,2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
contents.getZoomLevel()Returns Number - the current zoom level.
contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberRetourne Promise<void>
Définit le niveau maximum et minimum le niveau pinch-to-zoom.
\n\n\nNOTE: Le zoom visuel est désactivé par défaut dans Electron. To re-enable it, call:
\n\ncontents.setVisualZoomLevelLimits(1, 3)\n
contents.undo()Executes the editing command undo in web page.
contents.redo()Executes the editing command redo in web page.
contents.cut()Executes the editing command cut in web page.
contents.copy()Executes the editing command copy in web page.
contents.copyImageAt(x, y)x Integery IntegerCopy the image at the given position to the clipboard.
\ncontents.paste()Executes the editing command paste in web page.
contents.pasteAndMatchStyle()Executes the editing command pasteAndMatchStyle in web page.
contents.delete()Executes the editing command delete in web page.
contents.selectAll()Executes the editing command selectAll in web page.
contents.unselect()Executes the editing command unselect in web page.
contents.replace(text)text StringExecutes the editing command replace in web page.
contents.replaceMisspelling(text)text StringExecutes the editing command replaceMisspelling in web page.
contents.insertText(text)text StringRetourne Promise<void>
Insère le text à l'élément ciblé.
contents.findInPage(text[, options])text String - Content to be searched, must not be empty.options Object (facultatif)forward Boolean (facultatif) - Rechercher soit en avant soit en arrière, la valeur par défaut est true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Doit être true pour les requêtes initiales et false pour les requêtes de suivi. Par défaut, faux.matchCase Boolean (optional) - Whether search should be case-sensitive, defaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. Le résultat de la requête peut être obtenu en s'abonnant à l'événement found-in-page.
contents.stopFindInPage(action)action String - Specifies the action to take place when ending [webContents.findInPage] request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webContents with the provided action.
const { webContents } = require('electron')\nwebContents.on('found-in-page', (event, result) => {\n if (result.finalUpdate) webContents.stopFindInPage('clearSelection')\n})\n\nconst requestId = webContents.findInPage('api')\nconsole.log(requestId)\ncontents.capturePage([rect])rect Rectangle (optionnel) - La zone de la page dont on doit réaliser la capture.Retourne Promise<NativeImage> - résout avec une NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page.
contents.isBeingCaptured()Returns Boolean - Whether this page is being captured. It returns true when the capturer count is large then 0.
contents.incrementCapturerCount([size, stayHidden, stayAwake])size Size (optional) - The preferred size for the capturer.stayHidden Boolean (optional) - Keep the page hidden instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Increase the capturer count by one. The page is considered visible when its browser window is hidden and the capturer count is non-zero. If you would like the page to stay hidden, you should ensure that stayHidden is set to true.
This also affects the Page Visibility API.
\ncontents.decrementCapturerCount([stayHidden, stayAwake])stayHidden Boolean (optional) - Keep the page in hidden state instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Decrease the capturer count by one. The page will be set to hidden or occluded state when its browser window is hidden or occluded and the capturer count reaches zero. If you want to decrease the hidden capturer count instead you should set stayHidden to true.
contents.getPrinters()Récupère la liste des imprimantes système.
\nReturns PrinterInfo[]
contents.print([options], [callback])options Object (facultatif)silent Boolean (optional) - Don't ask user for print settings. Par défaut la valeur est false.printBackground Boolean (optional) - Prints the background color and image of the web page. Par défaut la valeur est false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. La valeur par défaut est vraie.margins Object (facultatif)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. Par défaut la valeur est false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print. Sur macOS, une seule plage est respectée.from Number - Index de la première page à imprimer (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Can be simplex, shortEdge, or longEdge.dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.callback Function (facultatif)success Boolean - Indicates success of the print call.failureReason String - Error description called back if the print fails.When a custom pageSize is passed, Chromium attempts to validate platform specific minimum values for width_microns and height_microns. Width and height must both be minimum 353 microns but may be higher on some operating systems.
Prints window's web page. When silent is set to true, Electron will pick the system's default printer if deviceName is empty and the default settings for printing.
Use page-break-before: always; CSS style to force to print to a new page.
Exemple d'utilisation :
\nconst options = {\n silent: true,\n deviceName: 'My-Printer',\n pageRanges: [{\n from: 0,\n to: 1\n }]\n}\nwin.webContents.print(options, (success, errorType) => {\n if (!success) console.log(errorType)\n})\ncontents.printToPDF(options)optionsheaderFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print.from Number - Index de la première page à imprimer (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height and width in microns.printBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Buffer> - Resolves with the generated PDF data.
Prints window's web page as PDF with Chromium's preview printing custom settings.
\nThe landscape will be ignored if @page CSS at-rule is used in the web page.
By default, an empty options will be regarded as:
{\n marginsType: 0,\n printBackground: false,\n printSelectionOnly: false,\n landscape: false,\n pageSize: 'A4',\n scaleFactor: 100\n}\nUse page-break-before: always; CSS style to force to print to a new page.
An example of webContents.printToPDF:
const { BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\nconst os = require('os')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nwin.webContents.on('did-finish-load', () => {\n // Use default printing options\n win.webContents.printToPDF({}).then(data => {\n const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')\n fs.writeFile(pdfPath, data, (error) => {\n if (error) throw error\n console.log(`Wrote PDF successfully to ${pdfPath}`)\n })\n }).catch(error => {\n console.log(`Failed to write PDF to ${pdfPath}: `, error)\n })\n})\ncontents.addWorkSpace(path)path StringAjoute le chemin spécifié à l'espace de travail des DevTools. Doit être utilisé après la création des DevTools :
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.on('devtools-opened', () => {\n win.webContents.addWorkSpace(__dirname)\n})\ncontents.removeWorkSpace(path)path StringRemoves the specified path from DevTools workspace.
\ncontents.setDevToolsWebContents(devToolsWebContents)devToolsWebContents WebContentsUses the devToolsWebContents as the target WebContents to show devtools.
The devToolsWebContents must not have done any navigation, and it should not be used for other purposes after the call.
By default Electron manages the devtools by creating an internal WebContents with native view, which developers have very limited control of. With the setDevToolsWebContents method, developers can use any WebContents to show the devtools in it, including BrowserWindow, BrowserView and <webview> tag.
Note that closing the devtools does not destroy the devToolsWebContents, it is caller's responsibility to destroy devToolsWebContents.
An example of showing devtools in a <webview> tag:
<html>\n<head>\n <style type=\"text/css\">\n * { margin: 0; }\n #browser { height: 70%; }\n #devtools { height: 30%; }\n </style>\n</head>\n<body>\n <webview id=\"browser\" src=\"https://github.com\"></webview>\n <webview id=\"devtools\" src=\"about:blank\"></webview>\n <script>\n const { ipcRenderer } = require('electron')\n const emittedOnce = (element, eventName) => new Promise(resolve => {\n element.addEventListener(eventName, event => resolve(event), { once: true })\n })\n const browserView = document.getElementById('browser')\n const devtoolsView = document.getElementById('devtools')\n const browserReady = emittedOnce(browserView, 'dom-ready')\n const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')\n Promise.all([browserReady, devtoolsReady]).then(() => {\n const targetId = browserView.getWebContentsId()\n const devtoolsId = devtoolsView.getWebContentsId()\n ipcRenderer.send('open-devtools', targetId, devtoolsId)\n })\n </script>\n</body>\n</html>\n// Main process\nconst { ipcMain, webContents } = require('electron')\nipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {\n const target = webContents.fromId(targetContentsId)\n const devtools = webContents.fromId(devtoolsContentsId)\n target.setDevToolsWebContents(devtools)\n target.openDevTools()\n})\nAn example of showing devtools in a BrowserWindow:
const { app, BrowserWindow } = require('electron')\n\nlet win = null\nlet devtools = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n devtools = new BrowserWindow()\n win.loadURL('https://github.com')\n win.webContents.setDevToolsWebContents(devtools.webContents)\n win.webContents.openDevTools({ mode: 'detach' })\n})\ncontents.openDevTools([options])options Object (facultatif)mode String - Opens the devtools with specified dock state, can be right, bottom, undocked, detach. Defaults to last used dock state. In undocked mode it's possible to dock back. In detach mode it's not.activate Boolean (optional) - Whether to bring the opened devtools window to the foreground. Par défaut, true.Ouvre les devtools.
\nWhen contents is a <webview> tag, the mode would be detach by default, explicitly passing an empty mode can force using last used dock state.
contents.closeDevTools()Ferme les devtools.
\ncontents.isDevToolsOpened()Retourne Boolean - Si les devtools sont ouvert.
contents.isDevToolsFocused()Retourne Boolean - Si les devtools ont le focus.
contents.toggleDevTools()Active/désactive les outils développeur.
\ncontents.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y).
contents.inspectSharedWorker()Opens the developer tools for the shared worker context.
\ncontents.inspectSharedWorkerById(workerId)workerId StringInspects the shared worker based on its ID.
\ncontents.getAllSharedWorkers()Returns SharedWorkerInfo[] - Information about all Shared Workers.
contents.inspectServiceWorker()Opens the developer tools for the service worker context.
\ncontents.send(channel, ...args)channel String...args any[]Send an asynchronous message to the renderer process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the ipcRenderer module.
An example of sending messages from the main process to the renderer process:
\n// Dans le processus main.\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL(`file://${__dirname}/index.html`)\n win.webContents.on('did-finish-load', () => {\n win.webContents.send('ping', 'whoooooooh!')\n })\n})\n<!-- index.html -->\n<html>\n<body>\n <script>\n require('electron').ipcRenderer.on('ping', (event, message) => {\n console.log(message) // Prints 'whoooooooh!'\n })\n </script>\n</body>\n</html>\ncontents.sendToFrame(frameId, channel, ...args)frameId Integer | [number, number] - the ID of the frame to send to, or a pair of [processId, frameId] if the frame is in a different process to the main frame.channel String...args any[]Send an asynchronous message to a specific frame in a renderer process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the ipcRenderer module.
If you want to get the frameId of a given renderer context you should use the webFrame.routingId value. Exemple :
// In a renderer process\nconsole.log('My frameId is:', require('electron').webFrame.routingId)\nYou can also read frameId from all incoming IPC messages in the main process.
// In the main process\nipcMain.on('ping', (event) => {\n console.info('Message came from frameId:', event.frameId)\n})\ncontents.postMessage(channel, message, [transfer])Envoie un message au processus de rendu en effectuant éventuellement un transfert de propriété de zéro ou plus objets de type [MessagePortMain][].
Les objets MessagePortMain transférés seront disponibles dans le processus de rendu en accédant à la propriété ports de l'événement émis. Ils seront des objets DOM MessagePort natifs en arrivant dans le moteur de rendu.
Par exemple :
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\ncontents.enableDeviceEmulation(parameters)parametersscreenPosition String - Specify the screen type to emulate (default: desktop):desktop - Desktop screen type.mobile - Mobile screen type.screenSize Size - Set the emulated screen size (screenPosition == mobile).viewPosition Point - Position the view on the screen (screenPosition == mobile) (default: { x: 0, y: 0 }).deviceScaleFactor Integer - Set the device scale factor (if zero defaults to original device scale factor) (default: 0).viewSize Size - Set the emulated view size (empty means no override)scale Float - Scale of emulated view inside available space (not in fit to view mode) (default: 1).Enable device emulation with the given parameters.
\ncontents.disableDeviceEmulation()Disable device emulation enabled by webContents.enableDeviceEmulation.
contents.sendInputEvent(inputEvent)inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventSends an input event to the page. Note: The BrowserWindow containing the contents needs to be focused for sendInputEvent() to work.
contents.beginFrameSubscription([onlyDirty ,]callback)onlyDirty Boolean (optionnel) - false par défaut.callback Functionimage NativeImagedirtyRect RectangleBegin subscribing for presentation events and captured frames, the callback will be called with callback(image, dirtyRect) when there is a presentation event.
The image is an instance of NativeImage that stores the captured frame.
The dirtyRect is an object with x, y, width, height properties that describes which part of the page was repainted. If onlyDirty is set to true, image will only contain the repainted area. onlyDirty defaults to false.
contents.endFrameSubscription()End subscribing for frame presentation events.
\ncontents.startDrag(item)itemfile String - The path to the file being dragged.files String - The paths to the files being dragged. (files will override file field)icon NativeImage | String - The image must be non-empty on macOS.Sets the item as dragging item for current drag-drop operation, file is the absolute path of the file to be dragged, and icon is the image showing under the cursor when dragging.
contents.savePage(fullPath, saveType)fullPath String - The full file path.saveType String - Specify the save type.HTMLOnly - Save only the HTML of the page.HTMLComplete - Save complete-html page.MHTML - Save complete-html page as MHTML.Returns Promise<void> - resolves if the page is saved.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.loadURL('https://github.com')\n\nwin.webContents.on('did-finish-load', async () => {\n win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {\n console.log('Page was saved successfully.')\n }).catch(err => {\n console.log(err)\n })\n})\ncontents.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\ncontents.isOffscreen()Returns Boolean - Indicates whether offscreen rendering is enabled.
contents.startPainting()If offscreen rendering is enabled and not painting, start painting.
\ncontents.stopPainting()If offscreen rendering is enabled and painting, stop painting.
\ncontents.isPainting()Returns Boolean - If offscreen rendering is enabled returns whether it is currently painting.
contents.setFrameRate(fps)fps IntegerIf offscreen rendering is enabled sets the frame rate to the specified number. Only values between 1 and 240 are accepted.
\ncontents.getFrameRate()Returns Integer - If offscreen rendering is enabled returns the current frame rate.
contents.invalidate()Schedules a full repaint of the window this web contents is in.
\nIf offscreen rendering is enabled invalidates the frame and generates a new one through the 'paint' event.
contents.getWebRTCIPHandlingPolicy()Returns String - Returns the WebRTC IP Handling Policy.
contents.setWebRTCIPHandlingPolicy(policy)policy String - Specify the WebRTC IP Handling Policy.default - Exposes user's public and local IPs. C’est le comportement par défaut. When this policy is used, WebRTC has the right to enumerate all interfaces and bind them to discover public interfaces.default_public_interface_only - Exposes user's public IP, but does not expose user's local IP. When this policy is used, WebRTC should only use the default route used by http. This doesn't expose any local addresses.default_public_and_private_interfaces - Exposes user's public and local IPs. When this policy is used, WebRTC should only use the default route used by http. This also exposes the associated default private address. Default route is the route chosen by the OS on a multi-homed endpoint.disable_non_proxied_udp - Does not expose public or local IPs. When this policy is used, WebRTC should only use TCP to contact peers or servers unless the proxy server supports UDP.Setting the WebRTC IP handling policy allows you to control which IPs are exposed via WebRTC. See BrowserLeaks for more details.
\ncontents.getOSProcessId()Returns Integer - The operating system pid of the associated renderer process.
contents.getProcessId()Returns Integer - The Chromium internal pid of the associated renderer. Can be compared to the frameProcessId passed by frame specific navigation events (e.g. did-frame-navigate)
contents.takeHeapSnapshot(filePath)filePath String - Chemin vers le fichier de sortie.Retourne Promise<void> - Indique si l'instantané a été créé avec succès.
Prend un instantané de tas V8 et l'enregistre dans filePath.
contents.getBackgroundThrottling()Returns Boolean - whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
contents.setBackgroundThrottling(allowed)allowed BooleanControls whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
\ncontents.getType()Returns String - the type of the webContent. Can be backgroundPage, window, browserView, remote, webview or offscreen.
contents.setImageAnimationPolicy(policy)policy Chaîne de caratères - Peut être animate, animateOnce ou noAnimation.Sets the image animation policy for this webContents. The policy only affects new images, existing images that are currently being animated are unaffected. This is a known limitation in Chromium, you can force image animation to be recalculated with img.src = img.src which will result in no network traffic but will update the animation policy.
This corresponds to the animationPolicy accessibility feature in Chromium.
\ncontents.audioMutedA Boolean property that determines whether this page is muted.
contents.userAgentA String property that determines the user agent for this web page.
contents.zoomLevelA Number property that determines the zoom level for this web contents.
The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
contents.zoomFactorA Number property that determines the zoom factor for this web contents.
The zoom factor is the zoom percent divided by 100, so 300% = 3.0.
\ncontents.frameRateAn Integer property that sets the frame rate of the web contents to the specified number. Only values between 1 and 240 are accepted.
Only applicable if offscreen rendering is enabled.
\ncontents.id Lecture seuleA Integer representing the unique ID of this WebContents. Chaque ID est unique parmi ceux des instances de WebContents de l'application Electron.
contents.session Lecture seuleA Session used by this webContents.
contents.hostWebContents Lecture seuleA WebContents instance that might own this WebContents.
contents.devToolsWebContents Lecture seuleA WebContents | null property that represents the of DevTools WebContents associated with a given WebContents.
Note: Users should never store this object because it may become null when the DevTools has been closed.
contents.debugger Lecture seuleA Debugger instance for this webContents.
contents.backgroundThrottlingA Boolean property that determines whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
contents.mainFrame Lecture seuleA WebFrameMain property that represents the top frame of the page's frame hierarchy.
Pour intégrer du contenu web (tiers) dans une BrowserWindow d'Electron vous disposez des trois options suivantes: soit les balises <iframe> ou <webview> soit en utilisant les BrowserViews. Chacune offre des fonctionnalités légèrement différentes et utile dans des situations différentes. Pour vous aider dans votre choix, ce guide explique les différences et les capacités de chaque option.
Iframes in Electron behave like iframes in regular browsers. Un élément <iframe> dans votre page peut afficher des pages web externes, à condition que leur Content Security Policy le permette. Pour limiter les fonctionnalités d’un site dans une balise <iframe> , il est recommandé d’utiliser l’attribut sandbox et d’autoriser uniquement les fonctionnalités que vous souhaitez prendre en charge.
\n\nNote importante : nous vous déconseillons d'utiliser WebViews, car cette balise subit des changements architecturaux dramatiques qui peuvent affecter la stabilité de votre application. Envisagez de basculer vers les alternatives,
\niframe, Electron'sBrowserViewou une architecture évitant par sa conception d'embarquer du contenu.
Les WebViews sont basées sur les WebViews de Chromium et ne sont pas explicitement supportés par Electron. Nous ne garantissons pas que l'API WebView restera disponible dans les futures versions d'Electron. Pour utiliser les balises <webview> , vous devrez définir webviewTag à true dans les webPreferences de votre BrowserWindow.
WebView est un élément personnalisé (<webview>) qui ne fonctionnera qu'à l'intérieur d'Electron. They are implemented as an \"out-of-process iframe\". Cela signifie que toute la communication avec la <webview> est faite de manière asynchrone en utilisant IPC. L'élément <webview> possède de nombreuses méthodes et événements personnalisés, similaire à webContents, qui vous donnent un grand contrôle sur le contenu.
Comparé à un <iframe>, <webview> tend à être légèrement plus lent, mais offre un contrôle beaucoup plus important dans le chargement et la communication avec le contenu tiers et la gestion de divers événements.
Les BrowserViews sont créés et pilotés par votre processus principal et ne font pas partie du DOM . Ils sont simplement une couche supplémentaire de contenu web au dessus de votre fenêtre existante. Cela signifie qu'ils sont complètement séparés du contenu de votre BrowserWindow et leur position n'est contrôlée ni par le DOM ni par le CSS. Au lieu de cela, elle est contrôlée en définissant les limites dans le processus principal.
BrowserViews offre le meilleur contrôle sur leur contenu, car ils implémentent le webContents de la même façon que la BrowserWindow. Cependant, comme les BrowserViews ne font pas partie de votre DOM étant plutôt superposés par dessus , vous devrez gérer leur position manuellement.
\n\nPersonnaliser le rendu de la page web actuelle.
\n
Processus : Renderer
\nwebFrame export of the Electron module is an instance of the WebFrame class representing the top frame of the current BrowserWindow. Sub-frames can be retrieved by certain properties and methods (e.g. webFrame.firstChild).
Un exemple d'un zoom de 200% de la page actuelle.
\nconst { webFrame } = require('electron')\n\nwebFrame.setZoomFactor(2)\nThe WebFrame class has the following instance methods:
webFrame.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Modifie le facteur de zoom en utilisant le facteur spécifié. Le Zoom factor est égal à la valeur du zoom exprimée en pourcent divisée par 100, donc 300% = 3.0.
\nLe rapport doit être supérieur à 0.0.
\nwebFrame.getZoomFactor()Retourne Number - Le facteur de zoom actuel.
webFrame.setZoomLevel(level)level Number - Niveau de zoom.Modifie le niveau de zoom jusqu'au niveau spécifié. La taille originale est de 0 et chaque incrément au-dessus ou en dessous représente un zoom de 20% supérieur ou inférieure jusqu'au limites de 300% et 50% de la taille originale, respectivement.
\n\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
webFrame.getZoomLevel()Retourne Number - Le niveau de zoom actuel.
webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberDéfinit le niveau maximum et minimum le niveau pinch-to-zoom.
\n\n\nNOTE: Le zoom visuel est désactivé par défaut dans Electron. To re-enable it, call:
\n\nwebFrame.setVisualZoomLevelLimits(1, 3)\n
\n\nNOTE: Le zoom visuel s'applique uniquement au comportement pinch-to-zoom. Les raccourcis de zoom Cmd+/-/0 sont contrôlés par les rôles des MenuItem 'zoomIn', 'zoomOut' et 'resetZoom' dans le menu de l'application. Pour désactiver les raccourcis, définissez manuellement le Menu et omettez les rôles de zoom de la définition.
\n
webFrame.setSpellCheckProvider(language, provider)language StringproviderspellCheck Functionwords String[]callback FunctionmisspeltWords String[]Définit un fournisseur pour la correction orthographique dans les champs de saisie et les zones de texte.
\nIf you want to use this method you must disable the builtin spellchecker when you construct the window.
\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: false\n }\n})\nThe provider must be an object that has a spellCheck method that accepts an array of individual words for spellchecking. The spellCheck function runs asynchronously and calls the callback function with an array of misspelt words when complete.
Un exemple d'utilisation de node-spellchecker comme fournisseur :
\nconst { webFrame } = require('electron')\nconst spellChecker = require('spellchecker')\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck (words, callback) {\n setTimeout(() => {\n const spellchecker = require('spellchecker')\n const misspelled = words.filter(x => spellchecker.isMisspelled(x))\n callback(misspelled)\n }, 0)\n }\n})\nwebFrame.insertCSS(css)css String - CSS source code.Returns String - A key for the inserted CSS that can later be used to remove the CSS via webFrame.removeInsertedCSS(key).
Injecte du CSS dans la page Web actuelle et renvoie une clé unique pour la feuille de style insérée .
\nwebFrame.removeInsertedCSS(key)key StringRemoves the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from webFrame.insertCSS(css).
webFrame.insertText(text)text StringInsère le text à l'élément ciblé.
webFrame.executeJavaScript(code[, userGesture, callback])code StringuserGesture Boolean (facultatif) - false par défaut.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.result Anyerror ErrorReturns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
Évalue le code dans la page.
Dans la fenêtre du navigateur, certaines APIs HTML comme requestFullScreen peut être invoqué seulement par un geste de l'utilisateur. Définir userGesture à true supprimera cette limitation.
webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])worldId Integer - The ID of the world to run the javascript in, 0 is the default main world (where content runs), 999 is the world used by Electron's contextIsolation feature. Accepts values in the range 1..536870911.scripts WebSource[]userGesture Boolean (facultatif) - false par défaut.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.result Anyerror ErrorReturns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution could not start.
Works like executeJavaScript but evaluates scripts in an isolated context.
Note that when the execution of script fails, the returned promise will not reject and the result would be undefined. This is because Chromium does not dispatch errors of isolated worlds to foreign worlds.
webFrame.setIsolatedWorldInfo(worldId, info)worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electrons contextIsolation feature. Chrome extensions reserve the range of IDs in [1 << 20, 1 << 29). You can provide any integer here.infosecurityOrigin String (optional) - Security origin for the isolated world.csp String (optional) - Content Security Policy for the isolated world.name String (optional) - Name for isolated world. Useful in devtools.Set the security origin, content security policy and name of the isolated world. Note: If the csp is specified, then the securityOrigin also has to be specified.
webFrame.getResourceUsage()Retourne Object:
images MemoryUsageDetailsscripts MemoryUsageDetailscssStyleSheets MemoryUsageDetailsxslStyleSheets MemoryUsageDetailsfonts MemoryUsageDetailsother MemoryUsageDetailsRetourne un objet décrivant les informations d'utilisation de caches de mémoire interne de Blink.
\nconst { webFrame } = require('electron')\nconsole.log(webFrame.getResourceUsage())\nCela va générer :
\n{\n images: {\n count: 22,\n size: 2549,\n liveSize: 2542\n },\n cssStyleSheets: { /* pareil qu'avec \"images\" */ },\n xslStyleSheets: { /* pareil qu'avec \"images\" */ },\n fonts: { /* pareil qu'avec \"images\" */ },\n other: { /* pareil qu'avec \"images\" */ }\n}\nwebFrame.clearCache()Tente de libérer de la mémoire qui n'est plus utilisée (comme les images d'une navigation précédente).
\nNotez que le fait d'appeler aveuglément cette méthode rend probablement Electron plus lent car il devra remplir ces caches vides, vous ne devriez l'appeler que si un événement dans votre application s'est produit vous faisant penser que votre page utilise réellement moins mémoire (c. -à-d. que vous avez navigué d'une page super lourde à une page presque vide, et avez l'intention d'y rester).
\nwebFrame.getFrameForSelector(selector)selector String - CSS selector for a frame element.Returns WebFrame - The frame element in webFrame's document selected by selector, null would be returned if selector does not select a frame or if the frame is not in the current renderer process.
webFrame.findFrameByName(name)name StringReturns WebFrame - A child of webFrame with the supplied name, null would be returned if there's no such frame or if the frame is not in the current renderer process.
webFrame.findFrameByRoutingId(routingId)routingId Integer - An Integer representing the unique frame id in the current renderer process. Routing IDs can be retrieved from WebFrame instances (webFrame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate)Returns WebFrame - that has the supplied routingId, null if not found.
webFrame.isWordMisspelled(word)word String - The word to be spellchecked.Returns Boolean - True if the word is misspelled according to the built in spellchecker, false otherwise. If no dictionary is loaded, always return false.
webFrame.getWordSuggestions(word)word String - The misspelled word.Returns String[] - A list of suggested words for a given word. If the word is spelled correctly, the result will be empty.
webFrame.top Lecture seuleA WebFrame | null representing top frame in frame hierarchy to which webFrame belongs, the property would be null if top frame is not in the current renderer process.
webFrame.opener Lecture seuleA WebFrame | null representing the frame which opened webFrame, the property would be null if there's no opener or opener is not in the current renderer process.
webFrame.parent Lecture seuleA WebFrame | null representing parent frame of webFrame, the property would be null if webFrame is top or parent is not in the current renderer process.
webFrame.firstChild Lecture seuleA WebFrame | null representing the first child frame of webFrame, the property would be null if webFrame has no children or if first child is not in the current renderer process.
webFrame.nextSibling Lecture seuleA WebFrame | null representing next sibling frame, the property would be null if webFrame is the last frame in its parent or if the next sibling is not in the current renderer process.
webFrame.routingId Lecture seuleAn Integer representing the unique frame id in the current renderer process. Distinct WebFrame instances that refer to the same underlying frame will have the same routingId.
\n\nControl web pages and iframes.
\n
Processus : Main
\nThe webFrameMain module can be used to lookup frames across existing WebContents instances. Navigation events are the common use case.
const { BrowserWindow, webFrameMain } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://twitter.com')\n\nwin.webContents.on(\n 'did-frame-navigate',\n (event, url, isMainFrame, frameProcessId, frameRoutingId) => {\n const frame = webFrameMain.fromId(frameProcessId, frameRoutingId)\n if (frame) {\n const code = 'document.body.innerHTML = document.body.innerHTML.replaceAll(\"heck\", \"h*ck\")'\n frame.executeJavaScript(code)\n }\n }\n)\nYou can also access frames of existing pages by using the mainFrame property of WebContents.
const { BrowserWindow } = require('electron')\n\nasync function main () {\n const win = new BrowserWindow({ width: 800, height: 600 })\n await win.loadURL('https://reddit.com')\n\n const youtubeEmbeds = win.webContents.mainFrame.frames.filter((frame) => {\n try {\n const url = new URL(frame.url)\n return url.host === 'www.youtube.com'\n } catch {\n return false\n }\n })\n\n console.log(youtubeEmbeds)\n}\n\nmain()\nThese methods can be accessed from the webFrameMain module:
webFrameMain.fromId(processId, routingId)processId Integer - An Integer representing the internal ID of the process which owns the frame.routingId Integer - An Integer representing the unique frame ID in the current renderer process. Routing IDs can be retrieved from WebFrameMain instances (frame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate).Returns WebFrameMain | undefined - A frame with the given process and routing IDs, or undefined if there is no WebFrameMain associated with the given IDs.
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emitted when the document is loaded.
\nframe.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (facultatif) - false par défaut.Returns Promise<unknown> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
Évalue le code dans la page.
Dans la fenêtre du navigateur, certaines APIs HTML comme requestFullScreen peut être invoqué seulement par un geste de l'utilisateur. Définir userGesture à true supprimera cette limitation.
frame.reload()Returns boolean - Whether the reload was initiated successfully. Only results in false when the frame has no history.
frame.send(channel, ...args)channel String...args any[]Send an asynchronous message to the renderer process via channel, along with arguments. Arguments will be serialized with the [Structured Clone Algorithm][SCA], just like [postMessage][], so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
The renderer process can handle the message by listening to channel with the ipcRenderer module.
frame.postMessage(channel, message, [transfer])Envoie un message au processus de rendu en effectuant éventuellement un transfert de propriété de zéro ou plus objets de type [MessagePortMain][].
Les objets MessagePortMain transférés seront disponibles dans le processus de rendu en accédant à la propriété ports de l'événement émis. Ils seront des objets DOM MessagePort natifs en arrivant dans le moteur de rendu.
Par exemple :
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nframe.url ReadonlyA string representing the current URL of the frame.
frame.top ReadonlyA WebFrameMain | null representing top frame in the frame hierarchy to which frame belongs.
frame.parent ReadonlyA WebFrameMain | null representing parent frame of frame, the property would be null if frame is the top frame in the frame hierarchy.
frame.frames ReadonlyA WebFrameMain[] collection containing the direct descendents of frame.
frame.framesInSubtree ReadonlyA WebFrameMain[] collection containing every frame in the subtree of frame, including itself. This can be useful when traversing through all frames.
frame.frameTreeNodeId ReadonlyAn Integer representing the id of the frame's internal FrameTreeNode instance. This id is browser-global and uniquely identifies a frame that hosts content. The identifier is fixed at the creation of the frame and stays constant for the lifetime of the frame. When the frame is removed, the id is not used again.
frame.name ReadonlyA String representing the frame name.
frame.osProcessId ReadonlyAn Integer representing the operating system pid of the process which owns this frame.
frame.processId ReadonlyAn Integer representing the Chromium internal pid of the process which owns this frame. This is not the same as the OS process ID; to read that use frame.osProcessId.
frame.routingId ReadonlyAn Integer representing the unique frame id in the current renderer process. Distinct WebFrameMain instances that refer to the same underlying frame will have the same routingId.
frame.visibilityState Lecture seuleA string representing the visibility state of the frame.
See also how the Page Visibility API is affected by other Electron APIs.
", "title": "webFrameMain", "description": "Control web pages and iframes." }, "/docs/api/web-request": { "locale": "fr-FR", "slug": "web-request", "href": "/docs/api/web-request", "crowdinFileId": "256405", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-request.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nIntercepte et modifie le contenu d'une requête à différents stades de son existence.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Les instances de la classe WebRequest sont accessibles à l'aide de la propriété WebRequest d'une Session.
Les méthodes de WebRequest acceptent un filter et un listener optionnels. Le listener va être appelé avec listener(details) quand l'événement de l'API est émis. L'objet details représente la requête.
⚠️ Only the last attached listener will be used. Passing null as listener will unsubscribe from the event.
L'objet filter a une propriété url qui est un tableau de modèles d'URL qui seront utilisés pour filtrer les requêtes qui ne satisfont pas aux modèles. . Si filter est omis, toutes les requêtes seront jugées comme conformes.
Pour certains événements, le listener est passé accompagné d'une callback, qui devrait être appelée avec un objet responselorsque le listener a fini son travail.
Un exemple d'ajout de l'en-tête User-Agent pour les requêtes :
const { session } = require('electron')\n\n// Modify the user agent for all requests to the following urls.\nconst filter = {\n urls: ['https://*.github.com/*', '*://electron.github.io']\n}\n\nsession.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {\n details.requestHeaders['User-Agent'] = 'MyAgent'\n callback({ requestHeaders: details.requestHeaders })\n})\nLes méthodes suivantes sont disponibles pour les instances de WebRequest :
webRequest.onBeforeRequest([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (facultatif)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleuploadData UploadData[]callback Functionresponsecancel Boolean)redirectURL String (facultatif) - Empêche la requête originale d'être envoyée ou complétée et à la place celle ci est redirigée vers l'URL donnée.Le listener sera appelé avec listener(détails, callback) lorsqu'une requête est sur le point de se produire.
Le uploadData est un tableau d'objets UploadData.
La callback doit être appelé avec un objet response.
Some examples of valid urls:
'http://foo:1234/'\n'http://foo.com/'\n'http://foo:1234/bar'\n'*://*/*'\n'*://example.com/*'\n'*://example.com/foo/*'\n'http://*.foo:1234/'\n'file://foo:1234/bar'\n'http://foo:*/'\n'*://www.foo.com/'\nwebRequest.onBeforeSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (facultatif)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders<string, string>callback FunctionbeforeSendResponsecancel Boolean)requestHeaders Record<string, string | string[]> (optional) - When provided, request will be made with these headers.The listener will be called with listener(details, callback) before sending an HTTP request, once the request headers are available. This may occur after a TCP connection is made to the server, but before any http data is sent.
The callback has to be called with a response object.
webRequest.onSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (facultatif)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders<string, string>The listener will be called with listener(details) just before a request is going to be sent to the server, modifications of previous onBeforeSendHeaders response are visible by the time this listener is fired.
webRequest.onHeadersReceived([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (facultatif)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublestatusLine StringstatusCode IntegerresponseHeaders Record<string, string[]> (optional)callback FunctionheadersReceivedResponsecancel Boolean)responseHeaders Record<string, string | string[]> (optional) - When provided, the server is assumed to have responded with these headers.statusLine String (optional) - Should be provided when overriding responseHeaders to change header status otherwise original response header's status will be used.The listener will be called with listener(details, callback) when HTTP response headers of a request have been received.
The callback has to be called with a response object.
webRequest.onResponseStarted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (facultatif)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache Boolean - Indicates whether the response was fetched from disk cache.statusCode IntegerstatusLine StringThe listener will be called with listener(details) when first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.
webRequest.onBeforeRedirect([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (facultatif)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleredirectURL StringstatusCode IntegerstatusLine Stringip String (optional) - The server IP address that the request was actually sent to.fromCache BooleanresponseHeaders Record<string, string[]> (optional)The listener will be called with listener(details) when a server initiated redirect is about to occur.
webRequest.onCompleted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (facultatif)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache BooleanstatusCode IntegerstatusLine Stringerror StringThe listener will be called with listener(details) when a request is completed.
webRequest.onErrorOccurred([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (facultatif)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublefromCache Booleanerror String - La description de l'erreur.The listener will be called with listener(details) when an error occurs.
urls String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.code Stringurl String (optional)startLine Integer (optional) - Default is 1.<webview> TagLa balise webview d'Electron est basée sur la webview de Chromium, qui subit des changements architecturaux spectaculaires. Cela affecte la stabilité des webviews, y compris le rendu, la navigation et le routage des événements. Nous recommandons actuellement de ne pas utiliser le tag webview et d’envisager des alternatives, comme iframe, Electron’s BrowserView, ou une architecture qui évite complètement le contenu intégré.
Par défaut, la balise webview est désactivée dans Electron >= 5. Vous devez activer la balise en définissant l'option webviewTag des webPréferenceslors de l'instanciation de votre BrowserWindow. Pour plus d'information voir la doc pour : BrowserWindow constructor .
\n\nAffiche un contenu web externe dans une frame et un processus isolés.
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Utilisez la balise webview pour intégrer du contenu 'hébergé' (comme des pages web) dans votre application Electron. Le contenu hébergé est inclus dans le conteneur webview. Une page intégrée dans votre application gère la façon dont le contenu est mis en page et affiché.
Contrairement à uneiframe, la webview s'exécute dans un processus séparé de votre application . Il n'a pas les mêmes permissions que votre page web et toutes les interactions entre votre application et le contenu intégré seront asynchrones. Cela protège votre application du contenu incorporé. Remarque : La plupart des méthodes appelées sur la webview à partir de la page hôte nécessitent un appel synchrone au processus principal.
Pour intégrer une page web dans votre application, ajoutez la balise webview à la page de votre application qui va l'intégrer (c'est la page de l'application qui affichera le contenu de cette page). Dans sa forme la plus simple la balise webview inclut la src de la page web et les styles css qui contrôlent l'apparence du conteneur webview:
<webview id=\"foo\" src=\"https://www.github.com/\" style=\"display:inline-flex; width:640px; height:480px\"></webview>\nSi vous voulez contrôler de quelque manière que ce soit le contenu hébergé , vous pouvez écrire du JavaScript qui écoute les événements webview et répond à ces événements en utilisant les méthodes de la webview. Voici un exemple de code avec deux écouteurs d'événements : un qui écoute quand la page web commence à télécharger, l'autre quand la page web arrête le chargement, et affiche un message \"loading...\" pendant le temps de chargement :
<script>\n onload = () => {\n const webview = document.querySelector('webview')\n const indicator = document.querySelector('.indicator')\n\n const loadstart = () => {\n indicator.innerText = 'loading...'\n }\n\n const loadstop = () => {\n indicator.innerText = ''\n }\n\n webview.addEventListener('did-start-loading', loadstart)\n webview.addEventListener('did-stop-loading', loadstop)\n }\n</script>\nDans les détails webview est implémentée avec des iframes hors processus (OOPIF). La balise webview est essentiellement un élément personnalisé utilisant un DOM fantôme pour encapsuler un élément iframe.
Donc, le comportement d'une webview est très similaire à une iframe cross-domain, comme dans ces exemples :
webview, the page focus will move from the embedder frame to webview.webview.webview are asynchronous.Please note that the webview tag's style uses display:flex; internally to ensure the child iframe element fills the full height and width of its webview container when used with traditional and flexbox layouts. Please do not overwrite the default display:flex; CSS property, unless specifying display:inline-flex; for inline layout.
La balise webview possède les attributs suivants :
src<webview src=\"https://www.github.com/\"></webview>\nUn String représentant l'URL visible. Writing to this attribute initiates top-level navigation.
En affectant sa propre valeur l'attribut src on rechargera la page actuelle.
L'attribut src peut également accepter des URL de données, telles que data:text/plain,Hello, world !.
nodeintegration<webview src=\"http://www.google.com/\" nodeintegration></webview>\nA Boolean. Lorsque cet attribut est présent, la page hébergée dans la webview pourra utiliser les API de node de nœud telles que require ou process pour accéder à des ressources système de bas niveau. Node integration est désactivée par défaut dans la page hébergée .
nodeintegrationinsubframes<webview src=\"http://www.google.com/\" nodeintegrationinsubframes></webview>\nA Boolean for the experimental option for enabling NodeJS support in sub-frames such as iframes inside the webview. All your preloads will load for every iframe, you can use process.isMainFrame to determine if you are in the main frame or not. Cette option est désactivée par défaut dans la page invité.
plugins<webview src=\"https://www.github.com/\" plugins></webview>\nA Boolean. When this attribute is present the guest page in webview will be able to use browser plugins. Les plugins sont désactivés par défaut.
preload<!-- à partir d'un fichier -->\n<webview src=\"https://www.github.com/\" preload=\"./test.js\"></webview>\n<! - ou si vous voulez à partir d'une archive asar -->\n<webview src=\"https://www.github.com/\" preload=\"./app.asar/test.js\"></webview>\nString (facultatif) Spécifie un script qui sera chargé avant les autres scripts exécutés dans la page hébergée. Le protocole de l'URL du script doit être file : (même en utilisant des archives asar : ) car il sera chargé, sous le capot, par require de Node qui traite les archives asar : comme des répertoires virtuels .
When the guest page doesn't have node integration this script will still have access to all Node APIs, but global objects injected by Node will be deleted after this script has finished executing.
\nNote : Cette option apparaîtra comme preloadURL (et non preload) dans webPréferences spécifiées à l’événement will-attach-webview .
httpreferrer<webview src=\"https://www.github.com/\" httpreferrer=\"http://cheng.guru\"></webview>\nA String that sets the referrer URL for the guest page.
useragent<webview src=\"https://www.github.com/\" useragent=\"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko\"></webview>\nA String that sets the user agent for the guest page before the page is navigated to. Once the page is loaded, use the setUserAgent method to change the user agent.
disablewebsecurity<webview src=\"https://www.github.com/\" disablewebsecurity></webview>\nA Boolean. When this attribute is present the guest page will have web security disabled. La sécurité Web est activée par défaut.
partition<webview src=\"https://github.com\" partition=\"persist:github\"></webview>\n<webview src=\"https://electronjs.org\" partition=\"electron\"></webview>\nA String that sets the session used by the page. If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. s'il n'y a pas de préfixe persistant:, la page utilisera une session en mémoire . En assignant la même partition, plusieurs pages peuvent partager la même session. If the partition is unset then default session of the app will be used.
This value can only be modified before the first navigation, since the session of an active renderer process cannot change. Subsequent attempts to modify the value will fail with a DOM exception.
\nallowpopups<webview src=\"https://www.github.com/\" allowpopups></webview>\nA Boolean. When this attribute is present the guest page will be allowed to open new windows. Les popups sont désactivés par défaut.
webpreferences<webview src=\"https://github.com\" webpreferences=\"allowRunningInsecureContent, javascript=no\"></webview>\nA String which is a comma separated list of strings which specifies the web preferences to be set on the webview. The full list of supported preference strings can be found in BrowserWindow.
The string follows the same format as the features string in window.open. A name by itself is given a true boolean value. A preference can be set to another value by including an =, followed by the value. Special values yes and 1 are interpreted as true, while no and 0 are interpreted as false.
enableblinkfeatures<webview src=\"https://www.github.com/\" enableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be enabled separated by ,. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
disableblinkfeatures<webview src=\"https://www.github.com/\" disableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be disabled separated by ,. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
La balise webview possède les méthodes suivantes :
Note: The webview element must be loaded before using the methods.
\nExample
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('dom-ready', () => {\n webview.openDevTools()\n})\n<webview>.loadURL(url[, options])url URLoptions Object (facultatif)httpReferrer (String | Referrer) (optional) - An HTTP Referrer url.userAgent String (optionnel) - Un agent utilisateur d'où provient la requête.extraHeaders String (optionnel) - Headers supplémentaires séparés par \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url is a data url and needs to load other files.Returns Promise<void> - The promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load).
Loads the url in the webview, the url must contain the protocol prefix, e.g. the http:// or file://.
<webview>.downloadURL(url)url StringInitiates a download of the resource at url without navigating.
<webview>.getURL()Returns String - The URL of guest page.
<webview>.getTitle()Returns String - The title of guest page.
<webview>.isLoading()Returns Boolean - Whether guest page is still loading resources.
<webview>.isLoadingMainFrame()Retourne Boolean - Si la frame principale (et pas seulement un iframe ou frames qu'il contient) sont toujours en chargement.
<webview>.isWaitingForResponse()Returns Boolean - Whether the guest page is waiting for a first-response for the main resource of the page.
<webview>.stop()Arrête toute navigation en attente.
\n<webview>.reload()Reloads the guest page.
\n<webview>.reloadIgnoringCache()Reloads the guest page and ignores cache.
\n<webview>.canGoBack()Returns Boolean - Whether the guest page can go back.
<webview>.canGoForward()Returns Boolean - Whether the guest page can go forward.
<webview>.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the guest page can go to offset.
<webview>.clearHistory()Efface l'historique de navigation.
\n<webview>.goBack()Makes the guest page go back.
\n<webview>.goForward()Makes the guest page go forward.
\n<webview>.goToIndex(index)index IntegerNavigates to the specified absolute index.
\n<webview>.goToOffset(offset)offset IntegerNavigates to the specified offset from the \"current entry\".
\n<webview>.isCrashed()Returns Boolean - Whether the renderer process has crashed.
<webview>.setUserAgent(userAgent)userAgent StringOverrides the user agent for the guest page.
\n<webview>.getUserAgent()Returns String - The user agent for guest page.
<webview>.insertCSS(css)css StringReturns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via <webview>.removeInsertedCSS(key).
Injecte du CSS dans la page Web actuelle et renvoie une clé unique pour la feuille de style insérée .
\n<webview>.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from <webview>.insertCSS(css).
<webview>.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (optional) - Default false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Évalue le code dans la page. If userGesture is set, it will create the user gesture context in the page. HTML APIs like requestFullScreen, which require user action, can take advantage of this option for automation.
<webview>.openDevTools()Opens a DevTools window for guest page.
\n<webview>.closeDevTools()Closes the DevTools window of guest page.
\n<webview>.isDevToolsOpened()Returns Boolean - Whether guest page has a DevTools window attached.
<webview>.isDevToolsFocused()Returns Boolean - Whether DevTools window of guest page is focused.
<webview>.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y) of guest page.
<webview>.inspectSharedWorker()Opens the DevTools for the shared worker context present in the guest page.
\n<webview>.inspectServiceWorker()Opens the DevTools for the service worker context present in the guest page.
\n<webview>.setAudioMuted(muted)muted BooleanSet guest page muted.
\n<webview>.isAudioMuted()Returns Boolean - Whether guest page has been muted.
<webview>.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
<webview>.undo()Executes editing command undo in page.
<webview>.redo()Executes editing command redo in page.
<webview>.cut()Executes editing command cut in page.
<webview>.copy()Executes editing command copy in page.
<webview>.paste()Executes editing command paste in page.
<webview>.pasteAndMatchStyle()Executes editing command pasteAndMatchStyle in page.
<webview>.delete()Executes editing command delete in page.
<webview>.selectAll()Executes editing command selectAll in page.
<webview>.unselect()Executes editing command unselect in page.
<webview>.replace(text)text StringExecutes editing command replace in page.
<webview>.replaceMisspelling(text)text StringExecutes editing command replaceMisspelling in page.
<webview>.insertText(text)text StringRetourne Promise<void>
Insère le text à l'élément ciblé.
<webview>.findInPage(text[, options])text String - Content to be searched, must not be empty.options Object (facultatif)forward Boolean (facultatif) - Rechercher soit en avant soit en arrière, la valeur par défaut est true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Doit être true pour les requêtes initiales et false pour les requêtes de suivi. Par défaut, faux.matchCase Boolean (optional) - Whether search should be case-sensitive, defaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. Le résultat de la requête peut être obtenu en s'abonnant à l'événement found-in-page.
<webview>.stopFindInPage(action)action String - Specifies the action to take place when ending <webview>.findInPage request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webview with the provided action.
<webview>.print([options])options Object (facultatif)silent Boolean (optional) - Don't ask user for print settings. Par défaut la valeur est false.printBackground Boolean (optional) - Prints the background color and image of the web page. Par défaut la valeur est false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. La valeur par défaut est vraie.margins Object (facultatif)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. Par défaut la valeur est false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - La plage de page à imprimer.from Number - Index de la première page à imprimer (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Can be simplex, shortEdge, or longEdge.dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.Retourne Promise<void>
Prints webview's web page. Identique à webContents.print([options]).
<webview>.printToPDF(options)optionsheaderFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin. and width in microns.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print. On macOS, only the first range is honored.from Number - Index de la première page à imprimer (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing heightprintBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Uint8Array> - Resolves with the generated PDF data.
Prints webview's web page as PDF, Same as webContents.printToPDF(options).
<webview>.capturePage([rect])rect Rectangle (optionnel) - La zone de la page dont on doit réaliser la capture.Retourne Promise<NativeImage> - résout avec une NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page.
<webview>.send(channel, ...args)channel String...args any[]Retourne Promise<void>
Send an asynchronous message to renderer process via channel, you can also send arbitrary arguments. The renderer process can handle the message by listening to the channel event with the ipcRenderer module.
See webContents.send for examples.
\n<webview>.sendToFrame(frameId, channel, ...args)frameId [number, number] - [processId, frameId]channel String...args any[]Retourne Promise<void>
Send an asynchronous message to renderer process via channel, you can also send arbitrary arguments. The renderer process can handle the message by listening to the channel event with the ipcRenderer module.
See webContents.sendToFrame for examples.
\n<webview>.sendInputEvent(event)event MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventRetourne Promise<void>
Sends an input event to the page.
See webContents.sendInputEvent for detailed description of event object.
<webview>.setZoomFactor(factor)factor Number - Facteur de zoom.Modifie le facteur de zoom en utilisant le facteur spécifié. Le Zoom factor est égal à la valeur du zoom exprimée en pourcent divisée par 100, donc 300% = 3.0.
\n<webview>.setZoomLevel(level)level Number - Niveau de zoom.Modifie le niveau de zoom jusqu'au niveau spécifié. La taille originale est de 0 et chaque incrément au-dessus ou en dessous représente un zoom de 20% supérieur ou inférieure jusqu'au limites de 300% et 50% de la taille originale, respectivement. La formule pour cela est 'scale:= 1,2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
<webview>.getZoomFactor()Returns Number - the current zoom factor.
<webview>.getZoomFactor()Returns Number - the current zoom level.
<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberRetourne Promise<void>
Définit le niveau maximum et minimum le niveau pinch-to-zoom.
\n<webview>.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\n<webview>.getWebContentsId()Returns Number - The WebContents ID of this webview.
The following DOM events are available to the webview tag:
Retourne :
\nurl StringisMainFrame BooleanFired when a load has committed. This includes navigation within the current document as well as subframe document-level loads, but does not include asynchronous resource loads.
\nFired when the navigation is done, i.e. the spinner of the tab will stop spinning, and the onload event is dispatched.
Retourne :
\nerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanThis event is like did-finish-load, but fired when the load failed or was cancelled, e.g. window.stop() is invoked.
Retourne :
\nisMainFrame BooleanFired when a frame has done navigation.
\nCorresponds to the points in time when the spinner of the tab starts spinning.
\nCorresponds to the points in time when the spinner of the tab stops spinning.
\nDéclenché lors de l'attachement au contenu Web de l'élément l'intégrant.
\nFired when document in the given frame is loaded.
\nRetourne :
\ntitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when title is synthesized from file url.
Retourne :
\nfavicons String[] - Tableau d'URLs.Fired when page receives favicon urls.
\nFired when page enters fullscreen triggered by HTML API.
\nFired when page leaves fullscreen triggered by HTML API.
\nRetourne :
\nlevel Integer - The log level, from 0 to 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Integer - The line number of the source that triggered this console messagesourceId StringFired when the guest window logs a console message.
\nThe following example code forwards all log messages to the embedder's console without regard for log level or other properties.
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('console-message', (e) => {\n console.log('La page invité a envoyé un message :', e.message)\n})\nRetourne :
\nresult ObjectrequestId IntegeractiveMatchOrdinal Integer - Position du résultat actif.matches Integer - Nombre de résultats.sélectionArea Rectangle - Coordonnées de la région de la première correspondance.finalUpdate BooleanFired when a result is available for webview.findInPage request.
const webview = document.querySelector('webview')\nwebview.addEventListener('found-in-page', (e) => {\n webview.stopFindInPage('keepSelection')\n})\n\nconst requestId = webview.findInPage('test')\nconsole.log(requestId)\nRetourne :
\nurl StringframeName Stringdisposition String - Peut être default, foreground-tab, background-tab, new-window, save-to-disk et other.options BrowserWindowConstructorOptions - The options which should be used for creating the new BrowserWindow.Fired when the guest page attempts to open a new browser window.
\nThe following example code opens the new url in system's default browser.
\nconst { shell } = require('electron')\nconst webview = document.querySelector('webview')\n\nwebview.addEventListener('new-window', async (e) => {\n const protocol = (new URL(e.url)).protocol\n if (protocol === 'http:' || protocol === 'https:') {\n await shell.openExternal(e.url)\n }\n})\nRetourne :
\nurl StringEmitted when a user or the page wants to start navigation. It can happen when the window.location object is changed or a user clicks a link in the page.
Cet événement ne sera pas émis lorsque la navigation démarre par programmation grâce aux APIs comme <webview>.loadURL et <webview>.back.
It is also not emitted during in-page navigation, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Calling event.preventDefault() does NOT have any effect.
Retourne :
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be true for in-page navigations.
Retourne :
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nRetourne :
\nurl StringÉmis lorsqu'une navigation est faite.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Retourne :
\nurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - vide pour les navigations non HTTP,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerÉmis lorsqu'une navigation est terminée.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Retourne :
\nisMainFrame Booleanurl StringÉmis lorsqu'une navigation dans la page s'est produite.
\nEn cas de navigation dans la page, l'URL de la page change mais ne provoque pas de navigation à l'extérieur de la page. Par exemple, lorsque vous cliquez sur un lien d'ancrage ou lorsque l'événement DOM hashchange est déclenché.
Fired when the guest page attempts to close itself.
\nThe following example code navigates the webview to about:blank when the guest attempts to close itself.
const webview = document.querySelector('webview')\nwebview.addEventListener('close', () => {\n webview.src = 'about:blank'\n})\nRetourne :
\nframeId [number, number] - pair of [processId, frameId].channel Stringargs any[]Fired when the guest page has sent an asynchronous message to embedder page.
\nWith sendToHost method and ipc-message event you can communicate between guest page and embedder page:
// In embedder page.\nconst webview = document.querySelector('webview')\nwebview.addEventListener('ipc-message', (event) => {\n console.log(event.channel)\n // Prints \"pong\"\n})\nwebview.send('ping')\n// In guest page.\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('ping', () => {\n ipcRenderer.sendToHost('pong')\n})\nFired when the renderer process is crashed.
\nRetourne :
\nname Stringversion StringDéclenché lorsqu’un processus de plugin crash.
\nDéclenché lorsque le WebContents est détruit.
\nÉmis lorsqu'un média se démarre.
\nÉmis lorsque le média est suspendu ou terminé.
\nRetourne :
\nthemeColor StringEmitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nRetourne :
\nurl StringÉmis lorsque la souris passe sur un lien ou le clavier déplace le focus vers un lien.
\nÉmis lorsque la DevTools est ouverte.
\nÉmis lorsque la DevTools est fermée.
\nÉmis lorsque la DevTools est active / ouverte.
", "title": "There are several ways to control how windows are created from trusted or untrusted content within a renderer. Windows can be created from the renderer in two ways:
\ntarget=_blankwindow.open()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.
When nativeWindowOpen is set to false, window.open instead results in the creation of a BrowserWindowProxy, 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 BrowserWindow in the main process by using webContents.setWindowOpenHandler() for renderer-created windows.
Les options du constructeur BrowserWindow sont définies par ordre croissant de priorité : avec d'abord les options héritées du parent puis les options analysées à partir de la chaîne features de window.open() puis les webPreferences héritées du parent et liées à la sécurité et enfin les options données par webContents.setWindowOpenHandler. Note that webContents.setWindowOpenHandler has final say and full privilege because it is invoked in the main process.
window.open(url[, frameName][, features])url StringframeName String (facultatif)features String (facultatif)Returns BrowserWindowProxy | Window
features is a comma-separated key-value list, following the standard format of the browser. Electron will parse BrowserWindowConstructorOptions out of this list where possible, for convenience. For full control and better ergonomics, consider using webContents.setWindowOpenHandler to customize the BrowserWindow creation.
A subset of WebPreferences can be set directly, unnested, from the features string: zoomFactor, nodeIntegration, preload, javascript, contextIsolation, and webviewTag.
Par exemple :
\nwindow.open('https://github.com', '_blank', 'top=500,left=200,frame=false,nodeIntegration=no')\nRemarque :
\nwindow si elle est désactivée sur la fenêtre parent.window si elle est activée sur la fenêtre parent.window si il est désactivé sur la fenêtre parent.features seront transmises à tout gestionnaire de l'événement did-create-window enregistré de webContents dans le paramètre options.frameName suit la spécification de windowName située dans la documentation native.To customize or cancel the creation of the window, you can optionally set an override handler with webContents.setWindowOpenHandler() from the main 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.
Window example// main.js\nconst mainWindow = new BrowserWindow()\n\n// In this example, only windows with the `about:blank` url will be created.\n// All other urls will be blocked.\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url === 'about:blank') {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n frame: false,\n fullscreenable: false,\n backgroundColor: 'black',\n webPreferences: {\n preload: 'my-child-window-preload-script.js'\n }\n }\n }\n }\n return { action: 'deny' }\n})\n// renderer process (mainWindow)\nconst childWindow = window.open('', 'modal')\nchildWindow.document.write('<h1>Hello</h1>')\nBrowserWindowProxy example\n// main.js\nconst mainWindow = new BrowserWindow({\n webPreferences: { nativeWindowOpen: false }\n})\n\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url.startsWith('https://github.com/')) {\n return { action: 'allow' }\n }\n return { action: 'deny' }\n})\n\nmainWindow.webContents.on('did-create-window', (childWindow) => {\n // For example...\n childWindow.webContents.on('will-navigate', (e) => {\n e.preventDefault()\n })\n})\n// renderer.js\nconst windowProxy = window.open('https://github.com/', null, 'minimizable=false')\nwindowProxy.postMessage('hi', '*')\nIf your app runs with Electron 6.0.8 or later, you can now build it for Windows 10 on Arm. This considerably improves performance, but requires recompilation of any native modules used in your app. It may also require small fixups to your build and packaging scripts.
\nIf your app doesn't use any native modules, then it's really easy to create an Arm version of your app.
\nnode_modules directory is empty.set npm_config_arch=arm64 before running npm install/yarn install as usual.Lots of Windows-specific code contains if... else logic that selects between either the x64 or x86 architectures.
\nif (process.arch === 'x64') {\n // Do 64-bit thing...\n} else {\n // Do 32-bit thing...\n}\nIf you want to target arm64, logic like this will typically select the wrong architecture, so carefully check your application and build scripts for conditions like this. In custom build and packaging scripts, you should always check the value of npm_config_arch in the environment, rather than relying on the current process arch.
If you use native modules, you must make sure that they compile against v142 of the MSVC compiler (provided in Visual Studio 2017). You must also check that any pre-built .dll or .lib files provided or referenced by the native module are available for Windows on Arm.
To test your app, use a Windows on Arm device running Windows 10 (version 1903 or later). Make sure that you copy your application over to the target device - Chromium's sandbox will not work correctly when loading your application assets from a network location.
\nNode.js v12.9.0 or later is recommended. If updating to a new version of Node is undesirable, you can instead update npm's copy of node-gyp manually to version 5.0.2 or later, which contains the required changes to compile native modules for Arm.
\nVisual Studio 2017 (any edition) is required for cross-compiling native modules. You can download Visual Studio Community 2017 via Microsoft's Visual Studio Dev Essentials program. After installation, you can add the Arm-specific components by running the following from a Command Prompt:
\nvs_installer.exe ^\n--add Microsoft.VisualStudio.Workload.NativeDesktop ^\n--add Microsoft.VisualStudio.Component.VC.ATLMFC ^\n--add Microsoft.VisualStudio.Component.VC.Tools.ARM64 ^\n--add Microsoft.VisualStudio.Component.VC.MFC.ARM64 ^\n--includeRecommended\nSetting npm_config_arch=arm64 in the environment creates the correct arm64 .obj files, but the standard Developer Command Prompt for VS 2017 will use the x64 linker. To fix this:
vcvarsamd64_arm64.bat at the end instead of vcvarsamd64_x86.bat.If done successfully, the command prompt should print something similar to this on startup:
\n**********************************************************************\n** Visual Studio 2017 Developer Command Prompt v15.9.15\n** Copyright (c) 2017 Microsoft Corporation\n**********************************************************************\n[vcvarsall.bat] Environment initialized for: 'x64_arm64'\nIf you want to develop your application directly on a Windows on Arm device, substitute vcvarsx86_arm64.bat in Target so that cross-compilation can happen with the device's x86 emulation.
node.libBy default, node-gyp unpacks Electron's node headers and downloads the x86 and x64 versions of node.lib into %APPDATA%\\..\\Local\\node-gyp\\Cache, but it does not download the arm64 version (a fix for this is in development.) To fix this:
node.lib from https://electronjs.org/headers/v6.0.9/win-arm64/node.lib%APPDATA%\\..\\Local\\node-gyp\\Cache\\6.0.9\\arm64\\node.libSubstitute 6.0.9 for the version you're using.
After completing all of the above, open your cross-compilation command prompt and run set npm_config_arch=arm64. Then use npm install to build your project as normal. As with cross-compiling x86 modules, you may need to remove node_modules to force recompilation of native modules if they were previously compiled for another architecture.
Debugging native modules can be done with Visual Studio 2017 (running on your development machine) and corresponding Visual Studio Remote Debugger running on the target device. To debug:
\n.exe on the target device via the Command Prompt (passing --inspect-brk to pause it before any native modules are loaded)..pdb symbols under Debugging > Symbols.If you encounter a problem with this documentation, or if your app works when compiled for x86 but not for arm64, please file an issue with \"Windows on Arm\" in the title.
", "title": "Windows sur ARM", "description": "" }, "/docs/tutorial/windows-store-guide": { "locale": "fr-FR", "slug": "windows-store-guide", "href": "/docs/tutorial/windows-store-guide", "crowdinFileId": "256273", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-store-guide.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Avec Windows 10, le bon vieux executable win32 a un nouveau frère: La plateforme Universelle de Windows. Le nouveau format .appx ne permet pas seulement d'avoir de nouvelles API puissantes comme Cortana ou Push Notifications, mais via le Windows Store, il simplifie également les installations et les mises à jour.
Microsoft à développé un outil qui compile les apps Electron en packages .appx, permettant aux développeurs d'utiliser une partie des goodies trouvés dans le nouveau modèle d'application. Ce guide explique comment l'utiliser - et quelles sont les capacités et les limites d'un package Electron AppX.
Windows 10 \"Anniversary Update\" est capable d'exécuter des binaires win32 .exe en les lançant avec un système de fichier et un registre virtualisé. Ils sont tout les deux créés durant la compilation en exécutant l'app et l'installer a l'intérieur d'un conteneur de Windows, ce qui permet à Windows d'identifier exactement quelles modifications au système d'exploitation sont effectuées pendant l'installation. Appareiller l'exécutable avec un système de fichiers virtuel et un registre virtuel permet à Windows la désinstallation et l'installation en un seul clic.
En addition, le exe est lancé à l'intérieur du modèle appx - ce qui signifie qu'il peut utiliser beaucoup des API disponibles pour la plateforme Universelle Windows. Pour gagner encore plus de fonctionnalités, une app Electron peut jumeler avec une tâche d'arrière-plan invisible UWP lancée avec le exe - sorte d'acolyte pour exécuter des tâches en arrière-plan, recevoir des notifications push, ou pour communiquer avec d'autres applications UWP.
Pour compiler n’importe quelle app Electron existante, assurez-vous que vous avez les exigences suivantes :
\nnode -v)Ensuite, installez electron-windows-store CLI:
npm install -g electron-windows-store\nEmpaquetez l’application à l’aide de electron-packager (ou un outil similaire). Assurez vous de supprimer node_modules que vous n'avez pas besoin dans votre application finale, puisque n'importe quel module dont vous n'avez pas besoin augmentera inutilement la taille de votre application.
La sortie devrait ressembler à peu près à ceci :
\n├── Ghost.exe\n├── LICENSE\n├── content_resources_200_percent.pak\n├── content_shell.pak\n├── d3dcompiler_47.dll\n├── ffmpeg.dll\n├── icudtl.dat\n├── libEGL.dll\n├── libGLESv2.dll\n├── locales\n│ ├── am.pak\n│ ├── ar.pak\n│ ├── [...]\n├── node.dll\n├── resources\n│ └── app.asar\n├── v8_context_snapshot.bin\n├── squirrel.exe\n└── ui_resources_200_percent.pak\nDepuis un PowerShell élevé (exécuter le \"en tant Administrateur\"), exécutez electron-windows-store avec les paramètres requis, en mettant le dossier d'entrée, le dossier de sortie, le nom et la version de l'application, et confirmer que node_modules doit être aplati :
electron-windows-store `\n --input-directory C:\\myelectronapp `\n --output-directory C:\\output\\myelectronapp `\n --package-version 1.0.0.0 `\n --package-name myelectronapp\nUne fois exécuté, l’outil se met au travail : il accepte votre app Electron comme entrée, et aplatit les node_modules. Ensuite, il archive votre application comme app.zip. En utilisant un installateur et un conteneur de Windows, l’outil crée un paquet AppX « élargi » - contenant le manifeste d’Application Windows (AppXManifest.xml) ainsi que le système de fichiers virtuel et le registre virtuel à l’intérieur de votre dossier de sortie.
Une fois les fichiers AppX élargis sont créés, l’outil utilise le Windows App Packager (MakeAppx.exe) pour créer un package de AppX de fichier unique de ces fichiers sur le disque. Enfin, l’outil peut servir pour créer un certificat approuvé sur votre ordinateur pour signer le nouveau paquet AppX. Avec le package AppX signé, la CLI peut également automatiquement installer le package sur votre machine.
Afin d’exécuter votre paquet, vos utilisateurs auront besoin de Windows 10 \"Anniversaire Update\" - plus de détails sur comment mettre à jour Windows peuvent être trouvés ici.
\nEn opposition aux traditionelles apps UWP, actuellement les apps empaquetées doivent subir un processus de vérification manuelle, pour lequel vous pouvez appliquer ici. En attendant, tous les utilisateurs seront en mesure d’installer votre paquet en double-cliquant dessus, donc une soumission au store ne sera ne peut-être pas nécessaire si vous cherchez simplement une méthode d’installation plus facile. Dans des environnements gérés (généralement des entreprises), l'Add-AppxPackage applet de commande PowerShell permet de l'installer de façon automatisée.
Une autre limitation importante est que le paquet AppX compilé contient un fichier exécutable win32 - toujours et qu’il ne fonctionnera donc pas sur Xbox, HoloLens ou téléphones.
\nVous pouvez coupler votre app Electron avec une tâche en arrière-plan UWP invisible qui vous permet de tirer pleinement parti des fonctionnalités de Windows 10 - comme notifications push, ou les tuiles vivantes.
\nPour voir comment une app Electron peut utiliser une tâche de fond pour envoyer des notifications toast et tuiles vivantes, consultez l'exemple fourni par Microsoft.
\nPour générer le package AppX, l'electron-windows-store CLI utilise un modèle qui devrait fonctionner pour la plupart des applications Electron. Toutefois, si vous utilisez un programme d’installation personnalisé, ou si vous rencontrez des problèmes avec le paquet généré, vous pouvez essayer de créer un package à l’aide de compilation avec un conteneur Windows - dans ce mode, le CLI va installer et exécuter votre application dans un conteneur vide de Windows pour déterminer quelles modifications votre application fait au système d’exploitation.
Avant d'exécuter le CLI pour la première fois, vous devrez configurer le \"Windows Desktop App Converter\". Cela prendra quelques minutes, mais ne vous inquiétez pas il suffit de le faire une fois. Téléchargez le Desktop App Converter ici. Vous recevrez deux fichiers: DesktopAppConverter.zip et BaseImage-14316.wim.
DesktopAppConverter.zip. Depuis un PowerShell élevé (ouvert avec \"exécuter en tant qu'administrateur\"), faire en sorte que votre stratégie d'exécution de systèmes nous permet d'exécuter tout que nous avons besoin d'exécuter en appelant Set-ExecutionPolicy bypass.BaseImage-14316.wim), en exécutant la commande .\\DesktopAppConverter.ps1 -Setup -BaseImage .\\BaseImage-14316.wim.Une fois l’installation réussie, vous pouvez passer à la compilation de votre app Electron.
", "title": "Guide Windows Store", "description": "" }, "/docs/tutorial/windows-taskbar": { "locale": "fr-FR", "slug": "windows-taskbar", "href": "/docs/tutorial/windows-taskbar", "crowdinFileId": "256275", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-taskbar.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron possède des APIs pour configurer l'icône de l'application dans la barre des tâches de Windows. This API supports both Windows-only features like creation of a JumpList, custom thumbnails and toolbars, icon overlays, and the so-called \"Flash Frame\" effect, and cross-platform features like recent documents and application progress.
Windows permet aux applications de définir un menu contextuel personnalisé s'affichant lorsque les utilisateurs effectuent un clic-droit sur l’icône de l’application dans la barre des tâches. Ce menu contextuel est appelé JumpList. You specify custom actions in the Tasks category of JumpList, as quoted from MSDN:
\n\nLes applications définissent des tâches basées sur les caractéristiques du programme et les fonctionnalités clés que l'utilisateur est censé utiliser. Les tâches doivent être indépendantes du contexte, c'est à dire qu'elles n'ont pas besoin de s'exécuter pour fonctionner. Il devrait également il y avoir les actions statistiquement plus courantes qu'un utilisateur normal utiliserait dans une application, comme rédiger un message électronique ou ouvrir le calendrier dans un logiciel de messagerie, ou créer un nouveau document dans un traitement de texte, lancer une application dans un certain mode, ou lancer une des ses sous-commandes. Une application ne doit pas encombrer le menu avec des fonctions avancées que les utilisateurs standards n'auraient pas besoin ou des actions ponctuelles telles que l'inscription. Ne pas utiliser les tâches pour les articles promotionnels tels que les mises à niveau ou des offres spéciales.
\nIl est fortement recommandé que la liste des tâches soit statique. Il devrait rester le même quelque soit l'état ou le statut de l'application. Bien qu'il soit possible de faire varier la liste dynamiquement, vous devez envisager que cela puisse confondre l'utilisateur qui n'attend pas que cette portion de la liste puisse changer.
\n
\n\nREMARQUE : La capture d'écran ci-dessus est un exemple de tâches générales de Internet Explorer
\n
Contrairement au menu du dock dans macOS, qui est un vrai menu, les tâches utilisateur dans Windows fonctionnent comme des raccourcis d'application. Par exemple, lorsqu'un utilisateur clique sur une tâche, le programme sera exécuté avec les arguments spécifiés.
\nTo set user tasks for your application, you can use app.setUserTasks API.
\nCommençons avec une application fonctionnelle issue du Quick Start Guide, mettez à jour le fichier main.js avec les lignes suivantes :
const { app } = require('electron')\n\napp.setUserTasks([\n {\n program: process.execPath,\n arguments: '--new-window',\n iconPath: process.execPath,\n iconIndex: 0,\n title: 'Nouvelle fenêtre',\n description: 'Créer une nouvelle fenêtre'\n }\n])\nPour effacer votre liste de tâches, vous devez appeler app.setUserTasks avec un tableau vide dans le fichier main.js.
const { app } = require('electron')\n\napp.setUserTasks([])\n\n\nLes tâches utilisateur seront visibles même après la fermeture de votre application, donc l'icône et le chemin d'accès du programme spécifié pour une tâche doivent exister jusqu'à ce que votre application soit désinstallée.
\n
Sur Windows, vous pouvez ajouter à la barre des tâches d'une fenêtre d'une 'application une barre d'outils miniatures avec des boutons spécifiés. Cela donne aux utilisateurs un moyen d'accéder aux commandes particulières d'une fenêtre sans avoir à restaurer ou réactiver la fenêtre.
\nAs quoted from MSDN:
\n\n\nCette barre d’outils est simplement le composant standard pour la barre d’outils. Il a un maximum de sept boutons. Chaque identifiant, image, info-bulle et état du bouton sont spécifiés dans une structure, qui est ensuite passée à la barre des tâches. L'application peut afficher, activer, désactiver ou masquer des boutons de la barre d'outils miniature comme requis par son état actuel.
\nPar exemple, le lecteur Windows Media Player peut offrir un support standard de contrôles tels que lecture, pause, muet et arrêt.
\n
\n\nREMARQUE : La capture d'écran ci-dessus est un exemple de barre d'outils miniatures de Windows Media Player
\n
Pour définir la barre d'outils des miniatures dans votre application, vous devez utiliser BrowserWindow.setThumbarButtons
\nCommençons avec une application fonctionnelle issue du Quick Start Guide, mettez à jour le fichier main.js avec les lignes suivantes :
const { BrowserWindow } = require('electron')\nconst path = require('path')\n\nconst win = new BrowserWindow()\n\nwin.setThumbarButtons([\n {\n tooltip: 'button1',\n icon: path.join(__dirname, 'button1.png'),\n click () { console.log('button1 clicked') }\n }, {\n tooltip: 'button2',\n icon: path.join(__dirname, 'button2.png'),\n flags: ['enabled', 'dismissonclick'],\n click () { console.log('button2 clicked.') }\n }\n])\nPour effacer les boutons de la barre d'outils miniatures, vous devez appeler BrowserWindow.setThumbarButtons avec un tableau vide dans le fichier main.js.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.setThumbarButtons([])\nSous Windows, un bouton de la barre des tâches peut utiliser un petit overlay pour afficher l'état de l'application.
\nAs quoted from MSDN:
\n\n\nLes superpositions d'icônes servent en tant que notification contextuelle du statut, et sont destinées à dénier la nécessité d'une zone de notification séparée pour communiquer cette information à l'utilisateur. Par exemple, le nouveau statut de messagerie de Microsoft Outlook, actuellement affiché dans la zone de notification, est maintenant indiqué par une superposition dans sur le bouton de la barre des tâches. Encore une fois, vous devez décider au cours de votre cycle de développement quelle méthode est la meilleure pour votre application. Les icônes de recouvrement sont destinées à fournir une information importante et de long terme, telle que l'état du réseau, un statut de messagerie ou de nouveaux messages. L'utilisateur ne devrait pas se retrouver face à des superpositions ou des animations en constante évolution.
\n
\n\nREMARQUE : La capture d'écran ci-dessus est un exemple d'overlay sur un bouton de la barre des tâches
\n
To set the overlay icon for a window, you need to use the BrowserWindow.setOverlayIcon API.
\nCommençons avec une application fonctionnelle issue du Quick Start Guide, mettez à jour le fichier main.js avec les lignes suivantes :
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.setOverlayIcon(\"path/to/overlay.png\", \"Description de l'overlay\")\nSur Windows vous pouvez mettre en valeur un bouton de la barre des tâches pour attirer l'attention de l'utilisateur. C'est similaire à l'effet de rebond des icônes dans le dock macOS.
\nAs quoted from MSDN:
\n\n\nEn règle générale, une fenêtre clignote pour informer l'utilisateur que la fenêtre nécessite de l'attention alors qu'elle n'a pas le focus clavier.
\n
To flash the BrowserWindow taskbar button, you need to use the BrowserWindow.flashFrame API.
\nCommençons avec une application fonctionnelle issue du Quick Start Guide, mettez à jour le fichier main.js avec les lignes suivantes :
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.once('focus', () => win.flashFrame(false))\nwin.flashFrame(true)\n\n", "title": "Personnalisation de la barre des tâches (Windows)", "description": "Les applications définissent des tâches basées sur les caractéristiques du programme et les fonctionnalités clés que l'utilisateur est censé utiliser. Les tâches doivent être indépendantes du contexte, c'est à dire qu'elles n'ont pas besoin de s'exécuter pour fonctionner. Il devrait également il y avoir les actions statistiquement plus courantes qu'un utilisateur normal utiliserait dans une application, comme rédiger un message électronique ou ouvrir le calendrier dans un logiciel de messagerie, ou créer un nouveau document dans un traitement de texte, lancer une application dans un certain mode, ou lancer une des ses sous-commandes. Une application ne doit pas encombrer le menu avec des fonctions avancées que les utilisateurs standards n'auraient pas besoin ou des actions ponctuelles telles que l'inscription. Ne pas utiliser les tâches pour les articles promotionnels tels que les mises à niveau ou des offres spéciales.\nIl est fortement recommandé que la liste des tâches soit statique. Il devrait rester le même quelque soit l'état ou le statut de l'application. Bien qu'il soit possible de faire varier la liste dynamiquement, vous devez envisager que cela puisse confondre l'utilisateur qui n'attend pas que cette portion de la liste puisse changer." } }, "ru-RU": { "/docs/api/accelerator": { "locale": "ru-RU", "slug": "accelerator", "href": "/docs/api/accelerator", "crowdinFileId": "256277", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/accelerator.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "NOTE : N'oubliez pas d'appeler
\nwin.flashFrame(false)pour désactiver le flash. Dans l'exemple ci-dessus, l'appel s'effectue quand la fenêtre est focalisée, mais vous pouvez utiliser une temporisation ou un autre événement pour désactiver.
\n\nОпределите сочетания клавиш.
\n
Акселераторы - строки, которые могут содержать множество модификаторов и код одной клавиши, комбинированные символом +, и используются для определения сочетания клавиш по всему приложению.
Примеры:
\nCommandOrControl+ACommandOrControl+Shift+ZСочетания клавиш регистрируются с помощью модуля globalShortcut, используя метод register, т.е.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Регистрирует слушателя сочетания клавиш 'CommandOrControl+Y'.\n globalShortcut.register('CommandOrControl+Y', () => {\n // Сделайте что-нибудь, когда Y и Command/Control нажаты.\n })\n})\nНа Linux и Windows, клавиша Command не имеет никакого эффекта, так что используйте CommandOrControl, который представляет собой Command на macOS и Control на Linux и Windows для определения некоторых акселераторов.
Используйте Alt вместо опции. Клавиша Option существует только на macOS, в то время как клавиша Alt доступна на всех платформах.
The Super (or Meta) key is mapped to the Windows key on Windows and Linux and Cmd on macOS.
Command (или Cmd для краткости)Control (или Ctrl для краткости)CommandOrControl (или CmdOrCtrl для краткости)AltOptionAltGrShiftSuperMeta0 - 9A - ZF1 - F24~, !, @, #, $ и т.д.PlusSpaceTabCapslockNumlockScrolllockBackspaceDeleteInsertReturn (или Enter как псевдоним)Up, Down, Left и RightHome и EndPageUp и PageDownEscape (или Esc для краткости)VolumeUp, VolumeDown и VolumeMuteMediaNextTrack, MediaPreviousTrack, MediaStop и MediaPlayPausePrintScreennum0 - num9numdec - клавиша десятичный разделительnumadd - клавиша + на numpadnumsub - клавиша - на numpadnummult - клавиша * на numpadnumdiv - клавиша ÷ на numpadСоздание доступных приложений важно и мы рады представить новые функции Devtron и Spectron, которые дают разработчикам возможность делать свои приложения лучше для всех.
\nПроблемы с доступностью в приложениях Electron аналогичны веб-сайтам, поскольку они оба в конечном итоге являются HTML. Однако, в приложениях на Electron мы не можем использовать онлайн-ресурсы для аудита доступности, поскольку ваше приложение не имеет URL-адреса.
\nThese features bring those auditing tools to your Electron app. You can choose to add audits to your tests with Spectron or use them within DevTools with Devtron. Читайте далее ознакомление с инструментами.
\nIn the testing framework Spectron, you can now audit each window and <webview> tag in your application. Например:
app.client.auditAccessibility().then(function (audit) {\n if (audit.failed) {\n console.error(audit.message)\n }\n})\nВы можете прочитать больше об этой функции в Spectron документации.
\nIn Devtron, there is an accessibility tab which will allow you to audit a page in your app, sort and filter the results.
\n
Оба эти средства используют библиотеку Accessibility Developer Tools, построенную Google для Chrome. Вы можете узнать больше о правилах для аудита доступности, которые эта библиотека использует, в этих wiki репозиториях .
\nЕсли вы знаете другие средства для поверки доступности в Electron, добавите их в документацию через pull request.
\nElectron applications will automatically enable accessibility features in the presence of assistive technology (e.g. JAWS on Windows or VoiceOver on macOS). See Chrome's accessibility documentation for more details.
\nYou can also manually toggle these features either within your Electron application or by setting flags in third-party native software.
\nBy using the app.setAccessibilitySupportEnabled(enabled) API, you can manually expose Chrome's accessibility tree to users in the application preferences. Note that the user's system assistive utilities have priority over this setting and will override it.
On macOS, third-party assistive technology can toggle accessibility features inside Electron applications by setting the AXManualAccessibility attribute programmatically:
CFStringRef kAXManualAccessibility = CFSTR(\"AXManualAccessibility\");\n\n+ (void)enableAccessibility:(BOOL)enable inElectronApplication:(NSRunningApplication *)app\n{\n AXUIElementRef appRef = AXUIElementCreateApplication(app.processIdentifier);\n if (appRef == nil)\n return;\n\n CFBooleanRef value = enable ? kCFBooleanTrue : kCFBooleanFalse;\n AXUIElementSetAttributeValue(appRef, kAXManualAccessibility, value);\n CFRelease(appRef);\n}\n\n\nКонтролируйте жизненный цикл Вашего приложения.
\n
Процесс: Основной
\nЭтот пример показывает, как закрыть приложение, когда последнее окно будет закрыто:
\nconst { app } = require('electron')\napp.on('window-all-closed', () => {\n app.quit()\n})\nОбъект app имеет следующие события:
Происходит, когда приложение заканчивает основной запуск. На Windows и Linux событие will-finish-launching подобно событию ready; на macOS это событие представляет собой уведомление applicationWillFinishLaunching объекта NSApplication. Обычно настраивают слушателей для open-file и open-url событий, и запускают репортер сбоев и автоматическое обновление.
В большинстве случаев, Вы должны выполнять всё в обработчике события ready.
Возвращает:
\neventlaunchInfo Record<string, any> | NotificationResponse macOSПроисходит единожды при завершении инициализации Electron. On macOS, launchInfo holds the userInfo of the NSUserNotification or information from UNNotificationResponse that was used to open the application, if it was launched from Notification Center. Вы также можете вызвать app.isReady() для проверки того, что событие уже произошло и app.whenReady() чтобы получить Promise, который выполнится, когда Electron будет инициализирован.
Происходит при закрытии всех окон.
\nЕсли Вы не подпишитесь на это событие, и все окна будут закрыты, поведением по умолчанию является выход из приложения; Однако, если Вы подпишитесь, то Вы определяете, будет ли приложение закрыто или нет. Если пользователь нажал Cmd + Q или разработчик вызвал app.quit(), Electron сначала попытается закрыть все окна, а затем происходит событие will-quit, и в этом случае событие window-all-closed не будет происходить.
Возвращает:
\neventПроисходит до того, как приложение начнет закрывать свои окна. Вызов event.preventDefault() предотвратит поведение по умолчанию, которое приводит к прекращению работы приложения.
Примечание: Если выход приложения был инициирован autoUpdater.quitAndInstall(), тогда before-quit происходит после того, как происходит событие close на всех окнах и закрывает их.
Примечание: На Windows это событие не произойдет, если приложение закрылось из-за выключения/перезагрузки системы или выхода пользователя из системы.
\nВозвращает:
\neventВозникает, когда все окна будут закрыты и приложение завершит работу. Вызов event.preventDefault() предотвратит поведение по умолчанию, которое приводит к прекращению работы приложения.
Смотрите описание события window-all-closed для различий между событиями will-quit и window-all-closed.
Примечание: На Windows это событие не произойдет, если приложение закрылось из-за выключения/перезагрузки системы или выхода пользователя из системы.
\nВозвращает:
\neventexitCode IntegerПроисходит при выходе из приложения.
\nПримечание: На Windows это событие не произойдет, если приложение закрылось из-за выключения/перезагрузки системы или выхода пользователя из системы.
\nВозвращает:
\neventpath StringПроисходит, когда пользователь хочет открыть файл. Событие open-file обычно происходит, когда приложение уже открыто и ОС хочет переиспользовать приложение, чтобы открыть файл. open-file также происходит, когда файл уже находится на Dock панели, но приложение еще не запущено. Убедитесь, что обработчик события open-file в самом начале запуска Вашего приложения обрабатывает этот случай (даже прежде, чем происходит событие ready).
Вы должны вызвать event.preventDefault(), если хотите обработать это событие.
На Windows Вам необходимо распарсить process.argv (в основном процессе), чтобы получить путь к файлу.
Возвращает:
\neventurl StringПроисходит, когда пользователь хочет открыть URL-адрес из приложения. Файл Вашего приложения Info.plist должнен определять схему URL в ключе CFBundleURLTypes и установить NSPrincipalClass в AtomApplication.
Вы должны вызвать event.preventDefault(), если хотите обработать это событие.
Возвращает:
\neventhasVisibleWindows BooleanПроисходит при активации приложения. Различные действия могут запускать это событие, например, запуск приложения в первый раз, попытка перезапустить приложение, когда оно уже запущено, или клик на иконку приложения на панели dock или панели задач.
\nВозвращает:
\neventПроисходит при активации приложения. Отличие от события activate в том, что did-become-active происходит после каждой активации приложения, а не только при нажатии на иконку на панели задач или перезапуске приложения.
Возвращает:
\neventtype String - строка идентифицирует активность. Карты для NSUserActivity.activityType.userInfo unknown - содержит специфическое для приложения состояние, сохраненное на другом устройстве.detailswebpageURL String (optional) - A string identifying the URL of the webpage accessed by the activity on another device, if available.Происходит во время Handoff, когда активность с другого устройства хочет возобновиться. Если вы хотите обработать это событие следует вызвать event.preventDefault().
Активность пользователя может быть продолжена только в приложении, которое имеет тот же ID команды разработчика, что и исходное приложение, и поддерживает тип активности. Поддерживаемые типы активности, указаны в Info.plist приложения под ключом NSUserActivityTypes.
Возвращает:
\neventtype String - строка идентифицирует активность. Карты для NSUserActivity.activityType.Происходит во время Handoff до того, как активность с другого устройства хочет возобновиться. Если вы хотите обработать это событие следует вызвать event.preventDefault().
Возвращает:
\neventtype String - строка идентифицирует активность. Карты для NSUserActivity.activityType.error String - cтрока с локализованным описанием ошибки.Происходит во время Handoff, при ошибочном возобновлении активности на различных устройствах.
\nВозвращает:
\neventtype String - строка идентифицирует активность. Карты для NSUserActivity.activityType.userInfo unknown - содержит специфичное, для приложения, состояние, сохраненное в хранилище по активности.Происходит во время Handoff, после удачного возобновления на другом устройстве.
\nВозвращает:
\neventtype String - строка идентифицирует активность. Карты для NSUserActivity.activityType.userInfo unknown - содержит специфичное, для приложения, состояние, сохраненное в хранилище по активности.Происходит во время Handoff, когда вот-вот возобновится на другом устройстве. Если Вы хотите обновить состояние, которое будет передано, Вам необходимо вызвать event.preventDefault() немедленно, собрать новый словарь userInfo и вызвать app.updateCurrentActivity() своевременно. Иначе, операция завершится ошибкой и будет вызвано continue-activity-error.
Возвращает:
\neventВозникает при нажатии пользователем кнопки новой вкладки macOS. Кнопка новой вкладки отобразится только если текущий BrowserWindow имеет tabbingIdentifier
Возвращает:
\neventwindow BrowserWindowВозникает, когда browserWindow получает размытие.
\nВозвращает:
\neventwindow BrowserWindowВозникает, когда browserWindow получает фокус.
\nВозвращает:
\neventwindow BrowserWindowПроисходит, когда создался новый browserWindow.
\nВозвращает:
\neventwebContents WebContentsПроисходит, когда создался новый webContents.
\nВозвращает:
\neventwebContents WebContentsurl Stringerror String - код ошибкиcertificate Certificatecallback FunctionisTrusted Boolean - учитывать ли сертификат как надёжныйisMainFrame BooleanВозникает, когда не удалось проверить certificate для url, чтобы доверять сертификату, вы должны предотвратить поведение по умолчанию с event.preventDefault() и вызвать callback(true).
const { app } = require('electron')\n\napp.on('certificate-error', (event, webContents, url, error, certificate, callback) => {\n if (url === 'https://github.com') {\n // Сверка логики.\n event.preventDefault()\n callback(true)\n } else {\n callback(false)\n }\n})\nВозвращает:
\neventwebContents WebContentsurl URLcertificateList Certificate[]callback Functioncertificate Certificate (опиционально)Возникает при запросе сертификата клиента.
\nurl соответствует записи навигации, запрашивающей сертификат клиента и callback можно вызвать с записью, отфильтрованной из списка. event.preventDefault() предотвращает приложению использование первого сертификата из хранилища.
const { app } = require('electron')\n\napp.on('select-client-certificate', (event, webContents, url, list, callback) => {\n event.preventDefault()\n callback(list[0])\n})\nВозвращает:
\neventwebContents WebContentsauthenticationResponseDetails Objecturl URLauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (опционально)password String (опционально)Возникает webContents, когда делается базовый auth.
Поведение по умолчанию - отмена всех аутентификаций. Чтобы переопределить это, Вы должны предотвратить поведение по умолчанию с помощью event.preventDefault() и вызвать callback(username, password) с учетными данными.
const { app } = require('electron')\n\napp.on('login', (event, webContents, details, authInfo, callback) => {\n event.preventDefault()\n callback('username', 'secret')\n})\nЕсли calllback вызывается без имени пользователя или пароля, запрос аутентификации будет отменен и ошибка аутентификации будет возвращена на страницу.
Выдается при каждом обновлении информации о GPU.
\nВозвращает:
\neventkilled BooleanВозникает, когда процесс GPU аварийно завершает работу или завершается принудительно.
\nУстарело: Это событие заменяется событием child-process-gone, которое содержит больше информации о том, почему дочерний процесс исчез. It isn't always because it crashed. The killed boolean can be replaced by checking reason === 'killed' when you switch to that event.
Возвращает:
\neventwebContents WebContentskilled BooleanПроисходит, когда графический процесс webContents аварийно завершает работу или является убитым.
Deprecated: This event is superceded by the render-process-gone event which contains more information about why the render process disappeared. It isn't always because it crashed. The killed boolean can be replaced by checking reason === 'killed' when you switch to that event.
Возвращает:
\neventwebContents WebContentsdetailsreason String - The reason the render process is gone. Возможные значения:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Integer - The exit code of the process, unless reason is launch-failed, in which case exitCode will be a platform-specific launch failure error code.Emitted when the renderer process unexpectedly disappears. This is normally because it was crashed or killed.
\nВозвращает:
\neventdetailstype String - Тип процесса. Одно из следующих значений:UtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownreason String - Причина исчезновения дочернего процесса. Возможные значения:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Number - The exit code for the process (e.g. status from waitpid if on posix, from GetExitCodeProcess on Windows).serviceName String (optional) - The non-localized name of the process.name String (опционально) - Название процесса. Например: Audio Service, Content Decryption Module Service, Network Service, Video Capture и т.д.Emitted when the child process unexpectedly disappears. This is normally because it was crashed or killed. It does not include renderer processes.
\nВозвращает:
\neventaccessibilitySupportEnabled Boolean - true когда доступность поддержки Chrome включена, false в противном случае.Возникает при изменении Chrome поддержки специальных возможностей. Это событие срабатывает, когда вспомогательные технологии, такие как устройства чтения с экрана, включены или отключены. Смотрите https://www.chromium.org/developers/design-documents/accessibility для подробностей.
\nВозвращает:
\nsession SessionПроисходит, когда Electron создал новый объект session.
const { app } = require('electron')\n\napp.on('session-created', (session) => {\n console.log(session)\n})\nВозвращает:
\neventargv String [] - массив аргументов командной строки вторичных экземпляровworkingDirectory String - рабочий каталог вторичных экземпляровЭто событие произойдет внутри главного экземпляра Вашего приложения, когда второй экземпляр был запущен и вызывает app.requestSingleInstanceLock().
argv это массив аргументов командной строки второго экземпляра, а workingDirectory это текущая рабочая директория. Обычно приложения реагируют на это, делая их основное окно сфокусированным и не свернутым.
Примечание: Если второй экземпляр запускается другим пользователем, массив argv не будет содержать аргументы.
Это событие гарантировано происходит после события ready в app.
Примечание: Дополнительные аргументы командной строки могут быть добавлены Chromium, такие как --original-process-start-time.
Возвращает:
\neventwebContents WebContentsВозникает, когда desktopCapturer.getSources() вызывается в процессе рендерера webContents. Вызов event.preventDefault() вернет пустые источники.
Объект app имеет следующие методы:
Примечание: Некоторые методы доступны только в определенных операционных системах и помечены как таковые.
\napp.quit()Попробуйте закрыть все окна. Сначала возникнет событие before-quit. Если все окна успешно закрыты, событие will-quit возникнет и по умолчанию приложение будет завершено.
Этот метод гарантирует, что все обработчики событий beforeunload и unload выполнятся корректно. Вполне возможно, что окно отменит выход, возвращая false в обработчике событий beforeunload.
app.exit([exitCode])exitCode Integer (опционально)Немедленный выход с помощью exitCode. exitCode по умолчанию 0.
Все окна будут закрыты немедленно, без разрешения пользователя, а также события before-quit и will-quit не будут происходить.
app.relaunch([options])Перезапускает приложение, когда существует текущий экземпляр.
\nПо умолчанию, новый экземпляр будет использовать ту же самую рабочую директорию и аргументы командной строки, что и текущий экземпляр. Когда args указаны, args передадутся как аргументы командной строки. Когда execPath задан, вместо текущего приложения будет выполнен execPath для перезапуска.
Обратите внимание, что этот метод не завершает приложение при выполнении, Вам нужно вызвать app.quit или app.exit после вызова app.relaunch, чтобы перезапустить приложение.
Когда app.relaunch вызывается несколько раз, несколько экземпляров будет запущено после выхода из текущего экземпляра.
Пример немедленного перезапуска текущего экземпляра и добавления нового аргумента в командную строку нового экземпляра:
\nconst { app } = require('electron')\n\napp.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) })\napp.exit(0)\napp.isReady()Возвращает Boolean - true, если Electron завершил инициализацию, иначе false. См. также app.whenReady().
app.whenReady()Возвращает Promise<void> - выполняется при инициализации Electron. Может быть использован в качестве удобной альтернативы проверки app.isReady() и подписывания на событие ready, если приложение еще не готово.
app.focus([options])options Object (опционально)steal Boolean macOS - Make the receiver the active app even if another app is currently active.On Linux, focuses on the first visible window. On macOS, makes the application the active app. On Windows, focuses on the application's first window.
\nYou should seek to use the steal option as sparingly as possible.
app.hide() macOSСкрывает все окна приложения, не минимизируя их.
\napp.show() macOSПоказывает окна приложения после того, как они были скрыты. Автоматической фокусировки на них не происходит.
\napp.setAppLogsPath([path])path String (опционально) - пользовательский путь для Ваших логов. Должен быть абсолютным.Устанавливает или создает каталог логов Вашего приложения, которые затем могут быть обработаны с помощью app.getPath() или app.setPath(pathName, newPath).
Вызов app.setAppLogsPath() без параметра path приведет к тому, что этот каталог будет установлен на ~/Library/Logs/YourAppName на macOS, и внутри директории userData на Linux и Windows.
app.getAppPath()Возвращает String - текущая директория приложения.
app.getPath(name)name String - You can request the following paths by the name:home домашняя директория пользователя.appData Per-user application data directory, which by default points to:%APPDATA% на Windows$XDG_CONFIG_HOME или ~/.config на Linux~/Library/Application Support на macOSuserData директория для хранения файлов конфигурации Вашего приложения, которая по умолчанию является директорией appData с названием Вашего приложения в конце.кэшtemp временный каталог.exe текущий исполняемый файл.module библиотека libchromiumcontent.desktop директория рабочего стола, для текущего пользователя.documents директория пользователя \"Мои Документы\".downloads директория пользователя для загрузок.music директория пользователя для музыки.pictures директория пользователя для фотографий.videos директория пользователя для видео.recent Directory for the user's recent files (Windows only).logs директория для логов Вашего приложения.crashDumps Directory where crash dumps are stored.Returns String - A path to a special directory or file associated with name. On failure, an Error is thrown.
Если app.getPath('logs') вызывается без имени app.setAppLogsPath(), то сначала создается каталог журнала по умолчанию, эквивалентный вызову app.setAppLogsPath() без параметра path.
app.getFileIcon(path[, options])path Stringoptions Object (опционально)sizesmall - 16x16normal - 32x32large - 48x48 на Linux, 32x32 на Windows, не поддерживается на macOS.Возвращает Promise<NativeImage> - содержащий иконку приложения, которая является NativeImage.
Извлекает иконку, связанную с путем.
\nНа Windows есть 2 вида иконок:
\n.mp3, .png, и т.д..exe, .dll, .ico.На Linux и macOS иконки зависят от приложения, ассоциируемого с mime-типом файла.
\napp.setPath(name, path)name Stringpath StringПереопределяет path в специальную директорию или файл, связанный с name. Если путь задает каталог, который не существует, то при вызове выбросится Error. В этом случае каталог должен быть создан с помощью fs.mkdirSync или аналогичным способом.
Можно переопределять только пути name, определенные в app.getPath.
По умолчанию cookies и кэш веб-страницы будут храниться в директории userData. Если Вы хотите изменить это расположение, Вам необходимо переопределить путь userData прежде, чем событие ready модуля app произойдет.
app.getVersion()Возвращает String - версию загруженного приложения. Если версия не найдена в файле приложения package.json, возвращается версия текущего пакета или исполняемого файла.
app.getName()Возвращает String - имя текущего приложения, которое является именем в файле приложения package.json.
Обычно поле name в package.json является коротким именем, написанном в нижнем регистре, согласно спецификации модулей npm. Обычно Вы должны также указать поле productName, которое пишется заглавными буквами - имя Вашего приложения, и которое будет предпочтительнее name для Electron.
app.setName(name)name StringПереопределяет имя текущего приложения.
\nПримечание: Эта функция перекрывает имя, используемое внутри Electron; это не влияет на имя, которое использует ОС.
\napp.getLocale()Returns String - The current application locale, fetched using Chromium's l10n_util library. Possible return values are documented here.
To set the locale, you'll want to use a command line switch at app startup, which may be found here.
\nПримечание: При распространении упакованного приложения, нужно также добавить папку locales.
Примечание На Windows Вы должны вызывать этот метод после того, как событие ready произойдет.
app.getLocaleCountryCode()Returns String - User operating system's locale two-letter ISO 3166 country code. The value is taken from native OS APIs.
Примечание: Когда невозможно определить код страны языка, возвращает пустую строку.
\napp.addRecentDocument(path) macOS Windowspath StringДобавляет path к списку последних документов.
This list is managed by the OS. On Windows, you can visit the list from the task bar, and on macOS, you can visit it from dock menu.
\napp.clearRecentDocuments() macOS WindowsОчищает список последних документов.
\napp.setAsDefaultProtocolClient(protocol[, path, args])protocol String - имя вашего протокола, без ://. For example, if you want your app to handle electron:// links, call this method with electron as the parameter.path String (optional) Windows - The path to the Electron executable. Defaults to process.execPathargs String Windows - Arguments passed to the executable. По умолчанию пустой массивВозвращает Boolean - был ли вызов успешным.
Sets the current executable as the default handler for a protocol (aka URI scheme). It allows you to integrate your app deeper into the operating system. Once registered, all links with your-protocol:// will be opened with the current executable. The whole link, including protocol, will be passed to your application as a parameter.
Note: On macOS, you can only register protocols that have been added to your app's info.plist, which cannot be modified at runtime. However, you can change the file during build time via Electron Forge, Electron Packager, or by editing info.plist with a text editor. За подробными сведениями обращайтесь к документации компании Apple.
Примечание: В окружении Windows Store (когда упаковано как appx) этот метод вернет true для всех вызовов, но ключ реестра, который он устанавливает, не будет доступен другим приложениям. Чтобы зарегистрировать Ваше приложения в Windows Store как обработчик протокола по умолчанию, Вы должны объявить протокол в Вашем манифесте.
The API uses the Windows Registry and LSSetDefaultHandlerForURLScheme internally.
app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windowsprotocol String - имя вашего протокола, без ://.path String (optional) Windows - по умолчанию process.execPathargs String Windows - по умолчанию пустой массивВозвращает Boolean - был ли вызов успешным.
This method checks if the current executable as the default handler for a protocol (aka URI scheme). If so, it will remove the app as the default handler.
\napp.isDefaultProtocolClient(protocol[, path, args])protocol String - имя вашего протокола, без ://.path String (optional) Windows - по умолчанию process.execPathargs String Windows - по умолчанию пустой массивReturns Boolean - Whether the current executable is the default handler for a protocol (aka URI scheme).
Примечание: На macOS можно использовать этот метод для проверки, если приложение было зарегистрировано в качестве обработчика протокола по умолчанию для протокола. Вы также можете проверить это, проверив ~/Library/Preferences/com.apple.LaunchServices.plist на машине macOS. За подробными сведениями обращайтесь к документации компании Apple.
The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internally.
app.getApplicationNameForProtocol(url)url String - a URL with the protocol name to check. Unlike the other methods in this family, this accepts an entire URL, including :// at a minimum (e.g. https://).Returns String - Name of the application handling the protocol, or an empty string if there is no handler. For instance, if Electron is the default handler of the URL, this could be Electron on Windows and Mac. However, don't rely on the precise format which is not guaranteed to remain unchanged. Expect a different format on Linux, possibly with a .desktop suffix.
This method returns the application name of the default handler for the protocol (aka URI scheme) of a URL.
\napp.getApplicationInfoForProtocol(url) macOS Windowsurl String - a URL with the protocol name to check. Unlike the other methods in this family, this accepts an entire URL, including :// at a minimum (e.g. https://).Возвращает Promise<Object> - Разрешить с объектом, содержащим следующее:
icon NativeImage - the display icon of the app handling the protocol.path String - installation path of the app handling the protocol.name String - display name of the app handling the protocol.This method returns a promise that contains the application name, icon and path of the default handler for the protocol (aka URI scheme) of a URL.
\napp.setUserTasks(tasks) Windowstasks Task[] - массив объектов TaskДобавляет tasks к категории Tasks в JumpList на Windows.
tasks - массив объектов Task.
Возвращает Boolean - был ли вызов успешным.
Примечание: Если Вы хотите настроить список переходов еще больше - используйте app.setJumpList(categories).
app.getJumpListSettings() WindowsВозвращает Object:
minItems Integer - минимальное количество элементов, которые будут показаны в Jump List (для более подробного описания этого значение см. документация MSDN).removedItems JumpListItem [] - массив объектов JumpListItem, которые соответствуют элементам, которые пользователь явно удалил из настраиваемых категорий в Jump List. Эти элементы не должны быть снова добавлены в список переходов, при следующем вызове app.setJumpList(), Windows не будет отображать любую пользовательскую категорию, содержащую любой из удаленных элементов.app.setJumpList(categories) Windowscategories JumpListCategory[] | null - массив типа JumpListCategory, состоящий из объектов.Задает или удаляет пользовательский список переходов для приложения и возвращает одну из следующих строк:
\nok - ничего не случилось.error - произошла одна или несколько ошибок, включите ведение журнала выполнения, чтобы выяснить возможную ошибку.invalidSeparatorError - An attempt was made to add a separator to a custom category in the Jump List. Separators are only allowed in the standard Tasks category.fileTypeRegistrationError - была сделана попытка добавить ссылку на файл в список переходов для типа файла, который в приложении не зарегистрирован для обработки.customCategoryAccessDeniedError - пользовательские категории не могут быть добавлены в список переходов из-за ограничений конфиденциальности пользователей или групповой политики.Если categories - null, то ранее установленный пользовательский список переходов (если таковой имеется) будет заменён стандартным списком переходов для приложения (управляется Windows).
Примечание: Если объект JumpListCategory не имеет ни type, ни name свойства, тогда type считается как tasks. Если свойство name установлено, но свойство type опущено, тогда type считается custom.
Примечание: Пользователи могут удалять элементы из пользовательских категорий, но Windows не будет позволять возвращать удаленный элемент в пользовательскую категорию до следующего удачного вызова app.setJumpList(categories). Любая попытка вновь добавить удаленный элемент в пользовательскую категорию перед тем, как метод выполнится, приведёт к исключению всей категории из списка переходов. Список удаленных элементов можно получить с помощью app.getJumpListSetting().
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
Вот очень простой способ, как создать пользовательский список переходов:
\nconst { app } = require('electron')\n\napp.setJumpList([\n {\n type: 'custom',\n name: 'Recent Projects',\n items: [\n { type: 'file', path: 'C:\\\\Projects\\\\project1.proj' },\n { type: 'file', path: 'C:\\\\Projects\\\\project2.proj' }\n ]\n },\n { // has a name so `type` is assumed to be \"custom\"\n name: 'Tools',\n items: [\n {\n type: 'task',\n title: 'Tool A',\n program: process.execPath,\n args: '--run-tool-a',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool A'\n },\n {\n type: 'task',\n title: 'Tool B',\n program: process.execPath,\n args: '--run-tool-b',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool B'\n }\n ]\n },\n { type: 'frequent' },\n { // has no name and no type so `type` is assumed to be \"tasks\"\n items: [\n {\n type: 'task',\n title: 'New Project',\n program: process.execPath,\n args: '--new-project',\n description: 'Create a new project.'\n },\n { type: 'separator' },\n {\n type: 'task',\n title: 'Recover Project',\n program: process.execPath,\n args: '--recover-project',\n description: 'Recover Project'\n }\n ]\n }\n])\napp.requestSingleInstanceLock()Возвращает Boolean
Значение, которое возвращает этот метод, указывает, успешно или нет экземпляр Вашего приложения получило блокировку. Если не удалось получить блокировку, можно предположить, что другой экземпляр Вашего приложения уже запущен с блокировкой и немедленно выходит.
\nI.e. This method returns true if your process is the primary instance of your application and your app should continue loading. Возвращает false, если Ваш процесс должен немедленно завершиться, так как он отправил свои параметры другому экземпляру, которые уже приобрел блокировку.
На macOS система автоматически обеспечивает единственный экземпляр, когда пользователи пытаются открыть второй экземпляра Вашего приложения в Finder, для этого будут происходить open-file и open-url события. Так или иначе, когда пользователи запустят Ваше приложение через командную строку, системный механизм единственного экземпляра будет обойден, и Вы должны использовать этот метод, чтобы обеспечить единственный экземпляр.
Пример активации окна первичного экземпляра, при запуске второго экземпляра:
\nconst { app } = require('electron')\nlet myWindow = null\n\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Кто-то пытался запустить второй экземпляр, мы должны сфокусировать наше окно.\n if (myWindow) {\n if (myWindow.isMinimized()) myWindow.restore()\n myWindow.focus()\n }\n })\n\n // Создать myWindow, загрузить остальную часть приложения, и т.д.\n app.whenReady().then(() => {\n myWindow = createWindow()\n })\n}\napp.hasSingleInstanceLock()Возвращает Boolean
Этот метод возвращает состояние, является или нет экземпляр Вашего приложения в данный момент, удерживающим блокировку единственного экземпляра. Вы можете запросить блокировку с помощью app.requestSingleInstanceLock() и освободить с помощью app.releaseSingleInstanceLock()
app.releaseSingleInstanceLock()Releases all locks that were created by requestSingleInstanceLock. This will allow multiple instances of the application to once again run side by side.
app.setUserActivity(type, userInfo[, webpageURL]) macOStype String - уникально идентифицирует действие. Карты для NSUserActivity.activityType.userInfo any- специфичное, для приложения, состояние для использования другими устройствами.webpageURL String (optional) - The webpage to load in a browser if no suitable app is installed on the resuming device. The scheme must be http or https.Создает NSUserActivity и задает её в качестве текущей активности. Активность позже имеет право для Handoff на другом устройстве.
app.getCurrentActivityType() macOSВозвращает String - тип текущей выполняемой активности.
app.invalidateCurrentActivity() macOSАннулирует текущую Handoff активность пользователя.
\napp.resignCurrentActivity() macOSПомечает текущую Handoff активность пользователя как неактивную без ее отмены.
\napp.updateCurrentActivity(type, userInfo) macOStype String - уникально идентифицирует действие. Карты для NSUserActivity.activityType.userInfo any- специфичное, для приложения, состояние для использования другими устройствами.Обновляет текущую активность, если его тип совпадает с type, объединяет записи из userInfo в его текущем словаре userInfo.
app.setAppUserModelId(id) Windowsid StringИзменяет Application User Model ID на id.
app.setActivationPolicy(policy) macOSpolicy String - Can be 'regular', 'accessory', or 'prohibited'.Sets the activation policy for a given app.
\nActivation policy types:
\napp.importCertificate(options, callback) Linuxoptions Objectcertificate String - путь к pkcs12 файлу.password String - парольная фраза для сертификата.callback Functionresult Integer - результат импорта.Импорт сертификата в формате pkcs12 из платформы хранилища сертификатов. callback вызывается с result - результат операции импорта, значение 0 указывает на успех, все другие значения указывают на ошибку в соответствии со списком net_error_list в Chromium.
app.configureHostResolver(options)options ObjectenableBuiltInResolver Boolean (optional) - Whether the built-in host resolver is used in preference to getaddrinfo. When enabled, the built-in resolver will attempt to use the system's DNS settings to do DNS lookups itself. Enabled by default on macOS, disabled by default on Windows and Linux.secureDnsMode String (optional) - Can be \"off\", \"automatic\" or \"secure\". Configures the DNS-over-HTTP mode. When \"off\", no DoH lookups will be performed. When \"automatic\", DoH lookups will be performed first if DoH is available, and insecure DNS lookups will be performed as a fallback. When \"secure\", only DoH lookups will be performed. Defaults to \"automatic\".secureDnsServers String[] (optional) - A list of DNS-over-HTTP server templates. See RFC8484 § 3 for details on the template format. Most servers support the POST method; the template for such servers is simply a URI. Note that for some DNS providers, the resolver will automatically upgrade to DoH unless DoH is explicitly disabled, even if there are no DoH servers provided in this list.enableAdditionalDnsQueryTypes Boolean (optional) - Controls whether additional DNS query types, e.g. HTTPS (DNS type 65) will be allowed besides the traditional A and AAAA queries when a request is being made via insecure DNS. Has no effect on Secure DNS which always allows additional types. Defaults to true.Configures host resolution (DNS and DNS-over-HTTPS). By default, the following resolvers will be used, in order:
\ngetaddrinfo).This can be configured to either restrict usage of non-encrypted DNS (secureDnsMode: \"secure\"), or disable DNS-over-HTTPS (secureDnsMode: \"off\"). It is also possible to enable or disable the built-in resolver.
To disable insecure DNS, you can specify a secureDnsMode of \"secure\". If you do so, you should make sure to provide a list of DNS-over-HTTPS servers to use, in case the user's DNS configuration does not include a provider that supports DoH.
app.configureHostResolver({\n secureDnsMode: 'secure',\n secureDnsServers: [\n 'https://cloudflare-dns.com/dns-query'\n ]\n})\nЭтот API должен вызываться после того, как произошло событие ready.
app.disableHardwareAcceleration()Отключает аппаратное ускорение для текущего приложения.
\nЭтот метод может быть вызван только до того, как приложение будет готово.
\napp.disableDomainBlockingFor3DAPIs()By default, Chromium disables 3D APIs (e.g. WebGL) until restart on a per domain basis if the GPU processes crashes too frequently. This function disables that behavior.
\nЭтот метод может быть вызван только до того, как приложение будет готово.
\napp.getAppMetrics()Возвращает ProcessMetric[]: массив объектов ProcessMetric, которые соответствует статистике использования памяти и CPU всех процессов, связанных с приложением.
app.getGPUFeatureStatus()Возвращает GPUFeatureStatus - статус функции графики из chrome://gpu/.
Примечание: Эта информация может использоваться только после возникновения события gpu-info-update.
app.getGPUInfo(infoType)infoType String - Может быть basic или complete.Возвращает Promise<unknown>
Для infoType равным complete: Промис выполняется с объектом, содержащий всю GPU информацию как в объекте GPUInfo в chromium. Это включает информацию о версии и драйвере, показанную на странице chrome://gpu.
Для infoType равным basic: Промис выполняется с объектом, содержащий меньшее количество атрибутов, чем когда запрашивается с complete. Вот пример базового ответа:
{\n auxAttributes:\n {\n amdSwitchable: true,\n canSupportThreadedTextureMailbox: false,\n directComposition: false,\n directRendering: true,\n glResetNotificationStrategy: 0,\n inProcessGpu: true,\n initializationTime: 0,\n jpegDecodeAcceleratorSupported: false,\n optimus: false,\n passthroughCmdDecoder: false,\n sandboxed: false,\n softwareRendering: false,\n supportsOverlays: false,\n videoDecodeAcceleratorFlags: 0\n },\n gpuDevice:\n [{ active: true, deviceId: 26657, vendorId: 4098 },\n { active: false, deviceId: 3366, vendorId: 32902 }],\n machineModelName: 'MacBookPro',\n machineModelVersion: '11.5'\n}\nИспользование basics должно быть предпочтительным, если требуется только основная информация, такая как vendorId или driverId.
app.setBadgeCount([count]) Linux macOScount Integer (optional) - If a value is provided, set the badge to the provided value otherwise, on macOS, display a plain white dot (e.g. unknown number of notifications). On Linux, if a value is not provided the badge will not display.Возвращает Boolean - был ли вызов успешным.
Sets the counter badge for current app. Setting the count to 0 will hide the badge.
На macOS отображается на иконке в Dock. На Linux работает только для лаунчера Unity.
\nПримечание: для работы Unity лаунчера требуется файл .desktop. Дополнительную информациюможно прочесть в Документации по интеграции Юнити.
app.getBadgeCount() Linux macOSВозвращает Integer - текущее значение, отображаемое в значке счётчика.
app.isUnityRunning() LinuxВозвращает Boolean - является ли текущее окружение рабочего стола Unity.
app.getLoginItemSettings([options]) macOS Windowsoptions Object (опционально)Если Вы предоставили параметры path и args в app.setLoginItemSettings, тогда Вам необходимо передать те же аргументы сюда, чтобы openAtLogin установилось корректно.
Возвращает Object:
openAtLogin Boolean - true если приложение планируется открыть при входе в систему.openAsHidden Boolean macOS - true if the app is set to open as hidden at login. Эта настройка недоступна в сборках MAS.wasOpenedAtLogin Boolean macOS - true if the app was opened at login automatically. Эта настройка недоступна в сборках MAS.wasOpenedAsHidden Boolean macOS - true if the app was opened as a hidden login item. Это означает, что приложению не следует открывать любое окно при запуске. Эта настройка недоступна в сборках MAS.restoreState Boolean macOS - true if the app was opened as a login item that should restore the state from the previous session. Это означает, что приложение должно восстановить окна, которые были открыты в последний раз, когда приложение было закрыто. Эта настройка недоступна в сборках MAS.executableWillLaunchAtLogin Boolean Windows - true if app is set to open at login and its run key is not deactivated. This differs from openAtLogin as it ignores the args option, this property will be true if the given executable would be launched at login with any arguments.launchItems Object[] Windowsname String Windows - name value of a registry entry.path String Windows - The executable to an app that corresponds to a registry entry.args String[] Windows - the command-line arguments to pass to the executable.scope String Windows - one of user or machine. Indicates whether the registry entry is under HKEY_CURRENT USER or HKEY_LOCAL_MACHINE.enabled Boolean Windows - true if the app registry key is startup approved and therefore shows as enabled in Task Manager and Windows settings.app.setLoginItemSettings(settings) macOS Windowssettings ObjectopenAtLogin Boolean (optional) - true to open the app at login, false to remove the app as a login item. Defaults to false.openAsHidden Boolean (optional) macOS - true to open the app as hidden. Значение по умолчанию: false. Пользователь может редактировать этот параметр в системных настройках, так что app.getLoginItemSettings().wasOpenedAsHidden должно быть проверено, когда приложение открыто, чтобы узнать текущее значение. Эта настройка недоступна в сборках MAS.path String (optional) Windows - The executable to launch at login. Defaults to process.execPath.args String Windows - The command-line arguments to pass to the executable. Defaults to an empty array. Take care to wrap paths in quotes.enabled Boolean (optional) Windows - true will change the startup approved registry key and enable / disable the App in Task Manager and Windows Settings. Defaults to true.name String (optional) Windows - value name to write into registry. Defaults to the app's AppUserModelId(). Установите приложению параметры при входе в систему.Для работы с Electron autoUpdater на Windows, который использует Squirrel, вы можете задать путь запуска Update.exe и передавать аргументы, которые указывают на имя приложения. Например:
const appFolder = path.dirname(process.execPath)\nconst updateExe = path.resolve(appFolder, '..', 'Update.exe')\nconst exeName = path.basename(process.execPath)\n\napp.setLoginItemSettings({\n openAtLogin: true,\n path: updateExe,\n args: [\n '--processStart', `\"${exeName}\"`,\n '--process-start-args', `\"--hidden\"`\n ]\n})\napp.isAccessibilitySupportEnabled() macOS WindowsВозвращает Boolean - true если включена поддержка специальных возможностей Chrome, и false в противном случае. Этот API будет возвращать true, если обнаружено использование вспомогательных технологий, таких как средства чтения с экрана. Смотрите https://www.chromium.org/developers/design-documents/accessibility для подробностей.
app.setAccessibilitySupportEnabled(enabled) macOS Windowsenabled Boolean - включить или отключить рендеринг древа специальных возможностейВручную включает поддержку специальных возможностей от Chrome, позволяя пользователям открывать специальные возможности в настройках приложения. Смотрите документацию специальных возможностей Chromium для подробной информации. Отключено по умолчанию.
\nЭтот API должен вызываться после того, как произошло событие ready.
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
\napp.showAboutPanel()Show the app's about panel options. These options can be overridden with app.setAboutPanelOptions(options).
app.setAboutPanelOptions(options)options ObjectapplicationName String (опиционально) - имя приложения.applicationVersion String (опиционально) - версия приложения.copyright String (опиционально) - copyright информация.version String (optional) macOS - The app's build version number.credits String (optional) macOS Windows - Credit information.authors String Linux - List of app authors.website String (optional) Linux - The app's website.iconPath String (optional) Linux Windows - Path to the app's icon in a JPEG or PNG file format. On Linux, will be shown as 64x64 pixels while retaining aspect ratio.Установите описание панели опций. This will override the values defined in the app's .plist file on macOS. Смотрите Apple docs для получения более подробной информации. На Linux необходимо устанавливать все значения; по умолчанию значений нет.
If you do not set credits but still wish to surface them in your app, AppKit will look for a file named \"Credits.html\", \"Credits.rtf\", and \"Credits.rtfd\", in that order, in the bundle returned by the NSBundle class method main. The first file found is used, and if none is found, the info area is left blank. See Apple documentation for more information.
app.isEmojiPanelSupported()Возвращает Boolean - позволяет или нет текущая версия ОС выбирать нативные эмодзи.
app.showEmojiPanel() macOS WindowsПоказывает нативный выбор эмодзи.
\napp.startAccessingSecurityScopedResource(bookmarkData) masbookmarkData String - Закодированные base64 данные закладки области безопасности, возвращаемые dialog.showOpenDialog или dialog.showSaveDialog.Returns Function - This function must be called once you have finished accessing the security scoped file. Если Вы забыли, запретить доступ к закладке, возможно утечка ресурсов ядра и ваше приложение потеряет свою способность выйти за пределы песочницы, пока не будет перезапущено.
// Получение доступа к файлу.\nconst stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)\n// Теперь вы можете получить доступ к файлу за пределами песочницы🎉\n\n// Не забудьте прекратить доступ к файлу после того, как закончите с ним.\nstopAccessingSecurityScopedResource()\nНачать доступ в области безопасности ресурса. С помощью этого метода Electron приложения, которые упакованы для Mac App Store, могут выходить на пределы их песочницы, чтобы получить файлы, выбранные пользователем. Подробное описание как работает эта система, смотри Apple's documentation.
\napp.enableSandbox()Включает полноценный режим песочницы в приложении. Это означает, что все рендереры будут запускаться изолированно, независимо от значения параметра sandbox флаг в WebPreferences.
Этот метод может быть вызван только до того, как приложение будет готово.
\napp.isInApplicationsFolder() macOSВозвращает Boolean - выполняется ли приложение в данный момент из системной папки Приложения. Используйте в сочетании с app.moveToApplicationsFolder()
app.moveToApplicationsFolder([options]) macOSoptions Object (опционально)conflictHandler Function\\conflictType String - Тип конфликта перемещения, с которым столкнулся обработчик; может быть exists или existsAndRunning, где exists означает, что приложение с тем же именем присутствует в каталоге приложений, а existsAndRunning означает, что он существует и работает в данный момент.Возвращает Boolean - если перемещение было успешным. Обратите внимание, что если перемещение выполнено успешно, ваше приложение закроется и перезапустится.
По умолчанию диалоговое окно подтверждения не отображается. Если нужно подтверждение операции пользователем, используйте dialog API.
ПРИМЕЧАНИЕ: Этот метод выдает ошибки, если что-то, кроме пользователя, вызывает переход к неудачи. Например, если пользователь отменяет диалоговое окно авторизации, этот метод возвращает false. Если нам не удастся выполнить копирование, этот метод вызовет ошибку. Сообщение об ошибке должно быть информативным и сообщать вам именно то, что пошло не так.
\nПо умолчанию, если приложение с тем же именем, что и перемещаемое, существует в каталоге Applications и not запущено, существующее приложение будет удалено, а активное приложение перемещено на свое место. Если оно работает, на уже существующее запущенное приложение переместится фокус, а ранее активное приложение само завершит работу. Это поведение можно изменить, предоставив необязательный обработчик конфликтов, где логическое значение, возвращаемое обработчиком, определяет, будет ли конфликт перемещения разрешен с поведением по умолчанию. то есть возврат false гарантирует, что дальнейшие действия не будут приняты, возврат true приведет к поведению по умолчанию и продолжению метода.
Например:
\napp.moveToApplicationsFolder({\n conflictHandler: (conflictType) => {\n if (conflictType === 'exists') {\n return dialog.showMessageBoxSync({\n type: 'question',\n buttons: ['Halt Move', 'Continue Move'],\n defaultId: 0,\n message: 'An app of this name already exists'\n }) === 1\n }\n }\n})\nБудет означать, что если приложение уже существует в каталоге пользователя, если пользователь выберет 'Continue Move', то эта функция будет продолжена с поведением по умолчанию, и существующее приложение будет удалено и активное приложение будет перемещено на место.
\napp.isSecureKeyboardEntryEnabled() macOSВозвращает Boolean - если включен Secure Keyboard Entry.
По умолчанию этот API вернет false.
app.setSecureKeyboardEntryEnabled(enabled) macOSenabled Boolean - Включить или отключить Secure Keyboard EntryУстановка Secure Keyboard Entry включена в вашем приложении.
Используя этот API, можно предотвратить перехват важной информации, такой как пароль и другую конфиденциальную информацию, другими процессами.
\nСм. Apple's documentation для получения дополнительной информации подробности.
\nПримечание: Включайте Secure Keyboard Entry только тогда, когда он нужен, и отключайте, когда он больше не нужен.
app.accessibilitySupportEnabled macOS WindowsBoolean свойство, которое true, если поддержка специальных возможностей Chrome включена, иначе false. Это свойство будет true, если использование вспомогательных технологий, таких как средства чтения с экрана, были обнаружены. Устанавливая это свойство на true, вручную включает поддержку специальных возможностей Chrome, позволяя разработчикам показать пользователю переключатели специальных возможностей в настройках приложения.
См. Chromium's accessibility docs для получения более подробной информации. Отключено по умолчанию.
\nЭтот API должен вызываться после того, как произошло событие ready.
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
\napp.applicationMenuA Menu | nullсвойство, которое возвращает Menu если оно было установлено, в противном случае возвращает null. Пользователи могут передать Меню, чтобы установить это свойство.
app.badgeCount Linux macOSСвойство Integer, которое возвращает количество значков для текущего приложения. Установка счетчика на 0 скроет значок.
В macOS установка любого ненулевого целого числа отображается на значке док-станции. В Linux это свойство работает только для модуля запуска Unity.
\nПримечание: для работы Unity лаунчера требуется файл .desktop. Дополнительную информациюможно прочесть в Документации по интеграции Юнити.
Примечание: На macOS, вы должны убедиться, что ваше приложение имеет разрешение на отображение уведомлений.
\napp.commandLine ReadonlyОбъект CommandLine, который позволяет читать и манипулировать аргументами командной строки, используемыми Chromium.
app.dock macOS ReadonlyЭто Dock | undefined объект, который позволяет вам выполнять действия со значком вашего приложения в пользовательском док на macOS.
app.isPackaged ReadonlyBoolean свойство, которое возвращает true, если приложение упаковано, false иначе. Для многих приложений это свойство может использоваться для отличия среды разработки и производства.
app.nameСвойство String, указывающее имя текущего приложения, которое является именем в файле package.json.
Обычно поле name в package.json является коротким именем, написанном в нижнем регистре, согласно спецификации модулей npm. Обычно Вы должны также указать поле productName, которое пишется заглавными буквами - имя Вашего приложения, и которое будет предпочтительнее name для Electron.
app.userAgentFallbackСтрока, которая является строкой агента пользователя, которую Electron будет использовать в качестве глобального запаса.
Это агент пользователя, который будет использоваться, если ни один агент пользователя не установлен на уровнях webContents или session. Это полезно для того, чтобы все ваше приложение имело один и тот же пользовательский агент. Установите пользовательское значение как можно раньше в инициализации Ваших приложений, чтобы убедиться, что используется переопределенное значение.
app.runningUnderRosettaTranslation macOS Readonly DeprecatedA Boolean which when true indicates that the app is currently running under the Rosetta Translator Environment.
Вы можете использовать это свойство, чтобы предложить пользователям загрузить версию для arm64 вашего приложения, когда они запускают версию x64 под Rosetta неправильно.
\nDeprecated: This property is superceded by the runningUnderARM64Translation property which detects when the app is being translated to ARM64 in both macOS and Windows.
app.runningUnderARM64Translation Readonly macOS WindowsA Boolean which when true indicates that the app is currently running under an ARM64 translator (like the macOS Rosetta Translator Environment or Windows WOW).
Вы можете использовать это свойство, чтобы предложить пользователям загрузить версию для arm64 вашего приложения, когда они запускают версию x64 под Rosetta неправильно.
", "title": "app", "description": "Контролируйте жизненный цикл Вашего приложения." }, "/docs/tutorial/application-debugging": { "locale": "ru-RU", "slug": "application-debugging", "href": "/docs/tutorial/application-debugging", "crowdinFileId": "256175", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/application-debugging.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Всякий раз, когда ваше приложение Electron не ведет себя так, как вы этого хотели, массив средств отладки может помочь вам найти ошибки в кодировании, узкие места производительности или возможности оптимизации.
\nНаиболее полным инструментом для отладки отдельных процессов рендеринга является набор инструментов разработчика Chromium. Он доступен для всех процессов рендеринга, включая экземпляры таких объектов как BrowserWindow, BrowserView, и WebView. Вы можете открыть их программно, вызывая API openDevTools() в webContents экземпляра:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.webContents.openDevTools()\nGoogle предлагает отличную документацию для своих инструментов разработчика. Мы рекомендуем вам ознакомиться с ними - они, как правило, являются одними из самых мощных утилит в инструментальном окружении для разработчиков Electron.
\nОтладка основного процесса немного сложнее, поскольку вы не можете открыть для них инструменты для разработчиков. Инструменты Chromium Developer Tools могут использоваться для отладки основного процесса Electron благодаря более тесному сотрудничеству между Google / Chrome и Node.js, но вы можете столкнуться с такими странностями, которые вам не нужны в консоли.
Для получения дополнительной информации см. Документацию Отладка основной процедуры.
\nIf the V8 context crashes, the DevTools will display this message.
\nDevTools was disconnected from the page. Once page is reloaded, DevTools will automatically reconnect.
Chromium logs can be enabled via the ELECTRON_ENABLE_LOGGING environment variable. Для получения дополнительной информации обратитесь к документации по переменным окружения.
Alternatively, the command line argument --enable-logging can be passed. Дополнительная информация доступна в switches документации командной строки.
To distribute your app with Electron, you need to package and rebrand it. Для этого можно использовать специализированный инструментарий или ручной подход.
\nВы можете использовать следующие инструменты для распространения вашего приложения:
\n\nЭти инструменты позаботятся о всех шагах, которые вам нужно предпринять, чтобы получить распространяемое приложение Electron, такие как сборка вашего приложения, ребрендинг выполнения и установка нужных иконок.
\nYou can check the example of how to package your app with electron-forge in the Quick Start guide.
Для ручного распространения вашего приложения Electron, вам нужно скачать предварительно собранные двоичные файлы Electron. Далее папку, содержащую ваше приложение следует назвать app и поместить в каталог ресурсов Electron, как показано в следующих примерах.
\n\nПРИМЕЧАНИЕ: расположение заранее встроенных двоичных файлов Electron указывается на примерах ниже, начиная с
\nelectron/.
На macOS:
\nelectron/Electron.app/Contents/Resources/app/\n├── package.json\n├── main.js\n└── index.html\nНа Windows и Linux:
\nelectron/resources/app\n├── package.json\n├── main.js\n└── index.html\nThen execute Electron.app on macOS, electron on Linux, or electron.exe on Windows, and Electron will start as your app. The electron directory will then be your distribution to deliver to users.
Вместо того, чтобы отправлять ваше приложение, копируя все исходные файлы, вы можете запаковать ваше приложение в asar архив, чтобы улучшить производительность чтения файлов на платформах, таких как Windows, если вы еще не используете такой пакет как Parcel или Webpack.
\nЧтобы использовать архив asar для замены каталога app, необходимо переименовать архив в app.asar и положить его в каталог ресурсов Electron, как показано ниже, и Electron будет пытаться прочитать архив и начать с него.
На macOS:
\nelectron/Electron.app/Contents/Resources/\n└── app.asar\nНа Windows и Linux:
\nelectron/resources/\n└── app.asar\nБолее подробную информацию об использовании asar вы можете найти в репозитории electron/asar.
После построения вашего приложения в Electron и перед распространением вам следует провести его ребрендинг.
\nВы можете переименовать Electron.app, а также вы должны переименовать поля CFBundleDisplayName, CFBundleIdentifier и CFBundleName в следующих файлах:
Electron.app/Contents/Info.plistElectron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plistВы также можете переименовать helper приложения, чтобы избежать показа Electron Helper в Activity Monitor, но убедитесь, что вы переименовали имя исполняемого файла helper приложения.
Структура переименования app будет такая:
\nMyApp.app/Contents\n├── Info.plist\n├── MacOS/\n│ └── MyApp\n└── Frameworks/\n └── MyApp Helper.app\n ├── Info.plist\n └── MacOS/\n └── MyApp Helper\nВы можете сменить имя файла electron.exe на любое понравившееся, отредактировать его значок и другую информацию такими инструментами, как rcedit.
Electron исполняемый файл можно переименовать на любое имя, которое вам нравится.
Можно изменить бренд Electron путем изменения имени продукта и сборки его из исходных кодов. Для этого вам надо установить аргумент, отвечающий за имя продукта (electron_product_name = \"YourProductName\") в файле args.gn и пересобрать Electron.
\n\nПозвольте приложениям автоматически обновляться.
\n
Процесс: Основной
\nСм. также: Подробное руководство о том, как внедрять обновления в Ваше приложение.
\nautoUpdater это EventEmitter.
В настоящее время поддерживаются только macOS и Windows. На Linux нет встроенной поддержи автоматического обновление, поэтому рекомендуется использовать менеджер пакетов для обновления вашего приложения.
\nКроме того есть некоторые тонкие различия на каждой платформе:
\nНа macOS модуль autoUpdater построен на Squirrel.Mac, что означает, что Вам не нужно делать каких-либо специальных настроек, чтобы заставить его работать. Для серверных условий, Вы можете прочитать Поддержку сервера. Заметьте, что App Transport Security (ATS) применяется ко всем запросам, сделанным как часть процесса обновления. Приложению, у которого требуется отключить ATS, можно добавить ключ NSAllowsArbitraryLoads в список свойств приложения (plist).
Примечание: Ваше приложение должно быть подписано для автоматических обновлений на macOS. Это требование Squirrel.Mac.
На Windows Вам придется установить приложение на компьютер пользователя, прежде чем Вы сможете использовать autoUpdater, поэтому рекомендуется использовать пакет electron-winstaller, electron-forge или grunt-electron-installer для создания установщика Windows.
При использовании electron-winstaller или electron-forge убедитесь, что Вы не пытаетесь обновить ваше приложение при первом запуске (также см. этот вопрос для получения дополнительной информации). Также рекомендуется использовать electron-squirrel-startup, для получения ярлыка Вашего приложения на рабочем столе.
\nУстановщик, сгенерированный с помощью Squirrel, создаст ярлык с Application User Model ID в формате com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE, com.squirrel.slack.Slack и com.squirrel.code.Code. Вы должны использовать тот же ID для Вашего приложения в app.setAppUserModelId API, иначе Windows не сможет должным образом закрепить приложение в панели задач.
Как и Squirrel.Mac, Windows может размещать обновления на S3 или любом другом статическом файловом хосте. Вы можете прочитать документацию о Squirrel.Windows, для получения более подробной информации о том, как работает Squirrel.Windows.
\nОбъект autoUpdater имеет следующие события:
Возвращает:
\nerror ErrorВозникает когда происходит ошибка при обновлении.
\nВозникает при проверке, если обновление началось.
\nПроисходит при наличии доступного обновления. Обновление загружается автоматически.
\nВозникает, когда нет доступных обновлений.
\nВозвращает:
\neventreleaseNotes StringreleaseName StringreleaseDate DateupdateURL StringВозникает при загрузке обновления.
\nНа Windows доступен только releaseName.
Примечание: Не обязательно обрабатывать это событие. Успешно загруженное обновление будет применено при следующем запуске приложения.
\nЭто событие происходит после вызова quitAndInstall().
Когда это API вызывается, событие before-quit не будет происходить, до тех пор, пока все окна не будут закрыты. В результате Вы должны прослушивать это событие, если хотите выполнить действия до закрытия окон, во время завершения процесса, а также прослушивать before-quit.
Объект autoUpdater имеет следующие методы:
autoUpdater.setFeedURL(options)options Objecturl Stringheaders Record<String, String> (optional) macOS - HTTP request headers.serverType String (опционально) macOS - может быть json, либо default, смотрите README Squirrel.Mac для подробной информации.Задает url и инициализирует автоматическое обновление.
autoUpdater.getFeedURL()String - возвращает URL текущей подписки обновления.
autoUpdater.checkForUpdates()Спрашивает сервер, есть ли обновление. Вы должны вызвать setFeedURL перед использованием API.
Note: If an update is available it will be downloaded automatically. Calling autoUpdater.checkForUpdates() twice will download the update two times.
autoUpdater.quitAndInstall()Перезапускает приложение и устанавливает обновление после его загрузки. Следует вызывать только после произошедшего update-downloaded.
Внутри, вызов autoUpdater.quitAndInstall() сначала закроет все окна приложения, и автоматически вызовет app.quit(), после того, как все окна будут закрыты.
Note: It is not strictly necessary to call this function to apply an update, as a successfully downloaded update will always be applied the next time the application starts.
", "title": "autoUpdater", "description": "Позвольте приложениям автоматически обновляться." }, "/docs/tutorial/automated-testing-with-a-custom-driver": { "locale": "ru-RU", "slug": "automated-testing-with-a-custom-driver", "href": "/docs/tutorial/automated-testing-with-a-custom-driver", "crowdinFileId": "256179", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/automated-testing-with-a-custom-driver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Для написания автоматических тестов для вашего приложения Electron вам понадобится способ \"управлять\" вашим приложением. Spectron - это широко используемое решение, которое позволяет вам эмулировать действия пользователя через WebDriver. Тем не менее, также можно написать свой собственный драйвер с помощью встроенного в узел IPC-over-STDIO. Преимущество собственного драйвера состоит в том, что он требует меньше служебных данных, чем Spectron, и позволяет вам использовать собственные методы для вашего набора тестов.
\nЧтобы создать собственный драйвер, мы будем использовать Node.js API child_process. Набор тестов вызовет процесс Electron, а затем установит простой протокол обмена сообщениями:
\nconst childProcess = require('child_process')\nconst electronPath = require('electron')\n\n// spawn the process\nconst env = { /* ... */ }\nconst stdio = ['inherit', 'inherit', 'inherit', 'ipc']\nconst appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })\n\n// listen for IPC messages from the app\nappProcess.on('message', (msg) => {\n // ...\n})\n\n// отправляем IPC сообщение в приложение\nappProcess.send({ my: 'message' })\nИз приложения Electron вы можете прослушивать сообщения и посылать ответы с помощью API process из Node.js:
\n// слушаем IPC сообщение из теста\nprocess.on('message', (msg) => {\n // ...\n})\n\n// отправляем IPC сообщение в тест\nprocess.send({ my: 'message' })\nТеперь мы можем передавать данные из теста в приложению Electron, используя объект appProcess.
Для удобства, вы можете обернуть appProcess в объект драйвера, который предоставляет более высокоуровневые функции. Here is an example of how you can do this:
class TestDriver {\n constructor ({ path, args, env }) {\n this.rpcCalls = []\n\n // start child process\n env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages\n this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })\n\n // handle rpc responses\n this.process.on('message', (message) => {\n // pop the handler\n const rpcCall = this.rpcCalls[message.msgId]\n if (!rpcCall) return\n this.rpcCalls[message.msgId] = null\n // reject/resolve\n if (message.reject) rpcCall.reject(message.reject)\n else rpcCall.resolve(message.resolve)\n })\n\n // wait for ready\n this.isReady = this.rpc('isReady').catch((err) => {\n console.error('Application failed to start', err)\n this.stop()\n process.exit(1)\n })\n }\n\n // simple RPC call\n // to use: driver.rpc('method', 1, 2, 3).then(...)\n async rpc (cmd, ...args) {\n // send rpc request\n const msgId = this.rpcCalls.length\n this.process.send({ msgId, cmd, args })\n return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))\n }\n\n stop () {\n this.process.kill()\n }\n}\nВ приложении вам нужно будет написать простой обработчик для вызовов RPC:
\nif (process.env.APP_TEST_DRIVER) {\n process.on('message', onMessage)\n}\n\nasync function onMessage ({ msgId, cmd, args }) {\n let method = METHODS[cmd]\n if (!method) method = () => new Error('Invalid method: ' + cmd)\n try {\n const resolve = await method(...args)\n process.send({ msgId, resolve })\n } catch (err) {\n const reject = {\n message: err.message,\n stack: err.stack,\n name: err.name\n }\n process.send({ msgId, reject })\n }\n}\n\nconst METHODS = {\n isReady () {\n // do any setup needed\n return true\n }\n // define your RPC-able methods here\n}\nЗатем в тесте можно использовать тестовый драйвер следующим образом:
\nconst test = require('ava')\nconst electronPath = require('electron')\n\nconst app = new TestDriver({\n path: electronPath,\n args: ['./app'],\n env: {\n NODE_ENV: 'test'\n }\n})\ntest.before(async t => {\n await app.isReady\n})\ntest.after.always('cleanup', async t => {\n await app.stop()\n})\nElectron CI на Windows использует AppVeyor, который в свою очередь использует изображения Azure VM для запуска. Occasionally, these VM images need to be updated due to changes in Chromium requirements. In order to update you will need PowerShell and the Azure PowerShell module.
\nOccasionally we need to update these images owing to changes in Chromium or other miscellaneous build requirement changes.
\nПример применения:\n* We need VS15.9 and we have VS15.7 installed; this would require us to update an Azure image.
Identify the image you wish to modify.
\nGet the Azure storage account key
\nappveyorlibccbuilds Disk Storage Account Name you'd look for appveyorlibccbuilds in the list of storage accounts @ Home < Storage AccountsAccess Keys, and then you can use any of the keys present in the list.Get the full virtual machine image URI from Azure
\n$ACCT_NAME < Blobs < ImagesCopy the image using the Copy Master Image PowerShell script.
\n(images)libcc-20core-vs2017-15.9-2019-04-15.vhdSpin up a new VM using the Create Master VM from VHD PowerShell.
\nps1 file with ./create_master_vm_from_vhd.ps1Standard_F32s_v2East USLog back into Azure and find the VM you just created in Home < Virtual Machines < $YOUR_NEW_VM
Using Microsoft Remote Desktop, click Connect to connect to the VM.
AppVeyor Enterprise master VM credentials.Modify the VM as required.
\nShut down the VM and then delete it in Azure.
\nAdd the new image to the Appveyor Cloud settings or modify an existing image to point to the new VHD.
\ndeviceName StringdeviceId StringРазработка в Electron разнообразна - нет \"одного истинного пути\" для разработки, сборки, упаковки или выпуска приложения. Дополнительные особенности для Electron, как для сборки, так и для времени выполнения, обычно можно найти в npm в отдельных пакетах, что позволяет разработчикам как создать приложение, так и построить конвейер, в котором они нуждаются.
\nЭтот уровень модульности и расширяемости гарантирует, что все разработчики, работающие с Electron, как большие, так и малые по размеру группы, никогда не ограничены тем, что они могут или не могут делать в любое время в течение своего жизненного цикла разработки. Тем не менее, для многих разработчиков один из управляемых сообществом шаблонов или инструментов командной строки может значительно упростить компиляцию, упаковку и выпуск приложения.
\nШаблон является только отправной точкой - это, так сказать, холст, из которого вы создаете свое приложение. Они обычно приходят в виде репозитория, который вы можете клонировать и настраивать ваш контент.
\nС другой стороны, инструмент командной строки продолжает поддерживать вас на протяжении всей разработки и выпуска. Они более полезны и поддерживаемы, но обеспечивают соблюдение рекомендаций о том, как ваш код должен быть структурирован и построен. Специально для новичков - использование командной строки будет весьма полезно.
\n\"Полноценный инструмент для создания современных приложений Electron\". Electron Forge объединяет существующие (и хорошо поддерживаемые) инструменты сборки в единый пакет, чтобы каждый мог прямо сейчас заняться разработкой в Electron.
\nForge поставляется с готовым к использованию шаблонои, используя Webpack в качестве бандлера. Он включает в себя пример конфигурации typescript и предоставляет два конфигурационных файла, которые позволяют легко настраивать. It uses the same core modules used by the greater Electron community (like electron-packager) – changes made by Electron maintainers (like Slack) benefit Forge's users, too.
Вы можете найти больше информации и документации на electronforge.io.
\n\"Полноценное решение для упаковки и создания готового к использованию приложения Electron\", которое фокусируется на интегрированном опыте. electron-builder добавляет одну единственную зависимость, ориентированную на простоту, и управляет всеми дополнительными требованиями изнутри.
electron-builder заменяет функции и модули, используемые майнтейнерами Electron (такими как автообновление) с пользовательскими. Они, как правило, более тесно интегрированы, но будут иметь меньше общего с популярными приложениями Electron, такими как Atom, Visual Studio Code или Slack.
Вы можете найти дополнительную информацию и документацию в репозитории.
\nЕсли вам не нужны какие-либо инструменты, а только плоский шаблон, из которого можно собрать приложение, вам стоит взглянуть на electron-react-boilerplate. Он довольно популярен в сообществе и использует встроенный electron-builder.
Список «Awesome Electron» предоставляет большой выбор инструментов и шаблонов. Если вы обнаружите, что длина списка вас пугает, не забывайте, что можно добавлять инструменты по ходу работы.
", "title": "Макеты и CLI", "description": "" }, "/docs/breaking-changes": { "locale": "ru-RU", "slug": "breaking-changes", "href": "/docs/breaking-changes", "crowdinFileId": "256117", "githubUrl": "https://github.com/electron/electron/tree/main/docs/breaking-changes.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Здесь будут описаны критические изменения, а также будут добавлены предупреждения об устаревших функциях в JS коде, где это возможно, по крайней мере перед тем, как изменения будут сделаны в одной мажорной версии.
\nВ этом документе используется следующее соглашение для классификации критических изменений:
\nremote moduleThe remote module was deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.
// Deprecated in Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// Replace with:\nconst { BrowserWindow } = require('@electron/remote')\n\n// In the main process:\nrequire('@electron/remote/main').initialize()\napp.allowRendererProcessReuseThe app.allowRendererProcessReuse property will be removed as part of our plan to more closely align with Chromium's process model for security, performance and maintainability.
Для подробностей см. #18397.
\nПараметр affinity при создании нового BrowserWindow будет удален в рамках нашего плана для более тесной связи с моделью процесса Chrome в целях безопасности, производительность и лучшей поддержки.
Для подробностей см. #18397.
\nwindow.open()Необязательный параметр frameName больше не устанавливает название окна. Теперь это следует спецификации, описанной в документации в соответствии с параметром windowName.
Если вы использовали этот параметр, чтобы задать заголовок окна, вы можете использовать win.setTitle(title).
\nworldSafeExecuteJavaScriptВ Electron 14 worldSafeExecuteJavaScript будет удален. Альтернатива отсутствует, пожалуйста, убедитесь, что в вашем коде данный параметр включен. Он был включен в Electron по умолчанию\n12.
На вас повлияет это изменение, если вы используете либо webFrame.executeJavaScript или webFrame.executeJavaScriptInIsolatedWorld. Вам нужно будет убедиться, что значения, возвращаемые одним из этих методов, поддерживаются Context Bridge API, поскольку эти методы используют одинаковую семантику значения.
nativeWindowOpen defaults to truePrior to Electron 14, window.open was by default shimmed to use BrowserWindowProxy. This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. nativeWindowOpen is no longer experimental, and is now the default.
See the documentation for window.open in Electron for more details.
\nPrior to Electron 14, windows opened with window.open would inherit BrowserWindow constructor options such as transparent and resizable from their parent window. Beginning with Electron 14, this behavior is removed, and windows will not inherit any BrowserWindow constructor options from their parents.
Instead, explicitly set options for the new window with setWindowOpenHandler:
webContents.setWindowOpenHandler((details) => {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n // ...\n }\n }\n})\nadditionalFeaturesThe deprecated additionalFeatures property in the new-window and did-create-window events of WebContents has been removed. Since new-window uses positional arguments, the argument is still present, but will always be the empty array []. (Though note, the new-window event itself is deprecated, and is replaced by setWindowOpenHandler.) Bare keys in window features will now present as keys with the value true in the options object.
// Removed in Electron 14\n// Triggered by window.open('...', '', 'my-key')\nwebContents.on('did-create-window', (window, details) => {\n if (details.additionalFeatures.includes('my-key')) {\n // ...\n }\n})\n\n// Replace with\nwebContents.on('did-create-window', (window, details) => {\n if (details.options['my-key']) {\n // ...\n }\n})\nsession.setPermissionCheckHandler(handler)Первым параметром handler был ранее всегда webContents, теперь он иногда может быть null. Вы должны использовать requestingOrigin, embeddingOrigin и securityOrigin свойства для правильного ответа на проверку. Так как webContents может быть null больше, на него нельзя полагаться.
// Старый код\nsession.setPermissionCheckHandler((webContents, permission) => {\n if (webContents.getURL().startsWith('https://google. om/') && permission === 'notification') {\n return true\n }\n возвращает false\n})\n\n// Заменить на\nсессию. etPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin). ostname === 'google.com' && permission === 'notification') {\n return true\n }\n возвращает false\n})\nshell.moveItemToTrash()Удален устаревший синхронный shell.moveItemToTrash() API. Вместо этого используйте асинхронный shell.trashItem().
// Удалён в Electron 13\nshell.moveItemToTrash(path)\n// Замена на\nshell.trashItem(path).then(/* ... */)\nBrowserWindow API расширенийУдалено устаревшее API расширений:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()Использовать API сессии:
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Удален в Electron 13\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Заменить\nsession.defaultSession.loadExtension(path)\n// Удален в Electron 13\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Заменить\nsession.defaultSession.loadExtension(path)\n// Удален в Electron 13\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Заменить\nsession.defaultSession.getAllExtensions()\nsystemPreferencesСледующие systemPreferences были устаревшими:
systemPreferences.isDarkMode()systemPreferences.isvertedColorScheme()systemPreferences.isHighContrastColorScheme()Используйте следующие свойства nativeTheme вместо этого:
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Удалён в Electron 13\nsystemPreferences.isDarkMode()\n// Заменить на\nnativeTheme.shouldUseDarkColors\n\n// Удалён в Electron 13\nsystemPreferences. sInvertedColorScheme()\n// Заменить на\nnativeTheme.shouldUseInvertedColorScheme\n\n// Удалено в Electron 13\nsystemPreferences.isHighContrastColorScheme()\n// Заменить на\nnativeTheme.shouldUseHighContrastColors\nnew-window событиеСобытие new-window сетевого контента является устаревшим. Заменяется на webContents.setWindowOpenHandler().
// Устарел в Electron 13\nwebContents.on('new-window', (event) => {\n событие. reventDefault()\n})\n\n// Заменить на\nwebContents.setWindowOpenHandler((details) => {\n return { action: 'deny' }\n})\nChromium удалил поддержку Flash, и поэтому мы должны следовать этому примеру. Смотрите Chromium Flash Roadmap для получения более подробной информации.
\nworldSafeExecuteJavaScript defaults to trueВ Electron 12, worldSafeExecuteJavaScript будет включен по умолчанию. Чтобы восстановить предыдущее поведение, в WebPreferences должен быть определен worldSafeExecuteJavaScript: false. Обратите внимание, что установливать этого параметр в false небезопасно.
This option will be removed in Electron 14 so please migrate your code to support the default value.
\ncontextIsolation defaults to true
We recommend having contextIsolation enabled for the security of your application.
\nAnother implication is that require() cannot be used in the renderer process unless nodeIntegration is true and contextIsolation is false.
Подробнее см.: https://github.com/electron/electron/issues/23506
\ncrashReporter.getCrashesDirectory()The crashReporter.getCrashesDirectory method has been removed. Usage should be replaced by app.getPath('crashDumps').
// Removed in Electron 12\ncrashReporter.getCrashesDirectory()\n// Replace with\napp.getPath('crashDumps')\ncrashReporter methods in the renderer processThe following crashReporter methods are no longer available in the renderer process:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServerвылетать Reporter.setUploadToServercrashReporter.getCrashesDirectoryThey should be called only from the main process.
\nSee #23265 for more details.
\ncrashReporter.start({ compress: true })The default value of the compress option to crashReporter.start has changed from false to true. This means that crash dumps will be uploaded to the crash ingestion server with the Content-Encoding: gzip header, and the body will be compressed.
If your crash ingestion server does not support compressed payloads, you can turn off compression by specifying { compress: false } in the crash reporter options.
remote moduleThe remote module is deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.
// Deprecated in Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// Replace with:\nconst { BrowserWindow } = require('@electron/remote')\n\n// In the main process:\nrequire('@electron/remote/main').initialize()\nshell.moveItemToTrash()The synchronous shell.moveItemToTrash() has been replaced by the new, asynchronous shell.trashItem().
// Deprecated in Electron 12\nshell.moveItemToTrash(path)\n// Replace with\nshell.trashItem(path).then(/* ... */)\nBrowserView.{destroy, fromId, fromWebContents, getAllViews} and id property of BrowserViewThe experimental APIs BrowserView.{destroy, fromId, fromWebContents, getAllViews} have now been removed. Additionally, the id property of BrowserView has also been removed.
For more detailed information, see #23578.
\ncompanyName argument to crashReporter.start()The companyName argument to crashReporter.start(), which was previously required, is now optional, and further, is deprecated. To get the same behavior in a non-deprecated way, you can pass a companyName value in globalExtra.
// Deprecated in Electron 10\ncrashReporter.start({ companyName: 'Umbrella Corporation' })\n// Replace with\ncrashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })\ncrashReporter.getCrashesDirectory()The crashReporter.getCrashesDirectory method has been deprecated. Usage should be replaced by app.getPath('crashDumps').
// Deprecated in Electron 10\ncrashReporter.getCrashesDirectory()\n// Replace with\napp.getPath('crashDumps')\ncrashReporter methods in the renderer processCalling the following crashReporter methods from the renderer process is deprecated:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServerвылетать Reporter.setUploadToServercrashReporter.getCrashesDirectoryThe only non-deprecated methods remaining in the crashReporter module in the renderer are addExtraParameter, removeExtraParameter and getParameters.
All above methods remain non-deprecated when called from the main process.
\nSee #23265 for more details.
\ncrashReporter.start({ compress: false })Setting { compress: false } in crashReporter.start is deprecated. Nearly all crash ingestion servers support gzip compression. This option will be removed in a future version of Electron.
enableRemoteModule изменено на falseIn Electron 9, using the remote module without explicitly enabling it via the enableRemoteModule WebPreferences option began emitting a warning. In Electron 10, the remote module is now disabled by default. To use the remote module, enableRemoteModule: true must be specified in WebPreferences:
const w = new BrowserWindow({\n webPreferences: {\n enableRemoteModule: true\n }\n})\nWe recommend moving away from the remote module.
\nprotocol.unregisterProtocolprotocol.uninterceptProtocolAPI теперь синхронизируются, и необязательный обратный вызов больше не требуется.
\n// Deprecated\nprotocol.unregisterProtocol(scheme, () => { /* ... */ })\n// Replace with\nprotocol.unregisterProtocol(scheme)\nprotocol.registerFileProtocolprotocol.registerBufferProtocolprotocol.registerStringProtocolprotocol.registerHttpProtocolprotocol.registerStreamProtocolprotocol.interceptFileProtocolprotocol.interceptStringProtocolprotocol.interceptBufferProtocolprotocol.interceptHttpProtocolprotocol.interceptStreamProtocolAPI теперь синхронизируются, и необязательный обратный вызов больше не требуется.
\n// Deprecated\nprotocol.registerFileProtocol(scheme, handler, () => { /* ... */ })\n// Replace with\nprotocol.registerFileProtocol(scheme, handler)\nЗарегистрированный или перехваченный протокол не влияет на текущую страницу до тех пор, пока не произойдет навигация.
\nprotocol.isProtocolHandledЭтот API является устаревшим, пользователи должны использовать protocol.isProtocolRegistered и protocol.isProtocolIntercepted.
// Deprecated\nprotocol.isProtocolHandled(scheme).then(() => { /* ... */ })\n// Replace with\nconst isRegistered = protocol.isProtocolRegistered(scheme)\nconst isIntercepted = protocol.isProtocolIntercepted(scheme)\nAs of Electron 9 we do not allow loading of non-context-aware native modules in the renderer process. This is to improve security, performance and maintainability of Electron as a project.
\nIf this impacts you, you can temporarily set app.allowRendererProcessReuse to false to revert to the old behavior. This flag will only be an option until Electron 11 so you should plan to update your native modules to be context aware.
Для подробностей см. #18397.
\nBrowserWindow extension APIsThe following extension APIs have been deprecated:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()Использовать API сессии:
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Deprecated in Electron 9\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Replace with\nsession.defaultSession.loadExtension(path)\n// Deprecated in Electron 9\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// Replace with\nsession.defaultSession.removeExtension(extension_id)\n// Deprecated in Electron 9\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Replace with\nsession.defaultSession.getAllExtensions()\n<webview>.getWebContents()Удален этот API, устаревший в Electron 8.0.
\n// Удален в Electron 9.0\nwebview.getWebContents()\n// Замена на\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium has removed support for changing the layout zoom level limits, and it is beyond Electron's capacity to maintain it. The function was deprecated in Electron 8.x, and has been removed in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.
\nIn Electron 8.0, IPC was changed to use the Structured Clone Algorithm, bringing significant performance improvements. To help ease the transition, the old IPC serialization algorithm was kept and used for some objects that aren't serializable with Structured Clone. In particular, DOM objects (e.g. Element, Location and DOMMatrix), Node.js objects backed by C++ classes (e.g. process.env, some members of Stream), and Electron objects backed by C++ classes (e.g. WebContents, BrowserWindow and WebFrame) are not serializable with Structured Clone. Whenever the old algorithm was invoked, a deprecation warning was printed.
In Electron 9.0, the old serialization algorithm has been removed, and sending such non-serializable objects will now throw an \"object could not be cloned\" error.
\nshell.openItem is now shell.openPathThe shell.openItem API has been replaced with an asynchronous shell.openPath API. You can see the original API proposal and reasoning here.
The algorithm used to serialize objects sent over IPC (through ipcRenderer.send, ipcRenderer.sendSync, WebContents.send and related methods) has been switched from a custom algorithm to V8's built-in Structured Clone Algorithm, the same algorithm used to serialize messages for postMessage. This brings about a 2x performance improvement for large messages, but also brings some breaking changes in behavior.
undefined.// Previously:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => results in { value: 3 } arriving in the main process\n\n// From Electron 8:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => throws Error(\"() => {} could not be cloned.\")\nNaN, Infinity and -Infinity will now be correctly serialized, instead of being converted to null.null.Set, Map, Error and RegExp values will be correctly serialized, instead of being converted to {}.BigInt values will be correctly serialized, instead of being converted to null.nulls.Date objects will be transferred as Date objects, instead of being converted to their ISO string representation.Uint8Array, Uint16Array, Uint32Array and so on) will be transferred as such, instead of being converted to Node.js Buffer.Buffer objects will be transferred as Uint8Arrays. You can convert a Uint8Array back to a Node.js Buffer by wrapping the underlying ArrayBuffer:Buffer.from(value.buffer, value.byteOffset, value.byteLength)\nSending any objects that aren't native JS types, such as DOM objects (e.g. Element, Location, DOMMatrix), Node.js objects (e.g. process.env, Stream), or Electron objects (e.g. WebContents, BrowserWindow, WebFrame) is deprecated. In Electron 8, these objects will be serialized as before with a DeprecationWarning message, but starting in Electron 9, sending these kinds of objects will throw a 'could not be cloned' error.
<webview>.getWebContents()This API is implemented using the remote module, which has both performance and security implications. Therefore its usage should be explicit.
// Deprecated\nwebview.getWebContents()\n// Replace with\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nHowever, it is recommended to avoid using the remote module altogether.
// main\nconst { ipcMain, webContents } = require('electron')\n\nconst getGuestForWebContents = (webContentsId, contents) => {\n const guest = webContents.fromId(webContentsId)\n if (!guest) {\n throw new Error(`Invalid webContentsId: ${webContentsId}`)\n }\n if (guest.hostWebContents !== contents) {\n throw new Error('Access denied to webContents')\n }\n return guest\n}\n\nipcMain.handle('openDevTools', (event, webContentsId) => {\n const guest = getGuestForWebContents(webContentsId, event.sender)\n guest.openDevTools()\n})\n\n// renderer\nconst { ipcRenderer } = require('electron')\n\nipcRenderer.invoke('openDevTools', webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium has removed support for changing the layout zoom level limits, and it is beyond Electron's capacity to maintain it. The function will emit a warning in Electron 8.x, and cease to exist in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.
\nsystemPreferencesThe following systemPreferences events have been deprecated:
inverted-color-scheme-changedhigh-contrast-color-scheme-changedUse the new updated event on the nativeTheme module instead.
// Deprecated\nsystemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })\nsystemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })\n\n// Replace with\nnativeTheme.on('updated', () => { /* ... */ })\nsystemPreferencesСледующие systemPreferences были устаревшими:
systemPreferences.isDarkMode()systemPreferences.isvertedColorScheme()systemPreferences.isHighContrastColorScheme()Используйте следующие свойства nativeTheme вместо этого:
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Deprecated\nsystemPreferences.isDarkMode()\n// Replace with\nnativeTheme.shouldUseDarkColors\n\n// Deprecated\nsystemPreferences.isInvertedColorScheme()\n// Replace with\nnativeTheme.shouldUseInvertedColorScheme\n\n// Deprecated\nsystemPreferences.isHighContrastColorScheme()\n// Replace with\nnativeTheme.shouldUseHighContrastColors\nЭто URL, указанный как disturl в файле .npmrc или как --dist-url флаг командной строки, при сборке нативных модулей Node. Оба будут поддерживаться в обозримом будущем, но рекомендуется переключиться.
Deprecated: https://atom.io/download/electron
\nReplace with: https://electronjs.org/headers
\nsession.clearAuthCache() no longer accepts optionssession.clearAuthCache API больше не принимает параметры для очистки, а вместо этого безоговорочно очищает весь кэш.
// Устарело\nsession.clearAuthCache({ type: 'password' })\n// Заменить на\nsession.clearAuthCache()\npowerMonitor.querySystemIdleState is now powerMonitor.getSystemIdleState// Removed in Electron 7.0\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime is now powerMonitor.getSystemIdleTime// Removed in Electron 7.0\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\nwebFrame.setIsolatedWorldInfo replaces separate methods// Удалено в Electron 7.0\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Заменить на\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nmarked property on getBlinkMemoryInfoЭто свойство было удалено в Chromium 77, и как таковое больше не доступно.
\nwebkitdirectory attribute for <input type=\"file\"/> now lists directory contentsThe webkitdirectory property on HTML file inputs allows them to select folders. Previous versions of Electron had an incorrect implementation where the event.target.files of the input returned a FileList that returned one File corresponding to the selected folder.
As of Electron 7, that FileList is now list of all files contained within the folder, similarly to Chrome, Firefox, and Edge (link to MDN docs).
As an illustration, take a folder with this structure:
\nfolder\n├── file1\n├── file2\n└── file3\nIn Electron <=6, this would return a FileList with a File object for:
path/to/folder\nIn Electron 7, this now returns a FileList with a File object for:
/path/to/folder/file3\n/path/to/folder/file2\n/path/to/folder/file1\nNote that webkitdirectory no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).
Electron 5 and Electron 6 introduced Promise-based versions of existing asynchronous APIs and deprecated their older, callback-based counterparts. In Electron 7, all deprecated callback-based APIs are now removed.
\nThese functions now only return Promises:
\napp.getFileIcon() #15742app.dock.show() #16904contentTracing.getCategories() #16583contentTracing.getTraceBufferUsage() #16600contentTracing.startRecording() #16584contentTracing.stopRecording() #16584contents.executeJavaScript() #17312cookies.flushStore() #16464cookies.get() #16464cookies.remove() #16464cookies.set() #16464debugger.sendCommand() #16861dialog.showCertificateTrustDialog() #17181inAppPurchase.getProducts() #17355inAppPurchase.purchaseProduct()#17355netLog.stopLogging() #16862session.clearAuthCache() #17259session.clearCache() #17185session.clearHostResolverCache() #17229session.clearStorageData() #17249session.getBlobData() #17303session.getCacheSize() #17185session.resolveProxy() #17222session.setProxy() #17222shell.openExternal() #16176webContents.loadFile() #15855webContents.loadURL() #15855webContents.hasServiceWorker() #16535webContents.printToPDF() #16795webContents.savePage() #16742webFrame.executeJavaScript() #17312webFrame.executeJavaScriptInIsolatedWorld() #17312webviewTag.executeJavaScript() #17312win.capturePage() #15743These functions now have two forms, synchronous and Promise-based asynchronous:
\ndialog.showMessageBox()/dialog.showMessageBoxSync() #17298dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054win.setMenu(null) is now win.removeMenu()// Устаревшее\nwin.setMenu(null)\n// Заменено на\nwin.removeMenu()\nelectron.screen in the renderer process should be accessed via remote// Устаревшее\nrequire('electron').screen\n// Заменено на\nrequire('electron').remote.screen\nrequire()ing node builtins in sandboxed renderers no longer implicitly loads the remote version// Устаревшее\nrequire('child_process')\n// Заменено на\nrequire('electron').remote.require('child_process')\n\n// Устаревшее\nrequire('fs')\n// Заменено на\nrequire('electron').remote.require('fs')\n\n// Устаревшее\nrequire('os')\n// Заменено на\nrequire('electron').remote.require('os')\n\n// Устаревшее\nrequire('path')\n// Заменено на\nrequire('electron').remote.require('path')\npowerMonitor.querySystemIdleState replaced with powerMonitor.getSystemIdleState// Deprecated\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime replaced with powerMonitor.getSystemIdleTime// Deprecated\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\napp.enableMixedSandbox() is no longer needed// Устарело\napp.enableMixedSandbox()\nРежим смешанной песочницы теперь включен по умолчанию.
\nTray.setHighlightModeПод macOS Catalina наша прежняя реализация Tray нарушена. Нативная замена Apple не поддерживает изменение поведения подсветки.
\n// Устарело\ntray.setHighlightMode(mode)\n// Метод будет удален в v7.0 без альтернатив.\nnodeIntegration and webviewTag default to false, contextIsolation defaults to trueСледующие значения по умолчанию для параметра webPreferences устарели в пользу новых значений по умолчанию, перечисленных ниже.
| Свойство | Устаревшее | Новое |
|---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration, если установлено, иначе true | false |
Например, Re-enabling the webviewTag
\nconst w = new BrowserWindow({\n webPreferences: {\n webviewTag: true\n }\n})\nnodeIntegration in child windows opened via nativeWindowOpenChild windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is true.
Renderer process APIs webFrame.registerURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. Новый API protocol.registerSchemesAsPrivileged был добавлен и должен использоваться для регистрации пользовательских схем с необходимыми привилегиями. Пользовательские схемы должны быть зарегистрированы до готовности приложения.
webFrame.setIsolatedWorld* replaced with webFrame.setIsolatedWorldInfo// Устарело\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Заменено на\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nwebFrame.setSpellCheckProvider now takes an asynchronous callbackПараметр spellCheck теперь асинхронный, а параметр autoCorrectWord был удален.
// Устаревшее\nwebFrame.setSpellCheckProvider('en-US', true, {\n spellCheck: (text) => {\n return !spellchecker. sMisspelled(text)\n }\n})\n// Заменить на\nwebFrame. etSpellCheckProvider('en-US', {\n spellCheck: (words, callback) => {\n callback(слова. ilter(text => spellchecker.isMisspelled(text)))\n }\n})\nwebContents.getZoomLevel and webContents.getZoomFactor are now synchronouswebContents.getZoomLevel and webContents.getZoomFactor no longer take callback parameters, instead directly returning their number values.
// Deprecated\nwebContents.getZoomLevel((level) => {\n console.log(level)\n})\n// Replace with\nconst level = webContents.getZoomLevel()\nconsole.log(level)\n// Deprecated\nwebContents.getZoomFactor((factor) => {\n console.log(factor)\n})\n// Replace with\nconst factor = webContents.getZoomFactor()\nconsole.log(factor)\nСледующий список включает в себя критические изменения API, сделанные в Electron 4.0.
\napp.makeSingleInstance// Deprecated\napp.makeSingleInstance((argv, cwd) => {\n /* ... */\n})\n// Replace with\napp.requestSingleInstanceLock()\napp.on('second-instance', (event, argv, cwd) => {\n /* ... */\n})\napp.releaseSingleInstance// Устарело\napp.releaseSingleInstance()\n// Заменено на\napp.releaseSingleInstanceLock()\napp.getGPUInfoapp.getGPUInfo('complete')\n// Теперь ведет себя так же с `basic` в macOS\napp.getGPUInfo('basic')\nwin_delay_load_hookПри создании нативных модулей для Windows переменная win_delay_load_hook в binding.gyp модуля должна быть true (это значение по умолчанию). Если этот хук отсутствует, то нативный модуль на Windows неудачно загрузится, с сообщением об ошибке, например Cannot find module. См. руководство по нативным модулям для получения дополнительной информации.
Данный список включает в себя критические изменения в API для Electron 3.0.
\napp// Устарело\napp.getAppMemoryInfo()\n// Заменить на\napp.getAppMetrics()\n\n// Устарело\nconst metrics = app.getAppMetrics()\nconst { memory } = metrics[0] // свойство устарело\nBrowserWindow// Deprecated\nconst optionsA = { webPreferences: { blinkFeatures: '' } }\nconst windowA = new BrowserWindow(optionsA)\n// Replace with\nconst optionsB = { webPreferences: { enableBlinkFeatures: '' } }\nconst windowB = new BrowserWindow(optionsB)\n\n// Deprecated\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play_pause') {\n // do something\n }\n})\n// Replace with\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play-pause') {\n // do something\n }\n})\nclipboard// Устарело\nclipboard.readRtf()\n// Заменить на\nclipboard.readRTF()\n\n// Устарело\nclipboard.writeRtf()\n// Заменить на\nclipboard.writeRTF()\n\n// Устарело\nclipboard.readHtml()\n// Заменить на\nclipboard.readHTML()\n\n// Устарело\nclipboard.writeHtml()\n// Заменить на\nclipboard.writeHTML()\ncrashReporter// Устарело\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n autoSubmit: true\n})\n// Заменить на\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n uploadToServer: true\n})\nnativeImage// Устарело\nnativeImage.createFromBuffer(buffer, 1.0)\n// Заменить на\nnativeImage.createFromBuffer(buffer, {\n scaleFactor: 1.0\n})\nprocess// Устарело\nconst info = process.getProcessMemoryInfo()\nscreen// Устарело\nscreen.getMenuBarHeight()\n// Заменить на\nscreen.getPrimaryDisplay().workArea\nsession// Устарело\nses.setCertificateVerifyProc((hostname, certificate, callback) => {\n callback(true)\n})\n// Заменено на\nses.setCertificateVerifyProc((request, callback) => {\n callback(0)\n})\nTray// Устарело\ntray.setHighlightMode(true)\n// Заменить на\ntray.setHighlightMode('on')\n\n// Устарело\ntray.setHighlightMode(false)\n// Заменить на\ntray.setHighlightMode('off')\nwebContents// Устарело\nwebContents.openDevTools({ detach: true })\n// Заменить на\nwebContents.openDevTools({ mode: 'detach' })\n\n// Удалено\nwebContents.setSize(options)\n// Нет замены для этого API\nwebFrame// Устарело\nwebFrame.registerURLSchemeAsSecure('app')\n// Заменить на\nprotocol.registerStandardSchemes(['app'], { secure: true })\n\n// Устарело\nwebFrame.registerURLSchemeAsPrivileged('app', { secure: true })\n// Заменить на\nprotocol.registerStandardSchemes(['app'], { secure: true })\n<webview>// Удалено\nwebview.setAttribute('disableguestresize', '')\n// Нет замены для этого API\n\n// Удалено\nwebview.setAttribute('guestinstance', instanceId)\n// Нет замены для этого API\n\n// Слушатели клавиатуры больше не работают в webview теге\nwebview.onkeydown = () => { /* обработчик */ }\nwebview.onkeyup = () => { /* обработчик */ }\nЭто URL, указанный как disturl в файле .npmrc или как --dist-url флаг командной строки, при сборке нативных модулей Node.
Устарело: https://atom.io/download/atom-shell
\nЗаменено на: https://atom.io/download/electron
\nСледующий список включает в себя критические изменения API, сделанные в Electron 2.0.
\nBrowserWindow// Deprecated\nconst optionsA = { titleBarStyle: 'hidden-inset' }\nconst windowA = new BrowserWindow(optionsA)\n// Replace with\nconst optionsB = { titleBarStyle: 'hiddenInset' }\nconst windowB = new BrowserWindow(optionsB)\nmenu// Удалено\nmenu.popup(browserWindow, 100, 200, 2)\n// Заменить на\nmenu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })\nnativeImage// Удалено\nnativeImage.toPng()\n// Заменить на\nnativeImage.toPNG()\n\n// Удалено\nnativeImage.toJpeg()\n// Заменить на\nnativeImage.toJPEG()\nprocessprocess.versions.electron и process.version.chrome будут доступны только для чтения, для согласованности с другими свойствами process.versions, установленными в Node.webContents// Удалено\nwebContents.setZoomLevelLimits(1, 2)\n// Заменить на\nwebContents.setVisualZoomLevelLimits(1, 2)\nwebFrame// Удалено\nwebFrame.setZoomLevelLimits(1, 2)\n// Заменить на\nwebFrame.setVisualZoomLevelLimits(1, 2)\n<webview>// Удалено\nwebview.setZoomLevelLimits(1, 2)\n// Заменить на\nwebview.setVisualZoomLevelLimits(1, 2)\nКаждый выпуск Electron включает в себя две идентичные сборки ARM с немного разными имена файлов, такие как electron-v1.7.3-linux-arm.zip и electron-v1.7.3-linux-armv7l.zip. Ресурсы с префиксом v7l были добавлены, чтобы уточнить для пользователей, какую версию ARM они поддерживают, и чтобы исключить их в будущих ресурсах armv6l и arm64, которые могут быть произведены.
The file without the prefix is still being published to avoid breaking any setups that may be consuming it. Начиная с версии 2.0, файл без префикса более не будет публиковаться.
\nДля подробностей см. 6986 и 7189.
", "title": "Критические изменения", "description": "" }, "/docs/api/browser-view": { "locale": "ru-RU", "slug": "browser-view", "href": "/docs/api/browser-view", "crowdinFileId": "256283", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-view.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "BrowserView может использоваться для встраивания дополнительного веб-контента в BrowserWindow. Это как дочернее окно, за исключением того, что оно позиционируется относительно его владельца окна. Он предназначен для того, чтобы быть альтернативой тега webview.
\n\nСоздание и управление видами.
\n
Процесс: Основной
\n// В основном процессе.\nconst { BrowserView, BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nconst view = new BrowserView()\nwin.setBrowserView(view)\nview.setBounds({ x: 0, y: 0, width: 300, height: 300 })\nview.webContents.loadURL('https://electronjs.org')\nnew BrowserView([options]) Экспериментальноoptions Object (опционально)webPreferences Объект (опционально) - Смотрите BrowserWindow.Объекты, созданные с помощью new BrowserView, имеют следующие свойства:
view.webContents ЭкспериментальноОбъект WebContents, принадлежащий этому виду.
Объекты, созданные с помощью new BrowserView, имеют следующие свойства:
view.setAutoResize(options) Экспериментальноoptions Objectwidth Boolean (опционально) - если true, то ширина будет увеличиваться и уменьшаться вместе с окном. По умолчанию false.height Boolean (опционально) - если true, то высота будет увеличиваться и уменьшаться вместе с окном. По умолчанию false.horizontal Boolean (опционально) - если true, то положение по X и ширина будут увеличиваться и уменьшаться вместе с окном. По умолчанию false.vertical Boolean (опционально) - если true, то положение по Y и высота будут увеличиваться и уменьшаться вместе с окном. По умолчанию false.view.setBounds(bounds) Экспериментальноbounds RectangleИзменяет и перемещает вид в предоставленные границы, относительно окна.
\nview.getBounds() ExperimentalВозвращает Rectangle
bounds этого экземпляра BrowserView как Object.
view.setBackgroundColor(color) Экспериментальноcolor String - цвет вида #aarrggbb или #argb. Альфа-канал является опциональным.\n\nСоздавайте окна браузера и управляйте ими.
\n
Процесс: Основной
\n// В основном процессе.\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\n// Загрузка удаленного URL\nwin.loadURL('https://github.com')\n\n// Или загрузка локального HTML файла\nwin.loadFile('index.html')\nДля создания окна без хрома или прозрачного окна произвольной формы, можно использовать API окна без рамки.
\nWhen loading a page in the window directly, users may see the page load incrementally, which is not a good experience for a native app. To make the window display without a visual flash, there are two solutions for different situations.
\nready-to-show eventПри загрузке страницы, после отрисовки страницы будет происходить событие ready-to-show, которое будет происходить первый раз, если окно до этого еще не было показано. Окно, показанное после этого события, не будет иметь визуальной ступенчатой подгрузки:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ show: false })\nwin.once('ready-to-show', () => {\n win.show()\n})\nОбычно это событие происходит после события did-finish-load. Однако, страницы, включающие в себя удаленные ресурсы, могут продолжать подгружаться после происхождения события did-finish-load.
Пожалуйста, обратите внимание, что использование этого события означает, что рендерер будет считаться \"видимым\" и отрисуется, даже если show является false. Это событие никогда не сработает, если вы используете paintWhenInitiallyHidden: false
backgroundColor propertyДля больших приложений событие ready-to-show может вызываться слишком поздно, что может замедлить приложение. В этом случае рекомендуется показать окно немедленно, и использовать backgroundColor, задающий цвет фона Вашего приложения:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ backgroundColor: '#2e2c29' })\nwin.loadURL('https://github.com')\nОбратите внимание, что даже для приложений, использующих ready-to-show события, по-прежнему рекомендуется установить backgroundColor, чтобы сделать приложение более нативным.
С помощью параметра parent, Вы можете создавать дочерние окна:
const { BrowserWindow } = require('electron')\n\nconst top = new BrowserWindow()\nconst child = new BrowserWindow({ parent: top })\nchild.show()\ntop.show()\nОкно child будет всегда показано поверх окна top.
Модальное окно - дочернее окно, которое делает недоступным родительское окно. Чтобы создать модальное окно, Вы должны установить два параметра parent и modal:
const { BrowserWindow } = require('electron')\n\nconst child = new BrowserWindow({ parent: top, modal: true, show: false })\nchild.loadURL('https://github.com')\nchild.once('ready-to-show', () => {\n child.show()\n})\nAPI видимости страниц работает следующим образом:
\nhidden. На других платформах состояние видимости будет hidden, только когда окно уменьшено или явно скрыто при помощи win.hide().BrowserWindow создано с show: false, первоначальное состояние видимости будет visible, несмотря на фактически скрытое окно.backgroundThrottling отключено, состояние видимости останется visible, даже если окно уменьшено, закрыто или скрыто.Рекомендуется приостановить дорогостоящие операции, когда состояние видимости hidden, для того чтобы свести к минимуму потребление энергии.
dialog.\n\nСоздавайте окна браузера и управляйте ими.
\n
Процесс: Основной
\nBrowserWindow этоEventEmitter.
Так создается новый экземпляр BrowserWindow с нативными свойствами, установленными в options.
new BrowserWindow([options])options Object (опционально)width Integer (опционально) - ширина окна в пикселях. По умолчанию 800.height Integer (опционально) - высота окна в пикселях. По умолчанию 600.x Integer (опционально) - (обязателен, если используется y) отступ окна слева от экрана. Значение по умолчанию центрирует окно.y Integer (опционально) - (обязателен, если используется x) отступ окна сверху от экрана. Значение по умолчанию центрирует окно.useContentSize Boolean (опционально) - width и height могут использоваться как размеры веб-страницы, это значит, что актуальный размер окна будет включать размер фрейма и будет немного крупнее. По умолчанию - false.center Boolean (опционально) - показывает окно в центре экрана.minWidth Integer (опционально) - минимальная ширина окна. По умолчанию 0.minHeight Integer (опционально) - минимальная высота окна. По умолчанию 0.maxWidth Integer (опционально) - максимальная ширина окна. По умолчанию нет ограничения.maxHeight Integer (опционально) - максимальная высота окна. По умолчанию нет ограничения.resizable Boolean (опционально) - будет ли окно изменять размеры. По умолчанию - true.movable Boolean (optional) - можно ли будет перемещать окно. Не реализовано в Linux. По умолчанию - true.minimizable Boolean (optional) - Whether window is minimizable. Не реализовано в Linux. По умолчанию - true.maximizable Boolean (optional) - Whether window is maximizable. Не реализовано в Linux. По умолчанию - true.closable Boolean (optional) - Whether window is closable. Не реализовано в Linux. По умолчанию - true.focusable Boolean (опционально) - может ли быть окно в фокусе. По умолчанию - true. На Windows настройка focusable: false также подразумевает настройку skipTaskbar: true. На Linux настройка focusable: false прекращает взаимодействие окна с оконным менеджером, на Windows же всегда остается поверх всех рабочих областей.alwaysOnTop Boolean (опционально) - будет ли окно всегда оставаться поверх других окон. По умолчанию - false.fullscreen Boolean (опционально) - будет ли окно показываться во весь экран. Когда явно установлено false, на macOS кнопка полноэкранного режима будет скрыта или отключена. По умолчанию - false.fullscreenable Boolean (опционально) - может ли окно быть в полноэкранном режиме. На macOS также кнопка увеличить/зумировать должна переключить в полноэкранный режим или увеличить окно. По умолчанию - true.simpleFullscreen Boolean (optional) - Use pre-Lion fullscreen on macOS. По умолчанию - false.skipTaskbar Boolean (optional) - Whether to show the window in taskbar. По умолчанию - false.kiosk Boolean (optional) - Whether the window is in kiosk mode. По умолчанию - false.title String (опционально) - заголовок окна по умолчанию. По умолчанию \"Electron\". Если HTML-тег <title> определен в HTML-файле, загруженном с помощью loadURL(), то это свойство будет игнорироваться.icon (NativeImage | String) (опционально) - иконка окна. На Windows рекомендуется использовать иконки ICO, чтобы получить лучший визуальный эффект, Вы также можете оставить неопределенным, чтобы был использован значок исполняемого файла.show Boolean (необязательно) - Будет ли показано окно, когда будет создано. По умолчанию - true.paintWhenInitiallyHidden Boolean (опционально) - Должен ли рендерер быть активным, когда show равен false и он только что создан. Для document.visibilityState для корректной работы при первой загрузке с show: false необходимо установить значение false. Установка этого в false приведёт к тому, что события ready-to-show не будут запускаться. По умолчанию - true.frame Boolean (optional) - Specify false to create a Frameless Window. По умолчанию - true.parent BrowserWindow (optional) - Specify parent window. По умолчанию - null.modal Boolean (optional) - Whether this is a modal window. This only works when the window is a child window. По умолчанию - false.acceptFirstMouse Boolean (optional) - Whether clicking an inactive window will also click through to the web contents. Default is false on macOS. This option is not configurable on other platforms.disableAutoHideCursor Boolean (optional) - Whether to hide cursor when typing. По умолчанию - false.autoHideMenuBar Boolean (optional) - Auto hide the menu bar unless the Alt key is pressed. По умолчанию - false.enableLargerThanScreen Boolean (опционально) - позволяет окну изменять размер больше, чем экран. Относится только к macOS, так как другие ОС по умолчанию разрешают окна больше экрана. По умолчанию - false.backgroundColor String (опционально) - фоновый цвет окна в HEX-формате, например #66CD00, #FFF или #80FFFFFF (альфа в формате #AARRGGBB поддерживается, если transparent установлено true). По умолчанию - #FFF (белый).hasShadow Boolean (optional) - Whether window should have a shadow. По умолчанию - true.opacity Number (optional) - Set the initial opacity of the window, between 0.0 (fully transparent) and 1.0 (fully opaque). This is only implemented on Windows and macOS.darkTheme Boolean (optional) - Forces using dark theme for the window, only works on some GTK+3 desktop environments. По умолчанию - false.transparent Boolean (опционально) - делает окно прозрачным. По умолчанию - false. В Windows не работает до тех пор, пока окно не будет без фрейма.type String (optional) - The type of window, default is normal window. See more about this below.visualEffectState String (optional) - Specify how the material appearance should reflect window activity state on macOS. Must be used with the vibrancy property. Возможные значения:followWindow - The backdrop should automatically appear active when the window is active, and inactive when it is not. This is the default.active - The backdrop should always appear active.inactive - The backdrop should always appear inactive.titleBarStyle Строка (необязательно) macOS Windows - Стиль строки заголовка окна. По умолчанию - default. Возможные значения:по умолчанию - результаты в стандартной строке заголовка для macOS или Windows, соответственно.скрытые - результаты в скрытой строке заголовка и окно полного размера. На macOS в левом верхнем углу окна все еще есть стандартное управление окном (\"светофоры\"). На Windows, когда в сочетании с заголовком titleBarOverlay: true он активирует Overlay Window Controls Overlay (см. titleBarOverlay для получения дополнительной информации), иначе панель управления окном не будет показана.hiddenInset - Только в macOS приводит к скрытой строке заголовка с альтернативным видом где кнопки светофора немного дальше от края окна.customButtonsOnHover - Только в macOS приводит к скрытой строке заголовка и полному размеру окно содержимого, кнопки светофора будут отображаться при наведении курсора в верхнем левом углу окна. Примечание: Эта опция в настоящее время экспериментальная.trafficLightPosition Point (optional) - Set a custom position for the traffic light buttons in frameless windows.roundedCorners Boolean (optional) - Whether frameless window should have rounded corners on macOS. По умолчанию - true.fullscreenWindowTitle Boolean (optional) Deprecated - Shows the title in the title bar in full screen mode on macOS for hiddenInset titleBarStyle. По умолчанию - false.thickFrame Boolenan (необязательно) - Использовать стиль WS_THICKFRAME на окнах с отсутствием рамок на Windows, добавляющий стандартные рамки окна. Установив значение false, тень окна и анимация окна будут удалены. По умолчанию - true.vibrancy String (опционально) - добавить тип эффекта вибрации к окну, только на macOS. Может быть appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window или under-page. Please note that appearance-based, light, dark, medium-light, and ultra-dark are deprecated and have been removed in macOS Catalina (10.15).zoomToPageWidth Boolean (optional) - Controls the behavior on macOS when option-clicking the green stoplight button on the toolbar or by clicking the Window > Zoom menu item. Если true, окно будет увеличиваться до предпочтительной ширины веб-страницы при увеличении, false приведет к увеличению масштаба до ширины экрана. Это также повлияет на поведение при вызове maximize() напрямую. По умолчанию - false.tabbingIdentifier String (опционально) - название группы вкладок, позволяет открывать окно как нативную вкладку в macOS 10.12+. Окна с одинаковым идентификатором вкладки будут сгруппированы вместе. Это также добавляет новую нативную кнопку вкладки в панель вкладок вашего окна и позволяет Вашему приложению и окну получать событие new-window-for-tab.webPreferences Object (optional) - Settings of web page's features.devTools Boolean (опционально) - включает инструменты разработчика. Если значение false, нельзя будет использовать BrowserWindow.webContents.openDevTools(), чтобы открыть инструменты разработчика. По умолчанию - true.nodeIntegration Boolean (optional) - Whether node integration is enabled. По умолчанию - false.nodeIntegrationInWorker Boolean (опционально) - включает интеграцию NodeJS в веб-воркерах. По умолчанию - false. Больше об этом можно найти в многопоточности.nodeIntegrationInSubFrames Boolean (опционально) - экспериментальная опция для включения поддержки NodeJS в подфреймах, таких как iframes и дочерних окнах. Все Ваши предварительные загрузки будут загружены для каждого iframe, Вы можете использовать process.isMainFrame, чтобы определить в главном фрейме Вы или нет.preload String (опционально) - Определяет скрипт, который будет загружен до других скриптов загружаемых в странице. Этот скрипт будет всегда иметь доступ к узлам API в не зависимости включено или выключено объединение узлов. Значение должно быть абсолютным файловым путем к скрипту. Когда интеграция узлов отключена, сценарий предварительной загрузки может повторно вводить глобальные символы узла обратно в глобальную область. Посмотреть пример здесь.sandbox Boolean (опционально) - если установлено в true, то в окне будет запущена песочница рендеринга, что делает ее совместимой с Chromium на уровне операционной системы и отключает Node.js. Это не тоже самое, что параметр nodeIntegration, доступные АПИ для предзагрузки более ограничены. Узнать больше об этой опции можно здесь.session Сессия (опционально) - отсылает сессию используемую на странице. Вместо передачи объекта Session напрямую, вы можете также выбрать использование partition опции вместо которой принимает строку раздела. Когда оба session и partition определены, session будет приоритентней. По умолчанию используется session по умолчанию.partition String (опционально) - Устанавливает сеанс, используемый страницей в соответствии со строкой раздела сессии. Если partition начинается с persist:, страница будет использовать постоянную сессию доступная всем страницам в приложении с некоторыми partition. Если нет persist: префикса, страница будет использовать сеанс в памяти. При присваивании одинаковой partition, разные страницы могут иметь одинаковую сессию. По умолчанию используется session по умолчанию.zoomFactor Number (optional) - The default zoom factor of the page, 3.0 represents 300%. По умолчанию - 1.0.javascript Boolean (optional) - Enables JavaScript support. По умолчанию - true.webSecurity Boolean (опционально) - Когда false, отключается политика same-origin (обычно используется при тестировании вебсайтов людьми), и устанавливается allowRunningInsecureContent в true, если параметр не был установлен пользователем. По умолчанию - true.allowRunningInsecureContent Boolean (optional) - Allow an https page to run JavaScript, CSS or plugins from http URLs. По умолчанию - false.images Boolean (optional) - Enables image support. По умолчанию - true.imageAnimationPolicy String (optional) - Specifies how to run image animations (E.g. GIFs). Can be animate, animateOnce or noAnimation. По умолчанию - animate.textAreasAreResizable Boolean (optional) - Make TextArea elements resizable. Default is true.webgl Boolean (optional) - Enables WebGL support. По умолчанию - true.plugins Boolean (optional) - Whether plugins should be enabled. По умолчанию - false.experimentalFeatures Boolean (optional) - Enables Chromium's experimental features. По умолчанию - false.scrollBounce Boolean (optional) - Enables scroll bounce (rubber banding) effect on macOS. По умолчанию - false.enableBlinkFeatures String (опционально) - список строк функций, разделенных запятой, которые нужно включить, например CSSVariables,KeyboardEventKey. Полный список поддерживаемых возможностей можно найти в файле RuntimeEnabledFeatures.json5.disableBlinkFeatures String (опционально) - Список функциональных возможностей для выключения, разделяются ',', например CSSVariables,KeyboardEventKey. Полный список поддерживаемых возможностей можно найти в файле RuntimeEnabledFeatures.json5.defaultFontFamily Object (optional) - Sets the default font for the font-family.standard String (опционально) - По умолчанию Times New Roman.serif String (опционально) - По умолчанию Times New Roman.sansSerif String (опционально) - По умолчанию Arial.monospace String (опционально) - По умолчанию Courier New.cursive String (optional) - Defaults to Script.fantasy String (optional) - Defaults to Impact.defaultFontSize Integer (optional) - Defaults to 16.defaultMonospaceFontSize Integer (optional) - Defaults to 13.minimumFontSize Integer (optional) - Defaults to 0.defaultEncoding String (optional) - Defaults to ISO-8859-1.backgroundThrottling Boolean (optional) - Whether to throttle animations and timers when the page becomes background. This also affects the Page Visibility API. Defaults to true.offscreen Boolean (optional) - Whether to enable offscreen rendering for the browser window. Defaults to false. See the offscreen rendering tutorial for more details.contextIsolation Boolean (optional) - Whether to run Electron APIs and the specified preload script in a separate JavaScript context. Defaults to true. The context that the preload script runs in will only have access to its own dedicated document and window globals, as well as its own set of JavaScript builtins (Array, Object, JSON, etc.), which are all invisible to the loaded content. The Electron API will only be available in the preload script and not the loaded page. This option should be used when loading potentially untrusted remote content to ensure the loaded content cannot tamper with the preload script and any Electron APIs being used. This option uses the same technique used by Chrome Content Scripts. You can access this context in the dev tools by selecting the 'Electron Isolated Context' entry in the combo box at the top of the Console tab.nativeWindowOpen Boolean (optional) - Whether to use native window.open(). Defaults to true. Дочерние окна всегда будут отключены для интеграции узлов, если nodeIntegrationInSubFrames будет true.webviewTag Boolean (опционально) - включает <webview>-тег. Defaults to false. Примечание: Cкрипт предварительной загрузки, настроенный для <webview>, будет иметь интеграцию NodeJS, когда будет запущен, так что Вы должны убедиться, что удаленный/непроверенный контент не может создавать тег <webview> с возможно вредоносным скриптом предварительной загрузки. Вы можете использовать событие will-attach-webview на webContents, чтобы снять скрипт предварительной загрузки и проверить или изменить начальные настройки <webview>.additionalArguments String - A list of strings that will be appended to process.argv in the renderer process of this app. Useful for passing small bits of data down to renderer process preload scripts.safeDialogs Boolean (optional) - Whether to enable browser style consecutive dialog protection. По умолчанию - false.safeDialogsMessage String (optional) - The message to display when consecutive dialog protection is triggered. If not defined the default message would be used, note that currently the default message is in English and not localized.disableDialogs Boolean (optional) - Whether to disable dialogs completely. Overrides safeDialogs. По умолчанию - false.navigateOnDragDrop Boolean (optional) - Whether dragging and dropping a file or link onto the page causes a navigation. По умолчанию - false.autoplayPolicy String (опционально) - политика автовоспроизведения для применения к содержимому в окне, может быть no-user-gesture-required, user-gesture-required или document-user-activation-required. По умолчанию no-user-gesture-required.disableHtmlFullscreenWindowResize Boolean (optional) - Whether to prevent the window from resizing when entering HTML Fullscreen. Default is false.accessibleTitle String (optional) - An alternative title string provided only to accessibility tools such as screen readers. This string is not directly visible to users.spellcheck Boolean (optional) - Whether to enable the builtin spellchecker. По умолчанию - true.enableWebSQL Boolean (optional) - Whether to enable the WebSQL api. По умолчанию - true.v8CacheOptions String (optional) - Enforces the v8 code caching policy used by blink. Accepted values arenone - Disables code cachingcode - Heuristic based code cachingbypassHeatCheck - Bypass code caching heuristics but with lazy compilationbypassHeatCheckAndEagerCompile - Same as above except compilation is eager. Default policy is code.enablePreferredSizeMode Boolean (optional) - Whether to enable preferred size mode. The preferred size is the minimum size needed to contain the layout of the document—without requiring scrolling. Enabling this will cause the preferred-size-changed event to be emitted on the WebContents when the preferred size changes. По умолчанию - false.titleBarOverlay Object | Boolean (optional) - When using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS or using a titleBarStyle so that the standard window controls (\"traffic lights\" on macOS) are visible, this property enables the Window Controls Overlay JavaScript APIs and CSS Environment Variables. Specifying true will result in an overlay with default system colors. По умолчанию - false.color String (optional) Windows - The CSS color of the Window Controls Overlay when enabled. Default is the system color.symbolColor String (optional) Windows - The CSS color of the symbols on the Window Controls Overlay when enabled. Default is the system color.Когда установлен минимальный или максимальный размер окна, при помощи minWidth/maxWidth/minHeight/maxHeight, это ограничивает только пользователей. Это не позволит Вам установить размер, который не будет следовать ограничениям размера, в setBounds/setSize или в конструкторе BrowserWindow.
The possible values and behaviors of the type option are platform dependent. Возможные значения:
desktop, dock, toolbar, splash, notification.desktop, textured.textured добавляет вид металлического градиента (NSTexturedBackgroundWindowMask).desktop размещает окно на уровень фонового окна рабочего стола (kCGDesktopWindowLevel - 1). Обратите внимание, что окно рабочего стола не будет получить события фокуса, клавиатуры или мыши, но Вы можете использовать globalShortcut, чтобы получать ввод.toolbar.Объекты созданные с помощью new BrowserWindow имеют следующие события:
Примечание: Некоторые методы доступны только в определенных операционных системах и помечены как таковые.
\nВозвращает:
\neventtitle StringexplicitSet BooleanВызывается, когда документ меняет свой заголовок, вызов event.preventDefault() предотвратит изменение заголовка родного окна. explicitSet является false, когда заголовок синтезирован из url файла.
Возвращает:
\neventПроисходит при закрытии окна. Оно происходит перед событиями beforeunload и unload в DOM. Вызов event.preventDefault() предотвратит закрытие.
Скорее всего, Вы захотите использовать обработчик beforeunload, чтобы решить, когда окно должно быть закрыто, который также будет вызываться, когда окно перезагружается. В Electron возврат любого значения, отличного от undefined, предотвратит закрытие. Например:
window.onbeforeunload = (e) => {\n console.log('Я не хочу быть закрыт')\n\n // В отличие от браузеров, пользователю будет показано окно с сообщением.\n // Возврат любого значения незаметно отменит закрытие.\n // Рекомендуется использовать dialog API, чтобы дать пользователям\n // возможность подтвердить закрытие приложения.\n e.returnValue = false // идентично `return false`, но в использовании не рекомендуется\n}\nПримечание: Существует тонкая разница между поведением window.onbeforeunload = handler и window.addEventListener('beforeunload', handler). Рекомендуется всегда устанавливать event.returnValue явно, вместо того, чтобы просто возвращать значение, поскольку первое работает более последовательно в Electron.
происходит когда окно приложения закрыто. After you have received this event you should remove the reference to the window and avoid using it any more.
\nПроисходит, когда сеанс окна заканчивается из-за выключения, перезагрузки компьютера или отключения сеанса.
\nВызывается, когда страница \"не отвечает\".
\nПроисходит, когда страница, которая \"не отвечала\", снова реагирует.
\nВызывается, когда окно теряет фокус.
\nВызывается, когда на окне фокусируются.
\nПроисходит, когда отображается окно.
\nПроисходит, когда окно спрятано.
\nПроисходит, когда веб-страница была отрисована (пока не отображена) и окно может быть отображено без визуального мерцания.
\nПожалуйста, обратите внимание, что использование этого события означает, что рендерер будет считаться \"видимым\" и отрисуется, даже если show является false. Это событие никогда не сработает, если вы используете paintWhenInitiallyHidden: false
Происходит, когда окно увеличивается до предела.
\nПроисходит, когда окно выходит из увеличенного состояния.
\nПроисходит, когда окно было свернуто.
\nПроисходит, когда окно восстанавливается из свернутого состояния.
\nВозвращает:
\neventnewBounds Rectangle - Размер окна, на который будет изменено.detailsedge (String) - The edge of the window being dragged for resizing. Can be bottom, left, right, top-left, top-right, bottom-left or bottom-right.Emitted before the window is resized. Calling event.preventDefault() will prevent the window from being resized.
Note that this is only emitted when the window is being resized manually. Resizing the window with setBounds/setSize will not emit this event.
The possible values and behaviors of the edge option are platform dependent. Возможные значения:
bottom, top, left, right, top-left, top-right, bottom-left, bottom-right.bottom and right.bottom is used to denote vertical resizing.right is used to denote horizontal resizing.Происходит после того, как изменился размер окна.
\nEmitted once when the window has finished being resized.
\nThis 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.
Возвращает:
\neventnewBounds Rectangle - Расположение, куда окно будет перемещено.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 resized manually. Resizing the window with setBounds/setSize will not emit this event.
Происходит, когда окно перемещено на новое место.
\nПроисходит единожды, когда окно перемещается в новое положение.
\nПримечание: На macOS это событие является псевдонимом move.
Происходит, когда окно переходит в полноэкранный режим.
\nПроисходит, когда окно выходит из полноэкранного режима.
\nПроисходит, когда окно входит в полноэкранный режим с помощью HTML API.
\nПроисходит, когда окно выходит из полноэкранного режима с помощью HTML API.
\nВозвращает:
\neventisAlwaysOnTop BooleanПроисходит, когда окно переключает режим отображения поверх всех окон.
\nВозвращает:
\neventcommand StringПроисходит, когда вызывается команда приложения. Обычно это касается клавиатурных медиа-клавиш или команд браузера, а также кнопки \"Назад\", встроенной в некоторые мыши на Windows.
\nКоманды в нижнем регистре, подчеркивание заменено на дефисы, а префикс APPCOMMAND_ обрезан. например APPCOMMAND_BROWSER_BACKWARD происходит как browser-backward.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.on('app-command', (e, cmd) => {\n // Navigate the window back when the user hits their mouse back button\n if (cmd === 'browser-backward' && win.webContents.canGoBack()) {\n win.webContents.goBack()\n }\n})\nСледующие команды приложения явно поддерживаются на Linux:
\nbrowser-backwardbrowser-forwardПроисходит, когда начинается прокрутка колеса.
\nПроисходит, когда заканчивается прокрутка колеса.
\nПроисходит, когда прокрутка колеса достигает края элемента.
\nВозвращает:
\neventdirection StringEmitted on 3-finger swipe. Possible directions are up, right, down, left.
Метод, лежащий в основе этого события, создан для обработки событий смахивания на устаревших трекпадах в стиле macOS, где содержимое на экране нельзя переместить смахнув. Большинство трекпадов macOS по умолчанию не настроены под этот вид смахивания, поэтому для того чтобы правильно работал 'Переход между страницами смахиванием' перейдите в Системные настройки > Трекпад > Другие жесты и включите \"Смахивание двумя или тремя пальцами\".
Возвращает:
\neventrotation FloatГенерируется жестом вращения трекпада. Непрерывно генерируется до тех пор, пока жест поворота не будет завершен. Значение rotation при каждом выбросе - угол поворота в градусах, отсчитанный от последнего выброса. Последнее событие на жесте вращения всегда будет иметь значение 0. Значения вращения против часовой стрелки положительные, по часовой стрелке отрицательные.
Происходит, когда окно открывает лист.
\nПроисходит, когда окно закрыло лист.
\nПроисходит, когда нажимается нативная кнопка новой вкладки.
\nВозвращает:
\neventpoint Point - The screen coordinates the context menu was triggered atEmitted when the system context menu is triggered on the window, this is normally only triggered when the user right clicks on the non-client area of your window. This is the window titlebar or any area you have declared as -webkit-app-region: drag in a frameless window.
Calling event.preventDefault() will prevent the menu from being displayed.
Класс BrowserWindow имеет следующие статические методы:
BrowserWindow.getAllWindows()Возвращает BrowserWindow[] - массив всех открытых окон браузера.
BrowserWindow.getFocusedWindow()Возвращает BrowserWindow | null - окно, которое сфокусировано в этом приложении, иначе возвращает null.
BrowserWindow.fromWebContents(webContents)webContents WebContentsВозвращает BrowserWindow | null - окно, которое владеет объектом webContents, или имеет null если не содержит контент.
BrowserWindow.fromBrowserView(browserView)browserView BrowserViewВозвращает BrowserWindow - окно, которое владеет объектом webContents. If the given view is not attached to any window, returns null.
BrowserWindow.fromId(id)id IntegerВозвращает BrowserWindow | null - окно с указанным id.
Объекты, созданные с помощью new BrowserWindow, имеют следующие свойства:
const { BrowserWindow } = require('electron')\n// In this example `win` is our instance\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('https://github.com')\nwin.webContents Только чтениеA WebContents object this window owns. All web page related events and operations will be done via it.
Смотрите документацию webContents для его методов и событий.
win.id Только чтениеСвойство Integer представляющее уникальный идентификатор окна. Each ID is unique among all BrowserWindow instances of the entire Electron application.
win.autoHideMenuBarA Boolean property that determines whether the window menu bar should hide itself automatically. Once set, the menu bar will only show when users press the single Alt key.
Если панель меню уже видна, установка этого свойства в true не будет скрывать ее немедленно.
win.simpleFullScreenA Boolean property that determines whether the window is in simple (pre-Lion) fullscreen mode.
win.fullScreenA Boolean property that determines whether the window is in fullscreen mode.
win.focusable Windows macOSA Boolean property that determines whether the window is focusable.
win.visibleOnAllWorkspacesA Boolean property that determines whether the window is visible on all workspaces.
Note: Always returns false on Windows.
\nwin.shadowA Boolean property that determines whether the window has a shadow.
win.menuBarVisible Windows LinuxA 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.kioskA Boolean property that determines whether the window is in kiosk mode.
win.documentEdited macOSA 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 macOSA 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.titleA 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.
\nwin.minimizableСвойство Boolean определяет, может ли окно быть вручную свернуто пользователем.
В Linux setter это невозможно, хотя getter возвращает true.
win.maximizableСвойство Boolean определяет, может ли окно быть вручную развернуто пользователем.
В Linux setter это невозможно, хотя getter возвращает true.
win.fullScreenableСвойство Boolean которое определяет, может ли кнопка увеличить/зумировать окно переключать полноэкранный режим или увеличивать до предела окно.
win.resizableСвойство Boolean определяет, может ли окно быть вручную изменено пользователем.
win.closableСвойство Boolean определяет, может ли окно быть вручную закрыто пользователем.
В Linux setter это невозможно, хотя getter возвращает true.
win.movableСвойство Boolean определяет, может ли окно перемещаться пользователем.
В Linux setter это невозможно, хотя getter возвращает true.
win.excludedFromShownWindowsMenu macOSA Boolean property that determines whether the window is excluded from the application’s Windows menu. По умолчанию false.
const win = new BrowserWindow({ height: 600, width: 600 })\n\nconst template = [\n {\n role: 'windowmenu'\n }\n]\n\nwin.excludedFromShownWindowsMenu = true\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nwin.accessibleTitleA String property that defines an alternative title provided only to accessibility tools such as screen readers. This string is not directly visible to users.
Objects created with new BrowserWindow have the following instance methods:
Примечание: Некоторые методы доступны только в определенных операционных системах и помечены как таковые.
\nwin.destroy()Force closing the window, the unload and beforeunload event won't be emitted for the web page, and close event will also not be emitted for this window, but it guarantees the closed event will be emitted.
win.close()Try to close the window. This has the same effect as a user manually clicking the close button of the window. The web page may cancel the close though. See the close event.
\nwin.focus()Focuses on the window.
\nwin.blur()Removes focus from the window.
\nwin.isFocused()Returns Boolean - Whether the window is focused.
win.isDestroyed()Returns Boolean - Whether the window is destroyed.
win.show()Shows and gives focus to the window.
\nwin.showInactive()Shows the window but doesn't focus on it.
\nwin.hide()Скрывает окно.
\nwin.isVisible()Returns Boolean - Whether the window is visible to the user.
win.isModal()Returns Boolean - Whether current window is a modal window.
win.maximize()Maximizes the window. This will also show (but not focus) the window if it isn't being displayed already.
\nwin.unmaximize()Unmaximizes the window.
\nwin.isMaximized()Возвращает Boolean - если окно развернуто.
win.minimize()Minimizes the window. On some platforms the minimized window will be shown in the Dock.
\nwin.restore()Restores the window from minimized state to its previous state.
\nwin.isMinimized()Возвращает Boolean - если окно свернуто.
win.setFullScreen(flag)flag BooleanSets whether the window should be in fullscreen mode.
\nwin.isFullScreen()Returns Boolean - Whether the window is in fullscreen mode.
win.setSimpleFullScreen(flag) macOSflag BooleanEnters or leaves simple fullscreen mode.
\nSimple fullscreen mode emulates the native fullscreen behavior found in versions of macOS prior to Lion (10.7).
\nwin.isSimpleFullScreen() macOSReturns Boolean - Whether the window is in simple (pre-Lion) fullscreen mode.
win.isNormal()Returns Boolean - Whether the window is in normal state (not maximized, not minimized, not in fullscreen mode).
win.setAspectRatio(aspectRatio[, extraSize])aspectRatio Float - The aspect ratio to maintain for some portion of the content view.extraSize Size (optional) macOS - The extra size not to be included while maintaining the aspect ratio.This will make a window maintain an aspect ratio. The extra size allows a developer to have space, specified in pixels, not included within the aspect ratio calculations. This API already takes into account the difference between a window's size and its content size.
\nConsider a normal window with an HD video player and associated controls. Perhaps there are 15 pixels of controls on the left edge, 25 pixels of controls on the right edge and 50 pixels of controls below the player. In order to maintain a 16:9 aspect ratio (standard aspect ratio for HD @1920x1080) within the player itself we would call this function with arguments of 16/9 and\n{ width: 40, height: 50 }. The second argument doesn't care where the extra width and height are within the content view--only that they exist. Sum any extra width and height areas you have within the overall content view.
\nThe aspect ratio is not respected when window is resized programmatically with APIs like win.setSize.
win.setBackgroundColor(backgroundColor)backgroundColor String - Window's background color as a hexadecimal value, like #66CD00 or #FFF or #80FFFFFF (alpha is supported if transparent is true). По умолчанию - #FFF (белый).Sets the background color of the window. See Setting backgroundColor.
win.previewFile(path[, displayName]) macOSpath String - абсолютный путь до файла, для предпросмотра в QuickLook. Это важно, так как QuickLook использует имя файла и расширение файла из пути, чтобы определить тип содержимого файла для открытия.displayName String (опционально) - имя файла, для отображения в модальном виде QuickLook. Это чисто визуально и не влияет на тип содержимого файла. По умолчанию path.Использует QuickLook для предпросмотра файла, по данному пути.
\nwin.closeFilePreview() macOSЗакрывает текущую открытую панель QuickLook.
\nwin.setBounds(bounds[, animate])bounds Partial<Rectangle>animate Boolean (необязательно) macOSResizes and moves the window to the supplied bounds. Any properties that are not supplied will default to their current values.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\n// Установить все свойства границы\nwin.setBounds({ x: 440, y: 225, width: 800, height: 600 })\n\n// Установить одно свойство границы\nwin.setBounds({ width: 100 })\n\n// { x: 440, y: 225, width: 100, height: 600 }\nconsole.log(win.getBounds())\nwin.getBounds()Возвращает Rectangle - границы окна как объект.
win.getBackgroundColor()Returns String - Gets the background color of the window. See Setting backgroundColor.
win.setContentBounds(bounds[, animate])bounds Rectangleanimate Boolean (необязательно) macOSМеняет размеры и перемещает клиентскую область окна (например, веб-страницу) на заданные границы.
\nwin.getContentBounds()Возвращает Rectangle - границы области клиентского окна как объект.
win.getNormalBounds()Возвращает Rectangle - содержит границы окна в нормальном состоянии
Примечание: Независимо от текущего состояния окна: увеличено до предела, свернуто или в полноэкранном режиме, эта функция всегда возвратит позицию и размер окна в нормальном состоянии. В нормальном состоянии, getBounds и getNormalBounds возвращают тот же Rectangle.
win.setEnabled(enable)enable BooleanВключает или выключает окно.
\nwin.isEnabled()Returns Boolean - whether the window is enabled.
win.setSize(width, height[, animate])width Integerheight Integeranimate Boolean (необязательно) macOSResizes the window to width and height. If width or height are below any set minimum size constraints the window will snap to its minimum size.
win.getSize()Возвращает Integer[] - Содержит высоту и ширину окна.
win.setContentSize(width, height[, animate])width Integerheight Integeranimate Boolean (необязательно) macOSМеняет размер клиентской области окна (например, веб-страница) на width и height.
win.getContentSize()Возвращает Integer[] - содержит ширину и высоту клиентской области окна.
win.setMinimumSize(width, height)width Integerheight IntegerУстанавливает минимальный размер окна на width и height.
win.getMinimumSize()Возвращает Integer[] - содержит минимальную ширину и высоту окна.
win.setMaximumSize(width, height)width Integerheight IntegerУстанавливает максимальный размер окна на width и height.
win.getMaximumSize()Возвращает Integer[] - содержит максимальную ширину и высоту окна.
win.setResizable(resizable)resizable BooleanSets whether the window can be manually resized by the user.
\nwin.isResizable()Returns Boolean - Whether the window can be manually resized by the user.
win.setMovable(movable) macOS Windowsmovable BooleanSets whether the window can be moved by user. On Linux does nothing.
\nwin.isMovable() macOS WindowsВозвращает Boolean - может пользователь перемещать окно или нет.
На Linux всегда возвращает true.
win.setMinimizable(minimizable) macOS Windowsminimizable BooleanSets whether the window can be manually minimized by user. On Linux does nothing.
\nwin.isMinimizable() macOS WindowsReturns Boolean - Whether the window can be manually minimized by the user.
На Linux всегда возвращает true.
win.setMaximizable(maximizable) macOS Windowsmaximizable BooleanSets whether the window can be manually maximized by user. On Linux does nothing.
\nwin.isMaximizable() macOS WindowsВозвращает Boolean - может пользователь вручную увеличивать до предела окно или нет.
На Linux всегда возвращает true.
win.setFullScreenable(fullscreenable)fullscreenable BooleanSets whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
\nwin.isFullScreenable()Returns Boolean - Whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
win.setClosable(closable) macOS Windowsclosable BooleanSets whether the window can be manually closed by user. On Linux does nothing.
\nwin.isClosable() macOS WindowsВозвращает Boolean - может пользователь вручную закрывать окно или нет.
На Linux всегда возвращает true.
win.setAlwaysOnTop(flag[, level][, relativeLevel])flag Booleanlevel String (опционально) macOS Windows - Значения включают normal, floating, torn-off-menu, modal-panel, main-menu, status, pop-up-menu, screen-saver и dockfloating, когда flag установлен true. level сбрасывается на normal, когда флаг устанавливается false. Обратите внимание, что от floating до status включительно, окно находится под Dock в macOS и под панелью задач в Windows. От pop-up-menu и выше отображается над Dock на macOS и выше панели задач на Windows. Смотрите документацию macOS для подробностей.relativeLevel Integer (опционально) macOS - количество слоев выше, чтобы установить окно относительно заданного level. По умолчанию - 0. Обратите внимание, что Apple не рекомендует устанавливать уровни выше, чем 1 верхнего screen-saver.Sets whether the window should show always on top of other windows. After setting this, the window is still a normal window, not a toolbox window which can not be focused on.
\nwin.isAlwaysOnTop()Возвращает Boolean - всегда ли окно поверх остальных окон.
win.moveAbove(mediaSourceId)mediaSourceId String - Window id in the format of DesktopCapturerSource's id. For example \"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()Перемещает окно на верх(z-order) независимо от фокуса
\nwin.center()Перемещает окно в центр экрана.
\nwin.setPosition(x, y[, animate])x Integery Integeranimate Boolean (необязательно) macOSПеремещает окно на x и y.
win.getPosition()Возвращает Integer[] - содержит текущую позицию окна.
win.setTitle(title)title StringИзменяет название нативного окна на title.
win.getTitle()Возвращает String - название нативного окна.
Примечание: Название веб-страницы может отличаться от названия нативного окна.
\nwin.setSheetOffset(offsetY[, offsetX]) macOSoffsetY FloatoffsetX Float (опционально)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. Например:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nconst toolbarRect = document.getElementById('toolbar').getBoundingClientRect()\nwin.setSheetOffset(toolbarRect.height)\nwin.flashFrame(flag)flag BooleanStarts or stops flashing the window to attract user's attention.
\nwin.setSkipTaskbar(skip)skip BooleanMakes the window not show in the taskbar.
\nwin.setKiosk(flag)flag BooleanEnters or leaves kiosk mode.
\nwin.isKiosk()Returns Boolean - Whether the window is in kiosk mode.
win.isTabletMode() WindowsReturns Boolean - Whether the window is in Windows 10 tablet mode.
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.
\nThis API returns whether the window is in tablet mode, and the resize event can be be used to listen to changes to tablet mode.
win.getMediaSourceId()Returns String - Window id in the format of DesktopCapturerSource's id. For example \"window:1324:0\".
More precisely the format is window:id:other_id where id is HWND on Windows, CGWindowID (uint64_t) on macOS and Window (unsigned long) on Linux. other_id is used to identify web contents (tabs) so within the same top level window.
win.getNativeWindowHandle()Returns Buffer - The platform-specific handle of the window.
The native type of the handle is HWND on Windows, NSView* on macOS, and Window (unsigned long) on Linux.
win.hookWindowMessage(message, callback) Windowsmessage Integercallback FunctionwParam any - The wParam provided to the WndProclParam any - The lParam provided to the WndProcHooks a windows message. The callback is called when the message is received in the WndProc.
win.isWindowMessageHooked(message) Windowsmessage IntegerReturns Boolean - true or false depending on whether the message is hooked.
win.unhookWindowMessage(message) Windowsmessage IntegerUnhook the window message.
\nwin.unhookAllWindowMessages() WindowsUnhooks all of the window messages.
\nwin.setRepresentedFilename(filename) macOSfilename StringSets the pathname of the file the window represents, and the icon of the file will show in window's title bar.
\nwin.getRepresentedFilename() macOSReturns String - The pathname of the file the window represents.
win.setDocumentEdited(edited) macOSedited BooleanSpecifies whether the window’s document has been edited, and the icon in title bar will become gray when set to true.
win.isDocumentEdited() macOSReturns Boolean - Whether the window's document has been edited.
win.focusOnWebView()win.blurWebView()win.capturePage([rect])rect Rectangle (optional) - The bounds to captureВозвращает Promise<NativeImage> - разрешается с NativeImage
Захватывает снимок страницы в границах rect. Пропустив rect, будет сделан захват всей видимой страницы. If the page is not visible, rect may be empty.
win.loadURL(url[, options])url Stringoptions Object (опционально)httpReferrer (String | Referrer) (опционально) - HTTP Referrer.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (опционально) - Базовый URL (с разделителем пути), для файлов, которые будут загружены по URL данных. Это необходимо, только если указанный url это URL данных и необходимо загрузить другие файлы.Возвращает Promise<void> - промис будет разрешен, когда страница завершит загрузку (см. did-finish-load), и отклоняет, если страница не удачно загрузилась (см. did-fail-load).
Тоже, что и webContents.loadURL(url[, options]).
The url can be a remote address (e.g. http://) or a path to a local HTML file using the file:// protocol.
To ensure that file URLs are properly formatted, it is recommended to use Node's url.format method:
const url = require('url').format({\n protocol: 'file',\n slashes: true,\n pathname: require('path').join(__dirname, 'index.html')\n})\n\nwin.loadURL(url)\nYou can load a URL using a POST request with URL-encoded data by doing the following:
win.loadURL('http://localhost:8000/post', {\n postData: [{\n type: 'rawData',\n bytes: Buffer.from('hello=world')\n }],\n extraHeaders: 'Content-Type: application/x-www-form-urlencoded'\n})\nwin.loadFile(filePath[, options])filePath Stringoptions Object (опционально)query Record<String, String> (опционально) - переданная в url.format().search String (optional) - Passed to url.format().hash String (optional) - Passed to url.format().Возвращает Promise<void> - промис будет разрешен, когда страница завершит загрузку (см. did-finish-load), и отклоняет, если страница не удачно загрузилась (см. did-fail-load).
Same as webContents.loadFile, filePath should be a path to an HTML file relative to the root of your application. See the webContents docs for more information.
win.reload()Same as webContents.reload.
win.setMenu(menu) Linux Windowsmenu Menu | nullУстанавливает menu в меню окна.
win.removeMenu() Linux WindowsУдаляет меню окна.
\nwin.setProgressBar(progress[, options])progress Doubleoptions Object (опционально)mode String Windows - Mode for the progress bar. Can be none, normal, indeterminate, error or paused.Устанавливает значение прогресса на шкале прогресса. Valid range is [0, 1.0].
\nУдаляет индикатор прогресса, когда прогресс меньше 0; Изменяет в режим indeterminate, когда прогресс больше 1.
\nНа платформе Linux поддерживается только рабочая среда Unity, Вам необходимо указать имя файла *.desktop в поле desktopName в package.json. По умолчанию будет предполагаться {app.name}.desktop.
На Windows режим может быть передан. Принимаемые значения: none, normal, indeterminate, error и paused. Если Вы вызовете setProgressBar без установленного режима (но со значением в пределах допустимого диапозона), будет предполагаться normal.
win.setOverlayIcon(overlay, description) Windowsoverlay NativeImage | null - иконка, которая будет отображаться в правом краю иконки на панели задач. Если параметр null, оверлей будет очищенdescription String - описание, которое будет представлено для доступности чтения с экранаУстанавливает 16x16 пиксельный оверлей поверх текущей иконки в панели задач, обычно используется для передачи какого-либо статуса приложения или пассивного уведомления пользователя.
\nwin.setHasShadow(hasShadow)hasShadow BooleanУстанавливает, будет ли окно иметь тень.
\nwin.hasShadow()Возвращает Boolean - есть ли у окна тень.
win.setOpacity(opacity) Windows macOSopacity Number - между 0.0 (полная прозрачность) и 1.0 (полная видимость)Sets the opacity of the window. On Linux, does nothing. Out of bound number values are clamped to the [0, 1] range.
\nwin.getOpacity()Возвращает Number - между 0.0 (полная прозрачность) и 1.0 (полная видимость). On Linux, always returns 1.
win.setShape(rects) Windows Linux Экспериментальноrects Rectangle[] - Sets a shape on the window. Passing an empty list reverts the window to being rectangular.Установка формы окна, которая определяет область в окне, где система разрешает отрисовку и взаимодействие пользователя. Вне данного региона ни один пиксель не отрисуется и ни одно событие мыши не будет зарегистрировано. Вне региона события мыши не будут получены этим окном, но будет передаваться чему-либо позади окна.
\nwin.setThumbarButtons(buttons) Windowsbuttons ThumbarButton[]Возвращает Boolean - успешно ли добавлены кнопки
Добавляет панель миниатюр, с определенным набором кнопок, на слой кнопок в изображении эскиза окна в панели задач. Возвращает объект Boolean, который указывает успешно ли добавлена панель миниатюр.
Количество кнопок в панели миниатюр не должно быть больше, чем 7, из-за ограничений. После установки панели миниатюр, панель не может быть удалена, из-за ограничений платформы. Но Вы можете вызвать метод с пустым массивом, чтобы убрать кнопки.
\nbuttons является массивом объектов Button:
Button Objecticon NativeImage - иконка, отображаемая на панели миниатюр.click Functiontooltip String (опционально) - текст всплывающей подсказки на кнопке.flags String - Управление конкретными состояниями и поведением кнопки. По умолчанию, является ['enabled'].flags — это массив, который может включать следующие строки:
enabled - кнопка активна и доступна пользователю.disabled - Кнопка отключена. Она присутствует, но имеет неактивное визуальное состояние и не будет реагировать на действия пользователя.dismissonclick - когда кнопка нажата, окно панели миниатюр закрывается немедленно.nobackground - не рисует границы кнопок, использует только изображение.hidden - кнопка не отображается пользователю.noninteractive - Кнопка включена, но не интерактивна; ни одно состояние кнопки не отображается. Это значение предназначено для случаев, когда кнопка используется в уведомлении.win.setThumbnailClip(region) Windowsregion Rectangle - область окнаУстанавливает область окна, которая будет показана в панели миниатюр, при наведении мыши на окно в панели задач. Вы можете сбросить панель миниатюры, чтобы показывалось окно полностью, указав пустую область: { x: 0, y: 0, width: 0, height: 0 }.
win.setThumbnailToolTip(toolTip) WindowstoolTip StringУстанавливает всплывающую подсказку, которая будет отображена, при наведении мыши на панель миниатюры окна в панели задач.
\nwin.setAppDetails(options) Windowsoptions ObjectappId String (опционально) - App User Model ID окна. Это должно быть установлено, иначе остальные параметры не будут иметь никакого эффекта.appIconPath String (опционально) - иконка перезапуска окна.appIconIndex Integer (optional) - Index of the icon in appIconPath. Ignored when appIconPath is not set. По умолчанию 0.relaunchCommand String (опционально) - команда перезапуска окна.relaunchDisplayName String (опционально) - отображаемое имя перезапуска окна.Устанавливает свойства для кнопки окна на панели задач.
\nNote: relaunchCommand and relaunchDisplayName must always be set together. If one of those properties is not set, then neither will be used.
win.showDefinitionForSelection() macOSТоже, что и webContents.showDefinitionForSelection().
win.setIcon(icon) Windows Linuxicon NativeImage | StringМеняет иконку окна.
\nwin.setWindowButtonVisibility(visible) macOSvisible BooleanУстанавливает, должны ли быть видны кнопки контроля окна.
\nwin.setAutoHideMenuBar(hide)hide BooleanSets whether the window menu bar should hide itself automatically. 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()Returns Boolean - Whether menu bar automatically hides itself.
win.setMenuBarVisibility(visible) Windows Linuxvisible BooleanSets whether the menu bar should be visible. If the menu bar is auto-hide, users can still bring up the menu bar by pressing the single Alt key.
win.isMenuBarVisible()Returns Boolean - Whether the menu bar is visible.
win.setVisibleOnAllWorkspaces(visible[, options])visible Booleanoptions Object (опционально)visibleOnFullScreen Boolean (optional) macOS - Sets whether the window should be visible above fullscreen windows.skipTransformProcessType Boolean (optional) macOS - Calling setVisibleOnAllWorkspaces will by default transform the process type between UIElementApplication and ForegroundApplication to ensure the correct behavior. However, this will hide the window and dock for a short time every time it is called. If your window is already of type UIElementApplication, you can bypass this transformation by passing true to skipTransformProcessType.Устанавливает видимость окна на всех рабочих местах.
\nПримечание: Этот API ничего не делает в Windows.
\nwin.isVisibleOnAllWorkspaces()Возвращает Boolean - видно ли окно на всех рабочих местах.
Примечание: Данный API всегда возвращает false в Windows.
\nwin.setIgnoreMouseEvents(ignore[, options])ignore Логическое значениеoptions Object (опционально)forward Boolean (optional) macOS Windows - If true, forwards mouse move messages to Chromium, enabling mouse related events such as mouseleave. Only used when ignore is true. If ignore is false, forwarding is always disabled regardless of this value.Включает для окна игнорирование событий от мыши.
\nВсе события мыши, произошедшие в этом окне, будут переданы окну позади этого окна, но, если это окно сфокусировано, оно все еще будет получать события клавиатуры.
\nwin.setContentProtection(enable) macOS Windowsenable BooleanПредотвращает захват содержимого окна другими приложениями.
\nOn 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 Windowsfocusable BooleanМеняет, может ли окно быть сфокусировано.
\nНа macOS он не снимает фокус с окна.
\nwin.isFocusable() macOS WindowsReturns whether the window can be focused.
\nwin.setParentWindow(parent)parent BrowserWindow | nullУстанавливает parent как родителя текущего окна, передав null превратит текущее окно в окно верхнего уровня.
win.getParentWindow()Возвращает BrowserWindow - родительское окно.
win.getChildWindows()Возвращает BrowserWindow[] - все дочерние окна.
win.setAutoHideCursor(autoHide) macOSautoHide BooleanКонтролирует скрытие курсора при вводе текста.
\nwin.selectPreviousTab() macOSВыбирает предыдущую вкладку, когда нативные вкладки включены и в окне присутствуют другие вкладки.
\nwin.selectNextTab() macOSВыбирает следующую вкладку, когда нативные вкладки включены и в окне присутствуют другие вкладки.
\nwin.mergeAllWindows() macOSОбъединяет все окна в одно окно с множественными вкладками, когда нативные вкладки включены и в присутствуют открытые окна больше, чем 1.
\nwin.moveTabToNewWindow() macOSПеремещает текущую вкладку в новое окно, если нативные вкладки включены и присутствует больше, чем одна вкладка, в текущем окне.
\nwin.toggleTabBar() macOSПереключает видимость вкладки, если включены нативные вкладки и присутствует только одна вкладка в текущем окне.
\nwin.addTabbedWindow(browserWindow) macOSbrowserWindow BrowserWindowДобавляет окно, как вкладку, в это окно, после вкладки экземпляра окна.
\nwin.setVibrancy(type) macOStype String | null - Может быть appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window и under-page. See the macOS documentation for more details.Adds a vibrancy effect to the browser window. Passing null or an empty string will remove the vibrancy effect on the window.
Обратите внимание, что appearance-based, light, dark, medium-light и ultra-dark устарела и будет удалена в следующей версии macOS.
win.setTrafficLightPosition(position) macOSposition PointSet a custom position for the traffic light buttons in frameless window.
\nwin.getTrafficLightPosition() macOSReturns Point - The custom position for the traffic light buttons in frameless window.
win.setTouchBar(touchBar) macOStouchBar TouchBar | nullSets the touchBar layout for the current window. Specifying null or undefined clears the touch bar. This method only has an effect if the machine has a touch bar and is running on macOS 10.12.1+.
Примечание: TouchBar API в настоящее время является экспериментальным и может быть изменен или удален в будущих версиях Electron.
\nwin.setBrowserView(browserView) ЭкспериментальноbrowserView BrowserView | null - Attach browserView to win. If there are other BrowserViews attached, they will be removed from this window.win.getBrowserView() ЭкспериментальноReturns BrowserView | null - The BrowserView attached to win. Returns null if one is not attached. Throws an error if multiple BrowserViews are attached.
win.addBrowserView(browserView) ЭкспериментальноbrowserView BrowserViewЗаменяет метод setBrowserView, для поддержки работы с множественными видами браузера.
\nwin.removeBrowserView(browserView) ЭкспериментальноbrowserView BrowserViewwin.setTopBrowserView(browserView) ЭкспериментальноbrowserView BrowserViewRaises browserView above other BrowserViews attached to win. Throws an error if browserView is not attached to win.
win.getBrowserViews() ЭкспериментальноВозвращает BrowserView[] - массив всех BrowserViews которые были присоединены с addBrowserView или setBrowserView.
Примечание: BrowserView API в настоящее время экспериментально и может измениться или быть удалено в будущих релизах Electron.
", "title": "BrowserWindow", "description": "Создавайте окна браузера и управляйте ими." }, "/docs/api/browser-window-proxy": { "locale": "ru-RU", "slug": "browser-window-proxy", "href": "/docs/api/browser-window-proxy", "crowdinFileId": "256285", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-window-proxy.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nМанипулируйте дочерним окном браузера
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Объект BrowserWindowProxy возвращается из window.open и предоставляет ограниченное управление дочерним окном.
Экземпляр объекта BrowserWindowProxy содержит следующие методы:
win.blur()Убирает фокус с дочернего окна.
\nwin.close()Принудительно закрывает дочернее окно без вызова события выгрузки.
\nwin.eval(code)code StringПозволяет запускать код в дочернем окне.
\nwin.focus()Фокусируется на дочернем окне (переносит окно на передний план).
\nwin.print()Вызывает диалог print в рамках дочернего окна.
\nwin.postMessage(message, targetOrigin)message anytargetOrigin StringОтправляет сообщение дочернему окну с указанием родительского окна или * - без указания.
Помимо этих методов, дочернее окно реализует объект window.opener без свойств и с одним методом.
Экземпляр объекта BrowserWindowProxy содержит следующие свойства:
win.closedBoolean, который устанавливается на true после закрытия дочернего окна.
Follow the guidelines below for building Electron itself, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nПеред началом проверьте требования сборки для вашей системы
\n\nElectron's Build Tools automate much of the setup for compiling Electron from source with different configurations and build targets. If you wish to set up the environment manually, the instructions are listed below.
\nВам нужно будет установить depot_tools, набор инструментов, используемый для извлечения Chromium и его зависимостей.
Также, для Windows вам потребуется добавить переменную среды DEPOT_TOOLS_WIN_TOOLCHAIN=0. Чтобы это сделать, откройте Панель управления → Система и безопасность → Система → Дополнительные параметры системы и добавьте системную переменную DEPOT_TOOLS_WIN_TOOLCHAIN со значением 0. Она говорит depot_tools использовать вашу локальную версию Visual Studio (по умолчанию, depot_tools попробует загрузить приватную Google версию к которой имеют доступ только Гугловцы).
If you plan on checking out Electron more than once (for example, to have multiple parallel directories checked out to different branches), using the git cache will speed up subsequent calls to gclient. To do this, set a GIT_CACHE_PATH environment variable:
$ export GIT_CACHE_PATH=\"${HOME}/.git_cache\"\n$ mkdir -p \"${GIT_CACHE_PATH}\"\n# Это будет использовать примерно 16 гигабайт.\n$ mkdir electron && cd electron\n$ gclient config --name \"src/electron\" --unmanaged https://github.com/electron/electron\n$ gclient sync --with_branch_heads --with_tags\n# This will take a while, go get a coffee.\n\n\nВместо
\nhttps://github.com/electron/electron, вы можете использовать здесь свой собственный форк (что-то вродеhttps://github.com/<username>/electron).
If you intend to git pull or git push from the official electron repository in the future, you now need to update the respective folder's origin URLs.
$ cd src/electron\n$ git remote remove origin\n$ git remote add origin https://github.com/electron/electron\n$ git checkout main\n$ git branch --set-upstream-to=origin/main\n$ cd -\n📝 gclient works by checking a file called DEPS inside the src/electron folder for dependencies (like Chromium or Node.js). Running gclient sync -f ensures that all dependencies required to build Electron match that file.
So, in order to pull, you'd run the following commands:
\n$ cd src/electron\n$ git pull\n$ gclient sync -f\n$ cd src\n$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nИли на Windows (без дополнительных аргументов):
\n$ cd src\n$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\\buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\")\"\nThis will generate a build directory out/Testing under src/ with the testing build configuration. You can replace Testing with another name, but it should be a subdirectory of out. Also you shouldn't have to run gn gen again—if you want to change the build arguments, you can run gn args out/Testing to bring up an editor.
To see the list of available build configuration options, run gn args out/Testing --list.
Для генерации тестовой сборки Electron:
\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nFor generating Release (aka \"non-component\" or \"static\") build config of Electron:
\n$ gn gen out/Release --args=\"import(\\\"//electron/build/args/release.gn\\\") $GN_EXTRA_ARGS\"\nЧтобы построить, запустите ninja с целью electron: Nota Bene: Это займет некоторое время и, вероятно, нагревает ваш ноутбук.
Для конфигурации тестирования:
\n$ ninja -C out/Testing electron\nДля конфигурации релиза:
\n$ ninja -C out/Release electron\nThis will build all of what was previously 'libchromiumcontent' (i.e. the content/ directory of chromium and its dependencies, incl. WebKit and V8), so it will take a while.
Собранный исполняемый файл будет находиться в ./out/Testing:
$ ./out/Testing/Electron.app/Contents/MacOS/Electron\n# или, на Windows\n$ ./out/Testing/electron.exe\n# или, на Linux\n$ ./out/Testing/electron\nOn linux, first strip the debugging and symbol information:
\nelectron/script/strip-binaries.py -d out/Release\nTo package the electron build as a distributable zip file:
\nninja -C out/Release electron:electron_dist_zip\nTo compile for a platform that isn't the same as the one you're building on, set the target_cpu and target_os GN arguments. For example, to compile an x86 target from an x64 host, specify target_cpu = \"x86\" in gn args.
$ gn gen out/Testing-x86 --args='... target_cpu = \"x86\"'\nNot all combinations of source and target CPU/OS are supported by Chromium.
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Host | Target | Состояние |
|---|---|---|
| Windows x64 | Windows arm64 | Experimental |
| Windows x64 | Windows x86 | Автоматически тестировано |
| Linux x64 | Linux x86 | Автоматически тестировано |
If you test other combinations and find them to work, please update this document :)
\nSee the GN reference for allowable values of target_os and target_cpu.
To cross-compile for Windows on Arm, follow Chromium's guide to get the necessary dependencies, SDK and libraries, then build with ELECTRON_BUILDING_WOA=1 in your environment before running gclient sync.
set ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nИли (если используется PowerShell):
\n$env:ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nДалее, запустите gn gen, как указано выше, с target_cpu=\"arm64\".
To run the tests, you'll first need to build the test modules against the same version of Node.js that was built as part of the build process. To generate build headers for the modules to compile against, run the following under src/ directory.
$ ninja -C out/Testing third_party/electron_node:headers\nТеперь вы можете запустить тесты.
\nЕсли вы что-то отлаживаете, то вам может быть полезно передать некоторые дополнительные флаги в бинарный Electron:
\n$ npm run test -- \\\n --enable-logging -g 'BrowserWindow module'\nIt is possible to share the gclient git cache with other machines by exporting it as SMB share on linux, but only one process/machine can be using the cache at a time. Блокировки, установленные скриптом git-cache попытаются предотвратить это, однако возможна нестабильная работа по сети.
\nНа Windows, у SMBv2 есть кэш директорий, который будет создавать проблемы со скриптом git-cache, поэтому необходимо отключить его, установив ключ регистра
\nHKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\\DirectoryCacheLifetime\nна 0. Подробнее: https://stackoverflow.com/a/9935126
\nЭто можно быстро установить в powershell (запускается от имени администратора):
\nNew-ItemProperty -Path \"HKLM:\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force\nIf gclient sync is interrupted the git tree may be left in a bad state, leading to a cryptic message when running gclient sync in the future:
2> Conflict while rebasing this branch.\n2> Fix the conflict and run gclient again.\n2> See man git-rebase for details.\nIf there are no git conflicts or rebases in src/electron, you may need to abort a git am in src:
$ cd ../\n$ git am --abort\n$ cd electron\n$ gclient sync -f\nЕсли вы видите запрос для Имя пользователя для 'https://chrome-internal.googlesource.com': при запуске gclient sync на Windows, это возможно, потому что DEPOT_TOOLS_WIN_TOOLCHAIN переменная окружения не установлена в 0. Откройте Панель управления → Система и безопасность → Система → Дополнительные параметры системы и добавьте системную переменную DEPOT_TOOLS_WIN_TOOLCHAIN с значением 0. Она говорит depot_tools использовать вашу локальную версию Visual Studio (по умолчанию, depot_tools попробует загрузить приватную Google версию к которой имеют доступ только Гугловцы).
Follow the guidelines below for building Electron itself on Linux, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nAt least 25GB disk space and 8GB RAM.
\nPython 2.7.x. Some distributions like CentOS 6.x still use Python 2.6.x so you may need to check your Python version with python -V.
Please also ensure that your system and Python version support at least TLS 1.2. For a quick test, run the following script:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, use your system's package manager to update Python to the latest version in the 2.7.x branch. Alternatively, visit https://www.python.org/downloads/ for detailed instructions.
\nNode.js. There are various ways to install Node. You can download source code from nodejs.org and compile it. Doing so permits installing Node on your own home directory as a standard user. Or try repositories such as NodeSource.
\nclang 3.4 or later.
\nDevelopment headers of GTK 3 and libnotify.
\nOn Ubuntu, install the following libraries:
\n$ sudo apt-get install build-essential clang libdbus-1-dev libgtk-3-dev \\\n libnotify-dev libgnome-keyring-dev \\\n libasound2-dev libcap-dev libcups2-dev libxtst-dev \\\n libxss1 libnss3-dev gcc-multilib g++-multilib curl \\\n gperf bison python-dbusmock openjdk-8-jre\nOn RHEL / CentOS, install the following libraries:
\n$ sudo yum install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Fedora, install the following libraries:
\n$ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Arch Linux / Manjaro, install the following libraries:
\n$ sudo pacman -Syu base-devel clang libdbus gtk2 libnotify \\\n libgnome-keyring alsa-lib libcap libcups libxtst \\\n libxss nss gcc-multilib curl gperf bison \\\n python2 python-dbusmock jdk8-openjdk\nOther distributions may offer similar packages for installation via package managers such as pacman. Or one can compile from source code.
\nIf you want to build for an arm target you should also install the following dependencies:
$ sudo apt-get install libc6-dev-armhf-cross linux-libc-dev-armhf-cross \\\n g++-arm-linux-gnueabihf\nSimilarly for arm64, install the following:
$ sudo apt-get install libc6-dev-arm64-cross linux-libc-dev-arm64-cross \\\n g++-aarch64-linux-gnu\nAnd to cross-compile for arm or ia32 targets, you should pass the target_cpu parameter to gn gen:
$ gn gen out/Testing --args='import(...) target_cpu=\"arm\"'\nPrebuilt clang will try to link to libtinfo.so.5. Depending on the host architecture, symlink to appropriate libncurses:
$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5\nThe default building configuration is targeted for major desktop Linux distributions. To build for a specific distribution or device, the following information may help you.
\nclang instead of downloaded clang binariesBy default Electron is built with prebuilt clang binaries provided by the Chromium project. If for some reason you want to build with the clang installed in your system, you can specify the clang_base_path argument in the GN args.
For example if you installed clang under /usr/local/bin/clang:
$ gn gen out/Testing --args='import(\"//electron/build/args/testing.gn\") clang_base_path = \"/usr/local/bin\"'\nclangBuilding Electron with compilers other than clang is not supported.
Follow the guidelines below for building Electron itself on macOS, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nPlease also ensure that your system and Python version support at least TLS 1.2. This depends on both your version of macOS and Python. For a quick test, run:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, you can either update macOS to High Sierra or install a new version of Python 2.7.x. To upgrade Python, use Homebrew:
\n$ brew install python@2 && brew link python@2 --force\nЕсли вы используете Python предоставленный Homebrew, вам также необходимо установить следующие модули Python:
\nВы можете использовать pip для установки:
$ pip установить pyobjc\nIf you're developing Electron and don't plan to redistribute your custom Electron build, you may skip this section.
\nOfficial Electron builds are built with Xcode 12.2, and the macOS 11.0 SDK. Building with a newer SDK works too, but the releases currently use the 11.0 SDK.
\nFollow the guidelines below for building Electron itself on Windows, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nvs2019_install = DRIVE:\\path\\to\\Microsoft Visual Studio\\2019\\Community, replacing 2019 and Community with your installed versions and replacing DRIVE: with the drive that Visual Studio is on. Обычно, это C:.WINDOWSSDKDIR = DRIVE:\\path\\to\\Windows Kits\\10, replacing DRIVE: with the drive that Windows Kits is on. Обычно, это C:.symstore.exe is used for creating a symbol store from .pdb files.Modify → Individual Components, scroll down and select the appropriate Windows SDK to install. Another option would be to look at the Windows SDK and emulator archive and download the standalone version of the SDK respectively.Control Panel → Programs → Programs and Features → Select the \"Windows Software Development Kit\" → Change → Change → Check \"Debugging Tools For Windows\" → Change. Or, you can download the standalone SDK installer and use it to install the Debugging Tools.Если у вас нет установщика Windows, то dev.microsoftedge.com имеет версии Windows, которые вы можете использовать для сборки Electron.
\nСборка Electron осуществляется исключительно через скрипты командной строки, и не может быть осуществлена в Visual Studio. Вы можете разрабатывать Electron в любом редакторе, но в будущем будет поддержка сборки в Visual Studio.
\nПримечание: Даже если Visual Studio не используется для сборки, он всё ещё требуется, потому что нам нужны средства сборки, которые он предоставляет.
\nWindows Security doesn't like one of the files in the Chromium source code (see https://crbug.com/441184), so it will constantly delete it, causing gclient sync issues. You can exclude the source tree from being monitored by Windows Security by following these instructions.
To build for the 32bit target, you need to pass target_cpu = \"x86\" as a GN arg. You can build the 32bit target alongside the 64bit target by using a different output directory for GN, e.g. out/Release-x86, with different arguments.
$ gn gen out/Release-x86 --args=\"import(\\\"//electron/build/args/release.gn\\\") target_cpu=\\\"x86\\\"\"\nВсе остальные инструкции по сборке идентичны.
\nДля генерации проекта в Visual Studio, вы можете передать параметр --ide=vs2017 в gn gen:
$ gn gen out/Testing --ide=vs2017\nЕсли вы столкнулись с ошибкой по типу Команда xxxx не найдена, вы можете попробовать использовать VS2015 Command Prompt консоль для выполнения скриптов сборки.
Убедитесь, что у вас установлена последняя версия Visual Studio.
\nПопробуйте переустановить 32-х битный Node.js.
\nСоздание директории по данному пути должно исправить проблему:
\n$ mkdir ~\\AppData\\Roaming\\npm\nВы можете столкнуться с этой ошибкой, если вы используете Git Bash для сборки, вместо этого, вы должны использовать PowerShell или командную строку Visual Code.
\nnode.js имеет несколько слишком длинных путей, и по стандарту, git на windows не обрабатывает длинные пути корректно (даже если windows их поддерживает). Это должно помочь:
\n$ git config --system core.longpaths true\nThis can happen during build, when Debugging Tools for Windows has been installed with Windows Driver Kit. Uninstall Windows Driver Kit and install Debugging Tools with steps described above.
\nУбедитесь, что вы установили pywin32 при помощи pip install pywin32.
Эта ошибка является \"функцией\" командной строки Windows. It happens when clicking inside the prompt window with QuickEdit enabled and is intended to allow selecting and copying output text easily. Puisque chaque clic accidentel met en pause le processus de construction, vous pouvez désactiver cette fonctionnalité dans les propriétés de l'invite de commande.
Electron uses GN for project generation and ninja for building. Project configurations can be found in the .gn and .gni files.
The following gn files contain the main rules for building Electron:
BUILD.gn defines how Electron itself is built and includes the default configurations for linking with Chromium.build/args/{debug,release,all}.gn contain the default build arguments for building Electron.Since Chromium is quite a large project, the final linking stage can take quite a few minutes, which makes it hard for development. In order to solve this, Chromium introduced the \"component build\", which builds each component as a separate shared library, making linking very quick but sacrificing file size and performance.
\nElectron inherits this build option from Chromium. In Debug builds, the binary will be linked to a shared library version of Chromium's components to achieve fast linking time; for Release builds, the binary will be linked to the static library versions, so we can have the best possible binary size and performance.
NB this section is out of date and contains information that is no longer relevant to the GN-built electron.
\nTest your changes conform to the project coding style using:
\n$ npm run lint\nTest functionality using:
\n$ npm test\nWhenever you make changes to Electron source code, you'll need to re-run the build before the tests:
\n$ npm run build && npm test\nYou can make the test suite run faster by isolating the specific test or block you're currently working on using Mocha's exclusive tests feature. Append .only to any describe or it function call:
describe.only('some feature', () => {\n // ... только в этом блоке будут выполняться тесты\n})\nAlternatively, you can use mocha's grep option to only run tests matching the given regular expression pattern:
$ npm test -- --grep child_process\nTests that include native modules (e.g. runas) can't be executed with the debug build (see #2558 for details), but they will work with the release build.
To run the tests with the release build use:
\n$ npm test -- -R\ndata String - PEM encoded dataissuer CertificatePrincipal - Issuer principalissuerName String - Issuer's Common NameissuerCert Certificate - Issuer certificate (if not self-signed)subject CertificatePrincipal - Subject principalsubjectName String - Subject's Common NameserialNumber String - Hex value represented stringvalidStart Number - Start date of the certificate being valid in secondsvalidExpiry Number - End date of the certificate being valid in secondsfingerprint String - Fingerprint of the certificatecommonName String - Common Name.organizations String[] - Organization names.organizationUnits String[] - Organization Unit names.locality String - Locality.state String - State or province.country String - Country or region.\n\nСписок ресурсов для изучения Chromium и отслеживания его разработки
\n
Также смотрите V8 Development
", "title": "Разработка Chromium", "description": "Список ресурсов для изучения Chromium и отслеживания его разработки" }, "/docs/development/clang-format": { "locale": "ru-RU", "slug": "clang-format", "href": "/docs/development/clang-format", "crowdinFileId": "256143", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/clang-format.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "clang-format это инструмент для автоматического форматирования кода на C/C++/Objective-C code, он используется для того, чтобы в процессе ревью разработчики не беспокоились о проблемах, связанных с форматированием.
Настоятельно рекомендуется форматировать измененный вами код C++ перед открытием пулл-реквестов, это сэкономят время вам и ревьюверам.
\nВы можете установить clang-format и git-clang-format командой npm install -g clang-format.
To automatically format a file according to Electron C++ code style, run clang-format -i path/to/electron/file.cc. It should work on macOS/Linux/Windows.
Процесс форматирования измененного вами кода:
\ngit add your_changed_file.cc.git-clang-format, и вы вероятно увидите изменения в your_changed_file.cc, эти изменения сформированы из clang-format.git add your_changed_file.cc, и выполните commit.If you want to format the changed code on your latest git commit (HEAD), you can run git-clang-format HEAD~1. See git-clang-format -h for more details.
You can also integrate clang-format directly into your favorite editors. For further guidance on setting up editor integration, see these pages:
clang-tidy is a tool to automatically check C/C++/Objective-C code for style violations, programming errors, and best practices.
Electron's clang-tidy integration is provided as a linter script which can be run with npm run lint:clang-tidy. While clang-tidy checks your on-disk files, you need to have built Electron so that it knows which compiler flags were used. There is one required option for the script --output-dir, which tells the script which build directory to pull the compilation information from. A typical usage would be: npm run lint:clang-tidy --out-dir ../out/Testing
With no filenames provided, all C/C++/Objective-C files will be checked. You can provide a list of files to be checked by passing the filenames after the options: npm run lint:clang-tidy --out-dir ../out/Testing shell/browser/api/electron_api_app.cc
While clang-tidy has a long list of possible checks, in Electron only a few are enabled by default. At the moment Electron doesn't have a .clang-tidy config, so clang-tidy will find the one from Chromium at src/.clang-tidy and use the checks which Chromium has enabled. You can change which checks are run by using the --checks= option. This is passed straight through to clang-tidy, so see its documentation for full details. Wildcards can be used, and checks can be disabled by prefixing a -. By default any checks listed are added to those in .clang-tidy, so if you'd like to limit the checks to specific ones you should first exclude all checks then add back what you want, like --checks=-*,performance*.
Running clang-tidy is rather slow - internally it compiles each file and then runs the checks so it will always be some factor slower than compilation. While you can use parallel runs to speed it up using the --jobs|-j option, clang-tidy also uses a lot of memory during its checks, so it can easily run into out-of-memory errors. As such the default number of jobs is one.
\n\nСоздает HTTP/HTTPS-запросы.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
ClientRequest реализует интерфейс Writable Stream и EventEmitter.
new ClientRequest(options)options (Object | String) - Если options является String, то она интепретируется как URL запроса. Если это объект, ожидается полное указание HTTP запроса через следующие свойства:method String (опционально) - Метод HTTP-запроса. По умолчанию метод GET.url String (опционально) - URL запроса. Необходимо предоставить в абсолютной форме с протокольной схемой, указанной как http или https.session Session (опционально) – экземпляр Session, с которым ассоциирован данный запрос.partition String (опционально) – название раздела, с которым ассоциирован данный запрос. По умолчанию является пустой строкой. The session option supersedes partition. Поэтому, если параметр session явно указан, то partition игнорируется.credentials String (опционально) - Может быть include или omit. Whether to send credentials with this request. If set to include, credentials from the session associated with the request will be used. If set to omit, credentials will not be sent with the request (and the 'login' event will not be triggered in the event of a 401). This matches the behavior of the fetch option of the same name. If this option is not specified, authentication data from the session will be sent, and cookies will not be sent (unless useSessionCookies is set).useSessionCookies Boolean (optional) - Whether to send cookies with this request from the provided session. If credentials is specified, this option has no effect. По умолчанию - false.protocol String (опционально) - Может быть http: или https:. The protocol scheme in the form 'scheme:'. По умолчанию 'http:'.host String (опционально) - объединенное с номером порта доменное имя сервера 'доменное_имя:порт'.hostname String (опционально) – доменное имя сервера.port Integer (опционально) – номер порта сервера.path String (опционально) - часть пути запроса URL.redirect String (необязательный) - Позиция иконки, может иметь значения follow, error или manual. The redirect mode for this request. When mode is error, any redirection will be aborted. When mode is manual the redirection will be cancelled unless request.followRedirect is invoked synchronously during the redirect event. По умолчанию - follow.origin String (optional) - The origin URL of the request.Свойства options, такие как protocol, host, hostname, port и path, строго следуют модели Node.js, которая описана в модуле URL.
Например, мы могли бы создать такой же запрос на 'github.com' следующим образом:
\nconst request = net.request({\n method: 'GET',\n protocol: 'https:',\n hostname: 'github.com',\n port: 443,\n path: '/'\n})\nВозвращает:
\nresponse IncomingMessage - Объект, представляющий ответ HTTP.Возвращает:
\nauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (опционально)password String (опционально)Происходит, когда прокси-сервер, выполняющий проверку подлинности, запрашивает учетные данные пользователя.
\nОжидается, что функция callback будет вызвана с учетными данными пользователя:
username Stringpassword Stringrequest.on('login', (authInfo, callback) => {\n callback('username', 'password')\n})\nПредоставление пустых учетных данных отменит запрос и сообщит об ошибке проверки подлинности в объекте ответа:
\nrequest.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`);\n response.on('error', (error) => {\n console.log(`ERROR: ${JSON.stringify(error)}`)\n })\n})\nrequest.on('login', (authInfo, callback) => {\n callback()\n})\nПроисходит сразу после того, как последняя часть данных запроса была записана в объект request.
Возникает при прерывании request. Событие abort не будет запущено, если request уже закрыт.
Возвращает:
\nerror Error - объект ошибки, содержащий некоторую информацию о неудаче.Происходит, когда модулю net не удается выполнить сетевой запрос. Обычно, когда объект request генерирует событие error, в последствии последует событие close и не будет представлен объект ответа.
Происходит как последнее событие в транзакции HTTP запроса-ответа. Событие close указывает, что больше события не будут происходить ни на request, ни на response объектах.
Возвращает:
\nstatusCode Integermethod StringredirectUrl StringresponseHeaders Record<String, String[]>Используется при возврате сервером перенаправленного ответа (например, 301 Перемещено навсегда). Вызов request.followRedirect продолжится с перенаправлением. Если событие обработано, request.followRedirect должен вызываться синхронно, в противном случае запрос будет отменен.
request.chunkedEncodingBoolean, определяющий, будет ли запрос использовать в HTTP шифрование передачи частей или нет. По умолчанию - false. Свойство доступно для чтения и записи, в любом случае оно может быть установлено только до первой операции записи, поскольку HTTP-заголовки еще не отправлены. Попытка установить свойство chunkedEncoding после первой записи вызовет ошибку.
Использование шифрование частей настоятельно рекомендуется, если Вам необходимо отправить большое содержимое запроса как данные, которые будут передаваться в потоке малыми частями вместо внутренней буферизации в памяти процесса Electron.
\nrequest.setHeader(name, value)name String - имя дополнительного HTTP-заголовка.value String - значение дополнительного HTTP-заголовка.Добавляет дополнительный HTTP-заголовок. Имя заголовка будет выдано как есть, без нижнего регистра. Может быть вызвано только перед первой записи. Вызов этого метода после первой записи вызовет ошибку. Если переданное значение это не String, тогда метод toString() будет вызван, чтобы получить конечное значение.
Certain headers are restricted from being set by apps. These headers are listed below. More information on restricted headers can be found in Chromium's header utils.
\nContent-LengthHostTrailer or TeUpgradeCookie2Keep-AliveTransfer-EncodingAdditionally, setting the Connection header to the value upgrade is also disallowed.
request.getHeader(name)name String - Specify an extra header name.Возвращает String - значение ранее установленного дополнительного заголовка.
request.removeHeader(name)name String - Specify an extra header name.Удаляет ранее установленное дополнительное имя заголовка. Этот метод может быть вызван только перед первой записью. Попытка вызвать его после первой записи приведет к ошибке.
\nrequest.write(chunk[, encoding][, callback])chunk (String | Buffer) - Часть данных в теле запроса. Если это строка, то она преобразуется в буфер в заданной кодировке.encoding String (опционально) - используется для конвертирования строковые части в объект Buffer. По умолчанию 'utf-8'.callback Function (опционально) - вызывается после того, как закончится операция записи.callback является по существу фиктивной функцией, представленной в целях сохранения схожести с API Node.JS. Вызывается асинхронно в следующем такте, после содержимое chunk будет отправлено в сетевой слой Chromium. В отличие от реализации Node.JS, не гарантировано, что содержимое chunk будет отправлено до вызова callback.
Добавляет часть данных в содержимое запроса. Первая операция записи может привести тому, что заголовки запроса будут отправлены. После первой операции записи, недопустимо добавлять или удалять пользовательские заголовки.
\nrequest.end([chunk][, encoding][, callback])chunk (String | Buffer) (опционально)encoding String (опционально)callback Function (опционально)Отправляет последний фрагмент данных запроса. Последующие операции по записи или завершению не будут разрешены. Событие finish происходит сразу после завершения операции.
request.abort()Отменяет текущую транзакцию HTTP. Если запрос уже сгенерировал событие close, операция прерывания не будет иметь эффекта. Иначе текущее событие будет генерировать события abort и close. Кроме того, если есть текущий объект ответа, будет сгенерировано событие aborted.
request.followRedirect()Continues any pending redirection. Can only be called during a 'redirect' event.
request.getUploadProgress()Возвращает Object:
active Boolean - Активен ли запрос в данный момент. Если это false, никакие другие свойства не будут установленыstarted Boolean - Началась ли загрузка. Если это false, то и current и total будут установлены в 0.current Integer - количество байтов, которые были загруженыtotal Integer - количество байтов, которые будут загружены в этом запросеВы можете использовать этот метод в сочетании с запросами POST, чтобы получить прогресс загрузки файла или другой передачи данных.
\n\nВыполняет копирование и вставку в буфер обмена системы.
\n
Процессы: Основной, Графический
\nВ Linux также есть selection буфер обмена. Для работы с ним необходимо передать selection каждому методу:
const { clipboard } = require('electron')\n\nclipboard.writeText('Пример строки', 'selection)\nconsole.log(clipboard.readText('selection'))\nМодуль clipboard имеет следующие методы:
Примечание: Экспериментальные API помечены и могут быть удалены в будущем.
\nclipboard.readText([type])type String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Возвращает String — содержимое буфера обмена в виде обычного текста.
const { clipboard } = require('electron')\n\nclipboard.writeText('hello i am a bit of text!')\n\nconst text = clipboard.readText()\nconsole.log(text)\n// hello i am a bit of text!'\nclipboard.writeText(text[, type])text Stringtype String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Записывает text в буфер обмена, как обычный текст.
const { clipboard } = require('electron')\n\nconst text = 'hello i am a bit of text!'\nclipboard.writeText(text)\nclipboard.readHTML([type])type String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Возвращает String - содержимое буфера обмена в виде разметки.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b>')\nconst html = clipboard.readHTML()\n\nconsole.log(html)\n// <meta charset='utf-8'><b>Hi</b>\nclipboard.writeHTML(markup[, type])markup Stringtype String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Записывает markup в буфер обмена.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b')\nclipboard.readImage([type])type String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Возвращает NativeImage - содержимое изображения в буфере обмена.
clipboard.writeImage(image[, type])image NativeImagetype String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Записывает image в буфер обмена.
clipboard.readRTF([type])type String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Возвращает String - содержимое в буфере обмена в виде RTF.
const { clipboard } = require('electron')\n\nclipboard.writeRTF('{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}')\n\nconst rtf = clipboard.readRTF()\nconsole.log(rtf)\n// {\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}\nclipboard.writeRTF(text[, type])text Stringtype String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Записывает text в буфер обмена как RTF.
const { clipboard } = require('electron')\n\nconst rtf = '{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}'\nclipboard.writeRTF(rtf)\nclipboard.readBookmark() macOS WindowsВозвращает Object:
title Stringurl StringВозвращает объект, содержащий ключи title и url, представляющие закладку в буфере обмена. Значения title и url будут пустыми строками, когда закладки недоступны.
clipboard.writeBookmark(title, url[, type]) macOS Windowstitle Stringurl Stringtype String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Записывает title и url в буфер обмена, как закладку.
Примечание: Большинство приложений на Windows не поддерживают вставку закладок в них, так что Вы можете использовать clipboard.write, чтобы записать как закладку, так и резервный текст в буфер обмена.
const { clipboard } = require('electron')\n\nclipboard.writeBookmark({\n text: 'https://electronjs.org',\n bookmark: 'Electron Homepage'\n})\nclipboard.readFindText() macOSВозвращает String - текст в панели поиска, который представляет собой информацию о текущем состоянии панели поиска активного приложения.
Этот метод использует синхронный IPC, когда вызывается в процессе рендеринга. Закэшированное значение перечитывается из буфера обмена, всякий раз, когда приложение активировано.
\nclipboard.writeFindText(text) macOStext StringЗаписывает text в панель поиска (панель, которая содержит информацию о текущем состоянии панели поиска активного приложения) в виде простого текста. Этот метод использует синхронный IPC, когда вызывается в процессе рендеринга.
clipboard.clear([type])type String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Очищает содержимое буфера обмена.
\nclipboard.availableFormats([type])type String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Возвращает String[] - массив поддерживаемых форматов для type буфера обмена.
const { clipboard } = require('electron')\n\nconst formats = clipboard.availableFormats()\nconsole.log(formats)\n// [ 'text/plain', 'text/html' ]\nclipboard.has(format[, type]) Экспериментальноformat Stringtype String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Возвращает Boolean - поддерживает ли буфер обмена указанный format.
const { clipboard } = require('electron')\n\nconst hasFormat = clipboard.has('<p>selection</p>')\nconsole.log(hasFormat)\n// 'true' or 'false'\nclipboard.read(format) Экспериментальноformat StringВозвращает String - читает тип format из буфера обмена.
format should contain valid ASCII characters and have / separator. a/c, a/bc are valid formats while /abc, abc/, a/, /a, a are not valid.
clipboard.readBuffer(format) Экспериментальноformat StringВозвращает Buffer - читает тип format из буфера обмена.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('this is binary', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\n\nconst ret = clipboard.readBuffer('public/utf8-plain-text')\n\nconsole.log(buffer.equals(out))\n// true\nclipboard.writeBuffer(format, buffer[, type]) Экспериментальноformat Stringbuffer Buffertype String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Записывает buffer в буфер обмена, как format.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('writeBuffer', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\nclipboard.write(data[, type])data Objecttext String (опционально)html String (опционально)image NativeImage (опционально)rtf String (опционально)bookmark String (опционально) - заголовок ссылки на text.type String (опционально) - Может быть selection или clipboard; по умолчанию 'clipboard'. selection доступен только в Linux.Записывает data в буфер обмена.
const { clipboard } = require('electron')\n\nclipboard.write({\n text: 'test',\n html: '<b>Hi</b>',\n rtf: '{\\\\rtf1\\\\utf8 text}',\n bookmark: 'a title'\n})\n\nconsole.log(clipboard.readText())\n// 'test'\n\nconsole.log(clipboard.readHTML())\n// <meta charset='utf-8'><b>Hi</b>\n\nconsole.log(clipboard.readRTF())\n// '{\\\\rtf1\\\\utf8 text}'\n\nconsole.log(clipboard.readBookmark())\n// { title: 'a title', url: 'test' }\nПодпись кода - это технология безопасности, которую вы используете для удостоверения того, что приложение было создано вами.
\nOn macOS the system can detect any change to the app, whether the change is introduced accidentally or by malicious code.
\nOn Windows, the system assigns a trust level to your code signing certificate which if you don't have, or if your trust level is low, will cause security dialogs to appear when users start using your application. Trust level builds over time so it's better to start code signing as early as possible.
\nМожно распространять неподписанные приложения, но не рекомендуется. Both Windows and macOS will, by default, prevent either the download or the execution of unsigned applications. Starting with macOS Catalina (version 10.15), users have to go through multiple manual steps to open unsigned applications.
\n
As you can see, users get two options: Move the app straight to the trash or cancel running it. You don't want your users to see that dialog.
\nIf you are building an Electron app that you intend to package and distribute, it should be code-signed.
\nProperly preparing macOS applications for release requires two steps: First, the app needs to be code-signed. Then, the app needs to be uploaded to Apple for a process called \"notarization\", where automated systems will further verify that your app isn't doing anything to endanger its users.
\nTo start the process, ensure that you fulfill the requirements for signing and notarizing your app:
\nElectron's ecosystem favors configuration and freedom, so there are multiple ways to get your application signed and notarized.
\nelectron-forgeIf you're using Electron's favorite build tool, getting your application signed and notarized requires a few additions to your configuration. Forge is a collection of the official Electron tools, using electron-packager, electron-osx-sign, and electron-notarize under the hood.
Let's take a look at an example configuration with all required fields. Not all of them are required: the tools will be clever enough to automatically find a suitable identity, for instance, but we recommend that you are explicit.
{\n \"name\": \"my-app\",\n \"version\": \"0.0.1\",\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"osxSign\": {\n \"identity\": \"Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)\",\n \"hardened-runtime\": true,\n \"entitlements\": \"entitlements.plist\",\n \"entitlements-inherit\": \"entitlements.plist\",\n \"signature-flags\": \"library\"\n },\n \"osxNotarize\": {\n \"appleId\": \"felix@felix.fun\",\n \"appleIdPassword\": \"my-apple-id-password\",\n }\n }\n }\n }\n}\nThe plist file referenced here needs the following macOS-specific entitlements to assure the Apple security mechanisms that your app is doing these things without meaning any harm:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nОбратите внимание, что до Electron 12 также требовалось право на com.apple.security.cs.allow-unsigned-executable-memory. Тем не менее, его больше не следует использовать, если есть возможность.
To see all of this in action, check out Electron Fiddle's source code, especially its electron-forge configuration file.
If you plan to access the microphone or camera within your app using Electron's APIs, you'll also need to add the following entitlements:
\n<key>com.apple.security.device.audio-input</key>\n<true/>\n<key>com.apple.security.device.camera</key>\n<true/>\nIf these are not present in your app's entitlements when you invoke, for example:
\nconst { systemPreferences } = require('electron')\n\nconst microphone = systemPreferences.askForMediaAccess('microphone')\nYour app may crash. See the Resource Access section in Hardened Runtime for more information and entitlements you may need.
\nelectron-builderElectron Builder comes with a custom solution for signing your application. You can find its documentation here.
\nelectron-packagerIf you're not using an integrated build pipeline like Forge or Builder, you are likely using electron-packager, which includes electron-osx-sign and electron-notarize.
Если вы используете API Packager, вы можете передать то, что подписывает и заверяет нотариально ваше приложение .
\nconst packager = require('electron-packager')\n\npackager({\n dir: '/path/to/my/app',\n osxSign: {\n identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',\n 'hardened-runtime': true,\n entitlements: 'entitlements.plist',\n 'entitlements-inherit': 'entitlements.plist',\n 'signature-flags': 'library'\n },\n osxNotarize: {\n appleId: 'felix@felix.fun',\n appleIdPassword: 'my-apple-id-password'\n }\n})\nThe plist file referenced here needs the following macOS-specific entitlements to assure the Apple security mechanisms that your app is doing these things without meaning any harm:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nВплоть до Electron 12 элемент com.apple.security.cs.allow-unsigned-executable-memory обязателен. Тем не менее, его больше не следует использовать, если есть возможность.
See the Mac App Store Guide.
\nПеред подписью, следует:
\nВы можете получить сертификат от множества продавцов, включая самых популярных. Цены варьируются, поэтому это может стоить вашего времени, чтобы ходить по магазинам. Популярные реселлеры включают:
\nСуществует ряд инструментов для подписывания приложений:
\nelectron-winstaller will generate an installer for windows and sign it for youelectron-forge can sign installers it generates through the Squirrel.Windows or MSI targets.electron-builder can sign some of its windows targetsСмотри страницу Windows Store Guide.
", "title": "Подписывание кода", "description": "" }, "/docs/development/coding-style": { "locale": "ru-RU", "slug": "coding-style", "href": "/docs/development/coding-style", "crowdinFileId": "256147", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/coding-style.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Это руководство по стилю кодирования для Electron.
\nВы пожете запустить npm run lint для того чтобы получить список проблемных мест по стилю кода, найденных с помощью cpplint и eslint.
path)ipc, app)@)path.join() для конкатенации имен файлов.os.tmpdir() вместо /tmp когда нужно сослаться на каталог для временных файлов.return when returning explicitly at the end of a function.return null, не return undefined, не null или undefinedДля C++ и Python мы следуем стилю кодирования Chromium. Для автоматического форматирования кода на C++ вы можете использовать clang-format. Есть также скрипт script/cpplint.py, позволяющий проверить, что все файлы соответствуют стилю.
Версией Python, которую мы используем в настоящее время, является Python 2.7.
\nКод C++ использует многожество абстракций и типов Chrome, поэтому рекомендуется ознакомиться с ними. Хорошее место чтобы начать это Important Abstractions and Data Structures из документации по Chromium. Документ упоминает некоторые специальные типы, областные типы (которые автоматически освобождают используемую ими память при выходе из области), механизмы логгирования и т. д.
\nВы можете выполнить команду npm run lint-docs чтобы убедиться, что ваши изменения документации корректно отформатированы.
- вместо _, например, file-name.js вместо file_name.js, поскольку имена в github/atom обычно пишутся в форме module-name. Это правило применяется только к .js-файлам.const для requires и прочих постоянных значений. Если значение примитивно, используйте имя в верхнем регистре (например, const NUMBER_OF_RETRIES = 5).let для определения переменныхfunction () { }+Electron APIs использует ту же схему капитализации, что и Node.js:
\nBrowserWindow, используйте PascalCase.globalShortcut, используйте camelCase.win.webContents, используйте mixedCase. Tag или Process Object.При создании новых API рекомендуется использовать getters и setters вместо одной функции для доступа в типичном для jQuery стиле. Например, .getText() и .setText(text) более предпочтительны, чем .text([text]). См. обсуждение этой темы здесь.
\n\nМанипулирование аргументами командной строки для вашего приложения, которое читает Chromium
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
В следующем примере показано, как проверить, установлен ли флаг --disable-gpu.
const { app } = require('electron')\napp.commandLine.hasSwitch('disable-gpu')\nДля получения более подробной информации о том, какие флаги и переключатели можно использовать, смотрите переключатели командной строки.
\ncommandLine.appendSwitch(switch[, value])switch String - переключатель командной строки, без ведущего --value String (опиционально) - значение для данного переключателяДобавьте переключатель (с опциональным значением value) Chromium в командной строке.
Примечание: Это не повлияет на process.argv. Предполагаемое использование этой функции — управлять поведением Chromium.
commandLine.appendArgument(value)value String - аргумент для добавления в командную строкуДобавляет аргумент в командную строку Chromium. Аргумент будет указан правильно. Переключатели будут предшествовать аргументам независимо от порядка добавления.
\nЕсли Вы добавляете аргумент, такой как --switch=value, вместо этого рассмотрите использование appendSwitch('switch', 'value').
Примечание: Это не повлияет на process.argv. Предполагаемое использование этой функции — управлять поведением Chromium.
commandLine.hasSwitch(switch)switch String - переключатель командной строкиВозвращает Boolean - есть или нет переключатель командной строки.
commandLine.getSwitchValue(switch)switch String - переключатель командной строкиВозвращает String - значение переключателя командной строки.
Примечание: Когда переключатель не присутствует или не имеет значения, возвращает пустую строку.
", "title": "CommandLine", "description": "Манипулирование аргументами командной строки для вашего приложения, которое читает Chromium" }, "/docs/api/command-line-switches": { "locale": "ru-RU", "slug": "command-line-switches", "href": "/docs/api/command-line-switches", "crowdinFileId": "256293", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/command-line-switches.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nПараметры командной строки поддерживаемые Electron.
\n
Вы можете использовать app.commandLine.appendSwitch, для добавления параметров командной строки, в основном скрипте Вашего приложения, перед тем как произойдет событие ready модуля app:
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('remote-debugging-port', '8315')\napp.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')\n\napp.whenReady().then(() => {\n // Your code here\n})\nссылкаСписок серверов (разделенные запятой), для которых разрешена интегрированная аутентификация.
\nНапример:
\n--auth-server-whitelist='*example.com, *foobar.com, *baz'\nтогда любая ссылка заканчивающаяся на example.com, foobar.com и baz будут рассматриваться для интегрированной аутентификации. Без префикса *, ссылка будет полностью соответствовать.
ссылкаA comma-separated list of servers for which delegation of user credentials is required. Без префикса *, ссылка будет полностью соответствовать.
Disables NTLM v2 for posix platforms, no effect elsewhere.
\nОтключить кэширование на жёсткий диск для HTTP запросов.
\nОтключить HTTP/2 и SPDY/3.1 протоколы.
\nПредотвращает Chromium от понижения приоритета для невидимых страниц графических процессов.
\nЭтот параметр глобален для всех графических процессов, если Вы хотите отключить троттлинг в одном окне, Вы может использовать трюк с проигрыванием беззвучных звуков.
\nразмерМаксимальный размер кеша на жёстком диске в байтах.
\nEnables caller stack logging for the following APIs (filtering events):
\ndesktopCapturer.getSources() / desktop-capturer-get-sourcesPrints Chromium's logging to stderr (or a log file).
\nThe ELECTRON_ENABLE_LOGGING environment variable has the same effect as passing --enable-logging.
Passing --enable-logging will result in logs being printed on stderr. Passing --enable-logging=file will result in logs being saved to the file specified by --log-file=..., or to electron_debug.log in the user-data directory if --log-file is not specified.
\n\nNote: On Windows, logs from child processes cannot be sent to stderr. Logging to a file is the most reliable way to collect logs on Windows.
\n
See also --log-file, --log-level, --v, and --vmodule.
trialsField trials to be forcefully enabled or disabled.
\nFor example: WebRTC-Audio-Red-For-Opus/Enabled/
правилаСписок правил, разделённых точкой с запятой, которые контролируют как сопоставляются имена хостов.
Например:
\nMAP * 127.0.0.1 Все имена хостов будут перенаправлены на 127.0.0.1MAP *.google.com proxy Заставляет все поддомены google.com обращаться к \"proxy\".MAP test.com [::1]:77 Forces \"test.com\" to resolve to IPv6 loopback. Также принудительно выставит порт получаемого адреса сокета, равный 77.MAP * baz, EXCLUDE www.google.com Перенаправляет всё на \"baz\", за исключением \"www.google.com\".Эти перенаправления применяются к хосту конечной точки в сетевом запросе (TCP соединения и резолвер хоста в прямых соединениях, CONNECT в HTTP прокси-соединениях и хост конечной точки в SOCKS прокси-соединений).
правилаКак --host-rules, но эти правила применяются только к резолверу хоста.
Игнорировать ошибки, связанные с сертификатами.
\nдоменыИгнорировать лимит подключения для списка доменов, разделённых ,.
флагиSpecifies the flags passed to the Node.js engine. Если вы хотите включить flags в главном процессе, то он должен быть передан при запуске Electron.
$ electron --js-flags=\"--harmony_proxies --harmony_collections\" your-app\nСмотрите документацию Node.js или запустите node --help в командной строке для списка доступных флагов. Дополнительно, запустите node --v8-options для просмотра списка флагов, которые касаются JavaScript движка V8 в Node.js.
Установить пользовательский язык.
\npathIf --enable-logging is specified, logs will be written to the given path. The parent directory must exist.
Setting the ELECTRON_LOG_FILE environment variable is equivalent to passing this flag. If both are present, the command-line switch takes precedence.
путьВключает логи сетевых событий для сохранения и записывает их в путь.
NSets the verbosity of logging when used together with --enable-logging. N should be one of Chrome's LogSeverities.
Note that two complimentary logging mechanisms in Chromium -- LOG() and VLOG() -- are controlled by different switches. --log-level controls LOG() messages, while --v and --vmodule control VLOG() messages. So you may want to use a combination of these three switches depending on the granularity you want and what logging calls are made by the code you're trying to watch.
See Chromium Logging source for more information on how LOG() and VLOG() interact. Loosely speaking, VLOG() can be thought of as sub-levels / per-module levels inside LOG(INFO) to control the firehose of LOG(INFO) data.
See also --enable-logging, --log-level, --v, and --vmodule.
Не использовать прокси сервер и всегда делать прямые соединения. Переопределяет все остальные флаги прокси-сервера, которые были указаны.
\nDisables the Chromium sandbox. Forces renderer process and Chromium helper processes to run un-sandboxed. Should only be used for testing.
\nхостыУказывает Electron обходить прокси-сервер для списка хостов, разделённых точкой с запятой. Этот флаг действует только в том случае, если он используется вместе с --proxy-server.
Например:
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')\nБудет использовать прокси сервер для всех хостов, за исключением локальных адресов (localhost, 127.0.0.1 и т. д.), google.com поддоменов, хостов которые содержат foo.com и 1.2.3.4:5678.
ссылкаИспользовать PAC скрипт для указанного url.
адрес:портИспользует указанный proxy сервер, который перезаписывает системные настройки. Этот параметр влияет только на запросы HTTP протокола, включая HTTPS и WebSocket. Примечательно также, что не все proxy серверы поддерживают HTTPS и WebSocket протоколы. В URL для прокси не поддерживается указание имени пользователя и пароля для аутентификации, из-за проблемы в Chromium.
\nпортВключает удалённую отладку через HTTP для указанного порта.
уровень_логированияGives the default maximal active V-logging level; 0 is the default. Normally positive values are used for V-logging levels.
\nЭтот параметр работает только когда --enable-logging также указан.
See also --enable-logging, --log-level, and --vmodule.
шаблонДает на каждый модуль максимальный уровень V-логирования, чтобы переопределить значения, заданное --v. Например, my_module=2,foo*=3 would change the logging level for all code in source files my_module.* and foo*.*.
Любой шаблон, содержащий переднюю или обратную косую черту, будет протестирован против всего пути, а не только модуля. Например, */foo/bar/*=2 would change the logging level for all code in the source files under a foo/bar directory.
Этот параметр работает только когда --enable-logging также указан.
See also --enable-logging, --log-level, and --v.
Force using discrete GPU when there are multiple GPUs available.
\nForce using integrated GPU when there are multiple GPUs available.
\nElectron поддерживает некоторые из флагов CLI, поддерживаемых Node.js.
\nNote: Passing unsupported command line switches to Electron when it is not running in ELECTRON_RUN_AS_NODE will have no effect.
Activate inspector on host:port and break at start of user script. Default host:port is 127.0.0.1:9229.
\nAliased to --debug-brk=[host:]port.
Set the host:port to be used when the inspector is activated. Useful when activating the inspector by sending the SIGUSR1 signal. Default host is 127.0.0.1.
Aliased to --debug-port=[host:]port.
Activate inspector on host:port. По умолчанию - 127.0.0.1:9229.
V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug and profile Electron instances. The tools attach to Electron instances via a TCP port and communicate using the Chrome DevTools Protocol.
\nСмотрите Руководство по отладке главного процесса для получения более подробной информации.
\nAliased to --debug[=[host:]port.
Specify ways of the inspector web socket url exposure.
\nBy default inspector websocket url is available in stderr and under /json/list endpoint on http://host:port/json/list.
", "title": "Поддерживаемые параметры командной строки", "description": "Параметры командной строки поддерживаемые Electron." }, "/docs/api/content-tracing": { "locale": "ru-RU", "slug": "content-tracing", "href": "/docs/api/content-tracing", "crowdinFileId": "256297", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/content-tracing.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nСобирает данные трассировки из содержимого модуля Chromium для поиска узких мест производительности и медленных операций.
\n
Процесс: Основной
\nЭтот модуль не содержит веб-интерфейса. Для просмотра записанных треков, используйте trace viewer, доступного по адресу chrome://tracing в Chrome.
Примечание: Вам не следует использовать данный модуль до тех пор, пока событие ready модуля app не произошло.
const { app, contentTracing } = require('electron')\n\napp.whenReady().then(() => {\n (async () => {\n await contentTracing.startRecording({\n included_categories: ['*']\n })\n console.log('Tracing started')\n await new Promise(resolve => setTimeout(resolve, 5000))\n const path = await contentTracing.stopRecording()\n console.log('Tracing data recorded to ' + path)\n })()\n})\nМодуль contentTracing имеет следующие методы:
contentTracing.getCategories()Возвращает Promise<String[]> - возвращает массив групп категорий, как только все дочерние процессы признают запрос getCategories
Получить набор групп категорий. Группы категорий могут меняться при достижении новых путей кода. Смотрите также список встроенных категорий трассировки.
\n\n\nNOTE: Electron adds a non-default tracing category called
\n\"electron\". This category can be used to capture Electron-specific tracing events.
contentTracing.startRecording(options)options (TraceConfig | TraceCategoriesAndOptions)Возвращает Promise<void> - возвращается, как только все дочерние процессы признают запрос startRecording.
Начинает запись во всех процессах.
\nЗапись начинается незамедлительно локально и ассинхронно в дочерних процессах, как только они получили запрос EnableRecording.
\nЕсли запись уже запущена, promise будет немедленно разрешен, поскольку одновременно может выполняться только одна операция трассировки.
\ncontentTracing.stopRecording([resultFilePath])resultFilePath String (опционально)Возвращает Promise<String> - возвращает путь к файлу, который содержит данные трассировки, как только все дочерние процессы признают запрос stopRecording
Останавливает запись во всех процессах.
\nДочерние процессы кэшируют данные трассировки и только изредка очищают и отправляют эти данные обратно в главный процесс. Это помогает свести к минимуму издержки трассировки, так как отправка данных трассировки через IPC может быть дорогостоящей операцией. Поэтому, чтобы окончить Chromium ассинхронно запрашивает все дочерние процессы, чтобы очистить оставшиеся данные трассировки.
\nДанные трассировки будут записаны в resultFilePath. Если resultFilePath является пустым или не указано, Данные трассировки будут записаны во временный файл, и путь будет возвращен в promise.
contentTracing.getTraceBufferUsage()Возвращает Promise <Object> - разрешается с объектом, содержащим value и percentage максимального использования буфера трассировки
value Numberpercentage NumberМаксимальное использование в различных процессах буфера трассировки в процентах от полного состояния.
", "title": "contentTracing", "description": "Собирает данные трассировки из содержимого модуля Chromium для поиска узких мест производительности и медленных операций." }, "/docs/api/context-bridge": { "locale": "ru-RU", "slug": "context-bridge", "href": "/docs/api/context-bridge", "crowdinFileId": "256299", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/context-bridge.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nСоздает безопасный, двунаправленный, синхронный мост через изолированные контексты
\n
Процесс: Графический
\nПример предоставления API-интерфейса средству визуализации из изолированного сценария предварительной загрузки приведен ниже:
\n// Предварительная загрузка (Isolated World/Изолированный Мир)\nconst { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing')\n }\n)\n// Рендер (Main World/Основной Мир)\n\nwindow.electron.doThing()\n\"Main World\" - это контекст javascript, в котором запускается ваш основной код рендера. По умолчанию загружаемая вами страница выполняет код в этом контексте.
\nКогда contextIsolation включен в вашем webPreferences (Это стандартное поведение в Electron 12.0.0) ваши preload скрипты выполняются в \"Isolated World\". Вы можете прочитать больше о контекстной изоляции и на что это влияет в документации BrowserWindow.
Модуль contextBridge имеет следующие методы:
contextBridge.exposeInMainWorld(apiKey, api)apiKey String - Ключ для вставки API в window. API будет доступен в window[apiKey].api Record - Ваш объект API, более подробная информация о том, что это и как он будет работать, доступна ниже.Объект api, предоставленный для exposeInMainWorld, должен быть объектом, ключи которого являются строками, а значения являются Function, String, Number, Array, Boolean или другой вложенный объект, удовлетворяющий тем же условиям.
Значения Function передаются в другой контекст, а все остальные значения копируются и заморожены. То есть Любые данные / примитивы, отправленные в объекте API, становятся неизменяемыми, и обновления на любой стороне моста не приводят к обновлению на другой стороне.
Пример сложного объекта API показан ниже:
\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing'),\n myPromises: [Promise.resolve(), Promise.reject(new Error('whoops'))],\n anAsyncFunction: async () => 123,\n data: {\n myFlags: ['a', 'b', 'c'],\n bootTime: 1234\n },\n nestedAPI: {\n evenDeeper: {\n youCanDoThisAsMuchAsYouWant: {\n fn: () => ({\n returnData: 123\n })\n }\n }\n }\n }\n)\nЗначения Function, которые вы связываете через contextBridge, передаются через Electron, чтобы гарантировать, что контексты остаются изолированными. Это приводит к некоторым ключевым ограничениям, которые мы описали ниже.
Поскольку параметры, ошибки и возвращаемые значения скопированы при отправке через мост, существуют только определенные типы, которые могут быть использованы. На высоком уровне, если тип, который вы хотите использовать, может быть сериализован и десериализован в один и тот же объект, то он будет работать. A table of type support has been included below for completeness:
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Тип | Сложность | Поддержка параметров | Возврат значения поддержки | Ограничения |
|---|---|---|---|---|
String | Простой | ✅ | ✅ | Нет |
Number | Простой | ✅ | ✅ | Нет |
Boolean | Простой | ✅ | ✅ | Нет |
Object | Сложный | ✅ | ✅ | Ключи должны поддерживаться «Простыми» типами в этой таблице. Значения должны поддерживаться в этой таблице. Модификации прототипа отбрасываются. Отправка пользовательских классов будет копировать значения, но не прототип. |
Array | Сложный | ✅ | ✅ | Те же ограничения, что и в типе Object |
Error | Сложный | ✅ | ✅ | Ошибки, которые выбрасываются также копируются, это может привести к тому, что сообщение и трассировка стека ошибки немного изменятся из-за того, что они будут выброшены в другом контексте |
Promise | Сложный | ✅ | ✅ | Промисы передаются только если они являются возвращаемым значением или точным параметром. Промисы, вложенные в массивы или объекты, будут удалены. |
Function | Сложный | ✅ | ✅ | Модификации прототипа отбрасываются. Отправка классов или конструкторов не будет работать. |
| Cloneable Types | Простой | ✅ | ✅ | Смотрите связанный документ по клонируемым типам |
Element | Сложный | ✅ | ✅ | Модификации прототипа отбрасываются. Отправка пользовательских элементов не будет работать. |
Blob | Сложный | ✅ | ✅ | Нет |
Symbol | Нет | ❌ | ❌ | Символы не могут быть скопированы в разных контекстах, поэтому они отбрасываются |
Если тип, о котором вы хотите использовать, не находится в приведенной выше таблице, то он, вероятно, не поддерживается.
\ncontextBridge может использоваться скриптом preload для предоставления вашему устройству доступа к узлам API. Таблица поддерживаемых типов, описанная выше, также применяется к Node API, которые вы используете через contextBridge. Пожалуйста, обратите внимание, что многие Node API предоставляют доступ к локальным системным ресурсам. Будьте очень осторожны относительно того, какие глобальные переменные и API вы предоставляете в ненадежном удаленном контенте.
const { contextBridge } = require('electron')\nconst crypto = require('crypto')\ncontextBridge.exposeInMainWorld('nodeCrypto', {\n sha256sum (data) {\n const hash = crypto.createHash('sha256')\n hash.update(data)\n return hash.digest('hex')\n }\n})\nContext Isolation is a feature that ensures that both your preload scripts and Electron's internal logic run in a separate context to the website you load in a webContents. This is important for security purposes as it helps prevent the website from accessing Electron internals or the powerful APIs your preload script has access to.
This means that the window object that your preload script has access to is actually a different object than the website would have access to. For example, if you set window.hello = 'wave' in your preload script and context isolation is enabled, window.hello will be undefined if the website tries to access it.
Context isolation has been enabled by default since Electron 12, and it is a recommended security setting for all applications.
\n\n\nWithout context isolation, I used to provide APIs from my preload script using
\nwindow.X = apiObject. Now what?
Exposing APIs from your preload script to a loaded website in the renderer process is a common use-case. With context isolation disabled, your preload script would share a common global window object with the renderer. You could then attach arbitrary properties to a preload script:
// preload with contextIsolation disabled\nwindow.myAPI = {\n doAThing: () => {}\n}\nThe doAThing() function could then be used directly in the renderer process:
// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nThere is a dedicated module in Electron to help you do this in a painless way. The contextBridge module can be used to safely expose APIs from your preload script's isolated context to the context the website is running in. The API will also be accessible from the website on window.myAPI just like it was before.
// preload with contextIsolation enabled\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n doAThing: () => {}\n})\n// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nPlease read the contextBridge documentation linked above to fully understand its limitations. For instance, you can't send custom prototypes or symbols over the bridge.
Just enabling contextIsolation and using contextBridge does not automatically mean that everything you do is safe. For instance, this code is unsafe.
// ❌ Bad code\ncontextBridge.exposeInMainWorld('myAPI', {\n send: ipcRenderer.send\n})\nIt directly exposes a powerful API without any kind of argument filtering. This would allow any website to send arbitrary IPC messages, which you do not want to be possible. The correct way to expose IPC-based APIs would instead be to provide one method per IPC message.
\n// ✅ Good code\ncontextBridge.exposeInMainWorld('myAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nIf you're building your Electron app with TypeScript, you'll want to add types to your APIs exposed over the context bridge. The renderer's window object won't have the correct typings unless you extend the types with a declaration file.
For example, given this preload.ts script:
contextBridge.exposeInMainWorld('electronAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nYou can create a renderer.d.ts declaration file and globally augment the Window interface:
export interface IElectronAPI {\n loadPreferences: () => Promise<void>,\n}\n\ndeclare global {\n interface Window {\n electronAPI: IElectronAPI\n }\n}\nDoing so will ensure that the TypeScript compiler will know about the electronAPI property on your global window object when writing scripts in your renderer process:
window.electronAPI.loadPreferences()\nname String - The name of the cookie.value String - The value of the cookie.domain String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains.hostOnly Boolean (optional) - Whether the cookie is a host-only cookie; this will only be true if no domain was passed.path String (optional) - The path of the cookie.secure Boolean (optional) - Whether the cookie is marked as secure.httpOnly Boolean (optional) - Whether the cookie is marked as HTTP only.session Boolean (optional) - Whether the cookie is a session cookie or a persistent cookie with an expiration date.expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.sameSite String - The Same Site policy applied to this cookie. Can be unspecified, no_restriction, lax or strict.\n\nЗапрашивайте и изменяйте cookie.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Экземпляры класса Cookies доступны через свойство cookies объекта Session.
Например:
\nconst { session } = require('electron')\n\n// Запрос всех cookies.\nsession.defaultSession.cookies.get({})\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// Запрос всех cookies, связанных с определенным Url.\nsession.defaultSession.cookies.get({ url: 'http://www.github.com' })\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// Установить cookie с данными объекта cookie;\n// перезаписывает эквивалентные cookie, если такие есть.\nconst cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }\nsession.defaultSession.cookies.set(cookie)\n .then(() => {\n // success\n }, (error) => {\n console.error(error)\n })\nДля экземпляров Cookies доступны следующие события:
Возвращает:
\neventcookie Cookie - Cookie, который был изменен.cause String - The cause of the change with one of the following values:explic - Cookie был изменен непосредственно действием потребителя.overwrite - Cookie был автоматически удален из-за операции вставки, которая перезаписала его.expired - Cookie был автоматически удален по истечении срока его действия.evicted - Cookie был автоматически исключен во время сбора мусора.expired-overwrite - Cookie был перезаписан с уже истекшим сроком действия.removed Boolean - true если cookie был удален, в противном случае false.Возникает при изменении cookie, так как она была добавлена, изменена, удалена или истекла.
\nВ экземпляре Cookies доступны следующие методы:
cookies.get(filter)filterurl String (optional) - Retrieves cookies which are associated with url. Empty implies retrieving cookies of all URLs.name String (опционально) - Фильтрует cookies по имени.domain String (опционально) - Изменяет cookies, чьи домены совпадают или являются поддоменами domains.path String (опционально) - Извлекает cookies чей путь совпадает с path.secure Boolean (опционально) - Фильтрует cookies по их защищенному свойству.session Boolean (опционально) - Отфильтровывает сеансовые или постоянные файлы cookie.Возвращает Promise<Cookie[]> - промисы, которые разрешают массив Cookie объектов.
Отправляет запрос на получение всех cookies, соответствующих filter, и выдает promise с ответом.
cookies.set(details)detailsurl String - The URL to associate the cookie with. The promise will be rejected if the URL is invalid.name String (optional) - The name of the cookie. Empty by default if omitted.value String (optional) - The value of the cookie. Empty by default if omitted.domain String (опционально) - домен cookie; это будет нормализовано с предыдущей точкой, чтобы он также был действителен для поддоменов. Empty by default if omitted.path String (опционально) - Путь к cookie. Empty by default if omitted.secure Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to false unless Same Site=None attribute is used.httpOnly Boolean (optional) - Whether the cookie should be marked as HTTP only. По умолчанию - false.expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted then the cookie becomes a session cookie and will not be retained between sessions.sameSite String (optional) - The Same Site policy to apply to this cookie. Может быть unspecified, no_restriction, lax или strict. По умолчанию - no_restriction.Возвращает Promise<void> - Promise, которое разрешается после установки файла cookie
Устанавливает cookie с details.
cookies.remove(url, name)url String - URL-дарес, связанный с cookie.name String - Название cookie для удаления.Возвращает Promise<void> - Promise, которое разрешается после удаления файла cookie
Удаляет cookies, соответствующие url и name
cookies.flushStore()Возвращает Promise<void> - Promise, которое разрешается, когда хранилище cookie было очищено
Записывает непрочитанные cookies на диск.
", "title": "Cookies", "description": "Запрашивайте и изменяйте cookie." }, "/docs/api/structures/cpu-usage": { "locale": "ru-RU", "slug": "cpu-usage", "href": "/docs/api/structures/cpu-usage", "crowdinFileId": "256419", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/cpu-usage.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "percentCPUUsage Number - Percentage of CPU used since the last call to getCPUUsage. First call returns 0.idleWakeupsPerSecond Number - The number of average idle CPU wakeups per second since the last call to getCPUUsage. First call returns 0. Will always return 0 on Windows.date Dateid String\n\nОтправляйте отчёты об ошибках на удалённый сервер.
\n
Процессы: Основной, Графический
\nThe following is an example of setting up Electron to automatically submit crash reports to a remote server:
\nconst { crashReporter } = require('electron')\n\ncrashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })\nЧтобы настроить сервер для приёма и обработки отчётов об ошибках, вы можете использовать эти проекты:
\n\nИли используйте стороннее решение:
\n\nCrash reports are stored temporarily before being uploaded in a directory underneath the app's user data directory (called 'Crashpad' on Windows and Mac, or 'Crash Reports' on Linux). You can override this directory by calling app.setPath('crashDumps', '/path/to/crashes') before starting the crash reporter.
On Windows and macOS, Electron uses crashpad to monitor and report crashes. On Linux, Electron uses breakpad. This is an implementation detail driven by Chromium, and it may change in future. In particular, crashpad is newer and will likely eventually replace breakpad on all platforms.
\nIf you are using the Node.js child_process module and want to report crashes from those processes on Linux, there is an extra step you will need to take to properly initialize the crash reporter in the child process. This is not necessary on Mac or Windows, as those platforms use Crashpad, which automatically monitors child processes.
Since require('electron') is not available in Node child processes, the following APIs are available on the process object in Node child processes. Note that, on Linux, each Node child process has its own separate instance of the breakpad crash reporter. This is dissimilar to renderer child processes, which have a \"stub\" breakpad reporter which returns information to the main process for reporting.
process.crashReporter.start(options)process.crashReporter.getParameters()See crashReporter.getParameters().
process.crashReporter.addExtraParameter(key, value)See crashReporter.addExtraParameter(key, value).
process.crashReporter.removeExtraParameter(key)See crashReporter.removeExtraParameter(key).
Модуль crashReporter имеет следующие методы:
crashReporter.start(options)options ObjectsubmitURL String (optional) - URL that crash reports will be sent to as POST. Required unless uploadToServer is false.productName String (опционально) - Значение по умолчанию - app.name.companyName String (optional) Deprecated - Deprecated alias for { globalExtra: { _companyName: ... } }.uploadToServer Boolean (optional) - Whether crash reports should be sent to the server. If false, crash reports will be collected and stored in the crashes directory, but not uploaded. По умолчанию - true.ignoreSystemCrashHandler Boolean (optional) - If true, crashes generated in the main process will not be forwarded to the system crash handler. По умолчанию - false.rateLimit Boolean (optional) macOS Windows - If true, limit the number of crashes uploaded to 1/hour. По умолчанию - false.compress Boolean (optional) - If true, crash reports will be compressed and uploaded with Content-Encoding: gzip. По умолчанию - true.extra Record<String, String> (optional) - Extra string key/value annotations that will be sent along with crash reports that are generated in the main process. Only string values are supported. Crashes generated in child processes will not contain these extra parameters to crash reports generated from child processes, call addExtraParameter from the child process.globalExtra Record<String, String> (optional) - Extra string key/value annotations that will be sent along with any crash reports generated in any process. These annotations cannot be changed once the crash reporter has been started. If a key is present in both the global extra parameters and the process-specific extra parameters, then the global one will take precedence. By default, productName and the app version are included, as well as the Electron version.This method must be called before using any other crashReporter APIs. Once initialized this way, the crashpad handler collects crashes from all subsequently created processes. The crash reporter cannot be disabled once started.
This method should be called as early as possible in app startup, preferably before app.on('ready'). If the crash reporter is not initialized at the time a renderer process is created, then that renderer process will not be monitored by the crash reporter.
Note: You can test out the crash reporter by generating a crash using process.crash().
Note: If you need to send additional/updated extra parameters after your first call start you can call addExtraParameter.
Note: Parameters passed in extra, globalExtra or set with addExtraParameter have limits on the length of the keys and values. Key names must be at most 39 bytes long, and values must be no longer than 127 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated.
Note: This method is only available in the main process.
\ncrashReporter.getLastCrashReport()Returns CrashReport - The date and ID of the last crash report. Only crash reports that have been uploaded will be returned; even if a crash report is present on disk it will not be returned until it is uploaded. Если нет загруженных отчетов, возвращается null.
Note: This method is only available in the main process.
\ncrashReporter.getUploadedReports()Возвращает CrashReport[]:
Returns all uploaded crash reports. Each report contains the date and uploaded ID.
\nNote: This method is only available in the main process.
\ncrashReporter.getUploadToServer()Returns Boolean - Whether reports should be submitted to the server. Set through the start method or setUploadToServer.
Note: This method is only available in the main process.
\ncrashReporter.setUploadToServer(uploadToServer)uploadToServer Boolean - Whether reports should be submitted to the server.This would normally be controlled by user preferences. This has no effect if called before start is called.
Note: This method is only available in the main process.
\ncrashReporter.addExtraParameter(key, value)key String - Parameter key, must be no longer than 39 bytes.value String - Parameter value, must be no longer than 127 bytes.Установите дополнительный параметр, который будет отправлен с отчетом о сбое. The values specified here will be sent in addition to any values set via the extra option when start was called.
Parameters added in this fashion (or via the extra parameter to crashReporter.start) are specific to the calling process. Adding extra parameters in the main process will not cause those parameters to be sent along with crashes from renderer or other child processes. Similarly, adding extra parameters in a renderer process will not result in those parameters being sent with crashes that occur in other renderer processes or in the main process.
Note: Parameters have limits on the length of the keys and values. Key names must be no longer than 39 bytes, and values must be no longer than 20320 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated.
\nNote: On linux values that are longer than 127 bytes will be chunked into multiple keys, each 127 bytes in length. Например, addExtraParameter('foo', 'a'.repeat(130)) will result in two chunked keys foo__1 and foo__2, the first will contain the first 127 bytes and the second will contain the remaining 3 bytes. On your crash reporting backend you should stitch together keys in this format.
crashReporter.removeExtraParameter(key)key String - Parameter key, must be no longer than 39 bytes.Remove an extra parameter from the current set of parameters. Future crashes will not include this parameter.
\ncrashReporter.getParameters()Returns Record<String, String> - The current 'extra' parameters of the crash reporter.
Процесс отчетов о сбоях отправит следующие данные в submitURL как multipart/form-data POST:
ver String - Версия Electron.platform String - например, 'win32'.process_type String - например, 'renderer'.guid String - например, '5e1286fc-da97-479e-918b-6bfb0c3d1c72'._version String - Версия в package.json._productName String - Имя продукта в crashReporter options объекте.prod String - Name of the underlying product. In this case Electron._companyName String - Имя компании в crashReporter options объекте.upload_file_minidump File - Отчет о сбое в формате minidump.extra в объекте crashReporter options.scheme String - Custom schemes to be registered with options.privileges Object (optional)standard Boolean (optional) - Default false.secure Boolean (optional) - Default false.bypassCSP Boolean (optional) - Default false.allowServiceWorkers Boolean (optional) - Default false.supportFetchAPI Boolean (optional) - Default false.corsEnabled Boolean (optional) - Default false.stream Boolean (optional) - Default false.\"Native interfaces\" include the file picker, window border, dialogs, context menus, and more - anything where the UI comes from your operating system and not from your app. The default behavior is to opt into this automatic theming from the OS.
\nIf your app has its own dark mode, you should toggle it on and off in sync with the system's dark mode setting. You can do this by using the [prefer-color-scheme] CSS media query.
\nIf you want to manually switch between light/dark modes, you can do this by setting the desired mode in the themeSource property of the nativeTheme module. This property's value will be propagated to your Renderer process. Any CSS rules related to prefers-color-scheme will be updated accordingly.
В macOS 10.14 Mojave, Apple представила новый системный темный режим для всех компьютеров macOS. If your Electron app has a dark mode, you can make it follow the system-wide dark mode setting using the nativeTheme api.
In macOS 10.15 Catalina, Apple introduced a new \"automatic\" dark mode option for all macOS computers. In order for the nativeTheme.shouldUseDarkColors and Tray APIs to work correctly in this mode on Catalina, you need to use Electron >=7.0.0, or set NSRequiresAquaSystemAppearance to false in your Info.plist file for older versions. Both Electron Packager and Electron Forge have a darwinDarkModeSupport option to automate the Info.plist changes during app build time.
If you wish to opt-out while using Electron > 8.0.0, you must set the NSRequiresAquaSystemAppearance key in the Info.plist file to true. Please note that Electron 8.0.0 and above will not let you opt-out of this theming, due to the use of the macOS 10.14 SDK.
This example demonstrates an Electron application that derives its theme colors from the nativeTheme. Additionally, it provides theme toggle and reset controls using IPC channels.
Starting with the index.html file:
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n <link rel=\"stylesheet\" type=\"text/css\" href=\"./styles.css\">\n</head>\n<body>\n <h1>Hello World!</h1>\n <p>Current theme source: <strong id=\"theme-source\">System</strong></p>\n\n <button id=\"toggle-dark-mode\">Toggle Dark Mode</button>\n <button id=\"reset-to-system\">Reset to System Theme</button>\n\n <script src=\"renderer.js\"></script>\n </body>\n</body>\n</html>\nИ файл styles.css:
@media (prefers-color-scheme: dark) {\n body { background: #333; color: white; }\n}\n\n@media (prefers-color-scheme: light) {\n body { background: #ddd; color: black; }\n}\nThe example renders an HTML page with a couple elements. The <strong id=\"theme-source\"> element shows which theme is currently selected, and the two <button> elements are the controls. The CSS file uses the prefers-color-scheme media query to set the <body> element background and text colors.
The preload.js script adds a new API to the window object called darkMode. This API exposes two IPC channels to the renderer process, 'dark-mode:toggle' and 'dark-mode:system'. It also assigns two methods, toggle and system, which pass messages from the renderer to the main process.
const { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld('darkMode', {\n toggle: () => ipcRenderer.invoke('dark-mode:toggle'),\n system: () => ipcRenderer.invoke('dark-mode:system')\n})\nNow the renderer process can communicate with the main process securely and perform the necessary mutations to the nativeTheme object.
The renderer.js file is responsible for controlling the <button> functionality.
document.getElementById('toggle-dark-mode').addEventListener('click', async () => {\n const isDarkMode = await window.darkMode.toggle()\n document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'\n})\n\ndocument.getElementById('reset-to-system').addEventListener('click', async () => {\n await window.darkMode.system()\n document.getElementById('theme-source').innerHTML = 'System'\n})\nUsing addEventListener, the renderer.js file adds 'click' event listeners to each button element. Each event listener handler makes calls to the respective window.darkMode API methods.
Finally, the main.js file represents the main process and contains the actual nativeTheme API.
const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n\n ipcMain.handle('dark-mode:toggle', () => {\n if (nativeTheme.shouldUseDarkColors) {\n nativeTheme.themeSource = 'light'\n } else {\n nativeTheme.themeSource = 'dark'\n }\n return nativeTheme.shouldUseDarkColors\n })\n\n ipcMain.handle('dark-mode:system', () => {\n nativeTheme.themeSource = 'system'\n })\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nThe ipcMain.handle methods are how the main process responds to the click events from the buttons on the HTML page.
The 'dark-mode:toggle' IPC channel handler method checks the shouldUseDarkColors boolean property, sets the corresponding themeSource, and then returns the current shouldUseDarkColors property. Looking back on the renderer process event listener for this IPC channel, the return value from this handler is utilized to assign the correct text to the <strong id='theme-source'> element.
The 'dark-mode:system' IPC channel handler method assigns the string 'system' to the themeSource and returns nothing. This also corresponds with the relative renderer process event listener as the method is awaited with no return value expected.
Run the example using Electron Fiddle and then click the \"Toggle Dark Mode\" button; the app should start alternating between a light and dark background color.
\n
Если вы наблюдаете аварии или проблемы в работе Electron, которые, как вы считаете, вызваны самим Electron, а не приложением на JavaScript, отладка может быть немного сложной, особенно для разработчиков ранее не занимавшихся отладкой кода на C++. However, using Visual Studio, Electron's hosted Symbol Server, and the Electron source code, you can enable step-through debugging with breakpoints inside Electron's source code.
\nСм. также: Есть много информации об отладке Chromium, большая часть из которых относится и к Electron, на сайте разработчиков Chromium: Отладка Chromium на Windows.
\nОтладочная сборка Electron: Обычно проще всего собрать ее самостоятельно, используя инструменты и предварительные требования, перечисленные в инструкции по сборке под Windows. Вы конечно можете скачать обычную сборку Electron и подключиться для отладки к ней, но вы обнаружите, что она сильно оптимизирована, и это существенно затрудняет отладку: отладчик не сможет показать вам содержимое всех переменных, так же путь выполнения может казаться странным вследствие встраивания функций (inlining), хвостовых вызовов (trail calls) и других оптимизаций, выполненных компилятором.
\nVisual Studio с инструментами C++: бесплатная общественная редакция Visual Studio, можно использовать версии VS2013 и VS2015. Once installed, configure Visual Studio to use Electron's Symbol server. Это позволит Visual Studio получить лучшее представление о том, что происходит внутри Electron, что позводит представить переменные в удобочитаемом формате.
\nProcMon: бесплатный инструмент от SysInternals, позволяющий вам просматривать параметры процессов, файловые дескрипторы, и операции над реестром.
\nДля запуска сеанса отладки, откройте PowerShell/CMD и запустите отладочную сборку Electron, указав приложение в качестве параметра.
\n$ ./out/Testing/electron.exe ~/my-electron-app/\nЗатем, откройте Visual Studio. Electron не был собран из Visual Studio, и поэтому код не содержит файла проекта; тем не менее, вы можете открывать исходные файлы просто \"как файл\", то есть Visual Studio откроет их сами по себе. Тем не менее, вы можете ставить точки останова - Visual Studio автоматически определит, что этот исходный код соответствует исполняемому коду в подключенном процессе, и остановится на указанной точке останова.
\nСоответствующие файлы кода можно найти в ./shell/.
Вы можете подключить отладчик Visual Studio к запущенному процессу, на локальном или удаленном компьютере. После того как процесс был запущен, нажмите Debug / Attach to Process (или нажмите CTRL + ALT + P), чтобы открыть диалоговое окно «Attach to Process». Вы можете использовать эту возможность для отладки приложений, выполняемых на локальном или удаленном компьютере, и для одновременной отладки нескольких процессов.
Если Electron выполняется под учетной записью другого пользователя, установите флажок Show processes from all users. Обратите внимание, что вы увидите несколько процессов, их количество зависит от того, сколько BrowserWindows открыто в вашем приложении. Типичное одноокнонное приложение будет выглядеть в Visual Studio как два процесса Electron.exe - один для основного процесса и один для процесса визуализации. Поскольку список показывает вам только имена, в настоящее время нет надежного способа выяснить какой из них к чему относится.
Code executed within the main process (that is, code found in or eventually run by your main JavaScript file) will run inside the main process, while other code will execute inside its respective renderer process.
\nВы можете подключиться к несколько программам для отладки, но только одна программа будет активна в отладчике в каждый момент времени. Вы можете задать активную программу в панели инструментов Debug Location либо в окне Processes.
В то время как Visual Studio отлично подходит для изучения конкретных путей выполнения, ProcMon действительно силен в наблюдении за всем, что делает ваше приложение с операционной системой - включая файлы, реестр, сеть, процессы и детальное профилирование процессов. Он пытается протоколировать все происходящие события, что может быть даже весьма излишним, но если вы стремитесь понять, что и как делает ваше приложение с операционной системой, это может быть ценным ресурсом.
\nВ качестве введения в базовые и расширенные возможности отладки через ProcMon можно рекомендовать это видео руководство от Microsoft.
", "title": "Отладка под Windows", "description": "" }, "/docs/api/debugger": { "locale": "ru-RU", "slug": "debugger", "href": "/docs/api/debugger", "crowdinFileId": "256305", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/debugger.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nАльтернативный транспорт для удаленной отладки протокола Chrome.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Инструменты разработчика Chrome имеют специальную привязку доступную во время выполнения JavaScript, что позволяет взаимодействовать со страницами и управлять ими.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\ntry {\n win.webContents.debugger.attach('1.1')\n} catch (err) {\n console.log('Debugger attach failed : ', err)\n}\n\nwin.webContents.debugger.on('detach', (event, reason) => {\n console.log('Debugger detached due to : ', reason)\n})\n\nwin.webContents.debugger.on('message', (event, method, params) => {\n if (method === 'Network.requestWillBeSent') {\n if (params.request.url === 'https://www.github.com') {\n win.webContents.debugger.detach()\n }\n }\n})\n\nwin.webContents.debugger.sendCommand('Network.enable')\nВозвращает:
\neventreason String - причина отсоединения отладчика.Emitted when the debugging session is terminated. This happens either when webContents is closed or devtools is invoked for the attached webContents.
Возвращает:
\neventmethod String - имя метода.params any - Event parameters defined by the 'parameters' attribute in the remote debugging protocol.sessionId String - Unique identifier of attached debugging session, will match the value sent from debugger.sendCommand.Возникает при отладке инструментальных событий.
\ndebugger.attach([protocolVersion])protocolVersion String (опционально) - запрошенная версия протокола отладки.Подключает отладчик к webContents.
debugger.isAttached()Возвращает Boolean - если отладчик присоединен к webContents.
debugger.detach()Отключает отладчик от webContents.
debugger.sendCommand(method[, commandParams, sessionId])method String - Method name, should be one of the methods defined by the remote debugging protocol.commandParams any (опционально) - JSON объект с параметрами запроса.sessionId String (optional) - send command to the target with associated debugging session id. The initial value can be obtained by sending Target.attachToTarget message.Возвращает Promise<any> - Promise, которое разрешается с ответом, определенным атрибутом 'returns' описания команды в протоколе удаленной отладки, или отклоняется, указывая на сбой команды.
Отправьте заданную команду на цель отладки.
", "title": "Debugger", "description": "Альтернативный транспорт для удаленной отладки протокола Chrome." }, "/docs/development/debugging-instructions-macos": { "locale": "ru-RU", "slug": "debugging-instructions-macos", "href": "/docs/development/debugging-instructions-macos", "crowdinFileId": "256153", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Если вы наблюдаете аварии или проблемы в работе Electron, которые, как вы считаете, вызваны самим Electron, а не приложением на JavaScript, отладка может быть немного сложной, особенно для разработчиков ранее не занимавшихся отладкой кода на C++. Однако, используя lldb и исходный код Electron, вы можете включить отладку с точками останова внутри исходного кода Electron. Если вы предпочитаете графический интерфейс, Вы также можете использовать XCode для отладки.
\nA debug build of Electron: The easiest way is usually building it yourself, using the tools and prerequisites listed in the build instructions for macOS. Вы конечно можете скачать обычную сборку Electron и подключиться для отладки к ней, но вы обнаружите, что она сильно оптимизирована, и это существенно затрудняет отладку: отладчик не сможет показать вам содержимое всех переменных, так же путь выполнения может казаться странным вследствие встраивания функций (inlining), хвостовых вызовов (trail calls) и других оптимизаций, выполненных компилятором.
\nXcode: В дополнение к Xcode, также установите утилиты командной строки Xcode. Они включают в себя LLDB, дебаггер по умолчанию в Xcode на macOS. Он поддерживает отладку C, Objective-C и C++ на настольных и iOS устройствах и симуляторах.
\n.lldbinit: Create or edit ~/.lldbinit to allow Chromium code to be properly source-mapped.
# e.g: ['~/electron/src/tools/lldb']\nscript sys.path[:0] = ['<...path/to/electron/src/tools/lldb>']\nscript import lldbinit\nTo start a debugging session, open up Terminal and start lldb, passing a non-release build of Electron as a parameter.
$ lldb ./out/Testing/Electron.app\n(lldb) target create \"./out/Testing/Electron.app\"\nCurrent executable set to './out/Testing/Electron.app' (x86_64).\nLLDB is a powerful tool and supports multiple strategies for code inspection. For this basic introduction, let's assume that you're calling a command from JavaScript that isn't behaving correctly - so you'd like to break on that command's C++ counterpart inside the Electron source.
\nСоответствующие файлы кода можно найти в ./shell/.
Let's assume that you want to debug app.setName(), which is defined in browser.cc as Browser::SetName(). Set the breakpoint using the breakpoint command, specifying file and line to break on:
(lldb) breakpoint set --file browser.cc --line 117\nBreakpoint 1: where = Electron Framework`atom::Browser::SetName(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) + 20 at browser.cc:118, address = 0x000000000015fdb4\nЗатем, запустите Electron:
\n(lldb) запуск\nThe app will immediately be paused, since Electron sets the app's name on launch:
\n(lldb) run\nProcess 25244 launched: '/Users/fr/Code/electron/out/Testing/Electron.app/Contents/MacOS/Electron' (x86_64)\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1\n frame #0: 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118\n 115 }\n 116\n 117 void Browser::SetName(const std::string& name) {\n-> 118 name_override_ = name;\n 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n(lldb)\nTo show the arguments and local variables for the current frame, run frame variable (or fr v), which will show you that the app is currently setting the name to \"Electron\".
(lldb) frame variable\n(atom::Browser *) this = 0x0000000108b14f20\n(const string &) name = \"Electron\": {\n [...]\n}\nTo do a source level single step in the currently selected thread, execute step (or s). This would take you into name_override_.empty(). To proceed and do a step over, run next (or n).
(lldb) step\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119, queue = 'com.apple.main-thread', stop reason = step in\n frame #0: 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119\n 116\n 117 void Browser::SetName(const std::string& name) {\n 118 name_override_ = name;\n-> 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n 122 return badge_count_;\nNOTE: If you don't see source code when you think you should, you may not have added the ~/.lldbinit file above.
To finish debugging at this point, run process continue. You can also continue until a certain line is hit in this thread (thread until 100). This command will run the thread in the current frame till it reaches line 100 in this frame or stops if it leaves the current frame.
Now, if you open up Electron's developer tools and call setName, you will once again hit the breakpoint.
LLDB это мощный инструмент с отличной документацией. To learn more about it, consider Apple's debugging documentation, for instance the LLDB Command Structure Reference or the introduction to Using LLDB as a Standalone Debugger.
\nYou can also check out LLDB's fantastic manual and tutorial, which will explain more complex debugging scenarios.
", "title": "Отладка под macOS", "description": "" }, "/docs/development/debugging-instructions-macos-xcode": { "locale": "ru-RU", "slug": "debugging-instructions-macos-xcode", "href": "/docs/development/debugging-instructions-macos-xcode", "crowdinFileId": "256151", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos-xcode.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Run gn gen with the --ide=xcode argument.
$ gn gen out/Testing --ide=xcode\nЭто будет генерировать electron.ninja.xcworkspace. Вам придётся открыть этот проект для установки точек останова и проверки.
\nСмотрите gn help gen для получения дополнительной информации о генерации проектов IDE с помощью GN.
Запустить Electron приложение после сборки. You can now open the xcode workspace created above and attach to the Electron process through the Debug > Attach To Process > Electron debug menu. [Примечание: если вы хотите отладить процесс рендеринга, вам также нужно присоединиться к Electron Helper.]
\nТеперь вы можете установить точки останова в любом из индексированных файлов. Тем не менее, вы не сможете установить точки останова непосредственно в исходниках Chromium. To set break points in the Chromium source, you can choose Debug > Breakpoints > Create Symbolic Breakpoint and set any function name as the symbol. Это установит точку останова для всех функций с таким именем, из всех классов, если их несколько. Вы также можете сделать этот шаг установки точек останова до прикрепления отладчика, однако, фактические точки останова для символической точки останова могут не появиться до тех пор, пока отладчик не будет прикреплен к приложению.
", "title": "Debugging with XCode", "description": "" }, "/docs/tutorial/debugging-main-process": { "locale": "ru-RU", "slug": "debugging-main-process", "href": "/docs/tutorial/debugging-main-process", "crowdinFileId": "256189", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/debugging-main-process.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "DevTools, который открывается в окне браузера может отлаживать только тот JavaScript, который выполняется в этом окне (т.е. веб-страницы). Для отладки кода основного процесса вам нужно будет использовать внешний отладчик и запускать Electron с ключом --inspect или --inspect-brk.
Для отладки основного процесса используйте один из следующих параметров командной строки:
\n--inspect=[port]Electron will listen for V8 inspector protocol messages on the specified port, an external debugger will need to connect on this port. The default port is 5858.
electron --inspect=5858 ваше/приложение\n--inspect-brk=[port]Работает так же, как --inspect, но останавливает выполнение в первой строке JavaScript.
Вам нужно будет использовать отладчик, поддерживающий протокол инспектора V8.
\nchrome://inspect в Chrome и выберите для проверки запущенное приложение Electron.Это руководство посвящено тому, как настроить VSCode отладку как для вашего проекта Electron, так и для родного кода Electron.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json со следующей конфигурацией:{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"Debug Main Process\",\n \"type\": \"node\",\n \"request\": \"launch\",\n \"cwd\": \"${workspaceFolder}\",\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron\",\n \"windows\": {\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron.cmd\"\n },\n \"args\" : [\".\"]\n }\n ]\n}\nУстановите некоторые точки останова в main.jsи начните отладку в Debug View. You should be able to hit the breakpoints.
Это заранее настроенный проект, который вы можете скачать и непосредственно отладить в VSCode: https://github.com/octref/vscode-electron-debug/tree/master/electron-quick-start
\nЕсли вы хотите собрать Electron из исходного кода и модифицировать его, данный раздел поможет тестировать ваши изменения.
\nДля тех, кто не знает, где получить или как собрать его, Electron Build Tools автоматизирует и объясняет большую часть этого процесса. Если вы хотите самостоятельно настроить окружение, вы можете использовать эти инструкции по сборке.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json со следующей конфигурацией:{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"(Windows) Launch\",\n \"type\": \"cppvsdbg\",\n \"request\": \"launch\",\n \"program\": \"${workspaceFolder}\\\\out\\\\your-executable-location\\\\electron.exe\",\n \"args\": [\"your-electron-project-path\"],\n \"stopAtEntry\": false,\n \"cwd\": \"${workspaceFolder}\",\n \"environment\": [\n {\"name\": \"ELECTRON_ENABLE_LOGGING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_ENABLE_STACK_DUMPING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_RUN_AS_NODE\", \"value\": \"\"},\n ],\n \"externalConsole\": false,\n \"sourceFileMap\": {\n \"o:\\\\\": \"${workspaceFolder}\",\n },\n },\n ]\n}\nПримечания к настройке
\ncppvsdbg требует включённого встроенного расширения C/C++.${workspaceFolder} – это полный путь к каталогу src Chromium.your-executable-location будет одним из следующих, в зависимости от нескольких пунктов:Testing: Если вы используете стандартные настройки Electron Build Tools или полностью следуете инструкции по сборке.Release: Если вы собирали release-версию, а не testing.your-directory-name: Если вы изменили его во время сборки, оно будет таким, каким вы его указали.args должен содержать строки your-electron-project-path, которые являются абсолютными путями до каждой директории или main.js файла проекта, который вы хотели бы протестировать. В данном примере в нём должен быть путь до electron-quick-start.Установите некоторые точки останова в .cc файле выбранного вами кода Electron C++ и начните отладку в Debug View.
", "title": "Отладка в VSCode", "description": "" }, "/docs/api/desktop-capturer": { "locale": "ru-RU", "slug": "desktop-capturer", "href": "/docs/api/desktop-capturer", "crowdinFileId": "256307", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/desktop-capturer.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nAccess information about media sources that can be used to capture audio and video from the desktop using the
\nnavigator.mediaDevices.getUserMediaAPI.
Процессы: Основной, Графический
\nСледующий пример демонстрирует захват видео с окна рабочего стола с названием Electron:
// В графическом процессе.\nconst { desktopCapturer } = require('electron')\n\ndesktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources => {\n for (const source of sources) {\n if (source.name === 'Electron') {\n try {\n const stream = await navigator.mediaDevices.getUserMedia({\n audio: false,\n video: {\n mandatory: {\n chromeMediaSource: 'desktop',\n chromeMediaSourceId: source.id,\n minWidth: 1280,\n maxWidth: 1280,\n minHeight: 720,\n maxHeight: 720\n }\n }\n })\n handleStream(stream)\n } catch (e) {\n handleError(e)\n }\n return\n }\n }\n})\n\nfunction handleStream (stream) {\n const video = document.querySelector('video')\n video.srcObject = stream\n video.onloadedmetadata = (e) => video.play()\n}\n\nfunction handleError (e) {\n console.log(e)\n}\nTo capture video from a source provided by desktopCapturer the constraints passed to navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop', and audio: false.
To capture both audio and video from the entire desktop the constraints passed to navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop', for both audio and video, but should not include a chromeMediaSourceId constraint.
const constraints = {\n audio: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n },\n video: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n }\n}\ndesktopCapturer имеет следующие методы:
desktopCapturer.getSources(options)options Objecttypes String[] - массив строк, который отображает типы источников рабочего стола для захвата, доступные типы screen и window.thumbnailSize Size (опционально) - Размер, до которого должен быть масштабирован эскиз источника мультимедиа. По умолчанию это 150 x 150. Установите ширину или высоту в 0, если вам не нужны эскизы. Это сэкономит время на обработку содержимого каждого окна и экрана.fetchWindowIcons Boolean (опционально) - установите значение true, чтобы включить загрузку значков окна. Значение по умолчанию false. Если false, то свойство appIcon из источников возвращает null. То же самое, если источник имеет тип экрана.Возвращает Promise<DesktopCapturerSource[]> - разрешается с массивом объектов DesktopCapturerSource, каждый DesktopCapturerSource представляет экран или отдельное окно, которое может быть захвачено.
Note Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher, which can detected by systemPreferences.getMediaAccessStatus.
navigator.mediaDevices. etUserMedia не работает в macOS из-за фундаментального ограничения, из-за которого приложениям, желающим получить доступ к звуку системы, требуется подписанное расширение ядра. Chromium, и расширение Electron, не предоставляет этого.
Это ограничение можно обойти путем захвата системного звука с помощью другого приложения macOS вроде Soundflower и передачи его через виртуальное устройство ввода. Это виртуальное устройство может быть запрошено с помощью navigator.mediaDevices.getUserMedia.
id String - The identifier of a window or screen that can be used as a chromeMediaSourceId constraint when calling [navigator.webkitGetUserMedia]. The format of the identifier will be window:XX:YY or screen:ZZ:0. XX is the windowID/handle. YY is 1 for the current process, and 0 for all others. ZZ is a sequential number that represents the screen, and it does not equal to the index in the source's name.name String - A screen source will be named either Entire Screen or Screen <index>, while the name of a window source will match the window title.thumbnail NativeImage - A thumbnail image. Note: There is no guarantee that the size of the thumbnail is the same as the thumbnailSize specified in the options passed to desktopCapturer.getSources. The actual size depends on the scale of the screen or window.display_id String - A unique identifier that will correspond to the id of the matching Display returned by the Screen API. On some platforms, this is equivalent to the XX portion of the id field above and on others it will differ. It will be an empty string if not available.appIcon NativeImage - An icon image of the application that owns the window or null if the source has a type screen. The size of the icon is not known in advance and depends on what the application provides.Like Chromium based browsers, Electron provides access to device hardware through web APIs. For the most part these APIs work like they do in a browser, but there are some differences that need to be taken into account. The primary difference between Electron and browsers is what happens when device access is requested. In a browser, users are presented with a popup where they can grant access to an individual device. In Electron APIs are provided which can be used by a developer to either automatically pick a device or prompt users to pick a device via a developer created interface.
\nThe Web Bluetooth API can be used to communicate with bluetooth devices. In order to use this API in Electron, developers will need to handle the select-bluetooth-device event on the webContents associated with the device request.
This example demonstrates an Electron application that automatically selects the first available bluetooth device when the Test Bluetooth button is clicked.
The WebHID API can be used to access HID devices such as keyboards and gamepads. Electron provides several APIs for working with the WebHID API:
\nselect-hid-device event on the Session can be used to select a HID device when a call to navigator.hid.requestDevice is made. Additionally the hid-device-added and hid-device-removed events on the Session can be used to handle devices being plugged in or unplugged during the navigator.hid.requestDevice process.ses.setDevicePermissionHandler(handler) can be used to provide default permissioning to devices without first calling for permission to devices via navigator.hid.requestDevice. Additionally, the default behavior of Electron is to store granted device permision through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.ses.setPermissionCheckHandler(handler) can be used to disable HID access for specific origins.By default Electron employs the same blocklist used by Chromium. If you wish to override this behavior, you can do so by setting the disable-hid-blocklist flag:
app.commandLine.appendSwitch('disable-hid-blocklist')\nThis example demonstrates an Electron application that automatically selects HID devices through ses.setDevicePermissionHandler(handler) and through select-hid-device event on the Session when the Test WebHID button is clicked.
The Web Serial API can be used to access serial devices that are connected via serial port, USB, or Bluetooth. In order to use this API in Electron, developers will need to handle the select-serial-port event on the Session associated with the serial port request.
There are several additional APIs for working with the Web Serial API:
\nserial-port-added and serial-port-removed events on the Session can be used to handle devices being plugged in or unplugged during the navigator.serial.requestPort process.ses.setPermissionCheckHandler(handler) can be used to disable serial access for specific origins.This example demonstrates an Electron application that automatically selects the first available Arduino Uno serial device (if connected) through select-serial-port event on the Session when the Test Web Serial button is clicked.
Electron supports Chrome DevTools extensions, which can be used to extend the ability of Chrome's developer tools for debugging popular web frameworks.
\nThe easiest way to load a DevTools extension is to use third-party tooling to automate the process for you. electron-devtools-installer is a popular NPM package that does just that.
\nIf you don't want to use the tooling approach, you can also do all of the necessary operations by hand. To load an extension in Electron, you need to download it via Chrome, locate its filesystem path, and then load it into your Session by calling the [ses.loadExtension] API.
Using the React Developer Tools as an example:
\n fmkadmapgofadopljbjfkapdkoienihi </ 0>.Find out the filesystem location used by Chrome for storing extensions:
\n\n\n- в Windows it is
%LOCALAPPDATA%\\Google\\Chrome\\User Data\\Default\\Extensions`; \n * в Linux это может быть:\n * `~/.config/google-chrome/Default/Extensions/`\n * `~/.config/google-chrome-beta/Default/Extensions/`\n * `~/.config/google-chrome-canary/Default/Extensions/`\n * `~/.config/chromium/Default/Extensions/`\n * в macOS это `~/Library/Application Support/Google/Chrome/Default/Extensions`.
\n1 Передайте местоположение расширения в [`ses.loadExtension`][load-extension] API. For React Developer Tools `v4.9.0`, it looks something like:\n const { app, session } = require('electron')\n const path = require('path')\n const os = require('os')\n\n // on macOS\n const reactDevToolsPath = path.join(\n os.homedir(),\n '/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.9.0_0'\n )\n\n app.whenReady().then(async () => {\n await session.defaultSession.loadExtension(reactDevToolsPath)\n })\n
\n\nПримечания:
\n\nloadExtension returns a Promise with an Extension object, which contains metadata about the extension that was loaded. This promise needs to resolve (e.g. with an await expression) before loading a page. Otherwise, the extension won't be guaranteed to load.loadExtension cannot be called before the ready event of the app module is emitted, nor can it be called on in-memory (non-persistent) sessions.loadExtension must be called on every boot of your app if you want the extension to be loaded.
\nRemoving a DevTools extension
\nYou can pass the extension's ID to the ses.removeExtension API to remove it from your Session. Loaded extensions are not persisted between app launches.
\nDevTools extension support
\nElectron only supports a limited set of chrome.* APIs, so extensions using unsupported chrome.* APIs under the hood may not work.
\nThe following Devtools extensions have been tested to work in Electron:
\n\n- Ember Inspector
\n- React Developer Tools
\n- Backbone Debugger
\n- jQuery Debugger
\n- AngularJS Batarang
\n- Vue.js devtools
\n- Cerebral Debugger
\n- Redux DevTools Extension
\n- MobX Developer Tools
\n
\nWhat should I do if a DevTools extension is not working?
\nFirst, please make sure the extension is still being maintained and is compatible with the latest version of Google Chrome. We cannot provide additional support for unsupported extensions.
\nIf the extension works on Chrome but not on Electron, file a bug in Electron's issue tracker and describe which part of the extension is not working as expected.
",
"title": "Расширение DevTools",
"description": ""
},
"/docs/api/dialog": {
"locale": "ru-RU",
"slug": "dialog",
"href": "/docs/api/dialog",
"crowdinFileId": "256309",
"githubUrl": "https://github.com/electron/electron/tree/main/docs/api/dialog.md",
"category": "api",
"categoryFancy": "API",
"isTutorial": false,
"isApiDoc": true,
"isApiStructureDoc": false,
"isDevTutorial": false,
"html": "\n\nПоказывает стандартные диалоги для открытия и сохранения файлов, предупреждения и т.п.
\n
Процесс: Основной
\nПример для показа диалога выбора нескольких файлов:
\nconst { dialog } = require('electron')\nconsole.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))\nМодуль dialog имеет следующие методы:
dialog.showOpenDialogSync([browserWindow, ]options)browserWindow BrowserWindow (опционально)options Objecttitle String (опционально)defaultPath String (опционально)buttonLabel String(опционально) - Пользовательский текст кнопки подтверждения. Если оставить пустым будет использован стандартный текст.filters FileFilter[] (опционально)properties String[] (optional) - Contains which features the dialog should use. The following values are supported:openFile - Позволяет выбирать файлы.openDirectory - Позволяет выбирать папки.multiSelections - Позволяет выбрать несколько объектов.showHiddenFiles - Отображает в диалоге скрытые файлы.createDirectory macOS - Позволяет создавать новые директории из диалога.promptToCreate Windows - Запрашивает подтверждение на создание недостающих папок по выбранному пути, если они не существуют. На самом деле, эта функция не создаёт их. Она всего лишь позволяет возвращать несуществующие пути из диалогового окна, которые должны после этого быть созданы приложением.noResolveAliases macOS - Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.treatPackageAsDirectory macOS - Считает пакеты, такие как папки .app, за папки, а не файлы.dontAddToRecent Windows - Do not add the item being opened to the recent documents list.message String (опционально) macOS - Сообщение, которое будет отображено над полями ввода.securityScopedBookmarks Boolean (опционально) macOS mas - Создает закладки с областью безопасности, при сборке пакета для Mac App Store.Возвращает String[] | undefined - пути файла, выбранные пользователем; если диалог отменен, то возвращает undefined.
Аргумент browserWindow позволяет диалоговому окну прикрепляться к родительскому, что делает его модальным.
The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Например:
{\n filters: [\n { name: 'Изображения', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Видео', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Свой тип файлов', extensions: ['as'] },\n { name: 'Все файлы', extensions: ['*'] }\n ]\n}\nМассив extentions должен содержать расширения файлов без шаблонов поиска и точек (например, png - верно, а .png и *.png - нет). Для того, чтобы показать все фалы, можно использовать шаблон поиска '*' (другие шаблоны не поддерживаются).
Замечание: на Windows и Linux в диалоговом окне нельзя дновременно выбирать и файлы, и директории, так что если вы установили properties в ['openFile', 'openDirectory'] на этих платформах, то возможно будет выбирать только директории.
dialog.showOpenDialogSync(mainWindow, {\n properties: ['openFile', 'openDirectory']\n})\ndialog.showOpenDialog([browserWindow, ]options)browserWindow BrowserWindow (опционально)options Objecttitle String (опционально)defaultPath String (опционально)buttonLabel String(опционально) - Пользовательский текст кнопки подтверждения. Если оставить пустым будет использован стандартный текст.filters FileFilter[] (опционально)properties String[] (optional) - Contains which features the dialog should use. The following values are supported:openFile - Позволяет выбирать файлы.openDirectory - Позволяет выбирать папки.multiSelections - Позволяет выбрать несколько объектов.showHiddenFiles - Отображает в диалоге скрытые файлы.createDirectory macOS - Позволяет создавать новые директории из диалога.promptToCreate Windows - Запрашивает подтверждение на создание недостающих папок по выбранному пути, если они не существуют. На самом деле, эта функция не создаёт их. Она всего лишь позволяет возвращать несуществующие пути из диалогового окна, которые должны после этого быть созданы приложением.noResolveAliases macOS - Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.treatPackageAsDirectory macOS - Считает пакеты, такие как папки .app, за папки, а не файлы.dontAddToRecent Windows - Do not add the item being opened to the recent documents list.message String (опционально) macOS - Сообщение, которое будет отображено над полями ввода.securityScopedBookmarks Boolean (опционально) macOS mas - Создает закладки с областью безопасности, при сборке пакета для Mac App Store.Возвращает Promise<Object> - Разрешить с объектом, содержащим следующее:
canceled Boolean - независимо от того, был ли диалог отменен.filePaths String[] - Массив файлов, которые выбрал пользователь. If the dialog is cancelled this will be an empty array.bookmarks String[] (optional) macOS mas - An array matching the filePaths array of base64 encoded strings which contains security scoped bookmark data. Для его использования, securityScopedBookmarks должны быть активированы. (For return values, see table here.)Аргумент browserWindow позволяет диалоговому окну прикрепляться к родительскому, что делает его модальным.
The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Например:
{\n filters: [\n { name: 'Изображения', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Видео', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Свой тип файлов', extensions: ['as'] },\n { name: 'Все файлы', extensions: ['*'] }\n ]\n}\nМассив extentions должен содержать расширения файлов без шаблонов поиска и точек (например, png - верно, а .png и *.png - нет). Для того, чтобы показать все фалы, можно использовать шаблон поиска '*' (другие шаблоны не поддерживаются).
Замечание: на Windows и Linux в диалоговом окне нельзя дновременно выбирать и файлы, и директории, так что если вы установили properties в ['openFile', 'openDirectory'] на этих платформах, то возможно будет выбирать только директории.
dialog.showOpenDialog(mainWindow, {\n properties: ['openFile', 'openDirectory']\n}).then(result => {\n console.log(result.canceled)\n console.log(result.filePaths)\n}).catch(err => {\n console.log(err)\n})\ndialog.showSaveDialogSync([browserWindow, ]options)browserWindow BrowserWindow (опционально)options Objecttitle String (optional) - The dialog title. Cannot be displayed on some Linux desktop environments.defaultPath String (опционально) - Абсолютный путь к директории, файлу или имя файла выбранного по умолчанию.buttonLabel String(опционально) - Пользовательский текст кнопки подтверждения. Если оставить пустым будет использован стандартный текст.filters FileFilter[] (опционально)message String (опционально) macOS - Сообщение, которое будет показано над полями ввода.nameFieldLabel String (опционально) macOS - Специальная метка для текста, отображаемая перед текстовым полем с именем файла.showsTagField Boolean (опционально) macOS - Показать поле ввода тегов, по умолчанию true.properties String[] (optional)showHiddenFiles - Отображает в диалоге скрытые файлы.createDirectory macOS - Позволяет создавать новые директории из диалога.treatPackageAsDirectory macOS - Считает пакеты, такие как папки .app, за папки, а не файлы.showOverwriteConfirmation Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.dontAddToRecent Windows - Do not add the item being saved to the recent documents list.securityScopedBookmarks Boolean (необязательно) maxOS mas - Создавать закладки с областью безопасности при сборке для Mac App Store. Если эта опция включена и выбранного файла не существует, то пустой файл будет создан по выбранному пути.Возвращает String | undefined, путь к файлу, выбранному пользователем; если диалог отменен, то возвращает undefined.
Аргумент browserWindow позволяет диалоговому окну прикрепляться к родительскому, что делает его модальным.
filters определяет массив типов файлов, которые могут быть отображены. Для примера смотрите dialog.showOpenDialog.
dialog.showSaveDialog([browserWindow, ]options)browserWindow BrowserWindow (опционально)options Objecttitle String (optional) - The dialog title. Cannot be displayed on some Linux desktop environments.defaultPath String (опционально) - Абсолютный путь к директории, файлу или имя файла выбранного по умолчанию.buttonLabel String(опционально) - Пользовательский текст кнопки подтверждения. Если оставить пустым будет использован стандартный текст.filters FileFilter[] (опционально)message String (опционально) macOS - Сообщение, которое будет показано над полями ввода.nameFieldLabel String (опционально) macOS - Специальная метка для текста, отображаемая перед текстовым полем с именем файла.showsTagField Boolean (optional) macOS - Show the tags input box, defaults to true.properties String[] (optional)showHiddenFiles - Отображает в диалоге скрытые файлы.createDirectory macOS - Позволяет создавать новые директории из диалога.treatPackageAsDirectory macOS - Считает пакеты, такие как папки .app, за папки, а не файлы.showOverwriteConfirmation Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.dontAddToRecent Windows - Do not add the item being saved to the recent documents list.securityScopedBookmarks Boolean (необязательно) maxOS mas - Создавать закладки с областью безопасности при сборке для Mac App Store. Если эта опция включена и выбранного файла не существует, то пустой файл будет создан по выбранному пути.Возвращает Promise<Object> - Разрешить с объектом, содержащим следующее:
canceled Boolean - независимо от того, был ли диалог отменен.filePath String (optional) - If the dialog is canceled, this will be undefined.bookmark String (необязательно) macOS mas - Строка в кодировке base64, содержащая зкладку с областью безопасности сохранённого файла. securityScopedBookmarks должны быть активированы для её использования. (For return values, see table here.)Аргумент browserWindow позволяет диалоговому окну прикрепляться к родительскому, что делает его модальным.
filters определяет массив типов файлов, которые могут быть отображены. Для примера смотрите dialog.showOpenDialog.
Заметка: На MacOS, рекомендуется асинхронная версия, чтобы избежать проблем при расширении и свёртывании окна.
\ndialog.showMessageBoxSync([browserWindow, ]options)browserWindow BrowserWindow (опционально)options Objectmessage String - содержимое сообщения.type String (опционально) - Может быть \"none\", \"info\", \"error\", \"question\" или \"warning\". В Windows, \"question\" отображает ту же иконку, что и \"info\", если вы не установили иконку, используя опцию \"icon\". На macOS и \"warning\" и \"error\" отображают ту же иконку предупреждения (warning).buttons String[] (optional) - Array of texts for buttons. On Windows, an empty array will result in one button labeled \"OK\".defaultId Integer (опционально) - Индекс кнопки в массиве кнопок, который будет выбран по умолчанию при открытии окна сообщения.title String (необязательно) - Заголовок окна сообщения, некоторые платформы не смогут его отобразить.detail String (опционально) - Дополнительные сведения о сообщении.icon (NativeImage | String) (опционально)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (опционально) - Индекс кнопки, которая будет использоваться для отмены диалога, через клавишу Esc. По умолчанию это назначается первой кнопке с меткой \"Отмена\" или \"Нет\". Если этот параметр не установлен и нет таких отмеченных кнопок, как возвращаемое значение будет использоваться 0.noLink Boolean (опционально) - В Windows Electron попытается выяснить, какие из buttons являются общими кнопками (например, «Отмена» или «Да»), и отобразить остальные как ссылки команд в диалоговом окне. Это может сделать диалог в стиле современных приложений Windows. Если вам не нравится такое поведение, вы можете установить noLink на true.normalizeAccessKeys Boolean (опционально) - Нормализация клавиш доступа к клавиатуре на разных платформах. По умолчанию - false. Включение этого предполагает, что & используется в метках кнопок для размещения клавиши быстрого доступа, и метки будут преобразованы, чтобы они правильно работали на каждой платформе, символы & удаляются в macOS, преобразуются в _ в Linux и остаются нетронутыми в Windows. Например, метка кнопки Vie&w будет преобразована в Vie_w в Linux и View в macOS и может быть выбрана с помощью Alt-W в Windows и Linux.Возвращает Integer - индекс нажатой кнопки.
Показывает окно сообщения, оно будет блокировать процесс, пока не будет закрыто окно сообщения. It returns the index of the clicked button.
\nАргумент browserWindow позволяет диалоговому окну прикрепляться к родительскому, что делает его модальным. If browserWindow is not shown dialog will not be attached to it. В этом случае он будет отображаться как независимое окно.
dialog.showMessageBox([browserWindow, ]options)browserWindow BrowserWindow (опционально)options Objectmessage String - содержимое сообщения.type String (опционально) - Может быть \"none\", \"info\", \"error\", \"question\" или \"warning\". В Windows, \"question\" отображает ту же иконку, что и \"info\", если вы не установили иконку, используя опцию \"icon\". На macOS и \"warning\" и \"error\" отображают ту же иконку предупреждения (warning).buttons String[] (optional) - Array of texts for buttons. On Windows, an empty array will result in one button labeled \"OK\".defaultId Integer (опционально) - Индекс кнопки в массиве кнопок, который будет выбран по умолчанию при открытии окна сообщения.signal AbortSignal (optional) - Pass an instance of AbortSignal to optionally close the message box, the message box will behave as if it was cancelled by the user. On macOS, signal does not work with message boxes that do not have a parent window, since those message boxes run synchronously due to platform limitations.title String (необязательно) - Заголовок окна сообщения, некоторые платформы не смогут его отобразить.detail String (опционально) - Дополнительные сведения о сообщении.checkboxLabel String (опционально) - Если это предусмотрено, в окне сообщения будет установлен флажок с данной меткой.checkboxChecked Boolean (optional) - Initial checked state of the checkbox. По умолчанию false.icon NativeImage (опционально)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (опционально) - Индекс кнопки, которая будет использоваться для отмены диалога, через клавишу Esc. По умолчанию это назначается первой кнопке с меткой \"Отмена\" или \"Нет\". Если этот параметр не установлен и нет таких отмеченных кнопок, как возвращаемое значение будет использоваться 0.noLink Boolean (опционально) - В Windows Electron попытается выяснить, какие из buttons являются общими кнопками (например, «Отмена» или «Да»), и отобразить остальные как ссылки команд в диалоговом окне. Это может сделать диалог в стиле современных приложений Windows. Если вам не нравится такое поведение, вы можете установить noLink на true.normalizeAccessKeys Boolean (опционально) - Нормализация клавиш доступа к клавиатуре на разных платформах. По умолчанию - false. Включение этого предполагает, что & используется в метках кнопок для размещения клавиши быстрого доступа, и метки будут преобразованы, чтобы они правильно работали на каждой платформе, символы & удаляются в macOS, преобразуются в _ в Linux и остаются нетронутыми в Windows. Например, метка кнопки Vie&w будет преобразована в Vie_w в Linux и View в macOS и может быть выбрана с помощью Alt-W в Windows и Linux.Возвращает Promise<Object> - разрешает Promise, содержащие следующие свойства:
response Number - The index of the clicked button.checkboxChecked Boolean - The checked state of the checkbox if checkboxLabel was set. Otherwise false.Shows a message box.
\nАргумент browserWindow позволяет диалоговому окну прикрепляться к родительскому, что делает его модальным.
dialog.showErrorBox(title, content)title String - Заголовок для отображения в поле ошибки.title String - Текстовое содержимое для отображения в поле ошибки.Отображает модальное диалоговое окно, показывающее сообщение об ошибке.
\nЭтот API можно безопасно вызывать до события ready, которое выдает модуль app, он обычно используется для сообщений об ошибках на ранней стадии запуска. При вызове до события app ready в Linux, сообщение будет выдано в stderr, и диалоговое окно GUI не появится.
dialog.showCertificateTrustDialog([browserWindow, ]options) macOS WindowsbrowserWindow BrowserWindow (опционально)options Objectcertificate Certificate - Сертификат доверия/импорта.message String - Сообщение, отображаемое пользователю.Возвращает Promise<void> - выполняется, когда показано диалоговое окно доверия сертификата.
На macOS отображается модальное диалоговое окно, которое показывает сообщение и сертификат информации, и предоставляет пользователю возможность доверия/импорта сертификата. Если вы укажете аргумент browserWindow, диалоговое окно будет присоединено к родительскому окну, что сделает его модальным.
В Windows параметры более ограничены, благодаря используемым API Win32:
\nmessage, так как ОС предоставляет свое собственное подтверждение диалогового окна.browserWindow игнорируется, поскольку невозможно сделать это диалоговое окно подтверждения.showOpenDialog, showOpenDialogSync, showSaveDialog, and showSaveDialogSync will return a bookmarks array.
| Build Type | securityScopedBookmarks boolean | Return Type | Return Value |
|---|---|---|---|
| macOS mas | True | Success | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | Error | [''] (array of empty string) |
| macOS mas | False | NA | [] (empty array) |
| non mas | any | NA | [] (empty array) |
В macOS диалоговые окна представляются в виде листов, прикрепленных к окну, если вы указали ссылку BrowserWindow в параметре browserWindow, или являются модальными, если окно не предусмотрено.
Вы можете вызвать BrowserWindow.getCurrentWindow().SetSheetOffset(offset), чтобы изменить смещение рамки окна, к которой прикреплены листы.
id Number - Unique identifier associated with the display.rotation Number - Can be 0, 90, 180, 270, represents screen rotation in clock-wise degrees.scaleFactor Number - Output device's pixel scale factor.touchSupport String - Can be available, unavailable, unknown.monochrome Boolean - Whether or not the display is a monochrome display.accelerometerSupport String - Can be available, unavailable, unknown.colorSpace String - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversionscolorDepth Number - The number of bits per pixel.depthPerComponent Number - The number of bits per color component.displayFrequency Number - The display refresh rate.bounds Rectangle - the bounds of the display in DIP points.size SizeworkArea Rectangle - the work area of the display in DIP points.workAreaSize Sizeinternal Boolean - true for an internal display and false for an external displayThe Display object represents a physical display connected to the system. A fake Display may exist on a headless system, or a Display may correspond to a remote, virtual display.
\n\nУправляйте вашим приложением в macOS dock
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Следующий пример показывает, как отскочить вашу иконку в dock.
\nconst { app } = require('electron')\napp.dock.bounce()\ndock.bounce([type]) macOStype String (опционально) - Может быть critical или informational. По умолчанию informationalВозвращает Integer - ID, представляющий запрос.
Когда critical передается, значок dock будет отскакивать, пока приложение не станет активным или запрос отменяется.
Когда informational пропущен, значок dock будет подпрыгивать в течение одной секунды. Тем не менее, запрос остается активным, пока приложение не станет активным или запрос не будет отменен.
Обратите внимание: Этот метод можно использовать только тогда, когда приложение не сфокусировано; когда приложение сфокусировано, оно вернет -1.
\ndock.cancelBounce(id) macOSid IntegerОтменить отскок по id.
dock.downloadFinished(filePath) macOSfilePath StringОтскакивает от \"Downloads\", если путь к файлу находится в папке \"Downloads\".
\ndock.setBadge(text) macOStext StringУстанавливает строку для отображения в панели dock запирающими областями.
\ndock.getBadge() macOSВозвращает String - строки значка в dock.
dock.hide() macOSСкрыть значок в dock.
\ndock.show() macOSВозвращает Promise<void> - выполняется, когда показан значок dock.
dock.isVisible() macOSВозвращает Boolean - виден или нет значок dock.
dock.setMenu(menu) macOSmenu MenuУстанавливает Dock меню приложения [dock-menu].
\ndock.getMenu() macOSВозвращает Menu | null - Dock меню приложения [dock-menu].
dock.setIcon(image) macOSimage (NativeImage | String)Задает image, связывает со значком в dock.
\n\nКонтроль загрузки файлов из удаленных источников.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
DownloadItem это EventEmitter, который представляет элемент загрузки в Electron. Он используется в событии will-download класса Session и позволяет пользователям управлять элементом загрузки.
// В основном процессе.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.session.on('will-download', (event, item, webContents) => {\n // Установите путь сохранения, чтобы Electron не отображал диалоговое окно сохранения.\n item.setSavePath('/tmp/save.pdf')\n\n item.on('updated', (event, state) => {\n if (state === 'interrupted') {\n console.log('Download is interrupted but can be resumed')\n } else if (state === 'progressing') {\n if (item.isPaused()) {\n console.log('Download is paused')\n } else {\n console.log(`Received bytes: ${item.getReceivedBytes()}`)\n }\n }\n })\n item.once('done', (event, state) => {\n if (state === 'completed') {\n console.log('Download successfully')\n } else {\n console.log(`Download failed: ${state}`)\n }\n })\n})\nВозвращает:
\neventstate String - Может быть progressing или interrupted.Возникает, когда загрузка была обновлена и не завершена.
\nstate может быть одним из следующих:
progressing - Загрузка находится в процессе загрузки.interrupted - загрузка прервалась и может быть возобновлена.Возвращает:
\neventstate String - может быть завершено completed, отменено cancelled или прервано interrupted.Emitted when the download is in a terminal state. This includes a completed download, a cancelled download (via downloadItem.cancel()), and interrupted download that can't be resumed.
state может быть одним из следующих:
completed - Загрузка завершена успешно.cancelled - загрузка была отменена.interrupted - загрузка прервалась и не может быть возобновлена.Объект downloadItem имеет следующие методы:
downloadItem.setSavePath(path)path String - Установить путь сохраняемого элемента загрузки.API доступен только в сессии will-download функции обратного вызова. If path doesn't exist, Electron will try to make the directory recursively. Если пользователь не устанавливает путь сохранения через API, Electron будет использовать исходную процедуру для определения пути сохранения; здесь обычно вызывается диалоговое окно сохранения.
downloadItem.getSavePath()Returns String - The save path of the download item. This will be either the path set via downloadItem.setSavePath(path) or the path selected from the shown save dialog.
downloadItem.setSaveDialogOptions(options)options SaveDialogOptions - Установите параметры диалога сохранения. Этот объект имеет те же свойства, что и параметры options в dialog.showSaveDialog().This API allows the user to set custom options for the save dialog that opens for the download item by default. API доступен только в сессии will-download функции обратного вызова.
downloadItem.getSaveDialogOptions()Возвращает SaveDialogOptions - Возвращает ранее установленный объект downloadItem.setSaveDialogOptions(options).
downloadItem.pause()Приостановить скачивание.
\ndownloadItem.isPaused()Returns Boolean - Whether the download is paused.
downloadItem.resume()Resumes the download that has been paused.
\nNote: To enable resumable downloads the server you are downloading from must support range requests and provide both Last-Modified and ETag header values. Otherwise resume() will dismiss previously received bytes and restart the download from the beginning.
downloadItem.canResume()Returns Boolean - Whether the download can resume.
downloadItem.cancel()Cancels the download operation.
\ndownloadItem.getURL()Возвращает String - URL источника, из которого загружается элемент.
downloadItem.getMimeType()Returns String - The files mime type.
downloadItem.hasUserGesture()Returns Boolean - Whether the download has user gesture.
downloadItem.getFilename()Returns String - The file name of the download item.
Note: The file name is not always the same as the actual one saved in local disk. If user changes the file name in a prompted download saving dialog, the actual name of saved file will be different.
\ndownloadItem.getTotalBytes()Returns Integer - The total size in bytes of the download item.
If the size is unknown, it returns 0.
\ndownloadItem.getReceivedBytes()Returns Integer - The received bytes of the download item.
downloadItem.getContentDisposition()Returns String - The Content-Disposition field from the response header.
downloadItem.getState()Returns String - The current state. Can be progressing, completed, cancelled or interrupted.
Note: The following methods are useful specifically to resume a cancelled item when session is restarted.
downloadItem.getURLChain()Возвращает String[] - полная URL-цепочка до элемента, включая любые перенаправления.
downloadItem.getLastModifiedTime()Returns String - Last-Modified header value.
downloadItem.getETag()Returns String - ETag header value.
downloadItem.getStartTime()Returns Double - Number of seconds since the UNIX epoch when the download was started.
downloadItem.savePathСвойство String, которое определяет путь к файлу сохранения элемента загрузки.
Свойство доступно только в сессии will-download функции обратного вызова. Если пользователь не устанавливает путь сохранения через свойство, Electron будет использовать исходную процедуру для определения пути сохранения; здесь обычно вызывается диалоговое окно сохранения.
Special notes:
\n-beta.1 and stable dates are our solid release dates.| Electron | Alpha | Beta | Стабильная | Chrome | Node |
|---|---|---|---|---|---|
| 2.0.0 | -- | 2018-Feb-21 | 2018-May-01 | М61 | v8.9 |
| 3.0.0 | -- | 2018-Jun-21 | 2018-Sep-18 | М66 | v10.2 |
| 4.0.0 | -- | 2018-Oct-11 | 2018-Dec-20 | М69 | v10.11 |
| 5.0.0 | -- | 2019-Jan-22 | 2019-Apr-24 | М73 | v12.0 |
| 6.0.0 | -- | 2019-May-01 | 2019-Jul-30 | М76 | v12.4 |
| 7.0.0 | -- | 2019-Aug-01 | 2019-Oct-22 | М78 | v12.8 |
| 8.0.0 | -- | 2019-Oct-24 | 2020-Feb-04 | M80 | v12.13 |
| 9.0.0 | -- | 2020-Feb-06 | 2020-May-19 | M83 | v12.14 |
| 10.0.0 | -- | 2020-May-21 | 2020-Aug-25 | M85 | v12.16 |
| 11.0.0 | -- | 2020-Aug-27 | 2020-Nov-17 | M87 | v12.18 |
| 12.0.0 | -- | 2020-Nov-19 | 2021-Mar-02 | M89 | v14.16 |
| 13.0.0 | -- | 2021-Mar-04 | 2021-May-25 | M91 | v14.16 |
| 14.0.0 | -- | 2021-May-27 | 2021-Aug-31 | M93 | v14.17 |
| 15.0.0 | 2021-Jul-20 | 2021-Sep-01 | 2021-Sep-21 | M94 | v16.5 |
| 16.0.0 | -- | 2021-Sep-23 | 2021-Nov-16 | M96 | TBD |
\n\nДетализированный взгляд на политику версионирования и ее реализацию.
\n
As of version 2.0.0, Electron follows SemVer. The following command will install the most recent stable build of Electron:
\nnpm install --save-dev electron\nОбновление до последней стабильной версии в существующем проекте:
\nnpm install --save-dev electron@latest\nElectron versions < 2.0 did not conform to the SemVer spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. While convenient for developers merging features, it creates problems for developers of client-facing applications. The QA testing cycles of major apps like Slack, Stride, Teams, Skype, VS Code, Atom, and Desktop can be lengthy and stability is a highly desired outcome. There is a high risk in adopting new features while trying to absorb bug fixes.
\nHere is an example of the 1.x strategy:
\n
An app developed with 1.8.1 cannot take the 1.8.3 bug fix without either absorbing the 1.8.2 feature, or by backporting the fix and maintaining a new release line.
There are several major changes from our 1.x strategy outlined below. Each change is intended to satisfy the needs and priorities of developers/maintainers and app developers.
\n-beta tagsmaster branch is versionless; only stabilization branches contain version informationWe will cover in detail how git branching works, how npm tagging works, what developers should expect to see, and how one can backport changes.
\nFrom 2.0 onward, Electron will follow SemVer.
\nBelow is a table explicitly mapping types of changes to their corresponding category of SemVer (e.g. Major, Minor, Patch).
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Major Version Increments | Minor Version Increments | Patch Version Increments |
|---|---|---|
| Electron breaking API changes | Electron non-breaking API changes | Electron bug fixes |
| Node.js major version updates | Node.js minor version updates | Node.js patch version updates |
| Chromium version updates | fix-related chromium patches |
Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
\nStabilization branches are branches that run parallel to master, taking in only cherry-picked commits that are related to security or stability. These branches are never merged back to master.
\n
Since Electron 8, stabilization branches are always major version lines, and named against the following template $MAJOR-x-y e.g. 8-x-y. Prior to that we used minor version lines and named them as $MAJOR-$MINOR-x e.g. 2-0-x
We allow for multiple stabilization branches to exist simultaneously, and intend to support at least two in parallel at all times, backporting security fixes as necessary.
Older lines will not be supported by GitHub, but other groups can take ownership and backport stability and security fixes on their own. We discourage this, but recognize that it makes life easier for many app developers.
\nDevelopers want to know which releases are safe to use. Even seemingly innocent features can introduce regressions in complex applications. At the same time, locking to a fixed version is dangerous because you’re ignoring security patches and bug fixes that may have come out since your version. Our goal is to allow the following standard semver ranges in package.json :
~2.0.0 to admit only stability or security related fixes to your 2.0.0 release.^2.0.0 to admit non-breaking reasonably stable feature work as well as security and bug fixes.What’s important about the second point is that apps using ^ should still be able to expect a reasonable level of stability. To accomplish this, SemVer allows for a pre-release identifier to indicate a particular version is not yet safe or stable.
Whatever you choose, you will periodically have to bump the version in your package.json as breaking changes are a fact of Chromium life.
The process is as follows:
\nbeta.N, e.g. 2.0.0-beta.1. After the first beta, subsequent beta releases must meet all of the following conditions:2.0.0-beta.2.2.0.0. After the first stable, all changes must be backwards-compatible bug or security fixes.2.0.1.Specifically, the above means:
\nFor each major and minor bump, you should expect to see something like the following:
\n2.0.0-beta.1\n2.0.0-beta.2\n2.0.0-beta.3\n2.0.0\n2.0.1\n2.0.2\nAn example lifecycle in pictures:
\n2.0.0-beta.1. 2.0.0-beta.2. 2.0.0. 2-0-x line and release 2.0.1. A few examples of how various SemVer ranges will pick up new releases:
\n
Our strategy has a few tradeoffs, which for now we feel are appropriate. Most importantly that new features in master may take a while before reaching a stable release line. If you want to try a new feature immediately, you will have to build Electron yourself.
\nAs a future consideration, we may introduce one or both of the following:
\nFeature flags are a common practice in Chromium, and are well-established in the web-development ecosystem. In the context of Electron, a feature flag or soft branch must have the following properties:
\nWe seek to increase clarity at all levels of the update and releases process. Starting with 2.0.0 we will require pull requests adhere to the Conventional Commits spec, which can be summarized as follows:
Commits that would result in a SemVer major bump must start their body with BREAKING CHANGE:.
Commits that would result in a SemVer minor bump must start with feat:.
Commits that would result in a SemVer patch bump must start with fix:.
We allow squashing of commits, provided that the squashed message adheres to the above message format.
\nIt is acceptable for some commits in a pull request to not include a semantic prefix, as long as the pull request title contains a meaningful encompassing semantic message.
\nmastermaster branch will always contain the next major version X.0.0-nightly.DATE in its package.jsonpackage.jsonmaster is always versioned as the next theoretical release branchLike NW.js, Electron provides a platform to write desktop applications with web technologies. Both platforms enable developers to utilize HTML, JavaScript, and Node.js. On the surface, they seem very similar.
\nThere are however fundamental differences between the two projects that make Electron a completely separate product from NW.js.
\nIn NW.js, the main entry point of an application can be an HTML web page. In that case, NW.js will open the given entry point in a browser window.
\nIn Electron, the entry point is always a JavaScript script. Instead of providing a URL directly, you manually create a browser window and load an HTML file using the API. You also need to listen to window events to decide when to quit the application.
\nElectron works more like the Node.js runtime. Electron's APIs are lower level so you can use it for browser testing in place of PhantomJS.
\nIn NW.js, the Node integration in web pages requires patching Chromium to work, while in Electron we chose a different way to integrate the libuv loop with each platform's message loop to avoid hacking Chromium. Вы можете изучить код node_bindings, чтобы узнать, как это было реализовано.
If you are an experienced NW.js user, you should be familiar with the concept of Node context and web context. These concepts were invented because of how NW.js was implemented.
\nBy using the multi-context feature of Node, Electron doesn't introduce a new JavaScript context in web pages.
\nПримечание: Поддержка multi-context была представлена c 0.13 версии NW.js.
\nNW.js still offers a \"legacy release\" that supports Windows XP. It doesn't receive security updates.
\nGiven that hardware manufacturers, Microsoft, Chromium, and Node.js haven't released even critical security updates for that system, we have to warn you that using Windows XP is wildly insecure and outright irresponsible.
\nHowever, we understand that requirements outside our wildest imagination may exist, so if you're looking for something like Electron that runs on Windows XP, the NW.js legacy release might be the right fit for you.
\nThere are numerous differences in the amount of supported features. Electron has a bigger community, more production apps using it, and a large amount of userland modules available on npm.
\nAs an example, Electron has built-in support for automatic updates and countless tools that make the creation of installers easier. As an example in favor of NW.js, NW.js supports more Chrome.* APIs for the development of Chrome Apps.
Naturally, we believe that Electron is the better platform for polished production applications built with web technologies (like Visual Studio Code, Slack, or Facebook Messenger); however, we want to be fair to our web technology friends. If you have feature needs that Electron does not meet, you might want to try NW.js.
", "title": "Технические различия между Electron и NW.js", "description": "" }, "/docs/api/environment-variables": { "locale": "ru-RU", "slug": "environment-variables", "href": "/docs/api/environment-variables", "crowdinFileId": "256315", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/environment-variables.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nУправляй настройкой приложения и его поведением без изменения кода.
\n
Некоторые поведения Electron управляются переменными окружения, потому что они инициализируются раньше, чем флаги командной строки и код приложения.
\nПример терминала POSIX:
\n$ export ELECTRON_ENABLE_LOGGING=true\n$ electron\nПример терминала Windows:
\n> set ELECTRON_ENABLE_LOGGING=true\n> electron\nСледующие переменные окружения предназначены для использования в среде выполнения приложения Electron.
\nNODE_OPTIONSElectron включает поддержку подмножества Node's NODE_OPTIONS. Большинство поддерживаются за исключением тех, которые конфликтуют с использованием Chromium BoringSSL.
Пример:
\nexport NODE_OPTIONS=\"--no-warnings --max-old-space-size=2048\"\nНеподдерживаемые опции:
\n--use-bundled-ca\n--force-fips\n--enable-fips\n--openssl-config\n--use-openssl-ca\nNODE_OPTIONS are explicitly disallowed in packaged apps, except for the following:
--max-http-header-size\n--http-parser\nGOOGLE_API_KEYПоддержка геолокации в Electron требует использования сервиса геолокации Google Cloud Platform. Для включения этой функции получите Ключ Google API и поместите следующий код в ваш файл основного процесса перед открытием любых окон браузера, делающим запросы геолокации:
\nprocess.env.GOOGLE_API_KEY = 'YOUR_KEY_HERE'\nПо умолчанию, новый сгенерированный ключ API Google не может делать запросы геолокации. Чтобы включить веб-сервис геолокации для вашего проекта требуется библиотека API.
\nОбратите внимание. You will need to add a Billing Account to the project associated to the API key for the geolocation webservice to work.
\nELECTRON_NO_ASARОтключает поддержку ASAR. Данная переменная поддерживается только в дочерних процессах, которые установили переменную окружения ELECTRON_RUN_AS_NODE.
ELECTRON_RUN_AS_NODEНачинает процесс как Node.js процесс.
\nIn this mode, you will be able to pass cli options to Node.js as you would when running the normal Node.js executable, with the exception of the following flags:
\nThese flags are disabled owing to the fact that Electron uses BoringSSL instead of OpenSSL when building Node.js' crypto module, and so will not work as designed.
ELECTRON_NO_ATTACH_CONSOLE WindowsНе присоединяться к текущей сессии терминала.
\nELECTRON_FORCE_WINDOW_MENU_BAR LinuxНе использовать глобальное меню в Linux.
\nELECTRON_TRASH LinuxSet the trash implementation on Linux. По умолчанию - gio.
Параметры:
\ngvfs-trashtrash-clikioclient5kioclientСледующие переменные окружения предназначены для использования в среде выполнения приложения Electron во время разработки и отладки.
\nELECTRON_ENABLE_LOGGINGPrints Chromium's internal logging to the console.
\nSetting this variable is the same as passing --enable-logging on the command line. For more info, see --enable-logging in command-line switches.
ELECTRON_LOG_FILESets the file destination for Chromium's internal logging.
\nSetting this variable is the same as passing --log-file on the command line. For more info, see --log-file in command-line switches.
ELECTRON_DEBUG_DRAG_REGIONSAdds coloration to draggable regions on BrowserViews on macOS - draggable regions will be colored green and non-draggable regions will be colored red to aid debugging.
ELECTRON_DEBUG_NOTIFICATIONSAdds extra logs to Notification lifecycles on macOS to aid in debugging. Extra logging will be displayed when new Notifications are created or activated. They will also be displayed when common a tions are taken: a notification is shown, dismissed, its button is clicked, or it is replied to.
Sample output:
\nNotification created (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification displayed (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification activated (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification replied to (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nELECTRON_LOG_ASAR_READSWhen Electron reads from an ASAR file, log the read offset and file path to the system tmpdir. The resulting file can be provided to the ASAR module to optimize file ordering.
ELECTRON_ENABLE_STACK_DUMPINGВыводит содержимое стэка в консоль при сбое Electron приложения.
\nДанная переменная окружения не будет работать, если crashReporter запущен.
ELECTRON_DEFAULT_ERROR_MODE WindowsПоказывает диалог сбоя Windows при сбое Electron приложения.
\nДанная переменная окружения не будет работать, если crashReporter запущен.
ELECTRON_OVERRIDE_DIST_PATHПри запуске из electron пакета, эта переменная дает команду electron использовать указанную сборку Electron вместо загруженной по npm install. Использование:
export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing\nElectron sets some variables in your environment at runtime.
\nORIGINAL_XDG_CURRENT_DESKTOPThis variable is set to the value of XDG_CURRENT_DESKTOP that your application originally launched with. Electron sometimes modifies the value of XDG_CURRENT_DESKTOP to affect other logic within Chromium so if you want access to the original value you should look up this environment variable instead.
GlobalEventpreventDefault VoidFunctionSome of Electrons APIs are tagged with _Experimental_ in the documentation. This tag indicates that the API may not be considered stable and the API may be removed or modified more frequently than other APIs with less warning.
Anyone can request an API be tagged as experimental in a feature PR, disagreements on the experimental nature of a feature can be discussed in the API WG if they can't be resolved in the PR.
\nOnce an API has been stable and in at least two major stable release lines it can be nominated to have its experimental tag removed. This discussion should happen at an API WG meeting. Things to consider when discussing / nominating:
\nid Stringmanifest any - Copy of the extension's manifest data.name Stringpath String - The extension's file path.version Stringurl String - The extension's chrome-extension:// URL.name Stringversion StringElectron частично поддерживает Chrome Extensions API прежде всего для поддержки расширений для DevTools и внутренних Chromium расширений, но он также поддерживает и некоторые другие возможности расширений.
\n\n\nПримечание: Electron не поддерживает пользовательские расширения из магазина Chrome. Идеальная совместимость с реализацией расширений Chrome не является целью проекта Electron.
\n
Electron поддерживает загрузку только распакованных расширение (т.е. файлы .crx не будут работать). Расширения устанавливаются с помощью объекта session. Для загрузки расширения вызовите ses.loadExtension:
const { session } = require('electron')\n\nsession.loadExtension('path/to/unpacked/extension').then(({ id }) => {\n // ...\n})\nЗагруженные расширения не буду автоматически запоминаться при выходе: если вы не вызовите loadExtension при запуске приложения - расширение не будет загружено.
Обратите внимание, что загрузка расширений поддерживается только в постоянных сессиях. Попытка загрузить расширение в сохраненную сессию приведет к ошибке.
\nСмотрите документацию по session чтобы узнать больше о загрузке, выгрузке и получении активных расширений.
Мы поддерживаем следующие API расширений с некоторыми оговорками. Остальные API могут дополнительно поддерживаться, но поддержка API, не перечисленных здесь, является предварительной и может быть удалена.
\nchrome.devtools.inspectedWindowВсе функции этого API поддерживаются.
\nchrome.devtools.networkВсе функции этого API поддерживаются.
\nchrome.devtools.panelsВсе функции этого API поддерживаются.
\nchrome.extensionПоддерживаются только следующие свойства chrome.extension:
chrome.extension.lastErrorПоддерживаются только следующие методы chrome.extension:
chrome.extension.getURLchrome.extension.getBackgroundPagechrome.runtimeПоддерживаются только следующие свойства chrome.runtime:
chrome.runtime.lastErrorchrome.runtime.idПоддерживаются только следующие методы chrome.runtime:
chrome.runtime.getBackgroundPagechrome.runtime.getManifestchrome.runtime.getPlatformInfochrome.runtime.getURLchrome.runtime.connectchrome.runtime.sendMessagechrome.runtime.reloadПоддерживаются только следующие события chrome.runtime:
chrome.runtime.onStartupchrome.runtime.onInstalledchrome.runtime.onSuspendchrome.runtime.onSuspendCanceledchrome.runtime.onConnectchrome.runtime.onMessagechrome.storageПоддерживается только chrome.storage.local; chrome.storage.sync и chrome.storage.managed не поддерживаются.
chrome.tabsПоддерживаются только следующие методы chrome.tabs:
chrome.tabs.sendMessagechrome.tabs.executeScript\n\nПримечание: В Chrome, передача
\n-1в качестве идентификатора вкладки означает \"текущую активную вкладку\". Поскольку в Electron такого понятия нет, передача-1не поддерживается и вызовет ошибку.
chrome.managementПоддерживаются только следующие методы chrome.management:
chrome.management.getAllchrome.management.getchrome.management.getSelfchrome.management.getPermissionWarningsByIdchrome.management.getPermissionWarningsByManifestchrome.management.onEnabledchrome.management.onDisabledchrome.webRequestВсе функции этого API поддерживаются.
\n\n", "title": "Chrome Extension Support", "description": "Примечание: Electron не поддерживает пользовательские расширения из магазина Chrome. Идеальная совместимость с реализацией расширений Chrome не является целью проекта Electron." }, "/docs/faq": { "locale": "ru-RU", "slug": "faq", "href": "/docs/faq", "crowdinFileId": "256121", "githubUrl": "https://github.com/electron/electron/tree/main/docs/faq.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "NOTE: Electron's
\nwebRequestmodule takes precedence overchrome.webRequestif there are conflicting handlers.
При выполнении команды npm install electron, некоторые пользователи сталкиваются с проблемами установки.
В большинстве случаев, эти ошибки являются результатом проблем сети и не связаны с npm пакетом electron. Такие ошибки, как ELIFECYCLE, EAI_AGAIN, ECONNRESET иETIMEDOUT возникают в результате проблем с сетью. Лучшее решение - попытаться переключить сеть, или немного подождать, и попытаться установить снова.
Также вы можете попытаться скачать Electron непосредственно из electron/electron/releases, если установка через npm терпит неудачу.
Chrome для Electron обычно выпускается в течение одной или двух недель после выпуска стабильной версии Chrome. Этот срок не является гарантированным и зависит от объема работ, связанных с обновлением.
\nOnly the stable channel of Chrome is used. If an important fix is in beta or dev channel, we will back-port it.
\nДля получения дополнительной информации, пожалуйста, просмотрите введение в обеспечение безопасности.
\nПосле выпуска новой версии Node.js, мы обычно ждем примерно месяц до обновления в Electron. Это помогает избежать ошибок, которые присутствуют в новых версиях Node.js, что случается довольно часто.
\nНовые возможности Node.js обычно входят в обновления V8, так как Electron использует V8, поставляемый с браузером Chrome, новейшие возможности JavaScript в новой версии Node.js обычно уже входят в Electron.
\nДля передачи данных между веб-страницами (графическими процессами) самым простым способом является использование HTML5 API, который уже доступен в браузерах. Good candidates are Storage API, localStorage, sessionStorage, and IndexedDB.
Alternatively, you can use the IPC primitives that are provided by Electron. To share data between the main and renderer processes, you can use the ipcMain and ipcRenderer modules. To communicate directly between web pages, you can send a MessagePort from one to the other, possibly via the main process using ipcRenderer.postMessage(). Subsequent communication over message ports is direct and does not detour through the main process.
Это происходит, когда переменная, используемая для хранения трея уничтожается сборщиком мусора.
\nЕсли Вы столкнулись с этой проблемой, могут оказаться полезными следующие статьи:
\n\nЕсли Вы хотите это быстро исправить, Вы можете сделать переменную глобальной, заменив для этого следующий код:
\nconst { app, Tray } = require('electron')\napp.whenReady().then(() => {\n const tray = new Tray('/путь/до/иконки.png')\n tray.setTitle('привет мир')\n})\nна этот:
\n{ app, Tray }\nВ связи с интеграцией Node.js с Electron, существуют некоторые дополнительные ключевые слова вставляемые в DOM, такие как: module, exports, и require. Это вызывает проблемы для некоторых библиотек, так как они пытаются вставить такие же имена.
Для решения этой проблемы, Вы можете отключить интеграцию node в Electron:
\n// В основном процессе.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n webPreferences: {\n nodeIntegration: false\n }\n})\nwin.show()\nНо если Вы хотите сохранить возможность использования Node.js или API Electron, Вы должны переименовать переменные на странице перед подключением других библиотек:
\n<head>\n<script>\nwindow.nodeRequire = require;\ndelete window.require;\ndelete window.exports;\ndelete window.module;\n</script>\n<script type=\"text/javascript\" src=\"jquery.js\"></script>\n</head>\nrequire('electron').xxx is undefined (не определено).При использовании встроенного модуля Electron может возникнуть подобная ошибка:
\n> require('electron').webFrame.setZoomFactor(1.0)\nUncaught TypeError: Cannot read property 'setZoomLevel' of undefined\nСкорее всего, Вы используете модуль в неправильном процессе. Например electron.app может быть использован только в главном процессе, в то время как electron.webFrame доступен только в процессах рендеринга.
If sub-pixel anti-aliasing is deactivated, then fonts on LCD screens can look blurry. Пример:
\n
Для анти-алиасинга подпикселя требуется непрозрачный фон, содержащий глифы шрифта. (См. эту проблему для получения дополнительной информации).
\nTo achieve this goal, set the background in the constructor for BrowserWindow:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n backgroundColor: '#fff'\n})\nThe effect is visible only on (some?) LCD screens. Even if you don't see a difference, some of your users may. It is best to always set the background this way, unless you have reasons not to do so.
\nОбратите внимание, что только настройка фона в CSS не имеет желаемого эффекта.
", "title": "FAQ по Electron", "description": "" }, "/docs/api/structures/file-filter": { "locale": "ru-RU", "slug": "file-filter", "href": "/docs/api/structures/file-filter", "crowdinFileId": "256435", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/file-filter.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "name Stringextensions String[]File\n\nИспользует
\nFileиз HTML5 API для найтивной работы с файлами в файловой системе.
Файловый интерфейс DOM предоставляет абстракции над файловой системой, чтобы позволить пользователям работать с ней с помощью файлового API HTML5. Electron добавил атрибут path к интерфейсу File, который предоставляет настоящий путь к файлу в файловой системе.
Пример получения настоящего пути из перетаскиваемого в приложение файла:
\n<div id=\"holder\">\n Drag your file here\n</div>\n\n<script>\n document.addEventListener('drop', (e) => {\n e.preventDefault();\n e.stopPropagation();\n\n for (const f of e.dataTransfer.files) {\n console.log('File(s) you dragged here: ', f.path)\n }\n });\n document.addEventListener('dragover', (e) => {\n e.preventDefault();\n e.stopPropagation();\n });\n</script>\npath String - The path to the file to send.headers Record<string, string> (optional) - Additional headers to be sent.\n\nОткройте окно без панелей инструментов, границ или другого графического «chrome».
\n
Безрамное окно - окно, в котором нет chrome частей окна, например панели инструментов, которые не являются частью веб-страницы. Эти варианты в классе BrowserWindow.
Для создания безрамного окна, нужно установить frame: false в параметрах BrowserWindow:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600, frame: false })\nwin.show()\nThere's an alternative way to specify a chromeless window on macOS and Windows. Instead of setting frame to false which disables both the titlebar and window controls, you may want to have the title bar hidden and your content extend to the full window size, yet still preserve the window controls (\"traffic lights\" on macOS) for standard window actions. Вы можете сделать это, указав параметр titleBarStyle:
hiddenResults in a hidden title bar and a full size content window. On macOS, the title bar still has the standard window controls (“traffic lights”) in the top left.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hidden' })\nwin.show()\nhiddenInsetВ результате скрытый заголовок с альтернативным видом, где кнопки контролирования немного больше вставки от края окна.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })\nwin.show()\ncustomButtonsOnHoverИспользует кастомные кнопки закрыть и уменьшить, которые display при наведении на верхний левый угол окна. The fullscreen button is not available due to restrictions of frameless windows as they interface with Apple's macOS window masks. Эти пользовательские кнопки предотвращают проблемы с событиями мыши, которые случаются со стандартными кнопками панели инструментов. Эта опция применима только для окон без рамки.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover', frame: false })\nwin.show()\nWhen using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS, using one of the titleBarStyles as described above so that the traffic lights are visible, or using titleBarStyle: hidden on Windows, you can access the Window Controls Overlay JavaScript APIs and CSS Environment Variables by setting the titleBarOverlay option to true. Specifying true will result in an overlay with default system colors.
On Windows, you can also specify the color of the overlay and its symbols by setting titleBarOverlay to an object with the options color and symbolColor. If an option is not specified, the color will default to its system color for the window control buttons:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: true\n})\nwin.show()\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: {\n color: '#2f3241',\n symbolColor: '#74b1be'\n }\n})\nwin.show()\nУстановив для параметра transparent значение true, можно также сделать безрамочный окно прозрачным:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ transparent: true, frame: false })\nwin.show()\nresizable to true may make a transparent window stop working on some platforms.blur применяется только к веб-странице, поэтому невозможно применить эффект размытия к содержимому под окном (т.е. другие приложения открываются в системе пользователя).--enable-transparent-visuals --disable-gpu в командной строке, чтобы отключить GPU процессор и позволить ARGB создать прозрачное окно, это вызвано вышестоящей ошибкой, когда альфа-канал не работает на некоторых драйверах NVidia на Linux.Чтобы создать окно клика, т.е. сделать так, чтобы окно игнорировало все события мыши, можно вызвать win.setIgnoreMouseEvents(ignore) API:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.setIgnoreMouseEvents(true)\nИгнорирование сообщений мыши заставляет веб-страницу забыть о движении мыши, что означает, что события движения мыши не будут вырабатываться. В операционных системах Windows дополнительный параметр может быть использован для передачи сообщений о перемещении мыши на веб-странице, что позволяют такие события как mouseleave:
const { ipcRenderer } = require('electron')\nconst el = document.getElementById('clickThroughElement')\nel.addEventListener('mouseenter', () => {\n ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })\n})\nel.addEventListener('mouseleave', () => {\n ipcRenderer.send('set-ignore-mouse-events', false)\n})\n\n// Main process\nconst { ipcMain } = require('electron')\nipcMain.on('set-ignore-mouse-events', (event, ...args) => {\n BrowserWindow.fromWebContents(event.sender).setIgnoreMouseEvents(...args)\n})\nЭто делает переход по веб-странице по окончании el, и возвращается к нормальному состоянию за ее пределами.
По-умолчанию, безрамное окно невозможно перетаскивать. В коде приложения необходимо указать в стилях CSS -webkit-app-region: drag, чтобы за выделенную область было возможно переносить окно (как за заголовок стандартного окна), также можно использовать -webkit-app-region: no-drag для исключения непереносимой области внутри переносимой. Обратите внимание, что в настоящий момент поддерживается прямоугольная форма области.
Примечание: -webkit-app-region: drag имеет проблемы, пока инструменты разработчика открыты. Смотрите Проблемы GitHub для получения дополнительной информации, включая обход.
Чтобы сделать все окно перетаскиваемым, вы можете добавить -webkit-app-region: drag как стиль body:
<body style=\"-webkit-app-region: drag\">\n</body>\nИ обратите внимание, что если вы перетащили окно целиком, вы также должны отметить кнопки как не перетаскиваемые, иначе пользователям было бы невозможно на них нажать:
\nbutton {\n -webkit-app-region: no-drag;\n}\nЕсли вы устанавливаете перетаскиваемым только пользовательский заголовок, вам нужно все кнопки в заголовке сделать без возможности перетаскивания.
\nIn a frameless window the dragging behavior may conflict with selecting text. Например, когда вы перетащите заголовок, вы можете случайно выбрать текст на панели заголовка. Чтобы предотвратить это, вам нужно отключить выбор текста в перетаскиваемой области, такой как:
\n.titlebar {\n -webkit-user-select: none;\n -webkit-app-region: drag;\n}\nНа некоторых платформах перетаскиваемая область будет рассматриваться как неклиентский фрейм, поэтому при щелчке правой кнопкой мыши на ней появится системное меню. Чтобы контекстное меню работало правильно на всех платформах, вы никогда не должны использовать настраиваемое контекстное меню в перетаскиваемых областях.
", "title": "Окно без рамки", "description": "Откройте окно без панелей инструментов, границ или другого графического «chrome»." }, "/docs/tutorial/fuses": { "locale": "ru-RU", "slug": "fuses", "href": "/docs/tutorial/fuses", "crowdinFileId": "256201", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/fuses.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nPackage time feature toggles
\n
For a subset of Electron functionality it makes sense to disable certain features for an entire application. For example, 99% of apps don't make use of ELECTRON_RUN_AS_NODE, these applications want to be able to ship a binary that is incapable of using that feature. We also don't want Electron consumers building Electron from source as that is both a massive technical challenge and has a high cost of both time and money.
Fuses are the solution to this problem, at a high level they are \"magic bits\" in the Electron binary that can be flipped when packaging your Electron app to enable / disable certain features / restrictions. Because they are flipped at package time before you code sign your app the OS becomes responsible for ensuring those bits aren't flipped back via OS level code signing validation (Gatekeeper / App Locker).
\nWe've made a handy module @electron/fuses to make flipping these fuses easy. Check out the README of that module for more details on usage and potential error cases.
require('@electron/fuses').flipFuses(\n // Path to electron\n require('electron'),\n // Fuses to flip\n {\n runAsNode: false\n }\n)\nManually flipping fuses requires editing the Electron binary and modifying the fuse wire to be the sequence of bytes that represent the state of the fuses you want.
\nSomewhere in the Electron binary there will be a sequence of bytes that look like this:
\n| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |\nsentinel_bytes is always this exact string dL7pKGdnNz796PbbjQWNKmHXBZaB9tsXfuse_version is a single byte whose unsigned integer value represents the version of the fuse schemafuse_wire_length is a single byte whose unsigned integer value represents the number of fuses in the following fuse wirefuse_wire is a sequence of N bytes, each byte represents a single fuse and its state.To flip a fuse you find its position in the fuse wire and change it to \"0\" or \"1\" depending on the state you'd like.
\nВы можете просмотреть текущую схему здесь.
", "title": "Electron Fuses", "description": "Package time feature toggles" }, "/docs/api/global-shortcut": { "locale": "ru-RU", "slug": "global-shortcut", "href": "/docs/api/global-shortcut", "crowdinFileId": "256323", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/global-shortcut.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nОтслеживает действия на клавиатуре, когда она не сфокусирована на приложении.
\n
Процесс: Основной
\nМодуль globalShortcut может регистрировать/отменять регистрацию глобальных сочетаний клавиш, так что вы можете настраивать задачи для различных сочетаний клавиш.
Примечание: Сочетания клавиш являются глобальными, они будут работать, даже если ваше приложение не акцентирует внимание на клавиатуре. This module cannot be used before the ready event of the app module is emitted.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+X' shortcut listener.\n const ret = globalShortcut.register('CommandOrControl+X', () => {\n console.log('CommandOrControl+X is pressed')\n })\n\n if (!ret) {\n console.log('ошибка регистрации')\n }\n\n // Проверяем, было ли сочетание зарегистрировано.\n console.log(globalShortcut.isRegistered('CommandOrControl+X'))\n})\n\napp.on('will-quit', () => {\n // Отменяем регистрацию сочетания клавиш.\n globalShortcut.unregister('CommandOrControl+X')\n\n // Отменяем регистрацию всех сочетаний.\n globalShortcut.unregisterAll()\n})\nМодуль globalShortcut имеет следующие методы:
globalShortcut.register(accelerator, callback)accelerator Acceleratorcallback FunctionВозвращает Boolean - было ли сочетание клавиш успешно зарегистрировано.
Registers a global shortcut of accelerator. The callback is called when the registered shortcut is pressed by the user.
Когда accelerator уже занят другими приложениями, этот вызов будет молча завершаться ошибкой. Такое поведение назначается операционными системами, поскольку они не хотят, чтобы приложения боролись за глобальные сочетания клавиш.
\nСледующие accelerators не будут успешно зарегистрированы на macOS 10.14 Mojave, если приложение не было авторизовано в качестве доверенного клиента специальных возможностей:
\nglobalShortcut.registerAll(accelerators, callback)accelerators String[] - массив Accelerator.callback FunctionRegisters a global shortcut of all accelerator items in accelerators. The callback is called when any of the registered shortcuts are pressed by the user.
Когда определенный accelerator уже занят другими приложениями, этот вызов будет молча завершаться ошибкой. Такое поведение назначается операционными системами, поскольку они не хотят, чтобы приложения боролись за глобальные сочетания клавиш.
\nСледующие accelerators не будут успешно зарегистрированы на macOS 10.14 Mojave, если приложение не было авторизовано в качестве доверенного клиента специальных возможностей:
\nglobalShortcut.isRegistered(accelerator)accelerator AcceleratorВозвращает Boolean - независимо от того, зарегистрировало ли это приложение accelerator.
Когда ускоритель уже занят другими приложениями, этот вызов будет возвращать false. Такое поведение назначается операционными системами, поскольку они не хотят, чтобы приложения боролись за глобальные сочетания клавиш.
globalShortcut.unregister(accelerator)accelerator AcceleratorОтмена регистрации сочетания клавиш accelerator.
globalShortcut.unregisterAll()Отменяет регистрацию всех глобальных ярлыков.
", "title": "globalShortcut", "description": "Отслеживает действия на клавиатуре, когда она не сфокусирована на приложении." }, "/docs/glossary": { "locale": "ru-RU", "slug": "glossary", "href": "/docs/glossary", "crowdinFileId": "256123", "githubUrl": "https://github.com/electron/electron/tree/main/docs/glossary.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Данная страница посвящена терминам, которые обычно используются при разработке на Electron.
\nASAR это Atom Shell Archive Format. Asar это простой архив tar-подобного формата, который объединяет файлы в один файл. Electron может читать файлы в архиве без распаковки оного.
Формат ASAR был создан в первую очередь для повышения производительности в Windows при чтения большого количества небольших файлов (например, при загрузке дерева зависимостей JavaScript приложения из node_modules).
Подписывание кода — это процесс, при котором разработчик приложения подписывает свой код цифровой подписью, чтобы после упаковки подтвердить, что он не подделан. И Windows, и macOS реализуют собственную версию подписи кода. Как разработчик классических приложений, важно подписать свой код, если вы планируете распространять его среди широкой общественности.
\nДополнительные сведения можно узнать в обучении подписывание кода.
\nContext isolation is a security measure in Electron that ensures that your preload script cannot leak privileged Electron or Node.js APIs to the web contents in your renderer process. With context isolation enabled, the only way to expose APIs from your preload script is through the contextBridge API.
For more information, read the Context Isolation tutorial.
\nSee also: preload script, renderer process
\nThe C Runtime Library (CRT) is the part of the C++ Standard Library that incorporates the ISO C99 standard library. Библиотеки Visual C++, которые реализуют CRT, поддерживают развитие машинного кода и смешанного собственного и управляемого кода и чисто управляемого кода для разработки .NET.
\nApple Disk Image (DMG) это пакетный формат, который используется в macOS. DMG файлы обычно используются для распространения \"установщиков\" приложения.
\nInput Method Editor. Эта программа позволяет пользователям вводить символы, которые отсутствуют на клавиатуре. Например, это позволяет пользователям Латинской клавиатуры вводить Китайские, Японские, Корейские и Хинди символы.
\nInterface description language. Write function signatures and data types in a format that can be used to generate interfaces in Java, C++, JavaScript, etc.
\nIPC stands for inter-process communication. Electron uses IPC to send serialized JSON messages between the main and renderer processes.
\nсм. также: основной(main) процесс, процесс отображения(renderer)
\nThe main process, commonly a file named main.js, is the entry point to every Electron app. It controls the life of the app, from open to close. Также управляет нативными элементами, такими как Menu, Menu Bar, Dock, Tray, и др. The main process is responsible for creating each new renderer process in the app. The full Node API is built in.
Every app's main process file is specified in the main property in package.json. This is how electron . knows what file to execute at startup.
In Chromium, this process is referred to as the \"browser process\". It is renamed in Electron to avoid confusion with renderer processes.
\nСм. также: процесс, процесс отображения(renderer)
\nAcronym for Apple's Mac App Store. For details on submitting your app to the MAS, see the Mac App Store Submission Guide.
\nAn IPC system for communicating intra- or inter-process, and that's important because Chrome is keen on being able to split its work into separate processes or not, depending on memory pressures etc.
\nСмотри https://chromium.googlesource.com/chromium/src/+/master/mojo/README.md
\nSee also: IPC
\nOn Windows, MSI packages are used by the Windows Installer (also known as Microsoft Installer) service to install and configure applications.
\nMore information can be found in Microsoft's documentation.
\nСобственные модули (также называемые дополнениями в Node.js) это модули написанные на C или C++, которые могут быть загружены в Node.js или Electron используя функцию require(), и используются так, как если бы они были обычным модулем Node.js. Они используются главным образом для предоставления интерфейса между скриптов JavaScript, выполняющийся в Node.js и C/C++ библиотеках.
\nСобственные модули Node поддерживаются в Electron, но учитывая, что Electron предпочитает использовать разные версии V8 для Node, установленного на Вашем компьютере, вы должны вручную указать расположение заголовков Electron'а, когда собираете собственные модули.
\nFor more information, read the [Native Node Modules] tutorial.
\nNotarization is a macOS-specific process where a developer can send a code-signed app to Apple servers to get verified for malicious components through an automated service.
\nSee also: code signing
\nOSR (offscreen rendering) can be used for loading heavy page in background and then displaying it after (it will be much faster). It allows you to render page without showing it on screen.
\nFor more information, read the Offscreen Rendering[osr] tutorial.
\nPreload scripts contain code that executes in a renderer process before its web contents begin loading. These scripts run within the renderer context, but are granted more privileges by having access to Node.js APIs.
\nSee also: renderer process, context isolation
\nПроцесс является экземпляром выполняемой компьютерной программы. Electron приложения используют главный(main) процесс и один или более процессы отображения(renderer), на самом деле работает несколько программ одновременно.
\nВ Node.js и Electron, каждый запущенный процесс имеет объект process. Этот объект является глобальным, предоставляющий информацию о текущем процессе и контроль над ним. Он всегда доступен глобально в приложение без использования require().
См. также: основной(main) процесс, процесс отображения(renderer)
\nThe renderer process is a browser window in your app. Unlike the main process, there can be multiple of these and each is run in a separate process. They can also be hidden.
\nСм. также: процесс, основной(main) процесс
\nThe sandbox is a security feature inherited from Chromium that restricts your renderer processes to a limited set of permissions.
\nFor more information, read the Process Sandboxing tutorial.
\nSee also: process
\nSquirrel является фреймворком с открытым исходным кодом, который позволяет Electron приложениям автоматически обновляться, когда выпустится новая версия. См. autoUpdated API для информации о начале работы с Squirrel.
\nЭтот термин возник в сообществе Unix, где \"userland\" или \"userspace\" относится к программам, которые выполняются за пределами ядра операционной системы. Этот термин был популяризирован в сообществах Node и npm, чтобы различать функции доступные в \"ядре Node\" по сравнению с пакетами опубликованными в реестре npm гораздо более \"пользовательским\" сообществом.
\nКак и Node, Electron сфокусирован на наличии небольшого набора API функций, которые обеспечивают весь необходимый базис для разработки кросс-платформенных настольных приложений. Такая философия позволяет Electron оставаться гибким инструментом, будучи не предписывая того как им пользоваться. Пользовательское пространство позволяет создавать и совместно использовать инструменты, которые обеспечивают дополнительный функционал поверх того, который доступен в ядре.
\nV8 is Google's open source JavaScript engine. It is written in C++ and is used in Google Chrome. V8 can run standalone, or can be embedded into any C++ application.
\nElectron компилирует V8 как часть Chromium а затем указывает Node использовать этот V8 при сборке.
\nV8's version numbers always correspond to those of Google Chrome. Chrome 59 includes V8 5.9, Chrome 58 includes V8 5.8, etc.
\n\nwebview tags are used to embed 'guest' content (such as external web pages) in your Electron app. They are similar to iframes, but differ in that each webview runs in a separate process. Оно не имеет тех же разрешений, так как ваша веб страница и все взаимодействие между вашим приложением и встроенным контентом будут асинхронными. Это позволяет защитить ваше приложение от встраиваемого содержимого.
\n\nGoma is a distributed compiler service for open-source projects such as Chromium and Android.
\n
Electron has a deployment of a custom Goma Backend that we make available to all Electron Maintainers. See the Access section below for details on authentication. There is also a cache-only Goma endpoint that will be used by default if you do not have credentials. Requests to the cache-only Goma will not hit our cluster, but will read from our cache and should result in significantly faster build times.
Currently the only supported way to use Goma is to use our Build Tools. Goma configuration is automatically included when you set up build-tools.
If you are a maintainer and have access to our cluster, please ensure that you run e init with --goma=cluster in order to configure build-tools to use the Goma cluster. If you have an existing config, you can just set \"goma\": \"cluster\" in your config file.
When you are using Goma you can run ninja with a substantially higher j value than would normally be supported by your machine.
Please do not set a value higher than 200 on Windows or Linux and 50 on macOS. We monitor Goma system usage, and users found to be abusing it with unreasonable concurrency will be de-activated.
\nninja -C out/Testing electron -j 200\nIf you're using build-tools, appropriate -j values will automatically be used for you.
If you access http://localhost:8088 on your local machine you can monitor compile jobs as they flow through the goma system.
\nFor security and cost reasons, access to Electron's Goma cluster is currently restricted to Electron Maintainers. If you want access please head to #access-requests in Slack and ping @goma-squad to ask for access. Please be aware that being a maintainer does not automatically grant access and access is determined on a case by case basis.
We have automated monitoring of our Goma cluster and cache at https://status.notgoma.com
\nWe do not provide support for usage of Goma and any issues raised asking for help / having issues will probably be closed without much reason, we do not have the capacity to handle that kind of support.
", "title": "Goma", "description": "Goma is a distributed compiler service for open-source projects such as Chromium and Android." }, "/docs/api/structures/gpu-feature-status": { "locale": "ru-RU", "slug": "gpu-feature-status", "href": "/docs/api/structures/gpu-feature-status", "crowdinFileId": "256439", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/gpu-feature-status.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "2d_canvas String - Canvas.flash_3d String - Flash.flash_stage3d String - Flash Stage3D.flash_stage3d_baseline String - Flash Stage3D Baseline profile.gpu_compositing String - Compositing.multiple_raster_threads String - Multiple Raster Threads.native_gpu_memory_buffers String - Native GpuMemoryBuffers.rasterization String - Rasterization.video_decode String - Video Decode.video_encode String - Video Encode.vpx_decode String - VPx Video Decode.webgl String - WebGL.webgl2 String - WebGL2.Возможные значения:
\ndisabled_software - Software only. Hardware acceleration disabled (yellow)disabled_off - Disabled (red)disabled_off_ok - Disabled (yellow)unavailable_software - Software only, hardware acceleration unavailable (yellow)unavailable_off - Unavailable (red)unavailable_off_ok - Unavailable (yellow)enabled_readback - Hardware accelerated but at reduced performance (yellow)enabled_force - Hardware accelerated on all pages (green)enabled - Hardware accelerated (green)enabled_on - Enabled (green)enabled_force_on - Force enabled (green)deviceId String - Unique identifier for the device.name String - Name of the device.vendorId Integer - The USB vendor ID.productId Integer - The USB product ID.serialNumber String (optional) - The USB device serial number.guid String (optional) - Unique identifier for the HID interface. A device may have multiple HID interfaces.\n\nПокупки внутри приложения в Mac App Store.
\n
Процесс: Основной
\nМодуль inAppPurchase генерирует следующие события:
Возникает при обновлении одной или нескольких транзакций.
\nВозвращает:
\neventtransactions Transaction[] - Массив Transaction объектов.Модуль inAppPurchase имеет следующие методы:
inAppPurchase.purchaseProduct(productID[, quantity])productID String - Идентификаторы продукта для покупки. (Идентификатор com.example.app.product1 это product1).quantity Integer (опционально) - Количество товаров, которое хочет приобрести пользователь.Возвращает Promise<Boolean> - Возвращает true, если товар действителен и добавлен в очередь платежей.
Вы должны начать считывать событие transactions-updated как можно скорее и в любом случае перед тем, как вызвать purchaseProduct.
inAppPurchase.getProducts(productIDs)productIDs String[] - Идентификаторы получаемых продуктов.Возвращает Promise<Product[]> - Разрешает с массив объектов Product.
Получает описания товара.
\ninAppPurchase.canMakePayments()Returns Boolean - whether a user can make a payment.
inAppPurchase.restoreCompletedTransactions()How can I get paid for translation or proofreading of this? Do you pay by Paypal? Can i also create reports for this?-Pls reply-Thank you in adv. This method can be called either to install purchases on additional devices, or to restore purchases for an application that the user deleted and reinstalled.
\nThe payment queue delivers a new transaction for each previously completed transaction that can be restored. Each transaction includes a copy of the original transaction.
\ninAppPurchase.getReceiptURL()Returns String - the path to the receipt.
inAppPurchase.finishAllTransactions()Завершает все ожидающие транзакции.
\ninAppPurchase.finishTransactionByDate(date)date String - Дата завершения транзакции в формате ISO.Завершает отложенные транзакции, соответствующие дате.
", "title": "inAppPurchase", "description": "Покупки внутри приложения в Mac App Store." }, "/docs/tutorial/in-app-purchases": { "locale": "ru-RU", "slug": "in-app-purchases", "href": "/docs/tutorial/in-app-purchases", "crowdinFileId": "256203", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/in-app-purchases.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "If you haven't already, you’ll need to sign the Paid Applications Agreement and set up your banking and tax information in iTunes Connect.
\niTunes Connect Developer Help: Agreements, tax, and banking overview
\nThen, you'll need to configure your in-app purchases in iTunes Connect, and include details such as name, pricing, and description that highlights the features and functionality of your in-app purchase.
\niTunes Connect Developer Help: Create an in-app purchase
\nДля проверки встроенных покупок в разработке с Electron вам нужно изменить CFBundleIdentifier в node_modules/electron/dist/Electron.app/Contents/Info.plist. Вы должны заменить com.github.electron идентификатором приложения, созданного с помощью iTunes Connect.
<key>CFBundleIdentifier</key>\n<string>com.example.app</string>\nHere is an example that shows how to use In-App Purchases in Electron. You'll have to replace the product ids by the identifiers of the products created with iTunes Connect (the identifier of com.example.app.product1 is product1). Note that you have to listen to the transactions-updated event as soon as possible in your app.
// Main process\nconst { inAppPurchase } = require('electron')\nconst PRODUCT_IDS = ['id1', 'id2']\n\n// Listen for transactions as soon as possible.\ninAppPurchase.on('transactions-updated', (event, transactions) => {\n if (!Array.isArray(transactions)) {\n return\n }\n\n // Check each transaction.\n transactions.forEach(function (transaction) {\n const payment = transaction.payment\n\n switch (transaction.transactionState) {\n case 'purchasing':\n console.log(`Purchasing ${payment.productIdentifier}...`)\n break\n\n case 'purchased': {\n console.log(`${payment.productIdentifier} purchased.`)\n\n // Get the receipt url.\n const receiptURL = inAppPurchase.getReceiptURL()\n\n console.log(`Receipt URL: ${receiptURL}`)\n\n // Submit the receipt file to the server and check if it is valid.\n // @see https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html\n // ...\n // If the receipt is valid, the product is purchased\n // ...\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n }\n\n case 'failed':\n\n console.log(`Failed to purchase ${payment.productIdentifier}.`)\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n case 'restored':\n\n console.log(`The purchase of ${payment.productIdentifier} has been restored.`)\n\n break\n case 'deferred':\n\n console.log(`The purchase of ${payment.productIdentifier} has been deferred.`)\n\n break\n default:\n break\n }\n })\n})\n\n// Check if the user is allowed to make in-app purchase.\nif (!inAppPurchase.canMakePayments()) {\n console.log('The user is not allowed to make in-app purchase.')\n}\n\n// Retrieve and display the product descriptions.\ninAppPurchase.getProducts(PRODUCT_IDS).then(products => {\n // Check the parameters.\n if (!Array.isArray(products) || products.length <= 0) {\n console.log('Unable to retrieve the product informations.')\n return\n }\n\n // Display the name and price of each product.\n products.forEach(product => {\n console.log(`The price of ${product.localizedTitle} is ${product.formattedPrice}.`)\n })\n\n // Ask the user which product he/she wants to purchase.\n const selectedProduct = products[0]\n const selectedQuantity = 1\n\n // Purchase the selected product.\n inAppPurchase.purchaseProduct(selectedProduct.productIdentifier, selectedQuantity).then(isProductValid => {\n if (!isProductValid) {\n console.log('The product is not valid.')\n return\n }\n\n console.log('The payment has been added to the payment queue.')\n })\n})\n\n\nОбрабатывает запросы на HTTP/HTTPS-запросы.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
IncomingMessage реализует интерфейс Readable Stream и, тем самым, также и EventEmitter.
Возвращает:
\nchunk Buffer - Часть данных в теле ответа.Событие data является обычным способом передачи данных ответа в применимый код.
Указывает, что тело ответа закончилось. Must be placed before 'data' event.
\nВозникает, когда запрос был отменен во время текущей HTTP-транзакции.
\nВозвращает:
\nerror Error - Содержит строку ошибки, идентифицирующую причину отказа.
Возникает при обнаружении ошибки во время потоковой передачи ответных данных. Например, если сервер закрывает базовый объект во время потоковой передачи ответа, объекту ответа будет выдано error, а событие close впоследствии будет выдано объекту запроса.
IncomingMessage имеет следующие свойства для чтения:
response.statusCodeInteger с указанием кода ответа HTTP.
response.statusMessageString, представляющая сообщение о состоянии HTTP.
response.headersA Record<string, string | string[]> representing the HTTP response headers. The headers object is formatted as follows:
age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, server, or user-agent are discarded.set-cookie is always an array. Duplicates are added to the array.cookie headers, the values are joined together with '; '.response.httpVersionString с указанием номера HTTP протокола. Типичные значения: «1.0» или «1.1». Дополнительно httpVersionMajor и httpVersionMinor являются двумя целочисленными читаемыми свойствами, которые возвращают соответственно основные и второстепенные номера версий HTTP.
response.httpVersionMajorInteger с указанием основной версии протокола HTTP.
response.httpVersionMinorInteger, указание номера младшей версии протокола HTTP.
modifiers String - An array of modifiers of the event, can be shift, control, ctrl, alt, meta, command, cmd, isKeypad, isAutoRepeat, leftButtonDown, middleButtonDown, rightButtonDown, capsLock, numLock, left, right.To install prebuilt Electron binaries, use npm. The preferred method is to install Electron as a development dependency in your app:
npm install electron --save-dev\nСмотри документацию к версиям Electron, чтобы узнать, как управлять версиями Electron в приложении.
\nIf you're in a pinch and would prefer to not use npm install in your local project, you can also run Electron ad-hoc using the npx command runner bundled with npm:
npx electron .\nThe above command will run the current working directory with Electron. Note that any dependencies in your app will not be installed.
\nЕсли хочешь изменить архитектуру загружаемого контента (например, i32 на компьютере с x64), можно использовать аргумент --arch при установке или использовать переменную окружения npm_config_arch:
npm install --arch=ia32 electron\nТак же можно менять платформу приложения (например, win32 или linux) при помощи аргумента --platform:
npm install --platform=win32 electron\nIf you need to use an HTTP proxy, you need to set the ELECTRON_GET_USE_PROXY variable to any value, plus additional environment variables depending on your host system's Node version:
Во время установки модуль electron будет обращаться к @electron/get, чтобы загрузить скомпилированные бинарники для твоей платформы, если она указана в списке релиза (https://github.com/electron/electron/releases/tag/v$VERSION, где $VERSION — версия Electron).
Если доступа к GitHub нет или нужна другая сборка, можно задать зеркало или папку кеша.
\nМожно использовать переменную окружения, чтобы переопределить базовый URL, по которому ищутся бинарники или имена файлов. The URL used by @electron/get is composed as follows:
url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME\nFor instance, to use the China CDN mirror:
\nELECTRON_MIRROR=\"https://cdn.npm.taobao.org/dist/electron/\"\nBy default, ELECTRON_CUSTOM_DIR is set to v$VERSION. To change the format, use the {{ version }} placeholder. For example, version-{{ version }} resolves to version-5.0.0, {{ version }} resolves to 5.0.0, and v{{ version }} is equivalent to the default. As a more concrete example, to use the China non-CDN mirror:
ELECTRON_MIRROR=\"https://npm.taobao.org/mirrors/electron/\"\nELECTRON_CUSTOM_DIR=\"{{ version }}\"\nThe above configuration will download from URLs such as https://npm.taobao.org/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip.
If your mirror serves artifacts with different checksums to the official Electron release you may have to set ELECTRON_USE_REMOTE_CHECKSUMS=1 to force Electron to use the remote SHASUMS256.txt file to verify the checksum instead of the embedded checksums.
Кроме того, можно заменить локальный кеш. @electron/get скачивает файлы в кеш, чтобы снизить нагрузку на сеть. Папку с кешем можно использовать для кастомных сборок или, чтобы полностью избежать сетевого трафика.
$XDG_CACHE_HOME или ~/.cache/electron/~/Library/Caches/electron/$LOCALAPPDATA/electron/Cache или ~/AppData/Local/electron/Cache/В старом Electron возможно использование папки ~/.electron.
Также можно переопределить место кеша с помощью переменной окружения electron_config_cache.
The cache contains the version's official zip file as well as a checksum, stored as a text file. A typical cache might look like this:
\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9electron-v1.7.9-darwin-x64.zip\n│ └── electron-v1.7.9-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1electron-v1.8.1-darwin-x64.zip\n│ └── electron-v1.8.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1electron-v1.8.2-beta.1-darwin-x64.zip\n│ └── electron-v1.8.2-beta.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2electron-v1.8.2-beta.2-darwin-x64.zip\n│ └── electron-v1.8.2-beta.2-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3electron-v1.8.2-beta.3-darwin-x64.zip\n│ └── electron-v1.8.2-beta.3-darwin-x64.zip\n└── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3SHASUMS256.txt\n └── SHASUMS256.txt\nUnder the hood, Electron's JavaScript API binds to a binary that contains its implementations. Because this binary is crucial to the function of any Electron app, it is downloaded by default in the postinstall step every time you install electron from the npm registry.
However, if you want to install your project's dependencies but don't need to use Electron functionality, you can set the ELECTRON_SKIP_BINARY_DOWNLOAD environment variable to prevent the binary from being downloaded. For instance, this feature can be useful in continuous integration environments when running unit tests that mock out the electron module.
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install\nПри выполнении команды npm install electron, некоторые пользователи сталкиваются с проблемами установки.
В большинстве случаев, эти ошибки являются результатом проблем сети и не связаны с npm пакетом electron. Такие ошибки, как ELIFECYCLE, EAI_AGAIN, ECONNRESET иETIMEDOUT возникают в результате проблем с сетью. Лучшее решение - попытаться переключить сеть, или немного подождать, и попытаться установить снова.
You can also attempt to download Electron directly from electron/electron/releases if installing via npm is failing.
If installation fails with an EACCESS error you may need to fix your npm permissions.
If the above error persists, the unsafe-perm flag may need to be set to true:
\nsudo npm install electron --unsafe-perm=true\nНа слабой сети следует использовать аргумент --verbose, чтобы задействовать замедленную загрузку:
npm install --verbose electron\nЕсли нужно перезагрузить файлы без кеша, нужно использовать переменную окружения force_no_cache = true.
Добро пожаловать в документацию Electron! Если вы впервые разрабатываете приложение на Electron, начните знакомство с раздела Getting Started, чтобы ознакомиться с основами. В противном случае, не стесняйтесь изучать наши руководства и документацию по API!
\nElectron - это фреймворк для разработки десктопных приложений с использованием HTML, CSS и JavaScript. В двоичный код Electron уже встроены Chromium и Node.js, и это позволяет вам поддерживать только JavaScript код и создавать кроссплатформенные приложение, которые будут работать как на Windows, так и на macOS и Linux без необходимости иметь собственный опыт разработки.
\nДанная документация опирается на предположение о том, что читатель знаком как с Node.js, так и с веб-разработкой в общем виде. Если вы хотите стать более уверенными в какой-либо из этих областей разработки, то мы рекомендуем вам следующие ресурсы для ознакомления:
\n\nБолее того, вы будете лучше понимать, как работает Electron, если вы ознакомитесь с моделью процессов Chromium. Вы можете ознакомиться с кратким обзором архитектуры Chrome с помощью комикса Chrome, который был выпущен вместе с релизом Chrome в 2008 году. Несмотря на то, что с тех пор прошло более десяти лет, основные принципы, представленные в комиксе, по-прежнему полезны для понимания Electron.
\nElectron Fiddle - песочница, написанная на Electron и поддерживаемая разработчиками Electron. Мы настоятельно рекомендуем установить его в качестве обучающего инструмента для экспериментов с API-интерфейсами Electron или для создания прототипов функций во время разработки.
\nFiddle также прекрасно интегрируется с нашей документацией. При просмотре примеров в наших учебниках вы часто видите кнопку \"Открыть в Electron Fiddle\" под блоком кода. Если у вас установлен Fiddle эта кнопка откроет , fiddle.electronjs. rg ссылка, которая автоматически загрузит пример в Fiddle, не требуется.
Вы застряли где-нибудь? Вот несколько ссылок для поиска:
\nelectron, пожалуйста, проверьте на GitHub issue tracker, чтобы увидеть, соответствуют ли какие-либо проблемы вашей проблеме. Если нет, заполните наш шаблон отчета об ошибке и отправьте новый выпуск.readOperationCount Number - The number of I/O read operations.writeOperationCount Number - The number of I/O write operations.otherOperationCount Number - Then number of I/O other operations.readTransferCount Number - The number of I/O read transfers.writeTransferCount Number - The number of I/O write transfers.otherTransferCount Number - Then number of I/O other transfers.\n\nАсинхронно взаимодействуйте с процессами рендеринга из главного процесса.
\n
Процесс: Основной
\nМодуль ipcMain представляет собой Event Emitter. При использовании в основном процессе он обрабатывает асинхронные и синхронные сообщения, отправленные из процесса рендеринга (веб-страницы). Сообщения, отправленные из процесса рендеринга, будут направлены в этот модуль.
Кроме того, существует возможность пересылать сообщения из главного процесса в процессы рендеринга. Более подробно это описано в webContents.send.
\nchannel.event.returnValue.event.reply(...). Этот вспомогательный метод автоматически обрабатывает сообщения, поступающие из фреймов, которые не являются основным фреймом (например, iframe), в то время как event.sender.send(...) всегда будет посылать в основной фрейм.Пример отправки и обработки сообщений между render и main процессами:
\n// В main процессе.\nconst { ipcMain } = require('electron')\nipcMain.on('asynchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.reply('asynchronous-reply', 'pong')\n})\n\nipcMain.on('synchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.returnValue = 'pong'\n})\n// В renderer процессе (web страница).\n// NB. Electron APIs are only accessible from preload, unless contextIsolation is disabled.\n// See https://www.electronjs.org/docs/tutorial/process-model#preload-scripts for more details.\nconst { ipcRenderer } = require('electron')\nconsole.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // prints \"pong\"\n\nipcRenderer.on('asynchronous-reply', (event, arg) => {\n console.log(arg) // prints \"pong\"\n})\nipcRenderer.send('asynchronous-message', 'ping')\nМодуль ipcMain имеет следующие методы для прослушивая событий:
ipcMain.on(channel, listener)channel String (Строка)listener Function (Функция)event IpcMainEvent...args any[]Слушает channel, когда приходит новое сообщение listener вызовется с listener(event, args...).
ipcMain.once(channel, listener)channel String (Строка)listener Function (Функция)event IpcMainEvent...args any[]Adds a one time listener function for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed.
ipcMain.removeListener(channel, listener)channel String (Строка)listener Function (Функция)...args any[]Удаляет указанный listener из массива слушателей конкретного channel.
ipcMain.removeAllListeners([channel])channel String (опционально)Удаляет всех слушателей channel.
ipcMain.handle(channel, listener)channel String (Строка)listener Function<Promise\\event IpcMainInvokeEvent...args any[]Adds a handler for an invokeable IPC. This handler will be called whenever a renderer calls ipcRenderer.invoke(channel, ...args).
Если listener возвращает Promise, то конечный результат Promise, будет возвращен в качестве ответа удаленному вызывающему объекту. В противном случае, возвращаемое значение слушателя будет использоваться как значение ответа.
// Main process\nipcMain.handle('my-invokable-ipc', async (event, ...args) => {\n const result = await somePromise(...args)\n return result\n})\n\n// Renderer process\nasync () => {\n const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)\n // ...\n}\nevent, которое передается обработчику в качестве первого аргумента, такое же, какое передается обычному прослушивателю событий. Оно включает информацию о том, какой WebContents является источником запроса на вызов.
Errors thrown through handle in the main process are not transparent as they are serialized and only the message property from the original error is provided to the renderer process. Please refer to #24427 for details.
ipcMain.handleOnce(channel, listener)channel String (Строка)listener Function<Promise\\event IpcMainInvokeEvent...args any[]Handles a single invokeable IPC message, then removes the listener. See ipcMain.handle(channel, listener).
ipcMain.removeHandler(channel)channel String (Строка)Удаляет обработчик для channel, если он присутствует.
Документацию для объекта event, передаваемого в callback, можно найти в документации по структуре ipc-main-event.
Документацию по объекту event, переданном обратным вызовом handle, можно найти в документации по структуре ipc-main-invoke-event.
EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagereturnValue any - Set this to the value to be returned in a synchronous messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this messageports MessagePortMain[] - A list of MessagePorts that were transferred with this messagereply Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to \"reply\" to the sent message in order to guarantee the reply will go to the correct process and frame.channel String...args any[]EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this message\n\nАсинхронное взаимодействие между процессом визуализации и основным процессом.
\n
Процесс: Графический
\nМодуль ipcRenderer представляет собой EventEmitter. Он предоставляет несколько методов, чтобы вы могли отправлять синхронные и асинхронные сообщения из процесса визуализации (веб-страницы) в основной процесс. Вы также можете получать ответы от главного процесса.
Примеры кода смотрите в ipcMain.
\nМодуль ipcRenderer имеет следующие методы для прослушивания событий и отправки сообщений:
ipcRenderer.on(channel, listener)channel String (Строка)listener Function (Функция)event IpcRendererEvent...args any[]Слушает channel, когда приходит новое сообщение listener вызовется с listener(event, args...).
ipcRenderer.once(channel, listener)channel String (Строка)listener Function (Функция)event IpcRendererEvent...args any[]Adds a one time listener function for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed.
ipcRenderer.removeListener(channel, listener)channel String (Строка)listener Function (Функция)...args any[]Удаляет указанный listener из массива слушателей конкретного channel.
ipcRenderer.removeAllListeners(channel)channel String (Строка)Удаляет всех слушателей или слушателей из указанного channel.
ipcRenderer.send(channel, ...args)channel String (Строка)...args any[]Send an asynchronous message to the main process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
Основной процесс обрабатывает его путем прослушивания channel с модулем ipcMain.
If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you want to receive a single response from the main process, like the result of a method call, consider using ipcRenderer.invoke.
ipcRenderer.invoke(channel, ...args)channel String (Строка)...args any[]Возвращает Promise<any> - Разрешается с ответом от основного процесса.
Send a message to the main process via channel and expect a result asynchronously. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
Основной процесс должен прослушивать channel с ipcMain.handle().
Например:
\n// Renderer process\nipcRenderer.invoke('some-name', someArgument).then((result) => {\n // ...\n})\n\n// Main process\nipcMain.handle('some-name', async (event, someArgument) => {\n const result = await doSomeWork(someArgument)\n return result\n})\nIf you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you do not need a response to the message, consider using ipcRenderer.send.
ipcRenderer.sendSync(channel, ...args)channel String (Строка)...args any[]Возвращает any - Значение, отправленное обработчиком ipcMain.
Send a message to the main process via channel and expect a result synchronously. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
Основной процесс обрабатывает его, прослушивая channel с помощью модуля ipcMain, и отвечая, установив event.returnValue.
\n\n⚠️ WARNING: Sending a synchronous message will block the whole renderer process until the reply is received, so use this method only as a last resort. It's much better to use the asynchronous version,
\ninvoke().
ipcRenderer.postMessage(channel, message, [transfer])Send a message to the main process, optionally transferring ownership of zero or more MessagePort objects.
The transferred MessagePort objects will be available in the main process as MessagePortMain objects by accessing the ports property of the emitted event.
Например:
\n// Renderer process\nconst { port1, port2 } = new MessageChannel()\nipcRenderer.postMessage('port', { message: 'hello' }, [port1])\n\n// Main process\nipcMain.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nFor more information on using MessagePort and MessageChannel, see the MDN documentation.
ipcRenderer.sendTo(webContentsId, channel, ...args)webContentsId Numberchannel String (Строка)...args any[]Отправляет сообщение в окно с помощью webContentsId через channel.
ipcRenderer.sendToHost(channel, ...args)channel String (Строка)...args any[]Как ipcRenderer.send, но событие будет отправлено в элемент <webview> на главной странице вместо основного процесса.
Документацию для объекта event, передаваемого в callback, можно найти в документации по структуре ipc-renderer-event.
Eventsender IpcRenderer - The IpcRenderer instance that emitted the event originallysenderId Integer - The webContents.id that sent the message, you can call event.sender.sendTo(event.senderId, ...) to reply to the message, see ipcRenderer.sendTo for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set event.senderId to 0.ports MessagePort[] - A list of MessagePorts that were transferred with this messageДля любого вопроса есть три основных способа, которыми человек может сделать вклад:
\nelectron/electron issue tracker.electron/electron в конкретный и рецензируемый способ.\"Finding Support\" имеет список ресурсов для получения помощи по программированию, сообщения о проблемах безопасности, и многое другое. Пожалуйста, используйте трекер ошибок только для ошибок!
\nЧтобы сообщить об ошибке:
\nWhen opening a new issue in the electron/electron issue tracker, users will be presented with a template that should be filled in.
If you believe that you have found a bug in Electron, please fill out the template to the best of your ability.
\nДвумя наиболее важными частями информации, необходимой для оценки отчета, являются описание ошибки и простой тестовый случай для его создания. Легче исправить ошибку, если она может быть воспроизведена.
\nСмотрите Как создать минимальный, завершенный и проверяемый пример.
\nЧаще всего открытые вопросы могут включать в себя обсуждение. Некоторые участники могут иметь различные мнения, в том числе, является ли поведение ошибкой или функцией. Эта дискуссия является частью процесса и должна быть целенаправленной, полезной, и профессиональной.
\nКраткие ответы, которые не предоставляют ни дополнительного контекста, ни вспомогательных деталей не полезны или не профессиональны. Многих такие ответы раздражают и не дружественны.
\nContributors are encouraged to solve issues collaboratively and help one another make progress. If you encounter an issue that you feel is invalid, or which contains incorrect information, explain why you feel that way with additional supporting context, and be willing to be convinced that you may be wrong. При этом мы часто можем достичь правильного результата быстрее.
\nБольшинство проблем решается путем открытия pull-запроса. The process for opening and reviewing a pull request is similar to that of opening and triaging issues, but carries with it a necessary review and approval workflow that ensures that the proposed changes meet the minimal quality and functional guidelines of the Electron project.
", "title": "Задачи в Electron", "description": "" }, "/docs/api/structures/jump-list-category": { "locale": "ru-RU", "slug": "jump-list-category", "href": "/docs/api/structures/jump-list-category", "crowdinFileId": "256451", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/jump-list-category.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "type String (optional) - One of the following:tasks - Items in this category will be placed into the standard Tasks category. There can be only one such category, and it will always be displayed at the bottom of the Jump List.frequent - Displays a list of files frequently opened by the app, the name of the category and its items are set by Windows.recent - Displays a list of files recently opened by the app, the name of the category and its items are set by Windows. Items may be added to this category indirectly using app.addRecentDocument(path).custom - Displays tasks or file links, name must be set by the app.name String (optional) - Must be set if type is custom, otherwise it should be omitted.items JumpListItem - Array of JumpListItem objects if type is tasks or custom, otherwise it should be omitted.Note: If a JumpListCategory object has neither the type nor the name property set then its type is assumed to be tasks. If the name property is set but the type property is omitted then the type is assumed to be custom.
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
type String (optional) - One of the following:task - A task will launch an app with specific arguments.separator - Can be used to separate items in the standard Tasks category.file - A file link will open a file using the app that created the Jump List, for this to work the app must be registered as a handler for the file type (though it doesn't have to be the default handler).path String (optional) - Path of the file to open, should only be set if type is file.program String (optional) - Path of the program to execute, usually you should specify process.execPath which opens the current program. Should only be set if type is task.args String (optional) - The command line arguments when program is executed. Should only be set if type is task.title String (optional) - The text to be displayed for the item in the Jump List. Should only be set if type is task.description String (optional) - Description of the task (displayed in a tooltip). Should only be set if type is task. Maximum length 260 characters.iconPath String (optional) - The absolute path to an icon to be displayed in a Jump List, which can be an arbitrary resource file that contains an icon (e.g. .ico, .exe, .dll). You can usually specify process.execPath to show the program icon.iconIndex Number (optional) - The index of the icon in the resource file. If a resource file contains multiple icons this value can be used to specify the zero-based index of the icon that should be displayed for this task. If a resource file contains only one icon, this property should be set to zero.workingDirectory String (optional) - The working directory. Default is empty.ctrlKey Boolean (optional) - whether the Control key was used in an accelerator to trigger the EventmetaKey Boolean (optional) - whether a meta key was used in an accelerator to trigger the EventshiftKey Boolean (optional) - whether a Shift key was used in an accelerator to trigger the EventaltKey Boolean (optional) - whether an Alt key was used in an accelerator to trigger the EventtriggeredByAccelerator Boolean (optional) - whether an accelerator was used to trigger the event as opposed to another user gesture like mouse clickInputEventtype String - The type of the event, can be keyDown, keyUp or char.keyCode String - The character that will be sent as the keyboard event. Should only use the valid key codes in Accelerator.Эта функция позволяет настроить локальные и глобальные сочетания клавиш для приложения Electron.
\nLocal keyboard shortcuts are triggered only when the application is focused. To configure a local keyboard shortcut, you need to specify an accelerator property when creating a MenuItem within the Menu module.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { Menu, MenuItem } = require('electron')\n\nconst menu = new Menu()\nmenu.append(new MenuItem({\n label: 'Electron',\n submenu: [{\n role: 'help',\n accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Alt+Shift+I',\n click: () => { console.log('Electron rocks!') }\n }]\n}))\n\nMenu.setApplicationMenu(menu)\n\n\nNOTE: In the code above, you can see that the accelerator differs based on the user's operating system. For MacOS, it is
\nAlt+Cmd+I, whereas for Linux and Windows, it isAlt+Shift+I.
After launching the Electron application, you should see the application menu along with the local shortcut you just defined:
\n
If you click Help or press the defined accelerator and then open the terminal that you ran your Electron application from, you will see the message that was generated after triggering the click event: \"Electron rocks!\".
To configure a global keyboard shortcut, you need to use the globalShortcut module to detect keyboard events even when the application does not have keyboard focus.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n globalShortcut.register('Alt+CommandOrControl+I', () => {\n console.log('Electron loves global shortcuts!')\n })\n}).then(createWindow)\n\n\nNOTE: In the code above, the
\nCommandOrControlcombination usesCommandon macOS andControlon Windows/Linux.
After launching the Electron application, if you press the defined key combination then open the terminal that you ran your Electron application from, you will see that Electron loves global shortcuts!
\nIf you want to handle keyboard shortcuts within a BrowserWindow, you can listen for the keyup and keydown DOM events inside the renderer process using the addEventListener() API.
function handleKeyPress(event) {\n // You can put code here to handle the keypress.\n document.getElementById(\"last-keypress\").innerText = event.key;\n console.log(`You pressed ${event.key}`);\n}\n\nwindow.addEventListener('keyup', handleKeyPress, true);\n\n\nNote: the third parameter
\ntrueindicates that the listener will always receive key presses before other listeners so they can't havestopPropagation()called on them.
Событие before-input-event генерируется перед отправкой событий keydown и keyup на странице. It can be used to catch and handle custom shortcuts that are not visible in the menu.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, BrowserWindow } = require('electron')\n\napp.whenReady().then(() => {\n const win = new BrowserWindow({ width: 800, height: 600 })\n\n win.loadFile('index.html')\n win.webContents.on('before-input-event', (event, input) => {\n if (input.control && input.key.toLowerCase() === 'i') {\n console.log('Pressed Control+I')\n event.preventDefault()\n }\n })\n})\nAfter launching the Electron application, if you open the terminal that you ran your Electron application from and press Ctrl+I key combination, you will see that this key combination was successfully intercepted.
If you don't want to do manual shortcut parsing, there are libraries that do advanced key detection, such as mousetrap. Below are examples of usage of the mousetrap running in the Renderer process:
Mousetrap.bind('4', () => { console.log('4') })\nMousetrap.bind('?', () => { console.log('show shortcuts!') })\nMousetrap.bind('esc', () => { console.log('escape') }, 'keyup')\n\n// combinations\nMousetrap.bind('command+shift+k', () => { console.log('command shift k') })\n\n// map multiple combinations to the same callback\nMousetrap.bind(['command+k', 'ctrl+k'], () => {\n console.log('command k or control k')\n\n // return false to prevent default behavior and stop event from bubbling\n return false\n})\n\n// gmail style sequences\nMousetrap.bind('g i', () => { console.log('go to inbox') })\nMousetrap.bind('* a', () => { console.log('select all') })\n\n// konami code!\nMousetrap.bind('up up down down left right left right b a enter', () => {\n console.log('konami code')\n})\ntitle: Launching Your Electron App From a URL In Another App\ndescription: This guide will take you through the process of setting your electron app as the default handler for a specific protocol.\nslug: launch-app-from-url-in-another-app
\nThis guide will take you through the process of setting your Electron app as the default handler for a specific protocol.
\nBy the end of this tutorial, we will have set our app to intercept and handle any clicked URLs that start with a specific protocol. In this guide, the protocol we will use will be \"electron-fiddle://\".
First, we will import the required modules from electron. These modules help control our application lifecycle and create a native browser window.
const { app, BrowserWindow, shell } = require('electron')\nconst path = require('path')\nNext, we will proceed to register our application to handle all \"electron-fiddle://\" protocols.
if (process.defaultApp) {\n if (process.argv.length >= 2) {\n app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])\n }\n} else {\n app.setAsDefaultProtocolClient('electron-fiddle')\n}\nWe will now define the function in charge of creating our browser window and load our application's index.html file.
const createWindow = () => {\n // Create the browser window.\n mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n mainWindow.loadFile('index.html')\n}\nIn this next step, we will create our BrowserWindow and tell our application how to handle an event in which an external protocol is clicked.
This code will be different in Windows compared to MacOS and Linux. This is due to Windows requiring additional code in order to open the contents of the protocol link within the same Electron instance. Read more about this here.
\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Someone tried to run a second instance, we should focus our window.\n if (mainWindow) {\n if (mainWindow.isMinimized()) mainWindow.restore()\n mainWindow.focus()\n }\n })\n\n // Create mainWindow, load the rest of the app, etc...\n app.whenReady().then(() => {\n createWindow()\n })\n\n // Handle the protocol. In this case, we choose to show an Error Box.\n app.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n })\n}\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// Некоторые интерфейсы API могут использоваться только после возникновения этого события.\napp.whenReady().then(() => {\n createWindow()\n})\n\n// Handle the protocol. In this case, we choose to show an Error Box.\napp.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n})\nFinally, we will add some additional code to handle when someone closes our application.
\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') app.quit()\n})\nOn macOS and Linux, this feature will only work when your app is packaged. It will not work when you're launching it in development from the command-line. When you package your app you'll need to make sure the macOS Info.plist and the Linux .desktop files for the app are updated to include the new protocol handler. Some of the Electron tools for bundling and distributing apps handle this for you.
If you're using Electron Forge, adjust packagerConfig for macOS support, and the configuration for the appropriate Linux makers for Linux support, in your Forge configuration (please note the following example only shows the bare minimum needed to add the configuration changes):
{\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"protocols\": [\n {\n \"name\": \"Electron Fiddle\",\n \"schemes\": [\"electron-fiddle\"]\n }\n ]\n },\n \"makers\": [\n {\n \"name\": \"@electron-forge/maker-deb\",\n \"config\": {\n \"mimeType\": [\"x-scheme-handler/electron-fiddle\"]\n }\n }\n ]\n }\n }\n}\nFor macOS support:
\nIf you're using Electron Packager's API, adding support for protocol handlers is similar to how Electron Forge is handled, except protocols is part of the Packager options passed to the packager function.
const packager = require('electron-packager')\n\npackager({\n // ...other options...\n protocols: [\n {\n name: 'Electron Fiddle',\n schemes: ['electron-fiddle']\n }\n ]\n\n}).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))\n .catch(err => console.error(`ERROR: ${err.message}`))\nIf you're using Electron Packager's CLI, use the --protocol and --protocol-name flags. For example:
npx electron-packager . --protocol=electron-fiddle --protocol-name=\"Electron Fiddle\"\nAfter you start your Electron app, you can enter in a URL in your browser that contains the custom protocol, for example \"electron-fiddle://open\" and observe that the application will respond and show an error dialog box.
On many Linux environments, you can add custom entries to the system launcher by modifying the .desktop file. For Canonical's Unity documentation, see Adding Shortcuts to a Launcher. For details on a more generic implementation, see the freedesktop.org Specification.
\n\nNOTE: The screenshot above is an example of launcher shortcuts in Audacious audio player
\n
To create a shortcut, you need to provide Name and Exec properties for the entry you want to add to the shortcut menu. Unity will execute the command defined in the Exec field after the user clicked the shortcut menu item. An example of the .desktop file may look as follows:
Actions=PlayPause;Next;Previous\n\n[Desktop Action PlayPause]\nName=Play-Pause\nExec=audacious -t\nOnlyShowIn=Unity;\n\n[Desktop Action Next]\nName=Next\nExec=audacious -f\nOnlyShowIn=Unity;\n\n[Desktop Action Previous]\nName=Previous\nExec=audacious -r\nOnlyShowIn=Unity;\nThe preferred way for Unity to instruct your application on what to do is using parameters. You can find them in your application in the global variable process.argv.
This guide provides information on:
\nTo sign Electron apps, the following tools must be installed first:
\nYou also have to register an Apple Developer account and join the Apple Developer Program.
\nElectron apps can be distributed through Mac App Store or outside it. Each way requires different ways of signing and testing. This guide focuses on distribution via Mac App Store, but will also mention other methods.
\nThe following steps describe how to get the certificates from Apple, how to sign Electron apps, and how to test them.
\nThe simplest way to get signing certificates is to use Xcode:
\nThe \"Apple Development\" certificate is used to sign apps for development and testing, on machines that have been registered on Apple Developer website. The method of registration will be described in Prepare provisioning profile.
\nApps signed with the \"Apple Development\" certificate cannot be submitted to Mac App Store. For that purpose, apps must be signed with the \"Apple Distribution\" certificate instead. But note that apps signed with the \"Apple Distribution\" certificate cannot run directly, they must be re-signed by Apple to be able to run, which will only be possible after being downloaded from the Mac App Store.
\nYou may notice that there are also other kinds of certificates.
\nThe \"Developer ID Application\" certificate is used to sign apps before distributing them outside the Mac App Store.
\nThe \"Developer ID Installer\" and \"Mac Installer Distribution\" certificates are used to sign the Mac Installer Package instead of the app itself. Most Electron apps do not use Mac Installer Package so they are generally not needed.
\nThe full list of certificate types can be found here.
\nApps signed with \"Apple Development\" and \"Apple Distribution\" certificates can only run under App Sandbox, so they must use the MAS build of Electron. However, the \"Developer ID Application\" certificate does not have this restrictions, so apps signed with it can use either the normal build or the MAS build of Electron.
\nApple has been changing the names of certificates during past years, you might encounter them when reading old documentations, and some utilities are still using one of the old names.
\nIf you want to test your app on your local machine before submitting your app to the Mac App Store, you have to sign the app with the \"Apple Development\" certificate with the provisioning profile embedded in the app bundle.
\nTo create a provisioning profile, you can follow the below steps:
\n/path/to/yourapp.provisionprofile.Apps submitted to the Mac App Store must run under Apple's App Sandbox, and only the MAS build of Electron can run with the App Sandbox. The standard darwin build of Electron will fail to launch when run under App Sandbox.
\nWhen signing the app with electron-osx-sign, it will automatically add the necessary entitlements to your app's entitlements, but if you are using custom entitlements, you must ensure App Sandbox capacity is added:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n </dict>\n</plist>\nelectron-osx-signIf you are signing your app without using electron-osx-sign, you must ensure the app bundle's entitlements have at least following keys:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.application-groups</key>\n <array>\n <string>TEAM_ID.your.bundle.id</string>\n </array>\n </dict>\n</plist>\nThe TEAM_ID should be replaced with your Apple Developer account's Team ID, and the your.bundle.id should be replaced with the App ID of the app.
And the following entitlements must be added to the binaries and helpers in the app's bundle:
\n\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.inherit</key>\n <true/>\n </dict>\n</plist>\nAnd the app bundle's Info.plist must include ElectronTeamID key, which has your Apple Developer account's Team ID as its value:
<plist version=\"1.0\">\n<dict>\n ...\n <key>ElectronTeamID</key>\n <string>TEAM_ID</string>\n</dict>\n</plist>\nWhen using electron-osx-sign the ElectronTeamID key will be added automatically by extracting the Team ID from the certificate's name. You may need to manually add this key if electron-osx-sign could not find the correct Team ID.
To sign an app that can run on your development machine, you must sign it with the \"Apple Development\" certificate and pass the provisioning profile to electron-osx-sign.
electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile\nIf you are signing without electron-osx-sign, you must place the provisioning profile to YourApp.app/Contents/embedded.provisionprofile.
The signed app can only run on the machines that registered by the provisioning profile, and this is the only way to test the signed app before submitting to Mac App Store.
\nTo sign an app that will be submitted to Mac App Store, you must sign it with the \"Apple Distribution\" certificate. Note that apps signed with this certificate will not run anywhere, unless it is downloaded from Mac App Store.
\nelectron-osx-sign YourApp.app --identity='Apple Distribution'\nIf you don't plan to submit the app to Mac App Store, you can sign it the \"Developer ID Application\" certificate. In this way there is no requirement on App Sandbox, and you should use the normal darwin build of Electron if you don't use App Sandbox.
\nelectron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess\nBy passing --no-gatekeeper-assess, the electron-osx-sign will skip the macOS GateKeeper check as your app usually has not been notarized yet by this step.
This guide does not cover App Notarization, but you might want to do it otherwise Apple may prevent users from using your app outside Mac App Store.
\nAfter signing the app with the \"Apple Distribution\" certificate, you can continue to submit it to Mac App Store.
\nHowever, this guide do not ensure your app will be approved by Apple; you still need to read Apple's Submitting Your App guide on how to meet the Mac App Store requirements.
\nThe Application Loader should be used to upload the signed app to iTunes Connect for processing, making sure you have created a record before uploading.
\nIf you are seeing errors like private APIs uses, you should check if the app is using the MAS build of Electron.
\nAfter uploading, you should submit your app for review.
\nIn order to satisfy all requirements for app sandboxing, the following modules have been disabled in the MAS build:
\ncrashReporterautoUpdaterand the following behaviors have been changed:
\nAlso, due to the usage of app sandboxing, the resources which can be accessed by the app are strictly limited; you can read App Sandboxing for more information.
\nDepending on which Electron APIs your app uses, you may need to add additional entitlements to your app's entitlements file. Otherwise, the App Sandbox may prevent you from using them.
\nEnable outgoing network connections to allow your app to connect to a server:
\n<key>com.apple.security.network.client</key>\n<true/>\nEnable incoming network connections to allow your app to open a network listening socket:
\n<key>com.apple.security.network.server</key>\n<true/>\nSee the Enabling Network Access documentation for more details.
\n<key>com.apple.security.files.user-selected.read-only</key>\n<true/>\nSee the Enabling User-Selected File Access documentation for more details.
\n<key>com.apple.security.files.user-selected.read-write</key>\n<true/>\nSee the Enabling User-Selected File Access documentation for more details.
\nDepending on the countries in which you are releasing your app, you may be required to provide information on the cryptographic algorithms used in your software. See the encryption export compliance docs for more information.
\nElectron использует следующие криптографические алгоритмы:
\nElectron has APIs to configure the app's icon in the macOS Dock. A macOS-only API exists to create a custom dock menu, but Electron also uses the app dock icon as the entry point for cross-platform features like recent documents and application progress.
\nThe custom dock is commonly used to add shortcuts to tasks the user wouldn't want to open the whole app window for.
\nDock меню из Terminal.app:
\n
To set your custom dock menu, you need to use the app.dock.setMenu API, which is only available on macOS.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, BrowserWindow, Menu } = require('electron')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n })\n\n win.loadFile('index.html')\n}\n\nconst dockMenu = Menu.buildFromTemplate([\n {\n label: 'New Window',\n click () { console.log('New Window') }\n }, {\n label: 'New Window with Settings',\n submenu: [\n { label: 'Basic' },\n { label: 'Pro' }\n ]\n },\n { label: 'New Command...' }\n])\n\napp.whenReady().then(() => {\n if (process.platform === 'darwin') {\n app.dock.setMenu(dockMenu)\n }\n}).then(createWindow)\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n\nAfter launching the Electron application, right click the application icon. You should see the custom menu you just defined:
\n
workingSetSize Integer - The amount of memory currently pinned to actual physical RAM.peakWorkingSetSize Integer - The maximum amount of memory that has ever been pinned to actual physical RAM.privateBytes Integer (optional) Windows - The amount of memory not shared by other processes, such as JS heap or HTML content.Note that all statistics are reported in Kilobytes.
", "title": "MemoryInfo Object", "description": "" }, "/docs/api/structures/memory-usage-details": { "locale": "ru-RU", "slug": "memory-usage-details", "href": "/docs/api/structures/memory-usage-details", "crowdinFileId": "256461", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/memory-usage-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "count Numbersize NumberliveSize Number\n\nСоздайте меню приложения и контекстное меню.
\n
Процесс: Основной
\nnew Menu()Создает новое меню.
\nКласс Menu имеет следующие статические методы:
Menu.setApplicationMenu(menu)menu Menu | nullУстанавливает меню в качестве меню приложения на macOS. On Windows and Linux, the menu will be set as each window's top menu.
Также на Windows и Linux, Вы можете использовать & в названии подменю верхнего списка, чтобы указать, какая буква должна получить сгенерированный акселератор( Accelerator ). Для примера, использование &File для меню файла в результате сгенерирует акселератор( Accelerator ) Alt-F, который открывает соответствующее меню. The indicated character in the button label then gets an underline, and the & character is not displayed on the button label.
In order to escape the & character in an item name, add a proceeding &. For example, &&File would result in &File displayed on the button label.
Passing null will suppress the default menu. On Windows and Linux, this has the additional effect of removing the menu bar from the window.
Примечание: Меню по умолчанию будет создано автоматически, если приложение не установит его. Он содержит стандартные элементы, такие как Файл, Редактировать, Вид, Окно и Помощь.
Menu.getApplicationMenu()Возвращает Menu | null - меню приложения, если значение задано, в противном случае null.
Примечание: Возвращенный экземпляр Menu не поддерживает динамическое добавление или удаление пунктов меню. Параметры экземпляра все ещё могут быть динамически изменены.
Menu.sendActionToFirstResponder(action) macOSaction StringПосылает action первому ответчику приложения. Это используется для эмуляции поведения меню macOS. Usually you would use the role property of a MenuItem.
Для дополнительной информации по нативным действиям в macOS смотрите macOS Cocoa Event Handling Guide.
\nMenu.buildFromTemplate(template)template (MenuItemConstructorOptions | MenuItem)[]Возвращает Menu
Generally, the template is an array of options for constructing a MenuItem. The usage can be referenced above.
Вы также можете прикрепить другие поля к элементу template и они станут свойствами элементов созданного меню.
Объект меню имеет следующие методы экземпляра:
menu.popup([options])options Object (опционально)windows BrowserWindow (опционально) - по умолчанию это сфокусированное окно.x Number (optional) - Default is the current mouse cursor position. Must be declared if y is declared.y Number (optional) - Default is the current mouse cursor position. Must be declared if x is declared.positioningItem Number (optional) macOS - The index of the menu item to be positioned under the mouse cursor at the specified coordinates. Default is -1.callback Функция (опционально) - вызывается, когда меню закрыто.Переключает это меню в контекстное меню в BrowserWindow.
menu.closePopup([browserWindow])browserWindow BrowserWindow (опционально) - по умолчанию это сфокусированное окно.Закрывает контекстное меню в browserWindow.
menu.append(menuItem)menuItem MenuItemДобавляет menuItem в меню.
menu.getMenuItemById(id)id StringВозвращает элемент MenuItem с указанным id
menu.insert(pos, menuItem)port IntegermenuItem MenuItemВставляет menuItem в меню на позицию pos.
Объекты созданные с помощью new Menu или возвращенные из Menu.buildFromTemplate вызывают следующие события:
Примечание: Некоторые методы доступны только в определенных операционных системах и помечены как таковые.
\nВозвращает:
\neventВызывается при вызове menu.popup().
Возвращает:
\neventВызывается, когда всплывающее окно закрывается вручную или с помощью menu.closePopup().
Объекты menu также имеют следующие свойства:
menu.itemsМассив MenuItem[] содержит элементы меню.
Каждое Menu состоит из нескольких MenuItem и каждое MenuItem может иметь подменю.
An example of creating the application menu with the simple template API:
\nconst { app, Menu } = require('electron')\n\nconst isMac = process.platform === 'darwin'\n\nconst template = [\n // { role: 'appMenu' }\n ...(isMac ? [{\n label: app.name,\n submenu: [\n { role: 'about' },\n { type: 'separator' },\n { role: 'services' },\n { type: 'separator' },\n { role: 'hide' },\n { role: 'hideOthers' },\n { role: 'unhide' },\n { type: 'separator' },\n { role: 'quit' }\n ]\n }] : []),\n // { role: 'fileMenu' }\n {\n label: 'File',\n submenu: [\n isMac ? { role: 'close' } : { role: 'quit' }\n ]\n },\n // { role: 'editMenu' }\n {\n label: 'Edit',\n submenu: [\n { role: 'undo' },\n { role: 'redo' },\n { type: 'separator' },\n { role: 'cut' },\n { role: 'copy' },\n { role: 'paste' },\n ...(isMac ? [\n { role: 'pasteAndMatchStyle' },\n { role: 'delete' },\n { role: 'selectAll' },\n { type: 'separator' },\n {\n label: 'Speech',\n submenu: [\n { role: 'startSpeaking' },\n { role: 'stopSpeaking' }\n ]\n }\n ] : [\n { role: 'delete' },\n { type: 'separator' },\n { role: 'selectAll' }\n ])\n ]\n },\n // { role: 'viewMenu' }\n {\n label: 'View',\n submenu: [\n { role: 'reload' },\n { role: 'forceReload' },\n { role: 'toggleDevTools' },\n { type: 'separator' },\n { role: 'resetZoom' },\n { role: 'zoomIn' },\n { role: 'zoomOut' },\n { type: 'separator' },\n { role: 'togglefullscreen' }\n ]\n },\n // { role: 'windowMenu' }\n {\n label: 'Window',\n submenu: [\n { role: 'minimize' },\n { role: 'zoom' },\n ...(isMac ? [\n { type: 'separator' },\n { role: 'front' },\n { type: 'separator' },\n { role: 'window' }\n ] : [\n { role: 'close' }\n ])\n ]\n },\n {\n role: 'help',\n submenu: [\n {\n label: 'Learn More',\n click: async () => {\n const { shell } = require('electron')\n await shell.openExternal('https://electronjs.org')\n }\n }\n ]\n }\n]\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nTo create menus initiated by the renderer process, send the required information to the main process using IPC and have the main process display the menu on behalf of the renderer.
\nBelow is an example of showing a menu when the user right clicks the page:
\n// renderer\nwindow.addEventListener('contextmenu', (e) => {\n e.preventDefault()\n ipcRenderer.send('show-context-menu')\n})\n\nipcRenderer.on('context-menu-command', (e, command) => {\n // ...\n})\n\n// main\nipcMain.on('show-context-menu', (event) => {\n const template = [\n {\n label: 'Menu Item 1',\n click: () => { event.sender.send('context-menu-command', 'menu-item-1') }\n },\n { type: 'separator' },\n { label: 'Menu Item 2', type: 'checkbox', checked: true }\n ]\n const menu = Menu.buildFromTemplate(template)\n menu.popup(BrowserWindow.fromWebContents(event.sender))\n})\nmacOS has a completely different style of application menu from Windows and Linux. Here are some notes on making your app's menu more native-like.
\nНа macOS есть много стандратных системных меню, таких как Службы и Окно. Чтобы сделать меню стандартным меню, Вы должны установить значение role у меню в одно из следующих, а Electron распознает их и сделает их стандартным меню:
windowhelpservicesmacOS представляет стандартные действия для некоторых элементов меню, таких как About xxx, Hide xxx и Hide Others. Чтобы установить действие элемента меню на стандартное действие, Вы должны установить атрибут role элемента меню.
На macOS название первого элемента меню приложения - всегда название Вашего приложения, независимо от того, какое название элемента Вы установили. Чтобы изменить его, измените файл Info.plist Вашей сборки приложения. See About Information Property List Files for more information.
Метод setMenu окна браузера может установить меню определенных окон браузера.
Вы можете использовать before, after, beforeGroupContaining, afterGroupContaining и id, чтобы контролировать то, как элементы будут размещены, при создании меню с помощью Menu.buildFromTemplate.
before - вставляет этот элемент перед элементом с указанным названием. Если ссылаемый элемент не существует, тогда элемент будет вставлен в конец меню. Кроме того, подразумевается, что рассматриваемый элемент меню размещен в той же \"группе\", что и сам элемент.after - вставляет элемент после элемента с указанным названием. Если ссылаемый элемент не существует, тогда элемент будет вставлен в конец меню. Кроме того, подразумевается, что рассматриваемый элемент меню размещен в той же \"группе\", что и сам элемент.beforeGroupContaining - представляет средства для одного контекстного меню, чтобы объявить размещение их содержащей группы перед содержащей группы элемента с указанным названием.afterGroupContaining - представляет средства для одного контекстного меню, чтобы объявить размещение их содержащей группы после содержащей группы элемента с указанным названием.По умолчанию, элементы будут вставлены в том порядке, в котором они существуют в шаблоне, если не используется ни один из указанных ключевых слов позиционирования.
\nШаблон:
\n[\n { id: '1', label: 'one' },\n { id: '2', label: 'two' },\n { id: '3', label: 'three' },\n { id: '4', label: 'four' }\n]\nМеню:
\n- 1\n- 2\n- 3\n- 4\nШаблон:
\n[\n { id: '1', label: 'one' },\n { type: 'separator' },\n { id: '3', label: 'three', beforeGroupContaining: ['1'] },\n { id: '4', label: 'four', afterGroupContaining: ['2'] },\n { type: 'separator' },\n { id: '2', label: 'two' }\n]\nМеню:
\n- 3\n- 4\n- ---\n- 1\n- ---\n- 2\nШаблон:
\n[\n { id: '1', label: 'one', after: ['3'] },\n { id: '2', label: 'two', before: ['1'] },\n { id: '3', label: 'three' }\n]\nМеню:
\n- ---\n- 3\n- 2\n- 1\n\n\nДобавляет элементы в основное меню и контекстное меню приложения.
\n
Процесс: Основной
\nПросмотрите Menu для примеров использования.
new MenuItem(options)options Objectclick Function (optional) - Will be called with click(menuItem, browserWindow, event) when the menu item is clicked.menuItem MenuItembrowserWindow BrowserWindow | undefined - This will not be defined if no window is open.event KeyboardEventrole String (optional) - Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu - Define the action of the menu item, when specified the click property will be ignored. Смотрите роли.type String (опционально) - Может быть normal, separator, submenu, checkbox или radio.label String (опционально)sublabel String (опционально)toolTip String (optional) macOS - Hover text for this menu item.accelerator Accelerator (опционально)icon (NativeImage | String) (опционально)enabled Boolean (опционально) - Если false, пункт меню выделится серым цветом и не будет нажимться.acceleratorWorksWhenHidden Boolean (optional) macOS - default is true, and when false will prevent the accelerator from triggering the item if the item is not visible`.visible Boolean (опционально) - Если false, пункт меню будет полностью скрыт.checked Boolean (опционально) - Должно быть указано только для checkbox или radio типов элементов меню.registerAccelerator Boolean (optional) Linux Windows - If false, the accelerator won't be registered with the system, but it will still be displayed. Defaults to true.sharingItem SharingItem (optional) macOS - The item to share when the role is shareMenu.submenu (MenuItemConstructorOptions[] | Menu) (опционально) - Необходимо указать для submenu типы элементов меню. Если submenu указано, то type: 'submenu' может быть опущен. Если значение не является Menu то оно будет автоматически преобразовано в значение Menu.buildFromTemplate.id String (optional) - Unique within a single menu. If defined then it can be used as a reference to this item by the position attribute.before String - Вставляет этот элемент перед элементом с указанным названием. Если указанный элемент не существует, то элемент будет вставлен в конец меню. Кроме того, подразумевается, что рассматриваемый элемент меню размещен в той же \"группе\", что и сам элемент.after String - Inserts this item after the item with the specified label. Если ссылаемый элемент не существует, тогда элемент будет вставлен в конец меню.beforeGroupContaining String - Предоставляет возможность в одном контекстном меню объявить размещение группы, содержащей элемент, перед группой, содержащей элемент с указанной меткой.afterGroupContaining String - Предоставляет возможность в одном контекстном меню объявить размещение группы, содержащей элемент, после группы, содержащей элемент с указанной меткой.Note: acceleratorWorksWhenHidden is specified as being macOS-only because accelerators always work when items are hidden on Windows and Linux. Эта опция доступна пользователям для того, чтобы дать им возможность отключить ее, так как это возможно в родной macOS разработке. Это свойство можно использовать только на macOS High Sierra 10.13 или новее.
Роли позволяют элементам класса menu иметь заранее определенные поведения.
\nЛучше всего указать role для любого элемента меню, который соответствует стандартной роли, а не пытаться вручную реализовать поведение в функции click. Встроенное поведение role даст наилучшую нативную возможность использования.
Значения label и accelerator необязательны при использовании role и по умолчанию будут присваиваться для каждой для каждой платформы.
Каждый элемент меню должен иметь role или label, или в случае разделителя type.
Свойство role может иметь следующие значения:
undo - Отменитьabout - Trigger a native about panel (custom message box on Window, which does not provide its own).redo - Восстановитьcut - Вырезатьcopy - Копироватьpaste - ВставитьpasteAndMatchStyle - Вставить и применить стильselectAll - Выделить всеdelete - Удалитьminimize - Свернуть текущее окно.close - Закрыть текущее окно.quit - Выйти из приложения.reload - Перезагрузить текущее окно.forceReload - Перезагрузить текущее окно, игнорировать кэш.toggleDevTools - Включить инструмент разработчика для текущего окна.togglefullscreen -Включить полноэкранный режим для текущего окна.resetZoom - Сброс измененного масштаба страницы до исходного размера.zoomIn - Увеличение масштаба страницы на 10%.zoomOut - Уменьшение масштаба страницы на 10%.toggleSpellChecker - Enable/disable builtin spell checker.fileMenu - Полное меню \"Файл\" по умолчанию (Закрыть/Выйти)editMenu - Whole default \"Edit\" menu (Undo, Copy, etc.).viewMenu - Полное меню \"Вид\" по умолчанию (перезагрузка, переключение инструментов разработчика и т. д.)windowMenu - Полное меню \"Окно\" по умолчанию (Свернуть, масштаб и т. д.).The following additional roles are available on macOS:
\nappMenu - Полное меню \"App\" по умолчанию (О программе, службах и т. д.)hide - Map to the hide action.hideOthers - Map to the hideOtherApplications action.unhide - Map to the unhideAllApplications action.startSpeaking - Map to the startSpeaking action.stopSpeaking - Map to the stopSpeaking action.front - Map to the arrangeInFront action.zoom - Map to the performZoom action.toggleTabBar - Map to the toggleTabBar action.selectNextTab - Map to the selectNextTab action.selectPreviousTab - Map to the selectPreviousTab action.mergeAllWindows - Map to the mergeAllWindows action.moveTabToNewWindow - Map to the moveTabToNewWindow action.window - The submenu is a \"Window\" menu.help - The submenu is a \"Help\" menu.services - Подменю меню \"Сервисы\". This is only intended for use in the Application Menu and is not the same as the \"Services\" submenu used in context menus in macOS apps, which is not implemented in Electron.recentDocuments - The submenu is an \"Open Recent\" menu.clearRecentDocuments - Map to the clearRecentDocuments action.shareMenu - The submenu is share menu. The sharingItem property must also be set to indicate the item to share.При задании role на macOS, label и accelerator являются единственными параметрами, которые влияют на пункт меню. Все остальные параметры будут проигнорированы. Нижний регистр role, например toggledevtools, все еще поддерживается.
Nota Bene: The enabled and visibility properties are not available for top-level menu items in the tray on macOS.
Для экземпляров MenuItem доступны следующие свойства:
menuItem.idСтрока с указанием уникального id элемента, это свойство может быть динамически изменено.
menuItem.labelA String indicating the item's visible label.
menuItem.clickA Function that is fired when the MenuItem receives a click event. It can be called with menuItem.click(event, focusedWindow, focusedWebContents).
event KeyboardEventfocusedWindow BrowserWindowfocusedWebContents WebContentsmenuItem.submenuMenu (опционально), содержащие подменю пункты, если таковые имеются.
menuItem.typeСтрока с указанием типа элемента. Can be normal, separator, submenu, checkbox or radio.
menuItem.roleString (опционально) с указанием роли элемента, если установлено. Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu
menuItem.acceleratorAn Accelerator (optional) indicating the item's accelerator, if set.
menuItem.userAccelerator Readonly macOSAn Accelerator | null indicating the item's user-assigned accelerator for the menu item.
Note: This property is only initialized after the MenuItem has been added to a Menu. Either via Menu.buildFromTemplate or via Menu.append()/insert(). Accessing before initialization will just return null.
menuItem.iconNativeImage | Строка (опционально) с указанием иконки элемента, если установлено.
menuItem.sublabelA String indicating the item's sublabel.
menuItem.toolTip macOSString с указанием текста, который появляется при наведении курсора на элемент.
menuItem.enabledBoolean указывает, включен ли элемент, это свойство может быть динамически изменено.
menuItem.visibleBoolean указывает, видим ли элемент, это свойство может быть динамически изменено.
menuItem.checkedBoolean указывает, помечен ли элемент флажком, это свойство может быть динамически изменено.
Элемент меню checkbox будет включать и выключать свойство checked при его выборе.
Radio пункт меню включит его свойство checked при нажатии, и отключит это свойство для всех смежных пунктов в том же меню.
Вы можете добавить функцию click для дополнительного поведения.
menuItem.registerAcceleratorA Boolean indicating if the accelerator should be registered with the system or just displayed.
This property can be dynamically changed.
\nmenuItem.sharingItem macOSA SharingItem indicating the item to share when the role is shareMenu.
This property can be dynamically changed.
\nmenuItem.commandIdНомер с указанием уникального последовательного идентификатора элемента.
menuItem.menuМеню, частью которого является элемент.
MessageChannelMain is the main-process-side equivalent of the DOM MessageChannel object. Its singular function is to create a pair of connected MessagePortMain objects.
See the Channel Messaging API documentation for more information on using channel messaging.
\n\n\nChannel interface for channel messaging in the main process.
\n
Процесс: Основной
\nПример:
\n// Main process\nconst { MessageChannelMain } = require('electron')\nconst { port1, port2 } = new MessageChannelMain()\nw.webContents.postMessage('port', null, [port2])\nport1.postMessage({ some: 'message' })\n\n// Renderer process\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('port', (e) => {\n // e.ports is a list of ports sent along with this message\n e.ports[0].on('message', (messageEvent) => {\n console.log(messageEvent.data)\n })\n})\nchannel.port1A MessagePortMain property.
channel.port2A MessagePortMain property.
MessagePortMain is the main-process-side equivalent of the DOM MessagePort object. It behaves similarly to the DOM version, with the exception that it uses the Node.js EventEmitter event system, instead of the DOM EventTarget system. This means you should use port.on('message', ...) to listen for events, instead of port.onmessage = ... or port.addEventListener('message', ...)
See the Channel Messaging API documentation for more information on using channel messaging.
\nMessagePortMain is an [EventEmitter][event-emitter].
\n\nPort interface for channel messaging in the main process.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
port.postMessage(message, [transfer])Sends a message from the port, and optionally, transfers ownership of objects to other browsing contexts.
\nport.start()Starts the sending of messages queued on the port. Messages will be queued until this method is called.
\nport.close()Disconnects the port, so it is no longer active.
\nВозвращает:
\nmessageEvent Objectdata anyports MessagePortMain[]Emitted when a MessagePortMain object receives a message.
\nEmitted when the remote end of a MessagePortMain object becomes disconnected.
", "title": "MessagePortMain", "description": "Port interface for channel messaging in the main process." }, "/docs/tutorial/message-ports": { "locale": "ru-RU", "slug": "message-ports", "href": "/docs/tutorial/message-ports", "crowdinFileId": "256219", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/message-ports.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "MessagePorts are a web feature that allow passing messages between different contexts. It's like window.postMessage, but on different channels. The goal of this document is to describe how Electron extends the Channel Messaging model, and to give some examples of how you might use MessagePorts in your app.
Here is a very brief example of what a MessagePort is and how it works:
\n// renderer.js ///////////////////////////////////////////////////////////////\n// MessagePorts are created in pairs. A connected pair of message ports is\n// called a channel.\nconst channel = new MessageChannel()\n\n// The only difference between port1 and port2 is in how you use them. Messages\n// sent to port1 will be received by port2 and vice-versa.\nconst port1 = channel.port1\nconst port2 = channel.port2\n\n// It's OK to send a message on the channel before the other end has registered\n// a listener. Messages will be queued until a listener is registered.\nport2.postMessage({ answer: 42 })\n\n// Here we send the other end of the channel, port1, to the main process. It's\n// also possible to send MessagePorts to other frames, or to Web Workers, etc.\nipcRenderer.postMessage('port', null, [port1])\n// main.js ///////////////////////////////////////////////////////////////////\n// In the main process, we receive the port.\nipcMain.on('port', (event) => {\n // When we receive a MessagePort in the main process, it becomes a\n // MessagePortMain.\n const port = event.ports[0]\n\n // MessagePortMain uses the Node.js-style events API, rather than the\n // web-style events API. So .on('message', ...) instead of .onmessage = ...\n port.on('message', (event) => {\n // data is { answer: 42 }\n const data = event.data\n })\n\n // MessagePortMain queues messages until the .start() method has been called.\n port.start()\n})\nThe Channel Messaging API documentation is a great way to learn more about how MessagePorts work.
\nIn the renderer, the MessagePort class behaves exactly as it does on the web. The main process is not a web page, though—it has no Blink integration—and so it does not have the MessagePort or MessageChannel classes. In order to handle and interact with MessagePorts in the main process, Electron adds two new classes: MessagePortMain and MessageChannelMain. These behave similarly to the analogous classes in the renderer.
MessagePort objects can be created in either the renderer or the main process, and passed back and forth using the ipcRenderer.postMessage and WebContents.postMessage methods. Note that the usual IPC methods like send and invoke cannot be used to transfer MessagePorts, only the postMessage methods can transfer MessagePorts.
By passing MessagePorts via the main process, you can connect two pages that might not otherwise be able to communicate (e.g. due to same-origin restrictions).
close eventElectron adds one feature to MessagePort that isn't present on the web, in order to make MessagePorts more useful. That is the close event, which is emitted when the other end of the channel is closed. Ports can also be implicitly closed by being garbage-collected.
In the renderer, you can listen for the close event either by assigning to port.onclose or by calling port.addEventListener('close', ...). In the main process, you can listen for the close event by calling port.on('close', ...).
In this example, your app has a worker process implemented as a hidden window. You want the app page to be able to communicate directly with the worker process, without the performance overhead of relaying via the main process.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, ipcMain, MessageChannelMain } = require('electron')\n\napp.whenReady().then(async () => {\n // The worker process is a hidden BrowserWindow, so that it will have access\n // to a full Blink context (including e.g. <canvas>, audio, fetch(), etc.)\n const worker = new BrowserWindow({\n show: false,\n webPreferences: { nodeIntegration: true }\n })\n await worker.loadFile('worker.html')\n\n // The main window will send work to the worker process and receive results\n // over a MessagePort.\n const mainWindow = new BrowserWindow({\n webPreferences: { nodeIntegration: true }\n })\n mainWindow.loadFile('app.html')\n\n // We can't use ipcMain.handle() here, because the reply needs to transfer a\n // MessagePort.\n ipcMain.on('request-worker-channel', (event) => {\n // For security reasons, let's make sure only the frames we expect can\n // access the worker.\n if (event.senderFrame === mainWindow.webContents.mainFrame) {\n // Create a new channel ...\n const { port1, port2 } = new MessageChannelMain()\n // ... send one end to the worker ...\n worker.webContents.postMessage('new-client', null, [port1])\n // ... and the other end to the main window.\n event.senderFrame.postMessage('provide-worker-channel', null, [port2])\n // Now the main window and the worker can communicate with each other\n // without going through the main process!\n }\n })\n})\n<!-- worker.html ------------------------------------------------------------>\n<script>\nconst { ipcRenderer } = require('electron')\n\nfunction doWork(input) {\n // Something cpu-intensive.\n return input * 2\n}\n\n// We might get multiple clients, for instance if there are multiple windows,\n// or if the main window reloads.\nipcRenderer.on('new-client', (event) => {\n const [ port ] = event.ports\n port.onmessage = (event) => {\n // The event data can be any serializable object (and the event could even\n // carry other MessagePorts with it!)\n const result = doWork(event.data)\n port.postMessage(result)\n }\n})\n</script>\n<!-- app.html --------------------------------------------------------------->\n<script>\nconst { ipcRenderer } = require('electron')\n\n// We request that the main process sends us a channel we can use to\n// communicate with the worker.\nipcRenderer.send('request-worker-channel')\n\nipcRenderer.once('provide-worker-channel', (event) => {\n // Once we receive the reply, we can take the port...\n const [ port ] = event.ports\n // ... register a handler to receive results ...\n port.onmessage = (event) => {\n console.log('received result:', event.data)\n }\n // ... and start sending it work!\n port.postMessage(21)\n})\n</script>\nElectron's built-in IPC methods only support two modes: fire-and-forget (e.g. send), or request-response (e.g. invoke). Using MessageChannels, you can implement a \"response stream\", where a single request responds with a stream of data.
// renderer.js ///////////////////////////////////////////////////////////////\n\nfunction makeStreamingRequest (element, callback) {\n // MessageChannels are lightweight--it's cheap to create a new one for each\n // request.\n const { port1, port2 } = new MessageChannel()\n\n // We send one end of the port to the main process ...\n ipcRenderer.postMessage(\n 'give-me-a-stream',\n { element, count: 10 },\n [port2]\n )\n\n // ... and we hang on to the other end. The main process will send messages\n // to its end of the port, and close it when it's finished.\n port1.onmessage = (event) => {\n callback(event.data)\n }\n port1.onclose = () => {\n console.log('stream ended')\n }\n}\n\nmakeStreamingRequest(42, (data) => {\n console.log('got response data:', event.data)\n})\n// We will see \"got response data: 42\" 10 times.\n// main.js ///////////////////////////////////////////////////////////////////\n\nipcMain.on('give-me-a-stream', (event, msg) => {\n // The renderer has sent us a MessagePort that it wants us to send our\n // response over.\n const [replyPort] = event.ports\n\n // Here we send the messages synchronously, but we could just as easily store\n // the port somewhere and send messages asynchronously.\n for (let i = 0; i < msg.count; i++) {\n replyPort.postMessage(msg.element)\n }\n\n // We close the port when we're done to indicate to the other end that we\n // won't be sending any more messages. This isn't strictly necessary--if we\n // didn't explicitly close the port, it would eventually be garbage\n // collected, which would also trigger the 'close' event in the renderer.\n replyPort.close()\n})\nWhen context isolation is enabled, IPC messages from the main process to the renderer are delivered to the isolated world, rather than to the main world. Sometimes you want to deliver messages to the main world directly, without having to step through the isolated world.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, MessageChannelMain } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(async () => {\n // Create a BrowserWindow with contextIsolation enabled.\n const bw = new BrowserWindow({\n webPreferences: {\n contextIsolation: true,\n preload: path.join(__dirname, 'preload.js')\n }\n })\n bw.loadURL('index.html')\n\n // We'll be sending one end of this channel to the main world of the\n // context-isolated page.\n const { port1, port2 } = new MessageChannelMain()\n\n // It's OK to send a message on the channel before the other end has\n // registered a listener. Messages will be queued until a listener is\n // registered.\n port2.postMessage({ test: 21 })\n\n // We can also receive messages from the main world of the renderer.\n port2.on('message', (event) => {\n console.log('from renderer main world:', event.data)\n })\n port2.start()\n\n // The preload script will receive this IPC message and transfer the port\n // over to the main world.\n bw.webContents.postMessage('main-world-port', null, [port1])\n})\n// preload.js ////////////////////////////////////////////////////////////////\nconst { ipcRenderer } = require('electron')\n\n// We need to wait until the main world is ready to receive the message before\n// sending the port. We create this promise in the preload so it's guaranteed\n// to register the onload listener before the load event is fired.\nconst windowLoaded = new Promise(resolve => {\n window.onload = resolve\n})\n\nipcRenderer.on('main-world-port', async (event) => {\n await windowLoaded\n // We use regular window.postMessage to transfer the port from the isolated\n // world to the main world.\n window.postMessage('main-world-port', '*', event.ports)\n})\n<!-- index.html ------------------------------------------------------------->\n<script>\nwindow.onmessage = (event) => {\n // event.source === window means the message is coming from the preload\n // script, as opposed to from an <iframe> or other source.\n if (event.source === window && event.data === 'main-world-port') {\n const [ port ] = event.ports\n // Once we have the port, we can communicate directly with the main\n // process.\n port.onmessage = (event) => {\n console.log('from main process:', event.data)\n port.postMessage(event.data * 2)\n }\n }\n}\n</script>\nmimeType String (optional) - MIME type of the buffer.charset String (optional) - Charset of the buffer.data Buffer - The actual Buffer content.InputEventtype String - The type of the event, can be mouseDown, mouseUp, mouseEnter, mouseLeave, contextMenu, mouseWheel or mouseMove.x Integery Integerbutton String (optional) - The button pressed, can be left, middle, right.globalX Integer (optional)globalY Integer (optional)movementX Integer (optional)movementY Integer (optional)clickCount Integer (optional)MouseInputEventtype String - The type of the event, can be mouseWheel.deltaX Integer (optional)deltaY Integer (optional)wheelTicksX Integer (optional)wheelTicksY Integer (optional)accelerationRatioX Integer (optional)accelerationRatioY Integer (optional)hasPreciseScrollingDeltas Boolean (optional)canScroll Boolean (optional)С помощью Web Workers, есть возможность запускать JavaScript в потоках на уровне операционной системы.
\nIt is possible to use Node.js features in Electron's Web Workers, to do so the nodeIntegrationInWorker option should be set to true in webPreferences.
const win = new BrowserWindow({\n webPreferences: {\n nodeIntegrationInWorker: true\n }\n})\nThe nodeIntegrationInWorker can be used independent of nodeIntegration, but sandbox must not be set to true.
All built-in modules of Node.js are supported in Web Workers, and asar archives can still be read with Node.js APIs. However none of Electron's built-in modules can be used in a multi-threaded environment.
Any native Node.js module can be loaded directly in Web Workers, but it is strongly recommended not to do so. Most existing native modules have been written assuming single-threaded environment, using them in Web Workers will lead to crashes and memory corruptions.
\nNote that even if a native Node.js module is thread-safe it's still not safe to load it in a Web Worker because the process.dlopen function is not thread safe.
The only way to load a native module safely for now, is to make sure the app loads no native modules after the Web Workers get started.
\nprocess.dlopen = () => {\n throw new Error('Load native module is not safe')\n}\nconst worker = new Worker('script.js')\nНекоторым приложениям может понадобиться поддержка реализованной в операционной системе функции перетаскивания файлов. Перетаскивание файлов в веб-контент поддерживается большинством веб-сайтов. Electron дополнительно поддерживает перетаскивание файлов и содержимого приложения в операционную систему.
\nTo implement this feature in your app, you need to call the webContents.startDrag(item) API in response to the ondragstart event.
An example demonstrating how you can create a file on the fly to be dragged out of the window.
\nIn preload.js use the contextBridge to inject a method window.electron.startDrag(...) that will send an IPC message to the main process.
const { contextBridge, ipcRenderer } = require('electron')\nconst path = require('path')\n\ncontextBridge.exposeInMainWorld('electron', {\n startDrag: (fileName) => {\n ipcRenderer.send('ondragstart', path.join(process.cwd(), fileName))\n }\n})\nAdd a draggable element to index.html, and reference your renderer script:
<div style=\"border:2px solid black;border-radius:3px;padding:5px;display:inline-block\" draggable=\"true\" id=\"drag\">Drag me</div>\n<script src=\"renderer.js\"></script>\nIn renderer.js set up the renderer process to handle drag events by calling the method you added via the contextBridge above.
document.getElementById('drag').ondragstart = (event) => {\n event.preventDefault()\n window.electron.startDrag('drag-and-drop.md')\n}\nIn the Main process (main.js file), expand the received event with a path to the file that is being dragged and an icon:
const { ipcMain } = require('electron')\n\nipcMain.on('ondragstart', (event, filePath) => {\n event.sender.startDrag({\n file: filePath,\n icon: '/path/to/icon.png'\n })\n})\nAfter launching the Electron application, try dragging and dropping the item from the BrowserWindow onto your desktop. In this guide, the item is a Markdown file located in the root of the project:
\n
\n\nСоздает иконки приложения, в том числе для системного лотка (Windows), дока (macOS), используя файлы PNG и JPG.
\n
Процессы: Основной, Графический
\nIn Electron, for the APIs that take images, you can pass either file paths or NativeImage instances. An empty image will be used when null is passed.
Например, при создании вкладки в области уведомлений или установке иконки окна можно задать путь к файлу изображения в виде String:
const { BrowserWindow, Tray } = require('electron')\n\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconst win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })\nconsole.log(appIcon, win)\nOr read the image from the clipboard, which returns a NativeImage:
const { clipboard, Tray } = require('electron')\nconst image = clipboard.readImage()\nconst appIcon = new Tray(image)\nconsole.log(appIcon)\nCurrently PNG and JPEG image formats are supported. PNG is recommended because of its support for transparency and lossless compression.
On Windows, you can also load ICO icons from file paths. For best visual quality, it is recommended to include at least the following sizes in the:
Проверьте раздел Size requirements в этой статье.
\nНа платформах, имеющих поддержку высокого DPI, таких как дисплеи Apple Retina, вы можете добавить @2x после имени файла изображения, чтобы пометить его как изображение с высоким разрешением.
For example, if icon.png is a normal image that has standard resolution, then icon@2x.png will be treated as a high resolution image that has double DPI density.
If you want to support displays with different DPI densities at the same time, you can put images with different sizes in the same folder and use the filename without DPI suffixes. Например:
\nimages/\n├── icon.png\n├── icon@2x.png\n└── icon@3x.png\nconst { Tray } = require('electron')\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconsole.log(appIcon)\nThe following suffixes for DPI are also supported:
\n@1x@1.25x@1.33x@1.4x@1.5x@1.8x@2x@2.5x@3x@4x@5xTemplate images consist of black and an alpha channel. Template images are not intended to be used as standalone images and are usually mixed with other content to create the desired final appearance.
\nThe most common case is to use template images for a menu bar icon, so it can adapt to both light and dark menu bars.
\nВнимание: Шаблонные изображения поддерживаются только на macOS.
\nTo mark an image as a template image, its filename should end with the word Template. Например:
xxxTemplate.pngxxxTemplate@2x.pngМодуль nativeImage имеет следующие методы, все из которых возвращают экземпляр класса NativeImage:
nativeImage.createEmpty()Возвращает NativeImage
Создает пустой экземпляр NativeImage.
nativeImage.createThumbnailFromPath(path, maxSize) macOS Windowspath String - path to a file that we intend to construct a thumbnail out of.maxSize Size - the maximum width and height (positive numbers) the thumbnail returned can be. The Windows implementation will ignore maxSize.height and scale the height according to maxSize.width.Returns Promise<NativeImage> - fulfilled with the file's thumbnail preview image, which is a NativeImage.
nativeImage.createFromPath(path)path StringВозвращает NativeImage
Создает новый экземпляр NativeImage из файла, расположенного по адресу path. Этот метод возвращает пустое изображение, если путь path не существует, не может быть прочитан или является некорректным.
const nativeImage = require('electron').nativeImage\n\nconst image = nativeImage.createFromPath('/Users/somebody/images/icon.png')\nconsole.log(image)\nnativeImage.createFromBitmap(buffer, options)buffer Bufferoptions Objectwidth Integerheight IntegerscaleFactor Double (опционально) - По умолчанию 1.0.Возвращает NativeImage
Creates a new NativeImage instance from buffer that contains the raw bitmap pixel data returned by toBitmap(). The specific format is platform-dependent.
nativeImage.createFromBuffer(buffer[, options])buffer Bufferoptions Object (опционально)width Integer (опционально) - требуется для буферов растровых изображений.height Integer (опционально) - требуется для буферов растровых изображений.scaleFactor Double (опционально) - По умолчанию 1.0.Возвращает NativeImage
Создает новый NativeImage из buffer. Tries to decode as PNG or JPEG first.
nativeImage.createFromDataURL(dataURL)dataURL StringВозвращает NativeImage
Создает новый NativeImage из dataURL.
nativeImage.createFromNamedImage(imageName[, hslShift]) macOSВозвращает NativeImage
Создает новый экземпляр NativeImage из NSImage, который сопоставляется с заданным именем изображения. Смотрите System Icons для получения списка возможных значений.
hslShift применяется к изображению со следующими правилами:
hsl_shift[0] (hue): The absolute hue value for the image - 0 and 1 map to 0 and 360 on the hue color wheel (red).hsl_shift[1] (saturation): A saturation shift for the image, with the following key values: 0 = remove all color. 0,5 = оставить без изменений. 1 = fully saturate the image.hsl_shift[2] (lightness): A lightness shift for the image, with the following key values: 0 = remove all lightness (make all pixels black). 0,5 = оставить без изменений. 1 = полная яркость (сделать все точки белыми).Это означает, что [-1, 0, 1] сделает изображение полностью белым, а [-1, 1, 0] сделает изображение полностью чёрным.
В некоторых случаях NSImageName не соответствует строковому представлению; одним из примеров может служить NSFolderImageName, строковое представление которого будет NSFolder. Поэтому вам нужно определить правильное представление строк для вашего изображения, перед тем как его передавать. Это можно сделать следующим образом:
echo -e '#import <Cocoa/Cocoa.h>\\nint main() { NSLog(@\"%@\", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test
где SYSTEM_IMAGE_NAME следует заменить любым значением из этого списка.
\n\nВстроенная упаковка изображений, таких как область уведомлений, док-станция и значки приложений.
\n
Process: Main, Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Для экземпляров класса NativeImage доступны следующие методы:
image.toPNG([options])options Object (опционально)scaleFactor Double (опционально) - По умолчанию 1.0.Возвращает Buffer - A Buffer, который содержит закодированные данные изображения PNG.
image.toJPEG(quality)quality Integer - Качество От 0 до 100.Возвращает Buffer - A Buffer, который содержит закодированные данные изображения JPEG.
image.toBitmap([options])options Object (опционально)scaleFactor Double (опционально) - По умолчанию 1.0.Возвращает Buffer - Buffer, который содержит копию сырых данных растровых пикселей изображения.
image.toDataURL([options])options Object (опционально)scaleFactor Double (опционально) - По умолчанию 1.0.Возвращает String - данные URL изображения.
image.getBitmap([options])options Object (опционально)scaleFactor Double (опционально) - По умолчанию 1.0.Возвращает Buffer - Buffer, который содержит сырые данные растровых пикселей изображения.
The difference between getBitmap() and toBitmap() is that getBitmap() does not copy the bitmap data, so you have to use the returned Buffer immediately in current event loop tick; otherwise the data might be changed or destroyed.
image.getNativeHandle() macOSВозвращает Buffer - Buffer в котором хранится указатель C на базовый собственный дескриптор изображения. На macOS возвращается указатель на экземпляр NSImage.
Обратите внимание, что возвращаемый указатель - это слабый указатель на исходное изображение, а не на копию, поэтому вы должны убедиться, что связанный с ним экземпляр NativeImage находится рядом.
image.isEmpty()Returns Boolean - Whether the image is empty.
image.getSize([scaleFactor])scaleFactor Double (опционально) - По умолчанию 1.0.Возвращает Size.
If scaleFactor is passed, this will return the size corresponding to the image representation most closely matching the passed value.
image.setTemplateImage(option)option BooleanMarks the image as a template image.
\nimage.isTemplateImage()Returns Boolean - Whether the image is a template image.
image.crop(rect)rect Rectangle - область изображения до которой нужно обрезать.Возвращает NativeImage - обрезанное изображение.
image.resize(options)options Objectwidth Integer (optional) - Defaults to the image's width.height Integer (optional) - Defaults to the image's height.quality String (optional) - The desired quality of the resize image. Possible values are good, better, or best. The default is best. These values express a desired quality/speed tradeoff. They are translated into an algorithm-specific method that depends on the capabilities (CPU, GPU) of the underlying platform. It is possible for all three methods to be mapped to the same algorithm on a given platform.Возвращает NativeImage - измененый размер изображения.
Если указаны только height или width, то текущее соотношение сторон будет сохранено в изображении.
image.getAspectRatio([scaleFactor])scaleFactor Double (опционально) - По умолчанию 1.0.Возвращает Float - пропорции изображения.
If scaleFactor is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value.
image.getScaleFactors()Returns Float[] - An array of all scale factors corresponding to representations for a given nativeImage.
image.addRepresentation(options)options ObjectscaleFactor Double - The scale factor to add the image representation for.width Integer (optional) - Defaults to 0. Required if a bitmap buffer is specified as buffer.height Integer (optional) - Defaults to 0. Required if a bitmap buffer is specified as buffer.buffer Buffer (optional) - The buffer containing the raw image data.dataURL String (optional) - The data URL containing either a base 64 encoded PNG or JPEG image.Add an image representation for a specific scale factor. This can be used to explicitly add different scale factor representations to an image. This can be called on empty images.
\nnativeImage.isMacTemplateImage macOSСвойство Boolean определяет, считается ли изображение шаблоном.
Пожалуйста, обратите внимание, что это свойство влияет только на macOS.
", "title": "nativeImage", "description": "Создает иконки приложения, в том числе для системного лотка (Windows), дока (macOS), используя файлы PNG и JPG." }, "/docs/api/native-theme": { "locale": "ru-RU", "slug": "native-theme", "href": "/docs/api/native-theme", "crowdinFileId": "256343", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/native-theme.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nЧитайте и реагируйте на изменения в родной цветовой теме Chromium.
\n
Процесс: Основной
\nОбъект nativeTheme имеет следующие события:
Возникает, когда в основной NativeTheme что-то изменилось. Это обычно означает, что значение shouldUseDarkColors (использовать темные цвета), shouldUseHighContrastColors (использовать высококонтрастные цвета) или shouldUseInvertedColorScheme (использовать инвертированную цветовую гамму) - изменилось. Вам придется проверить их для того, чтобы определить, какие из них были изменены.
Объект nativeTheme имеет следующие свойства:
nativeTheme.shouldUseDarkColors Только чтениеBoolean - в данный момент для текущей OS / Chromium включен темный режим или дается указание отображать пользовательский интерфейс в темном режиме. Если вы хотите изменить это значение, вы должны использовать themeSource ниже.
nativeTheme.themeSourceСвойство String может быть system, light или dark. It is used to override and supersede the value that Chromium has chosen to use internally.
Установка этого свойства на system удалит переопределение и все будет сброшено на установленное ОС по умолчанию. По умолчанию themeSource является system.
Параметры свойства dark имеют следующие эффекты:
nativeTheme.shouldUseDarkColors при обращении будет trueprefers-color-scheme CSS будет соответствовать режиму dark.updatedПараметры свойства light имеют следующие эффекты:
nativeTheme.shouldUseDarkColors при обращении будет falseprefers-color-scheme CSS будет соответствовать режиму light.updatedИспользование этого свойства должно совпадать с классическим \"темным режимом\" машины в вашем приложении, где у пользователя есть три варианта.
\nFollow OS --> themeSource = 'system'Dark Mode --> themeSource = 'dark'Light Mode --> themeSource = 'light'В этом случае ваше приложение должно всегда использовать shouldUseDarkColors, чтобы определить, какой CSS будет применяться.
nativeTheme.shouldUseHighContrastColors macOS Windows Только чтениеA Boolean for if the OS / Chromium currently has high-contrast mode enabled or is being instructed to show a high-contrast UI.
nativeTheme.shouldUseInvertedColorScheme macOS Windows Только чтениеBoolean - в данный момент для текущей OS / Chromium включен режим инвертирования цветовой схемы или дается указание отображать пользовательский интерфейс с инвертированной цветовой схемой.
\n\nВыполнение HTTP/HTTPS запросов с использованием родной сетевой библиотеки Chromium
\n
Процесс: Основной
\nМодуль net представляет собой клиентский API для выдачи HTTP(S) запросов. Он похож на модули HTTP и HTTPS в Node.js, но использует собственную сетевую библиотеку Chromium вместо реализации Node.js, обеспечивая лучшую поддержку веб-прокси. It also supports checking network status.
Ниже приведен неполный список причин, по которым вы можете рассмотреть использование модуля net вместо собственных модулей Node.js:
Компоненты API (включая классы, методы, свойства и имена событий) похожи на компоненты, используемые в Node.js.
\nПример использования:
\nconst { app } = require('electron')\napp.whenReady().then(() => {\n const { net } = require('electron')\n const request = net.request('https://github.com')\n request.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`)\n console.log(`HEADERS: ${JSON.stringify(response.headers)}`)\n response.on('data', (chunk) => {\n console.log(`BODY: ${chunk}`)\n })\n response.on('end', () => {\n console.log('No more data in response.')\n })\n })\n request.end()\n})\nThe net API can be used only after the application emits the ready event. Trying to use the module before the ready event will throw an error.
Модуль net имеет следующие методы:
net.request(options)options (ClientRequestConstructorOptions | String) - Параметры конструктора ClientRequest.Возвращает ClientRequest
Создает экземпляр ClientRequest, используя предоставленные options, которые напрямую передаются конструктору ClientRequest. Метод net.request будет использован для выполнения как безопасных, так и небезопасных HTTP-запросов в соответствии со схемой указанного протокола в объекте options.
net.isOnline()Returns Boolean - Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
net.online Только чтениеA Boolean property. Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
\n\nЖурналирование сетевых событий сессии.
\n
Процесс: Основной
\nconst { netLog } = require('electron')\n\napp.whenReady().then(async () => {\n await netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nСмотрите --log-net-log для регистрации сетевых событий на протяжении всего жизненного цикла приложения.
Примечание: Все методы, если не указано другого, могут быть использованы только после того, как событие ready модуля app будет отправлено.
netLog.startLogging(path[, options])path String - путь к файлу для записи сетевых журналов.options Object (опционально)captureMode String (опционально) - Какие типы данных должны быть зафиксированы. По умолчанию будут записаны только метаданные о запросах. Установка этого в includeSensitive будет включать cookies и данные аутентификации. Установка на everything включит все байты, передаваемые на сокеты. Может быть default, includeSensitive или everything.maxFileSize Number (опционально) - Когда журнал заполнится и станет больше этого размера, регистрация автоматически прекратится. По умолчанию неограничено.Возвращает Promise<void> - разрешает, когда сетевой журнал начал запись.
Запускает запись сетевых событий в path.
netLog.stopLogging()Returns Promise<void> - resolves when the net log has been flushed to disk.
Остановка записи сетевых событий. Если не вызвано, ведение сетевого журнала автоматически закроется при выходе из приложения.
\nnetLog.currentlyLogging Только чтениеA Boolean property that indicates whether network logs are currently being recorded.
EventnewGuest BrowserWindow (optional)\n\nСоздание уведомлений на рабочем столе ОС
\n
Процесс: Основной
\nЕсли вы хотите отобразить уведомления в Рендерер-процессе, вы должны использовать HTML5 Notification API
\n\n\nСоздание уведомлений на рабочем столе ОС
\n
Процесс: Основной
\nNotification является EventEmitter.
Так создается новый экземпляр BrowserWindow с собственными свойствами, установленными в options.
Класс Notification имеет следующие статические методы:
Notification.isSupported()Возвращает Boolean - Поддерживаются ли уведомления рабочего стола в текущей системе
new Notification([options])options Object (опционально)title String (optional) - A title for the notification, which will be shown at the top of the notification window when it is shown.subtitle String (опционально) macOS - Подзаголовок для уведомления, который будет отображаться под заголовком.body String (optional) - The body text of the notification, which will be displayed below the title or subtitle.silent Boolean (опционально) - Использовать ли звук уведомления ОС при отображении уведомления.icon (String | NativeImage) (опционально) - Значок для отображения в уведомлении.hasReply Boolean (опционально) macOS - Нужно ли добавлять встроенный ответ к уведомлению.timeoutType String (optional) Linux Windows - The timeout duration of the notification. Can be 'default' or 'never'.replyPlaceholder String (опционально) macOS - Заполнитель для записи в поле ввода встроенного ответа.sound String (опционально) macOS - Имя звукового файла, воспроизводимого при отображении уведомления.urgency String (optional) Linux - The urgency level of the notification. Can be 'normal', 'critical', or 'low'.actions NotificationAction[] (опционально) macOS - Действия для добавления к уведомлению. Пожалуйста, прочитайте доступные действия и ограничения в документации NotificationAction.closeButtonText String (optional) macOS - A custom title for the close button of an alert. An empty string will cause the default localized text to be used.toastXml String (optional) Windows - A custom description of the Notification on Windows superseding all properties above. Provides full customization of design and behavior of the notification.Объекты созданные с помощью new Notification имеют следующие события:
Примечание: Некоторые методы доступны только в определенных операционных системах и помечены как таковые.
\nВозвращает:
\neventВозникает, когда уведомление отображается пользователю, обратите внимание, что оно может быть вызвано несколько раз, поскольку уведомление может быть показано несколько раз с помощью метода show().
Возвращает:
\neventВозникает при нажатии на уведомление пользователя.
\nВозвращает:
\neventВозникает при закрытии уведомления вручную пользователем.
\nНе гарантируется, что это событие будет отправлено во всех случаях, когда уведомление закрыто.
\nВозвращает:
\neventreply String - Строка, введенная пользователем в поле ответа в строке ответа.Возникает при нажатии пользователем кнопки \"Ответить\" в уведомлении с hasReply: true.
Возвращает:
\neventindex Number - Индекс действия, которое было активировано.Возвращает:
\neventerror String - The error encountered during execution of the show() method.Emitted when an error is encountered while creating and showing the native notification.
\nОбъекты, созданные с помощью New Notification, имеют следующие методы экземпляра:
notification.show()Сразу же показывает уведомление пользователю, обратите внимание, что это означает, в отличие от реализации HTML5 Notification, создание экземпляра new Notification не сразу показывает его пользователю, вам нужно вызвать этот метод, прежде чем ОС покажет его.
Если уведомление было показано ранее, этот метод отклонит ранее показанное уведомление и создаст новое с идентичными свойствами.
\nnotification.close()Отклоняет уведомление.
\nnotification.titleСвойство String, представляющее заголовок уведомления.
notification.subtitleСвойство String, представляющее подзаголовок уведомления.
notification.bodyСвойство String, представляющее тело уведомления.
notification.replyPlaceholderСвойство String, представляющее заполнитель ответа уведомления.
notification.soundСвойство String, представляющее звук уведомления.
notification.closeButtonTextСвойство String, представляющее текст кнопки закрытия уведомления.
notification.silentСвойство Boolean, представляющее, является ли уведомление беззвучным.
notification.hasReplyСвойство Boolean, представляющее, есть ли в уведомлении действие для ответа.
notification.urgency LinuxA String property representing the urgency level of the notification. Can be 'normal', 'critical', or 'low'.
Стандартное значение - 'low'. Что бы узнать подробнее, смотрите NotifyUrgency.
\nnotification.timeoutType Linux WindowsA String property representing the type of timeout duration for the notification. Can be 'default' or 'never'.
If timeoutType is set to 'never', the notification never expires. It stays open until closed by the calling API or the user.
notification.actionsA NotificationAction[] свойство, представляющее действия уведомления.
notification.toastXml WindowsA String property representing the custom Toast XML of the notification.
В macOS вы можете указать название звука, который вы хотели бы воспроизвести, когда отображается уведомление. Any of the default sounds (under System Preferences > Sound) can be used, in addition to custom sound files. Убедитесь, что звуковой файл скопирован в папку пакета приложений (например, YourApp.app/Contents/Resources), или в одно из следующих мест:
~/Library/Sounds (~/Библиотека/Звуки)/Library/Sounds (/Библиотека/Звуки)/Network/Library/Sounds (/Сеть/Библиотека/Звуки)/System/Library/Sounds (/Система/Библиотека/Звуки)Смотрите документацию NSSound для получения дополнительной информации.
type String - The type of action, can be button.text String (optional) - The label for the given action.| Action Type | Platform Support | Usage of text | Default text | Limitations |
|---|---|---|---|---|
button | macOS | Used as the label for the button | \"Show\" (or a localized string by system default if first of such button, otherwise empty) | Only the first one is used. If multiple are provided, those beyond the first will be listed as additional actions (displayed when mouse active over the action button). Any such action also is incompatible with hasReply and will be ignored if hasReply is true. |
In order for extra notification buttons to work on macOS your app must meet the following criteria.
\nNSUserNotificationAlertStyle set to alert in the Info.plist.If either of these requirements are not met the button won't appear.
", "title": "NotificationAction Object", "description": "" }, "/docs/api/structures/notification-response": { "locale": "ru-RU", "slug": "notification-response", "href": "/docs/api/structures/notification-response", "crowdinFileId": "256473", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/notification-response.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "actionIdentifier String - The identifier string of the action that the user selected.date Number - The delivery date of the notification.identifier String - The unique identifier for this notification request.userInfo Record<String, any> - A dictionary of custom information associated with the notification.userText String (optional) - The text entered or chosen by the user.All three operating systems provide means for applications to send notifications to the user. The technique of showing notifications is different for the Main and Renderer processes.
\nFor the Renderer process, Electron conveniently allows developers to send notifications with the HTML5 Notification API, using the currently running operating system's native notification APIs to display it.
\nTo show notifications in the Main process, you need to use the Notification module.
\nStarting with a working application from the Quick Start Guide, add the following line to the index.html file before the closing </body> tag:
<script src=\"renderer.js\"></script>\n...and add the renderer.js file:
const NOTIFICATION_TITLE = 'Title'\nconst NOTIFICATION_BODY = 'Notification from the Renderer process. Click to log to console.'\nconst CLICK_MESSAGE = 'Notification clicked'\n\nnew Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY })\n .onclick = () => console.log(CLICK_MESSAGE)\nAfter launching the Electron application, you should see the notification:
\n
Additionally, if you click on the notification, the DOM will update to show \"Notification clicked!\".
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { Notification } = require('electron')\n\nconst NOTIFICATION_TITLE = 'Basic Notification'\nconst NOTIFICATION_BODY = 'Notification from the Main process'\n\nfunction showNotification () {\n new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()\n}\n\napp.whenReady().then(createWindow).then(showNotification)\nAfter launching the Electron application, you should see the system notification:
\n
Хотя код и Ux схожий между операционными системами, все же есть небольшие различия.
\nnode_modules\\electron\\dist\\electron.exe to your Start Menu also does the trick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'. You will then need to add the line app.setAppUserModelId(process.execPath) to your main process to see notifications.Electron attempts to automate the work around the Application User Model ID. When Electron is used together with the installation and update framework Squirrel, shortcuts will automatically be set correctly. Furthermore, Electron will detect that Squirrel was used and will automatically call app.setAppUserModelId() with the correct value. During development, you may have to call app.setAppUserModelId() yourself.
Furthermore, in Windows 8, the maximum length for the notification body is 250 characters, with the Windows team recommending that notifications should be kept to 200 characters. That said, that limitation has been removed in Windows 10, with the Windows team asking developers to be reasonable. Attempting to send gigantic amounts of text to the API (thousands of characters) might result in instability.
\nLater versions of Windows allow for advanced notifications, with custom templates, images, and other flexible elements. To send those notifications (from either the main process or the renderer process), use the userland module electron-windows-notifications, which uses native Node addons to send ToastNotification and TileNotification objects.
While notifications including buttons work with electron-windows-notifications, handling replies requires the use of electron-windows-interactive-notifications, which helps with registering the required COM components and calling your Electron app with the entered user data.
To detect whether or not you're allowed to send a notification, use the userland module electron-notification-state.
\nThis allows you to determine ahead of time whether or not Windows will silently throw the notification away.
\nNotifications are straight-forward on macOS, but you should be aware of Apple's Human Interface guidelines regarding notifications.
\nNote that notifications are limited to 256 bytes in size and will be truncated if you exceed that limit.
\nTo detect whether or not you're allowed to send a notification, use the userland module electron-notification-state.
\nThis will allow you to detect ahead of time whether or not the notification will be displayed.
\nNotifications are sent using libnotify which can show notifications on any desktop environment that follows Desktop Notifications Specification, including Cinnamon, Enlightenment, Unity, GNOME, KDE.
Offscreen rendering lets you obtain the content of a BrowserWindow in a bitmap, so it can be rendered anywhere, for example, on texture in a 3D scene. The offscreen rendering in Electron uses a similar approach to that of the Chromium Embedded Framework project.
Notes:
\npaint event to be more efficient.GPU accelerated rendering means that the GPU is used for composition. Because of that, the frame has to be copied from the GPU which requires more resources, thus this mode is slower than the Software output device. The benefit of this mode is that WebGL and 3D CSS animations are supported.
\nThis mode uses a software output device for rendering in the CPU, so the frame generation is much faster. As a result, this mode is preferred over the GPU accelerated one.
\nTo enable this mode, GPU acceleration has to be disabled by calling the app.disableHardwareAcceleration() API.
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\n\napp.disableHardwareAcceleration()\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ webPreferences: { offscreen: true } })\n\n win.loadURL('https://github.com')\n win.webContents.on('paint', (event, dirty, image) => {\n fs.writeFileSync('ex.png', image.toPNG())\n })\n win.webContents.setFrameRate(60)\n})\nAfter launching the Electron application, navigate to your application's working folder, where you'll find the rendered image.
", "title": "Закадровый рендеринг", "description": "" }, "/docs/tutorial/online-offline-events": { "locale": "ru-RU", "slug": "online-offline-events", "href": "/docs/tutorial/online-offline-events", "crowdinFileId": "256229", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/online-offline-events.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Online and offline event detection can be implemented in the Renderer process using the navigator.onLine attribute, part of standard HTML5 API.
The navigator.onLine attribute returns:
false if all network requests are guaranteed to fail (e.g. when disconnected from the network).true in all other cases.Since many cases return true, you should treat with care situations of getting false positives, as we cannot always assume that true value means that Electron can access the Internet. For example, in cases when the computer is running a virtualization software that has virtual Ethernet adapters in \"always connected\" state. Therefore, if you want to determine the Internet access status of Electron, you should develop additional means for this check.
Starting with an HTML file index.html, this example will demonstrate how the navigator.onLine API can be used to build a connection status indicator.
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n</head>\n<body>\n <h1>Connection status: <strong id='status'></strong></h1>\n <script src=\"renderer.js\"></script>\n</body>\n</html>\nIn order to mutate the DOM, create a renderer.js file that adds event listeners to the 'online' and 'offline' window events. The event handler sets the content of the <strong id='status'> element depending on the result of navigator.onLine.
function updateOnlineStatus () {\n document.getElementById('status').innerHTML = navigator.onLine ? 'online' : 'offline'\n}\n\nwindow.addEventListener('online', updateOnlineStatus)\nwindow.addEventListener('offline', updateOnlineStatus)\n\nupdateOnlineStatus()\nFinally, create a main.js file for main process that creates the window.
const { app, BrowserWindow } = require('electron')\n\nfunction createWindow () {\n const onlineStatusWindow = new BrowserWindow({\n width: 400,\n height: 100\n })\n\n onlineStatusWindow.loadFile('index.html')\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nAfter launching the Electron application, you should see the notification:
\n
\n", "title": "Обнаружение Online/Offline событий", "description": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API." }, "/docs/development/patches": { "locale": "ru-RU", "slug": "patches", "href": "/docs/development/patches", "crowdinFileId": "256161", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/patches.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API.
\n
Electron is built on two major upstream projects: Chromium and Node.js. Each of these projects has several of their own dependencies, too. We try our best to use these dependencies exactly as they are but sometimes we can't achieve our goals without patching those upstream dependencies to fit our use cases.
\nEvery patch in Electron is a maintenance burden. When upstream code changes, patches can break—sometimes without even a patch conflict or a compilation error. It's an ongoing effort to keep our patch set up-to-date and effective. So we strive to keep our patch count at a minimum. To that end, every patch must describe its reason for existence in its commit message. That reason must be one of the following:
\nProfile). Include reasoning about why the change cannot be implemented without a patch (e.g. by subclassing or copying the code).In general, all the upstream projects we work with are friendly folks and are often happy to accept refactorings that allow the code in question to be compatible with both Electron and the upstream project. (See e.g. this change in Chromium, which allowed us to remove a patch that did the same thing, or this change in Node, which was a no-op for Node but fixed a bug in Electron.) We should aim to upstream changes whenever we can, and avoid indefinite-lifetime patches.
\nIf you find yourself in the unfortunate position of having to make a change which can only be made through patching an upstream project, you'll need to know how to manage patches in Electron.
\nAll patches to upstream projects in Electron are contained in the patches/ directory. Each subdirectory of patches/ contains several patch files, along with a .patches file which lists the order in which the patches should be applied. Think of these files as making up a series of git commits that are applied on top of the upstream project after we check it out.
patches\n├── config.json <-- this describes which patchset directory is applied to what project\n├── chromium\n│ ├── .patches\n│ ├── accelerator.patch\n│ ├── add_contentgpuclient_precreatemessageloop_callback.patch\n│ ⋮\n├── node\n│ ├── .patches\n│ ├── add_openssl_is_boringssl_guard_to_oaep_hash_check.patch\n│ ├── build_add_gn_build_files.patch\n│ ⋮\n⋮\nTo help manage these patch sets, we provide two tools: git-import-patches and git-export-patches. git-import-patches imports a set of patch files into a git repository by applying each patch in the correct order and creating a commit for each one. git-export-patches does the reverse; it exports a series of git commits in a repository into a set of files in a directory and an accompanying .patches file.
\n\nSide note: the reason we use a
\n.patchesfile to maintain the order of applied patches, rather than prepending a number like001-to each file, is because it reduces conflicts related to patch ordering. It prevents the situation where two PRs both add a patch at the end of the series with the same numbering and end up both getting merged resulting in a duplicate identifier, and it also reduces churn when a patch is added or deleted in the middle of the series.
$ cd src/third_party/electron_node\n$ vim some/code/file.cc\n$ git commit\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\n\n\nNOTE:
\ngit-export-patchesignores any uncommitted files, so you must create a commit if you want your changes to be exported. The subject line of the commit message will be used to derive the patch file name, and the body of the commit message should include the reason for the patch's existence.
Re-exporting patches will sometimes cause shasums in unrelated patches to change. This is generally harmless and can be ignored (but go ahead and add those changes to your PR, it'll stop them from showing up for other people).
\n$ cd src/v8\n$ vim some/code/file.cc\n$ git log\n# Найти коммит патча, который вы хотите редактировать.\n$ git commit --fixup [COMMIT_SHA]\n$ git rebase --autosquash -i [COMMIT_SHA]^\n$ ../electron/script/git-export-patches -o ../electron/patches/v8\n$ vim src/electron/patches/node/.patches\n# Delete the line with the name of the patch you want to remove\n$ cd src/third_party/electron_node\n$ git reset --hard refs/patches/upstream-head\n$ ../../electron/script/git-import-patches ../../electron/patches/node\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\nNote that git-import-patches will mark the commit that was HEAD when it was run as refs/patches/upstream-head. This lets you keep track of which commits are from Electron patches (those that come after refs/patches/upstream-head) and which commits are in upstream (those before refs/patches/upstream-head).
When updating an upstream dependency, patches may fail to apply cleanly. Often, the conflict can be resolved automatically by git with a 3-way merge. You can instruct git-import-patches to use the 3-way merge algorithm by passing the -3 argument:
$ cd src/third_party/electron_node\n# If the patch application failed midway through, you can reset it with:\n$ git am --abort\n# And then retry with 3-way merge:\n$ ../../electron/script/git-import-patches -3 ../../electron/patches/node\nIf git-import-patches -3 encounters a merge conflict that it can't resolve automatically, it will pause and allow you to resolve the conflict manually. Once you have resolved the conflict, git add the resolved files and continue to apply the rest of the patches by running git am --continue.
Разработчики часто спрашивают о стратегиях оптимизации производительности приложений Electron. Les ingénieurs, les consommateurs et les développeurs de framework ne sont pas toujours d'accord sur une seule définition de ce que signifie \"performance\". This document outlines some of the Electron maintainers' favorite ways to reduce the amount of memory, CPU, and disk resources being used while ensuring that your app is responsive to user input and completes operations as quickly as possible. Furthermore, we want all performance strategies to maintain a high standard for your app's security.
\nWisdom and information about how to build performant websites with JavaScript generally applies to Electron apps, too. To a certain extent, resources discussing how to build performant Node.js applications also apply, but be careful to understand that the term \"performance\" means different things for a Node.js backend than it does for an application running on a client.
\nThis list is provided for your convenience – and is, much like our security checklist – not meant to exhaustive. It is probably possible to build a slow Electron app that follows all the steps outlined below. Electron is a powerful development platform that enables you, the developer, to do more or less whatever you want. All that freedom means that performance is largely your responsibility.
\nВ приведенном ниже списке содержится ряд шагов, которые достаточно просты и легко осуществить. Тем не менее, создание наиболее эффективной версии вашего приложения потребует вас выйти за рамки нескольких шагов. Instead, you will have to closely examine all the code running in your app by carefully profiling and measuring. Where are the bottlenecks? When the user clicks a button, what operations take up the brunt of the time? While the app is simply idling, which objects take up the most memory?
\nTime and time again, we have seen that the most successful strategy for building a performant Electron app is to profile the running code, find the most resource-hungry piece of it, and to optimize it. Repeating this seemingly laborious process over and over again will dramatically increase your app's performance. Experience from working with major apps like Visual Studio Code or Slack has shown that this practice is by far the most reliable strategy to improve performance.
\nTo learn more about how to profile your app's code, familiarize yourself with the Chrome Developer Tools. For advanced analysis looking at multiple processes at once, consider the Chrome Tracing tool.
\nChances are that your app could be a little leaner, faster, and generally less resource-hungry if you attempt these steps.
\nBefore adding a Node.js module to your application, examine said module. How many dependencies does that module include? What kind of resources does it need to simply be called in a require() statement? You might find that the module with the most downloads on the NPM package registry or the most stars on GitHub is not in fact the leanest or smallest one available.
The reasoning behind this recommendation is best illustrated with a real-world example. During the early days of Electron, reliable detection of network connectivity was a problem, resulting many apps to use a module that exposed a simple isOnline() method.
That module detected your network connectivity by attempting to reach out to a number of well-known endpoints. For the list of those endpoints, it depended on a different module, which also contained a list of well-known ports. This dependency itself relied on a module containing information about ports, which came in the form of a JSON file with more than 100,000 lines of content. Whenever the module was loaded (usually in a require('module') statement), it would load all its dependencies and eventually read and parse this JSON file. Parsing many thousands lines of JSON is a very expensive operation. On a slow machine it can take up whole seconds of time.
In many server contexts, startup time is virtually irrelevant. A Node.js server that requires information about all ports is likely actually \"more performant\" if it loads all required information into memory whenever the server boots at the benefit of serving requests faster. The module discussed in this example is not a \"bad\" module. Electron apps, however, should not be loading, parsing, and storing in memory information that it does not actually need.
\nIn short, a seemingly excellent module written primarily for Node.js servers running Linux might be bad news for your app's performance. In this particular example, the correct solution was to use no module at all, and to instead use connectivity checks included in later versions of Chromium.
\nWhen considering a module, we recommend that you check:
\nrequire()) itGenerating a CPU profile and a heap memory profile for loading a module can be done with a single command on the command line. In the example below, we're looking at the popular module request.
node --cpu-prof --heap-prof -e \"require('request')\"\nExecuting this command results in a .cpuprofile file and a .heapprofile file in the directory you executed it in. Both files can be analyzed using the Chrome Developer Tools, using the Performance and Memory tabs respectively.
In this example, on the author's machine, we saw that loading request took almost half a second, whereas node-fetch took dramatically less memory and less than 50ms.
If you have expensive setup operations, consider deferring those. Inspect all the work being executed right after the application starts. Instead of firing off all operations right away, consider staggering them in a sequence more closely aligned with the user's journey.
\nIn traditional Node.js development, we're used to putting all our require() statements at the top. If you're currently writing your Electron application using the same strategy and are using sizable modules that you do not immediately need, apply the same strategy and defer loading to a more opportune time.
Loading modules is a surprisingly expensive operation, especially on Windows. When your app starts, it should not make users wait for operations that are currently not necessary.
\nThis might seem obvious, but many applications tend to do a large amount of work immediately after the app has launched - like checking for updates, downloading content used in a later flow, or performing heavy disk I/O operations.
\nLet's consider Visual Studio Code as an example. When you open a file, it will immediately display the file to you without any code highlighting, prioritizing your ability to interact with the text. Once it has done that work, it will move on to code highlighting.
\nLet's consider an example and assume that your application is parsing files in the fictitious .foo format. In order to do that, it relies on the equally fictitious foo-parser module. In traditional Node.js development, you might write code that eagerly loads dependencies:
const fs = require('fs')\nconst fooParser = require('foo-parser')\n\nclass Parser {\n constructor () {\n this.files = fs.readdirSync('.')\n }\n\n getParsedFiles () {\n return fooParser.parse(this.files)\n }\n}\n\nconst parser = new Parser()\n\nmodule.exports = { parser }\nIn the above example, we're doing a lot of work that's being executed as soon as the file is loaded. Do we need to get parsed files right away? Could we do this work a little later, when getParsedFiles() is actually called?
// \"fs\" is likely already being loaded, so the `require()` call is cheap\nconst fs = require('fs')\n\nclass Parser {\n async getFiles () {\n // Touch the disk as soon as `getFiles` is called, not sooner.\n // Also, ensure that we're not blocking other operations by using\n // the asynchronous version.\n this.files = this.files || await fs.readdir('.')\n\n return this.files\n }\n\n async getParsedFiles () {\n // Our fictitious foo-parser is a big and expensive module to load, so\n // defer that work until we actually need to parse files.\n // Since `require()` comes with a module cache, the `require()` call\n // will only be expensive once - subsequent calls of `getParsedFiles()`\n // will be faster.\n const fooParser = require('foo-parser')\n const files = await this.getFiles()\n\n return fooParser.parse(files)\n }\n}\n\n// This operation is now a lot cheaper than in our previous example\nconst parser = new Parser()\n\nmodule.exports = { parser }\nIn short, allocate resources \"just in time\" rather than allocating them all when your app starts.
\nElectron's main process (sometimes called \"browser process\") is special: It is the parent process to all your app's other processes and the primary process the operating system interacts with. It handles windows, interactions, and the communication between various components inside your app. It also houses the UI thread.
\nUnder no circumstances should you block this process and the UI thread with long-running operations. Blocking the UI thread means that your entire app will freeze until the main process is ready to continue processing.
\nThe main process and its UI thread are essentially the control tower for major operations inside your app. When the operating system tells your app about a mouse click, it'll go through the main process before it reaches your window. If your window is rendering a buttery-smooth animation, it'll need to talk to the GPU process about that – once again going through the main process.
\nElectron and Chromium are careful to put heavy disk I/O and CPU-bound operations onto new threads to avoid blocking the UI thread. You should do the same.
\nElectron's powerful multi-process architecture stands ready to assist you with your long-running tasks, but also includes a small number of performance traps.
\n1) For long running CPU-heavy tasks, make use of worker threads, consider moving them to the BrowserWindow, or (as a last resort) spawn a dedicated process.
\n2) Avoid using the synchronous IPC and the remote module as much as possible. While there are legitimate use cases, it is far too easy to unknowingly block the UI thread using the remote module.
3) Avoid using blocking I/O operations in the main process. In short, whenever core Node.js modules (like fs or child_process) offer a synchronous or an asynchronous version, you should prefer the asynchronous and non-blocking variant.
Since Electron ships with a current version of Chrome, you can make use of the latest and greatest features the Web Platform offers to defer or offload heavy operations in a way that keeps your app smooth and responsive.
\nYour app probably has a lot of JavaScript to run in the renderer process. The trick is to execute operations as quickly as possible without taking away resources needed to keep scrolling smooth, respond to user input, or animations at 60fps.
\nOrchestrating the flow of operations in your renderer's code is particularly useful if users complain about your app sometimes \"stuttering\".
\nGenerally speaking, all advice for building performant web apps for modern browsers apply to Electron's renderers, too. The two primary tools at your disposal are currently requestIdleCallback() for small operations and Web Workers for long-running operations.
requestIdleCallback() allows developers to queue up a function to be executed as soon as the process is entering an idle period. It enables you to perform low-priority or background work without impacting the user experience. For more information about how to use it, check out its documentation on MDN.
Web Workers are a powerful tool to run code on a separate thread. There are some caveats to consider – consult Electron's multithreading documentation and the MDN documentation for Web Workers. They're an ideal solution for any operation that requires a lot of CPU power for an extended period of time.
\nОдним из преимуществ Electron является то, что вы точно знаете, какой движок будет парсить ваш JavaScript, HTML и CSS. Если вы повторно используете код, который был написан для веб в целом, убедитесь, что вы не должны полифилить функции, включенные в Electron.
\nWhen building a web application for today's Internet, the oldest environments dictate what features you can and cannot use. Even though Electron supports well-performing CSS filters and animations, an older browser might not. Where you could use WebGL, your developers may have chosen a more resource-hungry solution to support older phones.
\nWhen it comes to JavaScript, you may have included toolkit libraries like jQuery for DOM selectors or polyfills like the regenerator-runtime to support async/await.
It is rare for a JavaScript-based polyfill to be faster than the equivalent native feature in Electron. Do not slow down your Electron app by shipping your own version of standard web platform features.
\nOperate under the assumption that polyfills in current versions of Electron are unnecessary. If you have doubts, check caniuse.com and check if the version of Chromium used in your Electron version supports the feature you desire.
\nКроме того, внимательно изучите используемые вами библиотеки. Действительно ли они необходимы? Например, jQuery, был настолько успешным, что многие его функции теперь являются частью стандартного набора возможностей JavaScript.
If you're using a transpiler/compiler like TypeScript, examine its configuration and ensure that you're targeting the latest ECMAScript version supported by Electron.
\nAvoid fetching rarely changing resources from the internet if they could easily be bundled with your application.
\nMany users of Electron start with an entirely web-based app that they're turning into a desktop application. As web developers, we are used to loading resources from a variety of content delivery networks. Now that you are shipping a proper desktop application, attempt to \"cut the cord\" where possible and avoid letting your users wait for resources that never change and could easily be included in your app.
\nA typical example is Google Fonts. Many developers make use of Google's impressive collection of free fonts, which comes with a content delivery network. The pitch is straightforward: Include a few lines of CSS and Google will take care of the rest.
\nWhen building an Electron app, your users are better served if you download the fonts and include them in your app's bundle.
\nIn an ideal world, your application wouldn't need the network to operate at all. To get there, you must understand what resources your app is downloading - and how large those resources are.
\nTo do so, open up the developer tools. Navigate to the Network tab and check the Disable cache option. Then, reload your renderer. Unless your app prohibits such reloads, you can usually trigger a reload by hitting Cmd + R or Ctrl + R with the developer tools in focus.
The tools will now meticulously record all network requests. In a first pass, take stock of all the resources being downloaded, focusing on the larger files first. Are any of them images, fonts, or media files that don't change and could be included with your bundle? If so, include them.
\nAs a next step, enable Network Throttling. Find the drop-down that currently reads Online and select a slower speed such as Fast 3G. Reload your renderer and see if there are any resources that your app is unnecessarily waiting for. In many cases, an app will wait for a network request to complete despite not actually needing the involved resource.
As a tip, loading resources from the Internet that you might want to change without shipping an application update is a powerful strategy. For advanced control over how resources are being loaded, consider investing in Service Workers.
\nAs already pointed out in \"Loading and running code too soon\", calling require() is an expensive operation. If you are able to do so, bundle your application's code into a single file.
Modern JavaScript development usually involves many files and modules. While that's perfectly fine for developing with Electron, we heavily recommend that you bundle all your code into one single file to ensure that the overhead included in calling require() is only paid once when your application loads.
There are numerous JavaScript bundlers out there and we know better than to anger the community by recommending one tool over another. We do however recommend that you use a bundler that is able to handle Electron's unique environment that needs to handle both Node.js and browser environments.
\nAs of writing this article, the popular choices include Webpack, Parcel, and rollup.js.
", "title": "Характеристика", "description": "" }, "/docs/api/structures/point": { "locale": "ru-RU", "slug": "point", "href": "/docs/api/structures/point", "crowdinFileId": "256475", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/point.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "x Numbery NumberNote: Both x and y must be whole integers, when providing a point object as input to an Electron API we will automatically round your x and y values to the nearest whole integer.
data (UploadRawData | UploadFile)[] - The post data to be sent to the new window.contentType String - The content-type header used for the data. One of application/x-www-form-urlencoded or multipart/form-data. Corresponds to the enctype attribute of the submitted HTML form.boundary String (optional) - The boundary used to separate multiple parts of the message. Only valid when contentType is multipart/form-data.Note that keys starting with -- are not currently supported. For example, this will errantly submit as multipart/form-data when nativeWindowOpen is set to false in webPreferences:
<form\n target=\"_blank\"\n method=\"POST\"\n enctype=\"application/x-www-form-urlencoded\"\n action=\"https://postman-echo.com/post\"\n>\n <input type=\"text\" name=\"--theKey\">\n <input type=\"submit\">\n</form>\n\n\nОтслеживает изменения состояния питания устройства.
\n
Процесс: Основной
\nМодуль powerMonitor выдает следующие события:
Возникает, когда система приостановлена.
\nВозникает при возобновлении работы системы.
\nИспользуется при переключении системы на питание от переменного тока (блока питания).
\nИспользуется при переключении системы на питание от батареи.
\nВозникает, когда система собирается перезагрузиться или выключиться. Если обработчик события вызывает e.preventDefault(), Electron попытается отложить завершение работы системы, чтобы приложение корректно завершило работу. Если вызывается e.preventDefault(), приложение должно выйти как можно скорее, вызвав что-то вроде app.quit().
Возникает, когда система собирается заблокировать экран.
\nВозникает, как только система разблокирует экран.
\nEmitted when a login session is activated. See documentation for more information.
\nEmitted when a login session is deactivated. See documentation for more information.
\nМодуль powerMonitor имеет следующие методы:
powerMonitor.getSystemIdleState(idleThreshold)idleThreshold IntegerReturns String - The system's current state. Может быть active, idle, locked или unknown.
Calculate the system idle state. idleThreshold is the amount of time (in seconds) before considered idle. locked is available on supported systems only.
powerMonitor.getSystemIdleTime()Возвращает Integer - время простоя в секундах
Расчет времени простоя системы в секундах.
\npowerMonitor.isOnBatteryPower()Returns Boolean - Whether the system is on battery power.
To monitor for changes in this property, use the on-battery and on-ac events.
powerMonitor.onBatteryPowerA Boolean property. True if the system is on battery power.
See powerMonitor.isOnBatteryPower().
\n\nПредотвращает переход системы в режим пониженного потребления питания.
\n
Процесс: Основной
\nНапример:
\nconst { powerSaveBlocker } = require('electron')\n\nconst id = powerSaveBlocker.start('prevent-display-sleep')\nconsole.log(powerSaveBlocker.isStarted(id))\n\npowerSaveBlocker.stop(id)\nМодуль powerSaveBlocker имеет следующие методы:
powerSaveBlocker.start(type)type String - Power save blocker type.prevent-app-suspension - Prevent the application from being suspended. Keeps system active but allows screen to be turned off. Example use cases: downloading a file or playing audio.prevent-display-sleep - Prevent the display from going to sleep. Keeps system and screen active. Example use case: playing video.Возвращает Integer - Идентификатор блокировщика, назначенный этому блокировщику питания.
Starts preventing the system from entering lower-power mode. Returns an integer identifying the power save blocker.
\nПримечание: prevent-display-sleep имеет более высокий приоритет перед prevent-app-suspension. Вступает в силу только наиболее высокий тип приоритета. Другими словами, prevent-display-sleep всегда выше prevent-app-suspension.
Например, API-интерфейс, вызывающий запросы A для prevent-app-suspension, и другой вызов запросов B для prevent-display-sleep. prevent-display-sleep будет использоваться до тех пор, пока B не прекратит свой запрос. После этого, будет использоваться prevent-app-suspension.
powerSaveBlocker.stop(id)id Integer - Идентификатор блокировщика энергосбережения, возвращённый powerSaveBlocker.start.Останавливает указанный блокировщик энергосбережения.
\npowerSaveBlocker.isStarted(id)id Integer - Идентификатор блокировщика энергосбережения, возвращённый powerSaveBlocker.start.Возвращает Boolean - Запущен ли соответствующий powerSaveBlocker.
name String - the name of the printer as understood by the OS.displayName String - the name of the printer as shown in Print Preview.description String - a longer description of the printer's type.status Number - the current status of the printer.isDefault Boolean - whether or not a given printer is set as the default printer on the OS.options Object - an object containing a variable number of platform-specific printer information.The number represented by status means different things on different platforms: on Windows its potential values can be found here, and on Linux and macOS they can be found here.
Below is an example of some of the additional options that may be set which may be different on each platform.
\n{\n name: 'Austin_4th_Floor_Printer___C02XK13BJHD4',\n displayName: 'Austin 4th Floor Printer @ C02XK13BJHD4',\n description: 'TOSHIBA ColorMFP',\n status: 3,\n isDefault: false,\n options: {\n copies: '1',\n 'device-uri': 'dnssd://Austin%204th%20Floor%20Printer%20%40%20C02XK13BJHD4._ipps._tcp.local./?uuid=71687f1e-1147-3274-6674-22de61b110bd',\n finishings: '3',\n 'job-cancel-after': '10800',\n 'job-hold-until': 'no-hold',\n 'job-priority': '50',\n 'job-sheets': 'none,none',\n 'marker-change-time': '0',\n 'number-up': '1',\n 'printer-commands': 'ReportLevels,PrintSelfTestPage,com.toshiba.ColourProfiles.update,com.toshiba.EFiling.update,com.toshiba.EFiling.checkPassword',\n 'printer-info': 'Austin 4th Floor Printer @ C02XK13BJHD4',\n 'printer-is-accepting-jobs': 'true',\n 'printer-is-shared': 'false',\n 'printer-is-temporary': 'false',\n 'printer-location': '',\n 'printer-make-and-model': 'TOSHIBA ColorMFP',\n 'printer-state': '3',\n 'printer-state-change-time': '1573472937',\n 'printer-state-reasons': 'offline-report,com.toshiba.snmp.failed',\n 'printer-type': '10531038',\n 'printer-uri-supported': 'ipp://localhost/printers/Austin_4th_Floor_Printer___C02XK13BJHD4',\n system_driverinfo: 'T'\n }\n}\n\n\nРасширения для обработки объекта.
\n
Процессы: Основной, Графический
\nОбъект Electron process является расширенной версией объекта Node.js process. Он добавляет следующие события, свойства и методы:
В песочнице графический объект process содержит только подмножество API:
crash() - Падениеhang() - ЗависаниеgetCreationTime() - Время созданияgetHeapStatistics() - Статистика кучи (распределяемой памяти)getBlinkMemoryInfo() - Информация о памяти BlinkgetProcessMemoryInfo() - Сведения о памяти процессаgetSystemMemoryInfo() - Информация о системной памятиgetSystemVersion() - Версия системыgetCPUUsage() - Использование процессораgetIOCounters() - Счетчики IOuptime()argvexecPathenvpidarchplatformsandboxed - Запущена ли песочницаcontextIsolatedтипверсияversions - Список с версиями и их зависимостямиmas - Является ли сборкой Mac App StorewindowsStore - Является ли приложением Windows Store (appx)contextIdСрабатывает, когда Electron загрузил свой скрипт внутренней инициализации и начинает загружать веб-страницу или основной скрипт.
\nprocess.defaultApp Только чтениеA Boolean. When app is started by being passed as parameter to the default app, this property is true in the main process, otherwise it is undefined.
process.isMainFrame Только чтениеA Boolean, true when the current renderer context is the \"main\" renderer frame. If you want the ID of the current frame you should use webFrame.routingId.
process.mas Только чтениеA Boolean. For Mac App Store build, this property is true, for other builds it is undefined.
process.noAsarA Boolean that controls ASAR support inside your application. Setting this to true will disable the support for asar archives in Node's built-in modules.
process.noDeprecationBoolean. Контролирует будут ли неодобряющие предупреждения выводиться в stderr. Установка в true заглушит неодобряющие предупреждения. Это свойство используется вместо флага командной строки --no-deprecation.
process.resourcesPath Только чтениеString. Представляет из себя путь до каталога с ресурсами.
process.sandboxed Только чтениеA Boolean. When the renderer process is sandboxed, this property is true, otherwise it is undefined.
process.contextIsolated Только чтениеA Boolean that indicates whether the current renderer context has contextIsolation enabled. It is undefined in the main process.
process.throwDeprecationBoolean, определяет, будут ли предупреждения об устаревании выдаваться как исключения. Установка значения true приведет к выдаче ошибок при устаревании. Это свойство используется вместо флага командной строки --throw-deprecation.
process.traceDeprecationBoolean, определяет, будут ли сообщения об устаревании выдаваемые в stderr, включать трассировку стека. Установка значения true напечатает трассировку стека при устаревании. Это свойство вместо флага командной строки --trace-deprecation.
process.traceProcessWarningsBoolean, определяет, будут ли предупреждения процесса, выдаваемые в stderr, включать трассировку стека. Установка значения true напечатает трассировку стека для предупреждений процесса (включая устаревания). Это свойство вместо флага командной строки --trace-warnings.
process.type Только чтениеA String representing the current process's type, can be:
browser - The main processrenderer - A renderer processworker - In a web workerprocess.versions.chrome Только чтениеString, представляющая строку версии Chrome.
process.versions.electron Только чтениеString, представляющая строку версии Electron.
process.windowsStore Только чтениеA Boolean. If the app is running as a Windows Store app (appx), this property is true, for otherwise it is undefined.
process.contextId Только чтениеA String (optional) representing a globally unique ID of the current JavaScript context. Each frame has its own JavaScript context. When contextIsolation is enabled, the isolated world also has a separate JavaScript context. This property is only available in the renderer process.
Объект process имеет следующие методы:
process.crash()Вызывает сбой основного потока текущего процесса.
\nprocess.getCreationTime()Возвращает Number | null - Количество миллисекунд с начала эпохи, или null, если информация недоступна
Indicates the creation time of the application. Время представлено как количество миллисекунд с начала эпохи. It returns null if it is unable to get the process creation time.
\nprocess.getCPUUsage()Возвращает CPUUsage
process.getIOCounters() Windows LinuxВозвращает IOCounters
process.getHeapStatistics()Возвращает Object:
totalHeapSize Integer - Память, выделенная для кучиtotalHeapSizeExecutable Integer - Память для исполняемого файлаtotalPhysicalSize Integer - Заданный размерtotalAvailableSize Integer - Доступный размер кучиusedHeapSize Integer - Память, используемая данными приложенияheapSizeLimit Integer - Абсолютный предел, который куча не может превышатьmallocedMemory Integer - Текущий объем памяти, полученный через mallocpeakMallocedMemory Integer - Пиковый объем памяти, полученный через mallocdoesZapGarbage Boolean - Включена ли опция --zap_code_spaceReturns an object with V8 heap statistics. Обратите внимание, что вся статистика предоставляется в Килобайтах.
\nprocess.getBlinkMemoryInfo()Возвращает Object:
allocated Integer - Размер всех выделенных объектов в Килобайтах.marked Integer - Размер всех отмеченных объектов в Килобайтах.total Integer - Всего выделено места в Килобайтах.Returns an object with Blink memory information. It can be useful for debugging rendering / DOM related memory issues. Note that all values are reported in Kilobytes.
\nprocess.getProcessMemoryInfo()Возвращает Promise<ProcessMemoryInfo> - Разрешается с ProcessMemoryInfo
Returns an object giving memory usage statistics about the current process. Note that all statistics are reported in Kilobytes. This api should be called after app ready.
\nChromium не предоставляет значение residentSet для macOS. Это связано с тем, что MacOS сжимает в памяти страницы, которые в последнее время не использовались. В результате значение размера резидентного набора не соответствует ожидаемому. private память является более репрезентативной для фактического использования перед сжатием памяти процесса в MacOS.
process.getSystemMemoryInfo()Возвращает Object:
total Integer - Общий объем физической памяти в килобайтах, доступный системе.free Integer - Общий объем памяти, не используемый приложениями или дисковым кэшем.swapTotal Integer Windows Linux - Общий объем памяти подкачки в килобайтах, доступной системе.swapFree Integer Windows Linux - Свободный объем памяти подкачки в килобайтах, доступный системе.Returns an object giving memory usage statistics about the entire system. Note that all statistics are reported in Kilobytes.
\nprocess.getSystemVersion()Возвращает String - Версию операционной системы хоста.
Пример:
\nconst version = process.getSystemVersion()\nconsole.log(version)\n// В macOS -> '10.13.6'\n// В Windows -> '10.0.17763'\n// В Linux -> '4.15.0-45-generic'\nПримечание: В отличие от os.release() он возвращает фактическую версию операционной системы, а не версию ядра на MacOS.
process.takeHeapSnapshot(filePath)filePath String - Path to the output file.Возвращает Boolean, который указывает успешно ли создан снимок.
Делает снимок кучи V8 и сохраняет его в filePath.
process.hang()Вызывает зависание основного потока текущего процесса.
\nprocess.setFdLimit(maxDescriptors) macOS LinuxmaxDescriptors IntegerУстанавливает мягкое ограничение дескрипторов файлов до maxDescriptors или жесткое ограничение операционной системы, в зависимости от того, какое значение ниже для текущего процесса.
residentSet Integer Linux Windows - The amount of memory currently pinned to actual physical RAM in Kilobytes.private Integer - The amount of memory not shared by other processes, such as JS heap or HTML content in Kilobytes.shared Integer - The amount of memory shared between processes, typically memory consumed by the Electron code itself in Kilobytes.pid Integer - Process id of the process.type String - Тип процесса. Одно из следующих значений:BrowserTabUtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownserviceName String (optional) - The non-localized name of the process.name String (опционально) - Название процесса. Например: Audio Service, Content Decryption Module Service, Network Service, Video Capture и т.д.cpu CPUUsage - CPU usage of the process.creationTime Number - Creation time for this process. The time is represented as number of milliseconds since epoch. Since the pid can be reused after a process dies, it is useful to use both the pid and the creationTime to uniquely identify a process.memory MemoryInfo - Memory information for the process.sandboxed Boolean (optional) macOS Windows - Whether the process is sandboxed on OS level.integrityLevel String (optional) Windows - One of the following values:untrustedlowmediumhighunknownElectron inherits its multi-process architecture from Chromium, which makes the framework architecturally very similar to a modern web browser. In this guide, we'll expound on the conceptual knowledge of Electron that we applied in the minimal quick start app.
\nWeb browsers are incredibly complicated applications. Aside from their primary ability to display web content, they have many secondary responsibilities, such as managing multiple windows (or tabs) and loading third-party extensions.
\nIn the earlier days, browsers usually used a single process for all of this functionality. Although this pattern meant less overhead for each tab you had open, it also meant that one website crashing or hanging would affect the entire browser.
\nTo solve this problem, the Chrome team decided that each tab would render in its own process, limiting the harm that buggy or malicious code on a web page could cause to the app as a whole. A single browser process then controls these processes, as well as the application lifecycle as a whole. This diagram below from the Chrome Comic visualizes this model:
\n
Electron applications are structured very similarly. As an app developer, you control two types of processes: main and renderer. These are analogous to Chrome's own browser and renderer processes outlined above.
\nEach Electron app has a single main process, which acts as the application's entry point. The main process runs in a Node.js environment, meaning it has the ability to require modules and use all of Node.js APIs.
The main process' primary purpose is to create and manage application windows with the BrowserWindow module.
Each instance of the BrowserWindow class creates an application window that loads a web page in a separate renderer process. You can interact with this web content from the main process using the window's webContents object.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\n\n\nNote: A renderer process is also created for web embeds such as the
\nBrowserViewmodule. ThewebContentsobject is also accessible for embedded web content.
Because the BrowserWindow module is an EventEmitter, you can also add handlers for various user events (for example, minimizing or maximizing your window).
When a BrowserWindow instance is destroyed, its corresponding renderer process gets terminated as well.
The main process also controls your application's lifecycle through Electron's app module. This module provides a large set of events and methods that you can use to add custom application behaviour (for instance, programatically quitting your application, modifying the application dock, or showing an About panel).
As a practical example, the app shown in the quick start guide uses app APIs to create a more native application window experience.
// выход из приложения на не macOS платформах , если окно программы не открылось\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nTo extend Electron's features beyond being a Chromium wrapper for web contents, the main process also adds custom APIs to interact with the user's operating system. Electron exposes various modules that control native desktop functionality, such as menus, dialogs, and tray icons.
\nFor a full list of Electron's main process modules, check out our API documentation.
\nEach Electron app spawns a separate renderer process for each open BrowserWindow (and each web embed). As its name implies, a renderer is responsible for rendering web content. For all intents and purposes, code ran in renderer processes should behave according to web standards (insofar as Chromium does, at least).
Therefore, all user interfaces and app functionality within a single browser window should be written with the same tools and paradigms that you use on the web.
\nAlthough explaining every web spec is out of scope for this guide, the bare minimum to understand is:
\n<script> elements.Moreover, this also means that the renderer has no direct access to require or other Node.js APIs. In order to directly include NPM modules in the renderer, you must use the same bundler toolchains (for example, webpack or parcel) that you use on the web.
\n\nNote: Renderer processes can be spawned with a full Node.js environment for ease of development. Historically, this used to be the default, but this feature was disabled for security reasons.
\n
At this point, you might be wondering how your renderer process user interfaces can interact with Node.js and Electron's native desktop functionality if these features are only accessible from the main process. In fact, there is no direct way to import Electron's content scripts.
\nA preload script can be attached to the main process in the BrowserWindow constructor's webPreferences option.
const { BrowserWindow } = require('electron')\n//...\nconst win = new BrowserWindow({\n webPreferences: {\n preload: 'path/to/preload.js'\n }\n})\n//...\nBecause the preload script shares a global Window interface with the renderers and can access Node.js APIs, it serves to enhance your renderer by exposing arbitrary APIs in the window global that your web contents can then consume.
Although preload scripts share a window global with the renderer they're attached to, you cannot directly attach any variables from the preload script to window because of the contextIsolation default.
window.myAPI = {\n desktop: true\n}\nconsole.log(window.myAPI)\n// => undefined\nContext Isolation means that preload scripts are isolated from the renderer's main world to avoid leaking any privileged APIs into your web content's code.
\nInstead, use the contextBridge module to accomplish this securely:
const { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n desktop: true\n})\nconsole.log(window.myAPI)\n// => { desktop: true }\nThis feature is incredibly useful for two main purposes:
\nipcRenderer helpers to the renderer, you can use inter-process communication (IPC) to trigger main process tasks from the renderer (and vice-versa).window global that can be used for desktop-only logic on the web client's side.productIdentifier String - The string that identifies the product to the Apple App Store.localizedDescription String - A description of the product.localizedTitle String - The name of the product.contentVersion String - A string that identifies the version of the content.contentLengths Number[] - The total size of the content, in bytes.price Number - The cost of the product in the local currency.formattedPrice String - The locale formatted price of the product.currencyCode String - 3 character code presenting a product's currency based on the ISO 4217 standard.isDownloadable Boolean - A Boolean value that indicates whether the App Store has downloadable content for this product. true if at least one file has been associated with the product.Progress bar позволяет окну предоставлять информацию о прогрессе пользователю без необходимости переключения на само окно.
\nВ Windows вы можете использовать кнопку панели задач для отображения progress bar.
\n![Windows Progress Bar][https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png\\]
\nНа macOS progress bar будет отображаться как часть dock icon.
\n
На Linux графический интерфейс Unity также имеет аналогичную функцию, которая вам указать планку прогресса в пусковой установке.
\n
\n\nПРИМЕЧАНИЕ: на Windows, каждое окно может иметь свой собственный планку прогресса, в то время как на macOS и Linux (Unity) может быть только одна планка прогресса для приложения.
\n
Все три случая охватываются одним и тем же API - setProgressBar() методом, доступным на экземпляре BrowserWindow. Чтобы указать свой прогресс, позвоните в этот метод с номером между 0 и 1. Например, если у вас есть давняя задача, которая в настоящее время 63% к завершению, вы назвали бы ее как setProgressBar(0.63).
Setting the parameter to negative values (e.g. -1) will remove the progress bar. Setting it to a value greater than 1 will indicate an indeterminate progress bar in Windows or clamp to 100% in other operating systems. An indeterminate progress bar remains active but does not show an actual percentage, and is used for situations when you do not know how long an operation will take to complete.
Просмотрите документацию по API для большего количества опций и режимов.
\nIn this example, we add a progress bar to the main window that increments over time using Node.js timers.
\nconst { app, BrowserWindow } = require('electron')\n\nlet progressInterval\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n\n const INCREMENT = 0.03\n const INTERVAL_DELAY = 100 // ms\n\n let c = 0\n progressInterval = setInterval(() => {\n // update progress bar to next value\n // values between 0 and 1 will show progress, >1 will show indeterminate or stick at 100%\n win.setProgressBar(c)\n\n // increment or reset progress bar\n if (c < 2) c += INCREMENT\n else c = 0\n }, INTERVAL_DELAY)\n}\n\napp.whenReady().then(createWindow)\n\n// before the app is terminated, clear both timers\napp.on('before-quit', () => {\n clearInterval(progressInterval)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nAfter launching the Electron application, the dock (macOS) or taskbar (Windows, Unity) should show a progress bar that starts at zero and progresses through 100% to completion. It should then show indeterminate (Windows) or pin to 100% (other operating systems) briefly and then loop.
\n
Для macOS планка прогресса также будет указана для вашей приложения использовании Mission Control:
\n
\n\nРегистрация пользовательского протокола и перехват существующих запросов протокола.
\n
Процесс: Основной
\nПример реализации протокола, имеющего тот же эффект, что и протокол file://:
const { app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n})\nПримечание: Все методы, если не указано другого, могут быть использованы только после того, как событие ready модуля app будет отправлено.
protocol с пользовательским разделом partition или сеансом sessionПротокол регистрируется для определенного Electron объекта session. Если вы не укажете сеанс, то ваш protocol будет применен сеансу по умолчанию, который использует Electron. Однако, если вы определите partition или session в браузереWindow в webPreferences, то это окно будет использовать другой сеанс, и ваш пользовательский протокол не будет работать, если вы просто используете electron.protocol.XXX.
Для того, чтобы ваш пользовательский протокол работал в сочетании с пользовательским сеансом, вам необходимо явно зарегистрировать его в этом сеансе.
\nconst { session, app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const partition = 'persist:example'\n const ses = session.fromPartition(partition)\n\n ses.protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n\n mainWindow = new BrowserWindow({ webPreferences: { partition } })\n})\nМодуль protocol имеет следующие методы:
protocol.registerSchemesAsPrivileged(customSchemes)customSchemes CustomScheme[]Примечание: Этот метод можно использовать только до отправки события ready модуля app и может быть вызван только один раз.
Registers the scheme as standard, secure, bypasses content security policy for resources, allows registering ServiceWorker, supports fetch API, and streaming video/audio. Specify a privilege with the value of true to enable the capability.
Пример регистрации привилегированной схемы, которая обходит Политику безопасности контента:
\nconst { protocol } = require('electron')\nprotocol.registerSchemesAsPrivileged([\n { scheme: 'foo', privileges: { bypassCSP: true } }\n])\nСтандартная схема соответствует вызовам RFC 3986 универсальный синтаксис URI. Например, http и https являются стандартными схемами, в то время как file не является.
Регистрация схемы в качестве стандартной позволяет правильно разрешать относительные и абсолютные ресурсы при обслуживании. В противном случае схема будет вести себя как протокол file, но без возможности разрешения относительных URL-адресов.
Например, когда вы загружаете следующую страницу с помощью пользовательского протокола, не регистрируя его как стандартную схему, изображение не будет загружено, потому что нестандартные схемы не могут распознать относительные URL-адреса:
\n<body>\n <img src='test.png'>\n</body>\nRegistering a scheme as standard will allow access to files through the FileSystem API. В противном случае программа для схемы выдаст ошибку безопасности.
\nПо умолчанию веб-хранилище Apis (localStorage, sessionStorage, webSQL, indexedDB, cookies) отключено для нестандартных схем. Поэтому в общем случае, если вы хотите зарегистрировать пользовательский протокол для замены протокола http, необходимо зарегистрировать его как стандартную схему.
Protocols that use streams (http and stream protocols) should set stream: true. The <video> and <audio> HTML elements expect protocols to buffer their responses by default. The stream flag configures those elements to correctly expect streaming responses.
protocol.registerFileProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Регистрирует протокол scheme, который отправит файл в качестве ответа. Обработчик handler будет вызван с запросом request и обратным вызовом callback, где запрос request является входящим запросом для схемы scheme.
To handle the request, the callback should be called with either the file's path or an object that has a path property, e.g. callback(filePath) or callback({ path: filePath }). filePath должен быть абсолютным путем.
По умолчанию scheme обрабатывается как http:, который анализируется иначе, чем протоколы, которые следуют \"общему синтаксису URI\", как file:.
protocol.registerBufferProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Регистрирует протокол scheme, который отправит Buffer в качестве ответа.
Использование аналогично registerFileProtocol, за исключением того, что callback должен вызываться либо с объектом Buffer, либо с объектом, имеющим свойство data.
Пример:
\nprotocol.registerBufferProtocol('atom', (request, callback) => {\n callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })\n})\nprotocol.registerStringProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Регистрирует протокол scheme, который отправит String в качестве ответа.
Использование аналогично registerFileProtocol, за исключением того, что callback должен вызываться либо с String, либо с объектом, имеющим свойство data.
protocol.registerHttpProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully registered
Регистрирует протокол scheme, который отправит HTTP-запрос в качестве ответа.
Использование аналогично registerFileProtocol, за исключением того, что callback должен быть вызван с объектом, имеющим свойство url.
protocol.registerStreamProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Регистрирует протокол scheme, который отправит поток в качестве ответа.
Использование аналогично registerFileProtocol, за исключением того, что callback должен вызываться либо с объектом ReadableStream, либо с объектом, имеющим свойство data.
Пример:
\nconst { protocol } = require('electron')\nconst { PassThrough } = require('stream')\n\nfunction createStream (text) {\n const rv = new PassThrough() // PassThrough is also a Readable stream\n rv.push(text)\n rv.push(null)\n return rv\n}\n\nprotocol.registerStreamProtocol('atom', (request, callback) => {\n callback({\n statusCode: 200,\n headers: {\n 'content-type': 'text/html'\n },\n data: createStream('<h5>Response</h5>')\n })\n})\nВозможно передать любой объект, реализующий читаемый потоковый API (выдающий data/end/error события). Например, вот как может быть возвращен файл:
protocol.registerStreamProtocol('atom', (request, callback) => {\n callback(fs.createReadStream('index.html'))\n})\nprotocol.unregisterProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unregistered
Отменяет регистрацию пользовательского протокола scheme.
protocol.isProtocolRegistered(scheme)scheme StringВозвращает Boolean - является ли scheme уже зарегистрированной.
protocol.interceptFileProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Перехватывает протокол scheme и использует handler в качестве нового обработчика протокола, который отправляет файл в качестве ответа.
protocol.interceptStringProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Перехватывает протокол scheme и использует handler в качестве нового обработчика протокола, который отправляет String в качестве ответа.
protocol.interceptBufferProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Перехватывает протокол scheme и использует handler в качестве нового обработчика протокола, который отправляет Buffer в качестве ответа.
protocol.interceptHttpProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully intercepted
Перехватывает протокол scheme и использует handler в качестве нового обработчика протокола, который отправляет новый HTTP-запрос в качестве ответа.
protocol.interceptStreamProtocol(scheme, handler)scheme Stringhandler Functionrequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
То же самое, что и protocol.registerStreamProtocol, за исключением того, что он заменяет существующий обработчик протокола.
protocol.uninterceptProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unintercepted
Remove the interceptor installed for scheme and restore its original handler.
protocol.isProtocolIntercepted(scheme)scheme StringВозвращает Boolean - является ли scheme уже перехваченной.
url Stringreferrer Stringmethod StringuploadData UploadData[] (optional)headers Record<String, String>error Integer (optional) - When assigned, the request will fail with the error number . For the available error numbers you can use, please see the net error list.statusCode Number (optional) - The HTTP response code, default is 200.charset String (optional) - The charset of response body, default is \"utf-8\".mimeType String (optional) - The MIME type of response body, default is \"text/html\". Setting mimeType would implicitly set the content-type header in response, but if content-type is already set in headers, the mimeType would be ignored.headers Record<string, string | string[]> (optional) - An object containing the response headers. The keys must be String, and values must be either String or Array of String.data (Buffer | String | ReadableStream) (optional) - The response body. When returning stream as response, this is a Node.js readable stream representing the response body. When returning Buffer as response, this is a Buffer. When returning String as response, this is a String. This is ignored for other types of responses.path String (optional) - Path to the file which would be sent as response body. This is only used for file responses.url String (optional) - Download the url and pipe the result as response body. This is only used for URL responses.referrer String (optional) - The referrer URL. This is only used for file and URL responses.method String (optional) - The HTTP method. This is only used for file and URL responses.session Session (optional) - The session used for requesting URL, by default the HTTP request will reuse the current session. Setting session to null would use a random independent session. This is only used for URL responses.uploadData ProtocolResponseUploadData (optional) - The data used as upload data. This is only used for URL responses when method is \"POST\".contentType String - MIME type of the content.data String | Buffer - Content to be sent.Fork the project on GitHub and clone your fork locally.
\n$ git clone git@github.com:username/electron.git\n$ cd electron\n$ git remote add upstream https://github.com/electron/electron.git\n$ git fetch upstream\nBuild steps and dependencies differ slightly depending on your operating system. See these detailed guides on building Electron locally:
\n\nOnce you've built the project locally, you're ready to start making changes!
\nTo keep your development environment organized, create local branches to hold your work. Они должны быть вынесены непосредственно от ветки main.
$ git checkout -b my-branch -t upstream/main\nMost pull requests opened against the electron/electron repository include changes to either the C/C++ code in the shell/ folder, the JavaScript code in the lib/ folder, the documentation in docs/api/ or tests in the spec/ folder.
Please be sure to run npm run lint from time to time on any code changes to ensure that they follow the project's code style.
See coding style for more information about best practice when modifying code in different parts of the project.
\nIt is recommended to keep your changes grouped logically within individual commits. Many contributors find it easier to review changes that are split across multiple commits. There is no limit to the number of commits in a pull request.
\n$ git add my/changed/files\n$ git commit\nNote that multiple commits often get squashed when they are landed.
\nA good commit message should describe what changed and why. The Electron project uses semantic commit messages to streamline the release process.
\nBefore a pull request can be merged, it must have a pull request title with a semantic prefix.
\nExamples of commit messages with semantic prefixes:
\nfix: don't overwrite prevent_default if default wasn't preventedfeat: add app.isPackaged() methoddocs: app.isDefaultProtocolClient is now available on LinuxCommon prefixes:
\nOther things to keep in mind when writing a commit message:
\nA commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with Major in semantic versioning). A breaking change can be part of commits of any type. e.g., a fix:, feat: & chore: types would all be valid, in addition to any other type.
See conventionalcommits.org for more details.
\nOnce you have committed your changes, it is a good idea to use git rebase (not git merge) to synchronize your work with the main repository.
$ git fetch upstream\n$ git rebase upstream/main\nThis ensures that your working branch has the latest changes from electron/electron main.
Bug fixes and features should always come with tests. A testing guide has been provided to make the process easier. Looking at other tests to see how they should be structured can also help.
\nBefore submitting your changes in a pull request, always run the full test suite. To run the tests:
\n$ npm run test\nMake sure the linter does not report any issues and that all tests pass. Please do not submit patches that fail either check.
\nIf you are updating tests and want to run a single spec to check it:
\n$ npm run test -match=menu\nThe above would only run spec modules matching menu, which is useful for anyone who's working on tests that would otherwise be at the very end of the testing cycle.
Once your commits are ready to go -- with passing tests and linting -- begin the process of opening a pull request by pushing your working branch to your fork on GitHub.
\n$ git push origin my-branch\nFrom within GitHub, opening a new pull request will present you with a template that should be filled out:
\n<!--\nThank you for your pull request. Please provide a description above and review\nthe requirements below.\n\nBug fixes and new features should include tests and possibly benchmarks.\n\nРуководство для разработчиков: https://github.com/electron/electron/blob/main/CONTRIBUTING.md\n-->\nYou will probably get feedback or requests for changes to your pull request. This is a big part of the submission process so don't be discouraged! Some contributors may sign off on the pull request right away. Others may have detailed comments or feedback. This is a necessary part of the process in order to evaluate whether the changes are correct and necessary.
\nTo make changes to an existing pull request, make the changes to your local branch, add a new commit with those changes, and push those to your fork. GitHub will automatically update the pull request.
\n$ git add my/changed/files\n$ git commit\n$ git push origin my-branch\nThere are a number of more advanced mechanisms for managing commits using git rebase that can be used, but are beyond the scope of this guide.
Feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer on something. If you encounter words or acronyms that seem unfamiliar, refer to this glossary.
\nВсе Pull Request'ы требуют одобрения от владельца кода той области, которую вы изменили, для завершения. Whenever a maintainer reviews a pull request they may request changes. These may be small, such as fixing a typo, or may involve substantive changes. Such requests are intended to be helpful, but at times may come across as abrupt or unhelpful, especially if they do not include concrete suggestions on how to change them.
\nTry not to be discouraged. If you feel that a review is unfair, say so or seek the input of another project contributor. Often such comments are the result of a reviewer having taken insufficient time to review and are not ill-intended. Such difficulties can often be resolved with a bit of patience. That said, reviewers should be expected to provide helpful feedback.
\nIn order to land, a pull request needs to be reviewed and approved by at least one Electron Code Owner and pass CI. After that, if there are no objections from other contributors, the pull request can be merged.
\nCongratulations and thanks for your contribution!
\nEvery pull request is tested on the Continuous Integration (CI) system to confirm that it works on Electron's supported platforms.
\nIdeally, the pull request will pass (\"be green\") on all of CI's platforms. This means that all tests pass and there are no linting errors. However, it is not uncommon for the CI infrastructure itself to fail on specific platforms or for so-called \"flaky\" tests to fail (\"be red\"). Each CI failure must be manually inspected to determine the cause.
\nCI starts automatically when you open a pull request, but only core maintainers can restart a CI run. If you believe CI is giving a false negative, ask a maintainer to restart the tests.
", "title": "Запросы на слияние", "description": "" }, "/docs/tutorial/quick-start": { "locale": "ru-RU", "slug": "quick-start", "href": "/docs/tutorial/quick-start", "crowdinFileId": "256237", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/quick-start.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Это руководство проведёт вас через процесс создания простого Hello World приложения в Electron, похожий на electron/electron-quick-start.
К концу этого урока ваше приложение откроет окно браузера, отображая веб-страницу с информацией о том, какие версии Chromium.js Node и Electron работают.
\nЧтобы использовать Electron вы должны установить Node.js. Мы рекомендуем Вам использовать последнюю доступную LTS версию.
\n\nПожалуйста, установите Node.js с помощью предварительно собранных установщиков для вашей платформы. You may encounter incompatibility issues with different development tools otherwise.
\n
Чтобы убедится что Node.js был установлен правильно, напишите следующие команды в терминале:
\nnode -v\nnpm -v\nКоманды должны вывести версии Node.js и npm соответственно.
\nNote:Так как Electron встраивает Node.js в двоичный код, выполняемая версия Node.js может отличатся.
\nПриложения Electron имеют ту же общую структуру, что и другие проекты Node.js. Начните с создания папки и инициализации пакета npm.
\nmkdir my-electron-app && cd my-electron-app\nnpm init\nThe interactive init command will prompt you to set some fields in your config. There are a few rules to follow for the purposes of this tutorial:
entry point should be main.js.author and description can be any value, but are necessary for app packaging.Ваш package.json файл должен выглядеть примерно так:
{\n \"name\": \"my-electron-app\",\n \"version\": \"1.0.0\",\n \"description\": \"Hello World!\",\n \"main\": \"main.js\",\n \"author\": \"Jane Doe\",\n \"license\": \"MIT\"\n}\nThen, install the electron package into your app's devDependencies.
$ npm install --save-dev electron\n\n\nNote: If you're encountering any issues with installing Electron, please refer to the Advanced Installation guide.
\n
Finally, you want to be able to execute Electron. In the scripts field of your package.json config, add a start command like so:
{\n \"scripts\": {\n \"start\": \"electron .\"\n }\n}\nЭта start команда откроет ваше приложение в режиме разработчика.
npm start\n\n\nПримечание: Эта команда запускает приложение из корневой папки. На этом шаге возможна ошибка, которая заключается в том, что не найдено приложение для запуска.
\n
Входной точкой для любого приложения на Electron является скрипт main. Этот скрипт управляет основным процессом, который запускается в полной среде Node.js и отвечает за управление рабочего цикла вашего приложения, отображение основного интерфейса, выполнение привилегированных операций и управление процессом визуализации (подробнее об этом позже).
В процессе выполнения, Electron будет искать этот скрипт в основном поле вашего package.json конфига, который вы сконфигурировали в процессе формирования кода приложения.
Чтобы инициализировать основной скрипт, создайте пустой файл с именем main.js в корневой папке вашего проекта.
\n\nПримечание: Если вы снова запустите скрипт
\nзапускана этот момент, ваше приложение больше не будет выявлять никаких ошибок! Тем не менее, он не будет делать ничего, потому что мы не добавили код вmain.js.
Прежде чем мы сможем создать окно для нашего приложения, нам нужно создать контент, который будет загружен в него. В Electron каждое окно отображает веб-содержимое, которое может быть загружено из локального HTML файла или удаленного URL.
\nВ этом туториале вы будете создавать первое. Создайте index.html файл в корневой папке проекта:
\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n </body>\n</html>\n\n\nЗамечание: Посмотрев на этот HTML-документ, можно заметить, что версии не указаны в блоке body. Мы вручную вставим их позже с помощью JavaScript.
\n
Now that you have a web page, load it into an application window. To do so, you'll need two Electron modules:
\napp module, which controls your application's event lifecycle.BrowserWindow module, which creates and manages application windows.Because the main process runs Node.js, you can import these as CommonJS modules at the top of your file:
\nconst { app, BrowserWindow } = require('electron')\nThen, add a createWindow() function that loads index.html into a new BrowserWindow instance.
function createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\nNext, call this createWindow() function to open your window.
In Electron, browser windows can only be created after the app module's ready event is fired. You can wait for this event by using the app.whenReady() API. Call createWindow() after whenReady() resolves its Promise.
app.whenReady().then(() => {\n createWindow()\n})\n\n\nNote: At this point, your Electron application should successfully open a window that displays your web page!
\n
Although you can now open a browser window, you'll need some additional boilerplate code to make it feel more native to each platform. Application windows behave differently on each OS, and Electron puts the responsibility on developers to implement these conventions in their app.
\nIn general, you can use the process global's platform attribute to run code specifically for certain operating systems.
On Windows and Linux, exiting all windows generally quits an application entirely.
\nTo implement this, listen for the app module's 'window-all-closed' event, and call app.quit() if the user is not on macOS (darwin).
app.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nWhereas Linux and Windows apps quit when they have no windows open, macOS apps generally continue running even without any windows open, and activating the app when no windows are available should open a new one.
\nTo implement this feature, listen for the app module's activate event, and call your existing createWindow() method if no browser windows are open.
Because windows cannot be created before the ready event, you should only listen for activate events after your app is initialized. Do this by attaching your event listener from within your existing whenReady() callback.
app.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n\nNote: At this point, your window controls should be fully functional!
\n
Now, the last thing to do is print out the version numbers for Electron and its dependencies onto your web page.
\nAccessing this information is trivial to do in the main process through Node's global process object. However, you can't just edit the DOM from the main process because it has no access to the renderer's document context. They're in entirely different processes!
\n\nNote: If you need a more in-depth look at Electron processes, see the Process Model document.
\n
This is where attaching a preload script to your renderer comes in handy. A preload script runs before the renderer process is loaded, and has access to both renderer globals (e.g. window and document) and a Node.js environment.
Create a new script named preload.js as such:
window.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\nThe above code accesses the Node.js process.versions object and runs a basic replaceText helper function to insert the version numbers into the HTML document.
To attach this script to your renderer process, pass in the path to your preload script to the webPreferences.preload option in your existing BrowserWindow constructor.
// include the Node.js 'path' module at the top of your file\nconst path = require('path')\n\n// modify your existing createWindow() function\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n}\n// ...\nThere are two Node.js concepts that are used here:
\n__dirname string points to the path of the currently executing script (in this case, your project's root folder).path.join API joins multiple path segments together, creating a combined path string that works across all platforms.We use a path relative to the currently executing JavaScript file so that your relative path will work in both development and packaged mode.
\nAt this point, you might be wondering how to add more functionality to your application.
\nFor any interactions with your web contents, you want to add scripts to your renderer process. Because the renderer runs in a normal web environment, you can add a <script> tag right before your index.html file's closing </body> tag to include any arbitrary scripts you want:
<script src=\"./renderer.js\"></script>\nThe code contained in renderer.js can then use the same JavaScript APIs and tooling you use for typical front-end development, such as using webpack to bundle and minify your code or React to manage your user interfaces.
After following the above steps, you should have a fully functional Electron application that looks like this:
\n
The full code is available below:
\n// main.js\n\n// Modules to control application life and create native browser window\nconst { app, BrowserWindow } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n // Create the browser window.\n const mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n // and load the index.html of the app.\n mainWindow.loadFile('index.html')\n\n // Open the DevTools.\n // mainWindow.webContents.openDevTools()\n}\n\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// Некоторые интерфейсы API могут использоваться только после возникновения этого события.\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n // On macOS it's common to re-create a window in the app when the\n // dock icon is clicked and there are no other windows open.\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\n\n// In this file you can include the rest of your app's specific main process\n// code. Можно также поместить их в отдельные файлы и применить к ним require.\n// preload.js\n\n// All of the Node.js APIs are available in the preload process.\n// It has the same sandbox as a Chrome extension.\nwindow.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\n<!--index.html-->\n\n\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n\n <!-- You can also require other files to run in this process -->\n <script src=\"./renderer.js\"></script>\n </body>\n</html>\nTo summarize all the steps we've done:
\nWe bootstrapped a Node.js application and added Electron as a dependency.
\nWe created a main.js script that runs our main process, which controls our app\nand runs in a Node.js environment. In this script, we used Electron's app and\nBrowserWindow modules to create a browser window that displays web content\nin a separate process (the renderer).
In order to access certain Node.js functionality in the renderer, we attached\na preload script to our BrowserWindow constructor.
The fastest way to distribute your newly created app is using\nElectron Forge.
\nAdd Electron Forge as a development dependency of your app, and use its import command to set up\nForge's scaffolding:
```sh npm2yarn\nnpm install --save-dev @electron-forge/cli\nnpx electron-forge import\n\n✔ Checking your system\n✔ Initializing Git Repository\n✔ Writing modified package.json file\n✔ Installing dependencies\n✔ Writing modified package.json file\n✔ Fixing .gitignore\n\nWe have ATTEMPTED to convert your app to be in a format that electron-forge understands.\n\nСпасибо за использование \"electron-forge\"!!!\n```\nCreate a distributable using Forge's make command:
npm run make\n\n> my-electron-app@1.0.0 make /my-electron-app\n> electron-forge make\n\n✔ Checking your system\n✔ Resolving Forge Config\nWe need to package your application before we can make it\n✔ Preparing to Package Application for arch: x64\n✔ Preparing native dependencies\n✔ Packaging Application\nMaking for the following targets: zip\n✔ Making for target: zip - On platform: darwin - For arch: x64\nElectron Forge creates the out folder where your package will be located:
// Example for macOS\nout/\n├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip\n├── ...\n└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app\nУбедитесь, что Вы используете документацию, соответствующую вашей версии Electron. Версия должна быть частью URL-адреса страницы. If it's not, you are probably using the documentation of a development branch which may contain API changes that are not compatible with your Electron version. Чтобы просмотреть более старые версии документации, Вы можете использовать browse by tag на GitHub, открыв список «Switch branches/tags» и выбрав тег, соответствующий вашей версии.
\nЕсть вопросы, которые довольно часто задаваются. Проверьте это перед созданием проблемы:
\nЭти индивидуальные руководства расширят темы, обсуждаемые выше.
\nЭти руководства предназначены для людей, которые работают над Electron самостоятельно. Для руководств по разработке приложения Electron, посетите /docs/README.md.
\nWindows и macOS предоставляют легкий доступ к списку последних документов открытых приложением через JumpList или dock меню, соответственно.
\nJumpList:
\n
Dock меню приложения:
\n
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\n\nconst fileName = 'recently-used.md'\nfs.writeFile(fileName, 'Lorem Ipsum', () => {\n app.addRecentDocument(path.join(__dirname, fileName))\n})\n\napp.whenReady().then(createWindow)\n\napp.on('window-all-closed', () => {\n app.clearRecentDocuments()\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nTo add a file to recent documents, use the app.addRecentDocument API.
\nAfter launching the Electron application, right click the application icon. In this guide, the item is a Markdown file located in the root of the project. You should see recently-used.md added to the list of recent files:
To clear the list of recent documents, use the app.clearRecentDocuments API. In this guide, the list of documents is cleared once all windows have been closed.
\nTo use this feature on Windows, your application has to be registered as a handler of the file type of the document, otherwise the file won't appear in JumpList even after you have added it. You can find everything on registering your application in Application Registration.
\nКогда пользователь щелкает файл из JumpList, новый экземпляр приложения будет запущен с добавленного пути файла, как аргумент командной строки.
\nYou can add menu items to access and clear recent documents by adding the following code snippet to your menu template:
\n{\n \"submenu\":[\n {\n \"label\":\"Open Recent\",\n \"role\":\"recentdocuments\",\n \"submenu\":[\n {\n \"label\":\"Clear Recent\",\n \"role\":\"clearrecentdocuments\"\n }\n ]\n }\n ]\n}\nMake sure the application menu is added after the 'ready' event and not before, or the menu item will be disabled:
const { app, Menu } = require('electron')\n\nconst template = [\n // Menu template here\n]\nconst menu = Menu.buildFromTemplate(template)\n\napp.whenReady().then(() => {\n Menu.setApplicationMenu(menu)\n})\n
When a file is requested from the recent documents menu, the open-file event of app module will be emitted for it.
x Number - The x coordinate of the origin of the rectangle (must be an integer).y Number - The y coordinate of the origin of the rectangle (must be an integer).width Number - The width of the rectangle (must be an integer).height Number - The height of the rectangle (must be an integer).url String - HTTP Referrer URL.policy String - Can be default, unsafe-url, no-referrer-when-downgrade, no-referrer, origin, strict-origin-when-cross-origin, same-origin or strict-origin. See the Referrer-Policy spec for more details on the meaning of these values.Read-Eval-Print-Loop (REPL) is a simple, interactive computer programming environment that takes single user inputs (i.e. single expressions), evaluates them, and returns the result to the user.
\nElectron exposes the Node.js repl module through the --interactive CLI flag. Assuming you have electron installed as a local project dependency, you should be able to access the REPL with the following command:
./node_modules/.bin/electron --interactive\nNote: electron --interactive is not available on Windows (see electron/electron#5776 for more details).
You can use the DevTools Console tab to get a REPL for any renderer process. To learn more, read the Chrome documentation.
", "title": "REPL", "description": "" }, "/docs/tutorial/represented-file": { "locale": "ru-RU", "slug": "represented-file", "href": "/docs/tutorial/represented-file", "crowdinFileId": "256243", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/represented-file.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "On macOS, you can set a represented file for any window in your application. The represented file's icon will be shown in the title bar, and when users Command-Click or Control-Click, a popup with a path to the file will be shown.
\n\nNOTE: The screenshot above is an example where this feature is used to indicate the currently opened file in the Atom text editor.
\n
You can also set the edited state for a window so that the file icon can indicate whether the document in this window has been modified.
\nДля установления представленного файла можно использовать BrowserWindow.setRepresentedFilename и BrowserWindow.setDocumentEdited APIs.
\nconst { app, BrowserWindow } = require('electron')\nconst os = require('os');\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n}\n\napp.whenReady().then(() => {\n const win = new BrowserWindow()\n\n win.setRepresentedFilename(os.homedir())\n win.setDocumentEdited(true)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nAfter launching the Electron application, click on the title with Command or Control key pressed. You should see a popup with the represented file at the top. In this guide, this is the current user's home directory:
\n\nAllows access to simple encryption and decryption of strings for storage on the local machine.
\n
Процесс: Основной
\nThis module protects data stored on disk from being accessed by other applications or users with full disk access.
\nNote that on Mac, access to the system Keychain is required and these calls can block the current thread to collect user input. The same is true for Linux, if a password management tool is available.
\nМодуль safeStorage имеет следующие методы:
safeStorage.isEncryptionAvailable()Returns Boolean - Whether encryption is available.
On Linux, returns true if the secret key is available. On MacOS, returns true if Keychain is available. On Windows, returns true with no other preconditions.
\nsafeStorage.encryptString(plainText)plainTextReturns Buffer - An array of bytes representing the encrypted string.
This function will throw an error if encryption fails.
\nsafeStorage.decryptString(encrypted)encrypted BufferReturns String - the decrypted string. Decrypts the encrypted buffer obtained with safeStorage.encryptString back into a string.
This function will throw an error if decryption fails.
", "title": "safeStorage", "description": "Allows access to simple encryption and decryption of strings for storage on the local machine." }, "/docs/tutorial/sandbox": { "locale": "ru-RU", "slug": "sandbox", "href": "/docs/tutorial/sandbox", "crowdinFileId": "256245", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/sandbox.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Одна из ключевых функций безопасности в Chromium заключается в том, что процессы могут быть выполнены в песочнице. Песочница ограничивает вред, который может нанести вредоносный код, ограничивая доступ к большинству системных ресурсов — изолированные процессы могут свободно использовать только циклы ЦП и память. Для выполнения операций, требующих дополнительных привилегий, изолированные процессы используют выделенные каналы связи для делегирования задач более привилегированным процессам.
\nВ Chromium песочница применяется к большинству процессов, отличных от основного процесса. Сюда входят процессы визуализации, а также вспомогательные процессы, такие как службы аудио, служба GPU и сетевая служба.
\nСмотрите дизайн приложения Chromium для более подробной информации.
\nElectron поставляется со смешанной средой песочницы, что означает, что изолированные процессы могут выполняться наряду с привилегированными. По умолчанию, процессы рендеринга не выполняются в \"песочнице\", но служебные процессы - да. Обратите внимание, что, как и в Chromium, основной процесс (браузер) является привилегированным и не может быть изолирован.
\nИсторически сложилось так, что этот смешанный подход к песочнице был создан потому, что наличие Node.js доступной в рендерере, является чрезвычайно мощным инструментом для разработчиков приложений. К сожалению, эта функция также является столь же мощной уязвимостью в безопасности.
\nТеоретически, рендереры вне песочниц не являются проблемой для настольных приложений, которые отображают только доверенный код, но они делают Electron менее безопасным, чем Chromium для отображения ненадежного веб-контента. Тем не менее, даже якобы доверенный код может быть опасным — существует бесчисленное множество векторов атак, которые могут использовать злоумышленники, от межсайтовых сценариев до внедрения контента и атак «человек посередине» на удаленно загруженные веб-сайты, и это лишь некоторые из них. По этой причине мы рекомендуем включить песочницу рендереров для подавляющего большинства случаев с осторожностью.
\n\nОбратите внимание, что в трекере задач активно обсуждается включение песочницы рендерера по умолчанию. Подробности см. в #28466).
\nSandboxed processes in Electron behave mostly in the same way as Chromium's do, but Electron has a few additional concepts to consider because it interfaces with Node.js.
\nWhen renderer processes in Electron are sandboxed, they behave in the same way as a regular Chrome renderer would. A sandboxed renderer won't have a Node.js environment initialized.
\n\nTherefore, when the sandbox is enabled, renderer processes can only perform privileged tasks (such as interacting with the filesystem, making changes to the system, or spawning subprocesses) by delegating these tasks to the main process via inter-process communication (IPC).
\nIn order to allow renderer processes to communicate with the main process, preload scripts attached to sandboxed renderers will still have a polyfilled subset of Node.js APIs available. A require function similar to Node's require module is exposed, but can only import a subset of Electron and Node's built-in modules:
In addition, the preload script also polyfills certain Node.js primitives as globals:
\nBufferprocessclearImmediatesetImmediateBecause the require function is a polyfill with limited functionality, you will not be able to use CommonJS modules to separate your preload script into multiple files. If you need to split your preload code, use a bundler such as webpack or Parcel.
Note that because the environment presented to the preload script is substantially more privileged than that of a sandboxed renderer, it is still possible to leak privileged APIs to untrusted code running in the renderer process unless contextIsolation is enabled.
In Electron, renderer sandboxing can be enabled on a per-process basis with the sandbox: true preference in the BrowserWindow constructor.
// main.js\napp.whenReady().then(() => {\n const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n })\n win.loadURL('https://google.com')\n})\nIf you want to force sandboxing for all renderers, you can also use the app.enableSandbox API. Note that this API has to be called before the app's ready event.
// main.js\napp.enableSandbox()\napp.whenReady().then(() => {\n // no need to pass `sandbox: true` since `app.enableSandbox()` was called.\n const win = new BrowserWindow()\n win.loadURL('https://google.com')\n})\nYou can also disable Chromium's sandbox entirely with the --no-sandbox CLI flag, which will disable the sandbox for all processes (including utility processes). We highly recommend that you only use this flag for testing purposes, and never in production.
Note that the sandbox: true option will still disable the renderer's Node.js environment.
Rendering untrusted content in Electron is still somewhat uncharted territory, though some apps are finding success (e.g. Beaker Browser). Our goal is to get as close to Chrome as we can in terms of the security of sandboxed content, but ultimately we will always be behind due to a few fundamental issues:
\nWhile we make our best effort to backport Chromium security fixes to older versions of Electron, we do not make a guarantee that every fix will be backported. Your best chance at staying secure is to be on the latest stable version of Electron.
", "title": "Dima@mail.ru", "description": "" }, "/docs/api/screen": { "locale": "ru-RU", "slug": "screen", "href": "/docs/api/screen", "crowdinFileId": "256361", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/screen.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nПредоставляет информацию о размере экрана, дисплеях, позиции курсора.
\n
Процесс: Основной
\nЭтот модуль нельзя использовать до тех пор, пока событие ready в app не будет готово к использованию.
screen is an EventEmitter.
Note: In the renderer / DevTools, window.screen is a reserved DOM property, so writing let { screen } = require('electron') will not work.
An example of creating a window that fills the whole screen:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\napp.whenReady().then(() => {\n const { width, height } = screen.getPrimaryDisplay().workAreaSize\n win = new BrowserWindow({ width, height })\n win.loadURL('https://github.com')\n})\nДругой пример создания окна на внешнем дисплее:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n const displays = screen.getAllDisplays()\n const externalDisplay = displays.find((display) => {\n return display.bounds.x !== 0 || display.bounds.y !== 0\n })\n\n if (externalDisplay) {\n win = new BrowserWindow({\n x: externalDisplay.bounds.x + 50,\n y: externalDisplay.bounds.y + 50\n })\n win.loadURL('https://github.com')\n }\n})\nОбъект screen имеет следующие события:
Возвращает:
\neventnewDisplay DisplayВозникает при добавлении newDisplay.
Возвращает:
\neventoldDisplay DisplayВозникает при удалении oldDisplay.
Возвращает:
\neventdisplay DisplaychangedMetrics String[]Возникает при изменении одной или нескольких метрик в display. changedMetrics является массивом строк, описывающих изменения. Возможные изменения bounds, workArea, scaleFactor и rotation.
Модуль screen имеет следующие методы:
screen.getCursorScreenPoint()Возвращает Point
Текущее абсолютное положение указателя мыши.
\nNote: The return value is a DIP point, not a screen physical point.
\nscreen.getPrimaryDisplay()Возвращает Display - Основной дисплей.
screen.getAllDisplays()Возвращает Display[] - Массив доступных в настоящее время дисплеев.
screen.getDisplayNearestPoint(point)point PointВозвращает Display - Дисплей, ближайший к указанной точке.
screen.getDisplayMatching(rect)rect RectangleВозвращает Display - Дисплей, который наиболее близко пересекает заданные границы.
screen.screenToDipPoint(point) Windowspoint PointВозвращает Point
Преобразует физическую точку экрана в точку DIP экрана. Масштаб DPI выполняется относительно отображения, содержащего физическую точку.
\nscreen.dipToScreenPoint(point) Windowspoint PointВозвращает Point
Преобразует точку DIP экрана в физическую точку экрана. Масштаб DPI выполняется относительно отображения, содержащего точку DIP.
\nscreen.screenToDipRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleВозвращает Rectangle
Преобразует физический прямоугольник экрана в DIP-прямоугольник экрана. Шкала DPI выполняется относительно дисплея, ближайшего к window. Если window равен нулю, то масштабирование будет производиться до ближайшего к rect.
screen.dipToScreenRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleВозвращает Rectangle
Преобразовывает DIP-прямоуголник экрана в физический прямоугольник экрана. Шкала DPI выполняется относительно дисплея, ближайшего к window. Если window равен нулю, то масштабирование будет производиться до ближайшего к rect.
label String (optional) - The text to appear in this item.icon NativeImage (optional) - The image to appear in this item.Как веб-разработчики, мы заботимся о безопасности браузера и риски, связанные с кодом, который мы пишем, достаточно небольшие. Наши веб-сайты имеют ограниченные полномочия в песочнице, и мы верим, что пользователи довольны браузером, созданным большой командой инженеров, которая может быстро реагировать на последние обнаруженные угрозы безопасности.
\nКогда вы работаете в среде Электрон, важно понимать, что это не веб браузер. Электрон позволяет создавать функционально развитые приложения для настольных компьютеров с помощью веб технологий, но ваш код обладает большими возможностями. JavaScript имеет доступ к файловой системе, пользовательским скриптам и т. д. Благодаря этим возможностям вы можете создавать высококачественные нативные приложения, но это так же множит риски увеличивающиеся с дополнительными полномочиями вашего кода.
\nУчтите что показ произвольного содержимого от недоверенных источников влечет за собой риски безопасности, которые Электрон не предназначен купировать. К сведению, наиболее популярные приложения Электрон (Atom, Slack, Visual Studio Code, etc) предназначены для локальной работы (или с доверенными удаленными узлами, без Node интеграции). Если ваше приложение выполняет код из онлайн источника, вы обязаны обеспечить безопасность кода.
\nДля получения информации о том, как правильно устранять уязвимости Electron, загляни в SECURITY.md
\nElectron keeps up to date with alternating Chromium releases. For more information, see the Electron Release Cadence blog post.
\nВажно помнить, что безопасность вашего Electron приложения является результатом общей безопасности основы платформы (Chromium, Node.js), самого Electron, всех NPM-зависимостей и вашего кода. Поэтому вы обязаны следовать нескольким важным рекомендациям:
\nKeep your application up-to-date with the latest Electron framework release. When releasing your product, you’re also shipping a bundle composed of Electron, Chromium shared library and Node.js. Vulnerabilities affecting these components may impact the security of your application. By updating Electron to the latest version, you ensure that critical vulnerabilities (such as nodeIntegration bypasses) are already patched and cannot be exploited in your application. For more information, see \"Use a current version of Electron\".
\nОцените свои зависимости. В то время как NPM предоставляет полмиллиона многоразовых пакетов, вы несете ответственность за выбор надежных библиотек третьей стороны. If you use outdated libraries affected by known vulnerabilities or rely on poorly maintained code, your application security could be in jeopardy.
\nИспользуйте безопасные методы программирования Первая линия защиты вашей заявки — ваш собственный код. Common web vulnerabilities, such as Cross-Site Scripting (XSS), have a higher security impact on Electron applications hence it is highly recommended to adopt secure software development best practices and perform security testing.
\nПроблемы безопасности возникают всякий раз, когда вы получаете код из ненадежного источника (напр., удаленный сервер) и выполняете его локально. As an example, consider a remote website being displayed inside a default BrowserWindow. If an attacker somehow manages to change said content (either by attacking the source directly, or by sitting between your app and the actual destination), they will be able to execute native code on the user's machine.
\n\n⚠️ ни при каких обстоятельствах не следует загружать и выполнять удаленный код с Node.js integration enabled. Вместо этого используйте только локальные файлы (упакованные вместе с вашим приложением), для выполнения Node.js кода. To display remote content, use the
\n<webview>tag orBrowserView, make sure to disable thenodeIntegrationand enablecontextIsolation.
Электрон 2.0 показывает разработчикам предупреждения и рекомендации в консоли. Они показываются только тогда, когда имя исполняемого файла - Electron.
\nВы можете принудительно включить или выключить эти предупреждения в настройках ELECTRON_ENABLE_SECURITY_WARNINGS или ELECTRON_DISABLE_SECURITY_WARNINGS на любом process.env или объекте window.
You should at least follow these steps to improve the security of your application:
\nses.setPermissionRequestHandler() в сессиях с загрузкой удаленного контентаwebSecurityContent-Security-Policy и используйте ограничительные правила (i.e. script-src 'self')allowRunningInsecureContent в trueenableBlinkFeatures<webview>: Do not use allowpopups<webview>: Verify options and paramsopenExternal with untrusted contentTo automate the detection of misconfigurations and insecure patterns, it is possible to use electronegativity. For additional details on potential weaknesses and implementation bugs when developing applications using Electron, please refer to this guide for developers and auditors
\nВсе ресурсы не включенные в ваше приложение должны быть загружены с использованием безопасного протокола HTTPS. Откажитесь от не безопасных протоколов, таких как HTTP. Так же мы рекомендуем WSS over WS, FTPS over FTP, и т. п.
HTTPS имеет 3 главных преимущества:
1) It authenticates the remote server, ensuring your app connects to the correct host instead of an impersonator. 2) It ensures data integrity, asserting that the data was not modified while in transit between your application and the host. 3) Он шифрует трафик между вашим пользователем и хостом назначения, что усложняет перехват информации, отправленную между вашим приложением и хостом.
\n// Плохо\nbrowserWindow.loadURL('http://example.com') \n\n// Хорошо\nbrowserWindow.loadURL('https://example.com')\n<!-- Плохо -->\n<script crossorigin src=\"http://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"http://example.com/style.css\">\n\n<!-- Хорошо -->\n<script crossorigin src=\"https://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"https://example.com/style.css\">\nThis recommendation is the default behavior in Electron since 5.0.0.
\nIt is paramount that you do not enable Node.js integration in any renderer (BrowserWindow, BrowserView, or <webview>) that loads remote content. The goal is to limit the powers you grant to remote content, thus making it dramatically more difficult for an attacker to harm your users should they gain the ability to execute JavaScript on your website.
After this, you can grant additional permissions for specific hosts. For example, if you are opening a BrowserWindow pointed at https://example.com/, you can give that website exactly the abilities it needs, but no more.
A cross-site-scripting (XSS) attack is more dangerous if an attacker can jump out of the renderer process and execute code on the user's computer. Cross-site-scripting attacks are fairly common - and while an issue, their power is usually limited to messing with the website that they are executed on. Disabling Node.js integration helps prevent an XSS from being escalated into a so-called \"Remote Code Execution\" (RCE) attack.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n nodeIntegration: true,\n nodeIntegrationInWorker: true\n }\n})\n\nmainWindow.loadURL('https://example.com')\n// Good\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n preload: path.join(app.getAppPath(), 'preload.js')\n }\n})\n\nmainWindow.loadURL('https://example.com')\n<!-- Bad -->\n<webview nodeIntegration src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nПри отключении интеграции с Node.js, можно по-прежнему использовать API на вашем сайте, которые используют модули или функции Node.js. Preload scripts continue to have access to require and other Node.js features, allowing developers to expose a custom API to remotely loaded content.
In the following example preload script, the later loaded website will have access to a window.readConfig() method, but no Node.js features.
const { readFileSync } = require('fs')\n\nwindow.readConfig = function () {\n const data = readFileSync('./config.json')\n return data\n}\nContext isolation is an Electron feature that allows developers to run code in preload scripts and in Electron APIs in a dedicated JavaScript context. In practice, that means that global objects like Array.prototype.push or JSON.parse cannot be modified by scripts running in the renderer process.
Electron uses the same technology as Chromium's Content Scripts to enable this behavior.
\nEven when nodeIntegration: false is used, to truly enforce strong isolation and prevent the use of Node primitives contextIsolation must also be used.
For more information on what contextIsolation is and how to enable it please see our dedicated Context Isolation document.
Sandboxing is a Chromium feature that uses the operating system to significantly limit what renderer processes have access to. You should enable the sandbox in all renderers. Loading, reading or processing any untrusted content in an unsandboxed process, including the main process, is not advised.
\nWhen creating a window, pass the sandbox: true option in webPreferences:
const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n})\nYou may have seen permission requests while using Chrome: They pop up whenever the website attempts to use a feature that the user has to manually approve ( like notifications).
\nThe API is based on the Chromium permissions API and implements the same types of permissions.
\nBy default, Electron will automatically approve all permission requests unless the developer has manually configured a custom handler. While a solid default, security-conscious developers might want to assume the very opposite.
\nconst { session } = require('electron')\n\nsession\n .fromPartition('some-partition')\n .setPermissionRequestHandler((webContents, permission, callback) => {\n const url = webContents.getURL()\n\n if (permission === 'notifications') {\n // Approves the permissions request\n callback(true)\n }\n\n // Verify URL\n if (!url.startsWith('https://example.com/')) {\n // Denies the permissions request\n return callback(false)\n }\n })\nRecommendation is Electron's default
\nYou may have already guessed that disabling the webSecurity property on a renderer process (BrowserWindow, BrowserView, or <webview>) disables crucial security features.
Do not disable webSecurity in production applications.
Disabling webSecurity will disable the same-origin policy and set allowRunningInsecureContent property to true. In other words, it allows the execution of insecure code from different domains.
// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n webSecurity: false\n }\n})\n// Good\nconst mainWindow = new BrowserWindow()\n<!-- Bad -->\n<webview disablewebsecurity src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nA Content Security Policy (CSP) is an additional layer of protection against cross-site-scripting attacks and data injection attacks. We recommend that they be enabled by any website you load inside Electron.
\nCSP allows the server serving content to restrict and control the resources Electron can load for that given web page. https://example.com should be allowed to load scripts from the origins you defined while scripts from https://evil.attacker.com should not be allowed to run. Defining a CSP is an easy way to improve your application's security.
The following CSP will allow Electron to execute scripts from the current website and from apis.example.com.
// Bad\nContent-Security-Policy: '*'\n\n// Good\nContent-Security-Policy: script-src 'self' https://apis.example.com\nElectron respects the Content-Security-Policy HTTP header which can be set using Electron's webRequest.onHeadersReceived handler:
const { session } = require('electron')\n\nsession.defaultSession.webRequest.onHeadersReceived((details, callback) => {\n callback({\n responseHeaders: {\n ...details.responseHeaders,\n 'Content-Security-Policy': ['default-src \\'none\\'']\n }\n })\n})\nCSP's preferred delivery mechanism is an HTTP header, however it is not possible to use this method when loading a resource using the file:// protocol. It can be useful in some cases, such as using the file:// protocol, to set a policy on a page directly in the markup using a <meta> tag:
<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'\">\nallowRunningInsecureContent to trueRecommendation is Electron's default
\nBy default, Electron will not allow websites loaded over HTTPS to load and execute scripts, CSS, or plugins from insecure sources (HTTP). Setting the property allowRunningInsecureContent to true disables that protection.
Loading the initial HTML of a website over HTTPS and attempting to load subsequent resources via HTTP is also known as \"mixed content\".
Loading content over HTTPS assures the authenticity and integrity of the loaded resources while encrypting the traffic itself. See the section on only displaying secure content for more details.
// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n allowRunningInsecureContent: true\n }\n})\n// Good\nconst mainWindow = new BrowserWindow({})\nRecommendation is Electron's default
\nAdvanced users of Electron can enable experimental Chromium features using the experimentalFeatures property.
Experimental features are, as the name suggests, experimental and have not been enabled for all Chromium users. Furthermore, their impact on Electron as a whole has likely not been tested.
\nLegitimate use cases exist, but unless you know what you are doing, you should not enable this property.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n experimentalFeatures: true\n }\n})\n// Good\nconst mainWindow = new BrowserWindow({})\nenableBlinkFeaturesRecommendation is Electron's default
\nBlink is the name of the rendering engine behind Chromium. As with experimentalFeatures, the enableBlinkFeatures property allows developers to enable features that have been disabled by default.
Generally speaking, there are likely good reasons if a feature was not enabled by default. Legitimate use cases for enabling specific features exist. As a developer, you should know exactly why you need to enable a feature, what the ramifications are, and how it impacts the security of your application. Under no circumstances should you enable features speculatively.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n enableBlinkFeatures: 'ExecCommandInJavaScript'\n }\n})\n// Good\nconst mainWindow = new BrowserWindow()\nallowpopupsRecommendation is Electron's default
\nIf you are using <webview>, you might need the pages and scripts loaded in your <webview> tag to open new windows. The allowpopups attribute enables them to create new BrowserWindows using the window.open() method. <webview> tags are otherwise not allowed to create new windows.
If you do not need popups, you are better off not allowing the creation of new BrowserWindows by default. This follows the principle of minimally required access: Don't let a website create new popups unless you know it needs that feature.
<!-- Bad -->\n<webview allowpopups src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nA WebView created in a renderer process that does not have Node.js integration enabled will not be able to enable integration itself. However, a WebView will always create an independent renderer process with its own webPreferences.
It is a good idea to control the creation of new <webview> tags from the main process and to verify that their webPreferences do not disable security features.
Since <webview> live in the DOM, they can be created by a script running on your website even if Node.js integration is otherwise disabled.
Electron enables developers to disable various security features that control a renderer process. In most cases, developers do not need to disable any of those features - and you should therefore not allow different configurations for newly created <webview> tags.
Before a <webview> tag is attached, Electron will fire the will-attach-webview event on the hosting webContents. Use the event to prevent the creation of webViews with possibly insecure options.
app.on('web-contents-created', (event, contents) => {\n contents.on('will-attach-webview', (event, webPreferences, params) => {\n // Strip away preload scripts if unused or verify their location is legitimate\n delete webPreferences.preload\n delete webPreferences.preloadURL\n\n // Disable Node.js integration\n webPreferences.nodeIntegration = false\n\n // Verify URL being loaded\n if (!params.src.startsWith('https://example.com/')) {\n event.preventDefault()\n }\n })\n})\nAgain, this list merely minimizes the risk, it does not remove it. If your goal is to display a website, a browser will be a more secure option.
\nIf your app has no need to navigate or only needs to navigate to known pages, it is a good idea to limit navigation outright to that known scope, disallowing any other kinds of navigation.
\nNavigation is a common attack vector. If an attacker can convince your app to navigate away from its current page, they can possibly force your app to open web sites on the Internet. Even if your webContents are configured to be more secure (like having nodeIntegration disabled or contextIsolation enabled), getting your app to open a random web site will make the work of exploiting your app a lot easier.
A common attack pattern is that the attacker convinces your app's users to interact with the app in such a way that it navigates to one of the attacker's pages. This is usually done via links, plugins, or other user-generated content.
\nIf your app has no need for navigation, you can call event.preventDefault() in a will-navigate handler. If you know which pages your app might navigate to, check the URL in the event handler and only let navigation occur if it matches the URLs you're expecting.
We recommend that you use Node's parser for URLs. Simple string comparisons can sometimes be fooled - a startsWith('https://example.com') test would let https://example.com.attacker.com through.
const URL = require('url').URL\n\napp.on('web-contents-created', (event, contents) => {\n contents.on('will-navigate', (event, navigationUrl) => {\n const parsedUrl = new URL(navigationUrl)\n\n if (parsedUrl.origin !== 'https://example.com') {\n event.preventDefault()\n }\n })\n})\nIf you have a known set of windows, it's a good idea to limit the creation of additional windows in your app.
\nMuch like navigation, the creation of new webContents is a common attack vector. Attackers attempt to convince your app to create new windows, frames, or other renderer processes with more privileges than they had before; or with pages opened that they couldn't open before.
If you have no need to create windows in addition to the ones you know you'll need to create, disabling the creation buys you a little bit of extra security at no cost. This is commonly the case for apps that open one BrowserWindow and do not need to open an arbitrary number of additional windows at runtime.
webContents will delegate to its window open handler before creating new windows. The handler will receive, amongst other parameters, the url the window was requested to open and the options used to create it. We recommend that you register a handler to monitor the creation of windows, and deny any unexpected window creation.
const { shell } = require('electron')\n\napp.on('web-contents-created', (event, contents) => {\n contents.setWindowOpenHandler(({ url }) => {\n // In this example, we'll ask the operating system\n // to open this event's url in the default browser.\n //\n // See the following item for considerations regarding what\n // URLs should be allowed through to shell.openExternal.\n if (isSafeForExternalOpen(url)) {\n setImmediate(() => {\n shell.openExternal(url)\n })\n }\n\n return { action: 'deny' }\n })\n})\nopenExternal with untrusted contentShell's openExternal allows opening a given protocol URI with the desktop's native utilities. On macOS, for instance, this function is similar to the open terminal command utility and will open the specific application based on the URI and filetype association.
Improper use of openExternal can be leveraged to compromise the user's host. When openExternal is used with untrusted content, it can be leveraged to execute arbitrary commands.
// Bad\nconst { shell } = require('electron')\nshell.openExternal(USER_CONTROLLED_DATA_HERE)\n// Good\nconst { shell } = require('electron')\nshell.openExternal('https://example.com/index.html')\nYou should strive for always using the latest available version of Electron. Whenever a new major version is released, you should attempt to update your app as quickly as possible.
\nAn application built with an older version of Electron, Chromium, and Node.js is an easier target than an application that is using more recent versions of those components. Generally speaking, security issues and exploits for older versions of Chromium and Node.js are more widely available.
\nBoth Chromium and Node.js are impressive feats of engineering built by thousands of talented developers. Given their popularity, their security is carefully tested and analyzed by equally skilled security researchers. Many of those researchers disclose vulnerabilities responsibly, which generally means that researchers will give Chromium and Node.js some time to fix issues before publishing them. Your application will be more secure if it is running a recent version of Electron (and thus, Chromium and Node.js) for which potential security issues are not as widely known.
", "title": "Безопасность, нативные возможности и ваша ответственность", "description": "⚠️ ни при каких обстоятельствах не следует загружать и выполнять удаленный код с Node.js integration enabled. Вместо этого используйте только локальные файлы (упакованные вместе с вашим приложением), для выполнения Node.js кода. To display remote content, use thelabel String (optional) - The text to appear in this segment.icon NativeImage (optional) - The image to appear in this segment.enabled Boolean (optional) - Whether this segment is selectable. Default: true.portId String - Unique identifier for the port.portName String - Name of the port.displayName String - A string suitable for display to the user for describing this device.vendorId String - Optional USB vendor ID.productId String - Optional USB product ID.serialNumber String - The USB device serial number.usbDriverName String (optional) - Represents a single serial port on macOS can be enumerated by multiple drivers.deviceInstanceId String (optional) - A stable identifier on Windows that can be used for device permissions.scriptUrl String - The full URL to the script that this service worker runsscope String - The base URL that this service worker is active for.renderProcessId Number - The virtual ID of the process that this service worker is running in. This is not an OS level PID. This aligns with the ID set used for webContents.getProcessId().\n\nQuery and receive events from a sessions active service workers.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Экземпляры класса ServiceWorkers доступны через свойство serviceWorkers объекта Session.
Например:
\nconst { session } = require('electron')\n\n// Get all service workers.\nconsole.log(session.defaultSession.serviceWorkers.getAllRunning())\n\n// Handle logs and get service worker info\nsession.defaultSession.serviceWorkers.on('console-message', (event, messageDetails) => {\n console.log(\n 'Got service worker message',\n messageDetails,\n 'from',\n session.defaultSession.serviceWorkers.getFromVersionID(messageDetails.versionId)\n )\n})\nДля экземпляров ServiceWorkers доступны следующие события:
Возвращает:
\neventmessageDetails Object - Information about the console messagemessage String - The actual console messageversionId Number - The version ID of the service worker that sent the log messagesource String - The type of source for this message. Can be javascript, xml, network, console-api, storage, app-cache, rendering, security, deprecation, worker, violation, intervention, recommendation or other.level Number - The log level, from 0 to 3. In order it matches verbose, info, warning and error.sourceUrl String - The URL the message came fromlineNumber Number - The line number of the source that triggered this console messageEmitted when a service worker logs something to the console.
\nВозвращает:
\neventdetails Object - Information about the registered service workerscope String - The base URL that a service worker is registered forEmitted when a service worker has been registered. Can occur after a call to navigator.serviceWorker.register('/sw.js') successfully resolves or when a Chrome extension is loaded.
В экземпляре ServiceWorkers доступны следующие методы:
serviceWorkers.getAllRunning()Returns Record<Number, ServiceWorkerInfo> - A ServiceWorkerInfo object where the keys are the service worker version ID and the values are the information about that service worker.
serviceWorkers.getFromVersionID(versionId)versionId NumberReturns ServiceWorkerInfo - Information about this service worker
If the service worker does not exist or is not running this method will throw an exception.
", "title": "ServiceWorkers", "description": "Query and receive events from a sessions active service workers." }, "/docs/api/session": { "locale": "ru-RU", "slug": "session", "href": "/docs/api/session", "crowdinFileId": "256365", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/session.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nSession Управление сеансами браузера, куками, кешем, настройками прокси и т. д.
\n
Процесс: Основной
\nМодуль session может быть использован для создания новых объектов Session.
Вы также можете получить доступ к session существующих страниц, используя свойство session в WebContents, или из модуля session.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nconst ses = win.webContents.session\nconsole.log(ses.getUserAgent())\nМодуль session имеет следующие методы:
session.fromPartition(partition[, options])partition Stringoptions Object (опционально)cache Boolean - Включен ли кэш.Возвращает Session - Экземпляр сеанса из строки partition. При наличии Session с таким же partition, он будет возвращен; иначе новый экземпляр Session будет создан с options.
Если partition начинается с persist:, страница будет использовать постоянный сеанс, который доступен всем страницам в приложении с тем же partition. если нет префикса persist:, страница будет использовать сеанс в памяти. Если partition пуст, то будет возвращен сеанс приложения по умолчанию.
Чтобы создать Session с options, вы должны убедиться, что Session с partition раньше никогда не использовался. Невозможно изменить options из существующего Session объекта.
Модуль session имеет следующие свойства:
session.defaultSessionОбъект Session, объект сеанса по умолчанию для приложения.
\n\nПолучает и устанавливает свойства сеанса.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Вы можете создать объект Session в модуле session:
const { session } = require('electron')\nconst ses = session.fromPartition('persist:name')\nconsole.log(ses.getUserAgent())\nДля экземпляров Session доступны следующие события:
Возвращает:
\neventitem DownloadItemwebContents WebContentsВозникает, когда Electron собирается загрузить item в webContents.
Вызов event.preventDefault() отменит загрузку, и item не будет доступен со следующего тика процесса.
const { session } = require('electron')\nsession.defaultSession.on('will-download', (event, item, webContents) => {\n event.preventDefault()\n require('got')(item.getURL()).then((response) => {\n require('fs').writeFileSync('/somewhere', response.body)\n })\n})\nВозвращает:
\neventextension ExtensionEmitted after an extension is loaded. This occurs whenever an extension is added to the \"enabled\" set of extensions. This includes:
\nSession.loadExtension.chrome.runtime.reload()).Возвращает:
\neventextension ExtensionEmitted after an extension is unloaded. This occurs when Session.removeExtension is called.
Возвращает:
\neventextension ExtensionEmitted after an extension is loaded and all necessary browser state is initialized to support the start of the extension's background page.
\nВозвращает:
\neventpreconnectUrl String - URL-адрес, запрашиваемый рендерером для предварительного подключения.allowCredentials Boolean - True если рендерер запрашивает, чтобы соединение включало учетные данные (см. spec для получения более подробной информации.)Возникает, когда в процессе рендеринга запрашивается предварительное подключение к URL, как правило, из-за подсказки ресурса.
\nВозвращает:
\neventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file has been successfully initialized. This occurs after the file has been downloaded.
\nВозвращает:
\neventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file starts downloading
\nВозвращает:
\neventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file has been successfully downloaded
\nВозвращает:
\neventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file download fails. For details on the failure you should collect a netlog and inspect the download request.
\nВозвращает:
\neventdetailsdeviceList HIDDevice[]frame WebFrameMaincallback FunctiondeviceId String | null (optional)Emitted when a HID device needs to be selected when a call to navigator.hid.requestDevice is made. callback should be called with deviceId to be selected; passing no arguments to callback will cancel the request. Additionally, permissioning on navigator.hid can be further managed by using ses.setPermissionCheckHandler(handler) and ses.setDevicePermissionHandler(handler)`.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nВозвращает:
\neventdetailsdevice HIDDevice[]frame WebFrameMainEmitted when a new HID device becomes available. For example, when a new USB device is plugged in.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
Возвращает:
\neventdetailsdevice HIDDevice[]frame WebFrameMainEmitted when a HID device has been removed. For example, this event will fire when a USB device is unplugged.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
Возвращает:
\neventportList SerialPort[]webContents WebContentscallback FunctionportIdEmitted when a serial port needs to be selected when a call to navigator.serial.requestPort is made. callback should be called with portId to be selected, passing an empty string to callback will cancel the request. Additionally, permissioning on navigator.serial can be managed by using ses.setPermissionCheckHandler(handler) with the serial permission.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({\n width: 800,\n height: 600\n })\n win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {\n event.preventDefault()\n const selectedPort = portList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n if (!selectedPort) {\n callback('')\n } else {\n callback(selectedPort.portId)\n }\n })\n})\nВозвращает:
\neventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a new serial port becomes available. For example, this event will fire when a new USB device is plugged in.
Возвращает:
\neventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a serial port has been removed. For example, this event will fire when a USB device is unplugged.
Для экземпляров Session доступны следующие методы:
ses.getCacheSize()Возвращает Promise<Integer> - текущий размер кэша сеанса, в байтах.
ses.clearCache()Возвращает Promise<void> - Разрешение после завершения операции очистки кэша.
Очищает HTTP-кэш сеанса.
\nses.clearStorageData([options])options Object (опционально)origin String (опционально) - Должен следовать представлению window.location.origin scheme://host:port.storages String - типы хранилищ для очистки, могут содержать: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage. If not specified, clear all storage types.quotas String - типы квот для очистки, могут содержать: temporary, persistent, syncable. If not specified, clear all quotas.Возвращает Promise<void> - Разрешение после завершения очистки данных хранилища.
ses.flushStorageData()Записывает непрочитанные DOMStorage данные на диск.
\nses.setProxy(config)config Objectmode String (optional) - The proxy mode. Should be one of direct, auto_detect, pac_script, fixed_servers or system. If it's unspecified, it will be automatically determined based on other specified options.direct In direct mode all connections are created directly, without any proxy involved.auto_detect In auto_detect mode the proxy configuration is determined by a PAC script that can be downloaded at http://wpad/wpad.dat.pac_script In pac_script mode the proxy configuration is determined by a PAC script that is retrieved from the URL specified in the pacScript. This is the default mode if pacScript is specified.fixed_servers In fixed_servers mode the proxy configuration is specified in proxyRules. This is the default mode if proxyRules is specified.system In system mode the proxy configuration is taken from the operating system. Note that the system mode is different from setting no proxy configuration. In the latter case, Electron falls back to the system settings only if no command-line options influence the proxy configuration.pacScript String (optional) - The URL associated with the PAC file.proxyRules String (optional) - Rules indicating which proxies to use.proxyBypassRules String (optional) - Rules indicating which URLs should bypass the proxy settings.Возвращает Promise<void> - Разрешение после завершения процесса настройки прокси.
Установка настроек прокси.
\nWhen mode is unspecified, pacScript and proxyRules are provided together, the proxyRules option is ignored and pacScript configuration is applied.
You may need ses.closeAllConnections to close currently in flight connections to prevent pooled sockets using previous proxy from being reused by future requests.
proxyRules должен следовать следующим правилам:
proxyRules = schemeProxies[\";\"<;0>]\nschemeProxies = [<;1>\"=\"]<;2>\nurlScheme = \"http\" | \"https\" | \"ftp\" | \"socks\"\nproxyURIList = <;3>[\",\"<;2>]\nproxyURL = [<;4>\"://\"]<;5>[\":\"<;6>]\nНапример:
\nhttp=foopy:80;ftp=foopy2 - Использовать HTTP прокси foopy:80 для URL http://, и HTTP прокси foopy2:80 для URL ftp://.foopy:80 - Использовать HTTP прокси foopy:80 для всех URL.foopy:80,bar,direct:// - Использовать HTTP прокси foopy:80 для всех URL-адресов, переключение на bar, если foopy:80 недоступен, и после этого прокси не использовать.socks4://foopy - Использовать SOCKS v4 прокси foopy:1080 для всех URL.http=foopy,socks5://bar.com - Использовать HTTP прокси foopy для http URL-адресов и и переключиться на прокси SOCKS5 bar.com, если foopy недоступен.http=foopy,direct:// - Использовать HTTP прокси foopy для http URL-адресов и не использовать прокси, если foopy недоступен.http=foopy;socks=foopy2 - Использовать HTTP прокси foopy для http URL-адресов и использовать socks4://foopy2 для всех других URL.proxyBypassRules - это список правил, разделенных запятыми:
[ URL_SCHEME \"://\" ] HOSTNAME_PATTERN [ \":\" <;0> ]
Сопоставьте все имена хостов, которые соответствуют шаблону HOSTNAME_PATTERN.
\nExamples: \"foobar.com\", \"foobar.com\", \".foobar.com\", \"foobar.com:99\", \"https://x..y.com:99\"
\n\".\" HOSTNAME_SUFFIX_PATTERN [ \":\" PORT ]
Соответствует суффиксу конкретного домена.
\nExamples: \".google.com\", \".com\", \"http://.google.com\"
\n[ SCHEME \"://\" ] IP_LITERAL [ \":\" PORT ]
Сравнивать URL, которые являются знаками IP-адресов.
\nНапример: \"127.0.1\", \"[0:0::1]\", \"[::1]\", \"http://[::1]:99\"
\nIP_LITERAL \"/\" PREFIX_LENGTH_IN_BITS
Match any URL that is to an IP literal that falls between the given range. IP range is specified using CIDR notation.
\nНапример: \"192.168.1.1/16\", \"fefe:13::abc/33\".
\n<local>
Match local addresses. The meaning of <local> is whether the host matches one of: \"127.0.0.1\", \"::1\", \"localhost\".
ses.resolveProxy(url)url URLВозвращает Promise<String> - Разрешение с информацией прокси для url.
ses.forceReloadProxyConfig()Returns Promise<void> - Resolves when the all internal states of proxy service is reset and the latest proxy configuration is reapplied if it's already available. The pac script will be fetched from pacScript again if the proxy mode is pac_script.
ses.setDownloadPath(path)path String - Место загрузки.Sets download saving directory. By default, the download directory will be the Downloads under the respective app folder.
ses.enableNetworkEmulation(options)options Objectoffline Boolean (optional) - Whether to emulate network outage. Defaults to false.latency Double (optional) - RTT in ms. Defaults to 0 which will disable latency throttling.downloadThroughput Double (optional) - Download rate in Bps. Defaults to 0 which will disable download throttling.uploadThroughput Double (optional) - Upload rate in Bps. Defaults to 0 which will disable upload throttling.Эмулирует сеть с заданной конфигурацией для session.
// Для эмулирования GPRS соединения с пропускной способностью 50кбит/с и задержкой 500 мс.\nwindow.webContents.session.enableNetworkEmulation({\n latency: 500,\n downloadThroughput: 6400,\n uploadThroughput: 6400\n})\n\n// Для эмулирования отключения или отказа сети.\nwindow.webContents.session.enableNetworkEmulation({ offline: true })\nses.preconnect(options)options Objecturl String - URL for preconnect. Only the origin is relevant for opening the socket.numSockets Number (optional) - number of sockets to preconnect. Must be between 1 and 6. Defaults to 1.Preconnects the given number of sockets to an origin.
\nses.closeAllConnections()Returns Promise<void> - Resolves when all connections are closed.
Note: It will terminate / fail all requests currently in flight.
\nses.disableNetworkEmulation()Disables any network emulation already active for the session. Resets to the original network configuration.
ses.setCertificateVerifyProc(proc)proc Function | nullrequest Objecthostname Stringcertificate CertificatevalidatedCertificate CertificateverificationResult String - Результат проверки из хрома.errorCode Integer - Код ошибки.callback FunctionverificationResult Integer - Value can be one of certificate error codes from here. Apart from the certificate error codes, the following special codes can be used.0 - Указывает на успех и отключает проверку прозрачности сертификата.-2 - указывает на сбой.-3 - Использует результат проверки из хрома.Устанавливает значение проверки сертификата для session, proc будет вызываться с proc(request, callback) всякий раз, когда запрашивается сертификат сервера. Вызов callback(0) принимает сертификат, вызов callback(-2) отклоняет его.
Вызов setCertificateVerifyProc (null) приведет к возврату к процедуре проверки сертификата по умолчанию.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.webContents.session.setCertificateVerifyProc((request, callback) => {\n const { hostname } = request\n if (hostname === 'github.com') {\n callback(0)\n } else {\n callback(-2)\n }\n})\n\n\nNOTE: The result of this procedure is cached by the network service.
\n
ses.setPermissionRequestHandler(handler)handler Function | nullwebContents WebContents - WebContents requesting the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.permission String - The type of requested permission.clipboard-read - Request access to read from the clipboard.media - Request access to media devices such as camera, microphone and speakers.display-capture - Request access to capture the screen.mediaKeySystem - Request access to DRM protected content.geolocation - Request access to user's current location.notifications - Request notification creation and the ability to display them in the user's system tray.midi - Request MIDI access in the webmidi API.midiSysex - Request the use of system exclusive messages in the webmidi API.pointerLock - Request to directly interpret mouse movements as an input method. Click here to know more.fullscreen - Request for the app to enter fullscreen mode.openExternal - Request to open links in external applications.unknown - An unrecognized permission requestcallback FunctionpermissionGranted Boolean - Allow or deny the permission.details Object - Some properties are only available on certain permission types.externalURL String (optional) - The url of the openExternal request.mediaTypes String - The types of media access being requested, elements can be video or audiorequestingUrl String - The last URL the requesting frame loadedisMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission requests for the session. Calling callback(true) will allow the permission and callback(false) will reject it. To clear the handler, call setPermissionRequestHandler(null). Please note that you must also implement setPermissionCheckHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied.
const { session } = require('electron')\nsession.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {\n if (webContents.getURL() === 'some-host' && permission === 'notifications') {\n return callback(false) // denied.\n }\n\n callback(true)\n})\nses.setPermissionCheckHandler(handler)handler Function\\webContents (WebContents | null) - WebContents checking the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin. Все перекрёстные подкадры, делающие проверку прав доступа, передадут этому обработчику null webContents, в то время как другие проверку прав доступа, такие как notifications, после проверки всегда будут передавать null. You should use embeddingOrigin and requestingOrigin to determine what origin the owning frame and the requesting frame are on respectively.permission String - Type of permission check. Valid values are midiSysex, notifications, geolocation, media,mediaKeySystem,midi, pointerLock, fullscreen, openExternal, hid, or serial.requestingOrigin String - The origin URL of the permission checkdetails Object - Some properties are only available on certain permission types.embeddingOrigin String (optional) - The origin of the frame embedding the frame that made the permission check. Only set for cross-origin sub frames making permission checks.securityOrigin String (optional) - The security origin of the media check.mediaType String (optional) - The type of media access being requested, can be video, audio or unknownrequestingUrl String (optional) - The last URL the requesting frame loaded. This is not provided for cross-origin sub frames making permission checks.isMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission checks for the session. Returning true will allow the permission and false will reject it. Please note that you must also implement setPermissionRequestHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied. To clear the handler, call setPermissionCheckHandler(null).
const { session } = require('electron')\nconst url = require('url')\nsession.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {\n return true // granted\n }\n\n return false // denied\n})\nses.setDevicePermissionHandler(handler)handler Function\\detailsdeviceType String - The type of device that permission is being requested on, can be hid.origin String - The origin URL of the device permission check.device HIDDevice - the device that permission is being requested for.frame WebFrameMain - WebFrameMain checking the device permission.Sets the handler which can be used to respond to device permission checks for the session. Returning true will allow the device to be permitted and false will reject it. To clear the handler, call setDevicePermissionHandler(null). This handler can be used to provide default permissioning to devices without first calling for permission to devices (eg via navigator.hid.requestDevice). If this handler is not defined, the default device permissions as granted through device selection (eg via navigator.hid.requestDevice) will be used. Additionally, the default behavior of Electron is to store granted device permision through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nses.clearHostResolverCache()Returns Promise<void> - Resolves when the operation is complete.
Clears the host resolver cache.
\nses.allowNTLMCredentialsForDomains(domains)domains String - A comma-separated list of servers for which integrated authentication is enabled.Dynamically sets whether to always send credentials for HTTP NTLM or Negotiate authentication.
\nconst { session } = require('electron')\n// consider any url ending with `example.com`, `foobar.com`, `baz`\n// for integrated authentication.\nsession.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')\n\n// consider all urls for integrated authentication.\nsession.defaultSession.allowNTLMCredentialsForDomains('*')\nses.setUserAgent(userAgent[, acceptLanguages])userAgent StringacceptLanguages String (опционально)Overrides the userAgent and acceptLanguages for this session.
The acceptLanguages must a comma separated ordered list of language codes, for example \"en-US,fr,de,ko,zh-CN,ja\".
This doesn't affect existing WebContents, and each WebContents can use webContents.setUserAgent to override the session-wide user agent.
ses.isPersistent()Returns Boolean - Whether or not this session is a persistent one. The default webContents session of a BrowserWindow is persistent. When creating a session from a partition, session prefixed with persist: will be persistent, while others will be temporary.
ses.getUserAgent()Returns String - The user agent for this session.
ses.setSSLConfig(config)config ObjectminVersion String (опционально) - Может быть tls1, tls1.1, tls1.2 или tls1.3. The minimum SSL version to allow when connecting to remote servers. Значение по умолчанию: tls1.maxVersion String (опционально) - Может быть tls1.2 или tls1.3. The maximum SSL version to allow when connecting to remote servers. Defaults to tls1.3.disabledCipherSuites Integer - List of cipher suites which should be explicitly prevented from being used in addition to those disabled by the net built-in policy. Supported literal forms: 0xAABB, where AA is cipher_suite[0] and BB is cipher_suite[1], as defined in RFC 2246, Section 7.4.1.2. Unrecognized but parsable cipher suites in this form will not return an error. Ex: To disable TLS_RSA_WITH_RC4_128_MD5, specify 0x0004, while to disable TLS_ECDH_ECDSA_WITH_RC4_128_SHA, specify 0xC002. Note that TLSv1.3 ciphers cannot be disabled using this mechanism.Sets the SSL configuration for the session. All subsequent network requests will use the new configuration. Existing network connections (such as WebSocket connections) will not be terminated, but old sockets in the pool will not be reused for new connections.
\nses.getBlobData(identifier)identifier String - Valid UUID.Returns Promise<Buffer> - resolves with blob data.
ses.downloadURL(url)url StringInitiates a download of the resource at url. The API will generate a DownloadItem that can be accessed with the will-download event.
Note: This does not perform any security checks that relate to a page's origin, unlike webContents.downloadURL.
ses.createInterruptedDownload(options)options Objectpath String - Absolute path of the download.urlChain String[] - Complete URL chain for the download.mimeType String (опционально)offset Integer - Start range for the download.length Integer - Total length of the download.lastModified String (optional) - Last-Modified header value.eTag String (optional) - ETag header value.startTime Double (optional) - Time when download was started in number of seconds since UNIX epoch.Allows resuming cancelled or interrupted downloads from previous Session. The API will generate a DownloadItem that can be accessed with the will-download event. The DownloadItem will not have any WebContents associated with it and the initial state will be interrupted. The download will start only when the resume API is called on the DownloadItem.
ses.clearAuthCache()Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.
ses.setPreloads(preloads)preloads String[] - An array of absolute path to preload scriptsAdds scripts that will be executed on ALL web contents that are associated with this session just before normal preload scripts run.
ses.getPreloads()Returns String[] an array of paths to preload scripts that have been registered.
ses.setSpellCheckerEnabled(enable)enable BooleanSets whether to enable the builtin spell checker.
\nses.isSpellCheckerEnabled()Returns Boolean - Whether the builtin spell checker is enabled.
ses.setSpellCheckerLanguages(languages)languages String[] - An array of language codes to enable the spellchecker for.The built in spellchecker does not automatically detect what language a user is typing in. In order for the spell checker to correctly check their words you must call this API with an array of language codes. You can get the list of supported language codes with the ses.availableSpellCheckerLanguages property.
Note: On macOS the OS spellchecker is used and will detect your language automatically. This API is a no-op on macOS.
\nses.getSpellCheckerLanguages()Returns String[] - An array of language codes the spellchecker is enabled for. If this list is empty the spellchecker will fallback to using en-US. By default on launch if this setting is an empty list Electron will try to populate this setting with the current OS locale. This setting is persisted across restarts.
Note: On macOS the OS spellchecker is used and has its own list of languages. This API is a no-op on macOS.
\nses.setSpellCheckerDictionaryDownloadURL(url)url String - A base URL for Electron to download hunspell dictionaries from.By default Electron will download hunspell dictionaries from the Chromium CDN. If you want to override this behavior you can use this API to point the dictionary downloader at your own hosted version of the hunspell dictionaries. We publish a hunspell_dictionaries.zip file with each release which contains the files you need to host here, the file server must be case insensitive you must upload each file twice, once with the case it has in the ZIP file and once with the filename as all lower case.
If the files present in hunspell_dictionaries.zip are available at https://example.com/dictionaries/language-code.bdic then you should call this api with ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Please note the trailing slash. The URL to the dictionaries is formed as ${url}${filename}.
Note: On macOS the OS spellchecker is used and therefore we do not download any dictionary files. This API is a no-op on macOS.
\nses.listWordsInSpellCheckerDictionary()Returns Promise<String[]> - An array of all words in app's custom dictionary. Resolves when the full dictionary is loaded from disk.
ses.addWordToSpellCheckerDictionary(word)word String - The word you want to add to the dictionaryReturns Boolean - Whether the word was successfully written to the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be written to the OS custom dictionary as well
\nses.removeWordFromSpellCheckerDictionary(word)word String - The word you want to remove from the dictionaryReturns Boolean - Whether the word was successfully removed from the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be removed from the OS custom dictionary as well
\nses.loadExtension(path[, options])path String - Path to a directory containing an unpacked Chrome extensionoptions Object (опционально)allowFileAccess Boolean - Whether to allow the extension to read local files over file:// protocol and inject content scripts into file:// pages. This is required e.g. for loading devtools extensions on file:// URLs. По умолчанию - false.Returns Promise<Extension> - resolves when the extension is loaded.
This method will raise an exception if the extension could not be loaded. If there are warnings when installing the extension (e.g. if the extension requests an API that Electron does not support) then they will be logged to the console.
\nNote that Electron does not support the full range of Chrome extensions APIs. See Supported Extensions APIs for more details on what is supported.
\nNote that in previous versions of Electron, extensions that were loaded would be remembered for future runs of the application. This is no longer the case: loadExtension must be called on every boot of your app if you want the extension to be loaded.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.on('ready', async () => {\n await session.defaultSession.loadExtension(\n path.join(__dirname, 'react-devtools'),\n // allowFileAccess is required to load the devtools extension on file:// URLs.\n { allowFileAccess: true }\n )\n // Note that in order to use the React DevTools extension, you'll need to\n // download and unzip a copy of the extension.\n})\nThis API does not support loading packed (.crx) extensions.
\nПримечание: Этот метод не может быть вызван до тех пор, пока событие ready модуля app не произойдет.
Note: Loading extensions into in-memory (non-persistent) sessions is not supported and will throw an error.
\nses.removeExtension(extensionId)extensionId String - ID of extension to removeUnloads an extension.
\nПримечание: Этот метод не может быть вызван до тех пор, пока событие ready модуля app не произойдет.
ses.getExtension(extensionId)extensionId String - ID of extension to queryReturns Extension | null - The loaded extension with the given ID.
Примечание: Этот метод не может быть вызван до тех пор, пока событие ready модуля app не произойдет.
ses.getAllExtensions()Returns Extension[] - A list of all loaded extensions.
Примечание: Этот метод не может быть вызван до тех пор, пока событие ready модуля app не произойдет.
ses.getStoragePath()A String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
Для экземпляров Session доступны следующие свойства:
ses.availableSpellCheckerLanguages Только чтениеA String[] array which consists of all the known available spell checker languages. Providing a language code to the setSpellCheckerLanguages API that isn't in this array will result in an error.
ses.spellCheckerEnabledA Boolean indicating whether builtin spell checker is enabled.
ses.storagePath Только чтениеA String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
ses.cookies Только чтениеA Cookies object for this session.
ses.serviceWorkers Только чтениеA ServiceWorkers object for this session.
ses.webRequest Только чтениеA WebRequest object for this session.
ses.protocol Только чтениеA Protocol object for this session.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const protocol = session.fromPartition('some-partition').protocol\n if (!protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })) {\n console.error('Failed to register protocol')\n }\n})\nses.netLog Только чтениеA NetLog object for this session.
const { app, session } = require('electron')\n\napp.whenReady().then(async () => {\n const netLog = session.fromPartition('some-partition').netLog\n netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nDebug symbols allow you to have better debugging sessions. They have information about the functions contained in executables and dynamic libraries and provide you with information to get clean call stacks. A Symbol Server allows the debugger to load the correct symbols, binaries and sources automatically without forcing users to download large debugging files. The server functions like Microsoft's symbol server so the documentation there can be useful.
\nNote that because released Electron builds are heavily optimized, debugging is not always easy. The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations. The only workaround is to build an unoptimized local build.
\nThe official symbol server URL for Electron is https://symbols.electronjs.org. You cannot visit this URL directly, you must add it to the symbol path of your debugging tool. In the examples below, a local cache directory is used to avoid repeatedly fetching the PDB from the server. Replace c:\\code\\symbols with an appropriate cache directory on your machine.
The Windbg symbol path is configured with a string value delimited with asterisk characters. To use only the Electron symbol server, add the following entry to your symbol path (Note: you can replace c:\\code\\symbols with any writable directory on your computer, if you'd prefer a different location for downloaded symbols):
SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\nSet this string as _NT_SYMBOL_PATH in the environment, using the Windbg menus, or by typing the .sympath command. If you would like to get symbols from Microsoft's symbol server as well, you should list that first:
SRV*c:\\code\\symbols\\*https://msdl.microsoft.com/download/symbols;SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\n Options\">
Type the following commands in Windbg to print why symbols are not loading:
\n> !sym noisy\n> .reload /f electron.exe\nThe ShareMenu class creates Share Menu on macOS, which can be used to share information from the current context to apps, social media accounts, and other services.
For including the share menu as a submenu of other menus, please use the shareMenu role of MenuItem.
\n\nCreate share menu on macOS.
\n
Процесс: Основной
\nnew ShareMenu(sharingItem)sharingItem SharingItem - The item to share.Creates a new share menu.
\nЭкземпляр объекта shareMenu содержит следующие методы:
shareMenu.popup([options])options PopupOptions (optional)browserWindow BrowserWindow (опционально) - по умолчанию это сфокусированное окно.x Number (optional) - Default is the current mouse cursor position. Must be declared if y is declared.y Number (optional) - Default is the current mouse cursor position. Must be declared if x is declared.positioningItem Number (optional) macOS - The index of the menu item to be positioned under the mouse cursor at the specified coordinates. Default is -1.callback Функция (опционально) - вызывается, когда меню закрыто.Переключает это меню в контекстное меню в BrowserWindow.
shareMenu.closePopup([browserWindow])browserWindow BrowserWindow (опционально) - по умолчанию это сфокусированное окно.Закрывает контекстное меню в browserWindow.
id String - The unique id of the shared worker.url String - The url of the shared worker.texts String - An array of text to share.filePaths String - An array of files to share.urls String - An array of URLs to share.\n\nУправление файлами и URL-ами, используя стандартные приложения для их открытия.
\n
Process: Main, Renderer (non-sandboxed only)
\nМодуль shell предоставляет функции, относящиеся к десктопной интеграции.
Пример открытия ссылки в стандартном браузере пользователя:
\nconst { shell } = require('electron')\n\nshell.openExternal('https://github.com')\nNote: While the shell module can be used in the renderer process, it will not function in a sandboxed renderer.
Модуль shell имеет следующие методы:
shell.showItemInFolder(fullPath)fullPath StringShow the given file in a file manager. If possible, select the file.
\nshell.openPath(path)path StringReturns Promise<String> - Resolves with a string containing the error message corresponding to the failure if a failure occurred, otherwise \"\".
Open the given file in the desktop's default manner.
\nshell.openExternal(url[, options])url String - Max 2081 characters on windows.options Object (опционально)activate Boolean (optional) macOS - true to bring the opened application to the foreground. По-умолчанию - true.workingDirectory String (optional) Windows - The working directory.Возвращает Promise<void>
Open the given external protocol URL in the desktop's default manner. (For example, mailto: URLs in the user's default mail agent).
\nshell.trashItem(path)path String - path to the item to be moved to the trash.Returns Promise<void> - Resolves when the operation has been completed. Rejects if there was an error while deleting the requested item.
This moves a path to the OS-specific trash location (Trash on macOS, Recycle Bin on Windows, and a desktop-environment-specific location on Linux).
\nshell.beep()Play the beep sound.
\nshell.writeShortcutLink(shortcutPath[, operation], options) WindowsshortcutPath Stringoperation String (optional) - Default is create, can be one of following:create - Creates a new shortcut, overwriting if necessary.update - Updates specified properties only on an existing shortcut.replace - Overwrites an existing shortcut, fails if the shortcut doesn't exist.options ShortcutDetailsReturns Boolean - Whether the shortcut was created successfully.
Creates or updates a shortcut link at shortcutPath.
shell.readShortcutLink(shortcutPath) WindowsshortcutPath StringВозвращает ShortcutDetails
Resolves the shortcut link at shortcutPath.
An exception will be thrown when any error happens.
", "title": "shell", "description": "Управление файлами и URL-ами, используя стандартные приложения для их открытия." }, "/docs/api/structures/shortcut-details": { "locale": "ru-RU", "slug": "shortcut-details", "href": "/docs/api/structures/shortcut-details", "crowdinFileId": "256509", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/shortcut-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "target String - The target to launch from this shortcut.cwd String (optional) - The working directory. Default is empty.args String (optional) - The arguments to be applied to target when launching from this shortcut. Default is empty.description String (optional) - The description of the shortcut. Default is empty.icon String (optional) - The path to the icon, can be a DLL or EXE. icon and iconIndex have to be set together. Default is empty, which uses the target's icon.iconIndex Number (optional) - The resource ID of icon when icon is a DLL or EXE. Default is 0.appUserModelId String (optional) - The Application User Model ID. Default is empty.toastActivatorClsid String (optional) - The Application Toast Activator CLSID. Needed for participating in Action Center.width Numberheight NumberThis guide provides information on how to package your Electron application for any Snapcraft environment, including the Ubuntu Software Center.
\nTogether with the broader Linux community, Canonical aims to fix many of the common software installation problems with the snapcraft project. Snaps are containerized software packages that include required dependencies, auto-update, and work on all major Linux distributions without system modification.
There are three ways to create a .snap file:
1) Using electron-forge or electron-builder, both tools that come with snap support out of the box. This is the easiest option. 2) Using electron-installer-snap, which takes electron-packager's output. 3) Using an already created .deb package.
В некоторых случаях вам нужно установить инструмент snapcraft. Инструкции по установке snapcraft для вашего конкретного дистрибутива доступны здесь.
electron-installer-snapThe module works like electron-winstaller and similar modules in that its scope is limited to building snap packages. Вы можете установить его с:
npm install --save-dev electron-installer-snap\nPackage the application using electron-packager (or a similar tool). Удостоверьтесь, что вы удалили node_modules, которые не понадобятся вам в финальной версии приложения, так как любой неиспользуемый модуль в конечном счете увеличит размер вашего приложения.
Консольный вывод должен иметь примерный вид:
\n.\n└── dist\n └── app-linux-x64\n ├── LICENSE\n ├── LICENSES.chromium.html\n ├── content_shell.pak\n ├── app\n ├── icudtl.dat\n ├── libgcrypt.so.11\n ├── libnode.so\n ├── locales\n ├── resources\n ├── v8_context_snapshot.bin\n └── version\nelectron-installer-snapС терминала, который имеет snapcraft в PATH, запустить electron-installer-snap с единственным требуемым параметром --src, которое является местоположением вашего упакованного приложения Electron, созданного на первом шаге.
npx electron-installer-snap --src=out/myappname-linux-x64\nIf you have an existing build pipeline, you can use electron-installer-snap programmatically. For more information, see the Snapcraft API docs.
const snap = require('electron-installer-snap')\n\nsnap(options)\n .then(snapPath => console.log(`Created snap at ${snapPath}!`))\nsnapcraft with electron-packagerCreate your project directory and add the following to snap/snapcraft.yaml:
name: electron-packager-hello-world\nversion: '0.1'\nsummary: Hello World Electron app\ndescription: |\n Simple Hello World Electron app as an example\nbase: core18\nconfinement: strict\ngrade: stable\n\napps:\n electron-packager-hello-world:\n command: electron-quick-start/electron-quick-start --no-sandbox\n extensions: [gnome-3-34]\n plugs:\n - browser-support\n - network\n - network-bind\n environment:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n TMPDIR: $XDG_RUNTIME_DIR\n\nparts:\n electron-quick-start:\n plugin: nil\n source: https://github.com/electron/electron-quick-start.git\n override-build: |\n npm install electron electron-packager\n npx electron-packager . --overwrite --platform=linux --output=release-build --prune=true\n cp -rv ./electron-quick-start-linux-* $SNAPCRAFT_PART_INSTALL/electron-quick-start\n build-snaps:\n - node/14/stable\n build-packages:\n - unzip\n stage-packages:\n - libnss3\n - libnspr4\nIf you want to apply this example to an existing project:
\nsource: https://github.com/electron/electron-quick-start.git with source: ..electron-quick-start with your project's name.$ snapcraft\n\n<output snipped>\nSnapped electron-packager-hello-world_0.1_amd64.snap\nsudo snap install electron-packager-hello-world_0.1_amd64.snap --dangerous\nelectron-packager-hello-world\nSnapcraft is capable of taking an existing .deb file and turning it into a .snap file. The creation of a snap is configured using a snapcraft.yaml file that describes the sources, dependencies, description, and other core building blocks.
If you do not already have a .deb package, using electron-installer-snap might be an easier path to create snap packages. However, multiple solutions for creating Debian packages exist, including electron-forge, electron-builder or electron-installer-debian.
For more information on the available configuration options, see the documentation on the snapcraft syntax. Let's look at an example:
\nname: myApp\nversion: '2.0.0'\nsummary: A little description for the app.\ndescription: |\n You know what? This app is amazing! It does all the things\n for you. Some say it keeps you young, maybe even happy.\n\ngrade: stable\nconfinement: classic\n\nparts:\n slack:\n plugin: dump\n source: my-deb.deb\n source-type: deb\n after:\n - desktop-gtk3\n stage-packages:\n - libasound2\n - libnotify4\n - libnspr4\n - libnss3\n - libpcre3\n - libpulse0\n - libxss1\n - libxtst6\n electron-launch:\n plugin: dump\n source: files/\n prepare: |\n chmod +x bin/electron-launch\n\napps:\n myApp:\n command: bin/electron-launch $SNAP/usr/lib/myApp/myApp\n desktop: usr/share/applications/myApp.desktop\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n environment:\n TMPDIR: $XDG_RUNTIME_DIR\nAs you can see, the snapcraft.yaml instructs the system to launch a file called electron-launch. In this example, it passes information on to the app's binary:
\nexec \"$@\" --executed-from=\"$(pwd)\" --pid=$$ > /dev/null 2>&1 &\nAlternatively, if you're building your snap with strict confinement, you can use the desktop-launch command:
apps:\n myApp:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n command: env TMPDIR=$XDG_RUNTIME_DIR PATH=/usr/local/bin:${PATH} ${SNAP}/bin/desktop-launch $SNAP/myApp/desktop\n desktop: usr/share/applications/desktop.desktop\nThe source code of Electron is separated into a few parts, mostly following Chromium on the separation conventions.
\nYou may need to become familiar with Chromium's multi-process architecture to understand the source code better.
\nElectron\n├── build/ - Build configuration files needed to build with GN.\n├── buildflags/ - Determines the set of features that can be conditionally built.\n├── chromium_src/ - Source code copied from Chromium that isn't part of the content layer.\n├── default_app/ - A default app run when Electron is started without\n| providing a consumer app.\n├── docs/ - Electron's documentation.\n| ├── api/ - Documentation for Electron's externally-facing modules and APIs.\n| ├── development/ - Documentation to aid in developing for and with Electron.\n| ├── fiddles/ - A set of code snippets one can run in Electron Fiddle.\n| ├── images/ - Images used in documentation.\n| └── tutorial/ - Tutorial documents for various aspects of Electron.\n├── lib/ - JavaScript/TypeScript source code.\n| ├── browser/ - Main process initialization code.\n| | ├── api/ - API implementation for main process modules.\n| | └── remote/ - Code related to the remote module as it is\n| | used in the main process.\n| ├── common/ - Relating to logic needed by both main and renderer processes.\n| | └── api/ - API implementation for modules that can be used in\n| | both the main and renderer processes\n| ├── isolated_renderer/ - Handles creation of isolated renderer processes when\n| | contextIsolation is enabled.\n| ├── renderer/ - Renderer process initialization code.\n| | ├── api/ - API implementation for renderer process modules.\n| | ├── extension/ - Code related to use of Chrome Extensions\n| | | in Electron's renderer process.\n| | ├── remote/ - Logic that handles use of the remote module in\n| | | the main process.\n| | └── web-view/ - Logic that handles the use of webviews in the\n| | renderer process.\n| ├── sandboxed_renderer/ - Logic that handles creation of sandboxed renderer\n| | | processes.\n| | └── api/ - API implementation for sandboxed renderer processes.\n| └── worker/ - Logic that handles proper functionality of Node.js\n| environments in Web Workers.\n├── patches/ - Patches applied on top of Electron's core dependencies\n| | in order to handle differences between our use cases and\n| | default functionality.\n| ├── boringssl/ - Patches applied to Google's fork of OpenSSL, BoringSSL.\n| ├── chromium/ - Patches applied to Chromium.\n| ├── node/ - Patches applied on top of Node.js.\n| └── v8/ - Patches applied on top of Google's V8 engine.\n├── shell/ - C++ source code.\n| ├── app/ - System entry code.\n| ├── browser/ - The frontend including the main window, UI, and all of the\n| | | main process things. This talks to the renderer to manage web\n| | | pages.\n| | ├── ui/ - Implementation of UI stuff for different platforms.\n| | | ├── cocoa/ - Cocoa specific source code.\n| | | ├── win/ - исходный код специфичный для Windows GUI.\n| | ├── net/ - исходный код специфичный для X11.\n| | ├── api/ - The implementation of the main process APIs.\n| | ├── net/ - Код, связанный с сетью.\n| | ├── mac/ - Исходный код на Objective-C специфичный для Mac.\n| | └── resources/ - Icons, platform-dependent files, etc.\n| ├── renderer/ - Code that runs in renderer process.\n| | └── api/ - The implementation of renderer process APIs.\n| └── common/ - Code that used by both the main and renderer processes,\n| | including some utility functions and code to integrate node's\n| | message loop into Chromium's message loop.\n| └── api/ - The implementation of common APIs, and foundations of\n| Electron's built-in modules.\n├── spec/ - Components of Electron's test suite run in the renderer process.\n├── spec-main/ - Components of Electron's test suite run in the main process.\n└── BUILD.gn - Building rules of Electron.\nscript/create-dist.py script when creating a distribution.ninja.script/ - The set of all scripts Electron runs for a variety of purposes.\n├── codesign/ - Fakes codesigning for Electron apps; used for testing.\n├── lib/ - Miscellaneous python utility scripts.\n└── release/ - Scripts run during Electron's release process.\n ├── notes/ - Generates release notes for new Electron versions.\n └── uploaders/ - Uploads various release-related files during release.\nElectron has built-in support for Chromium's spellchecker since Electron 8. On Windows and Linux this is powered by Hunspell dictionaries, and on macOS it makes use of the native spellchecker APIs.
\nFor Electron 9 and higher the spellchecker is enabled by default. For Electron 8 you need to enable it in webPreferences.
const myWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: true\n }\n})\nOn macOS as we use the native APIs there is no way to set the language that the spellchecker uses. By default on macOS the native spellchecker will automatically detect the language being used for you.
\nFor Windows and Linux there are a few Electron APIs you should use to set the languages for the spellchecker.
\n// Sets the spellchecker to check English US and French\nmyWindow.session.setSpellCheckerLanguages(['en-US', 'fr'])\n\n// An array of all available language codes\nconst possibleLanguages = myWindow.session.availableSpellCheckerLanguages\nBy default the spellchecker will enable the language matching the current OS locale.
\nAll the required information to generate a context menu is provided in the context-menu event on each webContents instance. A small example of how to make a context menu with this information is provided below.
const { Menu, MenuItem } = require('electron')\n\nmyWindow.webContents.on('context-menu', (event, params) => {\n const menu = new Menu()\n\n // Add each spelling suggestion\n for (const suggestion of params.dictionarySuggestions) {\n menu.append(new MenuItem({\n label: suggestion,\n click: () => mainWindow.webContents.replaceMisspelling(suggestion)\n }))\n }\n\n // Allow users to add the misspelled word to the dictionary\n if (params.misspelledWord) {\n menu.append(\n new MenuItem({\n label: 'Add to dictionary',\n click: () => mainWindow.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord)\n })\n )\n }\n\n menu.popup()\n})\nAlthough the spellchecker itself does not send any typings, words or user input to Google services the hunspell dictionary files are downloaded from a Google CDN by default. If you want to avoid this you can provide an alternative URL to download the dictionaries from.
\nmyWindow.session.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/')\nCheck out the docs for session.setSpellCheckerDictionaryDownloadURL for more information on where to get the dictionary files from and how you need to host them.
Это руководство для написания Electron документации.
\n# в верхней части.##-level headings.# in the heading according to their nesting depth.Используйте Быстрый старт как пример:
# Quick Start\n\n...\n\n## Main process\n\n...\n\n## Renderer process\n\n...\n\n## Run your app\n\n...\n\n### Run as a distribution\n\n...\n\n### Manually downloaded Electron binary\n\n...\nДля ссылок на API есть исключения из этого правила.
\nThis repository uses the markdownlint package to enforce consistent Markdown styling. For the exact rules, see the .markdownlint.json file in the root folder.
There are a few style guidelines that aren't covered by the linter rules:
\n\nsh вместо cmd в блоках кода (из-за синтаксической подсветки).js и javascript проверяются линтером по standard-markdown.Следующие правила применяются только к документации по API.
\nEach module's API doc must use the actual object name returned by require('electron') as its title (such as BrowserWindow, autoUpdater, and session).
Directly under the page title, add a one-line description of the module as a markdown quote (beginning with >).
Using the session module as an example:
# session\n\n> Управление сеансами браузера, куками, кешем, настройками прокси и т.д.\nДля модулей, которые не являются классами, методы и события должны быть перечислены под главами ## Методы и ## События .
Используйте autoUpdater как пример:
# autoUpdater\n\n## События \n\n### Событие: 'error' \n\n## Методы \n\n### `autoUpdater.setFeedURL(url[, requestHeaders])`\n## Класс: НазваниеКласса.###-level headings.### Static Methods chapter.### Instance Methods chapter.[TYPE] - [Return description]\"Object, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.### События экземпляра.### Instance Properties chapter.Используйте классы Session и Cookies в качестве примера:
# session\n\n## Методы\n\n### session.fromPartition(partition)\n\n## Статические свойства\n\n### session.defaultSession\n\n## Class: Session\n\n### События экземпляра\n\n#### Event: 'will-download'\n\n### Методы экземпляра\n\n#### `ses.getCacheSize()`\n\n### Свойства экземпляра\n\n#### `ses.cookies`\n\n## Class: Cookies\n\n### Методы экземпляра\n\n#### `cookies.get(filter, callback)`\nМетоды главы должны быть в следующем виде:
\n### `objectName.methodName(required[, optional]))`\n\n* `required` String - A parameter description.\n* `optional` Integer (optional) - Another parameter description.\n\n...\nThe heading can be ### or ####-levels depending on whether the method belongs to a module or a class.
For modules, the objectName is the module's name. For classes, it must be the name of the instance of the class, and must not be the same as the module's name.
Например, методы класса Session под модулем session должны использовать ses как objectName.
Optional arguments are notated by square brackets [] surrounding the optional argument as well as the comma required if this optional argument follows another argument:
required[, optional]\nMore detailed information on each of the arguments is noted in an unordered list below the method. The type of argument is notated by either JavaScript primitives (e.g. String, Promise, or Object), a custom API structure like Electron's Cookie, or the wildcard any.
If the argument is of type Array, use [] shorthand with the type of value inside the array (for example,any[] or String[]).
If the argument is of type Promise, parametrize the type with what the promise resolves to (for example, Promise<void> or Promise<String>).
If an argument can be of multiple types, separate the types with |.
Описание аргументов типа Function должно дать понять, как это может быть вызвано и перечислить типы параметров, которые будут переданы ему.
Если аргумент или метод является уникальным для определенных платформ, эти платформы обозначаются списком, разделенных пробелами, после типа данных. Значения могут быть macOS, Windows или Linux.
* `animate` Boolean (по усмотрению) _macOS_ _Windows_ - анимировать вещь.\nГлава события должна быть в следующем виде:
\n### Событие: 'wake-up'\n\nВозвращает:\n\n* `time` String\n\n...\nThe heading can be ### or ####-levels depending on whether the event belongs to a module or a class.
Аргументы события следуют тем же правилам методов.
\nГлава свойства должна быть в следующем виде:
\n### session.defaultSession\n\n...\nThe heading can be ### or ####-levels depending on whether the property belongs to a module or a class.
См. electron/i18n
", "title": "Руководство по стилю документации Electron", "description": "" }, "/docs/tutorial/support": { "locale": "ru-RU", "slug": "support", "href": "/docs/tutorial/support", "crowdinFileId": "256253", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/support.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Если у вас есть проблема с безопасностью, смотрите документ безопасности.
\nЕсли вы ищете помощь в программировании, для ответов на вопросы, или присоединиться к обсуждению с другими разработчиками, которые используют Electron, вы можете взаимодействовать с сообществом в этих местах:
\nElectron's Discord has channels for:electron category on the Atom forums#electron канал на Atom Slackelectron-ru (Русский)electron-br (Бразильский Португальский)electron-kr (Корейский)electron-jp (Японский)electron-tr (Турецкий)electron-id (Индонезия)electron-pl (Польша)Если вы хотите внести свой вклад в Electron, смотрите документ.
\nЕсли вы обнаружили ошибку в поддерживаемой версии Electron, сообщите об этом issue tracker.
\nawesome-electron is a community-maintained list of useful example apps, tools and resources.
\nNote: Beginning in September 2021 with Electron 15, the Electron team will temporarily support the latest four stable major versions. This extended support is intended to help Electron developers transition to the new eight week release cadence, and will continue until May 2022, with the release of Electron 19. At that time, the Electron team will drop support back to the latest three stable major versions.
\nThe latest three stable major versions are supported by the Electron team. For example, if the latest release is 6.1.x, then the 5.0.x as well as the 4.2.x series are supported. We only support the latest minor release for each stable release series. This means that in the case of a security fix 6.1.x will receive the fix, but we will not release a new version of 6.0.x.
\nThe latest stable release unilaterally receives all fixes from main, and the version prior to that receives the vast majority of those fixes as time and bandwidth warrants. The oldest supported release line will receive only security fixes directly.
All supported release lines will accept external pull requests to backport fixes previously merged to main, though this may be on a case-by-case basis for some older supported lines. All contested decisions around release line backports will be resolved by the Releases Working Group as an agenda item at their weekly meeting the week the backport PR is raised.
When an API is changed or removed in a way that breaks existing functionality, the previous functionality will be supported for a minimum of two major versions when possible before being removed. For example, if a function takes three arguments, and that number is reduced to two in major version 10, the three-argument version would continue to work until, at minimum, major version 12. Past the minimum two-version threshold, we will attempt to support backwards compatibility beyond two versions until the maintainers feel the maintenance burden is too high to continue doing so.
\nWhen a release branch reaches the end of its support cycle, the series will be deprecated in NPM and a final end-of-support release will be made. This release will add a warning to inform that an unsupported version of Electron is in use.
\nThese steps are to help app developers learn when a branch they're using becomes unsupported, but without being excessively intrusive to end users.
\nIf an application has exceptional circumstances and needs to stay on an unsupported series of Electron, developers can silence the end-of-support warning by omitting the final release from the app's package.json devDependencies. For example, since the 1-6-x series ended with an end-of-support 1.6.18 release, developers could choose to stay in the 1-6-x series without warnings with devDependency of \"electron\": 1.6.0 - 1.6.17.
Следующие платформы поддерживаются Electron:
\n对 macOS 仅提供64位版本，并且只支持 macOS 10.11 (El Capitan) 以及更高版本。.
\nNative support for Apple Silicon (arm64) devices was added in Electron 11.0.0.
Поддерживаются Windows 7 и более поздние версии, более старые операционные системы не поддерживаются (и не работают).
\nBoth ia32 (x86) and x64 (amd64) binaries are provided for Windows. Native support for Windows on Arm (arm64) devices was added in Electron 6.0.8.. Running apps packaged with previous versions is possible using the ia32 binary.
The prebuilt binaries of Electron are built on Ubuntu 18.04.
\nБудет ли готовая бинарная сборка включена в дистрибутив, зависит от того, включает ли дистрибутив библиотеки, с которыми связан Electron на компилирруемой платформе, поэтому гарантируется работа только в Ubuntu 18.04, но следующие платформы также проверяются, чтобы иметь возможность запускать прекомпилированные сборки Electron:
\n\n\nКак использовать API Node.js и Electron.
\n
Все встроенные модули Node.js доступны в Electron и сторонних модулях (включая нативные модули).
\nКроме того, Electron предоставляет дополнительные встроенные модули для разработки нативных дестопных приложений. Некоторые модули доступны только в главном процессе, некоторые доступны только в процессе отрисовки (веб-страницы), а некоторые могут быть использованы в обоих процессах.
\nОсновное правило: если модуль связан с GUI или системой низкого уровня, то должно быть доступно только в основном процессе. You need to be familiar with the concept of main process vs. renderer process scripts to be able to use those modules.
\nСкрипт основного процесса похож на обычный скрипт Node.js:
\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL('https://github.com')\n})\nПроцесс отрисовки ничем не отличается от обычной веб-страницы, за исключением дополнительной возможности использования модулей node, если параметр nodeIntegration имеет значение \"Включён\":
\n<html>\n<body>\n<script>\n const fs = require('fs')\n console.log(fs.readFileSync(__filename, 'utf8'))\n</script>\n</body>\n</html>\nНачиная с версии 0.37 можно использовать деструктирующее присваивание, для того чтобы упростить использование встроенных модулей.
\nconst { app, BrowserWindow } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nIf you need the entire electron module, you can require it and then using destructuring to access the individual modules from electron.
const electron = require('electron')\nconst { app, BrowserWindow } = electron\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nЭто эквивалентно следующему коду:
\nconst electron = require('electron')\nconst app = electron.app\nconst BrowserWindow = electron.BrowserWindow\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\n\n\nПолучение системных параметров.
\n
Процесс: Основной
\nconst { systemPreferences } = require('electron')\nconsole.log(systemPreferences.isDarkMode())\nОбъект systemPreferences включает следующие события:
Возвращает:
\neventnewColor Строка - новый цвет RGBA, назначенный пользователем в качестве акцентного цвета.Возвращает:
\neventВозвращает:
\neventinvertedColorScheme Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is being used, false otherwise.Deprecated: Should use the new updated event on the nativeTheme module.
Возвращает:
\neventhighContrastColorScheme Boolean - true if a high contrast theme is being used, false otherwise.Deprecated: Should use the new updated event on the nativeTheme module.
systemPreferences.isDarkMode() macOS Windows DeprecatedВозвращает Boolean - если система в Ночном режиме.
Deprecated: Should use the new nativeTheme.shouldUseDarkColors API.
systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOSReturns Boolean - Whether the Swipe between pages setting is on.
systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOSevent StringuserInfo Record<String, any>deliverImmediately Boolean (optional) - true to post notifications immediately even when the subscribing app is inactive.Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postLocalNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postWorkspaceNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.subscribeNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object StringReturns Number - The ID of this subscription
Subscribes to native notifications of macOS, callback will be called with callback(event, userInfo) when the corresponding event happens. The userInfo is an Object that contains the user information dictionary sent along with the notification. The object is the sender of the notification, and only supports NSString values for now.
The id of the subscriber is returned, which can be used to unsubscribe the event.
Under the hood this API subscribes to NSDistributedNotificationCenter, example values of event are:
AppleInterfaceThemeChangedNotificationAppleAquaColorVariantChangedAppleColorPreferencesChangedNotificationAppleShowScrollBarsSettingChangedsystemPreferences.subscribeLocalNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object StringReturns Number - The ID of this subscription
Same as subscribeNotification, but uses NSNotificationCenter for local defaults. This is necessary for events such as NSUserDefaultsDidChangeNotification.
systemPreferences.subscribeWorkspaceNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object StringReturns Number - The ID of this subscription
Same as subscribeNotification, but uses NSWorkspace.sharedWorkspace.notificationCenter. This is necessary for events such as NSWorkspaceDidActivateApplicationNotification.
systemPreferences.unsubscribeNotification(id) macOSid IntegerRemoves the subscriber with id.
systemPreferences.unsubscribeLocalNotification(id) macOSid IntegerSame as unsubscribeNotification, but removes the subscriber from NSNotificationCenter.
systemPreferences.unsubscribeWorkspaceNotification(id) macOSid IntegerSame as unsubscribeNotification, but removes the subscriber from NSWorkspace.sharedWorkspace.notificationCenter.
systemPreferences.registerDefaults(defaults) macOSdefaults Record<String, String | Boolean | Number> - a dictionary of (key: value) user defaultsAdd the specified defaults to your application's NSUserDefaults.
systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOSkey Stringtype Type - Can be string, boolean, integer, float, double, url, array or dictionary.Returns UserDefaultTypes[Type] - The value of key in NSUserDefaults.
Самые популярные key и type:
AppleInterfaceStyle: stringAppleAquaColorVariant: integerAppleHighlightColor: stringAppleShowScrollBars: stringNSNavRecentPlaces: arrayNSPreferredWebServices: dictionaryNSUserDictionaryReplacementItems: arraysystemPreferences.setUserDefault(key, type, value) macOSkey Stringtype String - Can be string, boolean, integer, float, double, url, array or dictionary.value StringУстанавливает значение key в NSUserDefaults.
Note that type should match actual type of value. An exception is thrown if they don't.
Самые популярные key и type:
ApplePressAndHoldEnabled: booleansystemPreferences.removeUserDefault(key) macOSkey StringRemoves the key in NSUserDefaults. This can be used to restore the default or global value of a key previously set with setUserDefault.
systemPreferences.isAeroGlassEnabled() WindowsReturns Boolean - true if DWM composition (Aero Glass) is enabled, and false otherwise.
An example of using it to determine if you should create a transparent window or not (transparent windows won't work correctly when DWM composition is disabled):
\nconst { BrowserWindow, systemPreferences } = require('electron')\nconst browserOptions = { width: 1000, height: 800 }\n\n// Make the window transparent only if the platform supports it.\nif (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {\n browserOptions.transparent = true\n browserOptions.frame = false\n}\n\n// Create the window.\nconst win = new BrowserWindow(browserOptions)\n\n// Navigate.\nif (browserOptions.transparent) {\n win.loadURL(`file://${__dirname}/index.html`)\n} else {\n // Без прозрачности, значит мы загружаем резерв, использующий базовые стили.\n win.loadURL(`file://${__dirname}/fallback.html`) \n}\nsystemPreferences.getAccentColor() Windows macOSReturns String - The users current system wide accent color preference in RGBA hexadecimal form.
const color = systemPreferences.getAccentColor() // `\"aabbccdd\"` \nconst red = color.substr(0, 2) // \"aa\" \nconst green = color.substr(2, 2) // \"bb\" \nconst blue = color.substr(4, 2) // \"cc\" \nconst alpha = color.substr(6, 2) // \"dd\"\nThis API is only available on macOS 10.14 Mojave or newer.
\nsystemPreferences.getColor(color) Windows macOScolor String - One of the following values:3d-dark-shadow - Dark shadow for three-dimensional display elements.3d-face - Face color for three-dimensional display elements and for dialog box backgrounds.3d-highlight - Highlight color for three-dimensional display elements.3d-light - Light color for three-dimensional display elements.3d-shadow - Shadow color for three-dimensional display elements.active-border - Active window border.active-caption - Active window title bar. Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.active-caption-gradient - Right side color in the color gradient of an active window's title bar.app-workspace - Background color of multiple document interface (MDI) applications.button-text - Text on push buttons.caption-text - Text in caption, size box, and scroll bar arrow box.desktop - Desktop background color.disabled-text - Grayed (disabled) text.highlight - Item(s) selected in a control.highlight-text - Text of item(s) selected in a control.hotlight - Color for a hyperlink or hot-tracked item.inactive-border - Inactive window border.inactive-caption - Inactive window caption. Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.inactive-caption-gradient - Right side color in the color gradient of an inactive window's title bar.inactive-caption-text - Color of text in an inactive caption.info-background - Background color for tooltip controls.info-text - Text color for tooltip controls.menu - Menu background.menu-highlight - The color used to highlight menu items when the menu appears as a flat menu.menubar - The background color for the menu bar when menus appear as flat menus.menu-text - Text in menus.scrollbar - Scroll bar gray area.window - Window background.window-frame - Window frame.window-text - Text in windows.alternate-selected-control-text - The text on a selected surface in a list or table. deprecatedcontrol-background - The background of a large interface element, such as a browser or table.control - The surface of a control.control-text -The text of a control that isn’t disabled.disabled-control-text - The text of a control that’s disabled.find-highlight - The color of a find indicator.grid - The gridlines of an interface element such as a table.header-text - The text of a header cell in a table.highlight - The virtual light source onscreen.keyboard-focus-indicator - The ring that appears around the currently focused control when using the keyboard for interface navigation.label - The text of a label containing primary content.link - A link to other content.placeholder-text - A placeholder string in a control or text view.quaternary-label - The text of a label of lesser importance than a tertiary label such as watermark text.scrubber-textured-background - The background of a scrubber in the Touch Bar.secondary-label - The text of a label of lesser importance than a normal label such as a label used to represent a subheading or additional information.selected-content-background - The background for selected content in a key window or view.selected-control - The surface of a selected control.selected-control-text - The text of a selected control.selected-menu-item-text - The text of a selected menu.selected-text-background - The background of selected text.selected-text - Selected text.separator - A separator between different sections of content.shadow - The virtual shadow cast by a raised object onscreen.tertiary-label - The text of a label of lesser importance than a secondary label such as a label used to represent disabled text.text-background - Text background.text - The text in a document.under-page-background - The background behind a document's content.unemphasized-selected-content-background - The selected content in a non-key window or view.unemphasized-selected-text-background - A background for selected text in a non-key window or view.unemphasized-selected-text - Selected text in a non-key window or view.window-background - The background of a window.window-frame-text - The text in the window's titlebar area.Returns String - The system color setting in RGB hexadecimal form (#ABCDEF). See the Windows docs and the macOS docs for more details.
The following colors are only available on macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, and unemphasized-selected-text.
systemPreferences.getSystemColor(color) macOScolor String - One of the following values:bluebrowngraygreenorangepinkpurpleredyellowReturns String - The standard system color formatted as #RRGGBBAA.
Returns one of several standard system colors that automatically adapt to vibrancy and changes in accessibility settings like 'Increase contrast' and 'Reduce transparency'. See Apple Documentation for more details.
\nsystemPreferences.isInvertedColorScheme() Windows DeprecatedReturns Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is active, false otherwise.
Deprecated: Should use the new nativeTheme.shouldUseInvertedColorScheme API.
systemPreferences.isHighContrastColorScheme() macOS Windows DeprecatedReturns Boolean - true if a high contrast theme is active, false otherwise.
Deprecated: Should use the new nativeTheme.shouldUseHighContrastColors API.
systemPreferences.getEffectiveAppearance() macOSReturns String - Can be dark, light or unknown.
Gets the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance
\nsystemPreferences.getAppLevelAppearance() macOS DeprecatedReturns String | null - Can be dark, light or unknown.
Gets the macOS appearance setting that you have declared you want for your application, maps to NSApplication.appearance. You can use the setAppLevelAppearance API to set this value.
systemPreferences.setAppLevelAppearance(appearance) macOS Deprecatedappearance String | null - Can be dark or lightSets the appearance setting for your application, this should override the system default and override the value of getEffectiveAppearance.
systemPreferences.canPromptTouchID() macOSReturns Boolean - whether or not this device has the ability to use Touch ID.
NOTE: This API will return false on macOS systems older than Sierra 10.12.2.
systemPreferences.promptTouchID(reason) macOSreason String - The reason you are asking for Touch ID authenticationReturns Promise<void> - resolves if the user has successfully authenticated with Touch ID.
const { systemPreferences } = require('electron')\n\nsystemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {\n console.log('You have successfully authenticated with Touch ID!')\n}).catch(err => {\n console.log(err)\n})\nThis API itself will not protect your user data; rather, it is a mechanism to allow you to do so. Native apps will need to set Access Control Constants like kSecAccessControlUserPresence on their keychain entry so that reading it would auto-prompt for Touch ID biometric consent. This could be done with node-keytar, such that one would store an encryption key with node-keytar and only fetch it if promptTouchID() resolves.
NOTE: This API will return a rejected Promise on macOS systems older than Sierra 10.12.2.
\nsystemPreferences.isTrustedAccessibilityClient(prompt) macOSprompt Boolean - whether or not the user will be informed via prompt if the current process is untrusted.Returns Boolean - true if the current process is a trusted accessibility client and false if it is not.
systemPreferences.getMediaAccessStatus(mediaType) Windows macOSmediaType String - может быть завершено microphone, отменено camera или прервано screen.Returns String - Can be not-determined, granted, denied, restricted or unknown.
This user consent was not required on macOS 10.13 High Sierra or lower so this method will always return granted. macOS 10.14 Mojave or higher requires consent for microphone and camera access. macOS 10.15 Catalina or higher requires consent for screen access.
Windows 10 has a global setting controlling microphone and camera access for all win32 applications. It will always return granted for screen and for all media types on older versions of Windows.
systemPreferences.askForMediaAccess(mediaType) macOSmediaType String - the type of media being requested; can be microphone, camera.Returns Promise<Boolean> - A promise that resolves with true if consent was granted and false if it was denied. If an invalid mediaType is passed, the promise will be rejected. If an access request was denied and later is changed through the System Preferences pane, a restart of the app will be required for the new permissions to take effect. If access has already been requested and denied, it must be changed through the preference pane; an alert will not pop up and the promise will resolve with the existing access status.
Important: In order to properly leverage this API, you must set the NSMicrophoneUsageDescription and NSCameraUsageDescription strings in your app's Info.plist file. The values for these keys will be used to populate the permission dialogs so that the user will be properly informed as to the purpose of the permission request. See Electron Application Distribution for more information about how to set these in the context of Electron.
This user consent was not required until macOS 10.14 Mojave, so this method will always return true if your system is running 10.13 High Sierra or lower.
systemPreferences.getAnimationSettings()Возвращает Object:
shouldRenderRichAnimation Boolean - Returns true if rich animations should be rendered. Looks at session type (e.g. remote desktop) and accessibility settings to give guidance for heavy animations.scrollAnimationsEnabledBySystem Boolean - Determines on a per-platform basis whether scroll animations (e.g. produced by home/end key) should be enabled.prefersReducedMotion Boolean - Determines whether the user desires reduced motion based on platform APIs.Returns an object with system animation settings.
\nsystemPreferences.appLevelAppearance macOSСвойство String может быть dark, light или unknown. It determines the macOS appearance setting for your application. This maps to values in: NSApplication.appearance. Setting this will override the system default as well as the value of getEffectiveAppearance.
Possible values that can be set are dark and light, and possible return values are dark, light, and unknown.
This property is only available on macOS 10.14 Mojave or newer.
\nsystemPreferences.effectiveAppearance macOS ReadonlyСвойство String может быть dark, light или unknown.
Returns the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance
", "title": "systemPreferences", "description": "Получение системных параметров." }, "/docs/api/structures/task": { "locale": "ru-RU", "slug": "task", "href": "/docs/api/structures/task", "crowdinFileId": "256513", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/task.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "program String - Path of the program to execute, usually you should specify process.execPath which opens the current program.arguments String - The command line arguments when program is executed.title String - The string to be displayed in a JumpList.description String - Description of this task.iconPath String - The absolute path to an icon to be displayed in a JumpList, which can be an arbitrary resource file that contains an icon. You can usually specify process.execPath to show the icon of the program.iconIndex Number - The icon index in the icon file. If an icon file consists of two or more icons, set this value to identify the icon. If an icon file consists of one icon, this value is 0.workingDirectory String (optional) - The working directory. Default is empty.Мы стремимся сохранить кодовое покрытие Electron высоким. We ask that all pull request not only pass all existing tests, but ideally also add new tests to cover changed code and new scenarios. https://crowdin.com/translate/electron/159/en-ru#13105.
\nThis repository comes with linting rules for both JavaScript and C++ – as well as unit and integration tests. To learn more about Electron's coding style, please see the coding-style document.
\nTo ensure that your JavaScript is in compliance with the Electron coding style, run npm run lint-js, which will run standard against both Electron itself as well as the unit tests. If you are using an editor with a plugin/addon system, you might want to use one of the many StandardJS addons to be informed of coding style violations before you ever commit them.
To run standard with parameters, run npm run lint-js -- followed by arguments you want passed to standard.
To ensure that your C++ is in compliance with the Electron coding style, run npm run lint-cpp, which runs a cpplint script. We recommend that you use clang-format and prepared a short tutorial.
There is not a lot of Python in this repository, but it too is governed by coding style rules. npm run lint-py will check all Python, using pylint to do so.
If you are not using build-tools, ensure that that name you have configured for your local build of Electron is one of Testing, Release, Default, Debug, or you have set process.env.ELECTRON_OUT_DIR. Without these set, Electron will fail to perform some pre-testing steps.
To run all unit tests, run npm run test. The unit tests are an Electron app (surprise!) that can be found in the spec folder. Note that it has its own package.json and that its dependencies are therefore not defined in the top-level package.json.
To run only specific tests matching a pattern, run npm run test -- -g=PATTERN, replacing the PATTERN with a regex that matches the tests you would like to run. As an example: If you want to run only IPC tests, you would run npm run test -- -g ipc.
Visual Studio 2019 must be installed.
\nNode headers have to be compiled for your configuration.
\nninja -C out\\Testing third_party\\electron_node:headers\nThe electron.lib has to be copied as node.lib.
\ncd out\\Testing\nmkdir gen\\node_headers\\Release\ncopy electron.lib gen\\node_headers\\Release\\node.lib\nНа некоторых устройства на Windows 10 может быть не установлен шрифт Meriyo, что может привести к провалу fallback теста. Для того чтобы установить шрифт Meiryo:
\nSome tests which rely on precise pixel measurements may not work correctly on devices with Hi-DPI screen settings due to floating point precision errors. To run these tests correctly, make sure the device is set to 100% scaling.
\nTo configure display scaling:
\nBeing based on Chromium, Electron requires a display driver to function. If Chromium can't find a display driver, Electron will fail to launch - and therefore not executing any of your tests, regardless of how you are running them. Testing Electron-based apps on Travis, Circle, Jenkins or similar Systems requires therefore a little bit of configuration. In essence, we need to use a virtual display driver.
\nFirst, install Xvfb. It's a virtual framebuffer, implementing the X11 display server protocol - it performs all graphical operations in memory without showing any screen output, which is exactly what we need.
\nЗатем создайте виртуальный экран Xvfb и экспортируйте переменную окружения, называемую DISPLAY, которая указывает на него. Chromium in Electron will automatically look for $DISPLAY, so no further configuration of your app is required. This step can be automated with Anaïs Betts' xvfb-maybe: Prepend your test commands with xvfb-maybe and the little tool will automatically configure Xvfb, if required by the current system. On Windows or macOS, it will do nothing.
## On Windows or macOS, this invokes electron-mocha\n## On Linux, if we are in a headless environment, this will be equivalent\n## to xvfb-run electron-mocha ./test/*.js\nxvfb-maybe electron-mocha ./test/*.js\nДля Travis, ваш .travis.yml должен выглядеть примерно так:
addons:\n apt:\n packages:\n - xvfb\n\ninstall:\n - export DISPLAY=':99.0'\n - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &\nДля Jenkins доступен плагин Xvfb.
\nCircle CI замечательный, так что xvfb и $DISPLAY уже установлены, и дополнительной настройки не требуется.
AppVeyor работает под Windows, поддерживает Selenium, Chromium, Electron и другие подобные инструменты \"из коробки\" - настройка не требуется.
", "title": "Тестирование с помощью систем непрерывной интеграции (Travis, Jenkins)", "description": "" }, "/docs/tutorial/testing-widevine-cdm": { "locale": "ru-RU", "slug": "testing-widevine-cdm", "href": "/docs/tutorial/testing-widevine-cdm", "crowdinFileId": "256257", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/testing-widevine-cdm.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "In Electron you can use the Widevine CDM library shipped with Chrome browser.
\nWidevine Content Decryption Modules (CDMs) are how streaming services protect content using HTML5 video to web browsers without relying on an NPAPI plugin like Flash or Silverlight. Widevine support is an alternative solution for streaming services that currently rely on Silverlight for playback of DRM-protected video content. It will allow websites to show DRM-protected video content in Firefox without the use of NPAPI plugins. The Widevine CDM runs in an open-source CDM sandbox providing better user security than NPAPI plugins.
\nAs of Electron v1.8.0 (Chrome v59), the below steps are may only be some of the necessary steps to enable Widevine; any app on or after that version intending to use the Widevine CDM may need to be signed using a license obtained from Widevine itself.
Per Widevine:
\n\n\nChrome 59 (and later) includes support for Verified Media Path (VMP). VMP provides a method to verify the authenticity of a device platform. For browser deployments, this will provide an additional signal to determine if a browser-based implementation is reliable and secure.
\nThe proxy integration guide has been updated with information about VMP and how to issue licenses.
\nWidevine recommends our browser-based integrations (vendors and browser-based applications) add support for VMP.
\n
To enable video playback with this new restriction, castLabs has created a fork that has implemented the necessary changes to enable Widevine to be played in an Electron application if one has obtained the necessary licenses from widevine.
\nOpen chrome://components/ in Chrome browser, find Widevine Content Decryption Module and make sure it is up to date, then you can find the library files from the application directory.
The library file widevinecdm.dll will be under Program Files(x86)/Google/Chrome/Application/CHROME_VERSION/WidevineCdm/_platform_specific/win_(x86|x64)/ directory.
The library file libwidevinecdm.dylib will be under /Applications/Google Chrome.app/Contents/Versions/CHROME_VERSION/Google Chrome Framework.framework/Versions/A/Libraries/WidevineCdm/_platform_specific/mac_(x86|x64)/ directory.
Note: Make sure that chrome version used by Electron is greater than or equal to the min_chrome_version value of Chrome's widevine cdm component. The value can be found in manifest.json under WidevineCdm directory.
After getting the library files, you should pass the path to the file with --widevine-cdm-path command line switch, and the library's version with --widevine-cdm-version switch. The command line switches have to be passed before the ready event of app module gets emitted.
const { app, BrowserWindow } = require('electron')\n\n// You have to pass the directory that contains widevine library here, it is\n// * `libwidevinecdm.dylib` on macOS,\n// * `widevinecdm.dll` on Windows.\napp.commandLine.appendSwitch('widevine-cdm-path', '/path/to/widevine_library')\n// The version of plugin can be got from `chrome://components` page in Chrome.\n\n8r\nooo6\nTo verify whether widevine works, you can use following ways:
\nWidevine.bitdash uses Widevine in your browser, then play the video.icon NativeImage - The icon showing in thumbnail toolbar.click Functiontooltip String (optional) - The text of the button's tooltip.flags String - Control specific states and behaviors of the button. By default, it is ['enabled'].The flags is an array that can include following Strings:
enabled - The button is active and available to the user.disabled - The button is disabled. It is present, but has a visual state indicating it will not respond to user action.dismissonclick - When the button is clicked, the thumbnail window closes immediately.nobackground - Do not draw a button border, use only the image.hidden - The button is not shown to the user.noninteractive - The button is enabled but not interactive; no pressed button state is drawn. This value is intended for instances where the button is used in a notification.\n\nCreate TouchBar layouts for native macOS applications
\n
Процесс: Основной
\nnew TouchBar(options)options Objectitems (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer)escapeItem (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer | null) (optional)Creates a new touch bar with the specified items. Use BrowserWindow.setTouchBar to add the TouchBar to a window.
Примечание: TouchBar API в настоящее время является экспериментальным и может быть изменен или удален в будущих версиях Electron.
\nTip: If you don't have a MacBook with Touch Bar, you can use Touch Bar Simulator to test Touch Bar usage in your app.
\nTouchBarButtonA typeof TouchBarButton reference to the TouchBarButton class.
TouchBarColorPickerA typeof TouchBarColorPicker reference to the TouchBarColorPicker class.
TouchBarGroupA typeof TouchBarGroup reference to the TouchBarGroup class.
TouchBarLabelA typeof TouchBarLabel reference to the TouchBarLabel class.
TouchBarPopoverA typeof TouchBarPopover reference to the TouchBarPopover class.
TouchBarScrubberA typeof TouchBarScrubber reference to the TouchBarScrubber class.
TouchBarSegmentedControlA typeof TouchBarSegmentedControl reference to the TouchBarSegmentedControl class.
TouchBarSliderA typeof TouchBarSlider reference to the TouchBarSlider class.
TouchBarSpacerA typeof TouchBarSpacer reference to the TouchBarSpacer class.
TouchBarOtherItemsProxyA typeof TouchBarOtherItemsProxy reference to the TouchBarOtherItemsProxy class.
The following properties are available on instances of TouchBar:
touchBar.escapeItemA TouchBarItem that will replace the \"esc\" button on the touch bar when set. Setting to null restores the default \"esc\" button. Changing this value immediately updates the escape item in the touch bar.
Below is an example of a simple slot machine touch bar game with a button and some labels.
\nconst { app, BrowserWindow, TouchBar } = require('electron')\n\nconst { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar\n\nlet spinning = false\n\n// Reel labels\nconst reel1 = new TouchBarLabel()\nconst reel2 = new TouchBarLabel()\nconst reel3 = new TouchBarLabel()\n\n// Spin result label\nconst result = new TouchBarLabel()\n\n// Spin button\nconst spin = new TouchBarButton({\n label: '🎰 Spin',\n backgroundColor: '#7851A9',\n click: () => {\n // Ignore clicks if already spinning\n if (spinning) {\n return\n }\n\n spinning = true\n result.label = ''\n\n let timeout = 10\n const spinLength = 4 * 1000 // 4 seconds\n const startTime = Date.now()\n\n const spinReels = () => {\n updateReels()\n\n if ((Date.now() - startTime) >= spinLength) {\n finishSpin()\n } else {\n // Slow down a bit on each spin\n timeout *= 1.1\n setTimeout(spinReels, timeout)\n }\n }\n\n spinReels()\n }\n})\n\nconst getRandomValue = () => {\n const values = ['🍒', '💎', '7️⃣', '🍊', '🔔', '⭐', '🍇', '🍀']\n return values[Math.floor(Math.random() * values.length)]\n}\n\nconst updateReels = () => {\n reel1.label = getRandomValue()\n reel2.label = getRandomValue()\n reel3.label = getRandomValue()\n}\n\nconst finishSpin = () => {\n const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size\n if (uniqueValues === 1) {\n // All 3 values are the same\n result.label = '💰 Jackpot!'\n result.textColor = '#FDFF00'\n } else if (uniqueValues === 2) {\n // 2 values are the same\n result.label = '😍 Winner!'\n result.textColor = '#FDFF00'\n } else {\n // No values are the same\n result.label = '🙁 Spin Again'\n result.textColor = null\n }\n spinning = false\n}\n\nconst touchBar = new TouchBar({\n items: [\n spin,\n new TouchBarSpacer({ size: 'large' }),\n reel1,\n new TouchBarSpacer({ size: 'small' }),\n reel2,\n new TouchBarSpacer({ size: 'small' }),\n reel3,\n new TouchBarSpacer({ size: 'large' }),\n result\n ]\n})\n\nlet window\n\napp.whenReady().then(() => {\n window = new BrowserWindow({\n frame: false,\n titleBarStyle: 'hiddenInset',\n width: 200,\n height: 200,\n backgroundColor: '#000'\n })\n window.loadURL('about:blank')\n window.setTouchBar(touchBar)\n})\nTo run the example above, you'll need to (assuming you've got a terminal open in the directory you want to run the example):
\ntouchbar.jsnpm install electron./node_modules/.bin/electron touchbar.jsYou should then see a new Electron window and the app running in your touch bar (or touch bar emulator).
", "title": "TouchBar", "description": "Create TouchBar layouts for native macOS applications" }, "/docs/api/touch-bar-button": { "locale": "ru-RU", "slug": "touch-bar-button", "href": "/docs/api/touch-bar-button", "crowdinFileId": "256375", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/touch-bar-button.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nСоздает кнопку в сенсорной панели для нативных приложений macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarButton(options)options Objectlabel String (необязаельный) - Текст кнопки.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.backgroundColor String (необязательный) - Цвет фона кнопки в шестнадцатиричном представлении, т.е. #ABCDEF.icon NativeImage | String (optional) - Button icon.iconPosition String (необязательный) - Позиция иконки, может иметь значения left, right или overlay. По умолчанию - overlay.click Function (необязательный) - Функция которая будет вызвана при нажатии на кнопку.enabled Boolean (optional) - Whether the button is in an enabled state. По умолчанию - true.When defining accessibilityLabel, ensure you have considered macOS best practices.
Для экземпляров TouchBarButton доступны следующие свойства:
touchBarButton.accessibilityLabelA String representing the description of the button to be read by a screen reader. Will only be read by screen readers if no label is set.
touchBarButton.labelСтрока (String) представляющая текущий текст кнопки. Изменение этого значения немедленно обновляет кнопку в сенсорной панели.
touchBarButton.backgroundColorСтрока (String) представляющая текущий цвет кнопки в шестнадцатиричном формате. Изменение этого значения немедленно обновляет кнопку в сенсорной панели.
touchBarButton.iconNativeImage, представляющее текущую иконку кнопки. Изменение этого значения немедленно обновляет кнопку в сенсорной панели.
touchBarButton.iconPositionA String - Can be left, right or overlay. По умолчанию - overlay.
touchBarButton.enabledA Boolean representing whether the button is in an enabled state.
\n\nCreate a color picker in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarColorPicker(options)options ObjectavailableColors String - Array of hex color strings to appear as possible colors to select.selectedColor String (optional) - The selected hex color in the picker, i.e #ABCDEF.change Function (optional) - Function to call when a color is selected.color String - The color that the user selected from the picker.Для экземпляров TouchBarColorPicker доступны следующие свойства:
touchBarColorPicker.availableColorsA String[] array representing the color picker's available colors to select. Changing this value immediately updates the color picker in the touch bar.
touchBarColorPicker.selectedColorA String hex code representing the color picker's currently selected color. Changing this value immediately updates the color picker in the touch bar.
\n\nCreate a group in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarGroup(options)options Objectitems TouchBar - Items to display as a group.\n\nСоздает метку на тач-панели, для найтивного macOS-приложения
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarLabel(options)options Objectlabel String (optional) - Text to display.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.textColor String (optional) - Hex color of text, i.e #ABCDEF.When defining accessibilityLabel, ensure you have considered macOS best practices.
Для экземпляров TouchBarLabel доступны следующие свойства:
touchBarLabel.labelA String representing the label's current text. Changing this value immediately updates the label in the touch bar.
touchBarLabel.accessibilityLabelA String representing the description of the label to be read by a screen reader.
touchBarLabel.textColorA String hex code representing the label's current text color. Changing this value immediately updates the label in the touch bar.
\n\nInstantiates a special \"other items proxy\", which nests TouchBar elements inherited from Chromium at the space indicated by the proxy. By default, this proxy is added to each TouchBar at the end of the input. For more information, see the AppKit docs on NSTouchBarItemIdentifierOtherItemsProxy
\nNote: Only one instance of this class can be added per TouchBar.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarOtherItemsProxy()\n\nCreate a popover in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarPopover(options)options Objectlabel String (optional) - Popover button text.icon NativeImage (optional) - Popover button icon.items TouchBar - Items to display in the popover.showCloseButton Boolean (optional) - true to display a close button on the left of the popover, false to not show it. По умолчанию - true.Для экземпляров TouchBarPopover доступны следующие свойства:
touchBarPopover.labelA String representing the popover's current button text. Changing this value immediately updates the popover in the touch bar.
touchBarPopover.iconA NativeImage representing the popover's current button icon. Changing this value immediately updates the popover in the touch bar.
\n\nCreate a scrubber (a scrollable selector)
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarScrubber(options)options Objectitems ScrubberItem[] - An array of items to place in this scrubber.select Function (optional) - Called when the user taps an item that was not the last tapped item.selectedIndex Integer - The index of the item the user selected.highlight Function (optional) - Called when the user taps any item.highlightedIndex Integer - The index of the item the user touched.selectedStyle String (optional) - Selected item style. Can be background, outline or none. Defaults to none.overlayStyle String (optional) - Selected overlay item style. Can be background, outline or none. Defaults to none.showArrowButtons Boolean (опционально) - если нужно показать кнопки со стрелками. По умолчанию false и показывается только если элемент присутствует.mode String (опционально) - Может быть fixed или free. The default is free.continuous Boolean (опиционально) - по умолчанию true.The following properties are available on instances of TouchBarScrubber:
touchBarScrubber.itemsA ScrubberItem[] array representing the items in this scrubber. Updating this value immediately updates the control in the touch bar. Updating deep properties inside this array does not update the touch bar.
touchBarScrubber.selectedStyleA String representing the style that selected items in the scrubber should have. Updating this value immediately updates the control in the touch bar. Возможные значения:
background - Maps to [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Maps to [NSScrubberSelectionStyle outlineOverlayStyle].none - Removes all styles.touchBarScrubber.overlayStyleA String representing the style that selected items in the scrubber should have. This style is overlayed on top of the scrubber item instead of being placed behind it. Updating this value immediately updates the control in the touch bar. Возможные значения:
background - Maps to [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Maps to [NSScrubberSelectionStyle outlineOverlayStyle].none - Removes all styles.touchBarScrubber.showArrowButtonsA Boolean representing whether to show the left / right selection arrows in this scrubber. Updating this value immediately updates the control in the touch bar.
touchBarScrubber.modeA String representing the mode of this scrubber. Updating this value immediately updates the control in the touch bar. Возможные значения:
fixed - Maps to NSScrubberModeFixed.free - Maps to NSScrubberModeFree.touchBarScrubber.continuousA Boolean representing whether this scrubber is continuous or not. Updating this value immediately updates the control in the touch bar.
\n\nCreate a segmented control (a button group) where one button has a selected state
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSegmentedControl(options)options ObjectsegmentStyle String (optional) - Style of the segments:automatic - Default. The appearance of the segmented control is automatically determined based on the type of window in which the control is displayed and the position within the window. Maps to NSSegmentStyleAutomatic.rounded - The control is displayed using the rounded style. Maps to NSSegmentStyleRounded.textured-rounded - The control is displayed using the textured rounded style. Maps to NSSegmentStyleTexturedRounded.round-rect - The control is displayed using the round rect style. Maps to NSSegmentStyleRoundRect.textured-square - The control is displayed using the textured square style. Maps to NSSegmentStyleTexturedSquare.capsule - The control is displayed using the capsule style. Maps to NSSegmentStyleCapsule.small-square - The control is displayed using the small square style. Maps to NSSegmentStyleSmallSquare.separated - The segments in the control are displayed very close to each other but not touching. Maps to NSSegmentStyleSeparated.mode String (optional) - The selection mode of the control:single - Default. One item selected at a time, selecting one deselects the previously selected item. Maps to NSSegmentSwitchTrackingSelectOne.multiple - Multiple items can be selected at a time. Maps to NSSegmentSwitchTrackingSelectAny.buttons - Make the segments act as buttons, each segment can be pressed and released but never marked as active. Maps to NSSegmentSwitchTrackingMomentary.segments SegmentedControlSegment[] - An array of segments to place in this control.selectedIndex Integer (optional) - The index of the currently selected segment, will update automatically with user interaction. When the mode is multiple it will be the last selected item.change Function (optional) - Called when the user selects a new segment.selectedIndex Integer - The index of the segment the user selected.isSelected Boolean - Whether as a result of user selection the segment is selected or not.Для экземпляров TouchBarSegmentedControl доступны следующие свойства:
touchBarSegmentedControl.segmentStyleA String representing the controls current segment style. Updating this value immediately updates the control in the touch bar.
touchBarSegmentedControl.segmentsA SegmentedControlSegment[] array representing the segments in this control. Updating this value immediately updates the control in the touch bar. Updating deep properties inside this array does not update the touch bar.
touchBarSegmentedControl.selectedIndexAn Integer representing the currently selected segment. Changing this value immediately updates the control in the touch bar. User interaction with the touch bar will update this value automatically.
touchBarSegmentedControl.modeA String representing the current selection mode of the control. Can be single, multiple or buttons.
\n\nCreate a slider in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSlider(options)options Objectlabel String (optional) - Label text.value Integer (optional) - Selected value.minValue Integer (optional) - Minimum value.maxValue Integer (optional) - Maximum value.change Function (optional) - Function to call when the slider is changed.newValue Number - The value that the user selected on the Slider.Для экземпляров TouchBarSlider доступны следующие свойства:
touchBarSlider.labelA String representing the slider's current text. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.valueA Number representing the slider's current value. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.minValueA Number representing the slider's current minimum value. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.maxValueA Number representing the slider's current maximum value. Changing this value immediately updates the slider in the touch bar.
\n\nСоздает разделитель между двумя элементами в сенсорной панели для нативных приложений macOS
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSpacer(options)options Objectsize String (optional) - Size of spacer, possible values are:small - Небольшое пространство между элементами. Maps to NSTouchBarItemIdentifierFixedSpaceSmall. This is the default.large - Большое пространство между элементами. Maps to NSTouchBarItemIdentifierFixedSpaceLarge.flexible - Занимает всё доступное пространство. Maps to NSTouchBarItemIdentifierFlexibleSpace.The following properties are available on instances of TouchBarSpacer:
touchBarSpacer.sizeA String representing the size of the spacer. Can be small, large or flexible.
categoryFilter String - A filter to control what category groups should be traced. A filter can have an optional '-' prefix to exclude category groups that contain a matching category. Having both included and excluded category patterns in the same list is not supported. Examples: test_MyTest*, test_MyTest*,test_OtherStuff, -excluded_category1,-excluded_category2.traceOptions String - Controls what kind of tracing is enabled, it is a comma-delimited sequence of the following strings: record-until-full, record-continuously, trace-to-console, enable-sampling, enable-systrace, e.g. 'record-until-full,enable-sampling'. The first 3 options are trace recording modes and hence mutually exclusive. If more than one trace recording modes appear in the traceOptions string, the last one takes precedence. If none of the trace recording modes are specified, recording mode is record-until-full. The trace option will first be reset to the default option (record_mode set to record-until-full, enable_sampling and enable_systrace set to false) before options parsed from traceOptions are applied on it.recording_mode String (optional) - Can be record-until-full, record-continuously, record-as-much-as-possible or trace-to-console. Defaults to record-until-full.trace_buffer_size_in_kb number (optional) - maximum size of the trace recording buffer in kilobytes. Defaults to 100MB.trace_buffer_size_in_events number (optional) - maximum size of the trace recording buffer in events.enable_argument_filter boolean (optional) - if true, filter event data according to a specific list of events that have been manually vetted to not include any PII. See the implementation in Chromium for specifics.included_categories String - a list of tracing categories to include. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.excluded_categories String - a list of tracing categories to exclude. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.included_process_ids number - a list of process IDs to include in the trace. If not specified, trace all processes.histogram_names String - a list of histogram names to report with the trace.memory_dump_config Record<String, any> (optional) - if the disabled-by-default-memory-infra category is enabled, this contains optional additional configuration for data collection. See the Chromium memory-infra docs for more information.An example TraceConfig that roughly matches what Chrome DevTools records:
\n{\n recording_mode: 'record-until-full',\n included_categories: [\n 'devtools.timeline',\n 'disabled-by-default-devtools.timeline',\n 'disabled-by-default-devtools.timeline.frame',\n 'disabled-by-default-devtools.timeline.stack',\n 'v8.execute',\n 'blink.console',\n 'blink.user_timing',\n 'latencyInfo',\n 'disabled-by-default-v8.cpu_profiler',\n 'disabled-by-default-v8.cpu_profiler.hires'\n ],\n excluded_categories: ['*']\n}\ntransactionIdentifier String - A string that uniquely identifies a successful payment transaction.transactionDate String - The date the transaction was added to the App Store’s payment queue.originalTransactionIdentifier String - The identifier of the restored transaction by the App Store.transactionState String - The transaction state, can be purchasing, purchased, failed, restored or deferred.errorCode Integer - The error code if an error occurred while processing the transaction.errorMessage String - The error message if an error occurred while processing the transaction.payment ObjectproductIdentifier String - The identifier of the purchased product.quantity Integer - The quantity purchased.\n\nДобавить иконки и контекстные меню в системную область уведомлений.
\n
Процесс: Основной
\nTray является EventEmitter'ом.
const { app, Menu, Tray } = require('electron')\n\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n ])\n tray.setToolTip('This is my application.')\n tray.setContextMenu(contextMenu)\n})\nОграничения платформ:
\nGtkStatusIcon.libappindicator1, чтобы значок в трее заработал.click игнорируется.MenuItems to take effect, you have to call setContextMenu again. Например:const { app, Menu, Tray } = require('electron')\n\nlet appIcon = null\napp.whenReady().then(() => {\n appIcon = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' }\n ])\n\n // Make a change to the context menu\n contextMenu.items[1].checked = false\n\n // Call this again for Linux because we modified the context menu\n appIcon.setContextMenu(contextMenu)\n})\nICO для получения лучших визуальных эффектов.Если вы хотите сохранить одинаковое поведение на всех платформах, вам не следует полагаться на событие click и всегда прикреплять контекстное меню к значку в трее.
new Tray(image, [guid])image (NativeImage | String)guid String (optional) Windows - Assigns a GUID to the tray icon. If the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. OS level settings like the position of the tray icon in the system tray will persist even if the path to the executable changes. If the executable is not code-signed then the GUID is permanently associated with the path to the executable. Changing the path to the executable will break the creation of the tray icon and a new GUID must be used. However, it is highly recommended to use the GUID parameter only in conjunction with code-signed executable. If an App defines multiple tray icons then each icon must use a separate GUID.Создаёт новую иконку в трее, связанную с image.
Модуль Tray генерирует следующие события:
Возвращает:
\nevent KeyboardEventbounds Rectangle - границы иконки в трее.position Point - позиция события.Вызывается при двойном клике на иконке в трее.
\nВозвращает:
\nevent KeyboardEventbounds Rectangle - границы иконки в трее.Возникает при правом клике на иконке в трее.
\nВозвращает:
\nevent KeyboardEventbounds Rectangle - границы иконки в трее.Вызывается при двойном нажатии на иконку в трее.
\nВозникает при всплывающем сообщении в трее.
\nВызывается при клике на всплывающем сообщении в трее.
\nВозникает, когда всплывающее сообщение в трее закрыто из-за тайм-аута или вручную пользователем.
\nВозникает при перетаскивании элементов на значок в трее.
\nВозвращает:
\neventfiles String[] - пути брошенных файлов.Возникает при перетаскивании файлов на значок в трее.
\nВозвращает:
\neventtext String - брошенная текстовая строка.Возникает при перетаскивании строки на значок в трее.
\nВозникает, когда операция перетаскивания происходит на иконке в трее.
\nВозникает, когда операция перетаскивания завершилась на иконке в трее.
\nВозникает, когда операция перетаскивания заканчивается в трее или заканчивается в другом месте.
\nВозвращает:
\nevent KeyboardEventposition Point - позиция события.Emitted when the mouse is released from clicking the tray icon.
\nNote: This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.
Возвращает:
\nevent KeyboardEventposition Point - позиция события.Emitted when the mouse clicks the tray icon.
\nВозвращает:
\nevent KeyboardEventposition Point - позиция события.Возникает при входе курсора мыши на иконку в трее.
\nВозвращает:
\nevent KeyboardEventposition Point - позиция события.Возникает при выходе курсора мыши с иконки в трее.
\nВозвращает:
\nevent KeyboardEventposition Point - позиция события.Возникает при перемещении мыши на значке в трее.
\nКласс Tray имеет следующие методы:
tray.destroy()Немедленно уничтожить иконку в трее.
\ntray.setImage(image)image (NativeImage | String)Устанавливает image ассоциированный с значком в трее.
tray.setPressedImage(image) macOSimage (NativeImage | String)Устанавливает image, связанное с этим значком в трее, при нажатии в macOS.
tray.setToolTip(toolTip)toolTip StringУстанавливает текст отображаемый при наведении на значок в трее.
\ntray.setTitle(title[, options]) macOStitle Stringoptions Object (опционально)fontType String (опционально) - Вариант семейства шрифтов для отображения, может быть моноширинным или цифро-моноширинным. monospaced is available in macOS 10.15+ and monospacedDigit is available in macOS 10.11+. По умолчанию используют системный шрифт по умолчанию.Устанавливает заголовок, отображаемый рядом со значком в строке состояния (поддержка ANSI цветов).
\ntray.getTitle() macOSВозвращает String - заголовок, отображаемый рядом со значком в области уведомлений в строке состояния
tray.setIgnoreDoubleClickEvents(ignore) macOSignore Логическое значениеSets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.
\nЗначение по умолчанию установлено в значение false.
\ntray.getIgnoreDoubleClickEvents() macOSВозвращает Boolean - будет ли игнорироваться события двойного щелчка.
tray.displayBalloon(options) Windowsoptions Objecticon (NativeImage | String) (optional) - Icon to use when iconType is custom.iconType String (optional) - Can be none, info, warning, error or custom. По умолчанию - custom.title Stringcontent StringlargeIcon Boolean (optional) - The large version of the icon should be used. По умолчанию - true. Maps to NIIF_LARGE_ICON.noSound Boolean (опционально) - Не проигрывать соответствующий звук. По умолчанию - false. Maps to NIIF_NOSOUND.respectQuietTime Boolean (optional) - Do not display the balloon notification if the current user is in \"quiet time\". По умолчанию - false. Maps to NIIF_RESPECT_QUIET_TIME.Отображает всплывающее сообщение в трее.
\ntray.removeBalloon() WindowsУдаляет всплывающее уведомление в трее.
\ntray.focus() WindowsВозвращает фокус в область уведомления панели задач. Notification area icons should use this message when they have completed their UI operation. For example, if the icon displays a shortcut menu, but the user presses ESC to cancel it, use tray.focus() to return focus to the notification area.
tray.popUpContextMenu([menu, position]) macOS Windowsmenu Menu (опционально)position Point (optional) - позиция всплывающего сообщения.Pops up the context menu of the tray icon. When menu is passed, the menu will be shown instead of the tray icon's context menu.
position доступна только для Windows, и это (0, 0) по умолчанию.
tray.closeContextMenu() macOS WindowsCloses an open context menu, as set by tray.setContextMenu().
tray.setContextMenu(menu)menu Menu | nullУстанавливает контекстное меню для этого значка.
\ntray.getBounds() macOS WindowsВозвращает Rectangle
bounds значка в трее как Object.
tray.isDestroyed()Возвращает Boolean - уничтожен ли значок в трее.
title: Tray\ndescription: This guide will take you through the process of creating a Tray icon with its own context menu to the system's notification area.\nslug: tray
\nThis guide will take you through the process of creating a Tray icon with its own context menu to the system's notification area.
\nOn MacOS and Ubuntu, the Tray will be located on the top right corner of your screen, adjacent to your battery and wifi icons. On Windows, the Tray will usually be located in the bottom right corner.
\nFirst we must import app, Tray, Menu, nativeImage from electron.
const { app, Tray, Menu, nativeImage } = require('electron')\nNext we will create our Tray. To do this, we will use a NativeImage icon, which can be created through any one of these methods. Note that we wrap our Tray creation code within an app.whenReady as we will need to wait for our electron app to finish initializing.
let tray\n\napp.whenReady().then(() => {\n const icon = nativeImage.createFromPath('path/to/asset.png')\n tray = new Tray(icon)\n\n // note: your contextMenu, Tooltip and Title code will go here!\n})\nGreat! Now we can start attaching a context menu to our Tray, like so:
\nconst contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n])\n\ntray.setContextMenu(contextMenu)\nThe code above will create 4 separate radio-type items in the context menu. To read more about constructing native menus, click here.
\nFinally, let's give our tray a tooltip and a title.
\ntray.setToolTip('This is my application')\ntray.setTitle('This is my title')\nAfter you start your electron app, you should see the Tray residing in either the top or bottom right of your screen, depending on your operating system.\nfiddle docs/fiddles/native-ui/tray
Существует несколько способов по обновлению Electron приложений. Самый простой и официально поддерживаемый - воспользоваться встроенным Squirrel фреймворком и модулем Electron autoUpdater.
\nupdate.electronjs.orgThe Electron team maintains update.electronjs.org, a free and open-source webservice that Electron apps can use to self-update. Сервис разработан для приложений Electron, отвечающих следующим критериям:
\nСамый простой способ использовать этот сервис - установить update-electron-app, модуль Node.js, сконфигурированный для использования с update.electronjs.org.
\nУстановить модуль:
\nnpm install update-electron-app\nВызвать обновление из основного файла процесса вашего приложения:
\nrequire('update-electron-app')()\nПо умолчанию этот модуль будет проверять наличие обновлений при запуске приложения, а затем каждые десять минут. При обнаружении обновления оно будет автоматически загружено в фоновом режиме. Когда загрузка завершится, будет отображено диалоговое окно, позволяющее пользователю перезапустить приложение.
\nЕсли вам нужно настроить конфигурацию, вы можете передать параметры в update-electron-app или использовать службу обновления напрямую.
If you're developing a private Electron application, or if you're not publishing releases to GitHub Releases, it may be necessary to run your own update server.
\nDepending on your needs, you can choose from one of these:
\nOnce you've deployed your update server, continue with importing the required modules in your code. The following code might vary for different server software, but it works like described when using Hazel.
\nImportant: Please ensure that the code below will only be executed in your packaged app, and not in development. You can use electron-is-dev to check for the environment.
\nconst { app, autoUpdater, dialog } = require('electron')\nNext, construct the URL of the update server and tell autoUpdater about it:
\nconst server = 'https://your-deployment-url.com'\nconst url = `${server}/update/${process.platform}/${app.getVersion()}`\n\nautoUpdater.setFeedURL({ url })\nAs the final step, check for updates. The example below will check every minute:
\nsetInterval(() => {\n autoUpdater.checkForUpdates()\n}, 60000)\nOnce your application is packaged, it will receive an update for each new GitHub Release that you publish.
\nNow that you've configured the basic update mechanism for your application, you need to ensure that the user will get notified when there's an update. This can be achieved using the autoUpdater API events:
\nautoUpdater.on('update-downloaded', (event, releaseNotes, releaseName) => {\n const dialogOpts = {\n type: 'info',\n buttons: ['Restart', 'Later'],\n title: 'Application Update',\n message: process.platform === 'win32' ? releaseNotes : releaseName,\n detail: 'A new version has been downloaded. Restart the application to apply the updates.'\n }\n\n dialog.showMessageBox(dialogOpts).then((returnValue) => {\n if (returnValue.response === 0) autoUpdater.quitAndInstall()\n })\n})\nAlso make sure that errors are being handled. Here's an example for logging them to stderr:
autoUpdater.on('error', message => {\n console.error('There was a problem updating the application')\n console.error(message)\n})\nBecause the requests made by Auto Update aren't under your direct control, you may find situations that are difficult to handle (such as if the update server is behind authentication). The url field does support files, which means that with some effort, you can sidestep the server-communication aspect of the process. Here's an example of how this could work.
bytes Buffer - Content being sent.file String (optional) - Path of file being uploaded.blobUUID String (optional) - UUID of blob data. Use ses.getBlobData method to retrieve the data.type 'file' - file.filePath String - Path of file to be uploaded.offset Integer - Defaults to 0.length Integer - Number of bytes to read from offset. Defaults to 0.modificationTime Double - Last Modification time in number of seconds since the UNIX epoch.type 'rawData' - rawData.bytes Buffer - Data to be uploaded.stringboolean Booleaninteger Numberfloat Numberdouble Numberurl Stringarray Array\\dictionary Record\\<string, unknown>This type is a helper alias, no object will never exist of this type.
", "title": "UserDefaultTypes Object", "description": "" }, "/docs/tutorial/using-native-node-modules": { "locale": "ru-RU", "slug": "using-native-node-modules", "href": "/docs/tutorial/using-native-node-modules", "crowdinFileId": "256263", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-native-node-modules.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Native Node.js modules are supported by Electron, but since Electron has a different application binary interface (ABI) from a given Node.js binary (due to differences such as using Chromium's BoringSSL instead of OpenSSL), the native modules you use will need to be recompiled for Electron. Иначе, при запуске приложения вы получите следующий класс ошибок:
\nError: The module '/path/to/native/module.node'\nwas compiled against a different Node.js version using\nNODE_MODULE_VERSION $XYZ. This version of Node.js requires\nNODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing\nthe module (for instance, using `npm rebuild` or `npm install`).\nСуществует несколько способов установки нативных модулей:
\nYou can install modules like other Node projects, and then rebuild the modules for Electron with the electron-rebuild package. This module can automatically determine the version of Electron and handle the manual steps of downloading headers and rebuilding native modules for your app. If you are using Electron Forge, this tool is used automatically in both development mode and when making distributables.
For example, to install the standalone electron-rebuild tool and then rebuild modules with it via the command line:
npm install --save-dev electron-rebuild\n\n# Every time you run \"npm install\", run this:\n./node_modules/.bin/electron-rebuild\n\n# If you have trouble on Windows, try:\n.\\node_modules\\.bin\\electron-rebuild.cmd\nFor more information on usage and integration with other tools such as Electron Packager, consult the project's README.
\nnpmУстанавливая несколько переменных среды, вы можете использовать npm для непосредственной установки модулей.
For example, to install all dependencies for Electron:
\n# Electron's version.\nexport npm_config_target=1.2.3\n# The architecture of Electron, see https://electronjs.org/docs/tutorial/support#supported-platforms\n# for supported architectures.\nexport npm_config_arch=x64\nexport npm_config_target_arch=x64\n# Download headers for Electron.\nexport npm_config_disturl=https://electronjs.org/headers\n# Говорит node-pre-gyp, что мы собираем для Electron.\nexport npm_config_runtime=electron\n# Tell node-pre-gyp to build module from source code.\nexport npm_config_build_from_source=true\n# Install all dependencies, and store cache to ~/.electron-gyp.\nHOME=~/.electron-gyp npm install\nIf you are a developer developing a native module and want to test it against Electron, you might want to rebuild the module for Electron manually. You can use node-gyp directly to build for Electron:
cd /path-to-module/\nHOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://electronjs.org/headers\nHOME=~/.electron-gyp changes where to find development headers.--target=1.2.3 is the version of Electron.--dist-url=... specifies where to download the headers.--arch=x64 says the module is built for a 64-bit system.To compile native Node modules against a custom build of Electron that doesn't match a public release, instruct npm to use the version of Node you have bundled with your custom build.
npm rebuild --nodedir=/path/to/src/out/Default/gen/node_headers\nIf you installed a native module and found it was not working, you need to check the following things:
\nelectron-rebuild first.win_delay_load_hook is not set to false in the module's binding.gyp.win_delay_load_hookOn Windows, by default, node-gyp links native modules against node.dll. However, in Electron 4.x and higher, the symbols needed by native modules are exported by electron.exe, and there is no node.dll. In order to load native modules on Windows, node-gyp installs a delay-load hook that triggers when the native module is loaded, and redirects the node.dll reference to use the loading executable instead of looking for node.dll in the library search path (which would turn up nothing). As such, on Electron 4.x and higher, 'win_delay_load_hook': 'true' is required to load native modules.
If you get an error like Module did not self-register, or The specified procedure could not be found, it may mean that the module you're trying to use did not correctly include the delay-load hook. If the module is built with node-gyp, ensure that the win_delay_load_hook variable is set to true in the binding.gyp file, and isn't getting overridden anywhere. If the module is built with another system, you'll need to ensure that you build with a delay-load hook installed in the main .node file. Your link.exe invocation should look like this:
link.exe /OUT:\"foo.node\" \"...\\node.lib\" delayimp.lib /DELAYLOAD:node.exe /DLL\n \"my_addon.obj\" \"win_delay_load_hook.obj\"\nIn particular, it's important that:
\nnode.lib from Electron and not Node. If you link against the wrong node.lib you will get load-time errors when you require the module in Electron./DELAYLOAD:node.exe. If the node.exe link is not delayed, then the delay-load hook won't get a chance to fire and the node symbols won't be correctly resolved.win_delay_load_hook.obj is linked directly into the final DLL. If the hook is set up in a dependent DLL, it won't fire at the right time.See node-gyp for an example delay-load hook if you're implementing your own.
prebuildprebuild provides a way to publish native Node modules with prebuilt binaries for multiple versions of Node and Electron.
If the prebuild-powered module provide binaries for the usage in Electron, make sure to omit --build-from-source and the npm_config_build_from_source environment variable in order to take full advantage of the prebuilt binaries.
node-pre-gypThe node-pre-gyp tool provides a way to deploy native Node modules with prebuilt binaries, and many popular modules are using it.
Sometimes those modules work fine under Electron, but when there are no Electron-specific binaries available, you'll need to build from source. Because of this, it is recommended to use electron-rebuild for these modules.
If you are following the npm way of installing modules, you'll need to pass --build-from-source to npm, or set the npm_config_build_from_source environment variable.
Electron no longer supports the Pepper Flash plugin, as Chrome has removed support.
\nSee Chromium's Flash Roadmap for more details.
", "title": "Pepper Flash Plugin", "description": "" }, "/docs/tutorial/using-selenium-and-webdriver": { "locale": "ru-RU", "slug": "using-selenium-and-webdriver", "href": "/docs/tutorial/using-selenium-and-webdriver", "crowdinFileId": "256267", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-selenium-and-webdriver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "От ChromeDriver - WebDriver для Chrome:
\n\n\nWebDriver — это инструмент с открытым исходным кодом для автоматизации тестирования веб-приложений во многих браузерах. Он предоставляет возможности для навигации на веб-страницы, ввода пользователя, - выполнение JavaScript и многое другое. ChromeDriver - это автономный сервер, который использует протокол провода WebDriver для Chromium. Он разрабатывается членами команд Chromium и WebDriver.
\n
Spectron - официально поддерживаемая среда тестирования ChromeDriver для Electron. Он построен на основе WebdriverIO и имеет помощников для доступа к API Electron в ваших тестах и в комплекте с ChromeDriver.
\n$ npm install --save-dev spectron\n// Простой тест для проверки того, что видимое окно открывается с заголовком\nconst Application = require('spectron').Application\nconst assert = require('assert')\n\nconst myApp = new Application({\n path: '/Applications/MyApp.app/Contents/MacOS/MyApp'\n})\n\nconst verifyWindowIsVisibleWithTitle = async (app) => {\n await app.start()\n try {\n // Проверить, видно ли окно\n const isVisible = await app.browserWindow.isVisible()\n // Убедиться что окно видимое\n assert.strictEqual(isVisible, true)\n // Получить заголовок окна\n const title = await app.client.getTitle()\n // Проверить заголовок окна\n assert.strictEqual(title, 'Мое Приложение')\n } catch (error) {\n // Журналировать любые сбои\n console.error('Тест не пройден', error.message)\n }\n // Остановить приложение\n await app.stop()\n}\n\nverifyWindowIsVisibleWithTitle(myApp)\nWebDriverJs provides a Node package for testing with web driver, we will use it as an example.
\nСначала вам нужно скачать бинарный файл chromedriver и запустить его:
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\nЗапомните номер порта 9515, который будет использоваться позже
$ npm install selenium-webdriver\nThe usage of selenium-webdriver with Electron is the same with upstream, except that you have to manually specify how to connect chrome driver and where to find Electron's binary:
const webdriver = require('selenium-webdriver')\n\nconst driver = new webdriver.Builder()\n // The \"9515\" is the port opened by chrome driver.\n .usingServer('http://localhost:9515')\n .withCapabilities({\n 'goog:chromeOptions': {\n // Here is the path to your Electron binary.\n binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'\n }\n })\n .forBrowser('chrome') // note: use .forBrowser('electron') for selenium-webdriver <= 3.6.0\n .build()\n\ndriver.get('http://www.google.com')\ndriver.findElement(webdriver.By.name('q')).sendKeys('webdriver')\ndriver.findElement(webdriver.By.name('btnG')).click()\ndriver.wait(() => {\n return driver.getTitle().then((title) => {\n return title === 'webdriver - Google Search'\n })\n}, 1000)\n\ndriver.quit()\nWebdriverIO provides a Node package for testing with web driver.
\nСначала вам нужно скачать бинарный файл chromedriver и запустить его:
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver --url-base=wd/hub --port=9515\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\nЗапомните номер порта 9515, который будет использоваться позже
$ npm install webdriverio\nconst webdriverio = require('webdriverio')\nconst options = {\n host: 'localhost', // Use localhost as chrome driver server\n port: 9515, // \"9515\" is the port opened by chrome driver.\n desiredCapabilities: {\n browserName: 'chrome',\n 'goog:chromeOptions': {\n binary: '/Path-to-Your-App/electron', // Path to your Electron binary.\n args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/\n }\n }\n}\n\nconst client = webdriverio.remote(options)\n\nclient\n .init()\n .url('http://google.com')\n .setValue('#q', 'webdriverio')\n .click('#btnG')\n .getTitle().then((title) => {\n console.log('Title was: ' + title)\n })\n .end()\nTo test your application without rebuilding Electron, place your app source into Electron's resource directory.
\nAlternatively, 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.
", "title": "Selenium and WebDriver", "description": "WebDriver — это инструмент с открытым исходным кодом для автоматизации тестирования веб-приложений во многих браузерах. Он предоставляет возможности для навигации на веб-страницы, ввода пользователя, - выполнение JavaScript и многое другое. ChromeDriver - это автономный сервер, который использует протокол провода WebDriver для Chromium. Он разрабатывается членами команд Chromium и WebDriver." }, "/docs/development/v8-development": { "locale": "ru-RU", "slug": "v8-development", "href": "/docs/development/v8-development", "crowdinFileId": "256171", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/v8-development.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "\n\nКоллекция ссылок для изучения и использования V8
\n
--prof, --trace-ic, --trace-opt, --trace-deopt, --print-bytecode, --print-opt-codeСм. также Разработка Chromium
", "title": "Разработка V8", "description": "Коллекция ссылок для изучения и использования V8" }, "/docs/api/web-contents": { "locale": "ru-RU", "slug": "web-contents", "href": "/docs/api/web-contents", "crowdinFileId": "256399", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-contents.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRender and control web pages.
\n
Процесс: Основной
\nwebContents является EventEmitter'ом. Он ответственен за рендер и управление веб-страницы и является свойством объекта BrowserWindow. Пример доступа к объекту webContents:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('http://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\nЭти методы доступны из модуля webContents:
const { webContents } = require('electron')\nconsole.log(webContents)\nwebContents.getAllWebContents()Возвращает WebContents - массив всех экземпляров WebContents. Этот массив содержит веб-контент всех окон, webviews, открытых инструментов разработчика и расширений инструментов разработчика на фоновых страницах.
webContents.getFocusedWebContents()Возвращает WebContents - веб-контент, который сейчас активен в этом приложении, в ином случае возвращает null.
webContents.fromId(id)id IntegerReturns WebContents | undefined - A WebContents instance with the given ID, or undefined if there is no WebContents associated with the given ID.
webContents.fromDevToolsTargetId(targetId)targetId String - The Chrome DevTools Protocol TargetID associated with the WebContents instance.Returns WebContents | undefined - A WebContents instance with the given TargetID, or undefined if there is no WebContents associated with the given TargetID.
When communicating with the Chrome DevTools Protocol, it can be useful to lookup a WebContents instance based on its assigned TargetID.
\nasync function lookupTargetId (browserWindow) {\n const wc = browserWindow.webContents\n await wc.debugger.attach('1.3')\n const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')\n const { targetId } = targetInfo\n const targetWebContents = await webContents.fromDevToolsTargetId(targetId)\n}\n\n\nРендерит и управляет контент экземпляра BrowserWindow.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emitted when the navigation is done, i.e. the spinner of the tab has stopped spinning, and the onload event was dispatched.
Возвращает:
\neventerrorCode IntegererrorDescriptionvalidatedURLisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerThis event is like did-finish-load but emitted when the load failed. The full list of error codes and their meaning is available here.
Возвращает:
\neventerrorCode IntegererrorDescriptionvalidatedURLisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerThis event is like did-fail-load but emitted when the load was cancelled (e.g. window.stop() was invoked).
Возвращает:
\neventisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when a frame has done navigation.
\nCorresponds to the points in time when the spinner of the tab started spinning.
\nCorresponds to the points in time when the spinner of the tab stopped spinning.
\nВозвращает:
\neventEmitted when the document in the top-level frame is loaded.
\nВозвращает:
\neventtitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when title is synthesized from file url.
Возвращает:
\neventfavicons String[] - Array of URLs.Emitted when page receives favicon urls.
\nВозвращает:
\nevent NewWindowWebContentsEventurl StringframeName Stringdisposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.options BrowserWindowConstructorOptions - The options which will be used for creating the new BrowserWindow.additionalFeatures String[] - The non-standard features (features not handled by Chromium or Electron) given to window.open(). Deprecated, and will now always be the empty array [].referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.Deprecated in favor of webContents.setWindowOpenHandler.
Emitted when the page requests to open a new window for a url. It could be requested by window.open or an external link like <a target='_blank'>.
By default a new BrowserWindow will be created for the url.
Calling event.preventDefault() will prevent Electron from automatically creating a new BrowserWindow. If you call event.preventDefault() and manually create a new BrowserWindow then you must set event.newGuest to reference the new BrowserWindow instance, failing to do so may result in unexpected behavior. Например:
myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {\n event.preventDefault()\n const win = new BrowserWindow({\n webContents: options.webContents, // use existing webContents if provided\n show: false\n })\n win.once('ready-to-show', () => win.show())\n if (!options.webContents) {\n const loadOptions = {\n httpReferrer: referrer\n }\n if (postBody != null) {\n const { data, contentType, boundary } = postBody\n loadOptions.postData = postBody.data\n loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`\n }\n\n win.loadURL(url, loadOptions) // existing webContents will be navigated automatically\n }\n event.newGuest = win\n})\nВозвращает:
\nwindow BrowserWindowdetailsurl String - URL for the created window.frameName String - Name given to the created window in the window.open() call.options BrowserWindowConstructorOptions - The options used to create the BrowserWindow. They are merged in increasing precedence: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Unrecognized options are not filtered out.referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.Emitted after successful creation of a window via window.open in the renderer. Not emitted if the creation of the window is canceled from webContents.setWindowOpenHandler.
See window.open() for more details and how to use this in conjunction with webContents.setWindowOpenHandler.
Возвращает:
\neventurl StringEmitted when a user or the page wants to start navigation. It can happen when the window.location object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with APIs like webContents.loadURL and webContents.back.
It is also not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Calling event.preventDefault() will prevent the navigation.
Возвращает:
\neventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be true for in-page navigations.
Возвращает:
\neventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted as a server side redirect occurs during navigation. For example a 302 redirect.
\nThis event will be emitted after did-start-navigation and always before the did-redirect-navigation event for the same navigation.
Calling event.preventDefault() will prevent the navigation (not just the redirect).
Возвращает:
\neventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nЭто событие не может быть предотвращено, если вы хотите предотвратить перенаправления, то должны проверить событиеwill-redirect выше.
Возвращает:
\neventurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigationsEmitted when a main frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Возвращает:
\neventurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigations,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Возвращает:
\neventurl StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when an in-page navigation happened in any frame.
\nWhen in-page navigation happens, the page URL changes but does not cause navigation outside of the page. Examples of this occurring are when anchor links are clicked or when the DOM hashchange event is triggered.
Возвращает:
\neventEmitted when a beforeunload event handler is attempting to cancel a page unload.
Calling event.preventDefault() will ignore the beforeunload event handler and allow the page to be unloaded.
const { BrowserWindow, dialog } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.webContents.on('will-prevent-unload', (event) => {\n const choice = dialog.showMessageBoxSync(win, {\n type: 'question',\n buttons: ['Leave', 'Stay'],\n title: 'Do you want to leave this site?',\n message: 'Changes you made may not be saved.',\n defaultId: 0,\n cancelId: 1\n })\n const leave = (choice === 0)\n if (leave) {\n event.preventDefault()\n }\n})\nNote: This will be emitted for BrowserViews but will not be respected - this is because we have chosen not to tie the BrowserView lifecycle to its owning BrowserWindow should one exist per the specification.
Возвращает:
\neventkilled BooleanEmitted when the renderer process crashes or is killed.
\nDeprecated: This event is superceded by the render-process-gone event which contains more information about why the render process disappeared. It isn't always because it crashed. The killed boolean can be replaced by checking reason === 'killed' when you switch to that event.
Возвращает:
\neventdetailsreason String - The reason the render process is gone. Возможные значения:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Integer - The exit code of the process, unless reason is launch-failed, in which case exitCode will be a platform-specific launch failure error code.Emitted when the renderer process unexpectedly disappears. This is normally because it was crashed or killed.
\nВызывается, когда страница \"не отвечает\".
\nПроисходит, когда страница, которая \"не отвечала\", снова реагирует.
\nВозвращает:
\neventname Stringversion StringEmitted when a plugin process has crashed.
\nEmitted when webContents is destroyed.
Возвращает:
\neventinput Object - Input properties.type String - Either keyUp or keyDown.key String - Equivalent to KeyboardEvent.key.code String - Equivalent to KeyboardEvent.code.isAutoRepeat Boolean - Equivalent to KeyboardEvent.repeat.isComposing Boolean - Equivalent to KeyboardEvent.isComposing.shift Boolean - Equivalent to KeyboardEvent.shiftKey.control Boolean - Equivalent to KeyboardEvent.controlKey.alt Boolean - Equivalent to KeyboardEvent.altKey.meta Boolean - Equivalent to KeyboardEvent.metaKey.location Number - Equivalent to KeyboardEvent.location.modifiers String[] - See InputEvent.modifiers.Emitted before dispatching the keydown and keyup events in the page. Calling event.preventDefault will prevent the page keydown/keyup events and the menu shortcuts.
To only prevent the menu shortcuts, use setIgnoreMenuShortcuts:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nwin.webContents.on('before-input-event', (event, input) => {\n // Например, включать сочетания клавиш меню приложения\n // Только когда Ctrl/Cmd нажаты.\n win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)\n})\nПроисходит, когда окно входит в полноэкранный режим с помощью HTML API.
\nПроисходит, когда окно выходит из полноэкранного режима с помощью HTML API.
\nВозвращает:
\neventzoomDirection String - Can be in or out.Emitted when the user is requesting to change the zoom level using the mouse wheel.
\nEmitted when DevTools is opened.
\nEmitted when DevTools is closed.
\nEmitted when DevTools is focused / opened.
\nВозвращает:
\neventurl Stringerror String - The error code.certificate Certificatecallback FunctionisTrusted Boolean - Indicates whether the certificate can be considered trusted.isMainFrame BooleanEmitted when failed to verify the certificate for url.
The usage is the same with the certificate-error event of app.
Возвращает:
\neventurl URLcertificateList Certificate[]callback Functioncertificate Certificate - Must be a certificate from the given list.Возникает при запросе сертификата клиента.
\nThe usage is the same with the select-client-certificate event of app.
Возвращает:
\neventauthenticationResponseDetails Objecturl URLauthInfo ObjectisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (опционально)password String (опционально)Возникает webContents, когда делается базовый auth.
The usage is the same with the login event of app.
Возвращает:
\neventresult ObjectrequestId IntegeractiveMatchOrdinal Integer - Position of the active match.matches Integer - Number of Matches.selectionArea Rectangle - Coordinates of first match region.finalUpdate BooleanEmitted when a result is available for [webContents.findInPage] request.
Emitted when media starts playing.
\nEmitted when media is paused or done playing.
\nВозвращает:
\neventcolor (String | null) - Theme color is in format of '#rrggbb'. It is null when no theme color is set.Emitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nВозвращает:
\neventurl StringEmitted when mouse moves over a link or the keyboard moves the focus to a link.
\nВозвращает:
\neventtype Stringimage NativeImage (опционально)scale Float (optional) - scaling factor for the custom cursor.size Size (optional) - the size of the image.hotspot Point (optional) - coordinates of the custom cursor's hotspot.Emitted when the cursor's type changes. The type parameter can be default, crosshair, pointer, text, wait, help, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ns-resize, ew-resize, nesw-resize, nwse-resize, col-resize, row-resize, m-panning, e-panning, n-panning, ne-panning, nw-panning, s-panning, se-panning, sw-panning, w-panning, move, vertical-text, cell, context-menu, alias, progress, nodrop, copy, none, not-allowed, zoom-in, zoom-out, grab, grabbing or custom.
If the type parameter is custom, the image parameter will hold the custom cursor image in a NativeImage, and scale, size and hotspot will hold additional information about the custom cursor.
Возвращает:
\neventparams Objectx Integer - x coordinate.y Integer - y coordinate.frame WebFrameMain - Frame from which the context menu was invoked.linkURL String - URL of the link that encloses the node the context menu was invoked on.linkText String - Text associated with the link. May be an empty string if the contents of the link are an image.pageURL String - URL of the top level page that the context menu was invoked on.frameURL String - URL of the subframe that the context menu was invoked on.srcURL String - Source URL for the element that the context menu was invoked on. Elements with source URLs are images, audio and video.mediaType String - Type of the node the context menu was invoked on. Can be none, image, audio, video, canvas, file or plugin.hasImageContents Boolean - Whether the context menu was invoked on an image which has non-empty contents.isEditable Boolean - Whether the context is editable.selectionText String - Text of the selection that the context menu was invoked on.titleText String - Title text of the selection that the context menu was invoked on.altText String - Alt text of the selection that the context menu was invoked on.suggestedFilename String - Suggested filename to be used when saving file through 'Save Link As' option of context menu.selectionRect Rectangle - Rect representing the coordinates in the document space of the selection.selectionStartOffset Number - Start position of the selection text.referrerPolicy Referrer - The referrer policy of the frame on which the menu is invoked.misspelledWord String - The misspelled word under the cursor, if any.dictionarySuggestions String[] - An array of suggested words to show the user to replace the misspelledWord. Only available if there is a misspelled word and spellchecker is enabled.frameCharset String - The character encoding of the frame on which the menu was invoked.inputFieldType String - If the context menu was invoked on an input field, the type of that field. Possible values are none, plainText, password, other.spellcheckEnabled Boolean - If the context is editable, whether or not spellchecking is enabled.menuSourceType String - Input source that invoked the context menu. Can be none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, or adjustSelectionReset.mediaFlags Object - The flags for the media element the context menu was invoked on.inError Boolean - Whether the media element has crashed.isPaused Boolean - Whether the media element is paused.isMuted Boolean - Whether the media element is muted.hasAudio Boolean - Whether the media element has audio.isLooping Boolean - Whether the media element is looping.isControlsVisible Boolean - Whether the media element's controls are visible.canToggleControls Boolean - Whether the media element's controls are toggleable.canPrint Boolean - Whether the media element can be printed.canSave Boolean - Whether or not the media element can be downloaded.canShowPictureInPicture Boolean - Whether the media element can show picture-in-picture.isShowingPictureInPicture Boolean - Whether the media element is currently showing picture-in-picture.canRotate Boolean - Whether the media element can be rotated.canLoop Boolean - Whether the media element can be looped.editFlags Object - These flags indicate whether the renderer believes it is able to perform the corresponding action.canUndo Boolean - Whether the renderer believes it can undo.canRedo Boolean - Whether the renderer believes it can redo.canCut Boolean - Whether the renderer believes it can cut.canCopy Boolean - Whether the renderer believes it can copy.canPaste Boolean - Whether the renderer believes it can paste.canDelete Boolean - Whether the renderer believes it can delete.canSelectAll Boolean - Whether the renderer believes it can select all.canEditRichly Boolean - Whether the renderer believes it can edit text richly.Emitted when there is a new context menu that needs to be handled.
\nВозвращает:
\neventdevices BluetoothDevice[]callback FunctiondeviceId StringEmitted when bluetooth device needs to be selected on call to navigator.bluetooth.requestDevice. To use navigator.bluetooth api webBluetooth should be enabled. If event.preventDefault is not called, first available device will be selected. callback should be called with deviceId to be selected, passing empty string to callback will cancel the request.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\napp.commandLine.appendSwitch('enable-experimental-web-platform-features')\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {\n event.preventDefault()\n const result = deviceList.find((device) => {\n return device.deviceName === 'test'\n })\n if (!result) {\n callback('')\n } else {\n callback(result.deviceId)\n }\n })\n})\nВозвращает:
\neventdirtyRect Rectangleimage NativeImage - The image data of the whole frame.Emitted when a new frame is generated. Only the dirty area is passed in the buffer.
\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ webPreferences: { offscreen: true } })\nwin.webContents.on('paint', (event, dirty, image) => {\n // updateBitmap(dirty, image.getBitmap())\n})\nwin.loadURL('http://github.com')\nEmitted when the devtools window instructs the webContents to reload
\nВозвращает:
\neventwebPreferences WebPreferences - The web preferences that will be used by the guest page. This object can be modified to adjust the preferences for the guest page.params Record<string, string> - The other <webview> parameters such as the src URL. This object can be modified to adjust the parameters of the guest page.Emitted when a <webview>'s web contents is being attached to this web contents. Calling event.preventDefault() will destroy the guest page.
This event can be used to configure webPreferences for the webContents of a <webview> before it's loaded, and provides the ability to set settings that can't be set via <webview> attributes.
Note: The specified preload script option will appear as preloadURL (not preload) in the webPreferences object emitted with this event.
Возвращает:
\neventwebContents WebContents - The guest web contents that is used by the <webview>.Emitted when a <webview> has been attached to this web contents.
Возвращает:
\neventlevel Integer - The log level, from 0 to 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Integer - The line number of the source that triggered this console messagesourceId StringEmitted when the associated window logs a console message.
\nВозвращает:
\neventpreloadPath Stringerror ErrorEmitted when the preload script preloadPath throws an unhandled exception error.
Возвращает:
\neventchannel String (Строка)...args any[]Emitted when the renderer process sends an asynchronous message via ipcRenderer.send().
Возвращает:
\neventchannel String (Строка)...args any[]Emitted when the renderer process sends a synchronous message via ipcRenderer.sendSync().
Возвращает:
\neventEmitted when desktopCapturer.getSources() is called in the renderer process. Вызов event.preventDefault() вернет пустые источники.
Возвращает:
\neventpreferredSize Size - The minimum size needed to contain the layout of the document—without requiring scrolling.Emitted when the WebContents preferred size has changed.
This event will only be emitted when enablePreferredSizeMode is set to true in webPreferences.
Возвращает:
\neventdetailsframe WebFrameMainEmitted when the mainFrame, an <iframe>, or a nested <iframe> is loaded within the page.
contents.loadURL(url[, options])url Stringoptions Object (опционально)httpReferrer (String | Referrer) (optional) - An HTTP Referrer url.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\".postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url is a data url and needs to load other files.Returns Promise<void> - the promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load). A noop rejection handler is already attached, which avoids unhandled rejection errors.
Loads the url in the window. The url must contain the protocol prefix, e.g. the http:// or file://. If the load should bypass http cache then use the pragma header to achieve it.
const { webContents } = require('electron')\nconst options = { extraHeaders: 'pragma: no-cache\\n' }\nwebContents.loadURL('https://github.com', options)\ncontents.loadFile(filePath[, options])filePath Stringoptions Object (опционально)query Record<String, String> (опционально) - переданная в url.format().search String (optional) - Passed to url.format().hash String (optional) - Passed to url.format().Возвращает Promise<void> - промис будет разрешен, когда страница завершит загрузку (см. did-finish-load), и отклоняет, если страница не удачно загрузилась (см. did-fail-load).
Loads the given file in the window, filePath should be a path to an HTML file relative to the root of your application. For instance an app structure like this:
| root\n| - package.json\n| - src\n| - main.js\n| - index.html\nWould require code like this
\nwin.loadFile('src/index.html')\ncontents.downloadURL(url)url StringInitiates a download of the resource at url without navigating. The will-download event of session will be triggered.
contents.getURL()Returns String - The URL of the current web page.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com').then(() => {\n const currentURL = win.webContents.getURL()\n console.log(currentURL)\n})\ncontents.getTitle()Returns String - The title of the current web page.
contents.isDestroyed()Returns Boolean - Whether the web page is destroyed.
contents.focus()Focuses the web page.
\ncontents.isFocused()Returns Boolean - Whether the web page is focused.
contents.isLoading()Returns Boolean - Whether web page is still loading resources.
contents.isLoadingMainFrame()Returns Boolean - Whether the main frame (and not just iframes or frames within it) is still loading.
contents.isWaitingForResponse()Returns Boolean - Whether the web page is waiting for a first-response from the main resource of the page.
contents.stop()Stops any pending navigation.
\ncontents.reload()Reloads the current web page.
\ncontents.reloadIgnoringCache()Reloads current page and ignores cache.
\ncontents.canGoBack()Returns Boolean - Whether the browser can go back to previous web page.
contents.canGoForward()Returns Boolean - Whether the browser can go forward to next web page.
contents.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the web page can go to offset.
contents.clearHistory()Clears the navigation history.
\ncontents.goBack()Makes the browser go back a web page.
\ncontents.goForward()Makes the browser go forward a web page.
\ncontents.goToIndex(index)index IntegerNavigates browser to the specified absolute web page index.
\ncontents.goToOffset(offset)offset IntegerNavigates to the specified offset from the \"current entry\".
\ncontents.isCrashed()Returns Boolean - Whether the renderer process has crashed.
contents.forcefullyCrashRenderer()Forcefully terminates the renderer process that is currently hosting this webContents. This will cause the render-process-gone event to be emitted with the reason=killed || reason=crashed. Please note that some webContents share renderer processes and therefore calling this method may also crash the host process for other webContents as well.
Calling reload() immediately after calling this method will force the reload to occur in a new process. This should be used when this process is unstable or unusable, for instance in order to recover from the unresponsive event.
contents.on('unresponsive', async () => {\n const { response } = await dialog.showMessageBox({\n message: 'App X has become unresponsive',\n title: 'Do you want to try forcefully reloading the app?',\n buttons: ['OK', 'Cancel'],\n cancelId: 1\n })\n if (response === 0) {\n contents.forcefullyCrashRenderer()\n contents.reload()\n }\n})\ncontents.setUserAgent(userAgent)userAgent StringOverrides the user agent for this web page.
\ncontents.getUserAgent()Returns String - The user agent for this web page.
contents.insertCSS(css[, options])css Stringoptions Object (опционально)cssOrigin String (optional) - Can be either 'user' or 'author'; Specifying 'user' enables you to prevent websites from overriding the CSS you insert. Default is 'author'.Returns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via contents.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\ncontents.on('did-finish-load', () => {\n contents.insertCSS('html, body { background-color: #f00; }')\n})\ncontents.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from contents.insertCSS(css).
contents.on('did-finish-load', async () => {\n const key = await contents.insertCSS('html, body { background-color: #f00; }')\n contents.removeInsertedCSS(key)\n})\ncontents.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (опиционально) - по умолчанию false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Вычисляет code на странице.
В окне браузера некоторые HTML API как requestFullScreen может быть только вызван жестом пользователя. Указание userGesture как true снимает это ограничение.
Code execution will be suspended until web page stop loading.
\ncontents.executeJavaScript('fetch(\"https://jsonplaceholder.typicode.com/users/1\").then(resp => resp.json())', true)\n .then((result) => {\n console.log(result) // должен быть объект JSON из запрашиваемого вызова\n })\ncontents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electron's contextIsolation feature. You can provide any integer here.scripts WebSource[]userGesture Boolean (опиционально) - по умолчанию false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Works like executeJavaScript but evaluates scripts in an isolated context.
contents.setIgnoreMenuShortcuts(ignore)ignore Логическое значениеIgnore application menu shortcuts while this web contents is focused.
\ncontents.setWindowOpenHandler(handler)handler Function<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>
detailsurl String - The resolved version of the URL passed to window.open(). e.g. opening a window with window.open('foo') will yield something like https://the-origin/the/current/path/foo.frameName String - Name of the window provided in window.open()features String - Comma separated list of window features provided to window.open().disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk or other.referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.Returns {action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny cancels the creation of the new window. allow will allow the new window to be created. Specifying overrideBrowserWindowOptions allows customization of the created window. Returning an unrecognized value such as a null, undefined, or an object without a recognized 'action' value will result in a console error and have the same effect as returning {action: 'deny'}.
Called before creating a window a new window is requested by the renderer, e.g. by window.open(), a link with target=\"_blank\", shift+clicking on a link, or submitting a form with <form target=\"_blank\">. See window.open() for more details and how to use this in conjunction with did-create-window.
contents.setAudioMuted(muted)muted BooleanMute the audio on the current web page.
\ncontents.isAudioMuted()Returns Boolean - Whether this page has been muted.
contents.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
contents.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\nThe factor must be greater than 0.0.
\ncontents.getZoomFactor()Returns Number - the current zoom factor.
contents.setZoomLevel(level)level Number - уровень увеличения.Изменяет уровень масштаба на указанный уровень. Оригинальный размер 0 и каждое приращение выше или ниже представляет масштабирование 20% больше или меньше, по умолчанию ограничение на 300% и 50% от исходного размера, соответственно. The formula for this is scale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
contents.getZoomLevel()Returns Number - the current zoom level.
contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberВозвращает Promise<void>
Устанавливает максимальный и минимальный уровень пинч-маштабирования.
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\ncontents.setVisualZoomLevelLimits(1, 3)\n
contents.undo()Executes the editing command undo in web page.
contents.redo()Executes the editing command redo in web page.
contents.cut()Executes the editing command cut in web page.
contents.copy()Executes the editing command copy in web page.
contents.copyImageAt(x, y)x Integery IntegerCopy the image at the given position to the clipboard.
\ncontents.paste()Executes the editing command paste in web page.
contents.pasteAndMatchStyle()Executes the editing command pasteAndMatchStyle in web page.
contents.delete()Executes the editing command delete in web page.
contents.selectAll()Executes the editing command selectAll in web page.
contents.unselect()Executes the editing command unselect in web page.
contents.replace(text)text StringExecutes the editing command replace in web page.
contents.replaceMisspelling(text)text StringExecutes the editing command replaceMisspelling in web page.
contents.insertText(text)text StringВозвращает Promise<void>
Вставляет text в элемент с фокусом.
contents.findInPage(text[, options])text String - Content to be searched, must not be empty.options Object (опционально)forward Boolean (optional) - Whether to search forward or backward, defaults to true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Defaults to false.matchCase Boolean (optional) - Whether search should be case-sensitive, defaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. The result of the request can be obtained by subscribing to found-in-page event.
contents.stopFindInPage(action)action String - Specifies the action to take place when ending [webContents.findInPage] request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webContents with the provided action.
const { webContents } = require('electron')\nwebContents.on('found-in-page', (event, result) => {\n if (result.finalUpdate) webContents.stopFindInPage('clearSelection')\n})\n\nconst requestId = webContents.findInPage('api')\nconsole.log(requestId)\ncontents.capturePage([rect])rect Rectangle (optional) - The area of the page to be captured.Возвращает Promise<NativeImage> - разрешается с NativeImage
Захватывает снимок страницы в границах rect. Пропустив rect, будет сделан захват всей видимой страницы.
contents.isBeingCaptured()Returns Boolean - Whether this page is being captured. It returns true when the capturer count is large then 0.
contents.incrementCapturerCount([size, stayHidden, stayAwake])size Size (optional) - The preferred size for the capturer.stayHidden Boolean (optional) - Keep the page hidden instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Increase the capturer count by one. The page is considered visible when its browser window is hidden and the capturer count is non-zero. If you would like the page to stay hidden, you should ensure that stayHidden is set to true.
This also affects the Page Visibility API.
\ncontents.decrementCapturerCount([stayHidden, stayAwake])stayHidden Boolean (optional) - Keep the page in hidden state instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Decrease the capturer count by one. The page will be set to hidden or occluded state when its browser window is hidden or occluded and the capturer count reaches zero. If you want to decrease the hidden capturer count instead you should set stayHidden to true.
contents.getPrinters()Get the system printer list.
\nВозвращает PrinterInfo[]
contents.print([options], [callback])options Object (опционально)silent Boolean (optional) - Don't ask user for print settings. По умолчанию - false.printBackground Boolean (optional) - Prints the background color and image of the web page. По умолчанию - false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. По умолчанию - true.margins Object (опционально)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. По умолчанию - false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print. On macOS, only one range is honored.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Can be simplex, shortEdge, or longEdge.dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.callback Function (опционально)success Boolean - Indicates success of the print call.failureReason String - Error description called back if the print fails.When a custom pageSize is passed, Chromium attempts to validate platform specific minimum values for width_microns and height_microns. Width and height must both be minimum 353 microns but may be higher on some operating systems.
Prints window's web page. When silent is set to true, Electron will pick the system's default printer if deviceName is empty and the default settings for printing.
Use page-break-before: always; CSS style to force to print to a new page.
Пример использования:
\nconst options = {\n silent: true,\n deviceName: 'My-Printer',\n pageRanges: [{\n from: 0,\n to: 1\n }]\n}\nwin.webContents.print(options, (success, errorType) => {\n if (!success) console.log(errorType)\n})\ncontents.printToPDF(options)options ObjectheaderFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height and width in microns.printBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Buffer> - Resolves with the generated PDF data.
Prints window's web page as PDF with Chromium's preview printing custom settings.
\nThe landscape will be ignored if @page CSS at-rule is used in the web page.
By default, an empty options will be regarded as:
{\n marginsType: 0,\n printBackground: false,\n printSelectionOnly: false,\n landscape: false,\n pageSize: 'A4',\n scaleFactor: 100\n}\nUse page-break-before: always; CSS style to force to print to a new page.
An example of webContents.printToPDF:
const { BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\nconst os = require('os')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nwin.webContents.on('did-finish-load', () => {\n // Use default printing options\n win.webContents.printToPDF({}).then(data => {\n const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')\n fs.writeFile(pdfPath, data, (error) => {\n if (error) throw error\n console.log(`Wrote PDF successfully to ${pdfPath}`)\n })\n }).catch(error => {\n console.log(`Failed to write PDF to ${pdfPath}: `, error)\n })\n})\ncontents.addWorkSpace(path)path StringAdds the specified path to DevTools workspace. Must be used after DevTools creation:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.on('devtools-opened', () => {\n win.webContents.addWorkSpace(__dirname)\n})\ncontents.removeWorkSpace(path)path StringRemoves the specified path from DevTools workspace.
\ncontents.setDevToolsWebContents(devToolsWebContents)devToolsWebContents WebContentsUses the devToolsWebContents as the target WebContents to show devtools.
The devToolsWebContents must not have done any navigation, and it should not be used for other purposes after the call.
By default Electron manages the devtools by creating an internal WebContents with native view, which developers have very limited control of. With the setDevToolsWebContents method, developers can use any WebContents to show the devtools in it, including BrowserWindow, BrowserView and <webview> tag.
Note that closing the devtools does not destroy the devToolsWebContents, it is caller's responsibility to destroy devToolsWebContents.
An example of showing devtools in a <webview> tag:
<html>\n<head>\n <style type=\"text/css\">\n * { margin: 0; }\n #browser { height: 70%; }\n #devtools { height: 30%; }\n </style>\n</head>\n<body>\n <webview id=\"browser\" src=\"https://github.com\"></webview>\n <webview id=\"devtools\" src=\"about:blank\"></webview>\n <script>\n const { ipcRenderer } = require('electron')\n const emittedOnce = (element, eventName) => new Promise(resolve => {\n element.addEventListener(eventName, event => resolve(event), { once: true })\n })\n const browserView = document.getElementById('browser')\n const devtoolsView = document.getElementById('devtools')\n const browserReady = emittedOnce(browserView, 'dom-ready')\n const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')\n Promise.all([browserReady, devtoolsReady]).then(() => {\n const targetId = browserView.getWebContentsId()\n const devtoolsId = devtoolsView.getWebContentsId()\n ipcRenderer.send('open-devtools', targetId, devtoolsId)\n })\n </script>\n</body>\n</html>\n// Main process\nconst { ipcMain, webContents } = require('electron')\nipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {\n const target = webContents.fromId(targetContentsId)\n const devtools = webContents.fromId(devtoolsContentsId)\n target.setDevToolsWebContents(devtools)\n target.openDevTools()\n})\nAn example of showing devtools in a BrowserWindow:
const { app, BrowserWindow } = require('electron')\n\nlet win = null\nlet devtools = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n devtools = new BrowserWindow()\n win.loadURL('https://github.com')\n win.webContents.setDevToolsWebContents(devtools.webContents)\n win.webContents.openDevTools({ mode: 'detach' })\n})\ncontents.openDevTools([options])options Object (опционально)mode String - Opens the devtools with specified dock state, can be right, bottom, undocked, detach. Defaults to last used dock state. In undocked mode it's possible to dock back. In detach mode it's not.activate Boolean (optional) - Whether to bring the opened devtools window to the foreground. По-умолчанию - true.Opens the devtools.
\nWhen contents is a <webview> tag, the mode would be detach by default, explicitly passing an empty mode can force using last used dock state.
contents.closeDevTools()Closes the devtools.
\ncontents.isDevToolsOpened()Returns Boolean - Whether the devtools is opened.
contents.isDevToolsFocused()Returns Boolean - Whether the devtools view is focused .
contents.toggleDevTools()Toggles the developer tools.
\ncontents.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y).
contents.inspectSharedWorker()Opens the developer tools for the shared worker context.
\ncontents.inspectSharedWorkerById(workerId)workerId StringInspects the shared worker based on its ID.
\ncontents.getAllSharedWorkers()Returns SharedWorkerInfo[] - Information about all Shared Workers.
contents.inspectServiceWorker()Opens the developer tools for the service worker context.
\ncontents.send(channel, ...args)channel String (Строка)...args any[]Send an asynchronous message to the renderer process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the ipcRenderer module.
An example of sending messages from the main process to the renderer process:
\n// В основном процессе.\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL(`file://${__dirname}/index.html`)\n win.webContents.on('did-finish-load', () => {\n win.webContents.send('ping', 'whoooooooh!')\n })\n})\n<!-- index.html -->\n<html>\n<body>\n <script>\n require('electron').ipcRenderer.on('ping', (event, message) => {\n console.log(message) // Prints 'whoooooooh!'\n })\n </script>\n</body>\n</html>\ncontents.sendToFrame(frameId, channel, ...args)frameId Integer | [number, number] - the ID of the frame to send to, or a pair of [processId, frameId] if the frame is in a different process to the main frame.channel String (Строка)...args any[]Send an asynchronous message to a specific frame in a renderer process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the ipcRenderer module.
If you want to get the frameId of a given renderer context you should use the webFrame.routingId value. Например,
// In a renderer process\nconsole.log('My frameId is:', require('electron').webFrame.routingId)\nYou can also read frameId from all incoming IPC messages in the main process.
// In the main process\nipcMain.on('ping', (event) => {\n console.info('Message came from frameId:', event.frameId)\n})\ncontents.postMessage(channel, message, [transfer])Send a message to the renderer process, optionally transferring ownership of zero or more [MessagePortMain][] objects.
The transferred MessagePortMain objects will be available in the renderer process by accessing the ports property of the emitted event. When they arrive in the renderer, they will be native DOM MessagePort objects.
Например:
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\ncontents.enableDeviceEmulation(parameters)parametersscreenPosition String - Specify the screen type to emulate (default: desktop):desktop - Desktop screen type.mobile - Mobile screen type.screenSize Size - Set the emulated screen size (screenPosition == mobile).viewPosition Point - Position the view on the screen (screenPosition == mobile) (default: { x: 0, y: 0 }).deviceScaleFactor Integer - Set the device scale factor (if zero defaults to original device scale factor) (default: 0).viewSize Size - Set the emulated view size (empty means no override)scale Float - Scale of emulated view inside available space (not in fit to view mode) (default: 1).Enable device emulation with the given parameters.
\ncontents.disableDeviceEmulation()Disable device emulation enabled by webContents.enableDeviceEmulation.
contents.sendInputEvent(inputEvent)inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventSends an input event to the page. Note: The BrowserWindow containing the contents needs to be focused for sendInputEvent() to work.
contents.beginFrameSubscription([onlyDirty ,]callback)onlyDirty Boolean (опиционально) - по умолчанию false.callback Functionimage NativeImagedirtyRect RectangleBegin subscribing for presentation events and captured frames, the callback will be called with callback(image, dirtyRect) when there is a presentation event.
The image is an instance of NativeImage that stores the captured frame.
The dirtyRect is an object with x, y, width, height properties that describes which part of the page was repainted. If onlyDirty is set to true, image will only contain the repainted area. onlyDirty defaults to false.
contents.endFrameSubscription()End subscribing for frame presentation events.
\ncontents.startDrag(item)itemfile String - The path to the file being dragged.files String - The paths to the files being dragged. (files will override file field)icon NativeImage | String - The image must be non-empty on macOS.Sets the item as dragging item for current drag-drop operation, file is the absolute path of the file to be dragged, and icon is the image showing under the cursor when dragging.
contents.savePage(fullPath, saveType)fullPath String - The full file path.saveType String - Specify the save type.HTMLOnly - Save only the HTML of the page.HTMLComplete - Save complete-html page.MHTML - Save complete-html page as MHTML.Returns Promise<void> - resolves if the page is saved.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.loadURL('https://github.com')\n\nwin.webContents.on('did-finish-load', async () => {\n win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {\n console.log('Page was saved successfully.')\n }).catch(err => {\n console.log(err)\n })\n})\ncontents.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\ncontents.isOffscreen()Returns Boolean - Indicates whether offscreen rendering is enabled.
contents.startPainting()If offscreen rendering is enabled and not painting, start painting.
\ncontents.stopPainting()If offscreen rendering is enabled and painting, stop painting.
\ncontents.isPainting()Returns Boolean - If offscreen rendering is enabled returns whether it is currently painting.
contents.setFrameRate(fps)fps IntegerIf offscreen rendering is enabled sets the frame rate to the specified number. Only values between 1 and 240 are accepted.
\ncontents.getFrameRate()Returns Integer - If offscreen rendering is enabled returns the current frame rate.
contents.invalidate()Schedules a full repaint of the window this web contents is in.
\nIf offscreen rendering is enabled invalidates the frame and generates a new one through the 'paint' event.
contents.getWebRTCIPHandlingPolicy()Returns String - Returns the WebRTC IP Handling Policy.
contents.setWebRTCIPHandlingPolicy(policy)policy String - Specify the WebRTC IP Handling Policy.default - Exposes user's public and local IPs. This is the default behavior. When this policy is used, WebRTC has the right to enumerate all interfaces and bind them to discover public interfaces.default_public_interface_only - Exposes user's public IP, but does not expose user's local IP. When this policy is used, WebRTC should only use the default route used by http. This doesn't expose any local addresses.default_public_and_private_interfaces - Exposes user's public and local IPs. When this policy is used, WebRTC should only use the default route used by http. This also exposes the associated default private address. Default route is the route chosen by the OS on a multi-homed endpoint.disable_non_proxied_udp - Does not expose public or local IPs. When this policy is used, WebRTC should only use TCP to contact peers or servers unless the proxy server supports UDP.Setting the WebRTC IP handling policy allows you to control which IPs are exposed via WebRTC. See BrowserLeaks for more details.
\ncontents.getOSProcessId()Returns Integer - The operating system pid of the associated renderer process.
contents.getProcessId()Returns Integer - The Chromium internal pid of the associated renderer. Can be compared to the frameProcessId passed by frame specific navigation events (e.g. did-frame-navigate)
contents.takeHeapSnapshot(filePath)filePath String - Path to the output file.Возвращает Promise<void>, который указывает успешно ли создан снимок.
Делает снимок кучи V8 и сохраняет его в filePath.
contents.getBackgroundThrottling()Returns Boolean - whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
contents.setBackgroundThrottling(allowed)allowed BooleanControls whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
\ncontents.getType()Returns String - the type of the webContent. Can be backgroundPage, window, browserView, remote, webview or offscreen.
contents.setImageAnimationPolicy(policy)policy String - может быть завершено animate, отменено animateOnce или прервано noAnimation.Sets the image animation policy for this webContents. The policy only affects new images, existing images that are currently being animated are unaffected. This is a known limitation in Chromium, you can force image animation to be recalculated with img.src = img.src which will result in no network traffic but will update the animation policy.
This corresponds to the animationPolicy accessibility feature in Chromium.
\ncontents.audioMutedA Boolean property that determines whether this page is muted.
contents.userAgentA String property that determines the user agent for this web page.
contents.zoomLevelA Number property that determines the zoom level for this web contents.
The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
contents.zoomFactorA Number property that determines the zoom factor for this web contents.
The zoom factor is the zoom percent divided by 100, so 300% = 3.0.
\ncontents.frameRateAn Integer property that sets the frame rate of the web contents to the specified number. Only values between 1 and 240 are accepted.
Only applicable if offscreen rendering is enabled.
\ncontents.id Только чтениеA Integer representing the unique ID of this WebContents. Each ID is unique among all WebContents instances of the entire Electron application.
contents.session Только чтениеA Session used by this webContents.
contents.hostWebContents Только чтениеA WebContents instance that might own this WebContents.
contents.devToolsWebContents Только чтениеA WebContents | null property that represents the of DevTools WebContents associated with a given WebContents.
Note: Users should never store this object because it may become null when the DevTools has been closed.
contents.debugger Только чтениеA Debugger instance for this webContents.
contents.backgroundThrottlingA Boolean property that determines whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
contents.mainFrame Только чтениеA WebFrameMain property that represents the top frame of the page's frame hierarchy.
If you want to embed (third-party) web content in an Electron BrowserWindow, there are three options available to you: <iframe> tags, <webview> tags, and BrowserViews. Each one offers slightly different functionality and is useful in different situations. To help you choose between these, this guide explains the differences and capabilities of each option.
Iframe в Electron ведет себя так же, как iframe в обычных браузерах. An <iframe> element in your page can show external web pages, provided that their Content Security Policy allows it. To limit the number of capabilities of a site in an <iframe> tag, it is recommended to use the sandbox attribute and only allow the capabilities you want to support.
\n\nImportant Note: we do not recommend you to use WebViews, as this tag undergoes dramatic architectural changes that may affect stability of your application. Consider switching to alternatives, like
\niframeand Electron'sBrowserView, or an architecture that avoids embedded content by design.
WebViews are based on Chromium's WebViews and are not explicitly supported by Electron. We do not guarantee that the WebView API will remain available in future versions of Electron. To use <webview> tags, you will need to set webviewTag to true in the webPreferences of your BrowserWindow.
WebView is a custom element (<webview>) that will only work inside Electron. They are implemented as an \"out-of-process iframe\". This means that all communication with the <webview> is done asynchronously using IPC. The <webview> element has many custom methods and events, similar to webContents, that provide you with greater control over the content.
Compared to an <iframe>, <webview> tends to be slightly slower but offers much greater control in loading and communicating with the third-party content and handling various events.
BrowserViews are not a part of the DOM - instead, they are created in and controlled by your Main process. They are simply another layer of web content on top of your existing window. This means that they are completely separate from your own BrowserWindow content and their position is not controlled by the DOM or CSS. Instead, it is controlled by setting the bounds in the Main process.
BrowserViews offer the greatest control over their contents, since they implement the webContents similarly to how the BrowserWindow does it. However, as BrowserViews are not a part of your DOM, but are rather overlaid on top of them, you will have to manage their position manually.
\n\nНастройка отображения текущей веб-страницы.
\n
Процесс: Графический
\nwebFrame export of the Electron module is an instance of the WebFrame class representing the top frame of the current BrowserWindow. Sub-frames can be retrieved by certain properties and methods (e.g. webFrame.firstChild).
Пример масштабирования текущей страницы до 200%.
\nconst { webFrame } = require('electron')\n\nwebFrame.setZoomFactor(2)\nThe WebFrame class has the following instance methods:
webFrame.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\nThe factor must be greater than 0.0.
\nwebFrame.getZoomFactor()Возвращает Number - текущего маштаба.
webFrame.setZoomLevel(level)level Number - уровень увеличения.Изменяет уровень масштаба на указанный уровень. Оригинальный размер 0 и каждое приращение выше или ниже представляет масштабирование 20% больше или меньше, по умолчанию ограничение на 300% и 50% от исходного размера, соответственно.
\n\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
webFrame.getZoomLevel()Возвращает Number - текущего уровня маштаба.
webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberУстанавливает максимальный и минимальный уровень пинч-маштабирования.
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\nwebFrame.setVisualZoomLevelLimits(1, 3)\n
\n\nNOTE: Visual zoom only applies to pinch-to-zoom behavior. Cmd+/-/0 zoom shortcuts are controlled by the 'zoomIn', 'zoomOut', and 'resetZoom' MenuItem roles in the application Menu. To disable shortcuts, manually define the Menu and omit zoom roles from the definition.
\n
webFrame.setSpellCheckProvider(language, provider)language StringproviderspellCheck Functionwords[]callback FunctionmisspeltWords[]Задает поставщика для проверки орфографии в полях ввода и текстовых областях.
\nIf you want to use this method you must disable the builtin spellchecker when you construct the window.
\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: false\n }\n})\nThe provider must be an object that has a spellCheck method that accepts an array of individual words for spellchecking. The spellCheck function runs asynchronously and calls the callback function with an array of misspelt words when complete.
Пример использования node-spellchecker как поставщик:
\nconst { webFrame } = require('electron')\nconst spellChecker = require('spellchecker')\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck (words, callback) {\n setTimeout(() => {\n const spellchecker = require('spellchecker')\n const misspelled = words.filter(x => spellchecker.isMisspelled(x))\n callback(misspelled)\n }, 0)\n }\n})\nwebFrame.insertCSS(css)css String - CSS source code.Returns String - A key for the inserted CSS that can later be used to remove the CSS via webFrame.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\nwebFrame.removeInsertedCSS(key)key StringRemoves the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from webFrame.insertCSS(css).
webFrame.insertText(text)text StringВставляет text в элемент с фокусом.
webFrame.executeJavaScript(code[, userGesture, callback])code StringuserGesture Boolean (опиционально) - по умолчанию false.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.result Anyerror ErrorReturns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
Вычисляет code на странице.
В окне браузера некоторые HTML API как requestFullScreen может быть только вызван жестом пользователя. Указание userGesture как true снимает это ограничение.
webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])worldId Integer - The ID of the world to run the javascript in, 0 is the default main world (where content runs), 999 is the world used by Electron's contextIsolation feature. Accepts values in the range 1..536870911.scripts WebSource[]userGesture Boolean (опиционально) - по умолчанию false.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.result Anyerror ErrorReturns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution could not start.
Works like executeJavaScript but evaluates scripts in an isolated context.
Note that when the execution of script fails, the returned promise will not reject and the result would be undefined. This is because Chromium does not dispatch errors of isolated worlds to foreign worlds.
webFrame.setIsolatedWorldInfo(worldId, info)worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electrons contextIsolation feature. Chrome extensions reserve the range of IDs in [1 << 20, 1 << 29). You can provide any integer here.infosecurityOrigin String (optional) - Security origin for the isolated world.csp String (optional) - Content Security Policy for the isolated world.name String (optional) - Name for isolated world. Useful in devtools.Set the security origin, content security policy and name of the isolated world. Note: If the csp is specified, then the securityOrigin also has to be specified.
webFrame.getResourceUsage()Возвращает Object:
images MemoryUsageDetailsscripts MemoryUsageDetailscssStyleSheets MemoryUsageDetailsxslStyleSheets MemoryUsageDetailsfonts MemoryUsageDetailsother MemoryUsageDetailsВозвращает объект, описывающий сведения об использовании Blink внутренней памяти кэшей.
\nconst { webFrame } = require('electron')\nconsole.log(webFrame.getResourceUsage())\nЭто будет генерировать:
\n{\n images: {\n count: 22,\n size: 2549,\n liveSize: 2542\n },\n cssStyleSheets: { /* то же самое с \"images\" */ },\n xslStyleSheets: { /* то же самое с \"images\" */ },\n fonts: { /* то же самое с \"images\" */ },\n other: { /* то же самое с \"images\" */ }\n}\nwebFrame.clearCache()Пытается освободить память, которая больше не используется (например, изображения из предыдущей навигации).
\nОбратите внимание, что безрассудный вызов этого метода вероятно замедлит Electron, поскольку ему придется чистить кэши даже если они уже пустые, так что этот метод следует вызывать только в случае, когда вы уверены, что страница стала использовать меньше памяти (например, произошел переход с супер-тяжёлой страницы на лёгкую без ожидаемого возврата обратно на тяжёлую).
\nwebFrame.getFrameForSelector(selector)selector String - CSS selector for a frame element.Returns WebFrame - The frame element in webFrame's document selected by selector, null would be returned if selector does not select a frame or if the frame is not in the current renderer process.
webFrame.findFrameByName(name)name StringReturns WebFrame - A child of webFrame with the supplied name, null would be returned if there's no such frame or if the frame is not in the current renderer process.
webFrame.findFrameByRoutingId(routingId)routingId Integer - An Integer representing the unique frame id in the current renderer process. Routing IDs can be retrieved from WebFrame instances (webFrame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate)Returns WebFrame - that has the supplied routingId, null if not found.
webFrame.isWordMisspelled(word)word String - The word to be spellchecked.Returns Boolean - True if the word is misspelled according to the built in spellchecker, false otherwise. If no dictionary is loaded, always return false.
webFrame.getWordSuggestions(word)word String - The misspelled word.Returns String[] - A list of suggested words for a given word. If the word is spelled correctly, the result will be empty.
webFrame.top Только чтениеA WebFrame | null representing top frame in frame hierarchy to which webFrame belongs, the property would be null if top frame is not in the current renderer process.
webFrame.opener Только чтениеA WebFrame | null representing the frame which opened webFrame, the property would be null if there's no opener or opener is not in the current renderer process.
webFrame.parent Только чтениеA WebFrame | null representing parent frame of webFrame, the property would be null if webFrame is top or parent is not in the current renderer process.
webFrame.firstChild Только чтениеA WebFrame | null representing the first child frame of webFrame, the property would be null if webFrame has no children or if first child is not in the current renderer process.
webFrame.nextSibling Только чтениеA WebFrame | null representing next sibling frame, the property would be null if webFrame is the last frame in its parent or if the next sibling is not in the current renderer process.
webFrame.routingId Только чтениеAn Integer representing the unique frame id in the current renderer process. Distinct WebFrame instances that refer to the same underlying frame will have the same routingId.
\n\nControl web pages and iframes.
\n
Процесс: Основной
\nThe webFrameMain module can be used to lookup frames across existing WebContents instances. Navigation events are the common use case.
const { BrowserWindow, webFrameMain } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://twitter.com')\n\nwin.webContents.on(\n 'did-frame-navigate',\n (event, url, isMainFrame, frameProcessId, frameRoutingId) => {\n const frame = webFrameMain.fromId(frameProcessId, frameRoutingId)\n if (frame) {\n const code = 'document.body.innerHTML = document.body.innerHTML.replaceAll(\"heck\", \"h*ck\")'\n frame.executeJavaScript(code)\n }\n }\n)\nYou can also access frames of existing pages by using the mainFrame property of WebContents.
const { BrowserWindow } = require('electron')\n\nasync function main () {\n const win = new BrowserWindow({ width: 800, height: 600 })\n await win.loadURL('https://reddit.com')\n\n const youtubeEmbeds = win.webContents.mainFrame.frames.filter((frame) => {\n try {\n const url = new URL(frame.url)\n return url.host === 'www.youtube.com'\n } catch {\n return false\n }\n })\n\n console.log(youtubeEmbeds)\n}\n\nmain()\nThese methods can be accessed from the webFrameMain module:
webFrameMain.fromId(processId, routingId)processId Integer - An Integer representing the internal ID of the process which owns the frame.routingId Integer - An Integer representing the unique frame ID in the current renderer process. Routing IDs can be retrieved from WebFrameMain instances (frame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate).Returns WebFrameMain | undefined - A frame with the given process and routing IDs, or undefined if there is no WebFrameMain associated with the given IDs.
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emitted when the document is loaded.
\nframe.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (опиционально) - по умолчанию false.Returns Promise<unknown> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
Вычисляет code на странице.
В окне браузера некоторые HTML API как requestFullScreen может быть только вызван жестом пользователя. Указание userGesture как true снимает это ограничение.
frame.reload()Returns boolean - Whether the reload was initiated successfully. Only results in false when the frame has no history.
frame.send(channel, ...args)channel String (Строка)...args any[]Send an asynchronous message to the renderer process via channel, along with arguments. Arguments will be serialized with the [Structured Clone Algorithm][SCA], just like [postMessage][], so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
The renderer process can handle the message by listening to channel with the ipcRenderer module.
frame.postMessage(channel, message, [transfer])Send a message to the renderer process, optionally transferring ownership of zero or more [MessagePortMain][] objects.
The transferred MessagePortMain objects will be available in the renderer process by accessing the ports property of the emitted event. When they arrive in the renderer, they will be native DOM MessagePort objects.
Например:
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nframe.url ReadonlyA string representing the current URL of the frame.
frame.top ReadonlyA WebFrameMain | null representing top frame in the frame hierarchy to which frame belongs.
frame.parent ReadonlyA WebFrameMain | null representing parent frame of frame, the property would be null if frame is the top frame in the frame hierarchy.
frame.frames ReadonlyA WebFrameMain[] collection containing the direct descendents of frame.
frame.framesInSubtree ReadonlyA WebFrameMain[] collection containing every frame in the subtree of frame, including itself. This can be useful when traversing through all frames.
frame.frameTreeNodeId ReadonlyAn Integer representing the id of the frame's internal FrameTreeNode instance. This id is browser-global and uniquely identifies a frame that hosts content. The identifier is fixed at the creation of the frame and stays constant for the lifetime of the frame. When the frame is removed, the id is not used again.
frame.name ReadonlyA String representing the frame name.
frame.osProcessId ReadonlyAn Integer representing the operating system pid of the process which owns this frame.
frame.processId ReadonlyAn Integer representing the Chromium internal pid of the process which owns this frame. This is not the same as the OS process ID; to read that use frame.osProcessId.
frame.routingId ReadonlyAn Integer representing the unique frame id in the current renderer process. Distinct WebFrameMain instances that refer to the same underlying frame will have the same routingId.
frame.visibilityState Только чтениеA string representing the visibility state of the frame.
See also how the Page Visibility API is affected by other Electron APIs.
", "title": "webFrameMain", "description": "Control web pages and iframes." }, "/docs/api/web-request": { "locale": "ru-RU", "slug": "web-request", "href": "/docs/api/web-request", "crowdinFileId": "256405", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-request.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nIntercept and modify the contents of a request at various stages of its lifetime.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Instances of the WebRequest class are accessed by using the webRequest property of a Session.
The methods of WebRequest accept an optional filter and a listener. The listener will be called with listener(details) when the API's event has happened. The details object describes the request.
⚠️ Only the last attached listener will be used. Passing null as listener will unsubscribe from the event.
The filter object has a urls property which is an Array of URL patterns that will be used to filter out the requests that do not match the URL patterns. If the filter is omitted then all requests will be matched.
For certain events the listener is passed with a callback, which should be called with a response object when listener has done its work.
An example of adding User-Agent header for requests:
const { session } = require('electron')\n\n// Modify the user agent for all requests to the following urls.\nconst filter = {\n urls: ['https://*.github.com/*', '*://electron.github.io']\n}\n\nsession.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {\n details.requestHeaders['User-Agent'] = 'MyAgent'\n callback({ requestHeaders: details.requestHeaders })\n})\nДля экземпляров WebRequest доступны следующие методы:
webRequest.onBeforeRequest([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (опционально)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleuploadData UploadData[]callback Functionresponse Objectcancel Boolean (опционально)redirectURL String (optional) - The original request is prevented from being sent or completed and is instead redirected to the given URL.The listener will be called with listener(details, callback) when a request is about to occur.
uploadData является массивом объектов UploadData.
The callback has to be called with an response object.
Some examples of valid urls:
'http://foo:1234/'\n'http://foo.com/'\n'http://foo:1234/bar'\n'*://*/*'\n'*://example.com/*'\n'*://example.com/foo/*'\n'http://*.foo:1234/'\n'file://foo:1234/bar'\n'http://foo:*/'\n'*://www.foo.com/'\nwebRequest.onBeforeSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (опционально)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders Record<string, string>callback FunctionbeforeSendResponse Objectcancel Boolean (опционально)requestHeaders Record<string, string | string[]> (optional) - When provided, request will be made with these headers.The listener will be called with listener(details, callback) before sending an HTTP request, once the request headers are available. This may occur after a TCP connection is made to the server, but before any http data is sent.
The callback has to be called with a response object.
webRequest.onSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (опционально)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders Record<string, string>The listener will be called with listener(details) just before a request is going to be sent to the server, modifications of previous onBeforeSendHeaders response are visible by the time this listener is fired.
webRequest.onHeadersReceived([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (опционально)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublestatusLinestatusCode IntegerresponseHeaders Record<string, string[]> (optional)callback FunctionheadersReceivedResponse Objectcancel Boolean (опционально)responseHeaders Record<string, string | string[]> (optional) - When provided, the server is assumed to have responded with these headers.statusLine String (optional) - Should be provided when overriding responseHeaders to change header status otherwise original response header's status will be used.The listener will be called with listener(details, callback) when HTTP response headers of a request have been received.
The callback has to be called with a response object.
webRequest.onResponseStarted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (опционально)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache Boolean - Indicates whether the response was fetched from disk cache.statusCode IntegerstatusLineThe listener will be called with listener(details) when first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.
webRequest.onBeforeRedirect([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (опционально)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleredirectURL StringstatusCode IntegerstatusLineip String (optional) - The server IP address that the request was actually sent to.fromCache BooleanresponseHeaders Record<string, string[]> (optional)The listener will be called with listener(details) when a server initiated redirect is about to occur.
webRequest.onCompleted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (опционально)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache BooleanstatusCode IntegerstatusLineerrorThe listener will be called with listener(details) when a request is completed.
webRequest.onErrorOccurred([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Integerurl Stringmethod StringwebContentsId Integer (опционально)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublefromCache Booleanerror String - The error description.The listener will be called with listener(details) when an error occurs.
urls String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.code Stringurl String (optional)startLine Integer (optional) - Default is 1.<webview>Electron's webview tag is based on Chromium's webview, which is undergoing dramatic architectural changes. This impacts the stability of webviews, including rendering, navigation, and event routing. We currently recommend to not use the webview tag and to consider alternatives, like iframe, Electron's BrowserView, or an architecture that avoids embedded content altogether.
By default the webview tag is disabled in Electron >= 5. You need to enable the tag by setting the webviewTag webPreferences option when constructing your BrowserWindow. For more information see the BrowserWindow constructor docs.
\n\nDisplay external web content in an isolated frame and process.
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Use the webview tag to embed 'guest' content (such as web pages) in your Electron app. The guest content is contained within the webview container. An embedded page within your app controls how the guest content is laid out and rendered.
Unlike an 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. Note: Most methods called on the webview from the host page require a synchronous call to the main process.
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:
<webview id=\"foo\" src=\"https://www.github.com/\" style=\"display:inline-flex; width:640px; height:480px\"></webview>\nIf 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:
<script>\n onload = () => {\n const webview = document.querySelector('webview')\n const indicator = document.querySelector('.indicator')\n\n const loadstart = () => {\n indicator.innerText = 'loading...'\n }\n\n const loadstop = () => {\n indicator.innerText = ''\n }\n\n webview.addEventListener('did-start-loading', loadstart)\n webview.addEventListener('did-stop-loading', loadstop)\n }\n</script>\nUnder the hood webview is implemented with Out-of-Process iframes (OOPIFs). The webview tag is essentially a custom element using shadow DOM to wrap an iframe element inside it.
So the behavior of webview is very similar to a cross-domain iframe, as examples:
webview, the page focus will move from the embedder frame to webview.webview.webview are asynchronous.Please note that the webview tag's style uses display:flex; internally to ensure the child iframe element fills the full height and width of its webview container when used with traditional and flexbox layouts. Please do not overwrite the default display:flex; CSS property, unless specifying display:inline-flex; for inline layout.
The webview tag has the following attributes:
src<webview src=\"https://www.github.com/\"></webview>\nA String representing 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!.
nodeintegration<webview src=\"http://www.google.com/\" nodeintegration></webview>\nA Boolean. When this attribute is present the guest page in webview will have node integration and can use node APIs like require and process to access low level system resources. Node integration is disabled by default in the guest page.
nodeintegrationinsubframes<webview src=\"http://www.google.com/\" nodeintegrationinsubframes></webview>\nA Boolean for the experimental option for enabling NodeJS support in sub-frames such as iframes inside the webview. All your preloads will load for every iframe, you can use process.isMainFrame to determine if you are in the main frame or not. This option is disabled by default in the guest page.
plugins<webview src=\"https://www.github.com/\" plugins></webview>\nA Boolean. When this attribute is present the guest page in webview will be able to use browser plugins. Plugins are disabled by default.
предварительная загрузка<!-- from a file -->\n<webview src=\"https://www.github.com/\" preload=\"./test.js\"></webview>\n<!-- or if you want to load from an asar archive -->\n<webview src=\"https://www.github.com/\" preload=\"./app.asar/test.js\"></webview>\nA String that specifies a script that will be loaded before other scripts run in the guest page. Протокол URL скрипта должен быть file: (даже при использовании asar: архивов), потому что он будет загружен \"под капотом\" в узле require, который обрабатывает asar: архивы как виртуальные каталоги.
When the guest page doesn't have node integration this script will still have access to all Node APIs, but global objects injected by Node will be deleted after this script has finished executing.
\nNote: This option will appear as preloadURL (not preload) in the webPreferences specified to the will-attach-webview event.
httpreferrer<webview src=\"https://www.github.com/\" httpreferrer=\"http://cheng.guru\"></webview>\nA String that sets the referrer URL for the guest page.
useragent<webview src=\"https://www.github.com/\" useragent=\"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko\"></webview>\nA String that sets the user agent for the guest page before the page is navigated to. Once the page is loaded, use the setUserAgent method to change the user agent.
disablewebsecurity<webview src=\"https://www.github.com/\" disablewebsecurity></webview>\nA Boolean. When this attribute is present the guest page will have web security disabled. Web security is enabled by default.
partition<webview src=\"https://github.com\" partition=\"persist:github\"></webview>\n<webview src=\"https://electronjs.org\" partition=\"electron\"></webview>\nA String that sets the session used by the page. If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. если нет persist: префикса, страница будет использовать сеанс в памяти. При присваивании одинаковой partition, разные страницы могут иметь одинаковую сессию. If the partition is unset then default session of the app will be used.
This value can only be modified before the first navigation, since the session of an active renderer process cannot change. Subsequent attempts to modify the value will fail with a DOM exception.
\nallowpopups<webview src=\"https://www.github.com/\" allowpopups></webview>\nA Boolean. When this attribute is present the guest page will be allowed to open new windows. Popups are disabled by default.
webpreferences<webview src=\"https://github.com\" webpreferences=\"allowRunningInsecureContent, javascript=no\"></webview>\nA String which is a comma separated list of strings which specifies the web preferences to be set on the webview. The full list of supported preference strings can be found in BrowserWindow.
The string follows the same format as the features string in window.open. A name by itself is given a true boolean value. A preference can be set to another value by including an =, followed by the value. Special values yes and 1 are interpreted as true, while no and 0 are interpreted as false.
enableblinkfeatures<webview src=\"https://www.github.com/\" enableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be enabled separated by ,. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
disableblinkfeatures<webview src=\"https://www.github.com/\" disableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be disabled separated by ,. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
The webview tag has the following methods:
Note: The webview element must be loaded before using the methods.
\nПример
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('dom-ready', () => {\n webview.openDevTools()\n})\n<webview>.loadURL(url[, options])url URLoptions Object (опционально)httpReferrer (String | Referrer) (optional) - An HTTP Referrer url.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url is a data url and needs to load other files.Returns Promise<void> - The promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load).
Loads the url in the webview, the url must contain the protocol prefix, e.g. the http:// or file://.
<webview>.downloadURL(url)url StringInitiates a download of the resource at url without navigating.
<webview>.getURL()Returns String - The URL of guest page.
<webview>.getTitle()Returns String - The title of guest page.
<webview>.isLoading()Returns Boolean - Whether guest page is still loading resources.
<webview>.isLoadingMainFrame()Returns Boolean - Whether the main frame (and not just iframes or frames within it) is still loading.
<webview>.isWaitingForResponse()Returns Boolean - Whether the guest page is waiting for a first-response for the main resource of the page.
<webview>.stop()Stops any pending navigation.
\n<webview>.reload()Reloads the guest page.
\n<webview>.reloadIgnoringCache()Reloads the guest page and ignores cache.
\n<webview>.canGoBack()Returns Boolean - Whether the guest page can go back.
<webview>.canGoForward()Returns Boolean - Whether the guest page can go forward.
<webview>.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the guest page can go to offset.
<webview>.clearHistory()Clears the navigation history.
\n<webview>.goBack()Makes the guest page go back.
\n<webview>.goForward()Makes the guest page go forward.
\n<webview>.goToIndex(index)index IntegerNavigates to the specified absolute index.
\n<webview>.goToOffset(offset)offset IntegerNavigates to the specified offset from the \"current entry\".
\n<webview>.isCrashed()Returns Boolean - Whether the renderer process has crashed.
<webview>.setUserAgent(userAgent)userAgent StringOverrides the user agent for the guest page.
\n<webview>.getUserAgent()Returns String - The user agent for guest page.
<webview>.insertCSS(css)css StringReturns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via <webview>.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\n<webview>.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from <webview>.insertCSS(css).
<webview>.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (optional) - Default false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Вычисляет code на странице. If userGesture is set, it will create the user gesture context in the page. HTML APIs like requestFullScreen, which require user action, can take advantage of this option for automation.
<webview>.openDevTools()Opens a DevTools window for guest page.
\n<webview>.closeDevTools()Closes the DevTools window of guest page.
\n<webview>.isDevToolsOpened()Returns Boolean - Whether guest page has a DevTools window attached.
<webview>.isDevToolsFocused()Returns Boolean - Whether DevTools window of guest page is focused.
<webview>.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y) of guest page.
<webview>.inspectSharedWorker()Opens the DevTools for the shared worker context present in the guest page.
\n<webview>.inspectServiceWorker()Opens the DevTools for the service worker context present in the guest page.
\n<webview>.setAudioMuted(muted)muted BooleanSet guest page muted.
\n<webview>.isAudioMuted()Returns Boolean - Whether guest page has been muted.
<webview>.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
<webview>.undo()Executes editing command undo in page.
<webview>.redo()Executes editing command redo in page.
<webview>.cut()Executes editing command cut in page.
<webview>.copy()Executes editing command copy in page.
<webview>.paste()Executes editing command paste in page.
<webview>.pasteAndMatchStyle()Executes editing command pasteAndMatchStyle in page.
<webview>.delete()Executes editing command delete in page.
<webview>.selectAll()Executes editing command selectAll in page.
<webview>.unselect()Executes editing command unselect in page.
<webview>.replace(text)text StringExecutes editing command replace in page.
<webview>.replaceMisspelling(text)text StringExecutes editing command replaceMisspelling in page.
<webview>.insertText(text)text StringВозвращает Promise<void>
Вставляет text в элемент с фокусом.
<webview>.findInPage(text[, options])text String - Content to be searched, must not be empty.options Object (опционально)forward Boolean (optional) - Whether to search forward or backward, defaults to true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Defaults to false.matchCase Boolean (optional) - Whether search should be case-sensitive, defaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. The result of the request can be obtained by subscribing to found-in-page event.
<webview>.stopFindInPage(action)action String - Specifies the action to take place when ending <webview>.findInPage request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webview with the provided action.
<webview>.print([options])options Object (опционально)silent Boolean (optional) - Don't ask user for print settings. По умолчанию - false.printBackground Boolean (optional) - Prints the background color and image of the web page. По умолчанию - false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. По умолчанию - true.margins Object (опционально)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. По умолчанию - false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Can be simplex, shortEdge, or longEdge.dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.Возвращает Promise<void>
Prints webview's web page. Same as webContents.print([options]).
<webview>.printToPDF(options)options ObjectheaderFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin. and width in microns.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print. On macOS, only the first range is honored.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing heightprintBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Uint8Array> - Resolves with the generated PDF data.
Prints webview's web page as PDF, Same as webContents.printToPDF(options).
<webview>.capturePage([rect])rect Rectangle (optional) - The area of the page to be captured.Возвращает Promise<NativeImage> - разрешается с NativeImage
Захватывает снимок страницы в границах rect. Пропустив rect, будет сделан захват всей видимой страницы.
<webview>.send(channel, ...args)channel String (Строка)...args any[]Возвращает Promise<void>
Send an asynchronous message to renderer process via channel, you can also send arbitrary arguments. The renderer process can handle the message by listening to the channel event with the ipcRenderer module.
See webContents.send for examples.
\n<webview>.sendToFrame(frameId, channel, ...args)frameId [number, number] - [processId, frameId]channel String (Строка)...args any[]Возвращает Promise<void>
Send an asynchronous message to renderer process via channel, you can also send arbitrary arguments. The renderer process can handle the message by listening to the channel event with the ipcRenderer module.
See webContents.sendToFrame for examples.
\n<webview>.sendInputEvent(event)event MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventВозвращает Promise<void>
Sends an input event to the page.
See webContents.sendInputEvent for detailed description of event object.
<webview>.setZoomFactor(factor)factor Number - фактор увилечения.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\n<webview>.setZoomLevel(level)level Number - уровень увеличения.Изменяет уровень масштаба на указанный уровень. Оригинальный размер 0 и каждое приращение выше или ниже представляет масштабирование 20% больше или меньше, по умолчанию ограничение на 300% и 50% от исходного размера, соответственно. The formula for this is scale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
<webview>.getZoomFactor()Returns Number - the current zoom factor.
<webview>.getZoomLevel()Returns Number - the current zoom level.
<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberВозвращает Promise<void>
Устанавливает максимальный и минимальный уровень пинч-маштабирования.
\n<webview>.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\n<webview>.getWebContentsId()Returns Number - The WebContents ID of this webview.
The following DOM events are available to the webview tag:
Возвращает:
\nurl StringisMainFrame BooleanFired when a load has committed. This includes navigation within the current document as well as subframe document-level loads, but does not include asynchronous resource loads.
\nFired when the navigation is done, i.e. the spinner of the tab will stop spinning, and the onload event is dispatched.
Возвращает:
\nerrorCode IntegererrorDescriptionvalidatedURLisMainFrame BooleanThis event is like did-finish-load, but fired when the load failed or was cancelled, e.g. window.stop() is invoked.
Возвращает:
\nisMainFrame BooleanFired when a frame has done navigation.
\nCorresponds to the points in time when the spinner of the tab starts spinning.
\nCorresponds to the points in time when the spinner of the tab stops spinning.
\nFired when attached to the embedder web contents.
\nFired when document in the given frame is loaded.
\nВозвращает:
\ntitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when title is synthesized from file url.
Возвращает:
\nfavicons String[] - Array of URLs.Fired when page receives favicon urls.
\nFired when page enters fullscreen triggered by HTML API.
\nFired when page leaves fullscreen triggered by HTML API.
\nВозвращает:
\nlevel Integer - The log level, from 0 to 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Integer - The line number of the source that triggered this console messagesourceId StringFired when the guest window logs a console message.
\nThe following example code forwards all log messages to the embedder's console without regard for log level or other properties.
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('console-message', (e) => {\n console.log('Guest page logged a message:', e.message)\n})\nВозвращает:
\nresult ObjectrequestId IntegeractiveMatchOrdinal Integer - Position of the active match.matches Integer - Number of Matches.selectionArea Rectangle - Coordinates of first match region.finalUpdate BooleanFired when a result is available for webview.findInPage request.
const webview = document.querySelector('webview')\nwebview.addEventListener('found-in-page', (e) => {\n webview.stopFindInPage('keepSelection')\n})\n\nconst requestId = webview.findInPage('test')\nconsole.log(requestId)\nВозвращает:
\nurl StringframeName Stringdisposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.options BrowserWindowConstructorOptions - The options which should be used for creating the new BrowserWindow.Fired when the guest page attempts to open a new browser window.
\nThe following example code opens the new url in system's default browser.
\nconst { shell } = require('electron')\nconst webview = document.querySelector('webview')\n\nwebview.addEventListener('new-window', async (e) => {\n const protocol = (new URL(e.url)).protocol\n if (protocol === 'http:' || protocol === 'https:') {\n await shell.openExternal(e.url)\n }\n})\nВозвращает:
\nurl StringEmitted when a user or the page wants to start navigation. It can happen when the window.location object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with APIs like <webview>.loadURL and <webview>.back.
It is also not emitted during in-page navigation, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Calling event.preventDefault() does NOT have any effect.
Возвращает:
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be true for in-page navigations.
Возвращает:
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nВозвращает:
\nurl StringEmitted when a navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Возвращает:
\nurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigations,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Возвращает:
\nisMainFrame Booleanurl StringEmitted when an in-page navigation happened.
\nWhen in-page navigation happens, the page URL changes but does not cause navigation outside of the page. Examples of this occurring are when anchor links are clicked or when the DOM hashchange event is triggered.
Fired when the guest page attempts to close itself.
\nThe following example code navigates the webview to about:blank when the guest attempts to close itself.
const webview = document.querySelector('webview')\nwebview.addEventListener('close', () => {\n webview.src = 'about:blank'\n})\nВозвращает:
\nframeId [number, number] - pair of [processId, frameId].channel String (Строка)args any[]Fired when the guest page has sent an asynchronous message to embedder page.
\nWith sendToHost method and ipc-message event you can communicate between guest page and embedder page:
// In embedder page.\nconst webview = document.querySelector('webview')\nwebview.addEventListener('ipc-message', (event) => {\n console.log(event.channel)\n // Prints \"pong\"\n})\nwebview.send('ping')\n// In guest page.\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('ping', () => {\n ipcRenderer.sendToHost('pong')\n})\nFired when the renderer process is crashed.
\nВозвращает:
\nname Stringversion StringFired when a plugin process is crashed.
\nFired when the WebContents is destroyed.
\nEmitted when media starts playing.
\nEmitted when media is paused or done playing.
\nВозвращает:
\nthemeColorEmitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nВозвращает:
\nurl StringEmitted when mouse moves over a link or the keyboard moves the focus to a link.
\nEmitted when DevTools is opened.
\nEmitted when DevTools is closed.
\nEmitted when DevTools is focused / opened.
", "title": "ТегThere are several ways to control how windows are created from trusted or untrusted content within a renderer. Windows can be created from the renderer in two ways:
\ntarget=_blankwindow.open()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.
When nativeWindowOpen is set to false, window.open instead results in the creation of a BrowserWindowProxy, 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 BrowserWindow in the main process by using webContents.setWindowOpenHandler() for renderer-created windows.
BrowserWindow constructor options are set by, in increasing precedence order: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Note that webContents.setWindowOpenHandler has final say and full privilege because it is invoked in the main process.
window.open(url[, frameName][, features])url StringframeName String (опционально)features String (опционально)Returns BrowserWindowProxy | Window
features is a comma-separated key-value list, following the standard format of the browser. Electron will parse BrowserWindowConstructorOptions out of this list where possible, for convenience. For full control and better ergonomics, consider using webContents.setWindowOpenHandler to customize the BrowserWindow creation.
A subset of WebPreferences can be set directly, unnested, from the features string: zoomFactor, nodeIntegration, preload, javascript, contextIsolation, and webviewTag.
Например:
\nwindow.open('https://github.com', '_blank', 'top=500,left=200,frame=false,nodeIntegration=no')\nПримечания:
\nwindow если она была выключена в родительском окне.window если она была включена в родительском окне.window если он был включен в родительском окне.features will be passed to any registered webContents's did-create-window event handler in the options argument.frameName follows the specification of windowName located in the native documentation.To customize or cancel the creation of the window, you can optionally set an override handler with webContents.setWindowOpenHandler() from the main 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.
Window example// main.js\nconst mainWindow = new BrowserWindow()\n\n// In this example, only windows with the `about:blank` url will be created.\n// All other urls will be blocked.\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url === 'about:blank') {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n frame: false,\n fullscreenable: false,\n backgroundColor: 'black',\n webPreferences: {\n preload: 'my-child-window-preload-script.js'\n }\n }\n }\n }\n return { action: 'deny' }\n})\n// renderer process (mainWindow)\nconst childWindow = window.open('', 'modal')\nchildWindow.document.write('<h1>Hello</h1>')\nBrowserWindowProxy example\n// main.js\nconst mainWindow = new BrowserWindow({\n webPreferences: { nativeWindowOpen: false }\n})\n\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url.startsWith('https://github.com/')) {\n return { action: 'allow' }\n }\n return { action: 'deny' }\n})\n\nmainWindow.webContents.on('did-create-window', (childWindow) => {\n // For example...\n childWindow.webContents.on('will-navigate', (e) => {\n e.preventDefault()\n })\n})\n// renderer.js\nconst windowProxy = window.open('https://github.com/', null, 'minimizable=false')\nwindowProxy.postMessage('hi', '*')\nIf your app runs with Electron 6.0.8 or later, you can now build it for Windows 10 on Arm. This considerably improves performance, but requires recompilation of any native modules used in your app. It may also require small fixups to your build and packaging scripts.
\nIf your app doesn't use any native modules, then it's really easy to create an Arm version of your app.
\nnode_modules вашего приложения пуст.set npm_config_arch=arm64 before running npm install/yarn install as usual.Lots of Windows-specific code contains if... else logic that selects between either the x64 or x86 architectures.
\nif (process.arch === 'x64') {\n // Do 64-bit thing...\n} else {\n // Do 32-bit thing...\n}\nIf you want to target arm64, logic like this will typically select the wrong architecture, so carefully check your application and build scripts for conditions like this. In custom build and packaging scripts, you should always check the value of npm_config_arch in the environment, rather than relying on the current process arch.
If you use native modules, you must make sure that they compile against v142 of the MSVC compiler (provided in Visual Studio 2017). You must also check that any pre-built .dll or .lib files provided or referenced by the native module are available for Windows on Arm.
To test your app, use a Windows on Arm device running Windows 10 (version 1903 or later). Make sure that you copy your application over to the target device - Chromium's sandbox will not work correctly when loading your application assets from a network location.
\nNode.js v12.9.0 or later is recommended. If updating to a new version of Node is undesirable, you can instead update npm's copy of node-gyp manually to version 5.0.2 or later, which contains the required changes to compile native modules for Arm.
\nVisual Studio 2017 (any edition) is required for cross-compiling native modules. You can download Visual Studio Community 2017 via Microsoft's Visual Studio Dev Essentials program. After installation, you can add the Arm-specific components by running the following from a Command Prompt:
\nvs_installer.exe ^\n--add Microsoft.VisualStudio.Workload.NativeDesktop ^\n--add Microsoft.VisualStudio.Component.VC.ATLMFC ^\n--add Microsoft.VisualStudio.Component.VC.Tools.ARM64 ^\n--add Microsoft.VisualStudio.Component.VC.MFC.ARM64 ^\n--includeRecommended\nSetting npm_config_arch=arm64 in the environment creates the correct arm64 .obj files, but the standard Developer Command Prompt for VS 2017 will use the x64 linker. To fix this:
vcvarsamd64_arm64.bat at the end instead of vcvarsamd64_x86.bat.If done successfully, the command prompt should print something similar to this on startup:
\n**********************************************************************\n** Visual Studio 2017 Developer Command Prompt v15.9.15\n** Copyright (c) 2017 Microsoft Corporation\n**********************************************************************\n[vcvarsall.bat] Environment initialized for: 'x64_arm64'\nIf you want to develop your application directly on a Windows on Arm device, substitute vcvarsx86_arm64.bat in Target so that cross-compilation can happen with the device's x86 emulation.
node.libBy default, node-gyp unpacks Electron's node headers and downloads the x86 and x64 versions of node.lib into %APPDATA%\\..\\Local\\node-gyp\\Cache, but it does not download the arm64 version (a fix for this is in development.) To fix this:
node.lib from https://electronjs.org/headers/v6.0.9/win-arm64/node.lib%APPDATA%\\..\\Local\\node-gyp\\Cache\\6.0.9\\arm64\\node.libSubstitute 6.0.9 for the version you're using.
After completing all of the above, open your cross-compilation command prompt and run set npm_config_arch=arm64. Then use npm install to build your project as normal. As with cross-compiling x86 modules, you may need to remove node_modules to force recompilation of native modules if they were previously compiled for another architecture.
Debugging native modules can be done with Visual Studio 2017 (running on your development machine) and corresponding Visual Studio Remote Debugger running on the target device. To debug:
\n.exe on the target device via the Command Prompt (passing --inspect-brk to pause it before any native modules are loaded)..pdb symbols under Debugging > Symbols.If you encounter a problem with this documentation, or if your app works when compiled for x86 but not for arm64, please file an issue with \"Windows on Arm\" in the title.
", "title": "Windows on ARM", "description": "" }, "/docs/tutorial/windows-store-guide": { "locale": "ru-RU", "slug": "windows-store-guide", "href": "/docs/tutorial/windows-store-guide", "crowdinFileId": "256273", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-store-guide.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "С выходом Windows 10, старый добрый исполнительный файл win32 обзавелся новым братом: универсальной платформой Windows (The Universal Windows Platform). Новый формат .appx не только позволяет применять различные новые API, как push-уведомления от Кортаны, но также значительно упрощает установку и обновления через Windows Store.
Microsoft developed a tool that compiles Electron apps as .appx packages, enabling developers to use some of the goodies found in the new application model. Этот гайд объясняет как его использовать - и какие возможности и ограничения присутствуют у пакета Electron AppX.
\"Юбилейное обновление\" Windows 10 (Windows 10 \"Anniversary Update\") позволяет запускать win32 .exe-файлы, запуская их вместе с виртуализованными файловой системой и реестром. Они оба создаются во время компиляции запуском приложения и установщика внутри контейнера Windows (Windows Container), позволяя Windows определить, какие именно изменения были внесены в операционную систему во время установки. Соединение исполнительного файла с виртуальными файловой системой и реестром позволяет Windows задействовать установку и деинсталляцию в одно касание (one-click installation / uninstallation).
Вдобавок, exe-файл запускается внутри appx модели - это означает, что он может использовать множество API, доступных универсальной платформе Windows (Universal Windows Platform). Для получения еще больших возможностей, приложение на Electron можно соединить с невидимым фоновым процессом UWP, запущенным вместе с exe-файлом - что-то типа напарника, который будет запускать фоновые процессы, получать push-уведомления или взаимодействовать с другими UWP приложениями.
Для компиляции любого существующего приложения на Electron, удостоверьтесь, что вы попадаете под следующие требования:
\nnode -v)После этого, установите electron-windows-store CLI:
npm install -g electron-windows-store\nУпакуйте приложение, используя electron-packager (или подобный инструмент). Удостоверьтесь, что вы удалили node_modules, которые не понадобятся вам в финальной версии приложения, так как любой неиспользуемый модуль в конечном счете увеличит размер вашего приложения.
Консольный вывод должен иметь примерный вид:
\n├── Ghost.exe\n├── LICENSE\n├── content_resources_200_percent.pak\n├── content_shell.pak\n├── d3dcompiler_47.dll\n├── ffmpeg.dll\n├── icudtl.dat\n├── libEGL.dll\n├── libGLESv2.dll\n├── locales\n│ ├── am.pak\n│ ├── ar.pak\n│ ├── [...]\n├── node.dll\n├── resources\n│ └── app.asar\n├── v8_context_snapshot.bin\n├── squirrel.exe\n└── ui_resources_200_percent.pak\nИз под PowerShell с расширенными разрешениями (откройте как \"Администратор\"), запустите electron-windows-store с обязательными параметрами, подав как входные, так и выводные директории, имя приложения и версию, и подтверждение, что node_modules будут сжаты.
electron-windows-store `\n --input-directory C:\\myelectronapp `\n --output-directory C:\\output\\myelectronapp `\n --package-version 1.0.0.0 `\n --package-name myelectronapp\nПосле запуска инструмент начнет работу: он принимает ваше приложение как ввод, сжимая node_modules. Затем, он архивирует ваше приложение как app.zip. Используя установщик и Windows Container, он создает \"расширенный\" AppX пакет - включая Windows Application Manifest (AppXManifest.xml), а также виртуальные файловую систему и реестр внутри выходной папки.
После создания файлов расширенной AppX, инструмент использует упаковщик приложений Windows - Windows App Packager (MakeAppx.exe) - чтобы из всех файлов создать пакет AppX в одном файле. Наконец, инструмент может быть использован для создания доверенного сертификата на вашем компьютере, чтобы подписывать новые пакеты AppX. С подписанным AppX пакетом, CLI также может автоматически установить пакет на вашу машину.
Чтобы запустить ваш пакет, вашим пользователям необходима Windows 10 с так называемым \"Юбилейным обновлением\" - дополнительная информация по обновлению Windows здесь.
\nВ отличие от традиционных UWP приложений, упакованные приложения должны пройти процесс ручной проверки, записаться на которую можно здесь. Тем временем, все пользователи смогут установить ваш пакет, кликнув по нему два раза, так что передача в магазин может быть не обязательной, если вы хотите более легкий способ установки. В управляемых средах (обычно на уровне предприятия), Add-AppxPackage PowerShell Cmdlet может использоваться для установки в автоматическом режиме.
Еще одним важным ограничением является то, что скомпилированный AppX пакет все еще содержит win32 запускаемый файл - как следствие, он не запустится на Xbox, Hololens или смартфонах.
\nВы можете соединить свое приложение с невидимым фоновым UWP процессом, который будет использовать функционал Windows 10 на полную - push-уведомления, интеграция Кортаны или живые тайлы в меню Пуск.
\nЧтобы проверить, как приложение на Electron использует этот процесс для отправки Toast-уведомлений и живых тайлов, посмотрите на пример от Microsoft.
\nЧтобы создать AppX пакет, electron-windows-store CLI использует шаблон, который должен подойти для большинства приложений на Electron. Однако, если вы используете кастомный установщик, или вы испытываете какие-либо проблемы с созданным пакетом, вы можете попытаться создать пакет с использованием компиляции с Windows контейнером, CLI установит и запустит ваше приложение в пустом Windows контейнере, чтобы определить, какие изменения ваше приложение вносит в операционную систему.
Перед запуском CLI в первый раз, вам нужно настроить \"Конвертер десктопных приложений Windows\" (\"Windows Desktop App Converter\"). Этот процесс займет пару минут, но не беспокойтесь - его нужно запустить лишь один раз. Загрузите Desktop App Converter здесь. Вы получите два файла: DesktopAppConverter.zip и BaseImage-14316.wim.
DesktopAppConverter.zip. Из под PowerShell с расширенными разрешениями (\"открыть как Администратор\", убедитесь, что политика запуска на вашей системе позволяет нам запускать все, что потребуется, использовав обход Set-ExecutionPolicy).BaseImage-14316.wim), вызвав .\\DesktopAppConverter.ps1 -Setup -BaseImage .\\BaseImage-14316.wim.После успешной установки вы можете перейти к компиляции вашего приложения.
", "title": "Руководство по распространению с помощью Windows Store", "description": "" }, "/docs/tutorial/windows-taskbar": { "locale": "ru-RU", "slug": "windows-taskbar", "href": "/docs/tutorial/windows-taskbar", "crowdinFileId": "256275", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-taskbar.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron имеет API для настройки значка приложения на панели задач Windows. This API supports both Windows-only features like creation of a JumpList, custom thumbnails and toolbars, icon overlays, and the so-called \"Flash Frame\" effect, and cross-platform features like recent documents and application progress.
Windows позволяет приложениям определять пользовательское контекстное меню, которое появляется, когда пользователи щелкают правой кнопкой мыши значок приложения на панели задач. Это контекстное меню называется JumpList. You specify custom actions in the Tasks category of JumpList, as quoted from MSDN:
\n\nПриложения определяют задачи, основанные как на функциях программы, так и на ключевых моментах, которые пользователь должен делать с ними. Задачи должны быть контекстно-свободными, в данном случае, приложению не потребуется запускать их для работы. Они также должны быть статистически наиболее распространенными действиями, которые обычный пользователь будет выполнять в приложении, например, составить сообщение электронной почты или открыть календарь в почтовой программе, создать новый документ в текстовом редакторе, запустить приложение в определенном режиме, или запустить одну из своих подкоманд. Приложение не должно загромождать меню с расширенными функциями, которые не требуются обычным пользователям или одноразовыми действиями, такими как регистрация. Не используйте задачи для рекламных материалов, таких как обновления или специальные предложения.
\nНастоятельно рекомендуется, чтобы список задач был статическим. Он должен оставаться неизменным независимо от состояния или статуса приложения. Хотя можно динамически изменять список, вы должны учитывать, что это может смутить пользователя, который не ожидает изменения этой части списка адресатов.
\n
\n\nПРИМЕЧАНИЕ: Скриншот выше является примером общих задач Internet Explorer
\n
В отличие от меню dock в macOS, которое является реальным меню, пользовательские задачи в Windows работают как ярлыки приложений. Например, когда пользователь нажимает на задачу, программа будет выполняться с заданными аргументами.
\nTo set user tasks for your application, you can use app.setUserTasks API.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app } = require('electron')\n\napp.setUserTasks([\n {\n program: process.execPath,\n arguments: '--new-window',\n iconPath: process.execPath,\n iconIndex: 0,\n title: 'New Window',\n description: 'Create a new window'\n }\n])\nTo clear your tasks list, you need to call app.setUserTasks with an empty array in the main.js file.
const { app } = require('electron')\n\napp.setUserTasks([])\n\n\nNOTE: The user tasks will still be displayed even after closing your application, so the icon and program path specified for a task should exist until your application is uninstalled.
\n
On Windows, you can add a thumbnail toolbar with specified buttons to a taskbar layout of an application window. It provides users with a way to access a particular window's command without restoring or activating the window.
\nAs quoted from MSDN:
\n\n\nThis toolbar is the familiar standard toolbar common control. It has a maximum of seven buttons. Each button's ID, image, tooltip, and state are defined in a structure, which is then passed to the taskbar. The application can show, enable, disable, or hide buttons from the thumbnail toolbar as required by its current state.
\nFor example, Windows Media Player might offer standard media transport controls such as play, pause, mute, and stop.
\n
\n\nNOTE: The screenshot above is an example of thumbnail toolbar of Windows Media Player
\n
To set thumbnail toolbar in your application, you need to use BrowserWindow.setThumbarButtons
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { BrowserWindow } = require('electron')\nconst path = require('path')\n\nconst win = new BrowserWindow()\n\nwin.setThumbarButtons([\n {\n tooltip: 'button1',\n icon: path.join(__dirname, 'button1.png'),\n click () { console.log('button1 clicked') }\n }, {\n tooltip: 'button2',\n icon: path.join(__dirname, 'button2.png'),\n flags: ['enabled', 'dismissonclick'],\n click () { console.log('button2 clicked.') }\n }\n])\nTo clear thumbnail toolbar buttons, you need to call BrowserWindow.setThumbarButtons with an empty array in the main.js file.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.setThumbarButtons([])\nOn Windows, a taskbar button can use a small overlay to display application status.
\nAs quoted from MSDN:
\n\n\nIcon overlays serve as a contextual notification of status, and are intended to negate the need for a separate notification area status icon to communicate that information to the user. For instance, the new mail status in Microsoft Outlook, currently shown in the notification area, can now be indicated through an overlay on the taskbar button. Again, you must decide during your development cycle which method is best for your application. Overlay icons are intended to supply important, long-standing status or notifications such as network status, messenger status, or new mail. The user should not be presented with constantly changing overlays or animations.
\n
\n\nNOTE: The screenshot above is an example of overlay on a taskbar button
\n
To set the overlay icon for a window, you need to use the BrowserWindow.setOverlayIcon API.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.setOverlayIcon('path/to/overlay.png', 'Description for overlay')\nOn Windows, you can highlight the taskbar button to get the user's attention. This is similar to bouncing the dock icon in macOS.
\nAs quoted from MSDN:
\n\n\nTypically, a window is flashed to inform the user that the window requires attention but that it does not currently have the keyboard focus.
\n
To flash the BrowserWindow taskbar button, you need to use the BrowserWindow.flashFrame API.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.once('focus', () => win.flashFrame(false))\nwin.flashFrame(true)\n\n", "title": "Taskbar Customization (Windows)", "description": "Приложения определяют задачи, основанные как на функциях программы, так и на ключевых моментах, которые пользователь должен делать с ними. Задачи должны быть контекстно-свободными, в данном случае, приложению не потребуется запускать их для работы. Они также должны быть статистически наиболее распространенными действиями, которые обычный пользователь будет выполнять в приложении, например, составить сообщение электронной почты или открыть календарь в почтовой программе, создать новый документ в текстовом редакторе, запустить приложение в определенном режиме, или запустить одну из своих подкоманд. Приложение не должно загромождать меню с расширенными функциями, которые не требуются обычным пользователям или одноразовыми действиями, такими как регистрация. Не используйте задачи для рекламных материалов, таких как обновления или специальные предложения.\nНастоятельно рекомендуется, чтобы список задач был статическим. Он должен оставаться неизменным независимо от состояния или статуса приложения. Хотя можно динамически изменять список, вы должны учитывать, что это может смутить пользователя, который не ожидает изменения этой части списка адресатов." } }, "pt-BR": { "/docs/api/accelerator": { "locale": "pt-BR", "slug": "accelerator", "href": "/docs/api/accelerator", "crowdinFileId": "256277", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/accelerator.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "NOTE: Don't forget to call
\nwin.flashFrame(false)to turn off the flash. In the above example, it is called when the window comes into focus, but you might use a timeout or some other event to disable it.
\n\nDefinem atalhos de teclado.
\n
Aceleradores são Strings que podem conter múltiplos modificadores e um código de teclas combinados pelo '+' e que são utilizados para definir atalhos de teclado para sua aplicação.
Exemplos:
\nCommandOrControl+ACommandOrControl+Shift+ZOs atalhos são registrados com o módulo globalShortcut usando o método registrar, ou seja:
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+Y' shortcut listener.\n globalShortcut.register('CommandOrControl+Y', () => {\n // Fazer algo quando Y e Command ou Control forem pressionados.\n })\n})\nNo Linux e no Windows, a tecla Command não tem nenhum efeito, então, para definir alguns aceleradores é recomendado utilizar CommandOrControl que representa Command no macOS e Control no Linux e no Windows.
Use Alt instead of Option. The Option key only exists on macOS, whereas the Alt key is available on all platforms.
The Super (or Meta) key is mapped to the Windows key on Windows and Linux and Cmd on macOS.
Command (ou Cmd)Control (ou Ctrl)CommandOrControl (ou CmdOrCtrl)AltOptionAltGrShiftSuperMeta0 a 9A a ZF1 a F24~, !, @, #, $, etc.Plus (+)Space (Espaço)TabCapsLockNumLockScrolllockBackspaceDeleteInsertReturn (ou Enter)Up, Down, Left e Right (Setas do teclado: cima, baixo, esquerda e direita respectivamente)Home e EndPageUp e PageDownEscape (ou Esc)VolumeUp, VolumeDown e VolumeMuteMediaNextTrack, MediaPreviousTrack, MediaStop e MediaPlayPausePrintScreennum0 - num9numdec - tecla decimalnumadd - tecla +numsub - tecla -nummult - tecla *numdiv - tecla ÷Making accessible applications is important and we're happy to provide functionality to Devtron and Spectron that gives developers the opportunity to make their apps better for everyone.
\nAs questões de acessibilidade em aplicativos Electron são semelhantes às de sites na Web, já que ambos fazem uso do HTML. No entanto, com apps Electron, você não pode usar ferramentas online para auditorias de acessibilidade, pois seu aplicativo não tem uma URL para o auditor poder acessá-lo.
\nThese features bring those auditing tools to your Electron app. You can choose to add audits to your tests with Spectron or use them within DevTools with Devtron. Confira a seguir um resumo das ferramentas.
\nIn the testing framework Spectron, you can now audit each window and <webview> tag in your application. Como por exemplo:
app.client.auditAccessibility().then(function (audit) {\n if (audit.failed) {\n console.error(audit.message)\n }\n})\nVocê pode ler mais sobre esse recurso na documentação do Spectron.
\nIn Devtron, there is an accessibility tab which will allow you to audit a page in your app, sort and filter the results.
\n
Ambas essas ferramentas usam a biblioteca de ferramentas de acessibilidade para desenvolvedores feita para o Google Chrome. Você pode aprender mais sobre as regras de auditoria de acessibilidade que essa biblioteca usa no wiki do repositório.
\nSe você souber de outra fantástica ferramenta de acessibilidade para o Electron, adicione-a na documentação de acessibilidade com um pull request.
\nElectron applications will automatically enable accessibility features in the presence of assistive technology (e.g. JAWS on Windows or VoiceOver on macOS). See Chrome's accessibility documentation for more details.
\nYou can also manually toggle these features either within your Electron application or by setting flags in third-party native software.
\nBy using the app.setAccessibilitySupportEnabled(enabled) API, you can manually expose Chrome's accessibility tree to users in the application preferences. Note that the user's system assistive utilities have priority over this setting and will override it.
On macOS, third-party assistive technology can toggle accessibility features inside Electron applications by setting the AXManualAccessibility attribute programmatically:
CFStringRef kAXManualAccessibility = CFSTR(\"AXManualAccessibility\");\n\n+ (void)enableAccessibility:(BOOL)enable inElectronApplication:(NSRunningApplication *)app\n{\n AXUIElementRef appRef = AXUIElementCreateApplication(app.processIdentifier);\n if (appRef == nil)\n return;\n\n CFBooleanRef value = enable ? kCFBooleanTrue : kCFBooleanFalse;\n AXUIElementSetAttributeValue(appRef, kAXManualAccessibility, value);\n CFRelease(appRef);\n}\n\n\nControle os eventos do ciclo de vida da sua aplicação.
\n
Processo: Main
\nO seguinte exemplo mostra como encerrar a aplicação quando a última janela é fechada:
\nconst { app } = require('electron')\napp.on('window-all-closed', () => {\n app.quit()\n})\nO objeto app emite os seguintes eventos:
Emitido quando a aplicação termina inicialização básica. No Windows e Linux o evento will-finish-launching é o mesmo que o evento ready; no macOS, este evento representa a notificação applicationWillFinishLaunching de NSApplication. Você normalmente poderia escutar os eventos de open-file e open-url aqui e iniciar o crash reporter e auto atualização.
Na maioria dos casos, você deve fazer tudo no manipulador do evento ready.
Retorna:
\nevent EventlaunchInfo Record<string, any> | NotificationResponse macOSEmitted once, when Electron has finished initializing. On macOS, launchInfo holds the userInfo of the NSUserNotification or information from UNNotificationResponse that was used to open the application, if it was launched from Notification Center. You can also call app.isReady() to check if this event has already fired and app.whenReady() to get a Promise that is fulfilled when Electron is initialized.
Emitido quando todas as janelas foram fechadas.
\nSe você não escutar esse evento e todas as janelas forem fechadas, o comportamento padrão é fechar a aplicação. No entanto, se você estiver escutando, você controla se a aplicação fecha ou não. Se o usuário pressionou Cmd + Q ou o desenvolvedor chamou app.quit(), o Electron irá primeiro tentar fechar todas as janelas e então emitir o evento will-quit e neste caso, window-all-closed não será emitido.
Retorna:
\nevent EventEmitted before the application starts closing its windows. Calling event.preventDefault() will prevent the default behavior, which is terminating the application.
Nota: Se o encerramento da aplicação for iniciado pelo autoUpdater.quitAndInstall(), então o before-quit é emitido depois de lançar o evento close em todas as janelas e fechá-las.
Nota: No Windows, este evento não será emitido se o aplicativo for fechado devido a um desligamento / reinício do sistema ou a um logout do usuário.
\nRetorna:
\nevent EventEmitted when all windows have been closed and the application will quit. Calling event.preventDefault() will prevent the default behavior, which is terminating the application.
Consulte a descrição do evento window-all-closed para as diferenças entre os eventos will-quit e window-all-closed.
Nota: No Windows, este evento não será emitido se o aplicativo for fechado devido a um desligamento / reinício do sistema ou a um logout do usuário.
\nRetorna:
\nevent EventexitCode IntegerEmitido quando a aplicação esta sendo encerrada(quitting).
\nNota: No Windows, este evento não será emitido se o aplicativo for fechado devido a um desligamento / reinício do sistema ou a um logout do usuário.
\nRetorna:
\nevent Eventpath StringEmitido quando o usuário deseja abrir um arquivo com a aplicação. O evento open-file geralmente é emitido quando a aplicação já está aberta e o SO deseja reutilizar a aplicação para abrir o arquivo. open-file também é emitido quando um arquivo é solto sobre o dock e a aplicação ainda não está em execução. Certifique-se que o evento open-file seja detectado desde o início da aplicação para manipulá-lo (inclusive antes do evento ready ser emitido).
Se você deseja manipular esse evento, você deve chamar event.preventDefault().
No Windows, você tem que analisar process.argv (no processo principal) para obter o filepath.
Retorna:
\nevent EventurlEmitido quando o usuário deseja abrir um URL com a aplicação. Your application's Info.plist file must define the URL scheme within the CFBundleURLTypes key, and set NSPrincipalClass to AtomApplication.
Se você deseja manipular esse evento, você deve chamar event.preventDefault().
Retorna:
\nevent EventhasVisibleWindows BooleanEmitido quando a aplicação é ativada. Várias ações podem disparar esse evento, tais como iniciando o aplicativo pela primeira vez, a tentativa de re-iniciar o aplicativo quando ele já está sendo executado, ou clicando no ícone de barra de tarefas ou doca do aplicativo.
\nRetorna:
\nevent EventEmitido quando a aplicação mac se torna ativa. Diferença do evento ativo é que ativado é emitido toda vez que o app se torna ativo, não somente quando o ícone do Dock é clicado ou a aplicação é relançada.
Retorna:
\nevent Eventtype String - Uma string identificando a atividade. É mapeada para NSUserActivity.activityType.userInfo unknown - Contains app-specific state stored by the activity on another device.detailswebpageURL String (optional) - A string identifying the URL of the webpage accessed by the activity on another device, if available.Emitido durante Handoff quando a atividade em outro dispositivo deseja ser continuada. Você deve chamar event.preventDefault() caso queira manipular esse evento.
Uma atividade do usuário pode ser continuada apenas em uma aplicação que tem o mesmo Team ID do desenvolvedor como o aplicativo fonte da atividade e que suporta o tipo da atividade. Tipos de atividade suportadas são especificadas no Info.plist do aplicativo sob a chave NSUserActivityTypes.
Retorna:
\nevent Eventtype String - Uma string identificando a atividade. É mapeada para NSUserActivity.activityType.Emitido durante o Handoff antes de uma atividade em outro dispositivo desejar ser continuada. Você deve chamar event.preventDefault() caso queira manipular esse evento.
Retorna:
\nevent Eventtype String - Uma string identificando a atividade. É mapeada para NSUserActivity.activityType.error String - Uma string com a descrição traduzida do erro.Emitido durante o Handoff quando uma atividade de outro dispositivo falha ao ser resumida.
\nRetorna:
\nevent Eventtype String - Uma string identificando a atividade. É mapeada para NSUserActivity.activityType.userInfo unknown - Contains app-specific state stored by the activity.Emitido durante o Handoff depois que uma atividade deste dispositivo foi continuada com sucesso em outro dispositivo.
\nRetorna:
\nevent Eventtype String - Uma string identificando a atividade. É mapeada para NSUserActivity.activityType.userInfo unknown - Contains app-specific state stored by the activity.Emitido quando o Handoff está prestes a ser continuado em outro dispositivo. If you need to update the state to be transferred, you should call event.preventDefault() immediately, construct a new userInfo dictionary and call app.updateCurrentActivity() in a timely manner. Caso contrário, a operação irá falhar e continue-activity-error será chamado.
Retorna:
\nevent EventEmitted when the user clicks the native macOS new tab button. The new tab button is only visible if the current BrowserWindow has a tabbingIdentifier
Retorna:
\nevent Eventwindow BrowserWindowEmitido quando uma browserWindow é desfocada.
\nRetorna:
\nevent Eventwindow BrowserWindowEmitido quando browserWindow é focado.
\nRetorna:
\nevent Eventwindow BrowserWindowEmitido quando um novo browserWindow é criado.
\nRetorna:
\nevent EventwebContents WebContentsEmitido quando um novo webContents é criado.
\nRetorna:
\nevent EventwebContents WebContentsurlerror String - O código do errocertificate Certificatecallback FunctionisTrusted Boolean - Define considerar o certificado como confiávelisMainFrame BooleanEmitido quando a verificação do certificate para o url falha, para confiar no certificado você deve prevenir o comportamento padrão com event.preventDefault() e chamar callback(true).
const { app } = require('electron')\n\napp.on('certificate-error', (event, webContents, url, error, certificate, callback) => {\n if (url === 'https://github.com') {\n // Lógica de verificação.\n event.preventDefault()\n callback(true)\n } else {\n callback(false)\n }\n})\nRetorna:
\nevent EventwebContents WebContentsurl URLcertificateList Certificate[]callback Functioncertificate Certificate (opcional)Emitido quando um certificado de cliente é solicitado.
\nO url corresponde à entrada de navegação solicitando o certificado do cliente e callback pode ser chamado com uma entrada filtrada da lista. Usar event.preventDefault() previne a aplicação de utilizar o primeiro certificado da store.
const { app } = require('electron')\n\napp.on('select-client-certificate', (event, webContents, url, list, callback) => {\n event.preventDefault()\n callback(list[0])\n})\nRetorna:
\nevent EventwebContents WebContentsauthenticationResponseDetailsurl URLauthInfoisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (opcional)password String (opcional)Emitido quando webContents quer fazer uma autenticação básica.
O comportamento padrão é cancelar todas as autenticações. Para sobrescrever isso você deve prevenir o comportamento padrão com event.preventDefault() e chamar o callback(username, password) com as credenciais.
const { app } = require('electron')\n\napp.on('login', (event, webContents, details, authInfo, callback) => {\n event.preventDefault()\n callback('username', 'secret')\n})\nIf callback is called without a username or password, the authentication request will be cancelled and the authentication error will be returned to the page.
Emitted whenever there is a GPU info update.
\nRetorna:
\nevent Eventkilled BooleanEmitted when the GPU process crashes or is killed.
\nDepreciado Este evento é substituído pelo evento processo-filho-finalizado que contém mais informação sobre porque o processo filho desapareceu. It isn't always because it crashed. The killed boolean can be replaced by checking reason === 'killed' when you switch to that event.
Retorna:
\nevent EventwebContents WebContentskilled BooleanEmitido quando o processo de renderização do webContents trava ou é interrompido.
Deprecated: This event is superceded by the render-process-gone event which contains more information about why the render process disappeared. It isn't always because it crashed. The killed boolean can be replaced by checking reason === 'killed' when you switch to that event.
Retorna:
\nevent EventwebContents WebContentsdetailsreason String - The reason the render process is gone. Valores possíveis:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Integer - The exit code of the process, unless reason is launch-failed, in which case exitCode will be a platform-specific launch failure error code.Emitted when the renderer process unexpectedly disappears. This is normally because it was crashed or killed.
\nRetorna:
\nevent Eventdetailstype String - Process type. One of the following values:UtilidadeZygoteAjuda ao SandboxGPUPepper PluginPepper Plugin BrokerDesconhecidoreason String - The reason the child process is gone. Valores possíveis:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Number - The exit code for the process (e.g. status from waitpid if on posix, from GetExitCodeProcess on Windows).serviceName String (optional) - The non-localized name of the process.name String (optional) - The name of the process. Examples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.Emitted when the child process unexpectedly disappears. This is normally because it was crashed or killed. It does not include renderer processes.
\nRetorna:
\nevent EventaccessibilitySupportEnabled Boolean - true quando o suporte a acessibilidade do Chrome estiver ativo, false caso contrário.Emitido quando o suporte de acessibilidade do Chrome muda. Este evento é acionado quando a tecnologias assistivas, tais como leitores de tela, estão habilitadas ou desabilitadas. Veja https://www.chromium.org/developers/design-documents/accessibility para mais detalhes.
\nRetorna:
\nsession SessionEmitido quando Electron criar uma nova session.
const { app } = require('electron')\n\napp.on('session-created', (session) => {\n console.log(session)\n})\nRetorna:
\nevent Eventargv String[] - Um array dos argumentos da linha de comando da segunda instânciaworkingDirectory String - O diretório de trabalho da segunda instânciaThis event will be emitted inside the primary instance of your application when a second instance has been executed and calls app.requestSingleInstanceLock().
argv is an Array of the second instance's command line arguments, and workingDirectory is its current working directory. Geralmente, aplicativos reagem a isso tornando a janela principal deles visível e em primeiro plano.
Note: If the second instance is started by a different user than the first, the argv array will not include the arguments.
Esse evento é garantido que será emitido após o evento ready do objeto app ser emitido.
Note: Extra command line arguments might be added by Chromium, such as --original-process-start-time.
Retorna:
\nevent EventwebContents WebContentsEste evento será emitido quando desktopCapturer.getSources() é chamado no processo de renderização do webContents. Calling event.preventDefault() will make it return empty sources.
O objeto app tem os seguintes métodos:
Nota: Alguns métodos estão disponíveis somente em sistemas operacionais específicos e são rotulados como tal.
\napp.quit()Tenta fechar todas as janelas. O evento before-quit será emitido primeiro. Se todas as janelas forem fechadas com sucesso, o evento will-quit será emitido e por padrão, e o aplicativo será encerrado.
Este método garante que todos os manipuladores de vento beforeunload e unload seja executados corretamente. É possível que a janela cancele, retornando false no manipulador de eventos beforeunload.
app.exit([exitCode])exitCode Integer (opcional)Exits immediately with exitCode. exitCode defaults to 0.
All windows will be closed immediately without asking the user, and the before-quit and will-quit events will not be emitted.
app.relaunch([options])Reinicia a aplicação quando a instância atual sair.
\nBy default, the new instance will use the same working directory and command line arguments with current instance. Quando args são especificado, os args vão ser passados como argumentos de linha de comando em seu lugar. Quando execPath é especificado, o execPath será executado no reinício no lugar da aplicação atual.
Note que nesse método a aplicação não fecha quando executado. Você deve chamar app.quit ou app.exit depois de chamar app.relaunch para fazer a aplicação reiniciar.
Quando app.relaunch é chamado por várias vezes, várias instâncias serão iniciadas depois da instância atual sair.
Um exemplo de reinício da instância atual imediatamente e adicionar um novo argumento de linha de comando à nova instância:
\nconst { app } = require('electron')\n\napp.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) })\napp.exit(0)\napp.isReady()Retorna Boolean - true se o Electron tiver inicializado, false caso contrário. See also app.whenReady().
app.whenReady()Retorna Promise<void> - cumprido quando o Electron é inicializado. Pode ser usado como uma alternativa conveniente para a verificação app.isReady() e subscrever o evento ready se a aplicação ainda não estiver pronta.
app.focus([options])options (opcional)steal Boolean macOS - Make the receiver the active app even if another app is currently active.On Linux, focuses on the first visible window. On macOS, makes the application the active app. On Windows, focuses on the application's first window.
\nYou should seek to use the steal option as sparingly as possible.
app.hide() no macOSOculta todas as janelas do aplicativo sem minimizar-las.
\napp.show() no macOSShows application windows after they were hidden. Does not automatically focus them.
\napp.setAppLogsPath([path])path String (optional) - A custom path for your logs. Must be absolute.Sets or creates a directory your app's logs which can then be manipulated with app.getPath() or app.setPath(pathName, newPath).
Calling app.setAppLogsPath() without a path parameter will result in this directory being set to ~/Library/Logs/YourAppName on macOS, and inside the userData directory on Linux and Windows.
app.getAppPath()Retorna String - O diretório da aplicação atual.
app.getPath(name)name String - You can request the following paths by the name:home Diretório central do usuário.appData Per-user application data directory, which by default points to:%APPDATA% no Windows$XDG_CONFIG_HOME ou ~/.config no Linux~/Library/Application Support no macOSuserData O diretório que guarda as configurações da sua aplicação, que por padrão é o diretório appData anexado com o nome da sua aplicação.cachetemp Diretório temporário.exe O arquivo executável atual.module A biblioteca libchromiumcontent.desktop O diretório da Área de Trabalho do usuário atual.documents Diretório dos \"Meus Documentos\" de um usuário.downloads Diretório dos Downloads de um usuário.music Diretório para a música de um usuário.pictures Diretório para as imagens de um usuário.videos Diretório para os vídeos de um usuário.recent Directory for the user's recent files (Windows only).logs Diretório que armazena os logs da aplicação.crashDumps Directory where crash dumps are stored.Returns String - A path to a special directory or file associated with name. On failure, an Error is thrown.
If app.getPath('logs') is called without called app.setAppLogsPath() being called first, a default log directory will be created equivalent to calling app.setAppLogsPath() without a path parameter.
app.getFileIcon(path[, options])path Stringoptions (opcional)size Stringsmall - 16x16normal - 32x32large - 48x48 no Linux, 32x32 no Windows, não suportado no macOS.Returns Promise<NativeImage> - fulfilled with the app's icon, which is a NativeImage.
Obtém o ícone associado a um caminho.
\nNo Windows, há 2 tipos de ícones:
\n.mp3, .png, etc..exe, .dll, .ico.On Linux and macOS, icons depend on the application associated with file mime type.
\napp.setPath(name, path)name Stringpath StringMuda o path à um diretório especial ou arquivo relacionado ao name. If the path specifies a directory that does not exist, an Error is thrown. In that case, the directory should be created with fs.mkdirSync or similar.
Você pode modificar apenas caminhos de um name definidos no app.getPath.
Por padrão, cachês e cookies de páginas web serão guardados dentro do diretório userData. Se você quer mudar esse local, você deve modificar o caminho userData antes que o evento ready do app seja emitido.
app.getVersion()Retorna String - A versão da aplicação carregada. Se nenhuma versão é encontrada no package.json da aplicação, a versão do conjunto atual ou executável será retornada.
app.getName()Retorna String - O atual nome da aplicação, que é o nome da aplicação no arquivo package.json.
Usually the name field of package.json is a short lowercase name, according to the npm modules spec. Você normalmente deve especificar um campo productName, que é o nome completo da aplicação contendo letras maiúsculas e minúsculas e qual será preferido por name pelo Electron.
app.setName(name)name StringSobrescreve o atual nome da aplicação.
\nNote: This function overrides the name used internally by Electron; it does not affect the name that the OS uses.
\napp.getLocale()Returns String - The current application locale, fetched using Chromium's l10n_util library. Possible return values are documented here.
To set the locale, you'll want to use a command line switch at app startup, which may be found here.
\nNota: Quando estiver distribuindo seu aplicativo, você também deve entregar a pasta locales.
Note: On Windows, you have to call it after the ready events gets emitted.
app.getLocaleCountryCode()Returns String - User operating system's locale two-letter ISO 3166 country code. The value is taken from native OS APIs.
Note: When unable to detect locale country code, it returns empty string.
\napp.addRecentDocument(path) macOS Windowspath StringAdiciona o parâmetro path à lista de documentos recentes.
This list is managed by the OS. On Windows, you can visit the list from the task bar, and on macOS, you can visit it from dock menu.
\napp.clearRecentDocuments() macOS WindowsLimpa a lista de documentos recentes.
\napp.setAsDefaultProtocolClient(protocol[, path, args])protocol String - O nome do protocolo sem ://. For example, if you want your app to handle electron:// links, call this method with electron as the parameter.path String (optional) Windows - The path to the Electron executable. O padrão é process.execPathargs String Windows - Arguments passed to the executable. Defaults to an empty arrayRetorna Boolean - Se a chamada foi realizada com sucesso.
Sets the current executable as the default handler for a protocol (aka URI scheme). It allows you to integrate your app deeper into the operating system. Once registered, all links with your-protocol:// will be opened with the current executable. The whole link, including protocol, will be passed to your application as a parameter.
Note: On macOS, you can only register protocols that have been added to your app's info.plist, which cannot be modified at runtime. However, you can change the file during build time via Electron Forge, Electron Packager, or by editing info.plist with a text editor. Caso precise de mais detalhes, consulte a documentação da Apple.
Note: In a Windows Store environment (when packaged as an appx) this API will return true for all calls but the registry key it sets won't be accessible by other applications. In order to register your Windows Store application as a default protocol handler you must declare the protocol in your manifest.
The API uses the Windows Registry and LSSetDefaultHandlerForURLScheme internally.
app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windowsprotocol String - O nome do protocolo sem ://.path String (opcional) Windows - O padrão é process.execPathargs String Windows - O padrão é um array vazioRetorna Boolean - Se a chamada foi realizada com sucesso.
This method checks if the current executable as the default handler for a protocol (aka URI scheme). If so, it will remove the app as the default handler.
\napp.isDefaultProtocolClient(protocol[, path, args])protocol String - O nome do protocolo sem ://.path String (opcional) Windows - O padrão é process.execPathargs String Windows - O padrão é um array vazioReturns Boolean - Whether the current executable is the default handler for a protocol (aka URI scheme).
Nota: No macOS, você pode usar este método para verificar se a aplicação foi registrada como o manipulador padrão de um protocolo. Você também pode verificar isso consultando o ~/Library/Preferences/com.apple.LaunchServices.plist na máquina macOS. Caso precise de mais detalhes, consulte a documentação da Apple.
The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internally.
app.getApplicationNameForProtocol(url)url String - a URL with the protocol name to check. Unlike the other methods in this family, this accepts an entire URL, including :// at a minimum (e.g. https://).Returns String - Name of the application handling the protocol, or an empty string if there is no handler. For instance, if Electron is the default handler of the URL, this could be Electron on Windows and Mac. However, don't rely on the precise format which is not guaranteed to remain unchanged. Expect a different format on Linux, possibly with a .desktop suffix.
This method returns the application name of the default handler for the protocol (aka URI scheme) of a URL.
\napp.getApplicationInfoForProtocol(url) macOS Windowsurl String - a URL with the protocol name to check. Unlike the other methods in this family, this accepts an entire URL, including :// at a minimum (e.g. https://).Returns Promise<Object> - Resolve with an object containing the following:
icon NativeImage - the display icon of the app handling the protocol.path String - installation path of the app handling the protocol.name String - display name of the app handling the protocol.This method returns a promise that contains the application name, icon and path of the default handler for the protocol (aka URI scheme) of a URL.
\napp.setUserTasks(tasks) Windowstasks Task[] - Um array de objetos TaskAdds tasks to the Tasks category of the Jump List on Windows.
tasks é um array de objetos Task.
Retorna Boolean - Se a chamada foi realizada com sucesso.
Nota: Se desejar personalizar ainda mais a Jump List, use app.setJumpList(categories) em vez deste método.
app.getJumpListSettings() WindowsRetorna Object:
minItems Integer - O número mínimo de itens que serão mostrados na Jump List (para uma descrição mais detalhada deste valor, consulte a documentação no MSDN).removedItems JumpListItem[] - Array of JumpListItem objects that correspond to items that the user has explicitly removed from custom categories in the Jump List. Estes itens não devem ser adicionados novamente à Jump List na próxima chamada a app.setJumpList(). O Windows não irá mostrar nenhuma categoria personalizada que tiver qualquer um dos itens removidos.app.setJumpList(categories) Windowscategories JumpListCategory[] | null - Array of JumpListCategory objects.Define ou remove uma Jump List personalizada para a aplicação e retorna uma das seguintes strings:
\nok - Nada deu errado.error - Um ou mais erros ocorreram. Ative a geração de logs em tempo de execução para descobrir a causa provável.invalidSeparatorError - An attempt was made to add a separator to a custom category in the Jump List. Separators are only allowed in the standard Tasks category.fileTypeRegistrationError - Foi realizada uma tentativa de adicionar à Jump List um link de arquivo cujo tipo de arquivo não foi registrado para ser manipulado pela aplicação.customCategoryAccessDeniedError - Categorias personalizadas não podem ser adicionadas à Jump List devido a restrições de privacidade do usuário ou de políticas de grupo.Se categories for null, a Jump List personalizada anteriormente definida (se houver) será substituída por uma Jump List padrão para o app (gerenciada pelo Windows).
Nota: Se um objeto JumpListCategory não tiver for nem a propriedade type nem a name definidas, então seu type é assumido como tasks. Se a propriedade name está definida mas a propriedade type é omissa, então o type é assumido como custom.
Note: Os usuários podem remover itens de categorias personalizadas, e o Windows não permitirá que um item removido seja adicionado novamente a uma categoria personalizada até após a próxima chamada bem-sucedida a app.setJumpList(categories). Qualquer tentativa de adicionar novamente um item removido de uma categoria personalizada antes disso resultará na omissão da categoria inteira da Jump List. A lista dos itens removidos pode ser obtida usando app.getJumpListSettings().
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
Aqui vai um exemplo muito simples de como criar uma Jump List personalizada:
\nconst { app } = require('electron')\n\napp.setJumpList([\n {\n type: 'custom',\n name: 'Recent Projects',\n items: [\n { type: 'file', path: 'C:\\\\Projects\\\\project1.proj' },\n { type: 'file', path: 'C:\\\\Projects\\\\project2.proj' }\n ]\n },\n { // has a name so `type` is assumed to be \"custom\"\n name: 'Tools',\n items: [\n {\n type: 'task',\n title: 'Tool A',\n program: process.execPath,\n args: '--run-tool-a',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool A'\n },\n {\n type: 'task',\n title: 'Tool B',\n program: process.execPath,\n args: '--run-tool-b',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool B'\n }\n ]\n },\n { type: 'frequent' },\n { // has no name and no type so `type` is assumed to be \"tasks\"\n items: [\n {\n type: 'task',\n title: 'New Project',\n program: process.execPath,\n args: '--new-project',\n description: 'Create a new project.'\n },\n { type: 'separator' },\n {\n type: 'task',\n title: 'Recover Project',\n program: process.execPath,\n args: '--recover-project',\n description: 'Recover Project'\n }\n ]\n }\n])\napp.requestSingleInstanceLock()Retorna Boolean
The return value of this method indicates whether or not this instance of your application successfully obtained the lock. If it failed to obtain the lock, you can assume that another instance of your application is already running with the lock and exit immediately.
\nI.e. This method returns true if your process is the primary instance of your application and your app should continue loading. It returns false if your process should immediately quit as it has sent its parameters to another instance that has already acquired the lock.
On macOS, the system enforces single instance automatically when users try to open a second instance of your app in Finder, and the open-file and open-url events will be emitted for that. However when users start your app in command line, the system's single instance mechanism will be bypassed, and you have to use this method to ensure single instance.
Aqui vai um exemplo de como ativar a janela da instância principal quando uma segunda instância for iniciada:
\nconst { app } = require('electron')\nlet myWindow = null\n\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Someone tried to run a second instance, we should focus our window.\n if (myWindow) {\n if (myWindow.isMinimized()) myWindow.restore()\n myWindow.focus()\n }\n })\n\n // Create myWindow, load the rest of the app, etc...\n app.whenReady().then(() => {\n myWindow = createWindow()\n })\n}\napp.hasSingleInstanceLock()Retorna Boolean
This method returns whether or not this instance of your app is currently holding the single instance lock. You can request the lock with app.requestSingleInstanceLock() and release with app.releaseSingleInstanceLock()
app.releaseSingleInstanceLock()Releases all locks that were created by requestSingleInstanceLock. This will allow multiple instances of the application to once again run side by side.
app.setUserActivity(type, userInfo[, webpageURL]) macOStype String - Identificação única da atividade. É mapeada para NSUserActivity.activityType.userInfo any - App-specific state to store for use by another device.webpageURL String (optional) - The webpage to load in a browser if no suitable app is installed on the resuming device. The scheme must be http or https.Cria um NSUserActivity e o define como a atividade atual. A atividade, então, é qualificada para ser repassada (via Handoff) a outro dispositivo de agora em diante.
app.getCurrentActivityType() macOSRetorna String - O tipo da atividade atualmente em execução.
app.invalidateCurrentActivity() macOSInvalida a atividade de usuário atual do Handoff.
\napp.resignCurrentActivity() no macOSMarks the current Handoff user activity as inactive without invalidating it.
\napp.updateCurrentActivity(type, userInfo) macOStype String - Identificação única da atividade. É mapeada para NSUserActivity.activityType.userInfo any - App-specific state to store for use by another device.Atualiza a atividade atual se seu tipo corresponder a type, mesclando as entradas de userInfo ao seu dicionário userInfo atual.
app.setAppUserModelId(id) Windowsid StringMuda o Application User Model ID para id.
app.setActivationPolicy(policy) no macOSpolicy String - Can be 'regular', 'accessory', or 'prohibited'.Sets the activation policy for a given app.
\nActivation policy types:
\napp.importCertificate(options, callback) Linuxoptions Objectcertificate String - Caminho para o arquivo pkcs12.password String - Passphrase do certificado.callback Functionresult Integer - Resultado da importação.Importa o certificado em formato pkcs12 ao armazenamento de certificados da plataforma. callback is called with the result of import operation, a value of 0 indicates success while any other value indicates failure according to Chromium net_error_list.
app.configureHostResolver(options)options ObjectenableBuiltInResolver Boolean (optional) - Whether the built-in host resolver is used in preference to getaddrinfo. When enabled, the built-in resolver will attempt to use the system's DNS settings to do DNS lookups itself. Enabled by default on macOS, disabled by default on Windows and Linux.secureDnsMode String (optional) - Can be \"off\", \"automatic\" or \"secure\". Configures the DNS-over-HTTP mode. When \"off\", no DoH lookups will be performed. When \"automatic\", DoH lookups will be performed first if DoH is available, and insecure DNS lookups will be performed as a fallback. When \"secure\", only DoH lookups will be performed. Defaults to \"automatic\".secureDnsServers String[] (optional) - A list of DNS-over-HTTP server templates. See RFC8484 § 3 for details on the template format. Most servers support the POST method; the template for such servers is simply a URI. Note that for some DNS providers, the resolver will automatically upgrade to DoH unless DoH is explicitly disabled, even if there are no DoH servers provided in this list.enableAdditionalDnsQueryTypes Boolean (optional) - Controls whether additional DNS query types, e.g. HTTPS (DNS type 65) will be allowed besides the traditional A and AAAA queries when a request is being made via insecure DNS. Has no effect on Secure DNS which always allows additional types. Defaults to true.Configures host resolution (DNS and DNS-over-HTTPS). By default, the following resolvers will be used, in order:
\ngetaddrinfo).This can be configured to either restrict usage of non-encrypted DNS (secureDnsMode: \"secure\"), or disable DNS-over-HTTPS (secureDnsMode: \"off\"). It is also possible to enable or disable the built-in resolver.
To disable insecure DNS, you can specify a secureDnsMode of \"secure\". If you do so, you should make sure to provide a list of DNS-over-HTTPS servers to use, in case the user's DNS configuration does not include a provider that supports DoH.
app.configureHostResolver({\n secureDnsMode: 'secure',\n secureDnsServers: [\n 'https://cloudflare-dns.com/dns-query'\n ]\n})\nThis API must be called after the ready event is emitted.
app.disableHardwareAcceleration()Desativa a aceleração de hardware para o aplicativo atual.
\nEste método somente pode ser chamado antes do aplicativo estiver pronto.
\napp.disableDomainBlockingFor3DAPIs()By default, Chromium disables 3D APIs (e.g. WebGL) until restart on a per domain basis if the GPU processes crashes too frequently. This function disables that behavior.
\nEste método somente pode ser chamado antes do aplicativo estiver pronto.
\napp.getAppMetrics()Returns ProcessMetric[]: Array of ProcessMetric objects that correspond to memory and CPU usage statistics of all the processes associated with the app.
app.getGPUFeatureStatus()Retorna GPUFeatureStatus - Os status de recursos gráficos descritos em chrome://gpu/.
Note: This information is only usable after the gpu-info-update event is emitted.
app.getGPUInfo(infoType)infoType String - Pode ser basic ou complete.Retorna Promise<unknown>
For infoType equal to complete: Promise is fulfilled with Object containing all the GPU Information as in chromium's GPUInfo object. This includes the version and driver information that's shown on chrome://gpu page.
For infoType equal to basic: Promise is fulfilled with Object containing fewer attributes than when requested with complete. Here's an example of basic response:
{\n auxAttributes:\n {\n amdSwitchable: true,\n canSupportThreadedTextureMailbox: false,\n directComposition: false,\n directRendering: true,\n glResetNotificationStrategy: 0,\n inProcessGpu: true,\n initializationTime: 0,\n jpegDecodeAcceleratorSupported: false,\n optimus: false,\n passthroughCmdDecoder: false,\n sandboxed: false,\n softwareRendering: false,\n supportsOverlays: false,\n videoDecodeAcceleratorFlags: 0\n },\n gpuDevice:\n [{ active: true, deviceId: 26657, vendorId: 4098 },\n { active: false, deviceId: 3366, vendorId: 32902 }],\n machineModelName: 'MacBookPro',\n machineModelVersion: '11.5'\n}\nUsing basic should be preferred if only basic information like vendorId or driverId is needed.
app.setBadgeCount([count]) Linux macOScount Integer (optional) - If a value is provided, set the badge to the provided value otherwise, on macOS, display a plain white dot (e.g. unknown number of notifications). On Linux, if a value is not provided the badge will not display.Retorna Boolean - Se a chamada foi realizada com sucesso.
Sets the counter badge for current app. Setting the count to 0 will hide the badge.
On macOS, it shows on the dock icon. On Linux, it only works for Unity launcher.
\nNote: Unity launcher requires a .desktop file to work. For more information, please read the Unity integration documentation.
app.getBadgeCount() Linux macOSRetorna Integer - O valor sendo atualmente mostrado no selo contador.
app.isUnityRunning() LinuxRetorna Boolean - Indica se o ambiente de trabalho atual é o Unity ou não.
app.getLoginItemSettings([options]) macOS Windowsoptions (opcional)If you provided path and args options to app.setLoginItemSettings, then you need to pass the same arguments here for openAtLogin to be set correctly.
Retorna Object:
openAtLogin Boolean - true se o aplicativo está configurado para abrir no login.openAsHidden Boolean macOS - true if the app is set to open as hidden at login. This setting is not available on MAS builds.wasOpenedAtLogin Boolean macOS - true if the app was opened at login automatically. This setting is not available on MAS builds.wasOpenedAsHidden Boolean macOS - true if the app was opened as a hidden login item. Isso indica que o aplicativo não deverá abrir nenhuma janela durante a inicialização. This setting is not available on MAS builds.restoreState Boolean macOS - true if the app was opened as a login item that should restore the state from the previous session. Isso indica que o aplicativo deverá restaurar as janelas que foram abertas da última vez que o aplicativo fora fechado. This setting is not available on MAS builds.executableWillLaunchAtLogin Boolean Windows - true if app is set to open at login and its run key is not deactivated. This differs from openAtLogin as it ignores the args option, this property will be true if the given executable would be launched at login with any arguments.launchItems Object[] Windowsname String Windows - name value of a registry entry.path String Windows - The executable to an app that corresponds to a registry entry.args String[] Windows - the command-line arguments to pass to the executable.scope String Windows - one of user or machine. Indicates whether the registry entry is under HKEY_CURRENT USER or HKEY_LOCAL_MACHINE.enabled Boolean Windows - true if the app registry key is startup approved and therefore shows as enabled in Task Manager and Windows settings.app.setLoginItemSettings(settings) macOS Windowssettings ObjectopenAtLogin Boolean (optional) - true to open the app at login, false to remove the app as a login item. Defaults to false.openAsHidden Boolean (optional) macOS - true to open the app as hidden. Padrão sendo false. The user can edit this setting from the System Preferences so app.getLoginItemSettings().wasOpenedAsHidden should be checked when the app is opened to know the current value. This setting is not available on MAS builds.path String (optional) Windows - The executable to launch at login. Defaults to process.execPath.args String Windows - The command-line arguments to pass to the executable. Defaults to an empty array. Take care to wrap paths in quotes.enabled Boolean (optional) Windows - true will change the startup approved registry key and enable / disable the App in Task Manager and Windows Settings. Defaults to true.name String (optional) Windows - value name to write into registry. Defaults to the app's AppUserModelId(). Define as opções de execução do aplicativo na inicialização do sistema.Para funcionar com o autoUpdater do Electron no Windows, o qual usa o Squirrel, recomendamos definir o caminho de inicialização para Update.exe e passar a ele os argumentos que especificam o nome do seu aplicativo. Como por exemplo:
const appFolder = path.dirname(process.execPath)\nconst updateExe = path.resolve(appFolder, '..', 'Update.exe')\nconst exeName = path.basename(process.execPath)\n\napp.setLoginItemSettings({\n openAtLogin: true,\n path: updateExe,\n args: [\n '--processStart', `\"${exeName}\"`,\n '--process-start-args', `\"--hidden\"`\n ]\n})\napp.isAccessibilitySupportEnabled() macOS WindowsRetorna Boolean - true se o suporte à acessibilidade do Chrome estiver ativado, false caso contrário. Essa API retornará true se o uso de tecnologias assistivas, tais como leitores de tela, foi detectado. Consulte https://www.chromium.org/developers/design-documents/accessibility para mais detalhes.
app.setAccessibilitySupportEnabled(enabled) macOS Windowsenabled Boolean - Ativa ou desativa a renderização da árvore de acessibilidadeAtiva manualmente o suporte à acessibilidade do Chrome, permitindo expor uma opção para ativar/desativar a acessibilidade nas configurações do aplicativo. See Chromium's accessibility docs for more details. Desativado por padrão.
\nThis API must be called after the ready event is emitted.
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
\napp.showAboutPanel()Show the app's about panel options. These options can be overridden with app.setAboutPanelOptions(options).
app.setAboutPanelOptions(options)options ObjectapplicationName String (opcional) - O nome do aplicativo.applicationVersion String (opcional) - A versão do aplicativo.copyright String (opcional) - Informações de copyright.version String (optional) macOS - The app's build version number.credits String (optional) macOS Windows - Credit information.authors String Linux - List of app authors.website String (optional) Linux - The app's website.iconPath String (optional) Linux Windows - Path to the app's icon in a JPEG or PNG file format. On Linux, will be shown as 64x64 pixels while retaining aspect ratio.Define as opções do painel sobre. This will override the values defined in the app's .plist file on macOS. Consulte a documentação da Apple para mais detalhes. On Linux, values must be set in order to be shown; there are no defaults.
If you do not set credits but still wish to surface them in your app, AppKit will look for a file named \"Credits.html\", \"Credits.rtf\", and \"Credits.rtfd\", in that order, in the bundle returned by the NSBundle class method main. The first file found is used, and if none is found, the info area is left blank. See Apple documentation for more information.
app.isEmojiPanelSupported()Returns Boolean - whether or not the current OS version allows for native emoji pickers.
app.showEmojiPanel() macOS WindowsShow the platform's native emoji picker.
\napp.startAccessingSecurityScopedResource(bookmarkData) masbookmarkData String - The base64 encoded security scoped bookmark data returned by the dialog.showOpenDialog or dialog.showSaveDialog methods.Returns Function - This function must be called once you have finished accessing the security scoped file. If you do not remember to stop accessing the bookmark, kernel resources will be leaked and your app will lose its ability to reach outside the sandbox completely, until your app is restarted.
// Start accessing the file.\nconst stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)\n// You can now access the file outside of the sandbox 🎉\n\n// Remember to stop accessing the file once you've finished with it.\nstopAccessingSecurityScopedResource()\nStart accessing a security scoped resource. With this method Electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See Apple's documentation for a description of how this system works.
\napp.enableSandbox()Enables full sandbox mode on the app. This means that all renderers will be launched sandboxed, regardless of the value of the sandbox flag in WebPreferences.
Este método somente pode ser chamado antes do aplicativo estiver pronto.
\napp.isInApplicationsFolder() macOSReturns Boolean - Whether the application is currently running from the systems Application folder. Use in combination with app.moveToApplicationsFolder()
app.moveToApplicationsFolder([options]) macOSoptions (opcional)conflictHandler Function\\conflictType String - The type of move conflict encountered by the handler; can be exists or existsAndRunning, where exists means that an app of the same name is present in the Applications directory and existsAndRunning means both that it exists and that it's presently running.Returns Boolean - Whether the move was successful. Please note that if the move is successful, your application will quit and relaunch.
No confirmation dialog will be presented by default. If you wish to allow the user to confirm the operation, you may do so using the dialog API.
NOTE: This method throws errors if anything other than the user causes the move to fail. For instance if the user cancels the authorization dialog, this method returns false. If we fail to perform the copy, then this method will throw an error. The message in the error should be informative and tell you exactly what went wrong.
\nBy default, if an app of the same name as the one being moved exists in the Applications directory and is not running, the existing app will be trashed and the active app moved into its place. If it is running, the pre-existing running app will assume focus and the previously active app will quit itself. This behavior can be changed by providing the optional conflict handler, where the boolean returned by the handler determines whether or not the move conflict is resolved with default behavior. i.e. returning false will ensure no further action is taken, returning true will result in the default behavior and the method continuing.
Como por exemplo:
\napp.moveToApplicationsFolder({\n conflictHandler: (conflictType) => {\n if (conflictType === 'exists') {\n return dialog.showMessageBoxSync({\n type: 'question',\n buttons: ['Halt Move', 'Continue Move'],\n defaultId: 0,\n message: 'An app of this name already exists'\n }) === 1\n }\n }\n})\nWould mean that if an app already exists in the user directory, if the user chooses to 'Continue Move' then the function would continue with its default behavior and the existing app will be trashed and the active app moved into its place.
\napp.isSecureKeyboardEntryEnabled() macOSReturns Boolean - whether Secure Keyboard Entry is enabled.
By default this API will return false.
app.setSecureKeyboardEntryEnabled(enabled) macOSenabled Boolean - Enable or disable Secure Keyboard EntrySet the Secure Keyboard Entry is enabled in your application.
By using this API, important information such as password and other sensitive information can be prevented from being intercepted by other processes.
\nSee Apple's documentation for more details.
\nNote: Enable Secure Keyboard Entry only when it is needed and disable it when it is no longer needed.
app.accessibilitySupportEnabled macOS WindowsA Boolean property that's true if Chrome's accessibility support is enabled, false otherwise. This property will be true if the use of assistive technologies, such as screen readers, has been detected. Setting this property to true manually enables Chrome's accessibility support, allowing developers to expose accessibility switch to users in application settings.
See Chromium's accessibility docs for more details. Desativado por padrão.
\nThis API must be called after the ready event is emitted.
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
\napp.applicationMenuA Menu | null property that returns Menu if one has been set and null otherwise. Users can pass a Menu to set this property.
app.badgeCount Linux macOSAn Integer property that returns the badge count for current app. Setting the count to 0 will hide the badge.
On macOS, setting this with any nonzero integer shows on the dock icon. On Linux, this property only works for Unity launcher.
\nNote: Unity launcher requires a .desktop file to work. For more information, please read the Unity integration documentation.
Note: On macOS, you need to ensure that your application has the permission to display notifications for this property to take effect.
\napp.commandLine ReadonlyA CommandLine object that allows you to read and manipulate the command line arguments that Chromium uses.
app.dock macOS ReadonlyA Dock | undefined object that allows you to perform actions on your app icon in the user's dock on macOS.
app.isPackaged ReadonlyA Boolean property that returns true if the app is packaged, false otherwise. For many apps, this property can be used to distinguish development and production environments.
app.nameA String property that indicates the current application's name, which is the name in the application's package.json file.
Usually the name field of package.json is a short lowercase name, according to the npm modules spec. Você normalmente deve especificar um campo productName, que é o nome completo da aplicação contendo letras maiúsculas e minúsculas e qual será preferido por name pelo Electron.
app.userAgentFallbackA String which is the user agent string Electron will use as a global fallback.
This is the user agent that will be used when no user agent is set at the webContents or session level. It is useful for ensuring that your entire app has the same user agent. Set to a custom value as early as possible in your app's initialization to ensure that your overridden value is used.
app.runningUnderRosettaTranslation macOS Readonly DeprecatedA Boolean which when true indicates that the app is currently running under the Rosetta Translator Environment.
You can use this property to prompt users to download the arm64 version of your application when they are running the x64 version under Rosetta incorrectly.
\nDeprecated: This property is superceded by the runningUnderARM64Translation property which detects when the app is being translated to ARM64 in both macOS and Windows.
app.runningUnderARM64Translation Readonly macOS WindowsA Boolean which when true indicates that the app is currently running under an ARM64 translator (like the macOS Rosetta Translator Environment or Windows WOW).
You can use this property to prompt users to download the arm64 version of your application when they are running the x64 version under Rosetta incorrectly.
", "title": "app", "description": "Controle os eventos do ciclo de vida da sua aplicação." }, "/docs/tutorial/application-debugging": { "locale": "pt-BR", "slug": "application-debugging", "href": "/docs/tutorial/application-debugging", "crowdinFileId": "256175", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/application-debugging.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Sempre que seu aplicativo Electron não estiver se comportando do jeito que você queria, você pode usar uma gama de ferramentas te dão uma força para descobrir erros no seu código, gargalos de desempenho e oportunidades de otimização.
\nA ferramenta mais recomendada para depurar processos de renderização individuais é o Chromium DevTools. Ele está disponível em todos os processos de renderização, incluindo instâncias de BrowserWindow, BrowserView e WebView. Você pode abrí-lo a partir do seu código chamando a API openDevTools() no webContents da instância:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.webContents.openDevTools()\nO Google oferece [uma excelente documentação de suas ferramentas de desenvolvimento][devtools]. Recomendamos que você aprenda bem a usá-lo - ele está entre as ferramentas mais poderosas no cinto de utilidades de qualquer desenvolvedor Electron.
\nDepurar o processo principal é um pouquinho mais complicado, já que não dá de abrir ferramentas de desenvolvimento pra ele. O Chromium DevTools pode ser usado para depurar o processo principal do Electron graças a uma colaboração mais próxima entre o Google / Chrome e o Node.js, mas você poderá encontrar algumas desvantagens, como a indisponibilidade do método require no console.
Para mais informações, consulte o documento Depurando o Processo Principal.
\nSe o contexto V8 parar de funcionar, as ferramentas de desenvolvimento mostratão a seguinte mensagem.
\nDevTools was disconnected from the page. Once page is reloaded, DevTools will automatically reconnect.
Logs para Chromium podem ser habilitados através da variável de ambiente ELECTRON_ENABLE_LOGGING. Para mais informações, consulte o documento Variáveis de ambiente.
Alternativamente, o argumento da linha de comando --enable-logging pode ser passado. Mais informações estão disponíveis na documentação de Alteradores de linha de comando.
[devtools]: https://developers. google. com/web/tools/chrome-devtools/
", "title": "Depuração de Aplicativos", "description": "" }, "/docs/tutorial/application-distribution": { "locale": "pt-BR", "slug": "application-distribution", "href": "/docs/tutorial/application-distribution", "crowdinFileId": "256177", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/application-distribution.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "To distribute your app with Electron, you need to package and rebrand it. To do this, you can either use specialized tooling or manual approaches.
\nYou can use the following tools to distribute your application:
\n\nThese tools will take care of all the steps you need to take to end up with a distributable Electron application, such as bundling your application, rebranding the executable, and setting the right icons.
\nYou can check the example of how to package your app with electron-forge in the Quick Start guide.
To distribute your app manually, you need to download Electron's prebuilt binaries. Depois disso, a pasta contendo seu aplicativo deve ser renomeada para app e colocada dentro do diretório de recursos (resources) do Electron como mostrado nos seguintes exemplos.
\n\nNOTE: the location of Electron's prebuilt binaries is indicated with
\nelectron/in the examples below.
No macOS:
\nelectron/Electron.app/Contents/Resources/app/\n├── package.json\n├── main.js\n└── index.html\nNo Windows e Linux:
\nelectron/resources/app\n├── package.json\n├── main.js\n└── index.html\nThen execute Electron.app on macOS, electron on Linux, or electron.exe on Windows, and Electron will start as your app. The electron directory will then be your distribution to deliver to users.
Instead of from shipping your app by copying all of its source files, you can package your app into an asar archive to improve the performance of reading files on platforms like Windows, if you are not already using a bundler such as Parcel or Webpack.
\nPara usar um arquivo asar para substituir a pasta app, você precisa renomear o arquivo para app.asar e colocá-lo dentro da pasta de recursos do Electron como mostrado abaixo, e o Electron irá então ler o arquivo e executar seu app.
No macOS:
\nelectron/Electron.app/Contents/Resources/\n└── app.asar\nNo Windows e Linux:
\nelectron/resources/\n└── app.asar\nYou can find more details on how to use asar in the electron/asar repository.
Após deixar seu app Electron pronto para usar, você pode querer personalizar os executáveis do Electron antes de distribuí-los aos usuários.
\nVocê pode renomear o Electron.app para qualquer nome que você quiser, porém você também deve renomear os campos CFBundleDisplayName, CFBundleIdentifier e CFBundleName nos seguintes arquivos:
Electron.app/Contents/Info.plistElectron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plistVocê também pode renomear o app auxiliar para evitar de mostrar Electron Helper no Monitor de Atividade, mas não esqueça de renomear o arquivo executável do app auxiliar.
Veja como ficaria a estrutura de um aplicativo renomeado:
\nMyApp.app/Contents\n├── Info.plist\n├── MacOS/\n│ └── MyApp\n└── Frameworks/\n └── MyApp Helper.app\n ├── Info.plist\n └── MacOS/\n └── MyApp Helper\nVocê pode renomear o electron.exe para qualquer nome que você quiser, além de editar seu ícone e outras informações com ferramentas como o rcedit.
Você pode renomear o executável electron para qualquer nome que você quiser.
Também é possível remarcar o Electron mudando o nome do produto e construindo a partir fonte. To do this you need to set the build argument corresponding to the product name (electron_product_name = \"YourProductName\") in the args.gn file and rebuild.
\n\nHabilita aplicações a se atualizarem automaticamente.
\n
Processo: Main
\nSee also: A detailed guide about how to implement updates in your application.
\nautoUpdater é um EventEmitter.
Atualmente, apenas o macOS e o Windows são suportados. Não há suporte nativo para o atualizador automático no Linux - portanto, recomendamos usar o gerenciador de pacotes da distribuição para atualizar seu app.
\nAlém disso, existem algumas diferenças sutis em cada plataforma:
\nNo macOS, o módulo autoUpdater é construído em cima do Squirrel.Mac, ou seja, você não precisa de nenhuma configuração especial para que funcione. Para os requisitos do lado do servidor, você pode ler o Suporte do servidor. Observe que o App Transport Security (ATS) aplica-se a todas as solicitações feitas como parte do processo de atualização. Aplicações que precisam desativar o ATS podem adicionar a chave NSAllowsArbitraryLoads no plist de sua aplicação.
Nota: Seu aplicativo precisa estar assinado para que seja automaticamente atualizado no macOS. Isto é um requisito do Squirrel.Mac.
On Windows, you have to install your app into a user's machine before you can use the autoUpdater, so it is recommended that you use the electron-winstaller, electron-forge or the grunt-electron-installer package to generate a Windows installer.
When using electron-winstaller or electron-forge make sure you do not try to update your app the first time it runs (Also see this issue for more info). Também é recomendado utilizar o electron-squirrel-startup para obter atalhos da área de trabalho para sua aplicação.
\nThe installer generated with Squirrel will create a shortcut icon with an Application User Model ID in the format of com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE, examples are com.squirrel.slack.Slack and com.squirrel.code.Code. Você deve usar o mesmo ID para sua aplicação com a API app.setAppUserModelId, caso contrário, o Windows não será capaz de fixar sua aplicação corretamente na barra de tarefas.
Like Squirrel.Mac, Windows can host updates on S3 or any other static file host. You can read the documents of Squirrel.Windows to get more details about how Squirrel.Windows works.
\nO objeto autoUpdater emite os seguintes eventos:
Retorna:
\nerrorEmitido quando há um erro durante a atualização.
\nEmitido ao verificar se uma atualização começou.
\nEmitido quando houver uma atualização disponível. A atualização é baixada automaticamente.
\nEmitido quando não há atualização disponível.
\nRetorna:
\nevent EventreleaseNotesreleaseNamereleaseDateupdateURLEmitido quando uma atualização foi baixada.
\nNo Windows apenas o releaseName está disponível.
Nota: Não é estritamente necessário tratar este evento. Uma atualização baixada com sucesso ainda será aplicada na próxima vez que o aplicativo iniciar.
\nEste evento é emitido depois de um usuário chamar quitAndInstall().
Quando esta API é chamada, o evento before-quit não é emitido antes de todas as janelas serem fechadas. Como resultado, você deve ouvir este evento se você deseja executar ações antes das janelas serem fechadas enquanto um processo é encerrado, Além de ouvir before-quit.
O objeto autoUpdater possui os seguintes métodos:
autoUpdater.setFeedURL(options)options Objecturlheaders Record<String, String> (opcional) macOS - Cabeçalhos da solicitação HTTP.serverType String (optional) macOS - Can be json or default, see the Squirrel.Mac README for more information.Define a url e inicializa a atualização automática.
autoUpdater.getFeedURL()Returns String - The current update feed URL.
autoUpdater.checkForUpdates()Pergunta para o servidor se há alguma atualização. Você precisa chamar o setFeedURL antes de usar esta API.
Note: If an update is available it will be downloaded automatically. Calling autoUpdater.checkForUpdates() twice will download the update two times.
autoUpdater.quitAndInstall()Reinicia o aplicativo e instala a atualização após ela ter sido baixada. Deve ser chamado apenas após o evento update-downloaded ter sido emitido.
Sob o capô chamando autoUpdater.quitAndInstall() fechará todos os aplicativos janelas primeiro, e automaticamente chamar app.quit() depois de todas as janelas foram Fechado.
Nota: Não é estritamente necessário para lidar com este evento. Uma atualização baixada com sucesso ainda será aplicada na próxima vez que o aplicativo for iniciado.
", "title": "autoUpdater", "description": "Habilita aplicações a se atualizarem automaticamente." }, "/docs/tutorial/automated-testing-with-a-custom-driver": { "locale": "pt-BR", "slug": "automated-testing-with-a-custom-driver", "href": "/docs/tutorial/automated-testing-with-a-custom-driver", "crowdinFileId": "256179", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/automated-testing-with-a-custom-driver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Para escrever testes automatizados para seu aplicativo Electron, você precisará de uma maneira de \"conduzir\" seu aplicativo. Spectron is a commonly-used solution which lets you emulate user actions via WebDriver. However, it's also possible to write your own custom driver using node's builtin IPC-over-STDIO. The benefit of a custom driver is that it tends to require less overhead than Spectron, and lets you expose custom methods to your test suite.
\nTo create a custom driver, we'll use Node.js' child_process API. The test suite will spawn the Electron process, then establish a simple messaging protocol:
\nconst childProcess = require('child_process')\nconst electronPath = require('electron')\n\n// spawn the process\nconst env = { /* ... */ }\nconst stdio = ['inherit', 'inherit', 'inherit', 'ipc']\nconst appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })\n\n// listen for IPC messages from the app\nappProcess.on('message', (msg) => {\n // ...\n})\n\n// send an IPC message to the app\nappProcess.send({ my: 'message' })\nFrom within the Electron app, you can listen for messages and send replies using the Node.js process API:
\n// listen for IPC messages from the test suite\nprocess.on('message', (msg) => {\n // ...\n})\n\n// send an IPC message to the test suite\nprocess.send({ my: 'message' })\nWe can now communicate from the test suite to the Electron app using the appProcess object.
For convenience, you may want to wrap appProcess in a driver object that provides more high-level functions. Here is an example of how you can do this:
class TestDriver {\n constructor ({ path, args, env }) {\n this.rpcCalls = []\n\n // start child process\n env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages\n this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })\n\n // handle rpc responses\n this.process.on('message', (message) => {\n // pop the handler\n const rpcCall = this.rpcCalls[message.msgId]\n if (!rpcCall) return\n this.rpcCalls[message.msgId] = null\n // reject/resolve\n if (message.reject) rpcCall.reject(message.reject)\n else rpcCall.resolve(message.resolve)\n })\n\n // wait for ready\n this.isReady = this.rpc('isReady').catch((err) => {\n console.error('Application failed to start', err)\n this.stop()\n process.exit(1)\n })\n }\n\n // simple RPC call\n // to use: driver.rpc('method', 1, 2, 3).then(...)\n async rpc (cmd, ...args) {\n // send rpc request\n const msgId = this.rpcCalls.length\n this.process.send({ msgId, cmd, args })\n return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))\n }\n\n stop () {\n this.process.kill()\n }\n}\nIn the app, you'd need to write a simple handler for the RPC calls:
\nif (process.env.APP_TEST_DRIVER) {\n process.on('message', onMessage)\n}\n\nasync function onMessage ({ msgId, cmd, args }) {\n let method = METHODS[cmd]\n if (!method) method = () => new Error('Invalid method: ' + cmd)\n try {\n const resolve = await method(...args)\n process.send({ msgId, resolve })\n } catch (err) {\n const reject = {\n message: err.message,\n stack: err.stack,\n name: err.name\n }\n process.send({ msgId, reject })\n }\n}\n\nconst METHODS = {\n isReady () {\n // do any setup needed\n return true\n }\n // define your RPC-able methods here\n}\nThen, in your test suite, you can use your test-driver as follows:
\nconst test = require('ava')\nconst electronPath = require('electron')\n\nconst app = new TestDriver({\n path: electronPath,\n args: ['./app'],\n env: {\n NODE_ENV: 'test'\n }\n})\ntest.before(async t => {\n await app.isReady\n})\ntest.after.always('cleanup', async t => {\n await app.stop()\n})\nElectron Cl no Windows usa o AppVeyor, que por sua vez usa imagens do Azure Vm para executar. Occasionally, these VM images need to be updated due to changes in Chromium requirements. In order to update you will need PowerShell and the Azure PowerShell module.
\nOccasionally we need to update these images owing to changes in Chromium or other miscellaneous build requirement changes.
\nExample Use Case:\n* We need VS15.9 and we have VS15.7 installed; this would require us to update an Azure image.
Identify the image you wish to modify.
\nGet the Azure storage account key
\nappveyorlibccbuilds Disk Storage Account Name you'd look for appveyorlibccbuilds in the list of storage accounts @ Home < Storage AccountsAccess Keys, and then you can use any of the keys present in the list.Get the full virtual machine image URI from Azure
\n$ACCT_NAME < Blobs < ImagesCopy the image using the Copy Master Image PowerShell script.
\n(images)libcc-20core-vs2017-15.9-2019-04-15.vhdSpin up a new VM using the Create Master VM from VHD PowerShell.
\nps1 file with ./create_master_vm_from_vhd.ps1Standard_F32s_v2East USLog back into Azure and find the VM you just created in Home < Virtual Machines < $YOUR_NEW_VM
Using Microsoft Remote Desktop, click Connect to connect to the VM.
AppVeyor Enterprise master VM credentials.Modify the VM as required.
\nShut down the VM and then delete it in Azure.
\nAdd the new image to the Appveyor Cloud settings or modify an existing image to point to the new VHD.
\ndeviceName StringdeviceId StringElectron development is unopinionated - there is no \"one true way\" to develop, build, package, or release an Electron application. Additional features for Electron, both for build- and run-time, can usually be found on npm in individual packages, allowing developers to build both the app and build pipeline they need.
\nThat level of modularity and extendability ensures that all developers working with Electron, both big and small in team-size, are never restricted in what they can or cannot do at any time during their development lifecycle. However, for many developers, one of the community-driven boilerplates or command line tools might make it dramatically easier to compile, package, and release an app.
\nA boilerplate is only a starting point - a canvas, so to speak - from which you build your application. They usually come in the form of a repository you can clone and customize to your heart's content.
\nA command line tool on the other hand continues to support you throughout the development and release. They are more helpful and supportive but enforce guidelines on how your code should be structured and built. Especially for beginners, using a command line tool is likely to be helpful.
\nA \"complete tool for building modern Electron applications\". Electron Forge unifies the existing (and well maintained) build tools for Electron development into a cohesive package so that anyone can jump right in to Electron development.
\nForge comes with a ready-to-use template using Webpack as a bundler. It includes an example typescript configuration and provides two configuration files to enable easy customization. It uses the same core modules used by the greater Electron community (like electron-packager) – changes made by Electron maintainers (like Slack) benefit Forge's users, too.
You can find more information and documentation on electronforge.io.
\nA \"complete solution to package and build a ready-for-distribution Electron app\" that focuses on an integrated experience. electron-builder adds one single dependency focused on simplicity and manages all further requirements internally.
electron-builder replaces features and modules used by the Electron maintainers (such as the auto-updater) with custom ones. They are generally tighter integrated but will have less in common with popular Electron apps like Atom, Visual Studio Code, or Slack.
You can find more information and documentation in the repository.
\nIf you don't want any tools but only a solid boilerplate to build from, CT Lin's electron-react-boilerplate might be worth a look. It's quite popular in the community and uses electron-builder internally.
The \"Awesome Electron\" list contains more tools and boilerplates to choose from. If you find the length of the list intimidating, don't forget that adding tools as you go along is a valid approach, too.
", "title": "Boilerplates e CLIs", "description": "" }, "/docs/breaking-changes": { "locale": "pt-BR", "slug": "breaking-changes", "href": "/docs/breaking-changes", "crowdinFileId": "256117", "githubUrl": "https://github.com/electron/electron/tree/main/docs/breaking-changes.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least one major version before the change is made.
\nThis document uses the following convention to categorize breaking changes:
\nremote moduleThe remote module was deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.
// Deprecated in Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// Replace with:\nconst { BrowserWindow } = require('@electron/remote')\n\n// In the main process:\nrequire('@electron/remote/main').initialize()\napp.allowRendererProcessReuseThe app.allowRendererProcessReuse property will be removed as part of our plan to more closely align with Chromium's process model for security, performance and maintainability.
For more detailed information see #18397.
\nThe affinity option when constructing a new BrowserWindow will be removed as part of our plan to more closely align with Chromium's process model for security, performance and maintainability.
For more detailed information see #18397.
\nwindow.open()The optional parameter frameName will no longer set the title of the window. This now follows the specification described by the native documentation under the corresponding parameter windowName.
If you were using this parameter to set the title of a window, you can instead use win.setTitle(title).
\nworldSafeExecuteJavaScriptNo Electron 14, worldSafeExecuteJavaScript será removido. There is no alternative, please ensure your code works with this property enabled. It has been enabled by default since Electron\n12.
You will be affected by this change if you use either webFrame.executeJavaScript or webFrame.executeJavaScriptInIsolatedWorld. You will need to ensure that values returned by either of those methods are supported by the Context Bridge API as these methods use the same value passing semantics.
nativeWindowOpen defaults to truePrior to Electron 14, window.open was by default shimmed to use BrowserWindowProxy. This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. nativeWindowOpen is no longer experimental, and is now the default.
See the documentation for window.open in Electron for more details.
\nPrior to Electron 14, windows opened with window.open would inherit BrowserWindow constructor options such as transparent and resizable from their parent window. Beginning with Electron 14, this behavior is removed, and windows will not inherit any BrowserWindow constructor options from their parents.
Instead, explicitly set options for the new window with setWindowOpenHandler:
webContents.setWindowOpenHandler((details) => {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n // ...\n }\n }\n})\nadditionalFeaturesThe deprecated additionalFeatures property in the new-window and did-create-window events of WebContents has been removed. Since new-window uses positional arguments, the argument is still present, but will always be the empty array []. (Though note, the new-window event itself is deprecated, and is replaced by setWindowOpenHandler.) Bare keys in window features will now present as keys with the value true in the options object.
// Removed in Electron 14\n// Triggered by window.open('...', '', 'my-key')\nwebContents.on('did-create-window', (window, details) => {\n if (details.additionalFeatures.includes('my-key')) {\n // ...\n }\n})\n\n// Replace with\nwebContents.on('did-create-window', (window, details) => {\n if (details.options['my-key']) {\n // ...\n }\n})\nsession.setPermissionCheckHandler(handler)The handler methods first parameter was previously always a webContents, it can now sometimes be null. You should use the requestingOrigin, embeddingOrigin and securityOrigin properties to respond to the permission check correctly. As the webContents can be null it can no longer be relied on.
// Old code\nsession.setPermissionCheckHandler((webContents, permission) => {\n if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {\n return true\n }\n return false\n})\n\n// Replace with\nsession.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {\n return true\n }\n return false\n})\nshell.moveItemToTrash()The deprecated synchronous shell.moveItemToTrash() API has been removed. Use the asynchronous shell.trashItem() instead.
// Removed in Electron 13\nshell.moveItemToTrash(path)\n// Replace with\nshell.trashItem(path).then(/* ... */)\nBrowserWindow extension APIsThe deprecated extension APIs have been removed:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()Use the session APIs instead:
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Removed in Electron 13\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Replace with\nsession.defaultSession.loadExtension(path)\n// Removed in Electron 13\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// Replace with\nsession.defaultSession.removeExtension(extension_id)\n// Removed in Electron 13\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Replace with\nsession.defaultSession.getAllExtensions()\nsystemPreferencesThe following systemPreferences methods have been deprecated:
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()Use the following nativeTheme properties instead:
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Removed in Electron 13\nsystemPreferences.isDarkMode()\n// Replace with\nnativeTheme.shouldUseDarkColors\n\n// Removed in Electron 13\nsystemPreferences.isInvertedColorScheme()\n// Replace with\nnativeTheme.shouldUseInvertedColorScheme\n\n// Removed in Electron 13\nsystemPreferences.isHighContrastColorScheme()\n// Replace with\nnativeTheme.shouldUseHighContrastColors\nnew-window eventThe new-window event of WebContents has been deprecated. It is replaced by webContents.setWindowOpenHandler().
// Deprecated in Electron 13\nwebContents.on('new-window', (event) => {\n event.preventDefault()\n})\n\n// Replace with\nwebContents.setWindowOpenHandler((details) => {\n return { action: 'deny' }\n})\nChromium has removed support for Flash, and so we must follow suit. See Chromium's Flash Roadmap for more details.
\nworldSafeExecuteJavaScript defaults to trueIn Electron 12, worldSafeExecuteJavaScript will be enabled by default. To restore the previous behavior, worldSafeExecuteJavaScript: false must be specified in WebPreferences. Please note that setting this option to false is insecure.
This option will be removed in Electron 14 so please migrate your code to support the default value.
\ncontextIsolation defaults to trueIn Electron 12, contextIsolation will be enabled by default. To restore the previous behavior, contextIsolation: false must be specified in WebPreferences.
We recommend having contextIsolation enabled for the security of your application.
\nAnother implication is that require() cannot be used in the renderer process unless nodeIntegration is true and contextIsolation is false.
For more details see: https://github.com/electron/electron/issues/23506
\ncrashReporter.getCrashesDirectory()O método crashReporter.getCrashesDirectory foi removido. Usage should be replaced by app.getPath('crashDumps').
// Removido no Electron 12\ncrashReporter.getCrashesDirectory()\n// Substitua por\napp.getPath('crashDumps')\ncrashReporter methods in the renderer processThe following crashReporter methods are no longer available in the renderer process:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryThey should be called only from the main process.
\nSee #23265 for more details.
\ncrashReporter.start({ compress: true })The default value of the compress option to crashReporter.start has changed from false to true. This means that crash dumps will be uploaded to the crash ingestion server with the Content-Encoding: gzip header, and the body will be compressed.
If your crash ingestion server does not support compressed payloads, you can turn off compression by specifying { compress: false } in the crash reporter options.
remote moduleThe remote module is deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.
// Deprecated in Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// Replace with:\nconst { BrowserWindow } = require('@electron/remote')\n\n// In the main process:\nrequire('@electron/remote/main').initialize()\nshell.moveItemToTrash()The synchronous shell.moveItemToTrash() has been replaced by the new, asynchronous shell.trashItem().
// Descontinuado no Electron 12\nshell.moveItemToTrash(path)\n// Substitua por\nshell.trashItem(path).then(/* ... */)\nBrowserView.{destroy, fromId, fromWebContents, getAllViews} and id property of BrowserViewThe experimental APIs BrowserView.{destroy, fromId, fromWebContents, getAllViews} have now been removed. Additionally, the id property of BrowserView has also been removed.
For more detailed information, see #23578.
\ncompanyName argument to crashReporter.start()The companyName argument to crashReporter.start(), which was previously required, is now optional, and further, is deprecated. To get the same behavior in a non-deprecated way, you can pass a companyName value in globalExtra.
// Deprecated in Electron 10\ncrashReporter.start({ companyName: 'Umbrella Corporation' })\n// Replace with\ncrashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })\ncrashReporter.getCrashesDirectory()The crashReporter.getCrashesDirectory method has been deprecated. Usage should be replaced by app.getPath('crashDumps').
// Deprecated in Electron 10\ncrashReporter.getCrashesDirectory()\n// Replace with\napp.getPath('crashDumps')\ncrashReporter methods in the renderer processCalling the following crashReporter methods from the renderer process is deprecated:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryThe only non-deprecated methods remaining in the crashReporter module in the renderer are addExtraParameter, removeExtraParameter and getParameters.
All above methods remain non-deprecated when called from the main process.
\nSee #23265 for more details.
\ncrashReporter.start({ compress: false })Setting { compress: false } in crashReporter.start is deprecated. Nearly all crash ingestion servers support gzip compression. This option will be removed in a future version of Electron.
enableRemoteModule defaults to falseIn Electron 9, using the remote module without explicitly enabling it via the enableRemoteModule WebPreferences option began emitting a warning. In Electron 10, the remote module is now disabled by default. To use the remote module, enableRemoteModule: true must be specified in WebPreferences:
const w = new BrowserWindow({\n webPreferences: {\n enableRemoteModule: true\n }\n})\nWe recommend moving away from the remote module.
\nprotocol.unregisterProtocolprotocol.uninterceptProtocolThe APIs are now synchronous and the optional callback is no longer needed.
\n// Deprecated\nprotocol.unregisterProtocol(scheme, () => { /* ... */ })\n// Replace with\nprotocol.unregisterProtocol(scheme)\nprotocol.registerFileProtocolprotocol.registerBufferProtocolprotocol.registerStringProtocolprotocol.registerHttpProtocolprotocol.registerStreamProtocolprotocol.interceptFileProtocolprotocol.interceptStringProtocolprotocol.interceptBufferProtocolprotocol.interceptHttpProtocolprotocol.interceptStreamProtocolThe APIs are now synchronous and the optional callback is no longer needed.
\n// Deprecated\nprotocol.registerFileProtocol(scheme, handler, () => { /* ... */ })\n// Replace with\nprotocol.registerFileProtocol(scheme, handler)\nThe registered or intercepted protocol does not have effect on current page until navigation happens.
\nprotocol.isProtocolHandledThis API is deprecated and users should use protocol.isProtocolRegistered and protocol.isProtocolIntercepted instead.
// Deprecated\nprotocol.isProtocolHandled(scheme).then(() => { /* ... */ })\n// Replace with\nconst isRegistered = protocol.isProtocolRegistered(scheme)\nconst isIntercepted = protocol.isProtocolIntercepted(scheme)\nAs of Electron 9 we do not allow loading of non-context-aware native modules in the renderer process. This is to improve security, performance and maintainability of Electron as a project.
\nIf this impacts you, you can temporarily set app.allowRendererProcessReuse to false to revert to the old behavior. This flag will only be an option until Electron 11 so you should plan to update your native modules to be context aware.
For more detailed information see #18397.
\nBrowserWindow extension APIsThe following extension APIs have been deprecated:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()Use the session APIs instead:
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Deprecated in Electron 9\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Replace with\nsession.defaultSession.loadExtension(path)\n// Deprecated in Electron 9\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// Replace with\nsession.defaultSession.removeExtension(extension_id)\n// Deprecated in Electron 9\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Replace with\nsession.defaultSession.getAllExtensions()\n<webview>.getWebContents()This API, which was deprecated in Electron 8.0, is now removed.
\n// Removed in Electron 9.0\nwebview.getWebContents()\n// Replace with\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium has removed support for changing the layout zoom level limits, and it is beyond Electron's capacity to maintain it. The function was deprecated in Electron 8.x, and has been removed in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.
\nIn Electron 8.0, IPC was changed to use the Structured Clone Algorithm, bringing significant performance improvements. To help ease the transition, the old IPC serialization algorithm was kept and used for some objects that aren't serializable with Structured Clone. In particular, DOM objects (e.g. Element, Location and DOMMatrix), Node.js objects backed by C++ classes (e.g. process.env, some members of Stream), and Electron objects backed by C++ classes (e.g. WebContents, BrowserWindow and WebFrame) are not serializable with Structured Clone. Whenever the old algorithm was invoked, a deprecation warning was printed.
In Electron 9.0, the old serialization algorithm has been removed, and sending such non-serializable objects will now throw an \"object could not be cloned\" error.
\nshell.openItem is now shell.openPathThe shell.openItem API has been replaced with an asynchronous shell.openPath API. Você pode ver a proposta original da API e o raciocínio aqui.
The algorithm used to serialize objects sent over IPC (through ipcRenderer.send, ipcRenderer.sendSync, WebContents.send and related methods) has been switched from a custom algorithm to V8's built-in Structured Clone Algorithm, the same algorithm used to serialize messages for postMessage. This brings about a 2x performance improvement for large messages, but also brings some breaking changes in behavior.
undefined.// Previously:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => results in { value: 3 } arriving in the main process\n\n// From Electron 8:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => throws Error(\"() => {} could not be cloned.\")\nNaN, Infinity and -Infinity will now be correctly serialized, instead of being converted to null.null.Set, Map, Error and RegExp values will be correctly serialized, instead of being converted to {}.BigInt values will be correctly serialized, instead of being converted to null.nulls.Date objects will be transferred as Date objects, instead of being converted to their ISO string representation.Uint8Array, Uint16Array, Uint32Array and so on) will be transferred as such, instead of being converted to Node.js Buffer.Buffer objects will be transferred as Uint8Arrays. You can convert a Uint8Array back to a Node.js Buffer by wrapping the underlying ArrayBuffer:Buffer.from(value.buffer, value.byteOffset, value.byteLength)\nSending any objects that aren't native JS types, such as DOM objects (e.g. Element, Location, DOMMatrix), Node.js objects (e.g. process.env, Stream), or Electron objects (e.g. WebContents, BrowserWindow, WebFrame) is deprecated. In Electron 8, these objects will be serialized as before with a DeprecationWarning message, but starting in Electron 9, sending these kinds of objects will throw a 'could not be cloned' error.
<webview>.getWebContents()This API is implemented using the remote module, which has both performance and security implications. Therefore its usage should be explicit.
// Deprecated\nwebview.getWebContents()\n// Replace with\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nHowever, it is recommended to avoid using the remote module altogether.
// main\nconst { ipcMain, webContents } = require('electron')\n\nconst getGuestForWebContents = (webContentsId, contents) => {\n const guest = webContents.fromId(webContentsId)\n if (!guest) {\n throw new Error(`Invalid webContentsId: ${webContentsId}`)\n }\n if (guest.hostWebContents !== contents) {\n throw new Error('Access denied to webContents')\n }\n return guest\n}\n\nipcMain.handle('openDevTools', (event, webContentsId) => {\n const guest = getGuestForWebContents(webContentsId, event.sender)\n guest.openDevTools()\n})\n\n// renderer\nconst { ipcRenderer } = require('electron')\n\nipcRenderer.invoke('openDevTools', webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium has removed support for changing the layout zoom level limits, and it is beyond Electron's capacity to maintain it. The function will emit a warning in Electron 8.x, and cease to exist in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.
\nsystemPreferencesThe following systemPreferences events have been deprecated:
inverted-color-scheme-changedhigh-contrast-color-scheme-changedUse the new updated event on the nativeTheme module instead.
// Deprecated\nsystemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })\nsystemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })\n\n// Replace with\nnativeTheme.on('updated', () => { /* ... */ })\nsystemPreferencesThe following systemPreferences methods have been deprecated:
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()Use the following nativeTheme properties instead:
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Deprecated\nsystemPreferences.isDarkMode()\n// Replace with\nnativeTheme.shouldUseDarkColors\n\n// Deprecated\nsystemPreferences.isInvertedColorScheme()\n// Replace with\nnativeTheme.shouldUseInvertedColorScheme\n\n// Deprecated\nsystemPreferences.isHighContrastColorScheme()\n// Replace with\nnativeTheme.shouldUseHighContrastColors\nThis is the URL specified as disturl in a .npmrc file or as the --dist-url command line flag when building native Node modules. Both will be supported for the foreseeable future but it is recommended that you switch.
Deprecated: https://atom.io/download/electron
\nReplace with: https://electronjs.org/headers
\nsession.clearAuthCache() no longer accepts optionsThe session.clearAuthCache API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.
// Deprecated\nsession.clearAuthCache({ type: 'password' })\n// Replace with\nsession.clearAuthCache()\npowerMonitor.querySystemIdleState is now powerMonitor.getSystemIdleState// Removed in Electron 7.0\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime is now powerMonitor.getSystemIdleTime// Removed in Electron 7.0\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\nwebFrame.setIsolatedWorldInfo replaces separate methods// Removed in Electron 7.0\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Replace with\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nmarked property on getBlinkMemoryInfoThis property was removed in Chromium 77, and as such is no longer available.
\nwebkitdirectory attribute for <input type=\"file\"/> now lists directory contentsThe webkitdirectory property on HTML file inputs allows them to select folders. Previous versions of Electron had an incorrect implementation where the event.target.files of the input returned a FileList that returned one File corresponding to the selected folder.
As of Electron 7, that FileList is now list of all files contained within the folder, similarly to Chrome, Firefox, and Edge (link to MDN docs).
As an illustration, take a folder with this structure:
\nfolder\n├── file1\n├── file2\n└── file3\nIn Electron <=6, this would return a FileList with a File object for:
path/to/folder\nIn Electron 7, this now returns a FileList with a File object for:
/path/to/folder/file3\n/path/to/folder/file2\n/path/to/folder/file1\nNote that webkitdirectory no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).
Electron 5 and Electron 6 introduced Promise-based versions of existing asynchronous APIs and deprecated their older, callback-based counterparts. In Electron 7, all deprecated callback-based APIs are now removed.
\nThese functions now only return Promises:
\napp.getFileIcon() #15742app.dock.show() #16904contentTracing.getCategories() #16583contentTracing.getTraceBufferUsage() #16600contentTracing.startRecording() #16584contentTracing.stopRecording() #16584contents.executeJavaScript() #17312cookies.flushStore() #16464cookies.get() #16464cookies.remove() #16464cookies.set() #16464debugger.sendCommand() #16861dialog.showCertificateTrustDialog() #17181inAppPurchase.getProducts() #17355inAppPurchase.purchaseProduct()#17355netLog.stopLogging() #16862session.clearAuthCache() #17259session.clearCache() #17185session.clearHostResolverCache() #17229session.clearStorageData() #17249session.getBlobData() #17303session.getCacheSize() #17185session.resolveProxy() #17222session.setProxy() #17222shell.openExternal() #16176webContents.loadFile() #15855webContents.loadURL() #15855webContents.hasServiceWorker() #16535webContents.printToPDF() #16795webContents.savePage() #16742webFrame.executeJavaScript() #17312webFrame.executeJavaScriptInIsolatedWorld() #17312webviewTag.executeJavaScript() #17312win.capturePage() #15743These functions now have two forms, synchronous and Promise-based asynchronous:
\ndialog.showMessageBox()/dialog.showMessageBoxSync() #17298dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054win.setMenu(null) is now win.removeMenu()// Deprecated\nwin.setMenu(null)\n// Replace with\nwin.removeMenu()\nelectron.screen in the renderer process should be accessed via remote// Deprecated\nrequire('electron').screen\n// Replace with\nrequire('electron').remote.screen\nrequire()ing node builtins in sandboxed renderers no longer implicitly loads the remote version// Deprecated\nrequire('child_process')\n// Replace with\nrequire('electron').remote.require('child_process')\n\n// Deprecated\nrequire('fs')\n// Replace with\nrequire('electron').remote.require('fs')\n\n// Deprecated\nrequire('os')\n// Replace with\nrequire('electron').remote.require('os')\n\n// Deprecated\nrequire('path')\n// Replace with\nrequire('electron').remote.require('path')\npowerMonitor.querySystemIdleState replaced with powerMonitor.getSystemIdleState// Deprecated\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime replaced with powerMonitor.getSystemIdleTime// Deprecated\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\napp.enableMixedSandbox() is no longer needed// Deprecated\napp.enableMixedSandbox()\nMixed-sandbox mode is now enabled by default.
\nTray.setHighlightModeUnder macOS Catalina our former Tray implementation breaks. Apple's native substitute doesn't support changing the highlighting behavior.
\n// Deprecated\ntray.setHighlightMode(mode)\n// API will be removed in v7.0 without replacement.\nnodeIntegration and webviewTag default to false, contextIsolation defaults to trueThe following webPreferences option default values are deprecated in favor of the new defaults listed below.
| Property | Deprecated Default | New Default |
|---|---|---|
contextIsolation | falso | true |
nodeIntegration | true | falso |
webviewTag | nodeIntegration if set else true | falso |
Ex. Re-enabling the webviewTag
\nconst w = new BrowserWindow({\n webPreferences: {\n webviewTag: true\n }\n})\nnodeIntegration in child windows opened via nativeWindowOpenChild windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is true.
Renderer process APIs webFrame.registerURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. A new API, protocol.registerSchemesAsPrivileged has been added and should be used for registering custom schemes with the required privileges. Custom schemes are required to be registered before app ready.
webFrame.setIsolatedWorld* replaced with webFrame.setIsolatedWorldInfo// Deprecated\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Replace with\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nwebFrame.setSpellCheckProvider now takes an asynchronous callbackThe spellCheck callback is now asynchronous, and autoCorrectWord parameter has been removed.
// Deprecated\nwebFrame.setSpellCheckProvider('en-US', true, {\n spellCheck: (text) => {\n return !spellchecker.isMisspelled(text)\n }\n})\n// Replace with\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck: (words, callback) => {\n callback(words.filter(text => spellchecker.isMisspelled(text)))\n }\n})\nwebContents.getZoomLevel and webContents.getZoomFactor are now synchronouswebContents.getZoomLevel and webContents.getZoomFactor no longer take callback parameters, instead directly returning their number values.
// Deprecated\nwebContents.getZoomLevel((level) => {\n console.log(level)\n})\n// Replace with\nconst level = webContents.getZoomLevel()\nconsole.log(level)\n// Deprecated\nwebContents.getZoomFactor((factor) => {\n console.log(factor)\n})\n// Replace with\nconst factor = webContents.getZoomFactor()\nconsole.log(factor)\nThe following list includes the breaking API changes made in Electron 4.0.
\napp.makeSingleInstance// Deprecated\napp.makeSingleInstance((argv, cwd) => {\n /* ... */\n})\n// Replace with\napp.requestSingleInstanceLock()\napp.on('second-instance', (event, argv, cwd) => {\n /* ... */\n})\napp.releaseSingleInstance// depreciado\napp.releaseSingleInstance()\n// Substituir com\napp.releaseSingleInstanceLock()\napp.getGPUInfoapp.getGPUInfo('complete')\n// Now behaves the same with `basic` on macOS\napp.getGPUInfo('basic')\nwin_delay_load_hookWhen building native modules for windows, the win_delay_load_hook variable in the module's binding.gyp must be true (which is the default). If this hook is not present, then the native module will fail to load on Windows, with an error message like Cannot find module. See the native module guide for more.
A lista a seguir inclui as alterações na API do Election 3.0.
\napp// Deprecated\napp.getAppMemoryInfo()\n// Replace with\napp.getAppMetrics()\n\n// Deprecated\nconst metrics = app.getAppMetrics()\nconst { memory } = metrics[0] // Deprecated property\nBrowserWindow// Deprecated\nconst optionsA = { webPreferences: { blinkFeatures: '' } }\nconst windowA = new BrowserWindow(optionsA)\n// Replace with\nconst optionsB = { webPreferences: { enableBlinkFeatures: '' } }\nconst windowB = new BrowserWindow(optionsB)\n\n// Deprecated\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play_pause') {\n // do something\n }\n})\n// Replace with\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play-pause') {\n // do something\n }\n})\nclipboard// depreciado\nclipboard.readRtf()\n// Substitua com\nclipboard.readRTF()\n\n// depreciado\nclipboard.writeRtf()\n// Substitua com\nclipboard.writeRTF()\n\n// depreciado\nclipboard.readHtml()\n// Substitua com\nclipboard.readHTML()\n\n// depreciado\nclipboard.writeHtml()\n// Substitua com\nclipboard.writeHTML()\ncrashReporter// depreciado\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n autoSubmit: true\n})\n// Substitua com\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n uploadToServer: true\n})\nnativeImage// depreciado\nnativeImage.createFromBuffer(buffer, 1.0)\n// Substitua com\nnativeImage.createFromBuffer(buffer, {\n scaleFactor: 1.0\n})\nprocess// Deprecated\nconst info = process.getProcessMemoryInfo()\nscreen// Deprecated\nscreen.getMenuBarHeight()\n// Replace with\nscreen.getPrimaryDisplay().workArea\nsession// Deprecated\nses.setCertificateVerifyProc((hostname, certificate, callback) => {\n callback(true)\n})\n// Replace with\nses.setCertificateVerifyProc((request, callback) => {\n callback(0)\n})\nTray// Deprecated\ntray.setHighlightMode(true)\n// Replace with\ntray.setHighlightMode('on')\n\n// Deprecated\ntray.setHighlightMode(false)\n// Replace with\ntray.setHighlightMode('off')\nwebContents// Deprecated\nwebContents.openDevTools({ detach: true })\n// Replace with\nwebContents.openDevTools({ mode: 'detach' })\n\n// Removed\nwebContents.setSize(options)\n// There is no replacement for this API\nwebFrame// Deprecated\nwebFrame.registerURLSchemeAsSecure('app')\n// Replace with\nprotocol.registerStandardSchemes(['app'], { secure: true })\n\n// Deprecated\nwebFrame.registerURLSchemeAsPrivileged('app', { secure: true })\n// Replace with\nprotocol.registerStandardSchemes(['app'], { secure: true })\n<webview>// Removed\nwebview.setAttribute('disableguestresize', '')\n// There is no replacement for this API\n\n// Removed\nwebview.setAttribute('guestinstance', instanceId)\n// There is no replacement for this API\n\n// Keyboard listeners no longer work on webview tag\nwebview.onkeydown = () => { /* handler */ }\nwebview.onkeyup = () => { /* handler */ }\nThis is the URL specified as disturl in a .npmrc file or as the --dist-url command line flag when building native Node modules.
Deprecated: https://atom.io/download/atom-shell
\nReplace with: https://atom.io/download/electron
\nThe following list includes the breaking API changes made in Electron 2.0.
\nBrowserWindow// Deprecated\nconst optionsA = { titleBarStyle: 'hidden-inset' }\nconst windowA = new BrowserWindow(optionsA)\n// Replace with\nconst optionsB = { titleBarStyle: 'hiddenInset' }\nconst windowB = new BrowserWindow(optionsB)\nmenu// Removed\nmenu.popup(browserWindow, 100, 200, 2)\n// Replaced with\nmenu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })\nnativeImage// Removed\nnativeImage.toPng()\n// Replaced with\nnativeImage.toPNG()\n\n// Removed\nnativeImage.toJpeg()\n// Replaced with\nnativeImage.toJPEG()\nprocessprocess.versions.electron and process.version.chrome will be made read-only properties for consistency with the other process.versions properties set by Node.webContents// Removed\nwebContents.setZoomLevelLimits(1, 2)\n// Replaced with\nwebContents.setVisualZoomLevelLimits(1, 2)\nwebFrame// Removed\nwebFrame.setZoomLevelLimits(1, 2)\n// Replaced with\nwebFrame.setVisualZoomLevelLimits(1, 2)\n<webview>// Removed\nwebview.setZoomLevelLimits(1, 2)\n// Replaced with\nwebview.setVisualZoomLevelLimits(1, 2)\nEach Electron release includes two identical ARM builds with slightly different filenames, like electron-v1.7.3-linux-arm.zip and electron-v1.7.3-linux-armv7l.zip. The asset with the v7l prefix was added to clarify to users which ARM version it supports, and to disambiguate it from future armv6l and arm64 assets that may be produced.
The file without the prefix is still being published to avoid breaking any setups that may be consuming it. Starting at 2.0, the unprefixed file will no longer be published.
\nFor details, see 6986 and 7189.
", "title": "Breaking Changes", "description": "" }, "/docs/api/browser-view": { "locale": "pt-BR", "slug": "browser-view", "href": "/docs/api/browser-view", "crowdinFileId": "256283", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-view.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Uma BrowserView pode ser usado para transformar um conteúdo web em
BrowserWindow. Ela é como uma janela filha, exceto que ela está posicionada em relação à janela a que pertence. Isso quer dizer que ela pretende ser uma alternativa à tag <code>webview.
\n\nCria e controla views.
\n
Processo: Main
\n// No processo main.\nconst { BrowserView, BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nconst view = new BrowserView()\nwin.setBrowserView(view)\nview.setBounds({ x: 0, y: 0, width: 300, height: 300 })\nview.webContents.loadURL('https://electronjs.org')\nnew BrowserView([options]) Experimentaloptions (opcional) webPreferences Objeto (opcional) - Veja BrowserWindow.Objectos criados com new BrowserView posuem as seguintes propriedades:
view.webContents ExperimentalUm objeto WebContents que pertence à esta vizualização.
Objectos criados com new BrowserView possuem os seguintes métodos de instâncias:
view.setAutoResize(options) Experimentaloptions Object width Boolean (optional) - If true, the view's width will grow and shrink together with the window. false by default.height Boolean (optional) - If true, the view's height will grow and shrink together with the window. false by default.horizontal Boolean (optional) - If true, the view's x position and width will grow and shrink proportionally with the window. false by default.vertical Boolean (optional) - If true, the view's y position and height will grow and shrink proportionally with the window. false by default.view.setBounds(bounds) Experimentalbounds RetânguloResizes and moves the view to the supplied bounds relative to the window.
\nview.getBounds() ExperimentalRetorna Rectangle
The bounds of this BrowserView instance as Object.
view.setBackgroundColor(color) Experimentalcolor String - Color in #aarrggbb or #argb form. The alpha channel is optional.\n\nCrier e controle janelas de navegação.
\n
Processo: Main
\n// No processo main.\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\n// Load a remote URL\nwin.loadURL('https://github.com')\n\n// Or load a local HTML file\nwin.loadFile('index.html')\nPara criar uma janela sem frame ou uma janela transparente de formato arbitrário, use a API Frameless Window.
\nWhen loading a page in the window directly, users may see the page load incrementally, which is not a good experience for a native app. To make the window display without a visual flash, there are two solutions for different situations.
\nready-to-show eventEnquanto a página é carregada, o evento ready-to-show será disparado quando o processo de renderização estiver renderizado completamente a página pela primeira vez, caso a janela ainda não tenha sido exibida. Exibindo a janela após este evento não resultará em um flash visual:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ show: false })\nwin.once('ready-to-show', () => {\n win.show()\n})\nEste evento geralmente é emitido depois do evento did-finish-load, porém para páginas com vários recursos remotos, tal evento pode ser emitido antes.
Please note that using this event implies that the renderer will be considered \"visible\" and paint even though show is false. This event will never fire if you use paintWhenInitiallyHidden: false
backgroundColor propertyPara um aplicativo complexo, o evento ready-to-show poderia ser emitido tarde demais, fazendo com que o aplicativo aparente lentidão. Neste caso, é recomendado exibir a janela imediatamente e utilizar a propriedade backgroundColor com cor semelhante a cor de fundo do seu aplicativo:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ backgroundColor: '#2e2c29' })\nwin.loadURL('https://github.com')\nNote que mesmo para aplicativos que utilizam o evento ready-to-show, é recomendado informar a propriedade backgroundColor para fazer com que o aplicativo passe a sensação de um aplicativo nativo.
Ao utilizar a opção parent, é possível criar janelas secundarias:
const { BrowserWindow } = require('electron')\n\nconst top = new BrowserWindow()\nconst child = new BrowserWindow({ parent: top })\nchild.show()\ntop.show()\nA janela secundaria (child) sempre será exibida em frente a janela principal (top).
Uma janela modal é uma janela secundaria que desabilita a janela principal, para criar uma janela moda, você deve especificar ambas opções parent e modal:
const { BrowserWindow } = require('electron')\n\nconst child = new BrowserWindow({ parent: top, modal: true, show: false })\nchild.loadURL('https://github.com')\nchild.once('ready-to-show', () => {\n child.show()\n})\nA API de visibilidade de página funciona da seguinte forma:
\nhidden. Em outras plataformas, o estado de visibilidade será hidden somente quando a janela for minimizada ou explicitamente ocultada com o método win.hide().BrowserWindow é criado com a propriedade show: false, a visibilidade inicial será visible independente da janela estar de fato ocultada.backgroundThrottling estive desativado, o estado de visibilidade continuará visible mesmo que a janela esteja minimizada, ocultada ou escondida.É recomendado que você pause operações \"caras\" quando o estado de visibilidadade for hidden com o objetivo de minimizar o consumo de energia.
dialog.\n\nCrier e controle janelas de navegação.
\n
Processo: Main
\nBrowserWindow é um EventEmitter.
O mesmo cria um novo BrowserWindow com propriedades nativas informadas como a opção options.
new BrowserWindow([options])options (opcional)width Integer (optional) - Window's width in pixels. Por padrão é 800.height Integer (optional) - Window's height in pixels. Por padrão é 600.x Integer (optional) - (required if y is used) Window's left offset from screen. Default is to center the window.y Integer (optional) - (required if x is used) Window's top offset from screen. Default is to center the window.useContentSize Boolean (optional) - The width and height would be used as web page's size, which means the actual window's size will include window frame's size and be slightly larger. Por padrão é false.center Boolean (opcional) - Mostra a janela no centro da tela.minWidth Integer (optional) - Window's minimum width. Por padrão é 0.minHeight Integer (optional) - Window's minimum height. Por padrão é 0.maxWidth Integer (optional) - Window's maximum width. Default is no limit.maxHeight Integer (optional) - Window's maximum height. Default is no limit.resizable Boolean (optional) - Whether window is resizable. Por padrão é true.movable Boolean (optional) - Whether window is movable. This is not implemented on Linux. Por padrão é true.minimizable Boolean (optional) - Whether window is minimizable. This is not implemented on Linux. Por padrão é true.maximizable Boolean (optional) - Whether window is maximizable. This is not implemented on Linux. Por padrão é true.closable Boolean (optional) - Whether window is closable. This is not implemented on Linux. Por padrão é true.focusable Boolean (optional) - Whether the window can be focused. Default is true. On Windows setting focusable: false also implies setting skipTaskbar: true. On Linux setting focusable: false makes the window stop interacting with wm, so the window will always stay on top in all workspaces.alwaysOnTop Boolean (optional) - Whether the window should always stay on top of other windows. Por padrão é false.fullscreen Boolean (optional) - Whether the window should show in fullscreen. When explicitly set to false the fullscreen button will be hidden or disabled on macOS. Por padrão é false.fullscreenable Boolean (optional) - Whether the window can be put into fullscreen mode. On macOS, also whether the maximize/zoom button should toggle full screen mode or maximize window. Por padrão é true.simpleFullscreen Boolean (optional) - Use pre-Lion fullscreen on macOS. Por padrão é false.skipTaskbar Boolean (optional) - Whether to show the window in taskbar. Default is false.kiosk Boolean (optional) - Whether the window is in kiosk mode. Por padrão é false.title String (optional) - Default window title. Por padrão é \"Electron\". If the HTML tag <title> is defined in the HTML file loaded by loadURL(), this property will be ignored.icon (NativeImage | String) (optional) - The window icon. On Windows it is recommended to use ICO icons to get best visual effects, you can also leave it undefined so the executable's icon will be used.show Boolean (optional) - Whether window should be shown when created. Default is true.paintWhenInitiallyHidden Boolean (optional) - Whether the renderer should be active when show is false and it has just been created. In order for document.visibilityState to work correctly on first load with show: false you should set this to false. Setting this to false will cause the ready-to-show event to not fire. Por padrão é true.frame Boolean (optional) - Specify false to create a Frameless Window. Por padrão é true.parent BrowserWindow (optional) - Specify parent window. Por padrão é null.modal Boolean (optional) - Whether this is a modal window. This only works when the window is a child window. Por padrão é false.acceptFirstMouse Boolean (optional) - Whether clicking an inactive window will also click through to the web contents. Default is false on macOS. This option is not configurable on other platforms.disableAutoHideCursor Boolean (optional) - Whether to hide cursor when typing. Por padrão é false.autoHideMenuBar Boolean (optional) - Auto hide the menu bar unless the Alt key is pressed. Por padrão é false.enableLargerThanScreen Boolean (optional) - Enable the window to be resized larger than screen. Only relevant for macOS, as other OSes allow larger-than-screen windows by default. Por padrão é false.backgroundColor String (optional) - Window's background color as a hexadecimal value, like #66CD00 or #FFF or #80FFFFFF (alpha in #AARRGGBB format is supported if transparent is set to true). Default is #FFF (white).hasShadow Boolean (optional) - Whether window should have a shadow. Por padrão é true.opacity Number (optional) - Set the initial opacity of the window, between 0.0 (fully transparent) and 1.0 (fully opaque). This is only implemented on Windows and macOS.darkTheme Boolean (optional) - Forces using dark theme for the window, only works on some GTK+3 desktop environments. Por padrão é false.transparent Boolean (optional) - Makes the window transparent. Por padrão é false. On Windows, does not work unless the window is frameless.type String (optional) - The type of window, default is normal window. See more about this below.visualEffectState String (optional) - Specify how the material appearance should reflect window activity state on macOS. Must be used with the vibrancy property. Possible values are:followWindow - The backdrop should automatically appear active when the window is active, and inactive when it is not. This is the default.active - The backdrop should always appear active.inactive - The backdrop should always appear inactive.titleBarStyle String (optional) macOS Windows - The style of window title bar. Por padrão é default. Possible values are:default - Results in the standard title bar for macOS or Windows respectively.hidden - Results in a hidden title bar and a full size content window. On macOS, the window still has the standard window controls (“traffic lights”) in the top left. On Windows, when combined with titleBarOverlay: true it will activate the Window Controls Overlay (see titleBarOverlay for more information), otherwise no window controls will be shown.hiddenInset - Only on macOS, results in a hidden title bar with an alternative look where the traffic light buttons are slightly more inset from the window edge.customButtonsOnHover - Only on macOS, results in a hidden title bar and a full size content window, the traffic light buttons will display when being hovered over in the top left of the window. Note: This option is currently experimental.trafficLightPosition Point (optional) - Set a custom position for the traffic light buttons in frameless windows.roundedCorners Boolean (optional) - Whether frameless window should have rounded corners on macOS. Por padrão é true.fullscreenWindowTitle Boolean (optional) Deprecated - Shows the title in the title bar in full screen mode on macOS for hiddenInset titleBarStyle. Por padrão é false.thickFrame Boolean (optional) - Use WS_THICKFRAME style for frameless windows on Windows, which adds standard window frame. Setting it to false will remove window shadow and window animations. Por padrão é true.vibrancy String (optional) - Add a type of vibrancy effect to the window, only on macOS. Can be appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, or under-page. Please note that appearance-based, light, dark, medium-light, and ultra-dark are deprecated and have been removed in macOS Catalina (10.15).zoomToPageWidth Boolean (optional) - Controls the behavior on macOS when option-clicking the green stoplight button on the toolbar or by clicking the Window > Zoom menu item. If true, the window will grow to the preferred width of the web page when zoomed, false will cause it to zoom to the width of the screen. This will also affect the behavior when calling maximize() directly. Por padrão é false.tabbingIdentifier String (optional) - Tab group name, allows opening the window as a native tab on macOS 10.12+. Windows with the same tabbing identifier will be grouped together. This also adds a native new tab button to your window's tab bar and allows your app and window to receive the new-window-for-tab event.webPreferences Object (optional) - Settings of web page's features.devTools Boolean (optional) - Whether to enable DevTools. If it is set to false, can not use BrowserWindow.webContents.openDevTools() to open DevTools. Por padrão é true.nodeIntegration Boolean (optional) - Whether node integration is enabled. Por padrão é false.nodeIntegrationInWorker Boolean (optional) - Whether node integration is enabled in web workers. Por padrão é false. More about this can be found in Multithreading.nodeIntegrationInSubFrames Boolean (optional) - Experimental option for enabling Node.js support in sub-frames such as iframes and child windows. All your preloads will load for every iframe, you can use process.isMainFrame to determine if you are in the main frame or not.preload String (optional) - Specifies a script that will be loaded before other scripts run in the page. This script will always have access to node APIs no matter whether node integration is turned on or off. The value should be the absolute file path to the script. When node integration is turned off, the preload script can reintroduce Node global symbols back to the global scope. See example here.sandbox Boolean (optional) - If set, this will sandbox the renderer associated with the window, making it compatible with the Chromium OS-level sandbox and disabling the Node.js engine. This is not the same as the nodeIntegration option and the APIs available to the preload script are more limited. Read more about the option here.session Session (optional) - Sets the session used by the page. Instead of passing the Session object directly, you can also choose to use the partition option instead, which accepts a partition string. When both session and partition are provided, session will be preferred. Default is the default session.partition String (optional) - Sets the session used by the page according to the session's partition string. If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. If there is no persist: prefix, the page will use an in-memory session. By assigning the same partition, multiple pages can share the same session. Default is the default session.zoomFactor Number (optional) - The default zoom factor of the page, 3.0 represents 300%. Por padrão é 1.0.javascript Boolean (optional) - Enables JavaScript support. Por padrão é true.webSecurity Boolean (optional) - When false, it will disable the same-origin policy (usually using testing websites by people), and set allowRunningInsecureContent to true if this options has not been set by user. Por padrão é true.allowRunningInsecureContent Boolean (optional) - Allow an https page to run JavaScript, CSS or plugins from http URLs. Por padrão é false.images Boolean (optional) - Enables image support. Por padrão é true.imageAnimationPolicy String (optional) - Specifies how to run image animations (E.g. GIFs). Can be animate, animateOnce or noAnimation. Padrão é animate.textAreasAreResizable Boolean (optional) - Make TextArea elements resizable. Default is true.webgl Boolean (optional) - Enables WebGL support. Por padrão é true.plugins Boolean (optional) - Whether plugins should be enabled. Por padrão é false.experimentalFeatures Boolean (optional) - Enables Chromium's experimental features. Por padrão é false.scrollBounce Boolean (optional) - Enables scroll bounce (rubber banding) effect on macOS. Por padrão é false.enableBlinkFeatures String (optional) - A list of feature strings separated by ,, like CSSVariables,KeyboardEventKey to enable. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.disableBlinkFeatures String (optional) - A list of feature strings separated by ,, like CSSVariables,KeyboardEventKey to disable. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.defaultFontFamily Object (optional) - Sets the default font for the font-family.standard String (optional) - Defaults to Times New Roman.serif String (optional) - Defaults to Times New Roman.sansSerif String (optional) - Defaults to Arial.monospace String (optional) - Defaults to Courier New.cursive String (optional) - Defaults to Script.fantasy String (optional) - Defaults to Impact.defaultFontSize Integer (optional) - Defaults to 16.defaultMonospaceFontSize Integer (optional) - Defaults to 13.minimumFontSize Integer (optional) - Defaults to 0.defaultEncoding String (optional) - Defaults to ISO-8859-1.backgroundThrottling Boolean (optional) - Whether to throttle animations and timers when the page becomes background. This also affects the Page Visibility API. Defaults to true.offscreen Boolean (optional) - Whether to enable offscreen rendering for the browser window. Defaults to false. See the offscreen rendering tutorial for more details.contextIsolation Boolean (optional) - Whether to run Electron APIs and the specified preload script in a separate JavaScript context. Defaults to true. The context that the preload script runs in will only have access to its own dedicated document and window globals, as well as its own set of JavaScript builtins (Array, Object, JSON, etc.), which are all invisible to the loaded content. The Electron API will only be available in the preload script and not the loaded page. This option should be used when loading potentially untrusted remote content to ensure the loaded content cannot tamper with the preload script and any Electron APIs being used. This option uses the same technique used by Chrome Content Scripts. You can access this context in the dev tools by selecting the 'Electron Isolated Context' entry in the combo box at the top of the Console tab.nativeWindowOpen Boolean (optional) - Whether to use native window.open(). Defaults to true. Child windows will always have node integration disabled unless nodeIntegrationInSubFrames is true.webviewTag Boolean (optional) - Whether to enable the <webview> tag. Defaults to false. Note: The preload script configured for the <webview> will have node integration enabled when it is executed so you should ensure remote/untrusted content is not able to create a <webview> tag with a possibly malicious preload script. You can use the will-attach-webview event on webContents to strip away the preload script and to validate or alter the <webview>'s initial settings.additionalArguments String - A list of strings that will be appended to process.argv in the renderer process of this app. Useful for passing small bits of data down to renderer process preload scripts.safeDialogs Boolean (optional) - Whether to enable browser style consecutive dialog protection. Por padrão é false.safeDialogsMessage String (optional) - The message to display when consecutive dialog protection is triggered. If not defined the default message would be used, note that currently the default message is in English and not localized.disableDialogs Boolean (optional) - Whether to disable dialogs completely. Overrides safeDialogs. Por padrão é false.navigateOnDragDrop Boolean (optional) - Whether dragging and dropping a file or link onto the page causes a navigation. Por padrão é false.autoplayPolicy String (optional) - Autoplay policy to apply to content in the window, can be no-user-gesture-required, user-gesture-required, document-user-activation-required. Padrão sendo no-user-gesture-required.disableHtmlFullscreenWindowResize Boolean (optional) - Whether to prevent the window from resizing when entering HTML Fullscreen. Default is false.accessibleTitle String (optional) - An alternative title string provided only to accessibility tools such as screen readers. This string is not directly visible to users.spellcheck Boolean (optional) - Whether to enable the builtin spellchecker. Por padrão é true.enableWebSQL Boolean (optional) - Whether to enable the WebSQL api. Por padrão é true.v8CacheOptions String (optional) - Enforces the v8 code caching policy used by blink. Accepted values arenone - Disables code cachingcode - Heuristic based code cachingbypassHeatCheck - Bypass code caching heuristics but with lazy compilationbypassHeatCheckAndEagerCompile - Same as above except compilation is eager. Default policy is code.enablePreferredSizeMode Boolean (optional) - Whether to enable preferred size mode. The preferred size is the minimum size needed to contain the layout of the document—without requiring scrolling. Enabling this will cause the preferred-size-changed event to be emitted on the WebContents when the preferred size changes. Por padrão é false.titleBarOverlay Object | Boolean (optional) - When using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS or using a titleBarStyle so that the standard window controls (\"traffic lights\" on macOS) are visible, this property enables the Window Controls Overlay JavaScript APIs and CSS Environment Variables. Specifying true will result in an overlay with default system colors. Por padrão é false.color String (optional) Windows - The CSS color of the Window Controls Overlay when enabled. Default is the system color.symbolColor String (optional) Windows - The CSS color of the symbols on the Window Controls Overlay when enabled. Default is the system color.When setting minimum or maximum window size with minWidth/maxWidth/ minHeight/maxHeight, it only constrains the users. It won't prevent you from passing a size that does not follow size constraints to setBounds/setSize or to the constructor of BrowserWindow.
The possible values and behaviors of the type option are platform dependent. Possible values are:
desktop, dock, toolbar, splash, notification.desktop, textured.textured type adds metal gradient appearance (NSTexturedBackgroundWindowMask).desktop type places the window at the desktop background window level (kCGDesktopWindowLevel - 1). Note that desktop window will not receive focus, keyboard or mouse events, but you can use globalShortcut to receive input sparingly.toolbar.Objects created with new BrowserWindow emit the following events:
Note: Some events are only available on specific operating systems and are labeled as such.
\nRetorna:
\nevent Eventtitle StringexplicitSet BooleanEmitido quando o documento mudou seu título, chamando event.preventDefault() impedirá que o título da janela nativa mude. explicitSet is false when title is synthesized from file URL.
Retorna:
\nevent EventEmitted when the window is going to be closed. It's emitted before the beforeunload and unload event of the DOM. Calling event.preventDefault() will cancel the close.
Usually you would want to use the beforeunload handler to decide whether the window should be closed, which will also be called when the window is reloaded. In Electron, returning any value other than undefined would cancel the close. Como por exemplo:
window.onbeforeunload = (e) => {\n console.log('I do not want to be closed')\n\n // Unlike usual browsers that a message box will be prompted to users, returning\n // a non-void value will silently cancel the close.\n // It is recommended to use the dialog API to let the user confirm closing the\n // application.\n e.returnValue = false // equivalent to `return false` but not recommended\n}\nNote: There is a subtle difference between the behaviors of window.onbeforeunload = handler and window.addEventListener('beforeunload', handler). It is recommended to always set the event.returnValue explicitly, instead of only returning a value, as the former works more consistently within Electron.
Emitted when the window is closed. After you have received this event you should remove the reference to the window and avoid using it any more.
\nEmitted when window session is going to end due to force shutdown or machine restart or session log off.
\nEmitted when the web page becomes unresponsive.
\nEmitted when the unresponsive web page becomes responsive again.
\nEmitted when the window loses focus.
\nEmitted when the window gains focus.
\nEmitted when the window is shown.
\nEmitted when the window is hidden.
\nEmitted when the web page has been rendered (while not being shown) and window can be displayed without a visual flash.
\nPlease note that using this event implies that the renderer will be considered \"visible\" and paint even though show is false. This event will never fire if you use paintWhenInitiallyHidden: false
Emitted when window is maximized.
\nEmitted when the window exits from a maximized state.
\nEmitted when the window is minimized.
\nEmitted when the window is restored from a minimized state.
\nRetorna:
\nevent EventnewBounds Rectangle - Size the window is being resized to.detailsedge (String) - The edge of the window being dragged for resizing. Can be bottom, left, right, top-left, top-right, bottom-left or bottom-right.Emitted before the window is resized. Calling event.preventDefault() will prevent the window from being resized.
Note that this is only emitted when the window is being resized manually. Resizing the window with setBounds/setSize will not emit this event.
The possible values and behaviors of the edge option are platform dependent. Possible values are:
bottom, top, left, right, top-left, top-right, bottom-left, bottom-right.bottom and right.bottom is used to denote vertical resizing.right is used to denote horizontal resizing.Emitted after the window has been resized.
\nEmitted once when the window has finished being resized.
\nThis 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.
Retorna:
\nevent EventnewBounds Rectangle - Location the window is being moved to.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 resized manually. Resizing the window with setBounds/setSize will not emit this event.
Emitted when the window is being moved to a new position.
\nEmitted once when the window is moved to a new position.
\nNote: On macOS this event is an alias of move.
Emitted when the window enters a full-screen state.
\nEmitted when the window leaves a full-screen state.
\nEmitted when the window enters a full-screen state triggered by HTML API.
\nEmitted when the window leaves a full-screen state triggered by HTML API.
\nRetorna:
\nevent EventisAlwaysOnTop BooleanEmitted when the window is set or unset to show always on top of other windows.
\nRetorna:
\nevent Eventcommand StringEmitted when an App Command is invoked. These are typically related to keyboard media keys or browser commands, as well as the \"Back\" button built into some mice on Windows.
\nCommands are lowercased, underscores are replaced with hyphens, and the APPCOMMAND_ prefix is stripped off. e.g. APPCOMMAND_BROWSER_BACKWARD is emitted as browser-backward.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.on('app-command', (e, cmd) => {\n // Navigate the window back when the user hits their mouse back button\n if (cmd === 'browser-backward' && win.webContents.canGoBack()) {\n win.webContents.goBack()\n }\n})\nThe following app commands are explicitly supported on Linux:
\nbrowser-backwardbrowser-forwardEmitted when scroll wheel event phase has begun.
\nEmitted when scroll wheel event phase has ended.
\nEmitted when scroll wheel event phase filed upon reaching the edge of element.
\nRetorna:
\nevent Eventdirection StringEmitted on 3-finger swipe. Possible directions are up, right, down, left.
The method underlying this event is built to handle older macOS-style trackpad swiping, where the content on the screen doesn't move with the swipe. Most macOS trackpads are not configured to allow this kind of swiping anymore, so in order for it to emit properly the 'Swipe between pages' preference in System Preferences > Trackpad > More Gestures must be set to 'Swipe with two or three fingers'.
Retorna:
\nevent Eventrotation FloatEmitted on trackpad rotation gesture. Continually emitted until rotation gesture is ended. The rotation value on each emission is the angle in degrees rotated since the last emission. The last emitted event upon a rotation gesture will always be of value 0. Counter-clockwise rotation values are positive, while clockwise ones are negative.
Emitted when the window opens a sheet.
\nEmitted when the window has closed a sheet.
\nEmitted when the native new tab button is clicked.
\nRetorna:
\nevent Eventpoint Point - The screen coordinates the context menu was triggered atEmitted when the system context menu is triggered on the window, this is normally only triggered when the user right clicks on the non-client area of your window. This is the window titlebar or any area you have declared as -webkit-app-region: drag in a frameless window.
Calling event.preventDefault() will prevent the menu from being displayed.
A classe BrowserWindow tem os seguintes métodos estáticos:
BrowserWindow.getAllWindows()Returns BrowserWindow[] - An array of all opened browser windows.
BrowserWindow.getFocusedWindow()Returns BrowserWindow | null - The window that is focused in this application, otherwise returns null.
BrowserWindow.fromWebContents(webContents)webContents WebContentsReturns BrowserWindow | null - The window that owns the given webContents or null if the contents are not owned by a window.
BrowserWindow.fromBrowserView(browserView)browserView BrowserViewReturns BrowserWindow | null - The window that owns the given browserView. If the given view is not attached to any window, returns null.
BrowserWindow.fromId(id)id InteiroReturns BrowserWindow | null - The window with the given id.
Objectos criados com new BrowserWindow posuem as seguintes propriedades:
const { BrowserWindow } = require('electron')\n// In this example `win` is our instance\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('https://github.com')\nwin.webContents ReadonlyA WebContents object this window owns. All web page related events and operations will be done via it.
See the webContents documentation for its methods and events.
win.id ReadonlyA Integer property representing the unique ID of the window. Each ID is unique among all BrowserWindow instances of the entire Electron application.
win.autoHideMenuBarA Boolean property that determines whether the window menu bar should hide itself automatically. Once set, the menu bar will only show when users press the single Alt key.
If the menu bar is already visible, setting this property to true won't hide it immediately.
win.simpleFullScreenA Boolean property that determines whether the window is in simple (pre-Lion) fullscreen mode.
win.fullScreenA Boolean property that determines whether the window is in fullscreen mode.
win.focusable Windows macOSA Boolean property that determines whether the window is focusable.
win.visibleOnAllWorkspacesA Boolean property that determines whether the window is visible on all workspaces.
Note: Always returns false on Windows.
\nwin.shadowA Boolean property that determines whether the window has a shadow.
win.menuBarVisible Windows LinuxA 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.kioskA Boolean property that determines whether the window is in kiosk mode.
win.documentEdited macOSA 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 macOSA 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.titleA 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.
\nwin.minimizableA Boolean property that determines whether the window can be manually minimized by user.
On Linux the setter is a no-op, although the getter returns true.
win.maximizableA Boolean property that determines whether the window can be manually maximized by user.
On Linux the setter is a no-op, although the getter returns true.
win.fullScreenableA Boolean property that determines whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
win.resizableA Boolean property that determines whether the window can be manually resized by user.
win.closableA Boolean property that determines whether the window can be manually closed by user.
On Linux the setter is a no-op, although the getter returns true.
win.movableA Boolean property that determines Whether the window can be moved by user.
On Linux the setter is a no-op, although the getter returns true.
win.excludedFromShownWindowsMenu macOSA Boolean property that determines whether the window is excluded from the application’s Windows menu. false by default.
const win = new BrowserWindow({ height: 600, width: 600 })\n\nconst template = [\n {\n role: 'windowmenu'\n }\n]\n\nwin.excludedFromShownWindowsMenu = true\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nwin.accessibleTitleA String property that defines an alternative title provided only to accessibility tools such as screen readers. This string is not directly visible to users.
Objectos criados com new BrowserWindow possuem os seguintes métodos de instâncias:
Nota: Alguns métodos estão disponíveis somente em sistemas operacionais específicos e são rotulados como tal.
\nwin.destroy()Force closing the window, the unload and beforeunload event won't be emitted for the web page, and close event will also not be emitted for this window, but it guarantees the closed event will be emitted.
win.close()Try to close the window. This has the same effect as a user manually clicking the close button of the window. The web page may cancel the close though. See the close event.
\nwin.focus()Focuses on the window.
\nwin.blur()Removes focus from the window.
\nwin.isFocused()Returns Boolean - Whether the window is focused.
win.isDestroyed()Returns Boolean - Whether the window is destroyed.
win.show()Shows and gives focus to the window.
\nwin.showInactive()Shows the window but doesn't focus on it.
\nwin.hide()Hides the window.
\nwin.isVisible()Returns Boolean - Whether the window is visible to the user.
win.isModal()Returns Boolean - Whether current window is a modal window.
win.maximize()Maximizes the window. This will also show (but not focus) the window if it isn't being displayed already.
\nwin.unmaximize()Unmaximizes the window.
\nwin.isMaximized()Returns Boolean - Whether the window is maximized.
win.minimize()Minimizes the window. On some platforms the minimized window will be shown in the Dock.
\nwin.restore()Restores the window from minimized state to its previous state.
\nwin.isMinimized()Returns Boolean - Whether the window is minimized.
win.setFullScreen(flag)flag BooleanSets whether the window should be in fullscreen mode.
\nwin.isFullScreen()Returns Boolean - Whether the window is in fullscreen mode.
win.setSimpleFullScreen(flag) macOSflag BooleanEnters or leaves simple fullscreen mode.
\nSimple fullscreen mode emulates the native fullscreen behavior found in versions of macOS prior to Lion (10.7).
\nwin.isSimpleFullScreen() macOSReturns Boolean - Whether the window is in simple (pre-Lion) fullscreen mode.
win.isNormal()Returns Boolean - Whether the window is in normal state (not maximized, not minimized, not in fullscreen mode).
win.setAspectRatio(aspectRatio[, extraSize])aspectRatio Float - The aspect ratio to maintain for some portion of the content view.extraSize Size (optional) macOS - The extra size not to be included while maintaining the aspect ratio.This will make a window maintain an aspect ratio. The extra size allows a developer to have space, specified in pixels, not included within the aspect ratio calculations. This API already takes into account the difference between a window's size and its content size.
\nConsider a normal window with an HD video player and associated controls. Perhaps there are 15 pixels of controls on the left edge, 25 pixels of controls on the right edge and 50 pixels of controls below the player. In order to maintain a 16:9 aspect ratio (standard aspect ratio for HD @1920x1080) within the player itself we would call this function with arguments of 16/9 and\n{ width: 40, height: 50 }. The second argument doesn't care where the extra width and height are within the content view--only that they exist. Sum any extra width and height areas you have within the overall content view.
\nThe aspect ratio is not respected when window is resized programmatically with APIs like win.setSize.
win.setBackgroundColor(backgroundColor)backgroundColor String - Window's background color as a hexadecimal value, like #66CD00 or #FFF or #80FFFFFF (alpha is supported if transparent is true). Default is #FFF (white).Sets the background color of the window. See Setting backgroundColor.
win.previewFile(path[, displayName]) macOSpath String - The absolute path to the file to preview with QuickLook. This is important as Quick Look uses the file name and file extension on the path to determine the content type of the file to open.displayName String (optional) - The name of the file to display on the Quick Look modal view. This is purely visual and does not affect the content type of the file. O padrão é path.Uses Quick Look to preview a file at a given path.
\nwin.closeFilePreview() macOSCloses the currently open Quick Look panel.
\nwin.setBounds(bounds[, animate])bounds Partial<Rectangle>animate Boolean (optional) macOSResizes and moves the window to the supplied bounds. Any properties that are not supplied will default to their current values.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\n// set all bounds properties\nwin.setBounds({ x: 440, y: 225, width: 800, height: 600 })\n\n// set a single bounds property\nwin.setBounds({ width: 100 })\n\n// { x: 440, y: 225, width: 100, height: 600 }\nconsole.log(win.getBounds())\nwin.getBounds()Retorna Rectangle - Os limites da janela como Objeto.
win.getBackgroundColor()Returns String - Gets the background color of the window. See Setting backgroundColor.
win.setContentBounds(bounds[, animate])bounds Retânguloanimate Boolean (optional) macOSResizes and moves the window's client area (e.g. the web page) to the supplied bounds.
\nwin.getContentBounds()Returns Rectangle - The bounds of the window's client area as Object.
win.getNormalBounds()Returns Rectangle - Contains the window bounds of the normal state
Note: whatever the current state of the window : maximized, minimized or in fullscreen, this function always returns the position and size of the window in normal state. In normal state, getBounds and getNormalBounds returns the same Rectangle.
win.setEnabled(enable)enable BooleanDisable or enable the window.
\nwin.isEnabled()Returns Boolean - whether the window is enabled.
win.setSize(width, height[, animate])width Integerheight Integeranimate Boolean (optional) macOSResizes the window to width and height. If width or height are below any set minimum size constraints the window will snap to its minimum size.
win.getSize()Returns Integer[] - Contains the window's width and height.
win.setContentSize(width, height[, animate])width Integerheight Integeranimate Boolean (optional) macOSResizes the window's client area (e.g. the web page) to width and height.
win.getContentSize()Returns Integer[] - Contains the window's client area's width and height.
win.setMinimumSize(width, height)width Integerheight IntegerSets the minimum size of window to width and height.
win.getMinimumSize()Returns Integer[] - Contains the window's minimum width and height.
win.setMaximumSize(width, height)width Integerheight IntegerSets the maximum size of window to width and height.
win.getMaximumSize()Returns Integer[] - Contains the window's maximum width and height.
win.setResizable(resizable)resizable BooleanSets whether the window can be manually resized by the user.
\nwin.isResizable()Returns Boolean - Whether the window can be manually resized by the user.
win.setMovable(movable) macOS Windowsmovable BooleanSets whether the window can be moved by user. On Linux does nothing.
\nwin.isMovable() macOS WindowsReturns Boolean - Whether the window can be moved by user.
On Linux always returns true.
win.setMinimizable(minimizable) macOS Windowsminimizable BooleanSets whether the window can be manually minimized by user. On Linux does nothing.
\nwin.isMinimizable() macOS WindowsReturns Boolean - Whether the window can be manually minimized by the user.
On Linux always returns true.
win.setMaximizable(maximizable) macOS Windowsmaximizable BooleanSets whether the window can be manually maximized by user. On Linux does nothing.
\nwin.isMaximizable() macOS WindowsReturns Boolean - Whether the window can be manually maximized by user.
On Linux always returns true.
win.setFullScreenable(fullscreenable)fullscreenable BooleanSets whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
\nwin.isFullScreenable()Returns Boolean - Whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
win.setClosable(closable) macOS Windowsclosable BooleanSets whether the window can be manually closed by user. On Linux does nothing.
\nwin.isClosable() macOS WindowsReturns Boolean - Whether the window can be manually closed by user.
On Linux always returns true.
win.setAlwaysOnTop(flag[, level][, relativeLevel])flag Booleanlevel String (optional) macOS Windows - Values include normal, floating, torn-off-menu, modal-panel, main-menu, status, pop-up-menu, screen-saver, and dockfloating when flag is true. The level is reset to normal when the flag is false. Note that from floating to status included, the window is placed below the Dock on macOS and below the taskbar on Windows. From pop-up-menu to a higher it is shown above the Dock on macOS and above the taskbar on Windows. See the macOS docs for more details.relativeLevel Integer (optional) macOS - The number of layers higher to set this window relative to the given level. O padrão é 0. Note that Apple discourages setting levels higher than 1 above screen-saver.Sets whether the window should show always on top of other windows. After setting this, the window is still a normal window, not a toolbox window which can not be focused on.
\nwin.isAlwaysOnTop()Returns Boolean - Whether the window is always on top of other windows.
win.moveAbove(mediaSourceId)mediaSourceId String - Window id in the format of DesktopCapturerSource's id. For example \"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()Moves window to top(z-order) regardless of focus
\nwin.center()Moves window to the center of the screen.
\nwin.setPosition(x, y[, animate])x Integery Integeranimate Boolean (optional) macOSMoves window to x and y.
win.getPosition()Returns Integer[] - Contains the window's current position.
win.setTitle(title)title StringChanges the title of native window to title.
win.getTitle()Returns String - The title of the native window.
Note: The title of the web page can be different from the title of the native window.
\nwin.setSheetOffset(offsetY[, offsetX]) macOSoffsetY FloatoffsetX Float (optional)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. Como por exemplo:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nconst toolbarRect = document.getElementById('toolbar').getBoundingClientRect()\nwin.setSheetOffset(toolbarRect.height)\nwin.flashFrame(flag)flag BooleanStarts or stops flashing the window to attract user's attention.
\nwin.setSkipTaskbar(skip)skip BooleanMakes the window not show in the taskbar.
\nwin.setKiosk(flag)flag BooleanEnters or leaves kiosk mode.
\nwin.isKiosk()Returns Boolean - Whether the window is in kiosk mode.
win.isTabletMode() WindowsReturns Boolean - Whether the window is in Windows 10 tablet mode.
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.
\nThis API returns whether the window is in tablet mode, and the resize event can be be used to listen to changes to tablet mode.
win.getMediaSourceId()Returns String - Window id in the format of DesktopCapturerSource's id. For example \"window:1324:0\".
More precisely the format is window:id:other_id where id is HWND on Windows, CGWindowID (uint64_t) on macOS and Window (unsigned long) on Linux. other_id is used to identify web contents (tabs) so within the same top level window.
win.getNativeWindowHandle()Returns Buffer - The platform-specific handle of the window.
The native type of the handle is HWND on Windows, NSView* on macOS, and Window (unsigned long) on Linux.
win.hookWindowMessage(message, callback) Windowsmessage Integercallback FunctionwParam any - The wParam provided to the WndProclParam any - The lParam provided to the WndProcHooks a windows message. The callback is called when the message is received in the WndProc.
win.isWindowMessageHooked(message) Windowsmessage IntegerReturns Boolean - true or false depending on whether the message is hooked.
win.unhookWindowMessage(message) Windowsmessage IntegerUnhook the window message.
\nwin.unhookAllWindowMessages() WindowsUnhooks all of the window messages.
\nwin.setRepresentedFilename(filename) macOSfilename StringSets the pathname of the file the window represents, and the icon of the file will show in window's title bar.
\nwin.getRepresentedFilename() macOSReturns String - The pathname of the file the window represents.
win.setDocumentEdited(edited) macOSedited BooleanSpecifies whether the window’s document has been edited, and the icon in title bar will become gray when set to true.
win.isDocumentEdited() macOSReturns Boolean - Whether the window's document has been edited.
win.focusOnWebView()win.blurWebView()win.capturePage([rect])rect Rectangle (optional) - The bounds to captureReturns Promise<NativeImage> - Resolves with a NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page. If the page is not visible, rect may be empty.
win.loadURL(url[, options])urloptions (opcional)httpReferrer (String | Referrer) (optional) - An HTTP Referrer URL.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base URL (with trailing path separator) for files to be loaded by the data URL. This is needed only if the specified url is a data URL and needs to load other files.Returns Promise<void> - the promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load).
Same as webContents.loadURL(url[, options]).
The url can be a remote address (e.g. http://) or a path to a local HTML file using the file:// protocol.
To ensure that file URLs are properly formatted, it is recommended to use Node's url.format method:
const url = require('url').format({\n protocol: 'file',\n slashes: true,\n pathname: require('path').join(__dirname, 'index.html')\n})\n\nwin.loadURL(url)\nYou can load a URL using a POST request with URL-encoded data by doing the following:
win.loadURL('http://localhost:8000/post', {\n postData: [{\n type: 'rawData',\n bytes: Buffer.from('hello=world')\n }],\n extraHeaders: 'Content-Type: application/x-www-form-urlencoded'\n})\nwin.loadFile(filePath[, options])filePath Stringoptions (opcional)query Record<String, String> (optional) - Passed to url.format().search String (optional) - Passed to url.format().hash String (optional) - Passed to url.format().Returns Promise<void> - the promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load).
Same as webContents.loadFile, filePath should be a path to an HTML file relative to the root of your application. See the webContents docs for more information.
win.reload()Same as webContents.reload.
win.setMenu(menu) Linux Windowsmenu Menu | nullSets the menu as the window's menu bar.
win.removeMenu() Linux WindowsRemove the window's menu bar.
\nwin.setProgressBar(progress[, options])progress Doubleoptions (opcional)mode String Windows - Mode for the progress bar. Can be none, normal, indeterminate, error or paused.Sets progress value in progress bar. Valid range is [0, 1.0].
\nRemove progress bar when progress < 0; Change to indeterminate mode when progress > 1.
\nOn Linux platform, only supports Unity desktop environment, you need to specify the *.desktop file name to desktopName field in package.json. By default, it will assume {app.name}.desktop.
On Windows, a mode can be passed. Accepted values are none, normal, indeterminate, error, and paused. If you call setProgressBar without a mode set (but with a value within the valid range), normal will be assumed.
win.setOverlayIcon(overlay, description) Windowsoverlay NativeImage | null - the icon to display on the bottom right corner of the taskbar icon. If this parameter is null, the overlay is cleareddescription String - a description that will be provided to Accessibility screen readersSets a 16 x 16 pixel overlay onto the current taskbar icon, usually used to convey some sort of application status or to passively notify the user.
\nwin.setHasShadow(hasShadow)hasShadow BooleanSets whether the window should have a shadow.
\nwin.hasShadow()Returns Boolean - Whether the window has a shadow.
win.setOpacity(opacity) Windows macOSopacity Number - between 0.0 (fully transparent) and 1.0 (fully opaque)Sets the opacity of the window. On Linux, does nothing. Out of bound number values are clamped to the [0, 1] range.
\nwin.getOpacity()Returns Number - between 0.0 (fully transparent) and 1.0 (fully opaque). On Linux, always returns 1.
win.setShape(rects) Windows Linux Experimentalrects Rectangle[] - Sets a shape on the window. Passing an empty list reverts the window to being rectangular.Setting a window shape determines the area within the window where the system permits drawing and user interaction. Outside of the given region, no pixels will be drawn and no mouse events will be registered. Mouse events outside of the region will not be received by that window, but will fall through to whatever is behind the window.
\nwin.setThumbarButtons(buttons) Windowsbuttons ThumbarButton[]Returns Boolean - Whether the buttons were added successfully
Add a thumbnail toolbar with a specified set of buttons to the thumbnail image of a window in a taskbar button layout. Returns a Boolean object indicates whether the thumbnail has been added successfully.
The number of buttons in thumbnail toolbar should be no greater than 7 due to the limited room. Once you setup the thumbnail toolbar, the toolbar cannot be removed due to the platform's limitation. But you can call the API with an empty array to clean the buttons.
\nThe buttons is an array of Button objects:
Button Objecticon NativeImage - O icone exibido na barra de ferramentas de miniaturas.click Functiontooltip String (opcional) - O texto do tooltip do botão.flags String - Control specific states and behaviors of the button. By default, it is ['enabled'].As flags são um array que pode conter as seguintes Strings:
enabled - O botão está ativo e disponível ao usuário.disabled - The button is disabled. It is present, but has a visual state indicating it will not respond to user action.dismissonclick - Quando o botão é clicado, o janela da miniatura é fechada imediatamente.nobackground - Não desenha a borda do botão, utiliza apenas a imagem.hidden - O botão não é exibido ao usuário.noninteractive - The button is enabled but not interactive; no pressed button state is drawn. This value is intended for instances where the button is used in a notification.win.setThumbnailClip(region) Windowsregion Rectangle - Region of the windowSets the region of the window to show as the thumbnail image displayed when hovering over the window in the taskbar. You can reset the thumbnail to be the entire window by specifying an empty region: { x: 0, y: 0, width: 0, height: 0 }.
win.setThumbnailToolTip(toolTip) WindowstoolTip StringSets the toolTip that is displayed when hovering over the window thumbnail in the taskbar.
\nwin.setAppDetails(options) Windowsoptions ObjectappId String (optional) - Window's App User Model ID. It has to be set, otherwise the other options will have no effect.appIconPath String (optional) - Window's Relaunch Icon.appIconIndex Integer (optional) - Index of the icon in appIconPath. Ignored when appIconPath is not set. Por padrão é 0.relaunchCommand String (optional) - Window's Relaunch Command.relaunchDisplayName String (optional) - Window's Relaunch Display Name.Sets the properties for the window's taskbar button.
\nNote: relaunchCommand and relaunchDisplayName must always be set together. If one of those properties is not set, then neither will be used.
win.showDefinitionForSelection() macOSSame as webContents.showDefinitionForSelection().
win.setIcon(icon) Windows Linuxicon NativeImage | StringChanges window icon.
\nwin.setWindowButtonVisibility(visible) macOSvisible BooleanSets whether the window traffic light buttons should be visible.
\nwin.setAutoHideMenuBar(hide)hide BooleanSets whether the window menu bar should hide itself automatically. 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()Returns Boolean - Whether menu bar automatically hides itself.
win.setMenuBarVisibility(visible) Windows Linuxvisible BooleanSets whether the menu bar should be visible. If the menu bar is auto-hide, users can still bring up the menu bar by pressing the single Alt key.
win.isMenuBarVisible()Returns Boolean - Whether the menu bar is visible.
win.setVisibleOnAllWorkspaces(visible[, options])visible Booleanoptions (opcional)visibleOnFullScreen Boolean (optional) macOS - Sets whether the window should be visible above fullscreen windows.skipTransformProcessType Boolean (optional) macOS - Calling setVisibleOnAllWorkspaces will by default transform the process type between UIElementApplication and ForegroundApplication to ensure the correct behavior. However, this will hide the window and dock for a short time every time it is called. If your window is already of type UIElementApplication, you can bypass this transformation by passing true to skipTransformProcessType.Sets whether the window should be visible on all workspaces.
\nNote: This API does nothing on Windows.
\nwin.isVisibleOnAllWorkspaces()Returns Boolean - Whether the window is visible on all workspaces.
Note: This API always returns false on Windows.
\nwin.setIgnoreMouseEvents(ignore[, options])ignore Booleanoptions (opcional)forward Boolean (optional) macOS Windows - If true, forwards mouse move messages to Chromium, enabling mouse related events such as mouseleave. Only used when ignore is true. If ignore is false, forwarding is always disabled regardless of this value.Makes the window ignore all mouse events.
\nAll mouse events happened in this window will be passed to the window below this window, but if this window has focus, it will still receive keyboard events.
\nwin.setContentProtection(enable) macOS Windowsenable BooleanPrevents the window contents from being captured by other apps.
\nOn 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 Windowsfocusable BooleanChanges whether the window can be focused.
\nOn macOS it does not remove the focus from the window.
\nwin.isFocusable() macOS WindowsReturns whether the window can be focused.
\nwin.setParentWindow(parent)parent BrowserWindow | nullSets parent as current window's parent window, passing null will turn current window into a top-level window.
win.getParentWindow()Returns BrowserWindow - The parent window.
win.getChildWindows()Returns BrowserWindow[] - All child windows.
win.setAutoHideCursor(autoHide) no macOSautoHide BooleanControls whether to hide cursor when typing.
\nwin.selectPreviousTab() no macOSSelects the previous tab when native tabs are enabled and there are other tabs in the window.
\nwin.selectNextTab() no macOSSelects the next tab when native tabs are enabled and there are other tabs in the window.
\nwin.mergeAllWindows() no macOSMerges all windows into one window with multiple tabs when native tabs are enabled and there is more than one open window.
\nwin.moveTabToNewWindow() no macOSMoves the current tab into a new window if native tabs are enabled and there is more than one tab in the current window.
\nwin.toggleTabBar() no macOSToggles the visibility of the tab bar if native tabs are enabled and there is only one tab in the current window.
\nwin.addTabbedWindow(browserWindow) no macOSbrowserWindow BrowserWindowAdds a window as a tab on this window, after the tab for the window instance.
\nwin.setVibrancy(type) macOStype String | null - Can be appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, or under-page. See the macOS documentation for more details.Adds a vibrancy effect to the browser window. Passing null or an empty string will remove the vibrancy effect on the window.
Note that appearance-based, light, dark, medium-light, and ultra-dark have been deprecated and will be removed in an upcoming version of macOS.
win.setTrafficLightPosition(position) no macOSposition PointSet a custom position for the traffic light buttons in frameless window.
\nwin.getTrafficLightPosition() no macOSReturns Point - The custom position for the traffic light buttons in frameless window.
win.setTouchBar(touchBar) no macOStouchBar TouchBar | nullSets the touchBar layout for the current window. Specifying null or undefined clears the touch bar. This method only has an effect if the machine has a touch bar and is running on macOS 10.12.1+.
Note: The TouchBar API is currently experimental and may change or be removed in future Electron releases.
\nwin.setBrowserView(browserView) ExperimentalbrowserView BrowserView | null - Attach browserView to win. If there are other BrowserViews attached, they will be removed from this window.win.getBrowserView() ExperimentalReturns BrowserView | null - The BrowserView attached to win. Returns null if one is not attached. Throws an error if multiple BrowserViews are attached.
win.addBrowserView(browserView) ExperimentalbrowserView BrowserViewReplacement API for setBrowserView supporting work with multi browser views.
\nwin.removeBrowserView(browserView) ExperimentalbrowserView BrowserViewwin.setTopBrowserView(browserView) ExperimentalbrowserView BrowserViewRaises browserView above other BrowserViews attached to win. Throws an error if browserView is not attached to win.
win.getBrowserViews() ExperimentalReturns BrowserView[] - an array of all BrowserViews that have been attached with addBrowserView or setBrowserView.
Nota: A API BrowserView atualmente é experimental e pode mudar ou ser removida em versões futuras do Electron.
", "title": "BrowserWindow", "description": "Crier e controle janelas de navegação." }, "/docs/api/browser-window-proxy": { "locale": "pt-BR", "slug": "browser-window-proxy", "href": "/docs/api/browser-window-proxy", "crowdinFileId": "256285", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-window-proxy.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nManipular a janela filha
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The BrowserWindowProxy object is returned from window.open and provides limited functionality with the child window.
O objeto BrowserWindowProxy possui os seguintes métodos de instância:
win.blur()Remove o foco da janela filha.
\nwin.close()Forçadamente fecha a janela filha sem chamar o evento unload.
\nwin.eval(code)code StringEvaluates the code in the child window.
\nwin.focus()Focuses the child window (brings the window to front).
\nwin.print()Invokes the print dialog on the child window.
\nwin.postMessage(message, targetOrigin)message anytargetOrigin StringSends a message to the child window with the specified origin or * for no origin preference.
In addition to these methods, the child window implements window.opener object with no properties and a single method.
The BrowserWindowProxy object has the following instance properties:
win.closedA Boolean that is set to true after the child window gets closed.
Follow the guidelines below for building Electron itself, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nVerifique os pré-requisitos de compilação para sua plataforma antes de prosseguir
\n\nElectron's Build Tools automate much of the setup for compiling Electron from source with different configurations and build targets. If you wish to set up the environment manually, the instructions are listed below.
\nVocê precisará instalar depot_tools, o toolset usado para obter Chromium e suas dependências.
Also, on Windows, you'll need to set the environment variable DEPOT_TOOLS_WIN_TOOLCHAIN=0. To do so, open Control Panel → System and Security → System → Advanced system settings and add a system variable DEPOT_TOOLS_WIN_TOOLCHAIN with value 0. This tells depot_tools to use your locally installed version of Visual Studio (by default, depot_tools will try to download a Google-internal version that only Googlers have access to).
If you plan on checking out Electron more than once (for example, to have multiple parallel directories checked out to different branches), using the git cache will speed up subsequent calls to gclient. To do this, set a GIT_CACHE_PATH environment variable:
$ export GIT_CACHE_PATH=\"${HOME}/.git_cache\"\n$ mkdir -p \"${GIT_CACHE_PATH}\"\n# This will use about 16G.\n$ mkdir electron && cd electron\n$ gclient config --name \"src/electron\" --unmanaged https://github.com/electron/electron\n$ gclient sync --with_branch_heads --with_tags\n# This will take a while, go get a coffee.\n\n\nInstead of
\nhttps://github.com/electron/electron, you can use your own fork here (something likehttps://github.com/<username>/electron).
If you intend to git pull or git push from the official electron repository in the future, you now need to update the respective folder's origin URLs.
$ cd src/electron\n$ git remote remove origin\n$ git remote add origin https://github.com/electron/electron\n$ git checkout main\n$ git branch --set-upstream-to=origin/main\n$ cd -\n📝 gclient works by checking a file called DEPS inside the src/electron folder for dependencies (like Chromium or Node.js). Running gclient sync -f ensures that all dependencies required to build Electron match that file.
So, in order to pull, you'd run the following commands:
\n$ cd src/electron\n$ git pull\n$ gclient sync -f\n$ cd src\n$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nOr on Windows (without the optional argument):
\n$ cd src\n$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\\buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\")\"\nThis will generate a build directory out/Testing under src/ with the testing build configuration. You can replace Testing with another name, but it should be a subdirectory of out. Also you shouldn't have to run gn gen again—if you want to change the build arguments, you can run gn args out/Testing to bring up an editor.
To see the list of available build configuration options, run gn args out/Testing --list.
For generating Testing build config of Electron:
\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nFor generating Release (aka \"non-component\" or \"static\") build config of Electron:
\n$ gn gen out/Release --args=\"import(\\\"//electron/build/args/release.gn\\\") $GN_EXTRA_ARGS\"\nTo build, run ninja with the electron target: Nota Bene: This will also take a while and probably heat up your lap.
For the testing configuration:
\n$ ninja -C out/Testing electron\nFor the release configuration:
\n$ ninja -C out/Release electron\nThis will build all of what was previously 'libchromiumcontent' (i.e. the content/ directory of chromium and its dependencies, incl. WebKit and V8), so it will take a while.
The built executable will be under ./out/Testing:
$ ./out/Testing/Electron.app/Contents/MacOS/Electron\n# or, on Windows\n$ ./out/Testing/electron.exe\n# or, on Linux\n$ ./out/Testing/electron\nOn linux, first strip the debugging and symbol information:
\nelectron/script/strip-binaries.py -d out/Release\nTo package the electron build as a distributable zip file:
\nninja -C out/Release electron:electron_dist_zip\nTo compile for a platform that isn't the same as the one you're building on, set the target_cpu and target_os GN arguments. For example, to compile an x86 target from an x64 host, specify target_cpu = \"x86\" in gn args.
$ gn gen out/Testing-x86 --args='... target_cpu = \"x86\"'\nNot all combinations of source and target CPU/OS are supported by Chromium.
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Host | Objetivo | Status |
|---|---|---|
| Windows x64 | Windows arm64 | Experimental |
| Windows x64 | Windows x86 | Testado automaticamente |
| Linux x64 | Linux x86 | Testado automaticamente |
If you test other combinations and find them to work, please update this document :)
\nSee the GN reference for allowable values of target_os and target_cpu.
To cross-compile for Windows on Arm, follow Chromium's guide to get the necessary dependencies, SDK and libraries, then build with ELECTRON_BUILDING_WOA=1 in your environment before running gclient sync.
set ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nOu (se usando PowerShell):
\n$env:ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nNext, run gn gen as above with target_cpu=\"arm64\".
To run the tests, you'll first need to build the test modules against the same version of Node.js that was built as part of the build process. To generate build headers for the modules to compile against, run the following under src/ directory.
$ ninja -C out/Testing third_party/electron_node:headers\nYou can now run the tests.
\nIf you're debugging something, it can be helpful to pass some extra flags to the Electron binary:
\n$ npm run test -- \\\n --enable-logging -g 'BrowserWindow module'\nIt is possible to share the gclient git cache with other machines by exporting it as SMB share on linux, but only one process/machine can be using the cache at a time. The locks created by git-cache script will try to prevent this, but it may not work perfectly in a network.
\nOn Windows, SMBv2 has a directory cache that will cause problems with the git cache script, so it is necessary to disable it by setting the registry key
\nHKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\\DirectoryCacheLifetime\nto 0. More information: https://stackoverflow.com/a/9935126
\nThis can be set quickly in powershell (ran as administrator):
\nNew-ItemProperty -Path \"HKLM:\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force\nIf gclient sync is interrupted the git tree may be left in a bad state, leading to a cryptic message when running gclient sync in the future:
2> Conflict while rebasing this branch.\n2> Fix the conflict and run gclient again.\n2> See man git-rebase for details.\nIf there are no git conflicts or rebases in src/electron, you may need to abort a git am in src:
$ cd ../\n$ git am --abort\n$ cd electron\n$ gclient sync -f\nSe você ver um prompt solicitando o Usuário em 'https://chrome-internal.googlesource.com': ao executar o gclient sync no Windows, Provavelmente é porque a variável de ambiente DEPOT_TOOLS_WIN_TOOLCHAIN não está definida como 0. Abra Painel de Controle → Sistema e Segurança → Sistema → Configurações avançadas do sistema e adicione uma variável do sistema chamada DEPOT_TOOLS_WIN_TOOLCHAIN com valor 0. This tells depot_tools to use your locally installed version of Visual Studio (by default, depot_tools will try to download a Google-internal version that only Googlers have access to).
Follow the guidelines below for building Electron itself on Linux, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nAt least 25GB disk space and 8GB RAM.
\nPython 2.7.x. Some distributions like CentOS 6.x still use Python 2.6.x so you may need to check your Python version with python -V.
Please also ensure that your system and Python version support at least TLS 1.2. For a quick test, run the following script:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, use your system's package manager to update Python to the latest version in the 2.7.x branch. Alternatively, visit https://www.python.org/downloads/ for detailed instructions.
\nNode.js. There are various ways to install Node. You can download source code from nodejs.org and compile it. Doing so permits installing Node on your own home directory as a standard user. Or try repositories such as NodeSource.
\nclang 3.4 or later.
\nDevelopment headers of GTK 3 and libnotify.
\nOn Ubuntu, install the following libraries:
\n$ sudo apt-get install build-essential clang libdbus-1-dev libgtk-3-dev \\\n libnotify-dev libgnome-keyring-dev \\\n libasound2-dev libcap-dev libcups2-dev libxtst-dev \\\n libxss1 libnss3-dev gcc-multilib g++-multilib curl \\\n gperf bison python-dbusmock openjdk-8-jre\nOn RHEL / CentOS, install the following libraries:
\n$ sudo yum install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Fedora, install the following libraries:
\n$ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Arch Linux / Manjaro, install the following libraries:
\n$ sudo pacman -Syu base-devel clang libdbus gtk2 libnotify \\\n libgnome-keyring alsa-lib libcap libcups libxtst \\\n libxss nss gcc-multilib curl gperf bison \\\n python2 python-dbusmock jdk8-openjdk\nOther distributions may offer similar packages for installation via package managers such as pacman. Or one can compile from source code.
\nIf you want to build for an arm target you should also install the following dependencies:
$ sudo apt-get install libc6-dev-armhf-cross linux-libc-dev-armhf-cross \\\n g++-arm-linux-gnueabihf\nSimilarly for arm64, install the following:
$ sudo apt-get install libc6-dev-arm64-cross linux-libc-dev-arm64-cross \\\n g++-aarch64-linux-gnu\nAnd to cross-compile for arm or ia32 targets, you should pass the target_cpu parameter to gn gen:
$ gn gen out/Testing --args='import(...) target_cpu=\"arm\"'\nPrebuilt clang will try to link to libtinfo.so.5. Depending on the host architecture, symlink to appropriate libncurses:
$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5\nThe default building configuration is targeted for major desktop Linux distributions. To build for a specific distribution or device, the following information may help you.
\nclang instead of downloaded clang binariesBy default Electron is built with prebuilt clang binaries provided by the Chromium project. If for some reason you want to build with the clang installed in your system, you can specify the clang_base_path argument in the GN args.
For example if you installed clang under /usr/local/bin/clang:
$ gn gen out/Testing --args='import(\"//electron/build/args/testing.gn\") clang_base_path = \"/usr/local/bin\"'\nclangBuilding Electron with compilers other than clang is not supported.
Follow the guidelines below for building Electron itself on macOS, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nPlease also ensure that your system and Python version support at least TLS 1.2. This depends on both your version of macOS and Python. For a quick test, run:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, you can either update macOS to High Sierra or install a new version of Python 2.7.x. To upgrade Python, use Homebrew:
\n$ brew install python@2 && brew link python@2 --force\nIf you are using Python as provided by Homebrew, you also need to install the following Python modules:
\nYou can use pip to install it:
$ pip instalar pyobjc\nSe está desenvolvendo com Electron e não planeja redistribuir sua construção personalizada, pode pular essa seção.
\nOfficial Electron builds are built with Xcode 12.2, and the macOS 11.0 SDK. Compilar com um SDK mais recente também funciona, mas os lançamentos atualmente usam o SDK 11.0.
\nVeja Instruções de build: GN.
", "title": "Instruções de Compilação (macOS)", "description": "" }, "/docs/development/build-instructions-windows": { "locale": "pt-BR", "slug": "build-instructions-windows", "href": "/docs/development/build-instructions-windows", "crowdinFileId": "256137", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/build-instructions-windows.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Follow the guidelines below for building Electron itself on Windows, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nvs2019_install = DRIVE:\\path\\to\\Microsoft Visual Studio\\2019\\Community, replacing 2019 and Community with your installed versions and replacing DRIVE: with the drive that Visual Studio is on. Often, this will be C:.WINDOWSSDKDIR = DRIVE:\\path\\to\\Windows Kits\\10, replacing DRIVE: with the drive that Windows Kits is on. Often, this will be C:.symstore.exe is used for creating a symbol store from .pdb files.Modify → Individual Components, scroll down and select the appropriate Windows SDK to install. Another option would be to look at the Windows SDK and emulator archive and download the standalone version of the SDK respectively.Control Panel → Programs → Programs and Features → Select the \"Windows Software Development Kit\" → Change → Change → Check \"Debugging Tools For Windows\" → Change. Or, you can download the standalone SDK installer and use it to install the Debugging Tools.Caso você não tenha uma instalação do Windows, acesso o endereço dev.microsoftedge.com, tem uma versão para que possa configurar o Electron.
\nA configuração do Electron é feita totalmente por linha de comando, não é possível fazer pelo o Visual Studio. Você pode desenvolver com Electron utilizando qualquer editor, futuramente haverá suporte para o Visual Studio.
\nNote: Mesmo que o Visual Studio não seja utilizado para desenvolver com Electron, ainda é preciso ter instalado. required Porque é necessário a toolchains fornecida.
\nWindows Security doesn't like one of the files in the Chromium source code (see https://crbug.com/441184), so it will constantly delete it, causing gclient sync issues. You can exclude the source tree from being monitored by Windows Security by following these instructions.
To build for the 32bit target, you need to pass target_cpu = \"x86\" as a GN arg. You can build the 32bit target alongside the 64bit target by using a different output directory for GN, e.g. out/Release-x86, with different arguments.
$ gn gen out/Release-x86 --args=\"import(\\\"//electron/build/args/release.gn\\\") target_cpu=\\\"x86\\\"\"\nOs outros passos para a compilação são os mesmos.
\nTo generate a Visual Studio project, you can pass the --ide=vs2017 parameter to gn gen:
$ gn gen out/Testing --ide=vs2017\nSe você encontrar um erro parecido com Command xxxx not found, você pode tentar usar o console do Prompt de Comando do VS2015 para executar os scripts do build.
Verifique se você tem a atualização mais recente do Visual Studio instalada.
\nTente reinstalar o Node.js 32bit.
\nCreating that directory should fix the problem:
\n$ mkdir ~\\AppData\\Roaming\\npm\nVocê pode obter este erro se você estiver usando Git Bash para construção, você deve usar o PowerShell ou VS2015 Command Prompt.
\nnode.js has some extremely long pathnames, and by default git on windows doesn't handle long pathnames correctly (even though windows supports them). This should fix it:
\n$ git config --system core.longpaths true\nThis can happen during build, when Debugging Tools for Windows has been installed with Windows Driver Kit. Uninstall Windows Driver Kit and install Debugging Tools with steps described above.
\nMake sure you have installed pywin32 with pip install pywin32.
This bug is a \"feature\" of Windows' command prompt. It happens when clicking inside the prompt window with QuickEdit enabled and is intended to allow selecting and copying output text easily. Since each accidental click will pause the build process, you might want to disable this feature in the command prompt properties.
Electron uses GN for project generation and ninja for building. Configurações do projeto podem ser encontradas em arquivos .gn e .gni.
The following gn files contain the main rules for building Electron:
BUILD.gn defines how Electron itself is built and includes the default configurations for linking with Chromium.build/args/{debug,release,all}.gn contain the default build arguments for building Electron.Since Chromium is quite a large project, the final linking stage can take quite a few minutes, which makes it hard for development. In order to solve this, Chromium introduced the \"component build\", which builds each component as a separate shared library, making linking very quick but sacrificing file size and performance.
\nElectron inherits this build option from Chromium. In Debug builds, the binary will be linked to a shared library version of Chromium's components to achieve fast linking time; for Release builds, the binary will be linked to the static library versions, so we can have the best possible binary size and performance.
NB this section is out of date and contains information that is no longer relevant to the GN-built electron.
\nTeste suas modificações de acordo com o projeto, usando o estilo de codificação:
\n$ npm run lint\nTeste a funcionalidade usando:
\n$ npm test\nSempre que fizer alterações no seu código Electron, terá de reconstruir antes de rodar os testes:
\n$ npm run build && npm test\nYou can make the test suite run faster by isolating the specific test or block you're currently working on using Mocha's exclusive tests feature. Append .only to any describe or it function call:
describe.only('some feature', () => {\n // ... only tests in this block will be run\n})\nAlternatively, you can use mocha's grep option to only run tests matching the given regular expression pattern:
$ npm test -- --grep child_process\nTests that include native modules (e.g. runas) can't be executed with the debug build (see #2558 for details), but they will work with the release build.
To run the tests with the release build use:
\n$ npm test -- -R\ndata String - PEM encoded dataissuer CertificatePrincipal - Issuer principalissuerName String - Issuer's Common NameissuerCert Certificate - Issuer certificate (if not self-signed)subject CertificatePrincipal - Subject principalsubjectName String - Subject's Common NameserialNumber String - Hex value represented stringvalidStart Number - Start date of the certificate being valid in secondsvalidExpiry Number - End date of the certificate being valid in secondsfingerprint String - Fingerprint of the certificatecommonName String - Common Name.organizations String[] - Organization names.organizationUnits String[] - Organization Unit names.locality String - Locality.state String - State or province.country String - Country or region.\n\nUma coleção de recursos para a aprendizagem sobre o Chromium e controle de seu desenvolvimento
\n
Veja também V8 Development
", "title": "Desenvolvimento do Chromium", "description": "Uma coleção de recursos para a aprendizagem sobre o Chromium e controle de seu desenvolvimento" }, "/docs/development/clang-format": { "locale": "pt-BR", "slug": "clang-format", "href": "/docs/development/clang-format", "crowdinFileId": "256143", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/clang-format.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "clang-format é uma ferramenta para aplica estilo de codificação em C/C++/Objective-C para que os desenvolvedores não precisem se preocuparem com questões desse tipo, durante as revisões de código.
É altamente recomendável para formatar o seu código alterado em C++, antes de abir uma solicitação de pull requests, que irão salvar você e o tempo de revisores.
\nVocê pode instalar o clang-format e git-clang-format através do npm install -g clang-format.
To automatically format a file according to Electron C++ code style, run clang-format -i path/to/electron/file.cc. It should work on macOS/Linux/Windows.
O fluxo de trabalho para formatar o seu código alterado:
\ngit add your_changed_file.cc.git-clang-format, e você vai provavelmente ver uma notificação em your_changed_file.cc, essas modificações são geradas do clang-format.git add your_changed_file.cc, e confirme a sua alteração.If you want to format the changed code on your latest git commit (HEAD), you can run git-clang-format HEAD~1. See git-clang-format -h for more details.
You can also integrate clang-format directly into your favorite editors. For further guidance on setting up editor integration, see these pages:
clang-tidy is a tool to automatically check C/C++/Objective-C code for style violations, programming errors, and best practices.
Electron's clang-tidy integration is provided as a linter script which can be run with npm run lint:clang-tidy. While clang-tidy checks your on-disk files, you need to have built Electron so that it knows which compiler flags were used. There is one required option for the script --output-dir, which tells the script which build directory to pull the compilation information from. A typical usage would be: npm run lint:clang-tidy --out-dir ../out/Testing
With no filenames provided, all C/C++/Objective-C files will be checked. You can provide a list of files to be checked by passing the filenames after the options: npm run lint:clang-tidy --out-dir ../out/Testing shell/browser/api/electron_api_app.cc
While clang-tidy has a long list of possible checks, in Electron only a few are enabled by default. At the moment Electron doesn't have a .clang-tidy config, so clang-tidy will find the one from Chromium at src/.clang-tidy and use the checks which Chromium has enabled. You can change which checks are run by using the --checks= option. This is passed straight through to clang-tidy, so see its documentation for full details. Wildcards can be used, and checks can be disabled by prefixing a -. By default any checks listed are added to those in .clang-tidy, so if you'd like to limit the checks to specific ones you should first exclude all checks then add back what you want, like --checks=-*,performance*.
Running clang-tidy is rather slow - internally it compiles each file and then runs the checks so it will always be some factor slower than compilation. While you can use parallel runs to speed it up using the --jobs|-j option, clang-tidy also uses a lot of memory during its checks, so it can easily run into out-of-memory errors. As such the default number of jobs is one.
\n\nRealiza requisições HTTP/HTTPS.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
ClientRequest implementa a interface Writable Stream e deste modo um EventEmitter.
new ClientRequest(opções)options (Object | String) - If options is a String, it is interpreted as the request URL. If it is an object, it is expected to fully specify an HTTP request via the following properties:method String (optional) - The HTTP request method. Defaults to the GET method.url String (optional) - The request URL. Must be provided in the absolute form with the protocol scheme specified as http or https.session Session (optional) - The Session instance with which the request is associated.partition String (opcional) - O nome da partição com a qual a requisição está associada. O padrão é uma string vazia. The session option supersedes partition. Assim, se a sessão é explicitamente especificada, a partição é ignorada.credentials String (optional) - Can be include or omit. Whether to send credentials with this request. If set to include, credentials from the session associated with the request will be used. If set to omit, credentials will not be sent with the request (and the 'login' event will not be triggered in the event of a 401). This matches the behavior of the fetch option of the same name. If this option is not specified, authentication data from the session will be sent, and cookies will not be sent (unless useSessionCookies is set).useSessionCookies Boolean (optional) - Whether to send cookies with this request from the provided session. If credentials is specified, this option has no effect. Por padrão é false.protocol String (optional) - Can be http: or https:. The protocol scheme in the form 'scheme:'. Defaults to 'http:'.host String (opcional) - O servidor, definido como a concatenação do nome com a porta: 'nome:porta'.hostname String (opcional) - O nome do servidor.port Integer (opcional) - O número da porta do servidor.path String (opcional) - A parte do caminho da URL de requisição.redirect String (optional) - Can be follow, error or manual. The redirect mode for this request. When mode is error, any redirection will be aborted. When mode is manual the redirection will be cancelled unless request.followRedirect is invoked synchronously during the redirect event. O padrão é follow.origin String (optional) - The origin URL of the request.As propriedades em options, como protocol, host, hostname, port e path seguem estritamente o modelo Node.js, como descrito no módulo URL.
Por exemplo, nós poderíamos criar a mesma requisição para 'github.com' da seguinte forma:
\nconst request = net.request({\n method: 'GET',\n protocol: 'https:',\n hostname: 'github.com',\n port: 443,\n path: '/'\n})\nRetorna:
\nresponse IncomingMessage - An object representing the HTTP response message.Retorna:
\nauthInfoisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (opcional)password String (opcional)Emitido quando um proxy de autenticação está solicitando as credenciais de usuário.
\nA função de callback é esperada para chamar de volta as credenciais do usuário:
username Stringpassword Stringrequest.on('login', (authInfo, callback) => {\n callback('username', 'password')\n})\nInformar credenciais vazias irá cancelar a requisição e reportar um erro de autenticação no objeto de resposta:
\nrequest.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`);\n response.on('error', (error) => {\n console.log(`ERROR: ${JSON.stringify(error)}`)\n })\n})\nrequest.on('login', (authInfo, callback) => {\n callback()\n})\nEmitido logo após o último pedaço dos dados de request for escrito no objeto request.
Emitted when the request is aborted. The abort event will not be fired if the request is already closed.
Retorna:
\nerror Error - um objeto de erro que provê informações sobre a falha.Emitido quando o módulo net falha ao emitir uma requisição de rede. Normalmente quando o objeto request emite um evento error, um evento close virá a seguir e nenhum objeto de resposta será fornecido.
Emitido como último evento na transação HTTP de requisição-resposta. O evento close indica que nenhum outro evento será emitido no objeto request e nem no objeto response.
Retorna:
\nstatusCode Integermethod StringredirectUrl StringresponseHeaders Record<String, String[]>Emitted when the server returns a redirect response (e.g. 301 Moved Permanently). Calling request.followRedirect will continue with the redirection. If this event is handled, request.followRedirect must be called synchronously, otherwise the request will be cancelled.
request.chunkedEncodingA Boolean specifying whether the request will use HTTP chunked transfer encoding or not. Defaults to false. The property is readable and writable, however it can be set only before the first write operation as the HTTP headers are not yet put on the wire. Trying to set the chunkedEncoding property after the first write will throw an error.
Using chunked encoding is strongly recommended if you need to send a large request body as data will be streamed in small chunks instead of being internally buffered inside Electron process memory.
\nrequest.setHeader(name, value)name String - An extra HTTP header name.value String - An extra HTTP header value.Adds an extra HTTP header. The header name will be issued as-is without lowercasing. It can be called only before first write. Calling this method after the first write will throw an error. If the passed value is not a String, its toString() method will be called to obtain the final value.
Certain headers are restricted from being set by apps. These headers are listed below. More information on restricted headers can be found in Chromium's header utils.
\nContent-LengthHostTrailer ou TeUpgradeCookie2Keep-AliveTransfer-EncodingAdditionally, setting the Connection header to the value upgrade is also disallowed.
request.getHeader(name)name String - Specify an extra header name.Returns String - The value of a previously set extra header name.
request.removeHeader(name)name String - Specify an extra header name.Removes a previously set extra header name. This method can be called only before first write. Trying to call it after the first write will throw an error.
\nrequest.write(chunk[, encoding][, callback])chunk (String | Buffer) - A chunk of the request body's data. If it is a string, it is converted into a Buffer using the specified encoding.encoding String (optional) - Used to convert string chunks into Buffer objects. Defaults to 'utf-8'.callback Function (optional) - Called after the write operation ends.callback is essentially a dummy function introduced in the purpose of keeping similarity with the Node.js API. It is called asynchronously in the next tick after chunk content have been delivered to the Chromium networking layer. Contrary to the Node.js implementation, it is not guaranteed that chunk content have been flushed on the wire before callback is called.
Adds a chunk of data to the request body. The first write operation may cause the request headers to be issued on the wire. After the first write operation, it is not allowed to add or remove a custom header.
\nrequest.end([chunk][, encoding][, callback])chunk (String | Buffer) (optional)encoding String (opcional)callback Function (optional)Sends the last chunk of the request data. Subsequent write or end operations will not be allowed. The finish event is emitted just after the end operation.
request.abort()Cancels an ongoing HTTP transaction. If the request has already emitted the close event, the abort operation will have no effect. Otherwise an ongoing event will emit abort and close events. Additionally, if there is an ongoing response object,it will emit the aborted event.
request.followRedirect()Continues any pending redirection. Can only be called during a 'redirect' event.
request.getUploadProgress()Retorna Object:
active Boolean - Whether the request is currently active. If this is false no other properties will be setstarted Boolean - Whether the upload has started. If this is false both current and total will be set to 0.current Integer - The number of bytes that have been uploaded so fartotal Integer - The number of bytes that will be uploaded this requestYou can use this method in conjunction with POST requests to get the progress of a file upload or other data transfer.
\n\n\nRealizar cópia e colar operações na área de transferência do sistema.
\n
On Linux, there is also a selection clipboard. To manipulate it you need to pass selection to each method:
const { clipboard } = require('electron')\n\nclipboard.writeText('Example String', 'selection')\nconsole.log(clipboard.readText('selection'))\nO módulo clipboard possui os seguintes métodos:
Nota: APIs experimentais são marcadas como tal e podem ser removidas no futuro.
\nclipboard.readText([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Retorna String - o conteúdo da área de transferência como texto sem formatação.
const { clipboard } = require('electron')\n\nclipboard.writeText('hello i am a bit of text!')\n\nconst text = clipboard.readText()\nconsole.log(text)\n// hello i am a bit of text!'\nclipboard.writeText(text[, type])text Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Escreve o text na área de transferência como texto sem formatação.
const { clipboard } = require('electron')\n\nconst text = 'hello i am a bit of text!'\nclipboard.writeText(text)\nclipboard.readHTML([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Retorna String - o conteúdo da área de transferência como marcação.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b>')\nconst html = clipboard.readHTML()\n\nconsole.log(html)\n// <meta charset='utf-8'><b>Hi</b>\nclipboard.writeHTML(markup[, type])markup Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Escreve markup na área de transferência.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b')\nclipboard.readImage([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Retorna Nativeimage - o conteúdo da imagem na área de transferência.
clipboard.writeImage(image[, type])image NativeImagetype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Escreve image na área de transferência.
clipboard.readRTF([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Retorna String - o conteúdo da área de transferência como RTF.
const { clipboard } = require('electron')\n\nclipboard.writeRTF('{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}')\n\nconst rtf = clipboard.readRTF()\nconsole.log(rtf)\n// {\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}\nclipboard.writeRTF(text[, type])text Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Escreve o text na área de transferência em RTF.
const { clipboard } = require('electron')\n\nconst rtf = '{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}'\nclipboard.writeRTF(rtf)\nclipboard.readBookmark() macOS WindowsRetorna Object:
title StringurlRetorna um Objeto que contém as chaves title e url representando o bookmark na área de transferência. Os valores de title e url serão strings vazias quando o bookmark estiver indisponível.
clipboard.writeBookmark(title, url[, type]) macOS Windowstitle Stringurltype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Escreve o title e o url na área de transferência como um bookmark.
Note: Most apps on Windows don't support pasting bookmarks into them so you can use clipboard.write to write both a bookmark and fallback text to the clipboard.
const { clipboard } = require('electron')\n\nclipboard.writeBookmark({\n text: 'https://electronjs.org',\n bookmark: 'Electron Homepage'\n})\nclipboard.readFindText() macOSReturns String - The text on the find pasteboard, which is the pasteboard that holds information about the current state of the active application’s find panel.
This method uses synchronous IPC when called from the renderer process. The cached value is reread from the find pasteboard whenever the application is activated.
\nclipboard.writeFindText(text) macOStext StringWrites the text into the find pasteboard (the pasteboard that holds information about the current state of the active application’s find panel) as plain text. This method uses synchronous IPC when called from the renderer process.
clipboard.clear([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Clears the clipboard content.
\nclipboard.availableFormats([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Returns String[] - An array of supported formats for the clipboard type.
const { clipboard } = require('electron')\n\nconst formats = clipboard.availableFormats()\nconsole.log(formats)\n// [ 'text/plain', 'text/html' ]\nclipboard.has(format[, type]) Experimentalformat Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Returns Boolean - Whether the clipboard supports the specified format.
const { clipboard } = require('electron')\n\nconst hasFormat = clipboard.has('<p>selection</p>')\nconsole.log(hasFormat)\n// 'true' or 'false'\nclipboard.read(format) Experimentalformat StringReturns String - Reads format type from the clipboard.
format should contain valid ASCII characters and have / separator. a/c, a/bc are valid formats while /abc, abc/, a/, /a, a are not valid.
clipboard.readBuffer(format) Experimentalformat StringReturns Buffer - Reads format type from the clipboard.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('this is binary', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\n\nconst ret = clipboard.readBuffer('public/utf8-plain-text')\n\nconsole.log(buffer.equals(out))\n// true\nclipboard.writeBuffer(format, buffer[, type]) Experimentalformat Stringbuffer Buffertype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Writes the buffer into the clipboard as format.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('writeBuffer', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\nclipboard.write(data[, type])data Objecttext String (opcional)html String (opcional)image NativeImage (opcional)rtf String (opcional)bookmark String (optional) - The title of the URL at text.type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.Escreve data na área de transferência.
const { clipboard } = require('electron')\n\nclipboard.write({\n text: 'test',\n html: '<b>Hi</b>',\n rtf: '{\\\\rtf1\\\\utf8 text}',\n bookmark: 'a title'\n})\n\nconsole.log(clipboard.readText())\n// 'test'\n\nconsole.log(clipboard.readHTML())\n// <meta charset='utf-8'><b>Hi</b>\n\nconsole.log(clipboard.readRTF())\n// '{\\\\rtf1\\\\utf8 text}'\n\nconsole.log(clipboard.readBookmark())\n// { title: 'a title', url: 'test' }\nCode signing is a security technology that you use to certify that an app was created by you.
\nOn macOS the system can detect any change to the app, whether the change is introduced accidentally or by malicious code.
\nOn Windows, the system assigns a trust level to your code signing certificate which if you don't have, or if your trust level is low, will cause security dialogs to appear when users start using your application. Trust level builds over time so it's better to start code signing as early as possible.
\nWhile it is possible to distribute unsigned apps, it is not recommended. Both Windows and macOS will, by default, prevent either the download or the execution of unsigned applications. Starting with macOS Catalina (version 10.15), users have to go through multiple manual steps to open unsigned applications.
\n
As you can see, users get two options: Move the app straight to the trash or cancel running it. You don't want your users to see that dialog.
\nIf you are building an Electron app that you intend to package and distribute, it should be code-signed.
\nProperly preparing macOS applications for release requires two steps: First, the app needs to be code-signed. Then, the app needs to be uploaded to Apple for a process called \"notarization\", where automated systems will further verify that your app isn't doing anything to endanger its users.
\nTo start the process, ensure that you fulfill the requirements for signing and notarizing your app:
\nElectron's ecosystem favors configuration and freedom, so there are multiple ways to get your application signed and notarized.
\nelectron-forgeIf you're using Electron's favorite build tool, getting your application signed and notarized requires a few additions to your configuration. Forge is a collection of the official Electron tools, using electron-packager, electron-osx-sign, and electron-notarize under the hood.
Let's take a look at an example configuration with all required fields. Not all of them are required: the tools will be clever enough to automatically find a suitable identity, for instance, but we recommend that you are explicit.
{\n \"name\": \"my-app\",\n \"version\": \"0.0.1\",\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"osxSign\": {\n \"identity\": \"Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)\",\n \"hardened-runtime\": true,\n \"entitlements\": \"entitlements.plist\",\n \"entitlements-inherit\": \"entitlements.plist\",\n \"signature-flags\": \"library\"\n },\n \"osxNotarize\": {\n \"appleId\": \"felix@felix.fun\",\n \"appleIdPassword\": \"my-apple-id-password\",\n }\n }\n }\n }\n}\nThe plist file referenced here needs the following macOS-specific entitlements to assure the Apple security mechanisms that your app is doing these things without meaning any harm:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nNote that up until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required as well. However, it should not be used anymore if it can be avoided.
To see all of this in action, check out Electron Fiddle's source code, especially its electron-forge configuration file.
If you plan to access the microphone or camera within your app using Electron's APIs, you'll also need to add the following entitlements:
\n<key>com.apple.security.device.audio-input</key>\n<true/>\n<key>com.apple.security.device.camera</key>\n<true/>\nIf these are not present in your app's entitlements when you invoke, for example:
\nconst { systemPreferences } = require('electron')\n\nconst microphone = systemPreferences.askForMediaAccess('microphone')\nYour app may crash. See the Resource Access section in Hardened Runtime for more information and entitlements you may need.
\nelectron-builderElectron Builder comes with a custom solution for signing your application. You can find its documentation here.
\nelectron-packagerIf you're not using an integrated build pipeline like Forge or Builder, you are likely using electron-packager, which includes electron-osx-sign and electron-notarize.
If you're using Packager's API, you can pass in configuration that both signs and notarizes your application.
\nconst packager = require('electron-packager')\n\npackager({\n dir: '/path/to/my/app',\n osxSign: {\n identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',\n 'hardened-runtime': true,\n entitlements: 'entitlements.plist',\n 'entitlements-inherit': 'entitlements.plist',\n 'signature-flags': 'library'\n },\n osxNotarize: {\n appleId: 'felix@felix.fun',\n appleIdPassword: 'my-apple-id-password'\n }\n})\nThe plist file referenced here needs the following macOS-specific entitlements to assure the Apple security mechanisms that your app is doing these things without meaning any harm:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nUp until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required as well. However, it should not be used anymore if it can be avoided.
See the Mac App Store Guide.
\nBefore signing Windows builds, you must do the following:
\nVocê pode obter um certificado de assinatura de um grande número de revendedores. Prices vary, so it may be worth your time to shop around. Revendedores populares incluem:
\nThere are a number of tools for signing your packaged app:
\nelectron-winstaller will generate an installer for windows and sign it for youelectron-forge can sign installers it generates through the Squirrel.Windows or MSI targets.electron-builder can sign some of its windows targetsSee the Windows Store Guide.
", "title": "Assinando Código", "description": "" }, "/docs/development/coding-style": { "locale": "pt-BR", "slug": "coding-style", "href": "/docs/development/coding-style", "crowdinFileId": "256147", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/coding-style.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Essas são as diretrizes para programar no Electron.
\nVocê pode executar npm run lint para visualizar qualquer problemas de estilos detectados com cpplint e eslint.
path)ipc, app)@)path.join() para concatenar nome de arquivos.os.tmpdir() ao invés de /tmp quando você precisar fazer referência ao diretório temporário.return when returning explicitly at the end of a function.return null, return undefined, null or undefinedFor C++ and Python, we follow Chromium's Coding Style. You can use clang-format to format the C++ code automatically. There is also a script script/cpplint.py to check whether all files conform.
The Python version we are using now is Python 2.7.
\nThe C++ code uses a lot of Chromium's abstractions and types, so it's recommended to get acquainted with them. A good place to start is Chromium's Important Abstractions and Data Structures document. The document mentions some special types, scoped types (that automatically release their memory when going out of scope), logging mechanisms etc.
\nYou can run npm run lint-docs to ensure that your documentation changes are formatted correctly.
- instead of _, e.g. file-name.js rather than file_name.js, because in github/atom module names are usually in the module-name form. This rule only applies to .js files.const for requires and other constants. If the value is a primitive, use uppercase naming (eg const NUMBER_OF_RETRIES = 5).let for defining variablesfunction () { }+As APIs do Electron usam o mesmo esquema de capitalização do Node.js:
\nBrowserWindow, use PascalCase.globalShortcut, use camelCase.win.webContents, use mixedCase.<webview> Tag ou Process Object.Ao criar uma nova API, é preferível usar getters e setters em vez de estilo de uma função do jQuery. For example, .getText() and .setText(text) are preferred to .text([text]). There is a discussion on this.
\n\nManipulate the command line arguments for your app that Chromium reads
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The following example shows how to check if the --disable-gpu flag is set.
const { app } = require('electron')\napp.commandLine.hasSwitch('disable-gpu')\nFor more information on what kinds of flags and switches you can use, check out the Command Line Switches document.
\ncommandLine.appendSwitch(switch[, value])switch String - A command-line switch, without the leading --value String - (opcional) - Um valor para a opção desejadaInsere uma opção (com um value opcional) à linha de comando do Chromium.
Note: This will not affect process.argv. The intended usage of this function is to control Chromium's behavior.
commandLine.appendArgument(value)value String - The argument to append to the command lineAppend an argument to Chromium's command line. The argument will be quoted correctly. Switches will precede arguments regardless of appending order.
\nIf you're appending an argument like --switch=value, consider using appendSwitch('switch', 'value') instead.
Note: This will not affect process.argv. The intended usage of this function is to control Chromium's behavior.
commandLine.hasSwitch(switch)switch String - Uma opção de linha de comandoReturns Boolean - Whether the command-line switch is present.
commandLine.getSwitchValue(switch)switch String - Uma opção de linha de comandoReturns String - The command-line switch value.
Note: When the switch is not present or has no value, it returns empty string.
", "title": "Classe: Linha de Comando", "description": "Manipulate the command line arguments for your app that Chromium reads" }, "/docs/api/command-line-switches": { "locale": "pt-BR", "slug": "command-line-switches", "href": "/docs/api/command-line-switches", "crowdinFileId": "256293", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/command-line-switches.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nOpções de linha de comando suportados pelo Electron.
\n
You can use app.commandLine.appendSwitch to append them in your app's main script before the ready event of the app module is emitted:
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('remote-debugging-port', '8315')\napp.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')\n\napp.whenReady().then(() => {\n // Your code here\n})\nurlA comma-separated list of servers for which integrated authentication is enabled.
\nComo por exemplo:
\n--auth-server-whitelist='*example.com, *foobar.com, *baz'\nthen any url ending with example.com, foobar.com, baz will be considered for integrated authentication. Without * prefix the URL has to match exactly.
urlA comma-separated list of servers for which delegation of user credentials is required. Without * prefix the URL has to match exactly.
Disables NTLM v2 for posix platforms, no effect elsewhere.
\nDesabilita o cache de disco para as requisições HTTP.
\nDisable HTTP/2 and SPDY/3.1 protocols.
\nPrevents Chromium from lowering the priority of invisible pages' renderer processes.
\nThis flag is global to all renderer processes, if you only want to disable throttling in one window, you can take the hack of playing silent audio.
\nsizeForça o máximo de espaço em disco a ser usado pelo cache de disco, em bytes.
\nEnables caller stack logging for the following APIs (filtering events):
\ndesktopCapturer.getSources() / desktop-capturer-get-sourcesPrints Chromium's logging to stderr (or a log file).
\nThe ELECTRON_ENABLE_LOGGING environment variable has the same effect as passing --enable-logging.
Passing --enable-logging will result in logs being printed on stderr. Passing --enable-logging=file will result in logs being saved to the file specified by --log-file=..., or to electron_debug.log in the user-data directory if --log-file is not specified.
\n\nNote: On Windows, logs from child processes cannot be sent to stderr. Logging to a file is the most reliable way to collect logs on Windows.
\n
See also --log-file, --log-level, --v, and --vmodule.
trialsField trials to be forcefully enabled or disabled.
\nPor exemplo: WebRTC-Audio-Red-For-Opus/Enabled/
rulesA comma-separated list of rules that control how hostnames are mapped.
Como por exemplo:
\nMAP * 127.0.0.1 Forces all hostnames to be mapped to 127.0.0.1MAP *.google.com proxy Forces all google.com subdomains to be resolved to \"proxy\".MAP test.com [::1]:77 Forces \"test.com\" to resolve to IPv6 loopback. Will also force the port of the resulting socket address to be 77.MAP * baz, EXCLUDE www.google.com Remaps everything to \"baz\", except for \"www.google.com\".These mappings apply to the endpoint host in a net request (the TCP connect and host resolver in a direct connection, and the CONNECT in an HTTP proxy connection, and the endpoint host in a SOCKS proxy connection).
rulesLike --host-rules but these rules only apply to the host resolver.
Ignores certificate related errors.
\ndomainsIgnora o limite de conexão por domains lista separada por ,.
flagsSpecifies the flags passed to the Node.js engine. It has to be passed when starting Electron if you want to enable the flags in the main process.
$ electron --js-flags=\"--harmony_proxies --harmony_collections\" seu-app\nSee the Node.js documentation or run node --help in your terminal for a list of available flags. Additionally, run node --v8-options to see a list of flags that specifically refer to Node.js's V8 JavaScript engine.
Definir uma localidade customizada.
\npathIf --enable-logging is specified, logs will be written to the given path. The parent directory must exist.
Setting the ELECTRON_LOG_FILE environment variable is equivalent to passing this flag. If both are present, the command-line switch takes precedence.
pathEnables net log events to be saved and writes them to path.
NSets the verbosity of logging when used together with --enable-logging. N should be one of Chrome's LogSeverities.
Note that two complimentary logging mechanisms in Chromium -- LOG() and VLOG() -- are controlled by different switches. --log-level controls LOG() messages, while --v and --vmodule control VLOG() messages. So you may want to use a combination of these three switches depending on the granularity you want and what logging calls are made by the code you're trying to watch.
See Chromium Logging source for more information on how LOG() and VLOG() interact. Loosely speaking, VLOG() can be thought of as sub-levels / per-module levels inside LOG(INFO) to control the firehose of LOG(INFO) data.
See also --enable-logging, --log-level, --v, and --vmodule.
Don't use a proxy server and always make direct connections. Overrides any other proxy server flags that are passed.
\nDisables the Chromium sandbox. Forces renderer process and Chromium helper processes to run un-sandboxed. Should only be used for testing.
\nhostsInstructs Electron to bypass the proxy server for the given semi-colon-separated list of hosts. This flag has an effect only if used in tandem with --proxy-server.
Como por exemplo:
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')\nWill use the proxy server for all hosts except for local addresses (localhost, 127.0.0.1 etc.), google.com subdomains, hosts that contain the suffix foo.com and anything at 1.2.3.4:5678.
urlUses the PAC script at the specified url.
address:portUse a specified proxy server, which overrides the system setting. This switch only affects requests with HTTP protocol, including HTTPS and WebSocket requests. It is also noteworthy that not all proxy servers support HTTPS and WebSocket requests. The proxy URL does not support username and password authentication per Chromium issue.
\nportHabilita depuração remota sobre o HTTP na port especificada.
log_levelGives the default maximal active V-logging level; 0 is the default. Normally positive values are used for V-logging levels.
\nThis switch only works when --enable-logging is also passed.
See also --enable-logging, --log-level, and --vmodule.
patternGives the per-module maximal V-logging levels to override the value given by --v. Ex. my_module=2,foo*=3 would change the logging level for all code in source files my_module.* and foo*.*.
Any pattern containing a forward or backward slash will be tested against the whole pathname and not only the module. Ex. */foo/bar/*=2 would change the logging level for all code in the source files under a foo/bar directory.
This switch only works when --enable-logging is also passed.
See also --enable-logging, --log-level, and --v.
Force using discrete GPU when there are multiple GPUs available.
\nForce using integrated GPU when there are multiple GPUs available.
\nElectron supports some of the CLI flags supported by Node.js.
\nNote: Passing unsupported command line switches to Electron when it is not running in ELECTRON_RUN_AS_NODE will have no effect.
Activate inspector on host:port and break at start of user script. Default host:port is 127.0.0.1:9229.
\nAliased to --debug-brk=[host:]port.
Set the host:port to be used when the inspector is activated. Useful when activating the inspector by sending the SIGUSR1 signal. Default host is 127.0.0.1.
Aliased to --debug-port=[host:]port.
Activate inspector on host:port. Por padrão é 127.0.0.1:9229.
V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug and profile Electron instances. The tools attach to Electron instances via a TCP port and communicate using the Chrome DevTools Protocol.
\nSee the Debugging the Main Process guide for more details.
\nAliased to --debug[=[host:]port.
Specify ways of the inspector web socket url exposure.
\nBy default inspector websocket url is available in stderr and under /json/list endpoint on http://host:port/json/list.
", "title": "Switches de Linha de Comando Suportadas", "description": "Opções de linha de comando suportados pelo Electron." }, "/docs/api/content-tracing": { "locale": "pt-BR", "slug": "content-tracing", "href": "/docs/api/content-tracing", "crowdinFileId": "256297", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/content-tracing.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCollect tracing data from Chromium to find performance bottlenecks and slow operations.
\n
Processo: Main
\nThis module does not include a web interface. To view recorded traces, use trace viewer, available at chrome://tracing in Chrome.
Nota: Voce nao deve usar este modulo ate que o 'ready event' do modulo da aplicacao esteja finalizado e emitido.
const { app, contentTracing } = require('electron')\n\napp.whenReady().then(() => {\n (async () => {\n await contentTracing.startRecording({\n included_categories: ['*']\n })\n console.log('Tracing started')\n await new Promise(resolve => setTimeout(resolve, 5000))\n const path = await contentTracing.stopRecording()\n console.log('Tracing data recorded to ' + path)\n })()\n})\nO módulo contentTracing tem os seguintes métodos:
contentTracing.getCategories()Returns Promise<String[]> - resolves with an array of category groups once all child processes have acknowledged the getCategories request
Get a set of category groups. The category groups can change as new code paths are reached. See also the list of built-in tracing categories.
\n\n\nNOTE: Electron adds a non-default tracing category called
\n\"electron\". This category can be used to capture Electron-specific tracing events.
contentTracing.startRecording(options)options (TraceConfig | TraceCategoriesAndOptions)Returns Promise<void> - resolved once all child processes have acknowledged the startRecording request.
Start recording on all processes.
\nRecording begins immediately locally and asynchronously on child processes as soon as they receive the EnableRecording request.
\nIf a recording is already running, the promise will be immediately resolved, as only one trace operation can be in progress at a time.
\ncontentTracing.stopRecording([resultFilePath])resultFilePath String (opcional)Returns Promise<String> - resolves with a path to a file that contains the traced data once all child processes have acknowledged the stopRecording request
Stop recording on all processes.
\nChild processes typically cache trace data and only rarely flush and send trace data back to the main process. This helps to minimize the runtime overhead of tracing since sending trace data over IPC can be an expensive operation. So, to end tracing, Chromium asynchronously asks all child processes to flush any pending trace data.
\nTrace data will be written into resultFilePath. If resultFilePath is empty or not provided, trace data will be written to a temporary file, and the path will be returned in the promise.
contentTracing.getTraceBufferUsage()Returns Promise<Object> - Resolves with an object containing the value and percentage of trace buffer maximum usage
value Numberpercentage NumberGet the maximum usage across processes of trace buffer as a percentage of the full state.
", "title": "contentTracing", "description": "Collect tracing data from Chromium to find performance bottlenecks and slow operations." }, "/docs/api/context-bridge": { "locale": "pt-BR", "slug": "context-bridge", "href": "/docs/api/context-bridge", "crowdinFileId": "256299", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/context-bridge.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCreate a safe, bi-directional, synchronous bridge across isolated contexts
\n
Processo: Renderizador
\nAn example of exposing an API to a renderer from an isolated preload script is given below:
\n// Preload (Isolated World)\nconst { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing')\n }\n)\n// Renderer (Main World)\n\nwindow.electron.doThing()\nThe \"Main World\" is the JavaScript context that your main renderer code runs in. By default, the page you load in your renderer executes code in this world.
\nWhen contextIsolation is enabled in your webPreferences (this is the default behavior since Electron 12.0.0), your preload scripts run in an \"Isolated World\". You can read more about context isolation and what it affects in the security docs.
O módulo contextBridge possui os seguintes métodos:
contextBridge.exposeInMainWorld(apiKey, api)apiKey String - The key to inject the API onto window with. The API will be accessible on window[apiKey].api any - Your API, more information on what this API can be and how it works is available below.The api provided to exposeInMainWorld must be a Function, String, Number, Array, Boolean, or an object whose keys are strings and values are a Function, String, Number, Array, Boolean, or another nested object that meets the same conditions.
Function values are proxied to the other context and all other values are copied and frozen. Any data / primitives sent in the API become immutable and updates on either side of the bridge do not result in an update on the other side.
An example of a complex API is shown below:
\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing'),\n myPromises: [Promise.resolve(), Promise.reject(new Error('whoops'))],\n anAsyncFunction: async () => 123,\n data: {\n myFlags: ['a', 'b', 'c'],\n bootTime: 1234\n },\n nestedAPI: {\n evenDeeper: {\n youCanDoThisAsMuchAsYouWant: {\n fn: () => ({\n returnData: 123\n })\n }\n }\n }\n }\n)\nFunction values that you bind through the contextBridge are proxied through Electron to ensure that contexts remain isolated. This results in some key limitations that we've outlined below.
Because parameters, errors and return values are copied when they are sent over the bridge, there are only certain types that can be used. At a high level, if the type you want to use can be serialized and deserialized into the same object it will work. A table of type support has been included below for completeness:
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Tipo | Complexity | Parameter Support | Return Value Support | Limitações |
|---|---|---|---|---|
String | Simple | ✅ | ✅ | N/A |
Número | Simple | ✅ | ✅ | N/A |
Booleano | Simple | ✅ | ✅ | N/A |
Object | Complex | ✅ | ✅ | Keys must be supported using only \"Simple\" types in this table. Values must be supported in this table. Prototype modifications are dropped. Sending custom classes will copy values but not the prototype. |
Array | Complex | ✅ | ✅ | Same limitations as the Object type |
Erro | Complex | ✅ | ✅ | Errors that are thrown are also copied, this can result in the message and stack trace of the error changing slightly due to being thrown in a different context |
Promise | Complex | ✅ | ✅ | Promises are only proxied if they are the return value or exact parameter. Promises nested in arrays or objects will be dropped. |
Function | Complex | ✅ | ✅ | Prototype modifications are dropped. Sending classes or constructors will not work. |
| Cloneable Types | Simple | ✅ | ✅ | See the linked document on cloneable types |
Element | Complex | ✅ | ✅ | Prototype modifications are dropped. Sending custom elements will not work. |
Blob | Complex | ✅ | ✅ | N/A |
Symbol | N/A | ❌ | ❌ | Symbols cannot be copied across contexts so they are dropped |
If the type you care about is not in the above table, it is probably not supported.
\nThe contextBridge can be used by the preload script to give your renderer access to Node APIs. The table of supported types described above also applies to Node APIs that you expose through contextBridge. Please note that many Node APIs grant access to local system resources. Be very cautious about which globals and APIs you expose to untrusted remote content.
const { contextBridge } = require('electron')\nconst crypto = require('crypto')\ncontextBridge.exposeInMainWorld('nodeCrypto', {\n sha256sum (data) {\n const hash = crypto.createHash('sha256')\n hash.update(data)\n return hash.digest('hex')\n }\n})\nIsolamento de Contexto é um recurso que garante que tanto os seus scripts do preload quanto a lógica interna do Electron sejam executados em um contexto separado para a pagina que você carregar em um webContent. Isso é importante por questões de segurança, pois ajuda a impedir que a pagina web acesse os módulos internos do Electron ou aos privelégios de APIs que seu script de preload tem acesso.
Isto significa que o objeto window ao qual seu script de preload tem acesso seja realmente um objeto diferente do qual a sua pagina web teria acesso. For example, if you set window.hello = 'wave' in your preload script and context isolation is enabled, window.hello will be undefined if the website tries to access it.
Context isolation has been enabled by default since Electron 12, and it is a recommended security setting for all applications.
\n\n\nWithout context isolation, I used to provide APIs from my preload script using
\nwindow.X = apiObject. Now what?
Exposing APIs from your preload script to a loaded website in the renderer process is a common use-case. With context isolation disabled, your preload script would share a common global window object with the renderer. You could then attach arbitrary properties to a preload script:
// preload with contextIsolation disabled\nwindow.myAPI = {\n doAThing: () => {}\n}\nThe doAThing() function could then be used directly in the renderer process:
// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nThere is a dedicated module in Electron to help you do this in a painless way. The contextBridge module can be used to safely expose APIs from your preload script's isolated context to the context the website is running in. The API will also be accessible from the website on window.myAPI just like it was before.
// preload with contextIsolation enabled\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n doAThing: () => {}\n})\n// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nPlease read the contextBridge documentation linked above to fully understand its limitations. For instance, you can't send custom prototypes or symbols over the bridge.
Just enabling contextIsolation and using contextBridge does not automatically mean that everything you do is safe. For instance, this code is unsafe.
// ❌ Bad code\ncontextBridge.exposeInMainWorld('myAPI', {\n send: ipcRenderer.send\n})\nIt directly exposes a powerful API without any kind of argument filtering. This would allow any website to send arbitrary IPC messages, which you do not want to be possible. The correct way to expose IPC-based APIs would instead be to provide one method per IPC message.
\n// ✅ Good code\ncontextBridge.exposeInMainWorld('myAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nIf you're building your Electron app with TypeScript, you'll want to add types to your APIs exposed over the context bridge. The renderer's window object won't have the correct typings unless you extend the types with a declaration file.
For example, given this preload.ts script:
contextBridge.exposeInMainWorld('electronAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nYou can create a renderer.d.ts declaration file and globally augment the Window interface:
export interface IElectronAPI {\n loadPreferences: () => Promise<void>,\n}\n\ndeclare global {\n interface Window {\n electronAPI: IElectronAPI\n }\n}\nDoing so will ensure that the TypeScript compiler will know about the electronAPI property on your global window object when writing scripts in your renderer process:
window.electronAPI.loadPreferences()\nname String - The name of the cookie.value String - The value of the cookie.domain String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains.hostOnly Boolean (optional) - Whether the cookie is a host-only cookie; this will only be true if no domain was passed.path String (optional) - The path of the cookie.secure Boolean (optional) - Whether the cookie is marked as secure.httpOnly Boolean (optional) - Whether the cookie is marked as HTTP only.session Boolean (optional) - Whether the cookie is a session cookie or a persistent cookie with an expiration date.expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.sameSite String - The Same Site policy applied to this cookie. Can be unspecified, no_restriction, lax or strict.\n\nQuery and modify a session's cookies.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Instâncias da classe Cookies são acessadas através da propriedade cookies de uma Sessão.
Como por exemplo:
\nconst { session } = require('electron')\n\n// Query all cookies.\nsession.defaultSession.cookies.get({})\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// Query all cookies associated with a specific url.\nsession.defaultSession.cookies.get({ url: 'http://www.github.com' })\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// Set a cookie with the given cookie data;\n// may overwrite equivalent cookies if they exist.\nconst cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }\nsession.defaultSession.cookies.set(cookie)\n .then(() => {\n // success\n }, (error) => {\n console.error(error)\n })\nOs seguintes eventos estão disponíveis em instâncias de Cookies:
Retorna:
\nevent Eventcookie Cookie - O cookie que foi modificado.cause String - The cause of the change with one of the following values:explicit - O cookie foi modificado diretamente por uma ação do consumidor.overwrite - O cookie foi removido automaticamente devido à uma ação de inserção que o sobrescreveu.expired - O cookie foi automaticamente removido conforme expirou.evicted - The cookie was automatically evicted during garbage collection.expired-overwrite - The cookie was overwritten with an already-expired expiration date.removed Boolean - true se o cookie foi removido, false caso contrário.Emitido quando um cookie é modificado devido à adição, edição, remoção ou expiração.
\nOs metódos a seguir estão disponíveis em instâncias de Cookies:
cookies.get(filter)filter Objecturl String (optional) - Retrieves cookies which are associated with url. Empty implies retrieving cookies of all URLs.name String (opcional) - Filtra cookies por nome.domain String (opcional) - Recupera cookies nos quais os domínios sejam iguais ou subdomínios de domain.path String (opcional) - Recupera cookies nos quais o caminho seja igual a path.secure Boolean (opcional) - Filtra cookies pela propriedade Secure.session Boolean (optional) - Filters out session or persistent cookies.Returns Promise<Cookie[]> - A promise which resolves an array of cookie objects.
Sends a request to get all cookies matching filter, and resolves a promise with the response.
cookies.set(details)detailsurl String - The URL to associate the cookie with. The promise will be rejected if the URL is invalid.name String (optional) - The name of the cookie. Empty by default if omitted.value String (optional) - The value of the cookie. Empty by default if omitted.domain String (opcional) - O domínio do cookie; isto será normalizado com um ponto no início para que ele também seja válido para subdomínios. Empty by default if omitted.path String (opcional) - O Diretório do cookie. Empty by default if omitted.secure Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to false unless Same Site=None attribute is used.httpOnly Boolean (optional) - Whether the cookie should be marked as HTTP only. Defaults to false.expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted then the cookie becomes a session cookie and will not be retained between sessions.sameSite String (optional) - The Same Site policy to apply to this cookie. Pode ser unspecified, no_restriction, lax ou strict. Por padrão é no_restriction.Returns Promise<void> - A promise which resolves when the cookie has been set
Sets a cookie with details.
cookies.remove(url, name)url String - A URL associada com o cookie.name String - O nome do cookie a ser removido.Returns Promise<void> - A promise which resolves when the cookie has been removed
Removes the cookies matching url and name
cookies.flushStore()Returns Promise<void> - A promise which resolves when the cookie store has been flushed
Escreve qualquer cookie que não tenha sido escrito no disco.
", "title": "Cookies", "description": "Query and modify a session's cookies." }, "/docs/api/structures/cpu-usage": { "locale": "pt-BR", "slug": "cpu-usage", "href": "/docs/api/structures/cpu-usage", "crowdinFileId": "256419", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/cpu-usage.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "percentCPUUsage Number - Percentage of CPU used since the last call to getCPUUsage. First call returns 0.idleWakeupsPerSecond Number - The number of average idle CPU wakeups per second since the last call to getCPUUsage. First call returns 0. Will always return 0 on Windows.date Dateid String\n\n\nSubmit crash reports to a remote server.
\n
The following is an example of setting up Electron to automatically submit crash reports to a remote server:
\nconst { crashReporter } = require('electron')\n\ncrashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })\nFor setting up a server to accept and process crash reports, you can use following projects:
\n\nOr use a 3rd party hosted solution:
\n\nCrash reports are stored temporarily before being uploaded in a directory underneath the app's user data directory (called 'Crashpad' on Windows and Mac, or 'Crash Reports' on Linux). You can override this directory by calling app.setPath('crashDumps', '/path/to/crashes') before starting the crash reporter.
On Windows and macOS, Electron uses crashpad to monitor and report crashes. On Linux, Electron uses breakpad. This is an implementation detail driven by Chromium, and it may change in future. In particular, crashpad is newer and will likely eventually replace breakpad on all platforms.
\nIf you are using the Node.js child_process module and want to report crashes from those processes on Linux, there is an extra step you will need to take to properly initialize the crash reporter in the child process. This is not necessary on Mac or Windows, as those platforms use Crashpad, which automatically monitors child processes.
Since require('electron') is not available in Node child processes, the following APIs are available on the process object in Node child processes. Note that, on Linux, each Node child process has its own separate instance of the breakpad crash reporter. This is dissimilar to renderer child processes, which have a \"stub\" breakpad reporter which returns information to the main process for reporting.
process.crashReporter.start(options)process.crashReporter.getParameters()See crashReporter.getParameters().
process.crashReporter.addExtraParameter(key, value)See crashReporter.addExtraParameter(key, value).
process.crashReporter.removeExtraParameter(key)See crashReporter.removeExtraParameter(key).
O módulo crashReporter tem os seguintes métodos:
crashReporter.start(options)options ObjectsubmitURL String (optional) - URL that crash reports will be sent to as POST. Required unless uploadToServer is false.productName String (optional) - Defaults to app.name.companyName String (optional) Deprecated - Deprecated alias for { globalExtra: { _companyName: ... } }.uploadToServer Boolean (optional) - Whether crash reports should be sent to the server. If false, crash reports will be collected and stored in the crashes directory, but not uploaded. Por padrão é true.ignoreSystemCrashHandler Boolean (optional) - If true, crashes generated in the main process will not be forwarded to the system crash handler. Por padrão é false.rateLimit Boolean (optional) macOS Windows - If true, limit the number of crashes uploaded to 1/hour. Por padrão é false.compress Boolean (optional) - If true, crash reports will be compressed and uploaded with Content-Encoding: gzip. Por padrão é true.extra Record<String, String> (optional) - Extra string key/value annotations that will be sent along with crash reports that are generated in the main process. Only string values are supported. Crashes generated in child processes will not contain these extra parameters to crash reports generated from child processes, call addExtraParameter from the child process.globalExtra Record<String, String> (optional) - Extra string key/value annotations that will be sent along with any crash reports generated in any process. These annotations cannot be changed once the crash reporter has been started. If a key is present in both the global extra parameters and the process-specific extra parameters, then the global one will take precedence. By default, productName and the app version are included, as well as the Electron version.This method must be called before using any other crashReporter APIs. Once initialized this way, the crashpad handler collects crashes from all subsequently created processes. The crash reporter cannot be disabled once started.
This method should be called as early as possible in app startup, preferably before app.on('ready'). If the crash reporter is not initialized at the time a renderer process is created, then that renderer process will not be monitored by the crash reporter.
Note: You can test out the crash reporter by generating a crash using process.crash().
Note: If you need to send additional/updated extra parameters after your first call start you can call addExtraParameter.
Note: Parameters passed in extra, globalExtra or set with addExtraParameter have limits on the length of the keys and values. Key names must be at most 39 bytes long, and values must be no longer than 127 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated.
Note: This method is only available in the main process.
\ncrashReporter.getLastCrashReport()Returns CrashReport - The date and ID of the last crash report. Only crash reports that have been uploaded will be returned; even if a crash report is present on disk it will not be returned until it is uploaded. No caso de não existirem relatórios enviados, null é retornado.
Note: This method is only available in the main process.
\ncrashReporter.getUploadedReports()Retorna CrashReport[]:
Returns all uploaded crash reports. Each report contains the date and uploaded ID.
\nNote: This method is only available in the main process.
\ncrashReporter.getUploadToServer()Returns Boolean - Whether reports should be submitted to the server. Set through the start method or setUploadToServer.
Note: This method is only available in the main process.
\ncrashReporter.setUploadToServer(uploadToServer)uploadToServer Boolean - Whether reports should be submitted to the server.This would normally be controlled by user preferences. This has no effect if called before start is called.
Note: This method is only available in the main process.
\ncrashReporter.addExtraParameter(key, value)key String - Parameter key, must be no longer than 39 bytes.value String - Parameter value, must be no longer than 127 bytes.Set an extra parameter to be sent with the crash report. The values specified here will be sent in addition to any values set via the extra option when start was called.
Parameters added in this fashion (or via the extra parameter to crashReporter.start) are specific to the calling process. Adding extra parameters in the main process will not cause those parameters to be sent along with crashes from renderer or other child processes. Similarly, adding extra parameters in a renderer process will not result in those parameters being sent with crashes that occur in other renderer processes or in the main process.
Note: Parameters have limits on the length of the keys and values. Key names must be no longer than 39 bytes, and values must be no longer than 20320 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated.
\nNote: On linux values that are longer than 127 bytes will be chunked into multiple keys, each 127 bytes in length. Ex. addExtraParameter('foo', 'a'.repeat(130)) will result in two chunked keys foo__1 and foo__2, the first will contain the first 127 bytes and the second will contain the remaining 3 bytes. On your crash reporting backend you should stitch together keys in this format.
crashReporter.removeExtraParameter(key)key String - Parameter key, must be no longer than 39 bytes.Remove an extra parameter from the current set of parameters. Future crashes will not include this parameter.
\ncrashReporter.getParameters()Returns Record<String, String> - The current 'extra' parameters of the crash reporter.
The crash reporter will send the following data to the submitURL as a multipart/form-data POST:
ver String - The version of Electron.platform String - e.g. 'win32'.process_type String - e.g. 'renderer'.guid String - e.g. '5e1286fc-da97-479e-918b-6bfb0c3d1c72'._version String - The version in package.json._productName String - The product name in the crashReporter options object.prod String - Name of the underlying product. In this case Electron._companyName String - The company name in the crashReporter options object.upload_file_minidump File - The crash report in the format of minidump.extra object in the crashReporter options object.scheme String - Custom schemes to be registered with options.privileges Object (optional)standard Boolean (optional) - Default false.secure Boolean (optional) - Default false.bypassCSP Boolean (optional) - Default false.allowServiceWorkers Boolean (optional) - Default false.supportFetchAPI Boolean (optional) - Default false.corsEnabled Boolean (optional) - Default false.stream Boolean (optional) - Default false.\"Native interfaces\" include the file picker, window border, dialogs, context menus, and more - anything where the UI comes from your operating system and not from your app. O comportamento padrão é optar por esse tema automático do sistema operacional.
\nIf your app has its own dark mode, you should toggle it on and off in sync with the system's dark mode setting. You can do this by using the [prefer-color-scheme] CSS media query.
\nIf you want to manually switch between light/dark modes, you can do this by setting the desired mode in the themeSource property of the nativeTheme module. This property's value will be propagated to your Renderer process. Any CSS rules related to prefers-color-scheme will be updated accordingly.
No macOS 10.14 Mojave, a Apple introduziu um novo system-wide dark mode para todos computadores macOS. If your Electron app has a dark mode, you can make it follow the system-wide dark mode setting using the nativeTheme api.
In macOS 10.15 Catalina, Apple introduced a new \"automatic\" dark mode option for all macOS computers. In order for the nativeTheme.shouldUseDarkColors and Tray APIs to work correctly in this mode on Catalina, you need to use Electron >=7.0.0, or set NSRequiresAquaSystemAppearance to false in your Info.plist file for older versions. Both Electron Packager and Electron Forge have a darwinDarkModeSupport option to automate the Info.plist changes during app build time.
If you wish to opt-out while using Electron > 8.0.0, you must set the NSRequiresAquaSystemAppearance key in the Info.plist file to true. Please note that Electron 8.0.0 and above will not let you opt-out of this theming, due to the use of the macOS 10.14 SDK.
This example demonstrates an Electron application that derives its theme colors from the nativeTheme. Additionally, it provides theme toggle and reset controls using IPC channels.
Starting with the index.html file:
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n <link rel=\"stylesheet\" type=\"text/css\" href=\"./styles.css\">\n</head>\n<body>\n <h1>Hello World!</h1>\n <p>Current theme source: <strong id=\"theme-source\">System</strong></p>\n\n <button id=\"toggle-dark-mode\">Toggle Dark Mode</button>\n <button id=\"reset-to-system\">Reset to System Theme</button>\n\n <script src=\"renderer.js\"></script>\n </body>\n</body>\n</html>\nAnd the styles.css file:
@media (prefers-color-scheme: dark) {\n body { background: #333; color: white; }\n}\n\n@media (prefers-color-scheme: light) {\n body { background: #ddd; color: black; }\n}\nThe example renders an HTML page with a couple elements. The <strong id=\"theme-source\"> element shows which theme is currently selected, and the two <button> elements are the controls. The CSS file uses the prefers-color-scheme media query to set the <body> element background and text colors.
The preload.js script adds a new API to the window object called darkMode. This API exposes two IPC channels to the renderer process, 'dark-mode:toggle' and 'dark-mode:system'. It also assigns two methods, toggle and system, which pass messages from the renderer to the main process.
const { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld('darkMode', {\n toggle: () => ipcRenderer.invoke('dark-mode:toggle'),\n system: () => ipcRenderer.invoke('dark-mode:system')\n})\nNow the renderer process can communicate with the main process securely and perform the necessary mutations to the nativeTheme object.
The renderer.js file is responsible for controlling the <button> functionality.
document.getElementById('toggle-dark-mode').addEventListener('click', async () => {\n const isDarkMode = await window.darkMode.toggle()\n document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'\n})\n\ndocument.getElementById('reset-to-system').addEventListener('click', async () => {\n await window.darkMode.system()\n document.getElementById('theme-source').innerHTML = 'System'\n})\nUsing addEventListener, the renderer.js file adds 'click' event listeners to each button element. Each event listener handler makes calls to the respective window.darkMode API methods.
Finally, the main.js file represents the main process and contains the actual nativeTheme API.
const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n\n ipcMain.handle('dark-mode:toggle', () => {\n if (nativeTheme.shouldUseDarkColors) {\n nativeTheme.themeSource = 'light'\n } else {\n nativeTheme.themeSource = 'dark'\n }\n return nativeTheme.shouldUseDarkColors\n })\n\n ipcMain.handle('dark-mode:system', () => {\n nativeTheme.themeSource = 'system'\n })\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nThe ipcMain.handle methods are how the main process responds to the click events from the buttons on the HTML page.
The 'dark-mode:toggle' IPC channel handler method checks the shouldUseDarkColors boolean property, sets the corresponding themeSource, and then returns the current shouldUseDarkColors property. Looking back on the renderer process event listener for this IPC channel, the return value from this handler is utilized to assign the correct text to the <strong id='theme-source'> element.
The 'dark-mode:system' IPC channel handler method assigns the string 'system' to the themeSource and returns nothing. This also corresponds with the relative renderer process event listener as the method is awaited with no return value expected.
Run the example using Electron Fiddle and then click the \"Toggle Dark Mode\" button; the app should start alternating between a light and dark background color.
\n
Se experimentar falhas ou problemas no Electron que acredita que não são causados pelo seu aplicativo de JavaScript, mas devido ao próprio Electron, a depuração pode ser um pouco complicada, especialmente para os desenvolvedores que não usam a depuração nativa/C++. However, using Visual Studio, Electron's hosted Symbol Server, and the Electron source code, you can enable step-through debugging with breakpoints inside Electron's source code.
\nSee also: There's a wealth of information on debugging Chromium, much of which also applies to Electron, on the Chromium developers site: Debugging Chromium on Windows.
\nDepurar uma compilação de Electron: A maneira mais fácil é normalmente construí-lo você mesmo, usando as ferramentas e os pré-requisitos listados na construir instruções para Windows. While you can attach to and debug Electron as you can download it directly, you will find that it is heavily optimized, making debugging substantially more difficult: The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations.
\nVisual Studio com ferramentas C++: As edições de comunidade livre de Visual Studio de 2013 e Visual Studio 2015, ambos trabalham. Once installed, configure Visual Studio to use Electron's Symbol server. Permitirá que o Visual Studio obtenha uma melhor compreensão do que acontece dentro de Electron, tornando mais fácil para apresentar as variáveis num formato legível.
\nProcMon: The free SysInternals tool allows you to inspect a processes parameters, file handles, and registry operations.
\nPara iniciar uma sessão de depuração, abrá CMD/PowerShell e execute a sua compilação para depuração do Electron, usando o aplicativo para abrir como um parâmetro.
\n$ ./out/Testing/electron.exe ~/my-electron-app/\nEm seguida, abra o Visual Studio. Electron is not built with Visual Studio and hence does not contain a project file - you can however open up the source code files \"As File\", meaning that Visual Studio will open them up by themselves. You can still set breakpoints - Visual Studio will automatically figure out that the source code matches the code running in the attached process and break accordingly.
\nRelevant code files can be found in ./shell/.
You can attach the Visual Studio debugger to a running process on a local or remote computer. After the process is running, click Debug / Attach to Process (or press CTRL+ALT+P) to open the \"Attach to Process\" dialog box. You can use this capability to debug apps that are running on a local or remote computer, debug multiple processes simultaneously.
If Electron is running under a different user account, select the Show processes from all users check box. Notice that depending on how many BrowserWindows your app opened, you will see multiple processes. A typical one-window app will result in Visual Studio presenting you with two Electron.exe entries - one for the main process and one for the renderer process. Since the list only gives you names, there's currently no reliable way of figuring out which is which.
Code executed within the main process (that is, code found in or eventually run by your main JavaScript file) will run inside the main process, while other code will execute inside its respective renderer process.
\nYou can be attached to multiple programs when you are debugging, but only one program is active in the debugger at any time. You can set the active program in the Debug Location toolbar or the Processes window.
While Visual Studio is fantastic for inspecting specific code paths, ProcMon's strength is really in observing everything your application is doing with the operating system - it captures File, Registry, Network, Process, and Profiling details of processes. It attempts to log all events occurring and can be quite overwhelming, but if you seek to understand what and how your application is doing to the operating system, it can be a valuable resource.
\nFor an introduction to ProcMon's basic and advanced debugging features, go check out this video tutorial provided by Microsoft.
", "title": "Depuração no Windows", "description": "" }, "/docs/api/debugger": { "locale": "pt-BR", "slug": "debugger", "href": "/docs/api/debugger", "crowdinFileId": "256305", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/debugger.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nUm transporte alternativo para o protocolo de depuração remoto do Chrome.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
As ferramentas de desenvolvedor do Chrome possuem special binding disponível no runtime do JavaScript que permite interagir com páginas e instrumentá-las.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\ntry {\n win.webContents.debugger.attach('1.1')\n} catch (err) {\n console.log('Debugger attach failed : ', err)\n}\n\nwin.webContents.debugger.on('detach', (event, reason) => {\n console.log('Debugger detached due to : ', reason)\n})\n\nwin.webContents.debugger.on('message', (event, method, params) => {\n if (method === 'Network.requestWillBeSent') {\n if (params.request.url === 'https://www.github.com') {\n win.webContents.debugger.detach()\n }\n }\n})\n\nwin.webContents.debugger.sendCommand('Network.enable')\nRetorna:
\nevent Eventreason String - Reason for detaching debugger.Emitted when the debugging session is terminated. This happens either when webContents is closed or devtools is invoked for the attached webContents.
Retorna:
\nevent Eventmethod String - Method name.params any - Event parameters defined by the 'parameters' attribute in the remote debugging protocol.sessionId String - Unique identifier of attached debugging session, will match the value sent from debugger.sendCommand.Emitted whenever the debugging target issues an instrumentation event.
\ndebugger.attach([protocolVersion])protocolVersion String (opcional) - Versão do protocolo de debugging solicitado.Anexa o debugger à webContents.
debugger.isAttached()Retorna um Boolean - que mostra se o debugger está anexado à webContents.
debugger.detach()Retira o debugger de webContents.
debugger.sendCommand(method[, commandParams, sessionId])method String - Method name, should be one of the methods defined by the remote debugging protocol.commandParams any (optional) - JSON object with request parameters.sessionId String (optional) - send command to the target with associated debugging session id. The initial value can be obtained by sending Target.attachToTarget message.Returns Promise<any> - A promise that resolves with the response defined by the 'returns' attribute of the command description in the remote debugging protocol or is rejected indicating the failure of the command.
Send given command to the debugging target.
", "title": "Debugger", "description": "Um transporte alternativo para o protocolo de depuração remoto do Chrome." }, "/docs/development/debugging-instructions-macos": { "locale": "pt-BR", "slug": "debugging-instructions-macos", "href": "/docs/development/debugging-instructions-macos", "crowdinFileId": "256153", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Se experimentar falhas ou problemas no Electron que acredita que não são causados pelo seu aplicativo de JavaScript, mas devido ao próprio Electron, a depuração pode ser um pouco complicada, especialmente para os desenvolvedores que não usam a depuração nativa/C++. However, using lldb, and the Electron source code, you can enable step-through debugging with breakpoints inside Electron's source code. You can also use XCode for debugging if you prefer a graphical interface.
\nA debug build of Electron: The easiest way is usually building it yourself, using the tools and prerequisites listed in the build instructions for macOS. While you can attach to and debug Electron as you can download it directly, you will find that it is heavily optimized, making debugging substantially more difficult: The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations.
\nXcode: In addition to Xcode, also install the Xcode command line tools. They include LLDB, the default debugger in Xcode on macOS. It supports debugging C, Objective-C and C++ on the desktop and iOS devices and simulator.
\n.lldbinit: Create or edit ~/.lldbinit to allow Chromium code to be properly source-mapped.
# e.g: ['~/electron/src/tools/lldb']\nscript sys.path[:0] = ['<...path/to/electron/src/tools/lldb>']\nscript import lldbinit\nTo start a debugging session, open up Terminal and start lldb, passing a non-release build of Electron as a parameter.
$ lldb ./out/Testing/Electron.app\n(lldb) target create \"./out/Testing/Electron.app\"\nCurrent executable set to './out/Testing/Electron.app' (x86_64).\nLLDB is a powerful tool and supports multiple strategies for code inspection. For this basic introduction, let's assume that you're calling a command from JavaScript that isn't behaving correctly - so you'd like to break on that command's C++ counterpart inside the Electron source.
\nRelevant code files can be found in ./shell/.
Let's assume that you want to debug app.setName(), which is defined in browser.cc as Browser::SetName(). Set the breakpoint using the breakpoint command, specifying file and line to break on:
(lldb) breakpoint set --file browser.cc --line 117\nBreakpoint 1: where = Electron Framework`atom::Browser::SetName(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) + 20 at browser.cc:118, address = 0x000000000015fdb4\nThen, start Electron:
\n(lldb) run\nThe app will immediately be paused, since Electron sets the app's name on launch:
\n(lldb) run\nProcess 25244 launched: '/Users/fr/Code/electron/out/Testing/Electron.app/Contents/MacOS/Electron' (x86_64)\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1\n frame #0: 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118\n 115 }\n 116\n 117 void Browser::SetName(const std::string& name) {\n-> 118 name_override_ = name;\n 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n(lldb)\nTo show the arguments and local variables for the current frame, run frame variable (or fr v), which will show you that the app is currently setting the name to \"Electron\".
(lldb) frame variable\n(atom::Browser *) this = 0x0000000108b14f20\n(const string &) name = \"Electron\": {\n [...]\n}\nTo do a source level single step in the currently selected thread, execute step (or s). This would take you into name_override_.empty(). To proceed and do a step over, run next (or n).
(lldb) step\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119, queue = 'com.apple.main-thread', stop reason = step in\n frame #0: 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119\n 116\n 117 void Browser::SetName(const std::string& name) {\n 118 name_override_ = name;\n-> 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n 122 return badge_count_;\nNOTE: If you don't see source code when you think you should, you may not have added the ~/.lldbinit file above.
To finish debugging at this point, run process continue. You can also continue until a certain line is hit in this thread (thread until 100). This command will run the thread in the current frame till it reaches line 100 in this frame or stops if it leaves the current frame.
Now, if you open up Electron's developer tools and call setName, you will once again hit the breakpoint.
LLDB is a powerful tool with a great documentation. To learn more about it, consider Apple's debugging documentation, for instance the LLDB Command Structure Reference or the introduction to Using LLDB as a Standalone Debugger.
\nYou can also check out LLDB's fantastic manual and tutorial, which will explain more complex debugging scenarios.
", "title": "Depuração no macOS", "description": "" }, "/docs/development/debugging-instructions-macos-xcode": { "locale": "pt-BR", "slug": "debugging-instructions-macos-xcode", "href": "/docs/development/debugging-instructions-macos-xcode", "crowdinFileId": "256151", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos-xcode.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Run gn gen with the --ide=xcode argument.
$ gn gen out/Testing --ide=xcode\nThis will generate the electron.ninja.xcworkspace. You will have to open this workspace to set breakpoints and inspect.
\nSee gn help gen for more information on generating IDE projects with GN.
Launch Electron app after build. You can now open the xcode workspace created above and attach to the Electron process through the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug the renderer process, you need to attach to the Electron Helper as well.]
\nYou can now set breakpoints in any of the indexed files. However, you will not be able to set breakpoints directly in the Chromium source. To set break points in the Chromium source, you can choose Debug > Breakpoints > Create Symbolic Breakpoint and set any function name as the symbol. This will set the breakpoint for all functions with that name, from all the classes if there are more than one. You can also do this step of setting break points prior to attaching the debugger, however, actual breakpoints for symbolic breakpoint functions may not show up until the debugger is attached to the app.
", "title": "Debugging with XCode", "description": "" }, "/docs/tutorial/debugging-main-process": { "locale": "pt-BR", "slug": "debugging-main-process", "href": "/docs/tutorial/debugging-main-process", "crowdinFileId": "256189", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/debugging-main-process.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "O DevTools em uma janela do navegador do Electron, só pode depurar JavaScript que é executado na janela (ex. uma web página). Para depurar JavaScript que é executado no processo principal você precisá usar um depurador externo e fazer o carregamento do Electron com o --inspect ou --inspect-brk.
Use uma das seguintes opções de linha de comando para habilitar a depuração principal processo:
\n--inspect=[porta]Electron will listen for V8 inspector protocol messages on the specified port, an external debugger will need to connect on this port. The default port is 5858.
electron --inspect=5858 seu/app\n--inspect-brk=[porta]Como o --inspect mas pausa a execução na primeira linha de JavaScript.
Você precisá usar um depurador que suporta o protocolo de inspeção do V8.
\nchrome://inspect e selecionando para inspecionar o Electron app.Este guia trata de como configurar a depuração usando VSCode tanto para seu próprio projeto no Electron como para código nativo do Electron.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json com a seguinte configuração:{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"Debug Main Process\",\n \"type\": \"node\",\n \"request\": \"launch\",\n \"cwd\": \"${workspaceFolder}\",\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron\",\n \"windows\": {\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron.cmd\"\n },\n \"args\" : [\".\"],\n \"outputCapture\": \"std\"\n }\n ]\n}\nSet some breakpoints in main.js, and start debugging in the Debug View. You should be able to hit the breakpoints.
Aqui está um projeto pré-configurado que você pode baixar e depurar diretamente no VSCode: https://github.com/octref/vscode-electron-debug/tree/master/electron-quick-start
\nIf you want to build Electron from source and modify the native Electron codebase, this section will help you in testing your modifications.
\nFor those unsure where to acquire this code or how to build it, Electron's Build Tools automates and explains most of this process. If you wish to manually set up the environment, you can instead use these build instructions.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json com a seguinte configuração:{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"(Windows) Launch\",\n \"type\": \"cppvsdbg\",\n \"request\": \"launch\",\n \"program\": \"${workspaceFolder}\\\\out\\\\your-executable-location\\\\electron.exe\",\n \"args\": [\"your-electron-project-path\"],\n \"stopAtEntry\": false,\n \"cwd\": \"${workspaceFolder}\",\n \"environment\": [\n {\"name\": \"ELECTRON_ENABLE_LOGGING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_ENABLE_STACK_DUMPING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_RUN_AS_NODE\", \"value\": \"\"},\n ],\n \"externalConsole\": false,\n \"sourceFileMap\": {\n \"o:\\\\\": \"${workspaceFolder}\",\n },\n },\n ]\n}\nConfiguration Notes
\ncppvsdbg requires the built-in C/C++ extension be enabled.${workspaceFolder} is the full path to Chromium's src directory.your-executable-location will be one of the following depending on a few items:Testing: If you are using the default settings of Electron's Build-Tools or the default instructions when building from source.Release: If you built a Release build rather than a Testing build.your-directory-name: If you modified this during your build process from the default, this will be whatever you specified.args array string \"your-electron-project-path\" should be the absolute path to either the directory or main.js file of the Electron project you are using for testing. In this example, it should be your path to electron-quick-start.Set some breakpoints in the .cc files of your choosing in the native Electron C++ code, and start debugging in the Debug View.
", "title": "Debugging in VSCode", "description": "" }, "/docs/api/desktop-capturer": { "locale": "pt-BR", "slug": "desktop-capturer", "href": "/docs/api/desktop-capturer", "crowdinFileId": "256307", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/desktop-capturer.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n\nAccess information about media sources that can be used to capture audio and video from the desktop using the
\nnavigator.mediaDevices.getUserMediaAPI.
O exemplo a seguir mostra como capturar vídeo de uma janela desktop com o título Electron:
// No processo renderer.\nconst { desktopCapturer } = require('electron')\n\ndesktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources => {\n for (const source of sources) {\n if (source.name === 'Electron') {\n try {\n const stream = await navigator.mediaDevices.getUserMedia({\n audio: false,\n video: {\n mandatory: {\n chromeMediaSource: 'desktop',\n chromeMediaSourceId: source.id,\n minWidth: 1280,\n maxWidth: 1280,\n minHeight: 720,\n maxHeight: 720\n }\n }\n })\n handleStream(stream)\n } catch (e) {\n handleError(e)\n }\n return\n }\n }\n})\n\nfunction handleStream (stream) {\n const video = document.querySelector('video')\n video.srcObject = stream\n video.onloadedmetadata = (e) => video.play()\n}\n\nfunction handleError (e) {\n console.log(e)\n}\nTo capture video from a source provided by desktopCapturer the constraints passed to navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop', and audio: false.
To capture both audio and video from the entire desktop the constraints passed to navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop', for both audio and video, but should not include a chromeMediaSourceId constraint.
const constraints = {\n audio: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n },\n video: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n }\n}\nO módulo desktopCapturer tem os seguintes métodos:
desktopCapturer.getSources(options)options Objecttypes String[] - Um array de Strings que lista os tipos de área de trabalho a serem capturadas, tipos disponíveis são screen e window.thumbnailSize Size (optional) - The size that the media source thumbnail should be scaled to. Default is 150 x 150. Set width or height to 0 when you do not need the thumbnails. This will save the processing time required for capturing the content of each window and screen.fetchWindowIcons Boolean (optional) - Set to true to enable fetching window icons. The default value is false. When false the appIcon property of the sources return null. Same if a source has the type screen.Returns Promise<DesktopCapturerSource[]> - Resolves with an array of DesktopCapturerSource objects, each DesktopCapturerSource represents a screen or an individual window that can be captured.
Note Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher, which can detected by systemPreferences.getMediaAccessStatus.
navigator.mediaDevices.getUserMedia does not work on macOS for audio capture due to a fundamental limitation whereby apps that want to access the system's audio require a signed kernel extension. Chromium, and by extension Electron, does not provide this.
It is possible to circumvent this limitation by capturing system audio with another macOS app like Soundflower and passing it through a virtual audio input device. This virtual device can then be queried with navigator.mediaDevices.getUserMedia.
id String - The identifier of a window or screen that can be used as a chromeMediaSourceId constraint when calling [navigator.webkitGetUserMedia]. The format of the identifier will be window:XX:YY or screen:ZZ:0. XX is the windowID/handle. YY is 1 for the current process, and 0 for all others. ZZ is a sequential number that represents the screen, and it does not equal to the index in the source's name.name String - A screen source will be named either Entire Screen or Screen <index>, while the name of a window source will match the window title.thumbnail NativeImage - A thumbnail image. Note: There is no guarantee that the size of the thumbnail is the same as the thumbnailSize specified in the options passed to desktopCapturer.getSources. The actual size depends on the scale of the screen or window.display_id String - A unique identifier that will correspond to the id of the matching Display returned by the Screen API. On some platforms, this is equivalent to the XX portion of the id field above and on others it will differ. It will be an empty string if not available.appIcon NativeImage - An icon image of the application that owns the window or null if the source has a type screen. The size of the icon is not known in advance and depends on what the application provides.Like Chromium based browsers, Electron provides access to device hardware through web APIs. For the most part these APIs work like they do in a browser, but there are some differences that need to be taken into account. The primary difference between Electron and browsers is what happens when device access is requested. In a browser, users are presented with a popup where they can grant access to an individual device. In Electron APIs are provided which can be used by a developer to either automatically pick a device or prompt users to pick a device via a developer created interface.
\nThe Web Bluetooth API can be used to communicate with bluetooth devices. In order to use this API in Electron, developers will need to handle the select-bluetooth-device event on the webContents associated with the device request.
This example demonstrates an Electron application that automatically selects the first available bluetooth device when the Test Bluetooth button is clicked.
The WebHID API can be used to access HID devices such as keyboards and gamepads. Electron provides several APIs for working with the WebHID API:
\nselect-hid-device event on the Session can be used to select a HID device when a call to navigator.hid.requestDevice is made. Additionally the hid-device-added and hid-device-removed events on the Session can be used to handle devices being plugged in or unplugged during the navigator.hid.requestDevice process.ses.setDevicePermissionHandler(handler) can be used to provide default permissioning to devices without first calling for permission to devices via navigator.hid.requestDevice. Additionally, the default behavior of Electron is to store granted device permision through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.ses.setPermissionCheckHandler(handler) can be used to disable HID access for specific origins.By default Electron employs the same blocklist used by Chromium. If you wish to override this behavior, you can do so by setting the disable-hid-blocklist flag:
app.commandLine.appendSwitch('disable-hid-blocklist')\nThis example demonstrates an Electron application that automatically selects HID devices through ses.setDevicePermissionHandler(handler) and through select-hid-device event on the Session when the Test WebHID button is clicked.
The Web Serial API can be used to access serial devices that are connected via serial port, USB, or Bluetooth. In order to use this API in Electron, developers will need to handle the select-serial-port event on the Session associated with the serial port request.
There are several additional APIs for working with the Web Serial API:
\nserial-port-added and serial-port-removed events on the Session can be used to handle devices being plugged in or unplugged during the navigator.serial.requestPort process.ses.setPermissionCheckHandler(handler) can be used to disable serial access for specific origins.This example demonstrates an Electron application that automatically selects the first available Arduino Uno serial device (if connected) through select-serial-port event on the Session when the Test Web Serial button is clicked.
Electron supports Chrome DevTools extensions, which can be used to extend the ability of Chrome's developer tools for debugging popular web frameworks.
\nThe easiest way to load a DevTools extension is to use third-party tooling to automate the process for you. electron-devtools-installer is a popular NPM package that does just that.
\nIf you don't want to use the tooling approach, you can also do all of the necessary operations by hand. To load an extension in Electron, you need to download it via Chrome, locate its filesystem path, and then load it into your Session by calling the [ses.loadExtension] API.
Using the React Developer Tools as an example:
\nInstall the extension in Google Chrome.
\nNavigate to chrome://extensions, and find its extension ID, which is a hash string like fmkadmapgofadopljbjfkapdkoienihi.
Find out the filesystem location used by Chrome for storing extensions:
\n%LOCALAPPDATA%\\Google\\Chrome\\User Data\\Default\\Extensions;~/.config/google-chrome/Default/Extensions/~/.config/google-chrome-beta/Default/Extensions/~/.config/google-chrome-canary/Default/Extensions/~/.config/chromium/Default/Extensions/~/Library/Application Support/Google/Chrome/Default/Extensions.Pass the location of the extension to the ses.loadExtension API. For React Developer Tools v4.9.0, it looks something like:
const { app, session } = require('electron')\n const path = require('path')\n const os = require('os')\n\n // on macOS\n const reactDevToolsPath = path.join(\n os.homedir(),\n '/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.9.0_0'\n )\n\n app.whenReady().then(async () => {\n await session.defaultSession.loadExtension(reactDevToolsPath)\n })\nNotas:
\nloadExtension returns a Promise with an Extension object, which contains metadata about the extension that was loaded. This promise needs to resolve (e.g. with an await expression) before loading a page. Otherwise, the extension won't be guaranteed to load.loadExtension cannot be called before the ready event of the app module is emitted, nor can it be called on in-memory (non-persistent) sessions.loadExtension must be called on every boot of your app if you want the extension to be loaded.You can pass the extension's ID to the ses.removeExtension API to remove it from your Session. Loaded extensions are not persisted between app launches.
Electron only supports a limited set of chrome.* APIs, so extensions using unsupported chrome.* APIs under the hood may not work.
The following Devtools extensions have been tested to work in Electron:
\nFirst, please make sure the extension is still being maintained and is compatible with the latest version of Google Chrome. We cannot provide additional support for unsupported extensions.
\nIf the extension works on Chrome but not on Electron, file a bug in Electron's issue tracker and describe which part of the extension is not working as expected.
", "title": "Extensão de DevTools", "description": "" }, "/docs/api/dialog": { "locale": "pt-BR", "slug": "dialog", "href": "/docs/api/dialog", "crowdinFileId": "256309", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/dialog.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nExibe diálogos nativos do sistema para abrir e salvar arquivos, alertas, etc.
\n
Processo: Main
\nAn example of showing a dialog to select multiple files:
\nconst { dialog } = require('electron')\nconsole.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))\nO módulo dialog possúi os seguintes métodos:
dialog.showOpenDialogSync([browserWindow, ]options[, callback)browserWindow BrowserWindow)options Objecttitle String (opcional)defaultPath String (opcional)buttonLabel String (opcional) - Rótulo personalizado para o botão de confirmação, quando deixado em branco o label padrão será usado.filters FileFilter[] (opcional)properties String[] (optional) - Contains which features the dialog should use. The following values are supported:openFile - Permite selecionar arquivos.openDirectory - Permite selecionar diretórios.multiSelections - Permite selecionar múltiplos caminhos.showHiddenFiles - Mostra arquivos escondidos no dialog.createDirectory macOS - Allow creating new directories from dialog.promptToCreate Windows - Prompt for creation if the file path entered in the dialog does not exist. Na verdade este valor não cria o arquivo no caminho especificado mas permite que o aplicativo entenda que deverá criar o diretório não existente.noResolveAliases macOS - Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.treatPackageAsDirectory macOS - Treat packages, such as .app folders, as a directory instead of a file.dontAddToRecent Windows - Do not add the item being opened to the recent documents list.message String (opcional) macOS - Mensagem a ser apresentada acima da janela de entrada.securityScopedBookmarks Boolean (optional) macOS mas - Create security scoped bookmarks when packaged for the Mac App Store.Returns String[] | undefined, the file paths chosen by the user; if the dialog is cancelled it returns undefined.
O argumento browserWindow permite que o diálogo seja acoplado a janela parent, tornando-a modal.
The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Como por exemplo:
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nAs array de extensions devem conter extensões sem caracteres-curinga ou pontos. ('png' é bom mas, '.png' e '*.png' são ruins). Para mostrar todos os arquivos use o caracter-curinga * (nenhum ouro caracter-curinga é suportado).
Nota.: No Windows e Linux um diálogo aberto não pode ser usado ao mesmo tempo para selecionar arquivos e diretórios, portanto se você estabelecer properties para ['openFile', 'openDirectory'] nessas plataformas, um seletor de diretório será mostrado.
dialog.showOpenDialogSync(mainWindow, {\n properties: ['openFile', 'openDirectory']\n})\ndialog.showOpenDialog([browserWindow, ]options[, callback)browserWindow BrowserWindow)options Objecttitle String (opcional)defaultPath String (opcional)buttonLabel String (opcional) - Rótulo personalizado para o botão de confirmação, quando deixado em branco o label padrão será usado.filters FileFilter[] (opcional)properties String[] (optional) - Contains which features the dialog should use. The following values are supported:openFile - Permite selecionar arquivos.openDirectory - Permite selecionar diretórios.multiSelections - Permite selecionar múltiplos caminhos.showHiddenFiles - Mostra arquivos escondidos no dialog.createDirectory macOS - Allow creating new directories from dialog.promptToCreate Windows - Prompt for creation if the file path entered in the dialog does not exist. Na verdade este valor não cria o arquivo no caminho especificado mas permite que o aplicativo entenda que deverá criar o diretório não existente.noResolveAliases macOS - Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.treatPackageAsDirectory macOS - Treat packages, such as .app folders, as a directory instead of a file.dontAddToRecent Windows - Do not add the item being opened to the recent documents list.message String (opcional) macOS - Mensagem a ser apresentada acima da janela de entrada.securityScopedBookmarks Boolean (optional) macOS mas - Create security scoped bookmarks when packaged for the Mac App Store.Returns Promise<Object> - Resolve with an object containing the following:
canceled Boolean - whether or not the dialog was canceled.filePaths String[] - Um array de caminhos de arquivos selecionados pelo usuário. If the dialog is cancelled this will be an empty array.bookmarks String[] (optional) macOS mas - An array matching the filePaths array of base64 encoded strings which contains security scoped bookmark data. securityScopedBookmarks must be enabled for this to be populated. (For return values, see table here.)O argumento browserWindow permite que o diálogo seja acoplado a janela parent, tornando-a modal.
The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Como por exemplo:
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nAs array de extensions devem conter extensões sem caracteres-curinga ou pontos. ('png' é bom mas, '.png' e '*.png' são ruins). Para mostrar todos os arquivos use o caracter-curinga * (nenhum ouro caracter-curinga é suportado).
Nota.: No Windows e Linux um diálogo aberto não pode ser usado ao mesmo tempo para selecionar arquivos e diretórios, portanto se você estabelecer properties para ['openFile', 'openDirectory'] nessas plataformas, um seletor de diretório será mostrado.
dialog.showOpenDialog(mainWindow, {\n properties: ['openFile', 'openDirectory']\n}).then(result => {\n console.log(result.canceled)\n console.log(result.filePaths)\n}).catch(err => {\n console.log(err)\n})\ndialog.showSaveDialogSync([browserWindow, ]options[, callback)browserWindow BrowserWindow)options Objecttitle String (optional) - The dialog title. Cannot be displayed on some Linux desktop environments.defaultPath String (opcional) - Caminho absoluto do diretório, caminho absoluto do arquivo, ou o nome do arquivo a ser usado como padrão.buttonLabel String (opcional) - Rótulo personalizado para o botão de confirmação, quando deixado em branco o label padrão será usado.filters FileFilter[] (opcional)message String (opcional) macOS - Mensagem a ser exibida acima de campos de texto.nameFieldLabel String (opcional) macOS - Rótulo personalizado do texto a ser exibido em frente ao campo do nome do arquivo.showsTagField Boolean (opcional) macOS - apresenta a tag do campo de entrada, por padrão true.properties String[] (optional)showHiddenFiles - Mostra arquivos escondidos no dialog.createDirectory macOS - Allow creating new directories from dialog.treatPackageAsDirectory macOS - Treat packages, such as .app folders, as a directory instead of a file.showOverwriteConfirmation Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.dontAddToRecent Windows - Do not add the item being saved to the recent documents list.securityScopedBookmarks Boolean (optional) macOS mas - Create a security scoped bookmark when packaged for the Mac App Store. If this option is enabled and the file doesn't already exist a blank file will be created at the chosen path.Returns String | undefined, the path of the file chosen by the user; if the dialog is cancelled it returns undefined.
O argumento browserWindow permite que o diálogo seja acoplado a janela parent, tornando-a modal.
Os filters especificam um array de tipos de arquivo que podem ser exibidos, veja dialog.ShowOpenDialog para exemplos.
dialog.showSaveDialog([browserWindow, ]options[, callback)browserWindow BrowserWindow)options Objecttitle String (optional) - The dialog title. Cannot be displayed on some Linux desktop environments.defaultPath String (opcional) - Caminho absoluto do diretório, caminho absoluto do arquivo, ou o nome do arquivo a ser usado como padrão.buttonLabel String (opcional) - Rótulo personalizado para o botão de confirmação, quando deixado em branco o label padrão será usado.filters FileFilter[] (opcional)message String (opcional) macOS - Mensagem a ser exibida acima de campos de texto.nameFieldLabel String (opcional) macOS - Rótulo personalizado do texto a ser exibido em frente ao campo do nome do arquivo.showsTagField Boolean (optional) macOS - Show the tags input box, defaults to true.properties String[] (optional)showHiddenFiles - Mostra arquivos escondidos no dialog.createDirectory macOS - Allow creating new directories from dialog.treatPackageAsDirectory macOS - Treat packages, such as .app folders, as a directory instead of a file.showOverwriteConfirmation Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.dontAddToRecent Windows - Do not add the item being saved to the recent documents list.securityScopedBookmarks Boolean (optional) macOS mas - Create a security scoped bookmark when packaged for the Mac App Store. If this option is enabled and the file doesn't already exist a blank file will be created at the chosen path.Returns Promise<Object> - Resolve with an object containing the following:
canceled Boolean - whether or not the dialog was canceled.filePath String (optional) - If the dialog is canceled, this will be undefined.bookmark String (optional) macOS mas - Base64 encoded string which contains the security scoped bookmark data for the saved file. securityScopedBookmarks must be enabled for this to be present. (For return values, see table here.)O argumento browserWindow permite que o diálogo seja acoplado a janela parent, tornando-a modal.
Os filters especificam um array de tipos de arquivo que podem ser exibidos, veja dialog.ShowOpenDialog para exemplos.
Note: On macOS, using the asynchronous version is recommended to avoid issues when expanding and collapsing the dialog.
\ndialog.showMessageBoxSync([browserWindow, ]options[, callback)browserWindow BrowserWindow)options Objectmessage String - Conteúdo da caixa de mensagem.type String (opcional) - Pode ser \"none\", \"info\", \"error\", \"question\" ou \"warning\". No Windows, \"question\" exibe o mesmo ícone que \"info\", a menos que você especifique um ícone usando a opção \"icon\". No macOS, tanto \"warning\" como \"error\" exibirão o mesmo ícone de alerta.buttons String[] (optional) - Array of texts for buttons. On Windows, an empty array will result in one button labeled \"OK\".defaultId Integer (opcional) - Indicador do botão na array de botões que será selecionado como padrão quando a caixa de mensagem abrir.title String (opcional) - Título da caixa de mensagem, algumas plataformas não o exibirão.detail String (opcional) - Informações adicionais da mensagem.icon (NativeImage | String) (opcional)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (opcional) - O indicador do botão será usado para cancelar o diálogo, por via da tecla Esc. Por padrão é atribuído ao primeiro botão como \"cancelar\" ou \"não\" como rótulos. If no such labeled buttons exist and this option is not set, 0 will be used as the return value.noLink Boolean (opcional) - No Windows, o Electron tentará identificar qual dos buttons são botões comuns (como \"cancelar\" ou \"sim\"), e exibir os outros como links de comandos no diálogo. Ele pode fazer o diálogo ser apresentado com o estilo dos aplicativos modernos do Windows. Se você não deseja esse comportamento, você pode definir noLink para true.normalizeAccessKeys Boolean (opcional) - Normaliza o acesso às teclas do teclado entre as plataformas. Por padrão é false. Ativando-o assume-se que & é usado nos rótulos dos botões para atribuir a tecla de atalho de acesso do teclado assim os rótulos serão convertidos para que funcionem corretamente em cada plataforma, os caracteres & são removidos no macOS, convertidos para _ no Linux, e deixados intactos no Windows. Por exemplo, um rótulo de botão Vie&w será convertido para Vie_w no Linux e View no macOS e pode ser selecionado através de Alt-W no Windows e Linux.Returns Integer - the index of the clicked button.
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button.
\nO argumento browserWindow permite que o diálogo seja acoplado a janela parent, tornando-a modal. If browserWindow is not shown dialog will not be attached to it. In such case it will be displayed as an independent window.
dialog.showMessageBox([browserWindow, ]options[, callback)browserWindow BrowserWindow)options Objectmessage String - Conteúdo da caixa de mensagem.type String (opcional) - Pode ser \"none\", \"info\", \"error\", \"question\" ou \"warning\". No Windows, \"question\" exibe o mesmo ícone que \"info\", a menos que você especifique um ícone usando a opção \"icon\". No macOS, tanto \"warning\" como \"error\" exibirão o mesmo ícone de alerta.buttons String[] (optional) - Array of texts for buttons. On Windows, an empty array will result in one button labeled \"OK\".defaultId Integer (opcional) - Indicador do botão na array de botões que será selecionado como padrão quando a caixa de mensagem abrir.signal AbortSignal (optional) - Pass an instance of AbortSignal to optionally close the message box, the message box will behave as if it was cancelled by the user. On macOS, signal does not work with message boxes that do not have a parent window, since those message boxes run synchronously due to platform limitations.title String (opcional) - Título da caixa de mensagem, algumas plataformas não o exibirão.detail String (opcional) - Informações adicionais da mensagem.checkboxLabel String (optional) - If provided, the message box will include a checkbox with the given label.checkboxChecked Boolean (optional) - Initial checked state of the checkbox. false by default.icon NativeImage (opcional)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (opcional) - O indicador do botão será usado para cancelar o diálogo, por via da tecla Esc. Por padrão é atribuído ao primeiro botão como \"cancelar\" ou \"não\" como rótulos. If no such labeled buttons exist and this option is not set, 0 will be used as the return value.noLink Boolean (opcional) - No Windows, o Electron tentará identificar qual dos buttons são botões comuns (como \"cancelar\" ou \"sim\"), e exibir os outros como links de comandos no diálogo. Ele pode fazer o diálogo ser apresentado com o estilo dos aplicativos modernos do Windows. Se você não deseja esse comportamento, você pode definir noLink para true.normalizeAccessKeys Boolean (opcional) - Normaliza o acesso às teclas do teclado entre as plataformas. Por padrão é false. Ativando-o assume-se que & é usado nos rótulos dos botões para atribuir a tecla de atalho de acesso do teclado assim os rótulos serão convertidos para que funcionem corretamente em cada plataforma, os caracteres & são removidos no macOS, convertidos para _ no Linux, e deixados intactos no Windows. Por exemplo, um rótulo de botão Vie&w será convertido para Vie_w no Linux e View no macOS e pode ser selecionado através de Alt-W no Windows e Linux.Returns Promise<Object> - resolves with a promise containing the following properties:
response Number - The index of the clicked button.checkboxChecked Boolean - The checked state of the checkbox if checkboxLabel was set. Otherwise false.Shows a message box.
\nO argumento browserWindow permite que o diálogo seja acoplado a janela parent, tornando-a modal.
dialog.showErrorBox(title, content)title String - O título a ser exibido na caixa de erro.content String - O conteúdo a ser exibido na caixa de erro.Exibe um dialog modal que apresenta uma mensagem de erro.
\nEsse API pode ser chamado com segurança antes de que o evento ready que é emitido pelo app, é usado para reportar erros nos estágios iniciais da execução do aplicativo. Se chamado antes do evento ready do aplicativo no Linux, a mensagem será emitida para stderr, e o GUI do dialog não será mostrado.
dialog.showCertificateTrustDialog([browserWindow, ]options) macOS WindowsbrowserWindow BrowserWindow)options Objectcertificate Certificate - O certificado para trust/import.message String - A mensagem a ser exibida para o usuário.Returns Promise<void> - resolves when the certificate trust dialog is shown.
No macOS, esse método exibe um dialog modal que apresenta uma mensagem e informação de certificado, dando ao usuário a opção de confiar/importar o certificado. Se você fornecer um argumento browserWindow o dialog será acoplado à janela parent, fazendo-a modal.
No Windows as opções são mais limitadas, devido às API's do Win32 usadas:
\nmessage não é usado.browserWindow é ignorado já que não é possível fazer essa confirmação um diálogo modal.showOpenDialog, showOpenDialogSync, showSaveDialog, and showSaveDialogSync will return a bookmarks array.
| Build Type | securityScopedBookmarks boolean | Return Type | Return Value |
|---|---|---|---|
| macOS mas | True | Sucesso | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | Erro | [''] (array of empty string) |
| macOS mas | False | NA | [] (empty array) |
| non mas | any | NA | [] (empty array) |
On macOS, dialogs are presented as sheets attached to a window if you provide a BrowserWindow reference in the browserWindow parameter, or modals if no window is provided.
Você pode chamar BrowserWindow.getCurrentWindow().setSheetOffset (offset)para mudar o offset da janela aonde os diálogos (sheets) estão acoplados.
id Number - Unique identifier associated with the display.rotation Number - Can be 0, 90, 180, 270, represents screen rotation in clock-wise degrees.scaleFactor Number - Output device's pixel scale factor.touchSupport String - Can be available, unavailable, unknown.monochrome Boolean - Whether or not the display is a monochrome display.accelerometerSupport String - Can be available, unavailable, unknown.colorSpace String - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversionscolorDepth Number - The number of bits per pixel.depthPerComponent Number - The number of bits per color component.displayFrequency Number - The display refresh rate.bounds Rectangle - the bounds of the display in DIP points.size SizeworkArea Rectangle - the work area of the display in DIP points.workAreaSize Sizeinternal Boolean - true for an internal display and false for an external displayThe Display object represents a physical display connected to the system. A fake Display may exist on a headless system, or a Display may correspond to a remote, virtual display.
\n\nControl your app in the macOS dock
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The following example shows how to bounce your icon on the dock.
\nconst { app } = require('electron')\napp.dock.bounce()\ndock.bounce([type]) macOStype String (optional) - Can be critical or informational. The default is informationalReturns Integer - an ID representing the request.
When critical is passed, the dock icon will bounce until either the application becomes active or the request is canceled.
When informational is passed, the dock icon will bounce for one second. However, the request remains active until either the application becomes active or the request is canceled.
Nota Bene: This method can only be used while the app is not focused; when the app is focused it will return -1.
\ndock.cancelBounce(id) macOSid InteiroCancel the bounce of id.
dock.downloadFinished(filePath) no macOSfilePath StringBounces the Downloads stack if the filePath is inside the Downloads folder.
\ndock.setBadge(text) no macOStext StringSets the string to be displayed in the dock’s badging area.
\ndock.getBadge() no macOSReturns String - The badge string of the dock.
dock.hide() no macOSEsconde o ícone na Dock.
\ndock.show() no macOSReturns Promise<void> - Resolves when the dock icon is shown.
dock.isVisible() no macOSReturns Boolean - Whether the dock icon is visible.
dock.setMenu(menu) no macOSmenu MenuSets the application's [dock menu][dock-menu].
\ndock.getMenu() no macOSReturns Menu | null - The application's [dock menu][dock-menu].
dock.setIcon(image) no macOSimage (NativeImage | String)Define a imagem associada com o ícone do dock.
\n\nControla o download de arquivos de fontes remotas.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
DownloadItem is an EventEmitter that represents a download item in Electron. É usado no evento will-download da classe Session, e permite aos usuários controlarem o item de download.
// No processo main.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.session.on('will-download', (event, item, webContents) => {\n // Set the save path, making Electron not to prompt a save dialog.\n item.setSavePath('/tmp/save.pdf')\n\n item.on('updated', (event, state) => {\n if (state === 'interrupted') {\n console.log('Download is interrupted but can be resumed')\n } else if (state === 'progressing') {\n if (item.isPaused()) {\n console.log('Download is paused')\n } else {\n console.log(`Received bytes: ${item.getReceivedBytes()}`)\n }\n }\n })\n item.once('done', (event, state) => {\n if (state === 'completed') {\n console.log('Download successfully')\n } else {\n console.log(`Download failed: ${state}`)\n }\n })\n})\nRetorna:
\nevent Eventstate String - Pode ser progressing ou interrupted.Emitida quando o download foi atualizado e ainda não terminou.
\nstate pode ser um dos seguintes:
progressing - O download está em andamento.interrupted - O download foi interrompido e pode ser retomado.Retorna:
\nevent Eventstate String - Can be completed, cancelled or interrupted.Emitted when the download is in a terminal state. This includes a completed download, a cancelled download (via downloadItem.cancel()), and interrupted download that can't be resumed.
state pode ser um dos seguintes:
completed - The download completed successfully.cancelled - The download has been cancelled.interrupted - The download has interrupted and can not resume.The downloadItem object has the following methods:
downloadItem.setSavePath(path)path String - Set the save file path of the download item.The API is only available in session's will-download callback function. If path doesn't exist, Electron will try to make the directory recursively. If user doesn't set the save path via the API, Electron will use the original routine to determine the save path; this usually prompts a save dialog.
downloadItem.getSavePath()Returns String - The save path of the download item. This will be either the path set via downloadItem.setSavePath(path) or the path selected from the shown save dialog.
downloadItem.setSaveDialogOptions(options)options SaveDialogOptions - Set the save file dialog options. This object has the same properties as the options parameter of dialog.showSaveDialog().This API allows the user to set custom options for the save dialog that opens for the download item by default. The API is only available in session's will-download callback function.
downloadItem.getSaveDialogOptions()Returns SaveDialogOptions - Returns the object previously set by downloadItem.setSaveDialogOptions(options).
downloadItem.pause()Pauses the download.
\ndownloadItem.isPaused()Returns Boolean - Whether the download is paused.
downloadItem.resume()Resumes the download that has been paused.
\nNote: To enable resumable downloads the server you are downloading from must support range requests and provide both Last-Modified and ETag header values. Otherwise resume() will dismiss previously received bytes and restart the download from the beginning.
downloadItem.canResume()Returns Boolean - Whether the download can resume.
downloadItem.cancel()Cancels the download operation.
\ndownloadItem.getURL()Returns String - The origin URL where the item is downloaded from.
downloadItem.getMimeType()Returns String - The files mime type.
downloadItem.hasUserGesture()Returns Boolean - Whether the download has user gesture.
downloadItem.getFilename()Returns String - The file name of the download item.
Note: The file name is not always the same as the actual one saved in local disk. If user changes the file name in a prompted download saving dialog, the actual name of saved file will be different.
\ndownloadItem.getTotalBytes()Returns Integer - The total size in bytes of the download item.
If the size is unknown, it returns 0.
\ndownloadItem.getReceivedBytes()Returns Integer - The received bytes of the download item.
downloadItem.getContentDisposition()Returns String - The Content-Disposition field from the response header.
downloadItem.getState()Returns String - The current state. Can be progressing, completed, cancelled or interrupted.
Note: The following methods are useful specifically to resume a cancelled item when session is restarted.
downloadItem.getURLChain()Returns String[] - The complete URL chain of the item including any redirects.
downloadItem.getLastModifiedTime()Returns String - Last-Modified header value.
downloadItem.getETag()Returns String - ETag header value.
downloadItem.getStartTime()Returns Double - Number of seconds since the UNIX epoch when the download was started.
downloadItem.savePathA String property that determines the save file path of the download item.
The property is only available in session's will-download callback function. If user doesn't set the save path via the property, Electron will use the original routine to determine the save path; this usually prompts a save dialog.
Special notes:
\n-beta.1 and stable dates are our solid release dates.| Electron | Alfa | Beta | Stable | Chrome | Nó |
|---|---|---|---|---|---|
| 2.0.0 | -- | 2018-Feb-21 | 2018-May-01 | M61 | v8.9 |
| 3.0.0 | -- | 2018-Jun-21 | 2018-Sep-18 | M66 | v10.2 |
| 4.0.0 | -- | 2018-Oct-11 | 2018-Dec-20 | M69 | v10.11 |
| 5.0.0 | -- | 2019-Jan-22 | 2019-Apr-24 | M73 | v12.0 |
| 6.0.0 | -- | 2019-May-01 | 2019-Jul-30 | M76 | v12.4 |
| 7.0.0 | -- | 2019-Aug-01 | 2019-Oct-22 | M78 | v12.8 |
| 8.0.0 | -- | 2019-Oct-24 | 2020-Feb-04 | M80 | v12.13 |
| 9.0.0 | -- | 2020-Feb-06 | 2020-May-19 | M83 | v12.14 |
| 10.0.0 | -- | 2020-May-21 | 2020-Aug-25 | M85 | v12.16 |
| 11.0.0 | -- | 2020-Aug-27 | 2020-Nov-17 | M87 | v12.18 |
| 12.0.0 | -- | 2020-Nov-19 | 2021-Mar-02 | M89 | v14.16 |
| 13.0.0 | -- | 2021-Mar-04 | 2021-May-25 | M91 | v14.16 |
| 14.0.0 | -- | 2021-May-27 | 2021-Aug-31 | M93 | v14.17 |
| 15.0.0 | 2021-Jul-20 | 2021-Sep-01 | 2021-Sep-21 | M94 | v16.5 |
| 16.0.0 | -- | 2021-Sep-23 | 2021-Nov-16 | M96 | TBD |
\n\nUma visão detalhada da nossa política de versionamento e implementação.
\n
As of version 2.0.0, Electron follows SemVer. The following command will install the most recent stable build of Electron:
\nnpm install --save-dev electron\nPara atualizar a versão do Electron de um projeto existente para a versão mais recente, use:
\nnpm install --save-dev electron@latest\nElectron versions < 2.0 did not conform to the SemVer spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. Por mais que isso seja conveniente para que desenvolvedores do Electron mesclassem funcionalidades, isso cria problemas para desenvolvedores de aplicativos para o usuário final. Os ciclos de testes de QA de grandes aplicativos como Slack, Stride, Teams, Skype, VS Code, Atom e Desktop podem se tornar demorados, e a estabilidade é um resultado bastante desejado. Existe um alto risco ao se adotar novas funcionalidades ao mesmo tempo em que se tenta absorver correções de bugs.
\nAqui está um exemplo da estratégia da era 1.x:
\n
Um app desenvolvido com o Electron versão 1.8.1 não pode receber as correções de bugs da 1.8.3 sem antes ter que ou absorver a funcionalidade da 1.8.2 ou fazer o backport das correções e manter uma nova linha de lançamento.
There are several major changes from our 1.x strategy outlined below. Each change is intended to satisfy the needs and priorities of developers/maintainers and app developers.
\n-beta em conformidade com o semvermaster não tem versão - apenas as branches de estabilização contêm informações de versãoExplicaremos em detalhes como funcionam o esquema de branches do git, o esquema de tags do npm, o que desenvolvedores devem esperar ver e como é possível fazer o backport de alterações.
\nFrom 2.0 onward, Electron will follow SemVer.
\nBelow is a table explicitly mapping types of changes to their corresponding category of SemVer (e.g. Major, Minor, Patch).
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Major Version Increments | Minor Version Increments | Patch Version Increments |
|---|---|---|
| Electron breaking API changes | Electron non-breaking API changes | Electron bug fixes |
| Node.js major version updates | Node.js minor version updates | Node.js patch version updates |
| Chromium version updates | fix-related chromium patches |
Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
\nStabilization branches are branches that run parallel to master, taking in only cherry-picked commits that are related to security or stability. These branches are never merged back to master.
\n
Since Electron 8, stabilization branches are always major version lines, and named against the following template $MAJOR-x-y e.g. 8-x-y. Prior to that we used minor version lines and named them as $MAJOR-$MINOR-x e.g. 2-0-x
We allow for multiple stabilization branches to exist simultaneously, and intend to support at least two in parallel at all times, backporting security fixes as necessary.
Older lines will not be supported by GitHub, but other groups can take ownership and backport stability and security fixes on their own. We discourage this, but recognize that it makes life easier for many app developers.
\nDevelopers want to know which releases are safe to use. Even seemingly innocent features can introduce regressions in complex applications. At the same time, locking to a fixed version is dangerous because you’re ignoring security patches and bug fixes that may have come out since your version. Our goal is to allow the following standard semver ranges in package.json :
~2.0.0 to admit only stability or security related fixes to your 2.0.0 release.^2.0.0 to admit non-breaking reasonably stable feature work as well as security and bug fixes.What’s important about the second point is that apps using ^ should still be able to expect a reasonable level of stability. To accomplish this, SemVer allows for a pre-release identifier to indicate a particular version is not yet safe or stable.
Whatever you choose, you will periodically have to bump the version in your package.json as breaking changes are a fact of Chromium life.
The process is as follows:
\nbeta.N, e.g. 2.0.0-beta.1. After the first beta, subsequent beta releases must meet all of the following conditions:2.0.0-beta.2.2.0.0. After the first stable, all changes must be backwards-compatible bug or security fixes.2.0.1.Specifically, the above means:
\nFor each major and minor bump, you should expect to see something like the following:
\n2.0.0-beta.1\n2.0.0-beta.2\n2.0.0-beta.3\n2.0.0\n2.0.1\n2.0.2\nAn example lifecycle in pictures:
\n2.0.0-beta.1. 2.0.0-beta.2. 2.0.0. 2-0-x line and release 2.0.1. A few examples of how various SemVer ranges will pick up new releases:
\n
Our strategy has a few tradeoffs, which for now we feel are appropriate. Most importantly that new features in master may take a while before reaching a stable release line. If you want to try a new feature immediately, you will have to build Electron yourself.
\nAs a future consideration, we may introduce one or both of the following:
\nFeature flags are a common practice in Chromium, and are well-established in the web-development ecosystem. In the context of Electron, a feature flag or soft branch must have the following properties:
\nWe seek to increase clarity at all levels of the update and releases process. Starting with 2.0.0 we will require pull requests adhere to the Conventional Commits spec, which can be summarized as follows:
Commits that would result in a SemVer major bump must start their body with BREAKING CHANGE:.
Commits that would result in a SemVer minor bump must start with feat:.
Commits that would result in a SemVer patch bump must start with fix:.
We allow squashing of commits, provided that the squashed message adheres to the above message format.
\nIt is acceptable for some commits in a pull request to not include a semantic prefix, as long as the pull request title contains a meaningful encompassing semantic message.
\nmastermaster branch will always contain the next major version X.0.0-nightly.DATE in its package.jsonpackage.jsonmaster is always versioned as the next theoretical release branchLike NW.js, Electron provides a platform to write desktop applications with web technologies. Both platforms enable developers to utilize HTML, JavaScript, and Node.js. On the surface, they seem very similar.
\nThere are however fundamental differences between the two projects that make Electron a completely separate product from NW.js.
\nIn NW.js, the main entry point of an application can be an HTML web page. In that case, NW.js will open the given entry point in a browser window.
\nIn Electron, the entry point is always a JavaScript script. Instead of providing a URL directly, you manually create a browser window and load an HTML file using the API. You also need to listen to window events to decide when to quit the application.
\nElectron works more like the Node.js runtime. Electron's APIs are lower level so you can use it for browser testing in place of PhantomJS.
\nIn NW.js, the Node integration in web pages requires patching Chromium to work, while in Electron we chose a different way to integrate the libuv loop with each platform's message loop to avoid hacking Chromium. Veja o código do node_bindings para saber como foi feito.
If you are an experienced NW.js user, you should be familiar with the concept of Node context and web context. These concepts were invented because of how NW.js was implemented.
\nBy using the multi-context feature of Node, Electron doesn't introduce a new JavaScript context in web pages.
\nNota: Múltiplos contextos são opcionais no NW.js desde da versão 0.13.
\nNW.js still offers a \"legacy release\" that supports Windows XP. It doesn't receive security updates.
\nGiven that hardware manufacturers, Microsoft, Chromium, and Node.js haven't released even critical security updates for that system, we have to warn you that using Windows XP is wildly insecure and outright irresponsible.
\nHowever, we understand that requirements outside our wildest imagination may exist, so if you're looking for something like Electron that runs on Windows XP, the NW.js legacy release might be the right fit for you.
\nThere are numerous differences in the amount of supported features. Electron has a bigger community, more production apps using it, and a large amount of userland modules available on npm.
\nAs an example, Electron has built-in support for automatic updates and countless tools that make the creation of installers easier. As an example in favor of NW.js, NW.js supports more Chrome.* APIs for the development of Chrome Apps.
Naturally, we believe that Electron is the better platform for polished production applications built with web technologies (like Visual Studio Code, Slack, or Facebook Messenger); however, we want to be fair to our web technology friends. If you have feature needs that Electron does not meet, you might want to try NW.js.
", "title": "Technical Differences Between Electron and NW.js", "description": "" }, "/docs/api/environment-variables": { "locale": "pt-BR", "slug": "environment-variables", "href": "/docs/api/environment-variables", "crowdinFileId": "256315", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/environment-variables.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nControle configurações e comportamento de aplicações sem mudar o código.
\n
Certos comportamentos do Electron são controlados por variáveis de ambientes porque são inicializados antes que as flags da linha de comando e o código da aplicação.
\nExemplo de shell POSIX:
\n$ export ELECTRON_ENABLE_LOGGING=true\n$ electron\nExemplo de console do Windows:
\n> set ELECTRON_ENABLE_LOGGING=true\n> electron\nThe following environment variables are intended primarily for use at runtime in packaged Electron applications.
\nNODE_OPTIONSElectron includes support for a subset of Node's NODE_OPTIONS. The majority are supported with the exception of those which conflict with Chromium's use of BoringSSL.
Exemplo:
\nexport NODE_OPTIONS=\"--no-warnings --max-old-space-size=2048\"\nUnsupported options are:
\n--use-bundled-ca\n--force-fips\n--enable-fips\n--openssl-config\n--use-openssl-ca\nNODE_OPTIONS are explicitly disallowed in packaged apps, except for the following:
--max-http-header-size\n--http-parser\nGOOGLE_API_KEYGeolocation support in Electron requires the use of Google Cloud Platform's geolocation webservice. To enable this feature, acquire a Google API key and place the following code in your main process file, before opening any browser windows that will make geolocation requests:
\nprocess.env.GOOGLE_API_KEY = 'YOUR_KEY_HERE'\nBy default, a newly generated Google API key may not be allowed to make geolocation requests. To enable the geolocation webservice for your project, enable it through the API library.
\nN.B. You will need to add a Billing Account to the project associated to the API key for the geolocation webservice to work.
\nELECTRON_NO_ASARDisables ASAR support. This variable is only supported in forked child processes and spawned child processes that set ELECTRON_RUN_AS_NODE.
ELECTRON_RUN_AS_NODEStarts the process as a normal Node.js process.
\nIn this mode, you will be able to pass cli options to Node.js as you would when running the normal Node.js executable, with the exception of the following flags:
\nThese flags are disabled owing to the fact that Electron uses BoringSSL instead of OpenSSL when building Node.js' crypto module, and so will not work as designed.
ELECTRON_NO_ATTACH_CONSOLE WindowsDon't attach to the current console session.
\nELECTRON_FORCE_WINDOW_MENU_BAR LinuxDon't use the global menu bar on Linux.
\nELECTRON_TRASH LinuxSet the trash implementation on Linux. Por padrão é gio.
Opções:
\ngvfs-trashtrash-clikioclient5kioclientAs seguintes variáveis de ambiente são destinadas principalmente para fins de depuração e desenvolvimento.
\nELECTRON_ENABLE_LOGGINGPrints Chromium's internal logging to the console.
\nSetting this variable is the same as passing --enable-logging on the command line. For more info, see --enable-logging in command-line switches.
ELECTRON_LOG_FILESets the file destination for Chromium's internal logging.
\nSetting this variable is the same as passing --log-file on the command line. For more info, see --log-file in command-line switches.
ELECTRON_DEBUG_DRAG_REGIONSAdds coloration to draggable regions on BrowserViews on macOS - draggable regions will be colored green and non-draggable regions will be colored red to aid debugging.
ELECTRON_DEBUG_NOTIFICATIONSAdds extra logs to Notification lifecycles on macOS to aid in debugging. Extra logging will be displayed when new Notifications are created or activated. They will also be displayed when common a tions are taken: a notification is shown, dismissed, its button is clicked, or it is replied to.
Sample output:
\nNotification created (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification displayed (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification activated (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification replied to (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nELECTRON_LOG_ASAR_READSWhen Electron reads from an ASAR file, log the read offset and file path to the system tmpdir. The resulting file can be provided to the ASAR module to optimize file ordering.
ELECTRON_ENABLE_STACK_DUMPINGImprime o rastreamento da pilha para o console quando o Electron trava.
\nEssa variável de ambiente não funcionará se o crashReporter tiver iniciado.
ELECTRON_DEFAULT_ERROR_MODE WindowsMostra a caixa de diálogo de travamento do Windows quando o Electron trava.
\nEssa variável de ambiente não funcionará se o crashReporter tiver iniciado.
ELECTRON_OVERRIDE_DIST_PATHWhen running from the electron package, this variable tells the electron command to use the specified build of Electron instead of the one downloaded by npm install. Usando:
export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing\nElectron sets some variables in your environment at runtime.
\nORIGINAL_XDG_CURRENT_DESKTOPThis variable is set to the value of XDG_CURRENT_DESKTOP that your application originally launched with. Electron sometimes modifies the value of XDG_CURRENT_DESKTOP to affect other logic within Chromium so if you want access to the original value you should look up this environment variable instead.
GlobalEventpreventDefault VoidFunctionSome of Electrons APIs are tagged with _Experimental_ in the documentation. This tag indicates that the API may not be considered stable and the API may be removed or modified more frequently than other APIs with less warning.
Anyone can request an API be tagged as experimental in a feature PR, disagreements on the experimental nature of a feature can be discussed in the API WG if they can't be resolved in the PR.
\nOnce an API has been stable and in at least two major stable release lines it can be nominated to have its experimental tag removed. This discussion should happen at an API WG meeting. Things to consider when discussing / nominating:
\nid Stringmanifest any - Copy of the extension's manifest data.name Stringpath String - The extension's file path.version Stringurl String - The extension's chrome-extension:// URL.name Stringversion StringElectron supports a subset of the Chrome Extensions API, primarily to support DevTools extensions and Chromium-internal extensions, but it also happens to support some other extension capabilities.
\n\n\nNote: Electron does not support arbitrary Chrome extensions from the store, and it is a non-goal of the Electron project to be perfectly compatible with Chrome's implementation of Extensions.
\n
Electron only supports loading unpacked extensions (i.e., .crx files do not work). Extensions are installed per-session. To load an extension, call ses.loadExtension:
const { session } = require('electron')\n\nsession.loadExtension('path/to/unpacked/extension').then(({ id }) => {\n // ...\n})\nLoaded extensions will not be automatically remembered across exits; if you do not call loadExtension when the app runs, the extension will not be loaded.
Note that loading extensions is only supported in persistent sessions. Attempting to load an extension into an in-memory session will throw an error.
\nSee the session documentation for more information about loading, unloading, and querying active extensions.
We support the following extensions APIs, with some caveats. Other APIs may additionally be supported, but support for any APIs not listed here is provisional and may be removed.
\nchrome.devtools.inspectedWindowAll features of this API are supported.
\nchrome.devtools.networkAll features of this API are supported.
\nchrome.devtools.panelsAll features of this API are supported.
\nchrome.extensionThe following properties of chrome.extension are supported:
chrome.extension.lastErrorThe following methods of chrome.extension are supported:
chrome.extension.getURLchrome.extension.getBackgroundPagechrome.runtimeThe following properties of chrome.runtime are supported:
chrome.runtime.lastErrorchrome.runtime.idThe following methods of chrome.runtime are supported:
chrome.runtime.getBackgroundPagechrome.runtime.getManifestchrome.runtime.getPlatformInfochrome.runtime.getURLchrome.runtime.connectchrome.runtime.sendMessagechrome.runtime.reloadThe following events of chrome.runtime are supported:
chrome.runtime.onStartupchrome.runtime.onInstalledchrome.runtime.onSuspendchrome.runtime.onSuspendCanceledchrome.runtime.onConnectchrome.runtime.onMessagechrome.storageOnly chrome.storage.local is supported; chrome.storage.sync and chrome.storage.managed are not.
chrome.tabsThe following methods of chrome.tabs are supported:
chrome.tabs.sendMessagechrome.tabs.executeScript\n\nNote: In Chrome, passing
\n-1as a tab ID signifies the \"currently active tab\". Since Electron has no such concept, passing-1as a tab ID is not supported and will raise an error.
chrome.managementThe following methods of chrome.management are supported:
chrome.management.getAllchrome.management.getchrome.management.getSelfchrome.management.getPermissionWarningsByIdchrome.management.getPermissionWarningsByManifestchrome.management.onEnabledchrome.management.onDisabledchrome.webRequestAll features of this API are supported.
\n\n", "title": "Chrome Extension Support", "description": "Note: Electron does not support arbitrary Chrome extensions from the store, and it is a non-goal of the Electron project to be perfectly compatible with Chrome's implementation of Extensions." }, "/docs/faq": { "locale": "pt-BR", "slug": "faq", "href": "/docs/faq", "crowdinFileId": "256121", "githubUrl": "https://github.com/electron/electron/tree/main/docs/faq.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "NOTE: Electron's
\nwebRequestmodule takes precedence overchrome.webRequestif there are conflicting handlers.
Ao executar o npm install electron, alguns usuários encontram erros de instalação.
Em quase todos os casos, esses problemas são resultado de problemas de rede e não de problemas reais com o pacote npm electron. Erros como ELIFECYCLE, EAI_AGAIN, ECONNRESET, e ETIMEDOUT são resultados da falta de internet. A melhor solução é tentar trocar de rede, ou aguardar um pouco e tentar instalar novamente.
Se a instalação via npm falhar, você também pode tentar baixar o Electron diretamente do código fonte em electron/electron/releases.
A versão do Chrome utilizada no Electron normalmente é disponibilizada dentro de uma ou duas semanas depois que uma versão estável do Chrome é liberada. Esta estimativa não é garantida, depende da quantidade de trabalho envolvido na atualização.
\nSomente a versão estável do Chrome é usada. If an important fix is in beta or dev channel, we will back-port it.
\nPara mais informações, consulte a introdução de segurança.
\nQuando uma nova versão do Node.js é lançada, geralmente esperamos por cerca de um mês antes de atualizar a do Electron. Assim, podemos evitar sermos afetados por erros introduzidos na nova versão do Node.js, o que acontece muito frequentemente.
\nNovos recursos do Node.js geralmente são trazidos por atualização da V8, desde que o Electron usa o V8 enviado pelo navegador Chrome. Os novos recursos brilhante do JavaScript de uma nova versão Node.js esta geralmente no Electron.
\nPara compartilhar dados entre páginas web (os processos de renderização) a maneira mais simples é usar as APIs do HTML5 que já estão disponíveis nos navegadores. Good candidates are Storage API, localStorage, sessionStorage, and IndexedDB.
Alternatively, you can use the IPC primitives that are provided by Electron. To share data between the main and renderer processes, you can use the ipcMain and ipcRenderer modules. To communicate directly between web pages, you can send a MessagePort from one to the other, possibly via the main process using ipcRenderer.postMessage(). Subsequent communication over message ports is direct and does not detour through the main process.
Isto acontece quando a variável que é usada para armazenar a bandeja é coletada pelo garbage collector.
\nSe você encontrar esse problema, esses artigos podem ser úteis:
\n\nSe você quer uma solução rápida, você pode fazer as variáveis globais, alterando seu código:
\nconst { app, Tray } = require('electron')\napp.whenReady().then(() =>{\n const tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\npara isto:
\nconst { app, Tray } = require('electron')\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/icon.png')\n tray.setTitle('hello world')\n})\nDevido à integração de Node.js do Electron, existem alguns símbolos extras inseridos o DOM como module, exports e require. Isso causa problemas por causa de algumas bibliotecas que querem inserir os símbolos com os mesmos nomes.
Para resolver isso, você pode desativar a integração com node no Electron:
\n// No processo main.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n webPreferences: {\n nodeIntegration: false\n }\n})\nwin.show()\nMas se você quer manter as habilidades de usar Node.JS e Electron APIs, você tem que renomear os símbolos na página, antes de incluir outras bibliotecas:
\n<head>\n<script>\nwindow.nodeRequire = require;\ndelete window.require;\ndelete window.exports;\ndelete window.module;\n</script>\n<script type=\"text/javascript\" src=\"jquery.js\"></script>\n</head>\nrequire('electron').xxx é indefinido.Quando usar o módulo built-in do Electron você pode encontrar um erro como este:
\n> require('electron').webFrame.setZoomFactor(1.0)\nUncaught TypeError: Cannot read property 'setZoomLevel' of undefined\nÉ bem provável que você esteja utilizando o módulo no processo errado. Por exemplo, electron.app pode apenas ser usado pelo processo principal, enquanto electron.webFrame está apenas disponível no processo de renderização.
If sub-pixel anti-aliasing is deactivated, then fonts on LCD screens can look blurry. Exemplo:
\n
A anti-aliasing de sub-pixel precisa de um fundo não transparente na camada que contem os glyphs de texto. (Veja esta publicação para mais informações).
\nTo achieve this goal, set the background in the constructor for BrowserWindow:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n backgroundColor: '#fff'\n})\nThe effect is visible only on (some?) LCD screens. Even if you don't see a difference, some of your users may. It is best to always set the background this way, unless you have reasons not to do so.
\nAviso que apenas definir o background no CSS não tem o mesmo efeito desejado.
", "title": "Perguntas Frequentes no Electron", "description": "" }, "/docs/api/structures/file-filter": { "locale": "pt-BR", "slug": "file-filter", "href": "/docs/api/structures/file-filter", "crowdinFileId": "256435", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/file-filter.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "name Stringextensions String[]File Object\n\nUse a API do HTML5
\nFilepara funcionar nativamente com arquivos no sistema de arquivos.
The DOM's File interface provides abstraction around native files in order to let users work on native files directly with the HTML5 file API. Electron has added a path attribute to the File interface which exposes the file's real path on filesystem.
Example of getting a real path from a dragged-onto-the-app file:
\n<div id=\"holder\">\n Drag your file here\n</div>\n\n<script>\n document.addEventListener('drop', (e) => {\n e.preventDefault();\n e.stopPropagation();\n\n for (const f of e.dataTransfer.files) {\n console.log('File(s) you dragged here: ', f.path)\n }\n });\n document.addEventListener('dragover', (e) => {\n e.preventDefault();\n e.stopPropagation();\n });\n</script>\npath String - The path to the file to send.headers Record<string, string> (optional) - Additional headers to be sent.\n\nAbra uma janela sem barra de ferramentas, bordas ou outros elementos gráficos do \"Chrome\".
\n
Uma janela 'frameless' é uma janela que não possui chrome, ou seja, não possui partes da janela que não são partes da página web, como a barra de ferramentas. Estas são opções na classe BrowserWindow.
Para criar uma frameless window, você precisa definir frame como false nas options da BrowserWindow:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600, frame: false })\nwin.show()\nThere's an alternative way to specify a chromeless window on macOS and Windows. Instead of setting frame to false which disables both the titlebar and window controls, you may want to have the title bar hidden and your content extend to the full window size, yet still preserve the window controls (\"traffic lights\" on macOS) for standard window actions. Você pode fazê-lo, especificando a opção titleBarStyle:
hiddenResults in a hidden title bar and a full size content window. On macOS, the title bar still has the standard window controls (“traffic lights”) in the top left.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hidden' })\nwin.show()\nhiddenInsetResulta em uma barra de título escondida com uma aparência alternativa, onde os botões de controle da janela estão um pouco mais dentro do limite da janela.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })\nwin.show()\ncustomButtonsOnHoverUses custom drawn close, and miniaturize buttons that display when hovering in the top left of the window. The fullscreen button is not available due to restrictions of frameless windows as they interface with Apple's macOS window masks. These custom buttons prevent issues with mouse events that occur with the standard window toolbar buttons. This option is only applicable for frameless windows.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover', frame: false })\nwin.show()\nWhen using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS, using one of the titleBarStyles as described above so that the traffic lights are visible, or using titleBarStyle: hidden on Windows, you can access the Window Controls Overlay JavaScript APIs and CSS Environment Variables by setting the titleBarOverlay option to true. Specifying true will result in an overlay with default system colors.
On Windows, you can also specify the color of the overlay and its symbols by setting titleBarOverlay to an object with the options color and symbolColor. If an option is not specified, the color will default to its system color for the window control buttons:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: true\n})\nwin.show()\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: {\n color: '#2f3241',\n symbolColor: '#74b1be'\n }\n})\nwin.show()\nDefinindo a opção transparent como true você também pode fazer a frameless window transparente:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ transparent: true, frame: false })\nwin.show()\nresizable to true may make a transparent window stop working on some platforms.blur apenas se aplica a página web, logo, não há uma maneira de aplicar o efeito de borrado ao conteúdo abaixo da janela (ou seja, outras aplicações abertas no sistema do usuário).--enable-transparent-visuals --disable-gpu in the command line to disable GPU and allow ARGB to make transparent window, this is caused by an upstream bug that alpha channel doesn't work on some NVidia drivers on Linux.To create a click-through window, i.e. making the window ignore all mouse events, you can call the win.setIgnoreMouseEvents(ignore) API:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.setIgnoreMouseEvents(true)\nIgnoring mouse messages makes the web page oblivious to mouse movement, meaning that mouse movement events will not be emitted. On Windows operating systems an optional parameter can be used to forward mouse move messages to the web page, allowing events such as mouseleave to be emitted:
const { ipcRenderer } = require('electron')\nconst el = document.getElementById('clickThroughElement')\nel.addEventListener('mouseenter', () => {\n ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })\n})\nel.addEventListener('mouseleave', () => {\n ipcRenderer.send('set-ignore-mouse-events', false)\n})\n\n// Main process\nconst { ipcMain } = require('electron')\nipcMain.on('set-ignore-mouse-events', (event, ...args) => {\n BrowserWindow.fromWebContents(event.sender).setIgnoreMouseEvents(...args)\n})\nThis makes the web page click-through when over el, and returns to normal outside it.
By default, the frameless window is non-draggable. Apps need to specify -webkit-app-region: drag in CSS to tell Electron which regions are draggable (like the OS's standard titlebar), and apps can also use -webkit-app-region: no-drag to exclude the non-draggable area from the draggable region. Note that only rectangular shapes are currently supported.
Note: -webkit-app-region: drag is known to have problems while the developer tools are open. See this GitHub issue for more information including a workaround.
To make the whole window draggable, you can add -webkit-app-region: drag as body's style:
<body style=\"-webkit-app-region: drag\">\n</body>\nAnd note that if you have made the whole window draggable, you must also mark buttons as non-draggable, otherwise it would be impossible for users to click on them:
\nbutton {\n -webkit-app-region: no-drag;\n}\nIf you're only setting a custom titlebar as draggable, you also need to make all buttons in titlebar non-draggable.
\nIn a frameless window the dragging behavior may conflict with selecting text. For example, when you drag the titlebar you may accidentally select the text on the titlebar. To prevent this, you need to disable text selection within a draggable area like this:
\n.titlebar {\n -webkit-user-select: none;\n -webkit-app-region: drag;\n}\nOn some platforms, the draggable area will be treated as a non-client frame, so when you right click on it a system menu will pop up. To make the context menu behave correctly on all platforms you should never use a custom context menu on draggable areas.
", "title": "Frameless Window", "description": "Abra uma janela sem barra de ferramentas, bordas ou outros elementos gráficos do \"Chrome\"." }, "/docs/tutorial/fuses": { "locale": "pt-BR", "slug": "fuses", "href": "/docs/tutorial/fuses", "crowdinFileId": "256201", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/fuses.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nPackage time feature toggles
\n
For a subset of Electron functionality it makes sense to disable certain features for an entire application. For example, 99% of apps don't make use of ELECTRON_RUN_AS_NODE, these applications want to be able to ship a binary that is incapable of using that feature. We also don't want Electron consumers building Electron from source as that is both a massive technical challenge and has a high cost of both time and money.
Fuses are the solution to this problem, at a high level they are \"magic bits\" in the Electron binary that can be flipped when packaging your Electron app to enable / disable certain features / restrictions. Because they are flipped at package time before you code sign your app the OS becomes responsible for ensuring those bits aren't flipped back via OS level code signing validation (Gatekeeper / App Locker).
\nWe've made a handy module @electron/fuses to make flipping these fuses easy. Check out the README of that module for more details on usage and potential error cases.
require('@electron/fuses').flipFuses(\n // Path to electron\n require('electron'),\n // Fuses to flip\n {\n runAsNode: false\n }\n)\nManually flipping fuses requires editing the Electron binary and modifying the fuse wire to be the sequence of bytes that represent the state of the fuses you want.
\nSomewhere in the Electron binary there will be a sequence of bytes that look like this:
\n| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |\nsentinel_bytes is always this exact string dL7pKGdnNz796PbbjQWNKmHXBZaB9tsXfuse_version is a single byte whose unsigned integer value represents the version of the fuse schemafuse_wire_length is a single byte whose unsigned integer value represents the number of fuses in the following fuse wirefuse_wire is a sequence of N bytes, each byte represents a single fuse and its state.To flip a fuse you find its position in the fuse wire and change it to \"0\" or \"1\" depending on the state you'd like.
\nYou can view the current schema here.
", "title": "Electron Fuses", "description": "Package time feature toggles" }, "/docs/api/global-shortcut": { "locale": "pt-BR", "slug": "global-shortcut", "href": "/docs/api/global-shortcut", "crowdinFileId": "256323", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/global-shortcut.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nDetecta eventos de teclado quando o aplicativo não tiver o foco do teclado.
\n
Processo: Main
\nO módulo globalShortcut pode registrar/cancelar o registro de um atalho de teclado global com o sistema operativo que você possa personalizar as operações para os vários atalhos.
Nota: O atalho é global; Isso funcionará mesmo se o aplicativo não tenha o foco do teclado. This module cannot be used before the ready event of the app module is emitted.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+X' shortcut listener.\n const ret = globalShortcut.register('CommandOrControl+X', () => {\n console.log('CommandOrControl+X is pressed')\n })\n\n if (!ret) {\n console.log('registration failed')\n }\n\n // Check whether a shortcut is registered.\n console.log(globalShortcut.isRegistered('CommandOrControl+X'))\n})\n\napp.on('will-quit', () => {\n // Unregister a shortcut.\n globalShortcut.unregister('CommandOrControl+X')\n\n // Unregister all shortcuts.\n globalShortcut.unregisterAll()\n})\nO módulo globalShortcut tem os seguintes métodos:
globalShortcut.register(accelerator, callback)accelerator Acceleratorcallback FunctionReturns Boolean - Whether or not the shortcut was registered successfully.
Registers a global shortcut of accelerator. The callback is called when the registered shortcut is pressed by the user.
Quando o acelerador já está sendo utilizado por outras aplicações, esta chamada falhará silenciosamente. Este comportamento é pretendido pelos sistemas operacionais, uma vez que eles não querem que os aplicativos lutem por atalhos globais.
\nThe following accelerators will not be registered successfully on macOS 10.14 Mojave unless the app has been authorized as a trusted accessibility client:
\nglobalShortcut.registerAll(accelerators, callback)accelerators String[] - an array of Accelerators.callback FunctionRegisters a global shortcut of all accelerator items in accelerators. The callback is called when any of the registered shortcuts are pressed by the user.
When a given accelerator is already taken by other applications, this call will silently fail. Este comportamento é pretendido pelos sistemas operacionais, uma vez que eles não querem que os aplicativos lutem por atalhos globais.
\nThe following accelerators will not be registered successfully on macOS 10.14 Mojave unless the app has been authorized as a trusted accessibility client:
\nglobalShortcut.isRegistered(accelerator)accelerator AcceleratorRetorna Boolean - Se esta aplicação registrou o accelerator.
Quando o acelerador já está sendo utilizado por outras aplicações, esta ainda retorna false. Este comportamento é pretendido pelos sistemas operacionais, uma vez que eles não querem que os aplicativos lutem por atalhos globais.
globalShortcut.unregister(accelerator)accelerator AcceleratorNão registra o atalho global de accelerator.
globalShortcut.unregisterAll()Não registra todos os atalhos globais.
", "title": "globalShortcut", "description": "Detecta eventos de teclado quando o aplicativo não tiver o foco do teclado." }, "/docs/glossary": { "locale": "pt-BR", "slug": "glossary", "href": "/docs/glossary", "crowdinFileId": "256123", "githubUrl": "https://github.com/electron/electron/tree/main/docs/glossary.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Esta página define alguns termos usados frequentemente no desenvolvimento com Electron.
\nASAR significa formato de arquivo Atom Shell (em inglês, Atom Shell Archive Format). Um arquivo de asar é um simples tar formato que juntas os arquivos para um único arquivo. Electron pode ler arquivos arbitrários sem descompactar o arquivo inteiro.
The ASAR format was created primarily to improve performance on Windows when reading large quantities of small files (e.g. when loading your app's JavaScript dependency tree from node_modules).
Code signing is a process where an app developer digitally signs their code to ensure that it hasn't been tampered with after packaging. Both Windows and macOS implement their own version of code signing. As a desktop app developer, it's important that you sign your code if you plan on distributing it to the general public.
\nFor more information, read the Code Signing tutorial.
\nContext isolation is a security measure in Electron that ensures that your preload script cannot leak privileged Electron or Node.js APIs to the web contents in your renderer process. With context isolation enabled, the only way to expose APIs from your preload script is through the contextBridge API.
For more information, read the Context Isolation tutorial.
\nSee also: preload script, renderer process
\nThe C Runtime Library (CRT) is the part of the C++ Standard Library that incorporates the ISO C99 standard library. As bibliotecas do Visual C++ que implementam o CRT apoiar o desenvolvimento de código nativo e misto de código nativo e gerenciado e código gerenciado puro para desenvolvimento .NET.
\nUma imagem de disco da Apple é um formato de embalagem usado pelo macOS. DMG arquivos são componentes usados para distribuir um aplicativo \"instaladores\".
\nEditor de Método de Entrada. Um programa que permite os usuários inserir caracteres e símbolos não encontrados no seu teclado. Por exemplo, isso permite que usuários com teclado Latinos teclados troque as entradas de caracteres para Chinês, Japonês e Koreano.
\nInterface description language. Write function signatures and data types in a format that can be used to generate interfaces in Java, C++, JavaScript, etc.
\nIPC stands for inter-process communication. Electron uses IPC to send serialized JSON messages between the main and renderer processes.
\nconsulte também: processo principal, processo de processador
\nThe main process, commonly a file named main.js, is the entry point to every Electron app. It controls the life of the app, from open to close. Isso também é gerencia elementos nativos, como o Menu, Barra de Menus, Dock, Bandeja e etc. The main process is responsible for creating each new renderer process in the app. The full Node API is built in.
Every app's main process file is specified in the main property in package.json. This is how electron . knows what file to execute at startup.
In Chromium, this process is referred to as the \"browser process\". It is renamed in Electron to avoid confusion with renderer processes.
\nConsulte também: processo, processo de processador
\nAcronym for Apple's Mac App Store. For details on submitting your app to the MAS, see the Mac App Store Submission Guide.
\nAn IPC system for communicating intra- or inter-process, and that's important because Chrome is keen on being able to split its work into separate processes or not, depending on memory pressures etc.
\nVeja https://chromium.googlesource.com/chromium/src/+/master/mojo/README.md
\nSee also: IPC
\nOn Windows, MSI packages are used by the Windows Installer (also known as Microsoft Installer) service to install and configure applications.
\nMore information can be found in Microsoft's documentation.
\nMódulos nativos (também chamados addons em Node.Js) são módulos escritos em C ou C++ que pode ser carregado em Node.js ou Electron usando a função require() e fazer o uso de modo como se fossem um módulo comum de Node.js. Eles são usados principalmente para fornecer uma interface entre o JavaScript em execução em bibliotecas de Node.js e C/C++.
\nOs módulos nativos do Node são suportados pelo Electron, mas considerando que o Electron provavelmente irá utilizar uma versão do V8 dos binários do Node instalados no seu sistema, você deve especificar manualmente a localização dos headers do Electron quando for copilar módulos nativos.
\nFor more information, read the [Native Node Modules] tutorial.
\nNotarization is a macOS-specific process where a developer can send a code-signed app to Apple servers to get verified for malicious components through an automated service.
\nSee also: code signing
\nOSR (offscreen rendering) can be used for loading heavy page in background and then displaying it after (it will be much faster). It allows you to render page without showing it on screen.
\nFor more information, read the Offscreen Rendering[osr] tutorial.
\nPreload scripts contain code that executes in a renderer process before its web contents begin loading. These scripts run within the renderer context, but are granted more privileges by having access to Node.js APIs.
\nSee also: renderer process, context isolation
\nUm processo é uma instância de um programa de computador que está sendo executado. Apps de Electron que fazem usam do main e um ou vários processo de renderer estão executando vários programas simultaneamente.
\nEm Node.js e Electron, cada processo em execução tem um objeto de process. Este objeto é um global que fornece informações sobre e controle sobre, o atual processo. Como um global, é sempre disponível para aplicações sem o uso de require().
Consulte também: processo principal, processo de processador
\nThe renderer process is a browser window in your app. Unlike the main process, there can be multiple of these and each is run in a separate process. They can also be hidden.
\nConsulte também: process, main process
\nThe sandbox is a security feature inherited from Chromium that restricts your renderer processes to a limited set of permissions.
\nFor more information, read the Process Sandboxing tutorial.
\nSee also: process
\nSquirrel é um framework de código aberto que permite que aplicativos de elétron atualizar automaticamente como novas versões são lançadas. Consulte o autoUpdater API para obter informações sobre como começar com o Squirrel.
\nEste termo originou-se da comunidade Unix, onde \"userland\" ou \"userspace\" refere-se a programas que são executados fora da kernel do sistema operacional. Mais recentemente, o termo foi popularizado na comunidade Node e npm para distinguir entre os recursos disponíveis em \"Node core\" de pacotes publicados no registro do npm pela maior comunidade \"usuários\".
\nComo Node, o Electron é focado em ter um pequeno conjunto de APIs que fornecem todos os primitivos necessários para o desenvolvimento de aplicativos de multi-plataformas desktop. Esta filosofia do projeto permite que o Electron permaneça uma ferramenta flexível sem ser excessivamente prescritiva sobre como deve ser usado. Userland permite que os usuários criar e compartilhar ferramentas que fornecem funcionalidade adicional em cima do que é disponível no \"Núcleo\".
\nV8 is Google's open source JavaScript engine. It is written in C++ and is used in Google Chrome. V8 can run standalone, or can be embedded into any C++ application.
\nElectron forma o V8 como parte do Chromium e em seguida, aponta o Node ao V8 quando construindo.
\nV8's version numbers always correspond to those of Google Chrome. Chrome 59 includes V8 5.9, Chrome 58 includes V8 5.8, etc.
\n\nwebview tags are used to embed 'guest' content (such as external web pages) in your Electron app. They are similar to iframes, but differ in that each webview runs in a separate process. Ele não tem a mesma permissões como sua página web e todas as interações entre seu aplicativo e conteúdo incorporado será assíncrono. Isso mantém seu aplicativo seguro do conteúdo incorporado.
\n\nGoma é um serviço distribuído de compilador para projetos open-source como Chromium e Android.
\n
O Electron possui uma implantação de um Backend Goma personalizado que nós deixamos disponível para todos que fazem a manutenção do Electron. Veja a seção Acesso abaixo para detalhes sobre autenticação. Existe também um endpoint Goma cache-only que será usado por padrão caso você não tenha credenciais. Requisições para o cache-only Goma não chamará nosso cluster, mas lerá do nosso cache, o que deve resultar em tempos de build significativamente mais rápidos.
Atualmente, a única maneira suportada de utilizar o Goma é usando nossas Ferramentas de Construção. Uma configuração do Goma é automaticamente incluída quando você configurar as build-tools.
If you are a maintainer and have access to our cluster, please ensure that you run e init with --goma=cluster in order to configure build-tools to use the Goma cluster. If you have an existing config, you can just set \"goma\": \"cluster\" in your config file.
When you are using Goma you can run ninja with a substantially higher j value than would normally be supported by your machine.
Please do not set a value higher than 200 on Windows or Linux and 50 on macOS. We monitor Goma system usage, and users found to be abusing it with unreasonable concurrency will be de-activated.
\nninja -C out/Testing electron -j 200\nIf you're using build-tools, appropriate -j values will automatically be used for you.
If you access http://localhost:8088 on your local machine you can monitor compile jobs as they flow through the goma system.
\nFor security and cost reasons, access to Electron's Goma cluster is currently restricted to Electron Maintainers. If you want access please head to #access-requests in Slack and ping @goma-squad to ask for access. Please be aware that being a maintainer does not automatically grant access and access is determined on a case by case basis.
We have automated monitoring of our Goma cluster and cache at https://status.notgoma.com
\nWe do not provide support for usage of Goma and any issues raised asking for help / having issues will probably be closed without much reason, we do not have the capacity to handle that kind of support.
", "title": "Goma", "description": "Goma é um serviço distribuído de compilador para projetos open-source como Chromium e Android." }, "/docs/api/structures/gpu-feature-status": { "locale": "pt-BR", "slug": "gpu-feature-status", "href": "/docs/api/structures/gpu-feature-status", "crowdinFileId": "256439", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/gpu-feature-status.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "2d_canvas String - Canvas.flash_3d String - Flash.flash_stage3d String - Flash Stage3D.flash_stage3d_baseline String - Flash Stage3D Baseline profile.gpu_compositing String - Compositing.multiple_raster_threads String - Multiple Raster Threads.native_gpu_memory_buffers String - Native GpuMemoryBuffers.rasterization String - Rasterization.video_decode String - Video Decode.video_encode String - Video Encode.vpx_decode String - VPx Video Decode.webgl String - WebGL.webgl2 String - WebGL2.Valores possíveis:
\ndisabled_software - Software only. Hardware acceleration disabled (yellow)disabled_off - Disabled (red)disabled_off_ok - Disabled (yellow)unavailable_software - Software only, hardware acceleration unavailable (yellow)unavailable_off - Unavailable (red)unavailable_off_ok - Unavailable (yellow)enabled_readback - Hardware accelerated but at reduced performance (yellow)enabled_force - Hardware accelerated on all pages (green)enabled - Hardware accelerated (green)enabled_on - Enabled (green)enabled_force_on - Force enabled (green)deviceId String - Unique identifier for the device.name String - Name of the device.vendorId Integer - The USB vendor ID.productId Integer - The USB product ID.serialNumber String (optional) - The USB device serial number.guid String (optional) - Unique identifier for the HID interface. A device may have multiple HID interfaces.\n\nIn-app purchases on Mac App Store.
\n
Processo: Main
\nO módulo inAppPurchase emite os seguintes eventos:
Emitted when one or more transactions have been updated.
\nRetorna:
\nevent Eventtransactions Transaction[] - Array of Transaction objects.O módulo inAppPurchase tem os seguintes métodos:
inAppPurchase.purchaseProduct(productID[, quantity])productID String - The identifiers of the product to purchase. (The identifier of com.example.app.product1 is product1).quantity Integer (optional) - The number of items the user wants to purchase.Returns Promise<Boolean> - Returns true if the product is valid and added to the payment queue.
You should listen for the transactions-updated event as soon as possible and certainly before you call purchaseProduct.
inAppPurchase.getProducts(productIDs)productIDs String[] - The identifiers of the products to get.Returns Promise<Product[]> - Resolves with an array of Product objects.
Retrieves the product descriptions.
\ninAppPurchase.canMakePayments()Returns Boolean - whether a user can make a payment.
inAppPurchase.restoreCompletedTransactions()Restores finished transactions. This method can be called either to install purchases on additional devices, or to restore purchases for an application that the user deleted and reinstalled.
\nThe payment queue delivers a new transaction for each previously completed transaction that can be restored. Each transaction includes a copy of the original transaction.
\ninAppPurchase.getReceiptURL()Returns String - the path to the receipt.
inAppPurchase.finishAllTransactions()Completes all pending transactions.
\ninAppPurchase.finishTransactionByDate(date)date String - The ISO formatted date of the transaction to finish.Completes the pending transactions corresponding to the date.
", "title": "inAppPurchase", "description": "In-app purchases on Mac App Store." }, "/docs/tutorial/in-app-purchases": { "locale": "pt-BR", "slug": "in-app-purchases", "href": "/docs/tutorial/in-app-purchases", "crowdinFileId": "256203", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/in-app-purchases.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Se você ainda não o fez, precisará assinar o Contrato de aplicativos pagos e configurar suas informações bancárias e fiscais no iTunes Connect.
\nAjuda do desenvolvedor do iTunes Connect: Visão geral de contratos, impostos e serviços bancários
\nThen, you'll need to configure your in-app purchases in iTunes Connect, and include details such as name, pricing, and description that highlights the features and functionality of your in-app purchase.
\niTunes Connect Developer Help: Create an in-app purchase
\nTo test In-App Purchase in development with Electron you'll have to change the CFBundleIdentifier in node_modules/electron/dist/Electron.app/Contents/Info.plist. You have to replace com.github.electron by the bundle identifier of the application you created with iTunes Connect.
<key>CFBundleIdentifier</key>\n<string>com.example.app</string>\nHere is an example that shows how to use In-App Purchases in Electron. You'll have to replace the product ids by the identifiers of the products created with iTunes Connect (the identifier of com.example.app.product1 is product1). Note that you have to listen to the transactions-updated event as soon as possible in your app.
// Main process\nconst { inAppPurchase } = require('electron')\nconst PRODUCT_IDS = ['id1', 'id2']\n\n// Listen for transactions as soon as possible.\ninAppPurchase.on('transactions-updated', (event, transactions) => {\n if (!Array.isArray(transactions)) {\n return\n }\n\n // Check each transaction.\n transactions.forEach(function (transaction) {\n const payment = transaction.payment\n\n switch (transaction.transactionState) {\n case 'purchasing':\n console.log(`Purchasing ${payment.productIdentifier}...`)\n break\n\n case 'purchased': {\n console.log(`${payment.productIdentifier} purchased.`)\n\n // Get the receipt url.\n const receiptURL = inAppPurchase.getReceiptURL()\n\n console.log(`Receipt URL: ${receiptURL}`)\n\n // Submit the receipt file to the server and check if it is valid.\n // @see https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html\n // ...\n // If the receipt is valid, the product is purchased\n // ...\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n }\n\n case 'failed':\n\n console.log(`Failed to purchase ${payment.productIdentifier}.`)\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n case 'restored':\n\n console.log(`The purchase of ${payment.productIdentifier} has been restored.`)\n\n break\n case 'deferred':\n\n console.log(`The purchase of ${payment.productIdentifier} has been deferred.`)\n\n break\n default:\n break\n }\n })\n})\n\n// Check if the user is allowed to make in-app purchase.\nif (!inAppPurchase.canMakePayments()) {\n console.log('The user is not allowed to make in-app purchase.')\n}\n\n// Retrieve and display the product descriptions.\ninAppPurchase.getProducts(PRODUCT_IDS).then(products => {\n // Check the parameters.\n if (!Array.isArray(products) || products.length <= 0) {\n console.log('Unable to retrieve the product informations.')\n return\n }\n\n // Display the name and price of each product.\n products.forEach(product => {\n console.log(`The price of ${product.localizedTitle} is ${product.formattedPrice}.`)\n })\n\n // Ask the user which product he/she wants to purchase.\n const selectedProduct = products[0]\n const selectedQuantity = 1\n\n // Purchase the selected product.\n inAppPurchase.purchaseProduct(selectedProduct.productIdentifier, selectedQuantity).then(isProductValid => {\n if (!isProductValid) {\n console.log('The product is not valid.')\n return\n }\n\n console.log('The payment has been added to the payment queue.')\n })\n})\n\n\nHandle responses to HTTP/HTTPS requests.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
IncomingMessage implements the Readable Stream interface and is therefore an EventEmitter.
Retorna:
\nchunk Buffer - A chunk of response body's data.The data event is the usual method of transferring response data into applicative code.
Indicates that response body has ended. Must be placed before 'data' event.
\nEmitido quando uma solicitação foi cancelada durante uma transação HTTP em curso.
\nRetorna:
\nerror Error - Typically holds an error string identifying failure root cause.
Emitido quando ocorreu um erro ao transmitir eventos de dados de resposta. For instance, if the server closes the underlying while the response is still streaming, an error event will be emitted on the response object and a close event will subsequently follow on the request object.
An IncomingMessage instance has the following readable properties:
response.statusCodeUm Integer indica o estado do código de resposta HTTP.
response.statusMessageUma String representa a mensagem de estado HTTP.
response.headersA Record<string, string | string[]> representing the HTTP response headers. The headers object is formatted as follows:
age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, server, or user-agent are discarded.set-cookie is always an array. Duplicates are added to the array.cookie headers, the values are joined together with '; '.response.httpVersionA String indicating the HTTP protocol version number. Typical values are '1.0' or '1.1'. Additionally httpVersionMajor and httpVersionMinor are two Integer-valued readable properties that return respectively the HTTP major and minor version numbers.
response.httpVersionMajorAn Integer indicating the HTTP protocol major version number.
response.httpVersionMinorAn Integer indicating the HTTP protocol minor version number.
modifiers String - An array of modifiers of the event, can be shift, control, ctrl, alt, meta, command, cmd, isKeypad, isAutoRepeat, leftButtonDown, middleButtonDown, rightButtonDown, capsLock, numLock, left, right.npm install electron --save-dev The preferred method is to install Electron as a development dependency in your app:
\nnpm install electron --save-dev\nVeja a documentação de versionamento do Electron para informação de como gerenciar as versões em seus aplicativos.
\nIf you're in a pinch and would prefer to not use npm install in your local project, you can also run Electron ad-hoc using the npx command runner bundled with npm:
npx electron .\nThe above command will run the current working directory with Electron. Note that any dependencies in your app will not be installed.
\nSe você quer alterar a arquitetura que é baixada (Ex: ia32 em uma máquina x64), você pode usar a opção --arch com npm install ou definir a variável de ambiente npm_config_arch:
npm install --arch=ia32 electron\nAlém de alterar a arquitetura, você pode também especificar a plataforma (ex: win32, linux, etc.) usando a opção --platform:
npm install --platform=win32 electron\nSe você necessitar usar um HTTP proxy, é preciso adicionar a variável para múltiplos valores,ELECTRON_GET_USE_PROXY, além das variáveis de ambientes adicionais, dependendo da versão do Node:
Durante a instalação, o módulo electron vai se conectar para o @electron/get para fazer o download de binários pré-construídos do Electron para a sua plataforma. Ele fará isso entrando em contato a página de lançamento da GitHub (https://github.com/electron/electron/releases/tag/v$VERSION, onde $VERSION é a versão exata do Electron).
Se você não conseguir acessar o GitHub ou precisar fornecer uma compilação personalizada, poderá fazê-lo fornecendo um espelho ou um diretório de cache existente.
\nVocê pode usar variáveis de ambiente para substituir a URL base, o caminho no qual procurar por binários Electron e o nome do arquivo binário. The URL used by @electron/get is composed as follows:
url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME\nFor instance, to use the China CDN mirror:
\nELECTRON_MIRROR=\"https://cdn.npm.taobao.org/dist/electron/\"\nBy default, ELECTRON_CUSTOM_DIR is set to v$VERSION. To change the format, use the {{ version }} placeholder. For example, version-{{ version }} resolves to version-5.0.0, {{ version }} resolves to 5.0.0, and v{{ version }} is equivalent to the default. As a more concrete example, to use the China non-CDN mirror:
ELECTRON_MIRROR=\"https://npm.taobao.org/mirrors/electron/\"\nELECTRON_CUSTOM_DIR=\"{{ version }}\"\nThe above configuration will download from URLs such as https://npm.taobao.org/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip.
If your mirror serves artifacts with different checksums to the official Electron release you may have to set ELECTRON_USE_REMOTE_CHECKSUMS=1 to force Electron to use the remote SHASUMS256.txt file to verify the checksum instead of the embedded checksums.
Como alternativa, você pode substituir o cache local. O @electron/get armazenará em cache os binários baixados em um diretório local para não estressar sua rede. Você pode usar essa pasta de cache para fornecer construções personalizadas do Electron ou evitar contato com a rede.
$XDG_CACHE_HOME ou ~/.cache/electron/~/Library/Caches/electron/$LOCALAPPDATA/electron/Cache ou ~/AppData/Local/electron/Cache/Em ambientes que usam versões mais antigas do Electron, você pode encontrar cache também em ~/.electron.
Você também pode sobrescrever o local do cache local fornecendo uma variável electron_config_cache de ambiente.
The cache contains the version's official zip file as well as a checksum, stored as a text file. A typical cache might look like this:
\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9electron-v1.7.9-darwin-x64.zip\n│ └── electron-v1.7.9-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1electron-v1.8.1-darwin-x64.zip\n│ └── electron-v1.8.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1electron-v1.8.2-beta.1-darwin-x64.zip\n│ └── electron-v1.8.2-beta.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2electron-v1.8.2-beta.2-darwin-x64.zip\n│ └── electron-v1.8.2-beta.2-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3electron-v1.8.2-beta.3-darwin-x64.zip\n│ └── electron-v1.8.2-beta.3-darwin-x64.zip\n└── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3SHASUMS256.txt\n └── SHASUMS256.txt\nUnder the hood, Electron's JavaScript API binds to a binary that contains its implementations. Because this binary is crucial to the function of any Electron app, it is downloaded by default in the postinstall step every time you install electron from the npm registry.
However, if you want to install your project's dependencies but don't need to use Electron functionality, you can set the ELECTRON_SKIP_BINARY_DOWNLOAD environment variable to prevent the binary from being downloaded. For instance, this feature can be useful in continuous integration environments when running unit tests that mock out the electron module.
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install\nAo executar o npm install electron, alguns usuários encontram erros de instalação.
Em quase todos os casos, esses problemas são resultado de problemas de rede e não de problemas reais com o pacote npm electron. Erros como ELIFECYCLE, EAI_AGAIN, ECONNRESET, e ETIMEDOUT são resultados da falta de internet. A melhor solução é tentar trocar de rede, ou aguardar um pouco e tentar instalar novamente.
You can also attempt to download Electron directly from electron/electron/releases if installing via npm is failing.
If installation fails with an EACCESS error you may need to fix your npm permissions.
If the above error persists, the unsafe-perm flag may need to be set to true:
\nsudo npm install electron --unsafe-perm=true\nEm redes mais lentas, pode ser aconselhável usar o sinalizador --verbose para mostrar o progresso do download:
npm install --verbose electron\nSe você precisar forçar um novo download do ativo e o arquivo SHASUM, defina a variável force_no_cache do ambiente para true.
Bem vindo a documentação do Electron Se esta é a primeira vez que desenvolve um aplicativo com Electron, leia esta seção de Introdução para se familiarizar com o básico. Caso contrário, sinta-se à vontade para explorar nossos guias e documentação da API!
\nElectron é um framework que te permite criar aplicações desktop com JavaScript, HTML e CSS. Incorporando [Chromium][chromium] e [Node.js][node] no seu binário, Electron permite que você mantenha uma base de código para JavaScript e crie aplicações multiplataforma que funcionam no Windows macOS, e Linux — sem necessidade de experiência de desenvolvimento nativo.
\nEstes documentos operam sob a suposição de que o leitor está familiarizado com Node.js e desenvolvimento web geral. Se você precisar se sentir mais confortável com qualquer uma dessas áreas, recomendamos os seguintes recursos:
\n\nAlém disso, você terá um tempo melhor para entender como o Electron funciona se você tiver conhecido o modelo de processo do Chromium. Você pode ter uma breve visão geral de Arquitetura do Chrome com a história do Chrome , que foi lançada junto com Lançamento do Chrome em 2008. Embora já tenha mais de uma década desde então, os princípios fundamentais introduzidos na Google Comic permanecem úteis para entender a Electron.
\nElectron Fiddle é um aplicativo sandbox escrito com Electron e suportado por mantenedores do Electron. É altamente recomendável instalá-lo como uma ferramenta de aprendizado para experiências com APIs do Electron, ou para protótipos de recursos durante o desenvolvimento.
\nO Fiddle também se integra muito bem com a nossa documentação. Ao navegar pelos exemplos em nossos tutoriais, você frequentemente verá um botão \"Abrir no Electron Fiddle\" abaixo de um bloco de código. Se você tiver o Fiddle instalado, este botão abrirá um fiddle.electronjs. rg link que carregará automaticamente o exemplo no Fiddle, nenhuma cópia é necessária.
Você está ficando preso em algum lugar? Aqui estão alguns links de lugares para procurar:
\nelectron, verifique o problemas no GitHub para ver se algum problema existente corresponde ao seu problema Caso contrário, sinta-se à vontade para preencher o nosso modelo de relatório de erros e envie uma nova issue.readOperationCount Number - The number of I/O read operations.writeOperationCount Number - The number of I/O write operations.otherOperationCount Number - Then number of I/O other operations.readTransferCount Number - The number of I/O read transfers.writeTransferCount Number - The number of I/O write transfers.otherTransferCount Number - Then number of I/O other transfers.\n\nComunica de forma assíncrona o processo principal aos processos de renderização.
\n
Processo: Main
\nO módulo ipcMain é um emissor de eventos. Quando usado no processo principal, ele lida com mensagens assíncronas e síncronas enviadas a partir de um processo de renderização (página da web). As mensagens enviadas de um renderizador serão emitidas para este módulo.
Também é possível enviar mensagens do processo principal para o processo de renderização, veja webContents.send para obter mais informações.
\nchannel.event.returnValue.event.reply(...). This helper method will automatically handle messages coming from frames that aren't the main frame (e.g. iframes) whereas event.sender.send(...) will always send to the main frame.Um exemplo de enviar e manipular mensagens entre os processos de renderização e principais:
\n// In main process.\nconst { ipcMain } = require('electron')\nipcMain.on('asynchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.reply('asynchronous-reply', 'pong')\n})\n\nipcMain.on('synchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.returnValue = 'pong'\n})\n// In renderer process (web page).\n// NB. Electron APIs are only accessible from preload, unless contextIsolation is disabled.\n// See https://www.electronjs.org/docs/tutorial/process-model#preload-scripts for more details.\nconst { ipcRenderer } = require('electron')\nconsole.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // prints \"pong\"\n\nipcRenderer.on('asynchronous-reply', (event, arg) => {\n console.log(arg) // prints \"pong\"\n})\nipcRenderer.send('asynchronous-message', 'ping')\nO módulo ipcMain possui o seguinte método para ouvir eventos:
ipcMain.on(channel, listener)channel Stringlistener Funçãoevent IpcMainEvent...args any[]Ouve o channel, quando uma mensagem chega, o listener deve ser chamado com listener(event, args...).
ipcMain.once(channel, listener)channel Stringlistener Funçãoevent IpcMainEvent...args any[]Adds a one time listener function for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed.
ipcMain.removeListener(channel, listener)channel Stringlistener Função...args any[]Removes the specified listener from the listener array for the specified channel.
ipcMain.removeAllListeners([channel])channel String (opcional)Removes listeners of the specified channel.
ipcMain.handle(channel, listener)channel Stringlistener Function<Promise\\event IpcMainInvokeEvent...args any[]Adds a handler for an invokeable IPC. This handler will be called whenever a renderer calls ipcRenderer.invoke(channel, ...args).
If listener returns a Promise, the eventual result of the promise will be returned as a reply to the remote caller. Otherwise, the return value of the listener will be used as the value of the reply.
// Main process\nipcMain.handle('my-invokable-ipc', async (event, ...args) => {\n const result = await somePromise(...args)\n return result\n})\n\n// Renderer process\nasync () => {\n const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)\n // ...\n}\nThe event that is passed as the first argument to the handler is the same as that passed to a regular event listener. It includes information about which WebContents is the source of the invoke request.
Errors thrown through handle in the main process are not transparent as they are serialized and only the message property from the original error is provided to the renderer process. Please refer to #24427 for details.
ipcMain.handleOnce(channel, listener)channel Stringlistener Function<Promise\\event IpcMainInvokeEvent...args any[]Handles a single invokeable IPC message, then removes the listener. See ipcMain.handle(channel, listener).
ipcMain.removeHandler(channel)channel StringRemoves any handler for channel, if present.
The documentation for the event object passed to the callback can be found in the ipc-main-event structure docs.
The documentation for the event object passed to handle callbacks can be found in the ipc-main-invoke-event structure docs.
EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagereturnValue any - Set this to the value to be returned in a synchronous messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this messageports MessagePortMain[] - A list of MessagePorts that were transferred with this messagereply Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to \"reply\" to the sent message in order to guarantee the reply will go to the correct process and frame.channel String...args any[]EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this message\n\nComunica de forma assíncrona de um processo de renderização para o processo principal.
\n
Processo: Renderizador
\nO módulo ipcRenderer é um EventEmitter. Ele fornece alguns métodos para que você possa enviar mensagens síncronas e assíncronas do processo de renderização (página da web) para o processo principal. Você também pode receber respostas do processo principal.
Veja ipcMain para exemplos de código.
\nO módulo ipcRenderer possui o seguinte método para ouvir eventos e enviar mensagens:
ipcRenderer.on(channel, listener)channel Stringlistener Funçãoevent IpcRendererEvent...args any[]Ouve o channel, quando uma mensagem chega, o listener deve ser chamado com listener(event, args...).
ipcRenderer.once(channel, listener)channel Stringlistener Funçãoevent IpcRendererEvent...args any[]Adds a one time listener function for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed.
ipcRenderer.removeListener(channel, listener)channel Stringlistener Função...args any[]Removes the specified listener from the listener array for the specified channel.
ipcRenderer.removeAllListeners(channel)channel StringRemove todos os listeners, ou apenas os do channel especificado.
ipcRenderer.send(channel, ...args)channel String...args any[]Envie uma mensagem assíncrona para o processo principal através do channel, juntamente com argumentos. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. O envio de funções, promessas, símbolos, weakmaps ou WeakSets lançará uma exceção.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
The main process handles it by listening for channel with the ipcMain module.
If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you want to receive a single response from the main process, like the result of a method call, consider using ipcRenderer.invoke.
ipcRenderer.invoke(channel, ...args)channel String...args any[]Returns Promise<any> - Resolves with the response from the main process.
Send a message to the main process via channel and expect a result asynchronously. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. O envio de funções, promessas, símbolos, weakmaps ou WeakSets lançará uma exceção.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
The main process should listen for channel with ipcMain.handle().
Como por exemplo:
\n// Renderer process\nipcRenderer.invoke('some-name', someArgument).then((result) => {\n // ...\n})\n\n// Main process\nipcMain.handle('some-name', async (event, someArgument) => {\n const result = await doSomeWork(someArgument)\n return result\n})\nIf you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you do not need a response to the message, consider using ipcRenderer.send.
ipcRenderer.sendSync(channel, ...args)channel String...args any[]Returns any - The value sent back by the ipcMain handler.
Send a message to the main process via channel and expect a result synchronously. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. O envio de funções, promessas, símbolos, weakmaps ou WeakSets lançará uma exceção.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
The main process handles it by listening for channel with ipcMain module, and replies by setting event.returnValue.
\n\n⚠️ WARNING: Sending a synchronous message will block the whole renderer process until the reply is received, so use this method only as a last resort. It's much better to use the asynchronous version,
\ninvoke().
ipcRenderer.postMessage(channel, message, [transfer])Send a message to the main process, optionally transferring ownership of zero or more MessagePort objects.
The transferred MessagePort objects will be available in the main process as MessagePortMain objects by accessing the ports property of the emitted event.
Como por exemplo:
\n// Renderer process\nconst { port1, port2 } = new MessageChannel()\nipcRenderer.postMessage('port', { message: 'hello' }, [port1])\n\n// Main process\nipcMain.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nFor more information on using MessagePort and MessageChannel, see the MDN documentation.
ipcRenderer.sendTo(webContentsId, channel, ...args)webContentsId Numberchannel String...args any[]Sends a message to a window with webContentsId via channel.
ipcRenderer.sendToHost(channel, ...args)channel String...args any[]Like ipcRenderer.send but the event will be sent to the <webview> element in the host page instead of the main process.
The documentation for the event object passed to the callback can be found in the ipc-renderer-event structure docs.
Eventsender IpcRenderer - The IpcRenderer instance that emitted the event originallysenderId Integer - The webContents.id that sent the message, you can call event.sender.sendTo(event.senderId, ...) to reply to the message, see ipcRenderer.sendTo for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set event.senderId to 0.ports MessagePort[] - A list of MessagePorts that were transferred with this messagePara qualquer problema, existem fundamentalmente três maneiras que alguém pode contribuir:
\nelectron/electron issue tracker.electron/electron de uma forma concreta e revisável.\"Encontrando Suporte\" tem uma lista com informações para obter ajuda de programação, reportar problemas de segurança, contribuir e mais. Por favor, utilize o rastreador de problemas apenas para bugs!
\nTo submit a bug report:
\nWhen opening a new issue in the electron/electron issue tracker, users will be presented with a template that should be filled in.
If you believe that you have found a bug in Electron, please fill out the template to the best of your ability.
\nAs duas informações mais importantes necessárias para avaliar o relato de um bug são a descrição e um caso de teste simples para recriá-lo. It is easier to fix a bug if it can be reproduced.
\nVeja Como criar um exemplo Mínimo, Completo e Verificável.
\nÉ comum que questões abertas envolvam discussão. Alguns contribuidores podem diferir em opiniões em relação ao comportamento ser um bug ou uma característica. Esta discussão faz parte do processo e deve ser mantida em foco, útil, e profissional.
\nRespostas que não fornecem contexto adicional nem detalhes de suporte não são úteis ou profissionais. Para muitos, essas respostas são irritantes e nada amigáveis.
\nOs colaboradores são encorajados a resolver problemas colaborativamente e ajudar uns aos outros a fazer progresso. If you encounter an issue that you feel is invalid, or which contains incorrect information, explain why you feel that way with additional supporting context, and be willing to be convinced that you may be wrong. Ao fazê-lo, podemos frequentemente chegar mais rapidamente ao resultado correto.
\nA maioria das questões são resolvidas abrindo um pull request. O processo para abertura e revisão de um pull request é semelhante ao de abertura e triagem de questões, mas carrega consigo um fluxo de trabalho de revisão e aprovação necessário que garante que as alterações propostas atendem às orientações de qualidade mínima e funcionais do projeto Electron.
", "title": "Questões com o Electron", "description": "" }, "/docs/api/structures/jump-list-category": { "locale": "pt-BR", "slug": "jump-list-category", "href": "/docs/api/structures/jump-list-category", "crowdinFileId": "256451", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/jump-list-category.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "type String (optional) - One of the following:tasks - Items in this category will be placed into the standard Tasks category. There can be only one such category, and it will always be displayed at the bottom of the Jump List.frequent - Displays a list of files frequently opened by the app, the name of the category and its items are set by Windows.recent - Displays a list of files recently opened by the app, the name of the category and its items are set by Windows. Items may be added to this category indirectly using app.addRecentDocument(path).custom - Displays tasks or file links, name must be set by the app.name String (optional) - Must be set if type is custom, otherwise it should be omitted.items JumpListItem - Array of JumpListItem objects if type is tasks or custom, otherwise it should be omitted.Note: If a JumpListCategory object has neither the type nor the name property set then its type is assumed to be tasks. If the name property is set but the type property is omitted then the type is assumed to be custom.
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
type String (optional) - One of the following:task - A task will launch an app with specific arguments.separator - Can be used to separate items in the standard Tasks category.file - A file link will open a file using the app that created the Jump List, for this to work the app must be registered as a handler for the file type (though it doesn't have to be the default handler).path String (optional) - Path of the file to open, should only be set if type is file.program String (optional) - Path of the program to execute, usually you should specify process.execPath which opens the current program. Should only be set if type is task.args String (optional) - The command line arguments when program is executed. Should only be set if type is task.title String (optional) - The text to be displayed for the item in the Jump List. Should only be set if type is task.description String (optional) - Description of the task (displayed in a tooltip). Should only be set if type is task. Maximum length 260 characters.iconPath String (optional) - The absolute path to an icon to be displayed in a Jump List, which can be an arbitrary resource file that contains an icon (e.g. .ico, .exe, .dll). You can usually specify process.execPath to show the program icon.iconIndex Number (optional) - The index of the icon in the resource file. If a resource file contains multiple icons this value can be used to specify the zero-based index of the icon that should be displayed for this task. If a resource file contains only one icon, this property should be set to zero.workingDirectory String (optional) - The working directory. Default is empty.ctrlKey Boolean (optional) - whether the Control key was used in an accelerator to trigger the EventmetaKey Boolean (optional) - whether a meta key was used in an accelerator to trigger the EventshiftKey Boolean (optional) - whether a Shift key was used in an accelerator to trigger the EventaltKey Boolean (optional) - whether an Alt key was used in an accelerator to trigger the EventtriggeredByAccelerator Boolean (optional) - whether an accelerator was used to trigger the event as opposed to another user gesture like mouse clickInputEventtype String - The type of the event, can be keyDown, keyUp or char.keyCode String - The character that will be sent as the keyboard event. Should only use the valid key codes in Accelerator.This feature allows you to configure local and global keyboard shortcuts for your Electron application.
\nLocal keyboard shortcuts are triggered only when the application is focused. To configure a local keyboard shortcut, you need to specify an accelerator property when creating a MenuItem within the Menu module.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { Menu, MenuItem } = require('electron')\n\nconst menu = new Menu()\nmenu.append(new MenuItem({\n label: 'Electron',\n submenu: [{\n role: 'help',\n accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Alt+Shift+I',\n click: () => { console.log('Electron rocks!') }\n }]\n}))\n\nMenu.setApplicationMenu(menu)\n\n\nNOTE: In the code above, you can see that the accelerator differs based on the user's operating system. For MacOS, it is
\nAlt+Cmd+I, whereas for Linux and Windows, it isAlt+Shift+I.
After launching the Electron application, you should see the application menu along with the local shortcut you just defined:
\n
If you click Help or press the defined accelerator and then open the terminal that you ran your Electron application from, you will see the message that was generated after triggering the click event: \"Electron rocks!\".
To configure a global keyboard shortcut, you need to use the globalShortcut module to detect keyboard events even when the application does not have keyboard focus.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n globalShortcut.register('Alt+CommandOrControl+I', () => {\n console.log('Electron loves global shortcuts!')\n })\n}).then(createWindow)\n\n\nNOTE: In the code above, the
\nCommandOrControlcombination usesCommandon macOS andControlon Windows/Linux.
After launching the Electron application, if you press the defined key combination then open the terminal that you ran your Electron application from, you will see that Electron loves global shortcuts!
\nIf you want to handle keyboard shortcuts within a BrowserWindow, you can listen for the keyup and keydown DOM events inside the renderer process using the addEventListener() API.
function handleKeyPress(event) {\n // You can put code here to handle the keypress.\n document.getElementById(\"last-keypress\").innerText = event.key;\n console.log(`You pressed ${event.key}`);\n}\n\nwindow.addEventListener('keyup', handleKeyPress, true);\n\n\nNote: the third parameter
\ntrueindicates that the listener will always receive key presses before other listeners so they can't havestopPropagation()called on them.
O evento before-input-event é emitido antes enviar os eventos keydown e keyup na página. Ele pode ser usado para capturar e manipular atalhos personalizados que não estão visíveis no menu.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, BrowserWindow } = require('electron')\n\napp.whenReady().then(() => {\n const win = new BrowserWindow({ width: 800, height: 600 })\n\n win.loadFile('index.html')\n win.webContents.on('before-input-event', (event, input) => {\n if (input.control && input.key.toLowerCase() === 'i') {\n console.log('Pressed Control+I')\n event.preventDefault()\n }\n })\n})\nAfter launching the Electron application, if you open the terminal that you ran your Electron application from and press Ctrl+I key combination, you will see that this key combination was successfully intercepted.
If you don't want to do manual shortcut parsing, there are libraries that do advanced key detection, such as mousetrap. Below are examples of usage of the mousetrap running in the Renderer process:
Mousetrap.bind('4', () => { console.log('4') })\nMousetrap.bind('?', () => { console.log('show shortcuts!') })\nMousetrap.bind('esc', () => { console.log('escape') }, 'keyup')\n\n// combinations\nMousetrap.bind('command+shift+k', () => { console.log('command shift k') })\n\n// map multiple combinations to the same callback\nMousetrap.bind(['command+k', 'ctrl+k'], () => {\n console.log('command k or control k')\n\n // return false to prevent default behavior and stop event from bubbling\n return false\n})\n\n// gmail style sequences\nMousetrap.bind('g i', () => { console.log('go to inbox') })\nMousetrap.bind('* a', () => { console.log('select all') })\n\n// konami code!\nMousetrap.bind('up up down down left right left right b a enter', () => {\n console.log('konami code')\n})\ntitle: Launching Your Electron App From a URL In Another App\ndescription: This guide will take you through the process of setting your electron app as the default handler for a specific protocol.\nslug: launch-app-from-url-in-another-app
\nThis guide will take you through the process of setting your Electron app as the default handler for a specific protocol.
\nBy the end of this tutorial, we will have set our app to intercept and handle any clicked URLs that start with a specific protocol. In this guide, the protocol we will use will be \"electron-fiddle://\".
First, we will import the required modules from electron. These modules help control our application lifecycle and create a native browser window.
const { app, BrowserWindow, shell } = require('electron')\nconst path = require('path')\nNext, we will proceed to register our application to handle all \"electron-fiddle://\" protocols.
if (process.defaultApp) {\n if (process.argv.length >= 2) {\n app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])\n }\n} else {\n app.setAsDefaultProtocolClient('electron-fiddle')\n}\nWe will now define the function in charge of creating our browser window and load our application's index.html file.
const createWindow = () => {\n // Create the browser window.\n mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n mainWindow.loadFile('index.html')\n}\nIn this next step, we will create our BrowserWindow and tell our application how to handle an event in which an external protocol is clicked.
This code will be different in Windows compared to MacOS and Linux. This is due to Windows requiring additional code in order to open the contents of the protocol link within the same Electron instance. Read more about this here.
\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Someone tried to run a second instance, we should focus our window.\n if (mainWindow) {\n if (mainWindow.isMinimized()) mainWindow.restore()\n mainWindow.focus()\n }\n })\n\n // Create mainWindow, load the rest of the app, etc...\n app.whenReady().then(() => {\n createWindow()\n })\n\n // Handle the protocol. In this case, we choose to show an Error Box.\n app.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n })\n}\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// Algumas APIs podem ser usadas somente depois que este evento ocorre.\napp.whenReady().then(() => {\n createWindow()\n})\n\n// Handle the protocol. In this case, we choose to show an Error Box.\napp.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n})\nFinally, we will add some additional code to handle when someone closes our application.
\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') app.quit()\n})\nOn macOS and Linux, this feature will only work when your app is packaged. It will not work when you're launching it in development from the command-line. When you package your app you'll need to make sure the macOS Info.plist and the Linux .desktop files for the app are updated to include the new protocol handler. Some of the Electron tools for bundling and distributing apps handle this for you.
If you're using Electron Forge, adjust packagerConfig for macOS support, and the configuration for the appropriate Linux makers for Linux support, in your Forge configuration (please note the following example only shows the bare minimum needed to add the configuration changes):
{\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"protocols\": [\n {\n \"name\": \"Electron Fiddle\",\n \"schemes\": [\"electron-fiddle\"]\n }\n ]\n },\n \"makers\": [\n {\n \"name\": \"@electron-forge/maker-deb\",\n \"config\": {\n \"mimeType\": [\"x-scheme-handler/electron-fiddle\"]\n }\n }\n ]\n }\n }\n}\nFor macOS support:
\nIf you're using Electron Packager's API, adding support for protocol handlers is similar to how Electron Forge is handled, except protocols is part of the Packager options passed to the packager function.
const packager = require('electron-packager')\n\npackager({\n // ...other options...\n protocols: [\n {\n name: 'Electron Fiddle',\n schemes: ['electron-fiddle']\n }\n ]\n\n}).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))\n .catch(err => console.error(`ERROR: ${err.message}`))\nIf you're using Electron Packager's CLI, use the --protocol and --protocol-name flags. For example:
npx electron-packager . --protocol=electron-fiddle --protocol-name=\"Electron Fiddle\"\nAfter you start your Electron app, you can enter in a URL in your browser that contains the custom protocol, for example \"electron-fiddle://open\" and observe that the application will respond and show an error dialog box.
On many Linux environments, you can add custom entries to the system launcher by modifying the .desktop file. For Canonical's Unity documentation, see Adding Shortcuts to a Launcher. For details on a more generic implementation, see the freedesktop.org Specification.
\n\nNOTE: The screenshot above is an example of launcher shortcuts in Audacious audio player
\n
To create a shortcut, you need to provide Name and Exec properties for the entry you want to add to the shortcut menu. Unity will execute the command defined in the Exec field after the user clicked the shortcut menu item. An example of the .desktop file may look as follows:
Actions=PlayPause;Next;Previous\n\n[Desktop Action PlayPause]\nName=Play-Pause\nExec=audacious -t\nOnlyShowIn=Unity;\n\n[Desktop Action Next]\nName=Next\nExec=audacious -f\nOnlyShowIn=Unity;\n\n[Desktop Action Previous]\nName=Previous\nExec=audacious -r\nOnlyShowIn=Unity;\nThe preferred way for Unity to instruct your application on what to do is using parameters. You can find them in your application in the global variable process.argv.
Este guia fornece informações sobre:
\nPara assinar os aplicativos Electron, as seguintes ferramentas devem ser instaladas primeiro:
\nVocê também tem que registrar uma conta do Apple Developer e participar do Apple Developer Program.
\nElectron apps can be distributed through Mac App Store or outside it. Each way requires different ways of signing and testing. This guide focuses on distribution via Mac App Store, but will also mention other methods.
\nThe following steps describe how to get the certificates from Apple, how to sign Electron apps, and how to test them.
\nThe simplest way to get signing certificates is to use Xcode:
\nThe \"Apple Development\" certificate is used to sign apps for development and testing, on machines that have been registered on Apple Developer website. The method of registration will be described in Prepare provisioning profile.
\nApps signed with the \"Apple Development\" certificate cannot be submitted to Mac App Store. For that purpose, apps must be signed with the \"Apple Distribution\" certificate instead. But note that apps signed with the \"Apple Distribution\" certificate cannot run directly, they must be re-signed by Apple to be able to run, which will only be possible after being downloaded from the Mac App Store.
\nYou may notice that there are also other kinds of certificates.
\nThe \"Developer ID Application\" certificate is used to sign apps before distributing them outside the Mac App Store.
\nThe \"Developer ID Installer\" and \"Mac Installer Distribution\" certificates are used to sign the Mac Installer Package instead of the app itself. Most Electron apps do not use Mac Installer Package so they are generally not needed.
\nThe full list of certificate types can be found here.
\nApps signed with \"Apple Development\" and \"Apple Distribution\" certificates can only run under App Sandbox, so they must use the MAS build of Electron. However, the \"Developer ID Application\" certificate does not have this restrictions, so apps signed with it can use either the normal build or the MAS build of Electron.
\nApple has been changing the names of certificates during past years, you might encounter them when reading old documentations, and some utilities are still using one of the old names.
\nIf you want to test your app on your local machine before submitting your app to the Mac App Store, you have to sign the app with the \"Apple Development\" certificate with the provisioning profile embedded in the app bundle.
\nTo create a provisioning profile, you can follow the below steps:
\n/path/to/yourapp.provisionprofile.Apps submitted to the Mac App Store must run under Apple's App Sandbox, and only the MAS build of Electron can run with the App Sandbox. The standard darwin build of Electron will fail to launch when run under App Sandbox.
\nWhen signing the app with electron-osx-sign, it will automatically add the necessary entitlements to your app's entitlements, but if you are using custom entitlements, you must ensure App Sandbox capacity is added:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n </dict>\n</plist>\nelectron-osx-signIf you are signing your app without using electron-osx-sign, you must ensure the app bundle's entitlements have at least following keys:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.application-groups</key>\n <array>\n <string>TEAM_ID.your.bundle.id</string>\n </array>\n </dict>\n</plist>\nThe TEAM_ID should be replaced with your Apple Developer account's Team ID, and the your.bundle.id should be replaced with the App ID of the app.
And the following entitlements must be added to the binaries and helpers in the app's bundle:
\n\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.inherit</key>\n <true/>\n </dict>\n</plist>\nAnd the app bundle's Info.plist must include ElectronTeamID key, which has your Apple Developer account's Team ID as its value:
<plist version=\"1.0\">\n<dict>\n ...\n <key>ElectronTeamID</key>\n <string>TEAM_ID</string>\n</dict>\n</plist>\nWhen using electron-osx-sign the ElectronTeamID key will be added automatically by extracting the Team ID from the certificate's name. You may need to manually add this key if electron-osx-sign could not find the correct Team ID.
To sign an app that can run on your development machine, you must sign it with the \"Apple Development\" certificate and pass the provisioning profile to electron-osx-sign.
electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile\nIf you are signing without electron-osx-sign, you must place the provisioning profile to YourApp.app/Contents/embedded.provisionprofile.
The signed app can only run on the machines that registered by the provisioning profile, and this is the only way to test the signed app before submitting to Mac App Store.
\nTo sign an app that will be submitted to Mac App Store, you must sign it with the \"Apple Distribution\" certificate. Note that apps signed with this certificate will not run anywhere, unless it is downloaded from Mac App Store.
\nelectron-osx-sign YourApp.app --identity='Apple Distribution'\nIf you don't plan to submit the app to Mac App Store, you can sign it the \"Developer ID Application\" certificate. In this way there is no requirement on App Sandbox, and you should use the normal darwin build of Electron if you don't use App Sandbox.
\nelectron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess\nBy passing --no-gatekeeper-assess, the electron-osx-sign will skip the macOS GateKeeper check as your app usually has not been notarized yet by this step.
This guide does not cover App Notarization, but you might want to do it otherwise Apple may prevent users from using your app outside Mac App Store.
\nAfter signing the app with the \"Apple Distribution\" certificate, you can continue to submit it to Mac App Store.
\nHowever, this guide do not ensure your app will be approved by Apple; you still need to read Apple's Submitting Your App guide on how to meet the Mac App Store requirements.
\nThe Application Loader should be used to upload the signed app to iTunes Connect for processing, making sure you have created a record before uploading.
\nIf you are seeing errors like private APIs uses, you should check if the app is using the MAS build of Electron.
\nAfter uploading, you should submit your app for review.
\nIn order to satisfy all requirements for app sandboxing, the following modules have been disabled in the MAS build:
\ncrashReporterautoUpdaterand the following behaviors have been changed:
\nAlso, due to the usage of app sandboxing, the resources which can be accessed by the app are strictly limited; you can read App Sandboxing for more information.
\nDepending on which Electron APIs your app uses, you may need to add additional entitlements to your app's entitlements file. Otherwise, the App Sandbox may prevent you from using them.
\nEnable outgoing network connections to allow your app to connect to a server:
\n<key>com.apple.security.network.client</key>\n<true/>\nEnable incoming network connections to allow your app to open a network listening socket:
\n<key>com.apple.security.network.server</key>\n<true/>\nSee the Enabling Network Access documentation for more details.
\n<key>com.apple.security.files.user-selected.read-only</key>\n<true/>\nSee the Enabling User-Selected File Access documentation for more details.
\n<key>com.apple.security.files.user-selected.read-write</key>\n<true/>\nSee the Enabling User-Selected File Access documentation for more details.
\nDependendo dos países em que você esteja liberando seu aplicativo, você pode ser obrigado a fornecer informações sobre os algoritmos criptográficos usados em seu software. Veja a documentação de conformidade com a criptografia para mais informações.
\nElectron uses following cryptographic algorithms:
\nElectron possui API's para configurar ícones de aplicativos no dock do macOS. A macOS-only API exists to create a custom dock menu, but Electron also uses the app dock icon as the entry point for cross-platform features like recent documents and application progress.
\nO dock customizado é frequentemente usado para adicionar atalhos para tarefas as quais o usuário não irá querer abrir totalmente a janela do aplicativo para acessá-la.
\nMenu do Dock do Terminal.app:
\n
To set your custom dock menu, you need to use the app.dock.setMenu API, which is only available on macOS.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, BrowserWindow, Menu } = require('electron')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n })\n\n win.loadFile('index.html')\n}\n\nconst dockMenu = Menu.buildFromTemplate([\n {\n label: 'New Window',\n click () { console.log('New Window') }\n }, {\n label: 'New Window with Settings',\n submenu: [\n { label: 'Basic' },\n { label: 'Pro' }\n ]\n },\n { label: 'New Command...' }\n])\n\napp.whenReady().then(() => {\n if (process.platform === 'darwin') {\n app.dock.setMenu(dockMenu)\n }\n}).then(createWindow)\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n\nAfter launching the Electron application, right click the application icon. You should see the custom menu you just defined:
\n
workingSetSize Integer - The amount of memory currently pinned to actual physical RAM.peakWorkingSetSize Integer - The maximum amount of memory that has ever been pinned to actual physical RAM.privateBytes Integer (optional) Windows - The amount of memory not shared by other processes, such as JS heap or HTML content.Note that all statistics are reported in Kilobytes.
", "title": "MemoryInfo Object", "description": "" }, "/docs/api/structures/memory-usage-details": { "locale": "pt-BR", "slug": "memory-usage-details", "href": "/docs/api/structures/memory-usage-details", "crowdinFileId": "256461", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/memory-usage-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "count Numbersize NumberliveSize Number\n\nCria menus de aplicativo e menus de contexto nativos.
\n
Processo: Main
\nnew Menu()Cria um novo menu.
\nA classe Menu tem os seguintes métodos estáticos:
Menu.setApplicationMenu(menu)menu Menu | nullSets menu as the application menu on macOS. On Windows and Linux, the menu will be set as each window's top menu.
Also on Windows and Linux, you can use a & in the top-level item name to indicate which letter should get a generated accelerator. For example, using &File for the file menu would result in a generated Alt-F accelerator that opens the associated menu. The indicated character in the button label then gets an underline, and the & character is not displayed on the button label.
In order to escape the & character in an item name, add a proceeding &. For example, &&File would result in &File displayed on the button label.
Passing null will suppress the default menu. On Windows and Linux, this has the additional effect of removing the menu bar from the window.
Note: The default menu will be created automatically if the app does not set one. It contains standard items such as File, Edit, View, Window and Help.
Menu.getApplicationMenu()Retorna Menu | null - O menu do aplicativo, se definido, ou null, se não fora definido.
Nota: A instancia Menu retornada não suporta adição dinâmica ou remoção de itens de menu. Instance properties ainda podem ser modificadas dinamicamente.
Menu.sendActionToFirstResponder(action) no macOSaction StringSends the action to the first responder of application. This is used for emulating default macOS menu behaviors. Usually you would use the role property of a MenuItem.
See the macOS Cocoa Event Handling Guide for more information on macOS' native actions.
\nMenu.buildFromTemplate(template)template (MenuItemConstructorOptions | MenuItem)[]Retorna Menu
Generally, the template is an array of options for constructing a MenuItem. The usage can be referenced above.
You can also attach other fields to the element of the template and they will become properties of the constructed menu items.
O objeto menu possui os seguintes métodos de instância:
menu.popup([options])options (opcional)window BrowserWindow (optional) - Default is the focused window.x Number (optional) - Default is the current mouse cursor position. Must be declared if y is declared.y Number (optional) - Default is the current mouse cursor position. Must be declared if x is declared.positioningItem Number (optional) macOS - The index of the menu item to be positioned under the mouse cursor at the specified coordinates. Default is -1.callback Function (optional) - Called when menu is closed.Pops up this menu as a context menu in the BrowserWindow.
menu.closePopup([browserWindow])browserWindow BrowserWindow (optional) - Default is the focused window.Fecha o menu de contexto em browserWindow.
menu.append(menuItem)menuItem MenuItemAcrescenta o menuItem ao menu.
menu.getMenuItemById(id)id StringReturns MenuItem | null the item with the specified id
menu.Insert(pos, menuItem)pos IntegermenuItem MenuItemInsere o menuItem na posição pos do menu.
Objects created with new Menu or returned by Menu.buildFromTemplate emit the following events:
Note: Some events are only available on specific operating systems and are labeled as such.
\nRetorna:
\nevent EventEmitted when menu.popup() is called.
Retorna:
\nevent EventEmitted when a popup is closed either manually or with menu.closePopup().
Objetos menu também possuem as seguintes propriedades:
menu.itemsUm array MenuItem[] contendo os itens do menu.
Cada Menu consiste de múltiplos MenuItems e cada MenuItem pode ter um submenu.
An example of creating the application menu with the simple template API:
\nconst { app, Menu } = require('electron')\n\nconst isMac = process.platform === 'darwin'\n\nconst template = [\n // { role: 'appMenu' }\n ...(isMac ? [{\n label: app.name,\n submenu: [\n { role: 'about' },\n { type: 'separator' },\n { role: 'services' },\n { type: 'separator' },\n { role: 'hide' },\n { role: 'hideOthers' },\n { role: 'unhide' },\n { type: 'separator' },\n { role: 'quit' }\n ]\n }] : []),\n // { role: 'fileMenu' }\n {\n label: 'File',\n submenu: [\n isMac ? { role: 'close' } : { role: 'quit' }\n ]\n },\n // { role: 'editMenu' }\n {\n label: 'Edit',\n submenu: [\n { role: 'undo' },\n { role: 'redo' },\n { type: 'separator' },\n { role: 'cut' },\n { role: 'copy' },\n { role: 'paste' },\n ...(isMac ? [\n { role: 'pasteAndMatchStyle' },\n { role: 'delete' },\n { role: 'selectAll' },\n { type: 'separator' },\n {\n label: 'Speech',\n submenu: [\n { role: 'startSpeaking' },\n { role: 'stopSpeaking' }\n ]\n }\n ] : [\n { role: 'delete' },\n { type: 'separator' },\n { role: 'selectAll' }\n ])\n ]\n },\n // { role: 'viewMenu' }\n {\n label: 'View',\n submenu: [\n { role: 'reload' },\n { role: 'forceReload' },\n { role: 'toggleDevTools' },\n { type: 'separator' },\n { role: 'resetZoom' },\n { role: 'zoomIn' },\n { role: 'zoomOut' },\n { type: 'separator' },\n { role: 'togglefullscreen' }\n ]\n },\n // { role: 'windowMenu' }\n {\n label: 'Window',\n submenu: [\n { role: 'minimize' },\n { role: 'zoom' },\n ...(isMac ? [\n { type: 'separator' },\n { role: 'front' },\n { type: 'separator' },\n { role: 'window' }\n ] : [\n { role: 'close' }\n ])\n ]\n },\n {\n role: 'help',\n submenu: [\n {\n label: 'Learn More',\n click: async () => {\n const { shell } = require('electron')\n await shell.openExternal('https://electronjs.org')\n }\n }\n ]\n }\n]\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nTo create menus initiated by the renderer process, send the required information to the main process using IPC and have the main process display the menu on behalf of the renderer.
\nBelow is an example of showing a menu when the user right clicks the page:
\n// renderer\nwindow.addEventListener('contextmenu', (e) => {\n e.preventDefault()\n ipcRenderer.send('show-context-menu')\n})\n\nipcRenderer.on('context-menu-command', (e, command) => {\n // ...\n})\n\n// main\nipcMain.on('show-context-menu', (event) => {\n const template = [\n {\n label: 'Menu Item 1',\n click: () => { event.sender.send('context-menu-command', 'menu-item-1') }\n },\n { type: 'separator' },\n { label: 'Menu Item 2', type: 'checkbox', checked: true }\n ]\n const menu = Menu.buildFromTemplate(template)\n menu.popup(BrowserWindow.fromWebContents(event.sender))\n})\nmacOS has a completely different style of application menu from Windows and Linux. Here are some notes on making your app's menu more native-like.
\nOn macOS there are many system-defined standard menus, like the Services and Windows menus. To make your menu a standard menu, you should set your menu's role to one of the following and Electron will recognize them and make them become standard menus:
windowhelpservicesO macOS fornece ações padronizadas para alguns itens de menu, como About xxx, Hide xxx, and Hide Others. To set the action of a menu item to a standard action, you should set the role attribute of the menu item.
On macOS the label of the application menu's first item is always your app's name, no matter what label you set. To change it, modify your app bundle's Info.plist file. See About Information Property List Files for more information.
The setMenu method of browser windows can set the menu of certain browser windows.
You can make use of before, after, beforeGroupContaining, afterGroupContaining and id to control how the item will be placed when building a menu with Menu.buildFromTemplate.
before - Inserts this item before the item with the specified label. If the referenced item doesn't exist the item will be inserted at the end of the menu. Also implies that the menu item in question should be placed in the same “group” as the item.after - Inserts this item after the item with the specified label. If the referenced item doesn't exist the item will be inserted at the end of the menu. Also implies that the menu item in question should be placed in the same “group” as the item.beforeGroupContaining - Provides a means for a single context menu to declare the placement of their containing group before the containing group of the item with the specified label.afterGroupContaining - Provides a means for a single context menu to declare the placement of their containing group after the containing group of the item with the specified label.By default, items will be inserted in the order they exist in the template unless one of the specified positioning keywords is used.
\nModelo:
\n[\n { id: '1', label: 'one' },\n { id: '2', label: 'two' },\n { id: '3', label: 'three' },\n { id: '4', label: 'four' }\n]\nMenu:
\n- 1\n- 2\n- 3\n- 4\nModelo:
\n[\n { id: '1', label: 'one' },\n { type: 'separator' },\n { id: '3', label: 'three', beforeGroupContaining: ['1'] },\n { id: '4', label: 'four', afterGroupContaining: ['2'] },\n { type: 'separator' },\n { id: '2', label: 'two' }\n]\nMenu:
\n- 3\n- 4\n- ---\n- 1\n- ---\n- 2\nModelo:
\n[\n { id: '1', label: 'one', after: ['3'] },\n { id: '2', label: 'two', before: ['1'] },\n { id: '3', label: 'three' }\n]\nMenu:
\n- ---\n- 3\n- 2\n- 1\n\n\nAdicione itens para menus e menus de contexto para aplicações nativas.
\n
Processo: Main
\nVeja Menu para exemplos.
new MenuItem(options)options Objectclick Function (optional) - Will be called with click(menuItem, browserWindow, event) when the menu item is clicked.menuItem MenuItembrowserWindow BrowserWindow | undefined - This will not be defined if no window is open.event KeyboardEventrole String (optional) - Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu - Define the action of the menu item, when specified the click property will be ignored. See roles.type String (opcional) - Pode ser normal, separator, submenu, checkbox ou radio.label String (optional)sublabel String (optional)toolTip String (optional) macOS - Hover text for this menu item.accelerator Accelerator (opcional) - Atalhoicon (NativeImage | String) (opcional)enabled Boolean (optional) - Se falso, o item do menu vai ser não-clicável e cinza.acceleratorWorksWhenHidden Boolean (optional) macOS - default is true, and when false will prevent the accelerator from triggering the item if the item is not visible`.visible Boolean (opcional) - Se falso, o item do menu será inteiramente escondido.checked Boolean (opcinal) - Deve ser especificado apenas para checkbox ou radio tipos de item de menu.registerAccelerator Boolean (optional) Linux Windows - If false, the accelerator won't be registered with the system, but it will still be displayed. Defaults to true.sharingItem SharingItem (optional) macOS - The item to share when the role is shareMenu.submenu (MenuItemConstructorOptions[] | Menu) (optional) - Should be specified for submenu type menu items. If submenu is specified, the type: 'submenu' can be omitted. If the value is not a Menu then it will be automatically converted to one using Menu.buildFromTemplate.id String (optional) - Unique within a single menu. If defined then it can be used as a reference to this item by the position attribute.before String - Inserts this item before the item with the specified label. If the referenced item doesn't exist the item will be inserted at the end of the menu. Also implies that the menu item in question should be placed in the same “group” as the item.after String - Inserts this item after the item with the specified label. If the referenced item doesn't exist the item will be inserted at the end of the menu.beforeGroupContaining String - Provides a means for a single context menu to declare the placement of their containing group before the containing group of the item with the specified label.afterGroupContaining String - Provides a means for a single context menu to declare the placement of their containing group after the containing group of the item with the specified label.Note: acceleratorWorksWhenHidden is specified as being macOS-only because accelerators always work when items are hidden on Windows and Linux. The option is exposed to users to give them the option to turn it off, as this is possible in native macOS development. This property is only usable on macOS High Sierra 10.13 or newer.
Roles permitem itens de menu items terem funcionamentos pré-definidos.
\nÉ melhor especificar role para qualquer item de menu que utiliza uma role padrão, ao invés de tentar implementar manualmente um funcionamento em uma função de click. O funcionamento built-in role dará a melhor experiência nativa.
O valor de label e de acceleratorsão opcionais quando utilizando uma role e lhes serão dados valores padrão apropriados para cada plataforma.
Every menu item must have either a role, label, or in the case of a separator a type.
A propriedade role pode ter os seguintes valores:
undoabout - Trigger a native about panel (custom message box on Window, which does not provide its own).redocutcopypastepasteAndMatchStyleselectAlldeleteminimize - Minimize current window.close - Close current window.quit - Quit the application.reload - Reload the current window.forceReload - Reload the current window ignoring the cache.toggleDevTools - Toggle developer tools in the current window.togglefullscreen - Toggle full screen mode on the current window.resetZoom - Reset the focused page's zoom level to the original size.zoomIn - Zoom in the focused page by 10%.zoomOut - Zoom out the focused page by 10%.toggleSpellChecker - Enable/disable builtin spell checker.fileMenu - Whole default \"File\" menu (Close / Quit)editMenu - Whole default \"Edit\" menu (Undo, Copy, etc.).viewMenu - Whole default \"View\" menu (Reload, Toggle Developer Tools, etc.)windowMenu - Whole default \"Window\" menu (Minimize, Zoom, etc.).The following additional roles are available on macOS:
\nappMenu - Whole default \"App\" menu (About, Services, etc.)hide - Map to the hide action.hideOthers - Map to the hideOtherApplications action.unhide - Map to the unhideAllApplications action.startSpeaking - Map to the startSpeaking action.stopSpeaking - Map to the stopSpeaking action.front - Map to the arrangeInFront action.zoom - Map to the performZoom action.toggleTabBar - Map to the toggleTabBar action.selectNextTab - Map to the selectNextTab action.selectPreviousTab - Map to the selectPreviousTab action.mergeAllWindows - Map to the mergeAllWindows action.moveTabToNewWindow - Map to the moveTabToNewWindow action.window - The submenu is a \"Window\" menu.help - The submenu is a \"Help\" menu.services - The submenu is a \"Services\" menu. This is only intended for use in the Application Menu and is not the same as the \"Services\" submenu used in context menus in macOS apps, which is not implemented in Electron.recentDocuments - The submenu is an \"Open Recent\" menu.clearRecentDocuments - Map to the clearRecentDocuments action.shareMenu - The submenu is share menu. The sharingItem property must also be set to indicate the item to share.When specifying a role on macOS, label and accelerator are the only options that will affect the menu item. All other options will be ignored. Lowercase role, e.g. toggledevtools, is still supported.
Nota Bene: The enabled and visibility properties are not available for top-level menu items in the tray on macOS.
As seguintes propriedades estão disponíveis em instâncias de MenuItem:
menuItem.idA String indicating the item's unique id, this property can be dynamically changed.
menuItem.labelA String indicating the item's visible label.
menuItem.clickA Function that is fired when the MenuItem receives a click event. It can be called with menuItem.click(event, focusedWindow, focusedWebContents).
event KeyboardEventfocusedWindow BrowserWindowfocusedWebContents WebContentsmenuItem.submenuA Menu (optional) containing the menu item's submenu, if present.
menuItem.typeA String indicating the type of the item. Can be normal, separator, submenu, checkbox or radio.
menuItem.roleA String (optional) indicating the item's role, if set. Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu
menuItem.acceleratorAn Accelerator (optional) indicating the item's accelerator, if set.
menuItem.userAccelerator Readonly macOSAn Accelerator | null indicating the item's user-assigned accelerator for the menu item.
Note: This property is only initialized after the MenuItem has been added to a Menu. Either via Menu.buildFromTemplate or via Menu.append()/insert(). Accessing before initialization will just return null.
menuItem.iconA NativeImage | String (optional) indicating the item's icon, if set.
menuItem.sublabelA String indicating the item's sublabel.
menuItem.toolTip macOSA String indicating the item's hover text.
menuItem.enabledUm Boolean indicando se o item está ativo, essa propriedade pode ser alterada dinamicamente.
menuItem.visibleUm Boolean indicando se o item está visível, essa propriedade pode ser alterada dinamicamente.
menuItem.checkedUm Boolean indicando se o item está ativo ou não, essa propriedade pode ser alterada dinamicamente.
Um item do menu de um checkbox irá mudar a propriedade checked para ativa ou não quando selecionada.
Um item do menu de um radio irá ativar a sua propriedade checked quando clicado, e irá desativar essa propriedade para todos os itens adjacentes no mesmo menu.
Você pode adicionar uma função click para comportamentos adicionais.
menuItem.registerAcceleratorA Boolean indicating if the accelerator should be registered with the system or just displayed.
This property can be dynamically changed.
\nmenuItem.sharingItem macOSA SharingItem indicating the item to share when the role is shareMenu.
This property can be dynamically changed.
\nmenuItem.commandIdA Number indicating an item's sequential unique id.
menuItem.menuA Menu that the item is a part of.
MessageChannelMain is the main-process-side equivalent of the DOM MessageChannel object. Its singular function is to create a pair of connected MessagePortMain objects.
See the Channel Messaging API documentation for more information on using channel messaging.
\n\n\nChannel interface for channel messaging in the main process.
\n
Processo: Main
\nExemplo:
\n// Main process\nconst { MessageChannelMain } = require('electron')\nconst { port1, port2 } = new MessageChannelMain()\nw.webContents.postMessage('port', null, [port2])\nport1.postMessage({ some: 'message' })\n\n// Renderer process\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('port', (e) => {\n // e.ports is a list of ports sent along with this message\n e.ports[0].on('message', (messageEvent) => {\n console.log(messageEvent.data)\n })\n})\nchannel.port1A MessagePortMain property.
channel.port2A MessagePortMain property.
MessagePortMain is the main-process-side equivalent of the DOM MessagePort object. It behaves similarly to the DOM version, with the exception that it uses the Node.js EventEmitter event system, instead of the DOM EventTarget system. This means you should use port.on('message', ...) to listen for events, instead of port.onmessage = ... or port.addEventListener('message', ...)
See the Channel Messaging API documentation for more information on using channel messaging.
\nMessagePortMain is an [EventEmitter][event-emitter].
\n\nPort interface for channel messaging in the main process.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
port.postMessage(message, [transfer])Sends a message from the port, and optionally, transfers ownership of objects to other browsing contexts.
\nport.start()Starts the sending of messages queued on the port. Messages will be queued until this method is called.
\nport.close()Disconnects the port, so it is no longer active.
\nRetorna:
\nmessageEvent Objectdata anyports MessagePortMain[]Emitted when a MessagePortMain object receives a message.
\nEmitted when the remote end of a MessagePortMain object becomes disconnected.
", "title": "MessagePortMain", "description": "Port interface for channel messaging in the main process." }, "/docs/tutorial/message-ports": { "locale": "pt-BR", "slug": "message-ports", "href": "/docs/tutorial/message-ports", "crowdinFileId": "256219", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/message-ports.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "MessagePorts are a web feature that allow passing messages between different contexts. It's like window.postMessage, but on different channels. The goal of this document is to describe how Electron extends the Channel Messaging model, and to give some examples of how you might use MessagePorts in your app.
Here is a very brief example of what a MessagePort is and how it works:
\n// renderer.js ///////////////////////////////////////////////////////////////\n// MessagePorts are created in pairs. A connected pair of message ports is\n// called a channel.\nconst channel = new MessageChannel()\n\n// The only difference between port1 and port2 is in how you use them. Messages\n// sent to port1 will be received by port2 and vice-versa.\nconst port1 = channel.port1\nconst port2 = channel.port2\n\n// It's OK to send a message on the channel before the other end has registered\n// a listener. Messages will be queued until a listener is registered.\nport2.postMessage({ answer: 42 })\n\n// Here we send the other end of the channel, port1, to the main process. It's\n// also possible to send MessagePorts to other frames, or to Web Workers, etc.\nipcRenderer.postMessage('port', null, [port1])\n// main.js ///////////////////////////////////////////////////////////////////\n// In the main process, we receive the port.\nipcMain.on('port', (event) => {\n // When we receive a MessagePort in the main process, it becomes a\n // MessagePortMain.\n const port = event.ports[0]\n\n // MessagePortMain uses the Node.js-style events API, rather than the\n // web-style events API. So .on('message', ...) instead of .onmessage = ...\n port.on('message', (event) => {\n // data is { answer: 42 }\n const data = event.data\n })\n\n // MessagePortMain queues messages until the .start() method has been called.\n port.start()\n})\nThe Channel Messaging API documentation is a great way to learn more about how MessagePorts work.
\nIn the renderer, the MessagePort class behaves exactly as it does on the web. The main process is not a web page, though—it has no Blink integration—and so it does not have the MessagePort or MessageChannel classes. In order to handle and interact with MessagePorts in the main process, Electron adds two new classes: MessagePortMain and MessageChannelMain. These behave similarly to the analogous classes in the renderer.
MessagePort objects can be created in either the renderer or the main process, and passed back and forth using the ipcRenderer.postMessage and WebContents.postMessage methods. Note that the usual IPC methods like send and invoke cannot be used to transfer MessagePorts, only the postMessage methods can transfer MessagePorts.
By passing MessagePorts via the main process, you can connect two pages that might not otherwise be able to communicate (e.g. due to same-origin restrictions).
close eventElectron adds one feature to MessagePort that isn't present on the web, in order to make MessagePorts more useful. That is the close event, which is emitted when the other end of the channel is closed. Ports can also be implicitly closed by being garbage-collected.
In the renderer, you can listen for the close event either by assigning to port.onclose or by calling port.addEventListener('close', ...). In the main process, you can listen for the close event by calling port.on('close', ...).
In this example, your app has a worker process implemented as a hidden window. You want the app page to be able to communicate directly with the worker process, without the performance overhead of relaying via the main process.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, ipcMain, MessageChannelMain } = require('electron')\n\napp.whenReady().then(async () => {\n // The worker process is a hidden BrowserWindow, so that it will have access\n // to a full Blink context (including e.g. <canvas>, audio, fetch(), etc.)\n const worker = new BrowserWindow({\n show: false,\n webPreferences: { nodeIntegration: true }\n })\n await worker.loadFile('worker.html')\n\n // The main window will send work to the worker process and receive results\n // over a MessagePort.\n const mainWindow = new BrowserWindow({\n webPreferences: { nodeIntegration: true }\n })\n mainWindow.loadFile('app.html')\n\n // We can't use ipcMain.handle() here, because the reply needs to transfer a\n // MessagePort.\n ipcMain.on('request-worker-channel', (event) => {\n // For security reasons, let's make sure only the frames we expect can\n // access the worker.\n if (event.senderFrame === mainWindow.webContents.mainFrame) {\n // Create a new channel ...\n const { port1, port2 } = new MessageChannelMain()\n // ... send one end to the worker ...\n worker.webContents.postMessage('new-client', null, [port1])\n // ... and the other end to the main window.\n event.senderFrame.postMessage('provide-worker-channel', null, [port2])\n // Now the main window and the worker can communicate with each other\n // without going through the main process!\n }\n })\n})\n<!-- worker.html ------------------------------------------------------------>\n<script>\nconst { ipcRenderer } = require('electron')\n\nfunction doWork(input) {\n // Something cpu-intensive.\n return input * 2\n}\n\n// We might get multiple clients, for instance if there are multiple windows,\n// or if the main window reloads.\nipcRenderer.on('new-client', (event) => {\n const [ port ] = event.ports\n port.onmessage = (event) => {\n // The event data can be any serializable object (and the event could even\n // carry other MessagePorts with it!)\n const result = doWork(event.data)\n port.postMessage(result)\n }\n})\n</script>\n<!-- app.html --------------------------------------------------------------->\n<script>\nconst { ipcRenderer } = require('electron')\n\n// We request that the main process sends us a channel we can use to\n// communicate with the worker.\nipcRenderer.send('request-worker-channel')\n\nipcRenderer.once('provide-worker-channel', (event) => {\n // Once we receive the reply, we can take the port...\n const [ port ] = event.ports\n // ... register a handler to receive results ...\n port.onmessage = (event) => {\n console.log('received result:', event.data)\n }\n // ... and start sending it work!\n port.postMessage(21)\n})\n</script>\nElectron's built-in IPC methods only support two modes: fire-and-forget (e.g. send), or request-response (e.g. invoke). Using MessageChannels, you can implement a \"response stream\", where a single request responds with a stream of data.
// renderer.js ///////////////////////////////////////////////////////////////\n\nfunction makeStreamingRequest (element, callback) {\n // MessageChannels are lightweight--it's cheap to create a new one for each\n // request.\n const { port1, port2 } = new MessageChannel()\n\n // We send one end of the port to the main process ...\n ipcRenderer.postMessage(\n 'give-me-a-stream',\n { element, count: 10 },\n [port2]\n )\n\n // ... and we hang on to the other end. The main process will send messages\n // to its end of the port, and close it when it's finished.\n port1.onmessage = (event) => {\n callback(event.data)\n }\n port1.onclose = () => {\n console.log('stream ended')\n }\n}\n\nmakeStreamingRequest(42, (data) => {\n console.log('got response data:', event.data)\n})\n// We will see \"got response data: 42\" 10 times.\n// main.js ///////////////////////////////////////////////////////////////////\n\nipcMain.on('give-me-a-stream', (event, msg) => {\n // The renderer has sent us a MessagePort that it wants us to send our\n // response over.\n const [replyPort] = event.ports\n\n // Here we send the messages synchronously, but we could just as easily store\n // the port somewhere and send messages asynchronously.\n for (let i = 0; i < msg.count; i++) {\n replyPort.postMessage(msg.element)\n }\n\n // We close the port when we're done to indicate to the other end that we\n // won't be sending any more messages. This isn't strictly necessary--if we\n // didn't explicitly close the port, it would eventually be garbage\n // collected, which would also trigger the 'close' event in the renderer.\n replyPort.close()\n})\nWhen context isolation is enabled, IPC messages from the main process to the renderer are delivered to the isolated world, rather than to the main world. Sometimes you want to deliver messages to the main world directly, without having to step through the isolated world.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, MessageChannelMain } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(async () => {\n // Create a BrowserWindow with contextIsolation enabled.\n const bw = new BrowserWindow({\n webPreferences: {\n contextIsolation: true,\n preload: path.join(__dirname, 'preload.js')\n }\n })\n bw.loadURL('index.html')\n\n // We'll be sending one end of this channel to the main world of the\n // context-isolated page.\n const { port1, port2 } = new MessageChannelMain()\n\n // It's OK to send a message on the channel before the other end has\n // registered a listener. Messages will be queued until a listener is\n // registered.\n port2.postMessage({ test: 21 })\n\n // We can also receive messages from the main world of the renderer.\n port2.on('message', (event) => {\n console.log('from renderer main world:', event.data)\n })\n port2.start()\n\n // The preload script will receive this IPC message and transfer the port\n // over to the main world.\n bw.webContents.postMessage('main-world-port', null, [port1])\n})\n// preload.js ////////////////////////////////////////////////////////////////\nconst { ipcRenderer } = require('electron')\n\n// We need to wait until the main world is ready to receive the message before\n// sending the port. We create this promise in the preload so it's guaranteed\n// to register the onload listener before the load event is fired.\nconst windowLoaded = new Promise(resolve => {\n window.onload = resolve\n})\n\nipcRenderer.on('main-world-port', async (event) => {\n await windowLoaded\n // We use regular window.postMessage to transfer the port from the isolated\n // world to the main world.\n window.postMessage('main-world-port', '*', event.ports)\n})\n<!-- index.html ------------------------------------------------------------->\n<script>\nwindow.onmessage = (event) => {\n // event.source === window means the message is coming from the preload\n // script, as opposed to from an <iframe> or other source.\n if (event.source === window && event.data === 'main-world-port') {\n const [ port ] = event.ports\n // Once we have the port, we can communicate directly with the main\n // process.\n port.onmessage = (event) => {\n console.log('from main process:', event.data)\n port.postMessage(event.data * 2)\n }\n }\n}\n</script>\nmimeType String (optional) - MIME type of the buffer.charset String (optional) - Charset of the buffer.data Buffer - The actual Buffer content.InputEventtype String - The type of the event, can be mouseDown, mouseUp, mouseEnter, mouseLeave, contextMenu, mouseWheel or mouseMove.x Integery Integerbutton String (optional) - The button pressed, can be left, middle, right.globalX Integer (optional)globalY Integer (optional)movementX Integer (optional)movementY Integer (optional)clickCount Integer (optional)MouseInputEventtype String - The type of the event, can be mouseWheel.deltaX Integer (optional)deltaY Integer (optional)wheelTicksX Integer (optional)wheelTicksY Integer (optional)accelerationRatioX Integer (optional)accelerationRatioY Integer (optional)hasPreciseScrollingDeltas Boolean (optional)canScroll Boolean (optional)Com o Web Workers, é possível executar JavaScript em nível de tarefas de um sistema operacional.
\nÉ possível usar os recursos de Node.js em Electron Web Workers,para fazer issso use a opção nodeIntegrationInWorker deve ser definida como true em webPreferences.
const win = new BrowserWindow({\n webPreferences: {\n nodeIntegrationInWorker: true\n }\n})\nO nodeIntegrationInWorker pode ser usado independente do nodeIntegration, mas o sandbox não deve ser definido para true.
Todos os módulos internos do Node.js são suportados em Web Workers e asar, arquivos ainda podem ser lidos com Node.js APIs. No entando, nenhum dos módulos internos do Electron pode ser usado em um ambiente multitarefa.
Qualquer módulo nativo do Node.js pode ser carregado diretamente em Web Workers, mas é altamente recomendável não fazer isso. A maioria dos módulos nativos existentes foram escritos para ambiente single-threaded (sem multitarefa), usá-los em Web Workers vai levar a falhas e corrupções de memória.
\nObserve que mesmo se um módulo nativo do Node.js é thread-safe (tarefa seguro) ele ainda assim não é seguro para carregá-lo em um Web Worker, porque a função process.dlopen não é thread-safe.
A única maneira de carregar um módulo nativo, com segurança, por enquanto, é certificar-se de que o aplicativo carrega os módulos nativos após começar o Web Workers.
\nprocess.dlopen = () => {\n throw new Error('Load native module is not safe')\n}\nconst worker = new Worker('script.js')\nAlguns tipos de aplicativos que manipulam arquivos talvez queiram oferecer suporte ao recurso de drag & drop (arrastar e soltar) nativo do sistema operacional. Arrastar arquivos para a web é bastante comum e utilizado por muitos sites. Além disso, Electron adicionou suporte para arrastar arquivos e conteúdos de fora do conteúdo web para o mundo do sistema operacional.
\nTo implement this feature in your app, you need to call the webContents.startDrag(item) API in response to the ondragstart event.
An example demonstrating how you can create a file on the fly to be dragged out of the window.
\nIn preload.js use the contextBridge to inject a method window.electron.startDrag(...) that will send an IPC message to the main process.
const { contextBridge, ipcRenderer } = require('electron')\nconst path = require('path')\n\ncontextBridge.exposeInMainWorld('electron', {\n startDrag: (fileName) => {\n ipcRenderer.send('ondragstart', path.join(process.cwd(), fileName))\n }\n})\nAdd a draggable element to index.html, and reference your renderer script:
<div style=\"border:2px solid black;border-radius:3px;padding:5px;display:inline-block\" draggable=\"true\" id=\"drag\">Drag me</div>\n<script src=\"renderer.js\"></script>\nIn renderer.js set up the renderer process to handle drag events by calling the method you added via the contextBridge above.
document.getElementById('drag').ondragstart = (event) => {\n event.preventDefault()\n window.electron.startDrag('drag-and-drop.md')\n}\nIn the Main process (main.js file), expand the received event with a path to the file that is being dragged and an icon:
const { ipcMain } = require('electron')\n\nipcMain.on('ondragstart', (event, filePath) => {\n event.sender.startDrag({\n file: filePath,\n icon: '/path/to/icon.png'\n })\n})\nAfter launching the Electron application, try dragging and dropping the item from the BrowserWindow onto your desktop. In this guide, the item is a Markdown file located in the root of the project:
\n
\n\n\nCria ícones de bandeija, dock e aplicações usando arquivos PNG ou JPG.
\n
In Electron, for the APIs that take images, you can pass either file paths or NativeImage instances. An empty image will be used when null is passed.
Por exemplo, quando for criar uma bandeija ou designar um ícone para uma janela, você pode passar um caminho de arquivo de imagem com a String:
const { BrowserWindow, Tray } = require('electron')\n\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconst win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })\nconsole.log(appIcon, win)\nOr read the image from the clipboard, which returns a NativeImage:
const { clipboard, Tray } = require('electron')\nconst image = clipboard.readImage()\nconst appIcon = new Tray(image)\nconsole.log(appIcon)\nCurrently PNG and JPEG image formats are supported. PNG is recommended because of its support for transparency and lossless compression.
On Windows, you can also load ICO icons from file paths. For best visual quality, it is recommended to include at least the following sizes in the:
Confira a seção Size requirements nesse artigo.
\nEm plataformas que possuem suporte para high-DPI como a tela Retina da Apple, você pode acrescentar @2x depois do nome base da imagem para marcar-la como imagem de alta resolução.
For example, if icon.png is a normal image that has standard resolution, then icon@2x.png will be treated as a high resolution image that has double DPI density.
If you want to support displays with different DPI densities at the same time, you can put images with different sizes in the same folder and use the filename without DPI suffixes. Como por exemplo:
\nimages/\n├── icon.png\n├── icon@2x.png\n└── icon@3x.png\nconst { Tray } = require('electron')\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconsole.log(appIcon)\nThe following suffixes for DPI are also supported:
\n@1x@1.25x@1.33x@1.4x@1.5x@1.8x@2x@2.5x@3x@4x@5xTemplate images consist of black and an alpha channel. Imagens padrão não são destinadas a serem usadas sozinhas, e geralmente são acompanhadas por outros conteúdos para criar a aparência final desejada.
\nThe most common case is to use template images for a menu bar icon, so it can adapt to both light and dark menu bars.
\nNota: Imagens padrão são suportadas somente no macOS.
\nTo mark an image as a template image, its filename should end with the word Template. Como por exemplo:
xxxTemplate.pngxxxTemplate@2x.pngO módulo nativeImage possui os seguintes métodos, todos os quais retornam uma instância da classe NativeImage:
nativeImage.createEmpty()Retorna NativeImage
Cria uma instância NativeImage vazia.
nativeImage.createThumbnailFromPath(path, maxSize) macOS Windowspath String - path to a file that we intend to construct a thumbnail out of.maxSize Size - the maximum width and height (positive numbers) the thumbnail returned can be. The Windows implementation will ignore maxSize.height and scale the height according to maxSize.width.Returns Promise<NativeImage> - fulfilled with the file's thumbnail preview image, which is a NativeImage.
nativeImage.createFromPath(path)path StringRetorna NativeImage
Cria uma nova instância NativeImage de um arquivo localizado em path. Esse método retorna uma imagem vazia se path não existir, não poder ser lido, ou não ser uma imagem válida.
const nativeImage = require('electron').nativeImage\n\nconst image = nativeImage.createFromPath('/Users/somebody/images/icon.png')\nconsole.log(image)\nnativeImage.createFromBitmap(buffer, options)buffer Bufferoptions Objectwidth Integerheight IntegerscaleFactor Double (opcional) - Padrão sendo 1.0.Retorna NativeImage
Creates a new NativeImage instance from buffer that contains the raw bitmap pixel data returned by toBitmap(). The specific format is platform-dependent.
nativeImage.createFromBuffer(buffer[, options])buffer Bufferoptions (opcional)width Integer (opicional) - Necessário para buffers de bitmap.height Integer (opicional) - Necessário para buffers de bitmap.scaleFactor Double (opcional) - Padrão sendo 1.0.Retorna NativeImage
Cria uma nova instância NativeImage a partir do buffer. Tries to decode as PNG or JPEG first.
nativeImage.createFromDataURL(dataURL)dataURL StringRetorna NativeImage
Cria uma nova instância NativeImage a partir do dataURL.
nativeImage.createFromNamedImage(imageName[, hslShift]) macOSRetorna NativeImage
Cria uma nova instância de NativeImage a partir de NSImage o qual direciona para o dado nome da Imagem. Veja System Icons para uma lista dos possíveis valores.
O hslShift é aplicado à imagem com as seguintes regras:
hsl_shift[0] (hue): The absolute hue value for the image - 0 and 1 map to 0 and 360 on the hue color wheel (red).hsl_shift[1] (saturation): A saturation shift for the image, with the following key values: 0 = remove all color. 0.5 = leave unchanged. 1 = fully saturate the image.hsl_shift[2] (lightness): A lightness shift for the image, with the following key values: 0 = remove all lightness (make all pixels black). 0.5 = leave unchanged. 1 = full lightness (make all pixels white).Isso significa que [-1, 0, 1] irá deixar a imagem totalmente branca e [-1, 1, 0] irá deixar a imagem totalmente preta.
In some cases, the NSImageName doesn't match its string representation; one example of this is NSFolderImageName, whose string representation would actually be NSFolder. Therefore, you'll need to determine the correct string representation for your image before passing it in. This can be done with the following:
echo -e '#import <Cocoa/Cocoa.h>\\nint main() { NSLog(@\"%@\", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test
where SYSTEM_IMAGE_NAME should be replaced with any value from this list.
\n\nNatively wrap images such as tray, dock, and application icons.
\n
Process: Main, Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Os seguintes métodos estão disponíveis nas instâncias da classe NativeImage:
image.toPNG([options])options (opcional)scaleFactor Double (opcional) - Padrão sendo 1.0.Retorna Buffer - Um Buffer que contém os dados codificados de PNG da imagem.
image.toJPEG(quality)quality Integer - Between 0 - 100.Retorna Buffer - Um Buffer que contém os dados codificados de JPG da imagem.
image.toBitmap([options])options (opcional)scaleFactor Double (opcional) - Padrão sendo 1.0.Retorna Buffer - Um Buffer que contém uma copia dos dados de bitmap crus (sem alterações) da imagem.
image.toDataURL([options])options (opcional)scaleFactor Double (opcional) - Padrão sendo 1.0.Retorna String - Os dados de URL da imagem.
image.getBitmap([options])options (opcional)scaleFactor Double (opcional) - Padrão sendo 1.0.Retorna Buffer - Um Buffer que contém os dados de bitmap crus (sem alterações) da imagem.
The difference between getBitmap() and toBitmap() is that getBitmap() does not copy the bitmap data, so you have to use the returned Buffer immediately in current event loop tick; otherwise the data might be changed or destroyed.
image.getNativeHandle() no macOSReturns Buffer - A Buffer that stores C pointer to underlying native handle of the image. On macOS, a pointer to NSImage instance would be returned.
Perceba que o ponteiro retornado é um ponteiro fraco para a imagem nativa subjacente invés de uma cópia, então você deve se certificar de que a instância nativeImage esteja próxima.
image.isEmpty()Returns Boolean - Whether the image is empty.
image.getSize([scaleFactor])scaleFactor Double (opcional) - Padrão sendo 1.0.Retorna Size.
If scaleFactor is passed, this will return the size corresponding to the image representation most closely matching the passed value.
image.setTemplateImage(option)option BooleanMarca a imagem como uma imagem padrão.
\nimage.isTemplateImage()Retorna Boolean - sendo a imagem uma imagem padrão ou não.
image.crop(rect)rect Rectangle - A área da imagem a ser cortada.Retorna NativeImage - A imagem cortada.
image.resize(options)options Objectwidth Integer (optional) - Defaults to the image's width.height Integer (optional) - Defaults to the image's height.quality String (optional) - The desired quality of the resize image. Os valores possíveis são: good, better ou best. O padrão é best. Esses valores apresentam a qualidade/velocidade de troca desejada. They are translated into an algorithm-specific method that depends on the capabilities (CPU, GPU) of the underlying platform. It is possible for all three methods to be mapped to the same algorithm on a given platform.Retorna NativeImage - A imagem redimensionada.
Se apenas o height ou o width forem definidos então a atual proporção de tela da imagem será preservada na imagem redimensionada.
image.getAspectRatio([scaleFactor])scaleFactor Double (opcional) - Padrão sendo 1.0.Retorna Float - A proporção de tela da imagem.
If scaleFactor is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value.
image.getScaleFactors()Returns Float[] - An array of all scale factors corresponding to representations for a given nativeImage.
image.addRepresentation(options)options ObjectscaleFactor Double - The scale factor to add the image representation for.width Integer (optional) - Padrão sendo 0. Required if a bitmap buffer is specified as buffer.height Integer (opcional) - Padrão sendo 0. Required if a bitmap buffer is specified as buffer.buffer Buffer (opcional) - O buffer contendo os dados crus (sem alteração) da imagem.dataURL String (optional) - The data URL containing either a base 64 encoded PNG or JPEG image.Add an image representation for a specific scale factor. This can be used to explicitly add different scale factor representations to an image. This can be called on empty images.
\nnativeImage.isMacTemplateImage no macOSA Boolean property that determines whether the image is considered a template image.
Please note that this property only has an effect on macOS.
", "title": "nativeImage", "description": "Cria ícones de bandeija, dock e aplicações usando arquivos PNG ou JPG." }, "/docs/api/native-theme": { "locale": "pt-BR", "slug": "native-theme", "href": "/docs/api/native-theme", "crowdinFileId": "256343", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/native-theme.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRead and respond to changes in Chromium's native color theme.
\n
Processo: Main
\nO módulo nativeTheme emite os seguintes eventos:
Emitted when something in the underlying NativeTheme has changed. This normally means that either the value of shouldUseDarkColors, shouldUseHighContrastColors or shouldUseInvertedColorScheme has changed. You will have to check them to determine which one has changed.
The nativeTheme module has the following properties:
nativeTheme.shouldUseDarkColors ReadonlyA Boolean for if the OS / Chromium currently has a dark mode enabled or is being instructed to show a dark-style UI. If you want to modify this value you should use themeSource below.
nativeTheme.themeSourceA String property that can be system, light or dark. Ela é usada para sobrepor e substituir o valor que o Chromium escolheu para usar internamente.
Setting this property to system will remove the override and everything will be reset to the OS default. By default themeSource is system.
Settings this property to dark will have the following effects:
nativeTheme.shouldUseDarkColors will be true when accessedprefers-color-scheme CSS query will match dark mode.updated event will be emittedSettings this property to light will have the following effects:
nativeTheme.shouldUseDarkColors will be false when accessedprefers-color-scheme CSS query will match light mode.updated event will be emittedThe usage of this property should align with a classic \"dark mode\" state machine in your application where the user has three options.
\nPadrão do Sistema --> themeSource = 'system'Modo Escuro --> themeSource = 'dark'Modo Claro --> themeSource = 'light'Your application should then always use shouldUseDarkColors to determine what CSS to apply.
nativeTheme.shouldUseHighContrastColors macOS Windows ReadonlyA Boolean for if the OS / Chromium currently has high-contrast mode enabled or is being instructed to show a high-contrast UI.
nativeTheme.shouldUseInvertedColorScheme macOS Windows ReadonlyA Boolean for if the OS / Chromium currently has an inverted color scheme or is being instructed to use an inverted color scheme.
\n\nIssue HTTP/HTTPS requests using Chromium's native networking library
\n
Processo: Main
\nThe net module is a client-side API for issuing HTTP(S) requests. It is similar to the HTTP and HTTPS modules of Node.js but uses Chromium's native networking library instead of the Node.js implementation, offering better support for web proxies. It also supports checking network status.
The following is a non-exhaustive list of why you may consider using the net module instead of the native Node.js modules:
The API components (including classes, methods, properties and event names) are similar to those used in Node.js.
\nExample usage:
\nconst { app } = require('electron')\napp.whenReady().then(() => {\n const { net } = require('electron')\n const request = net.request('https://github.com')\n request.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`)\n console.log(`HEADERS: ${JSON.stringify(response.headers)}`)\n response.on('data', (chunk) => {\n console.log(`BODY: ${chunk}`)\n })\n response.on('end', () => {\n console.log('No more data in response.')\n })\n })\n request.end()\n})\nThe net API can be used only after the application emits the ready event. Trying to use the module before the ready event will throw an error.
O módulo net possui os seguintes métodos:
net.request(options)options (ClientRequestConstructorOptions | String) - The ClientRequest constructor options.Retorna ClientRequest
Creates a ClientRequest instance using the provided options which are directly forwarded to the ClientRequest constructor. The net.request method would be used to issue both secure and insecure HTTP requests according to the specified protocol scheme in the options object.
net.isOnline()Returns Boolean - Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
net.online ReadonlyA Boolean property. Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
\n\nLogging network events for a session.
\n
Processo: Main
\nconst { netLog } = require('electron')\n\napp.whenReady().then(async () => {\n await netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nSee --log-net-log to log network events throughout the app's lifecycle.
Nota: Todos os métodos, a menos que seja especificados, só podem ser usados após o evento app quando é emitido.
netLog.startLogging(path[, options])path String - File path to record network logs.options (opcional)captureMode String (optional) - What kinds of data should be captured. By default, only metadata about requests will be captured. Setting this to includeSensitive will include cookies and authentication data. Setting it to everything will include all bytes transferred on sockets. Can be default, includeSensitive or everything.maxFileSize Number (optional) - When the log grows beyond this size, logging will automatically stop. Defaults to unlimited.Returns Promise<void> - resolves when the net log has begun recording.
Starts recording network events to path.
netLog.stopLogging()Returns Promise<void> - resolves when the net log has been flushed to disk.
Stops recording network events. If not called, net logging will automatically end when app quits.
\nnetLog.currentlyLogging ReadonlyA Boolean property that indicates whether network logs are currently being recorded.
EventnewGuest BrowserWindow (optional)\n\nCriar notificações para o desktop do sistema
\n
Processo: Main
\nIf you want to show Notifications from a renderer process you should use the HTML5 Notification API
\n\n\nCriar notificações para o desktop do sistema
\n
Processo: Main
\nNotification é um EventEmitter.
O mesmo cria um novo Notification com propriedades nativas informadas como a opção options.
A classe Notification tem os seguintes métodos estáticos:
Notification.isSupported()Retorna Boolean - se as notificações do desktop são suportadas ou não pelo atual sistema
new Notification([options])options (opcional)title String (optional) - A title for the notification, which will be shown at the top of the notification window when it is shown.subtitle String (optional) macOS - A subtitle for the notification, which will be displayed below the title.body String (optional) - The body text of the notification, which will be displayed below the title or subtitle.silent Boolean (optional) - Whether or not to emit an OS notification noise when showing the notification.icon (String | NativeImage) (optional) - An icon to use in the notification.hasReply Boolean (optional) macOS - Whether or not to add an inline reply option to the notification.timeoutType String (optional) Linux Windows - The timeout duration of the notification. Can be 'default' or 'never'.replyPlaceholder String (optional) macOS - The placeholder to write in the inline reply input field.sound String (optional) macOS - The name of the sound file to play when the notification is shown.urgency String (optional) Linux - The urgency level of the notification. Can be 'normal', 'critical', or 'low'.actions NotificationAction[] (optional) macOS - Actions to add to the notification. Please read the available actions and limitations in the NotificationAction documentation.closeButtonText String (optional) macOS - A custom title for the close button of an alert. An empty string will cause the default localized text to be used.toastXml String (optional) Windows - A custom description of the Notification on Windows superseding all properties above. Provides full customization of design and behavior of the notification.Objects created with new Notification emit the following events:
Note: Some events are only available on specific operating systems and are labeled as such.
\nRetorna:
\nevent EventEmitted when the notification is shown to the user, note this could be fired multiple times as a notification can be shown multiple times through the show() method.
Retorna:
\nevent EventEmitted when the notification is clicked by the user.
\nRetorna:
\nevent EventEmitted when the notification is closed by manual intervention from the user.
\nThis event is not guaranteed to be emitted in all cases where the notification is closed.
\nRetorna:
\nevent Eventreply String - The string the user entered into the inline reply field.Emitted when the user clicks the \"Reply\" button on a notification with hasReply: true.
Retorna:
\nevent Eventindex Number - The index of the action that was activated.Retorna:
\nevent Eventerror String - The error encountered during execution of the show() method.Emitted when an error is encountered while creating and showing the native notification.
\nObjectos criados com new Notification possuem os seguintes métodos de instâncias:
notification.show()Immediately shows the notification to the user, please note this means unlike the HTML5 Notification implementation, instantiating a new Notification does not immediately show it to the user, you need to call this method before the OS will display it.
If the notification has been shown before, this method will dismiss the previously shown notification and create a new one with identical properties.
\nnotification.close()Dismisses the notification.
\nnotification.titleA String property representing the title of the notification.
notification.subtitleA String property representing the subtitle of the notification.
notification.bodyA String property representing the body of the notification.
notification.replyPlaceholderA String property representing the reply placeholder of the notification.
notification.soundA String property representing the sound of the notification.
notification.closeButtonTextA String property representing the close button text of the notification.
notification.silentA Boolean property representing whether the notification is silent.
notification.hasReplyA Boolean property representing whether the notification has a reply action.
notification.urgency LinuxA String property representing the urgency level of the notification. Can be 'normal', 'critical', or 'low'.
Default is 'low' - see NotifyUrgency for more information.
\nnotification.timeoutType Linux WindowsA String property representing the type of timeout duration for the notification. Can be 'default' or 'never'.
If timeoutType is set to 'never', the notification never expires. It stays open until closed by the calling API or the user.
notification.actionsA NotificationAction[] property representing the actions of the notification.
notification.toastXml WindowsA String property representing the custom Toast XML of the notification.
On macOS, you can specify the name of the sound you'd like to play when the notification is shown. Any of the default sounds (under System Preferences > Sound) can be used, in addition to custom sound files. Be sure that the sound file is copied under the app bundle (e.g., YourApp.app/Contents/Resources), or one of the following locations:
~/Library/Sounds/Library/Sounds/Network/Library/Sounds/System/Library/SoundsSee the NSSound docs for more information.
type String - The type of action, can be button.text String (optional) - The label for the given action.| Action Type | Platform Support | Usage of text | Default text | Limitations |
|---|---|---|---|---|
button | macOS | Used as the label for the button | \"Show\" (or a localized string by system default if first of such button, otherwise empty) | Only the first one is used. If multiple are provided, those beyond the first will be listed as additional actions (displayed when mouse active over the action button). Any such action also is incompatible with hasReply and will be ignored if hasReply is true. |
In order for extra notification buttons to work on macOS your app must meet the following criteria.
\nNSUserNotificationAlertStyle set to alert in the Info.plist.If either of these requirements are not met the button won't appear.
", "title": "NotificationAction Object", "description": "" }, "/docs/api/structures/notification-response": { "locale": "pt-BR", "slug": "notification-response", "href": "/docs/api/structures/notification-response", "crowdinFileId": "256473", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/notification-response.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "actionIdentifier String - The identifier string of the action that the user selected.date Number - The delivery date of the notification.identifier String - The unique identifier for this notification request.userInfo Record<String, any> - A dictionary of custom information associated with the notification.userText String (optional) - The text entered or chosen by the user.All three operating systems provide means for applications to send notifications to the user. The technique of showing notifications is different for the Main and Renderer processes.
\nFor the Renderer process, Electron conveniently allows developers to send notifications with the HTML5 Notification API, using the currently running operating system's native notification APIs to display it.
\nTo show notifications in the Main process, you need to use the Notification module.
\nStarting with a working application from the Quick Start Guide, add the following line to the index.html file before the closing </body> tag:
<script src=\"renderer.js\"></script>\n...and add the renderer.js file:
const NOTIFICACAO_TITULO = 'Title'\nconst NOTIFICACAO_CORPO = 'Notification from the Renderer process. Click to log to console.'\nconst CLICK_MENSAGEM = 'Notificação clicada!'\n\nnew Notification(NOTIFICACAO_TITULO, { body: NOTIFICACAO_CORPO })\n .onclick = () => console.log(CLICK_MENSAGEM)\nApós iniciar o aplicativo Electron, você verá a notificação:
\n
Além disso, se você clicar na notificação, o DOM atualizará para exibir 'Notificação clicada!\".
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { Notification } = require('electron')\n\nconst NOTIFICATION_TITLE = 'Basic Notification'\nconst NOTIFICATION_BODY = 'Notification from the Main process'\n\nfunction showNotification () {\n new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()\n}\n\napp.whenReady().then(createWindow).then(showNotification)\nApós executar a aplicação em Electron, você deve ver a notificação do sistema:
\n
Enquanto o código e a experiência do usuário em sistemas operacionais sejam semelhantes, há algumas diferenças.
\nnode_modules\\electron\\dist\\electron.exe to your Start Menu also does the trick. Navegue até o arquivo no Explorer, clique com o botão direito e \"Fixar em Iniciar\". You will then need to add the line app.setAppUserModelId(process.execPath) to your main process to see notifications.O Electron tenta automatizar o trabalho em torno do Application User Model ID. Quando o Electron é usado juntamente com o framework de instalação e atualização Squirrel, atalhos serão definidos automaticamente corretamente. Além disso, Electron irá detectar que o Squirrel foi usado e irá chamar automaticamente app.setAppUserModelId() com o valor correto. Durante o desenvolvimento, você pode ter que chamar app.setAppUserModelId() por si só.
Além disso, no Windows 8, o comprimento máximo para o corpo da notificação é de 250 caracteres, o time do Windows recomenda que a notificações tenha 200 caracteres. Dito isto, essa limitação foi removida no Windows 10, mas a equipe do Windows pede que os desenvolvedores seja razoável. Tentativa de enviar gigantescas quantidades de texto pela API (milhares de caracteres) pode resultar em instabilidade.
\nVersões posteriores do Windows permitem notificações avançadas, com os modelos personalizados, imagens e outros elementos flexíveis. Para enviar essas notificações(tanto do processo principal, quanto do processo de renderização), use o módulo de userland electron-windows-notifications, que usa addons nativos Node parar enviar ToastNotification e objetos TileNotification.
While notifications including buttons work with electron-windows-notifications, handling replies requires the use of electron-windows-interactive-notifications, which helps with registering the required COM components and calling your Electron app with the entered user data.
To detect whether or not you're allowed to send a notification, use the userland module electron-notification-state.
\nThis allows you to determine ahead of time whether or not Windows will silently throw the notification away.
\nAs notificações são simples no macOS, mas você deve estar ciente das diretrizes da Interface Humana da Apple sobre notificações.
\nNote que as notificações tem um limite de 256 bytes de tamanho e serão truncadas se você exceder esse limite.
\nPara detectar se é ou não permitido enviar uma notificação, use o módulo da userland electron-notification-state.
\nIsso permitirá você detectar antes do tempo ou não a notificação que será exibida.
\nNotificações são enviadas usando libnotify que podem mostrar notificações em qualquer ambiente de trabalho que segue as Especificação de Notificação em Desktop, incluindo Cinnamon, Enlightenment, Unity, GNOME, KDE.
Offscreen rendering lets you obtain the content of a BrowserWindow in a bitmap, so it can be rendered anywhere, for example, on texture in a 3D scene. The offscreen rendering in Electron uses a similar approach to that of the Chromium Embedded Framework project.
Notes:
\npaint event to be more efficient.GPU accelerated rendering means that the GPU is used for composition. Because of that, the frame has to be copied from the GPU which requires more resources, thus this mode is slower than the Software output device. The benefit of this mode is that WebGL and 3D CSS animations are supported.
\nThis mode uses a software output device for rendering in the CPU, so the frame generation is much faster. As a result, this mode is preferred over the GPU accelerated one.
\nTo enable this mode, GPU acceleration has to be disabled by calling the app.disableHardwareAcceleration() API.
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\n\napp.disableHardwareAcceleration()\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ webPreferences: { offscreen: true } })\n\n win.loadURL('https://github.com')\n win.webContents.on('paint', (event, dirty, image) => {\n fs.writeFileSync('ex.png', image.toPNG())\n })\n win.webContents.setFrameRate(60)\n})\nAfter launching the Electron application, navigate to your application's working folder, where you'll find the rendered image.
", "title": "Renderização fora da tela", "description": "" }, "/docs/tutorial/online-offline-events": { "locale": "pt-BR", "slug": "online-offline-events", "href": "/docs/tutorial/online-offline-events", "crowdinFileId": "256229", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/online-offline-events.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Online and offline event detection can be implemented in the Renderer process using the navigator.onLine attribute, part of standard HTML5 API.
The navigator.onLine attribute returns:
false if all network requests are guaranteed to fail (e.g. when disconnected from the network).true in all other cases.Since many cases return true, you should treat with care situations of getting false positives, as we cannot always assume that true value means that Electron can access the Internet. For example, in cases when the computer is running a virtualization software that has virtual Ethernet adapters in \"always connected\" state. Therefore, if you want to determine the Internet access status of Electron, you should develop additional means for this check.
Starting with an HTML file index.html, this example will demonstrate how the navigator.onLine API can be used to build a connection status indicator.
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n</head>\n<body>\n <h1>Connection status: <strong id='status'></strong></h1>\n <script src=\"renderer.js\"></script>\n</body>\n</html>\nIn order to mutate the DOM, create a renderer.js file that adds event listeners to the 'online' and 'offline' window events. The event handler sets the content of the <strong id='status'> element depending on the result of navigator.onLine.
function updateOnlineStatus () {\n document.getElementById('status').innerHTML = navigator.onLine ? 'online' : 'offline'\n}\n\nwindow.addEventListener('online', updateOnlineStatus)\nwindow.addEventListener('offline', updateOnlineStatus)\n\nupdateOnlineStatus()\nFinally, create a main.js file for main process that creates the window.
const { app, BrowserWindow } = require('electron')\n\nfunction createWindow () {\n const onlineStatusWindow = new BrowserWindow({\n width: 400,\n height: 100\n })\n\n onlineStatusWindow.loadFile('index.html')\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nApós iniciar o aplicativo Electron, você verá a notificação:
\n
\n", "title": "Detecção de Evento Online/Offline", "description": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API." }, "/docs/development/patches": { "locale": "pt-BR", "slug": "patches", "href": "/docs/development/patches", "crowdinFileId": "256161", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/patches.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API.
\n
Electron is built on two major upstream projects: Chromium and Node.js. Each of these projects has several of their own dependencies, too. We try our best to use these dependencies exactly as they are but sometimes we can't achieve our goals without patching those upstream dependencies to fit our use cases.
\nEvery patch in Electron is a maintenance burden. When upstream code changes, patches can break—sometimes without even a patch conflict or a compilation error. It's an ongoing effort to keep our patch set up-to-date and effective. So we strive to keep our patch count at a minimum. To that end, every patch must describe its reason for existence in its commit message. That reason must be one of the following:
\nProfile). Include reasoning about why the change cannot be implemented without a patch (e.g. by subclassing or copying the code).In general, all the upstream projects we work with are friendly folks and are often happy to accept refactorings that allow the code in question to be compatible with both Electron and the upstream project. (See e.g. this change in Chromium, which allowed us to remove a patch that did the same thing, or this change in Node, which was a no-op for Node but fixed a bug in Electron.) We should aim to upstream changes whenever we can, and avoid indefinite-lifetime patches.
\nIf you find yourself in the unfortunate position of having to make a change which can only be made through patching an upstream project, you'll need to know how to manage patches in Electron.
\nAll patches to upstream projects in Electron are contained in the patches/ directory. Each subdirectory of patches/ contains several patch files, along with a .patches file which lists the order in which the patches should be applied. Think of these files as making up a series of git commits that are applied on top of the upstream project after we check it out.
patches\n├── config.json <-- this describes which patchset directory is applied to what project\n├── chromium\n│ ├── .patches\n│ ├── accelerator.patch\n│ ├── add_contentgpuclient_precreatemessageloop_callback.patch\n│ ⋮\n├── node\n│ ├── .patches\n│ ├── add_openssl_is_boringssl_guard_to_oaep_hash_check.patch\n│ ├── build_add_gn_build_files.patch\n│ ⋮\n⋮\nTo help manage these patch sets, we provide two tools: git-import-patches and git-export-patches. git-import-patches imports a set of patch files into a git repository by applying each patch in the correct order and creating a commit for each one. git-export-patches does the reverse; it exports a series of git commits in a repository into a set of files in a directory and an accompanying .patches file.
\n\nSide note: the reason we use a
\n.patchesfile to maintain the order of applied patches, rather than prepending a number like001-to each file, is because it reduces conflicts related to patch ordering. It prevents the situation where two PRs both add a patch at the end of the series with the same numbering and end up both getting merged resulting in a duplicate identifier, and it also reduces churn when a patch is added or deleted in the middle of the series.
$ cd src/third_party/electron_node\n$ vim some/code/file.cc\n$ git commit\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\n\n\nNOTE:
\ngit-export-patchesignores any uncommitted files, so you must create a commit if you want your changes to be exported. The subject line of the commit message will be used to derive the patch file name, and the body of the commit message should include the reason for the patch's existence.
Re-exporting patches will sometimes cause shasums in unrelated patches to change. This is generally harmless and can be ignored (but go ahead and add those changes to your PR, it'll stop them from showing up for other people).
\n$ cd src/v8\n$ vim some/code/file.cc\n$ git log\n# Find the commit sha of the patch you want to edit.\n$ git commit --fixup [COMMIT_SHA]\n$ git rebase --autosquash -i [COMMIT_SHA]^\n$ ../electron/script/git-export-patches -o ../electron/patches/v8\n$ vim src/electron/patches/node/.patches\n# Delete the line with the name of the patch you want to remove\n$ cd src/third_party/electron_node\n$ git reset --hard refs/patches/upstream-head\n$ ../../electron/script/git-import-patches ../../electron/patches/node\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\nNote that git-import-patches will mark the commit that was HEAD when it was run as refs/patches/upstream-head. This lets you keep track of which commits are from Electron patches (those that come after refs/patches/upstream-head) and which commits are in upstream (those before refs/patches/upstream-head).
When updating an upstream dependency, patches may fail to apply cleanly. Often, the conflict can be resolved automatically by git with a 3-way merge. You can instruct git-import-patches to use the 3-way merge algorithm by passing the -3 argument:
$ cd src/third_party/electron_node\n# If the patch application failed midway through, you can reset it with:\n$ git am --abort\n# And then retry with 3-way merge:\n$ ../../electron/script/git-import-patches -3 ../../electron/patches/node\nIf git-import-patches -3 encounters a merge conflict that it can't resolve automatically, it will pause and allow you to resolve the conflict manually. Once you have resolved the conflict, git add the resolved files and continue to apply the rest of the patches by running git am --continue.
Desenvolvedores frequentemente perguntam sobre formas de otimizar a performance de aplicações Electron. Engenheiros de software, consumidores e desenvolvedores de frameworks nem sempre estão de acordo com uma simples definição de a \"performance\" acontece. Esse documento demonstra algumas práticas favoritas dos mantenedores do Electron, com a finalidade de reduzir consumo de memória, CPU e recursos de disco, enquanto garante que o APP seja responsivo a entrada do usuário e complete as operações da forma mais rápida possível. Além disso, nós queremos todas os meios de performance para manter um alto padrão para a segurança dos Apps.
\nConhecimento e informação sobre como construir websites de performance com JavaScript geralmente também se aplicam à aplicativos Electron. Até certo ponto,recursos discutidos para performance de aplicações Node.js também se aplicam,porém fique atento que o termo \"performance\" no backend Node.js tem um significado diferente do de uma aplicação cliente.
\nEsta lista é providenciada para sua conveniência - e é muito parecida com nossa checklist de segurança - não pretende ser cansativa. Provavelmente é possível construir uma aplicação Electron lenta seguindo todos os passos listados abaixo. Electron é uma poderosa plataforma de desenvolvimento que deixa você, o desenvolvedor, fazer mais ou menos o que você quiser. Toda essa liberdade significa que a performance é amplamente sua responsabilidade.
\nA lista abaixo contém um número de passos razoavelmente diretos e fáceis de implementar. Entretanto, construir a melhor versão da sua aplicação vai exigir que você vá além de uma série de etapas. Ao invés disso, você deve examinar de perto todo o código rodando em sua aplicação sendo cuidadoso, meticuloso e observador. Onde estão os gargalos ? Quando o usuário clica em um botão, quais operações gastam mais tempo de processamento ? Enquanto a aplicação está ociosa, quais objetos gastam mais memória ?
\nDia após dia nós temos visto que a estratégia mais bem sucedida para construir aplicações Electron com bom desempenho é analisar o código rodando, encontrar a parte que mais precisa de recursos e otimizá-la. Repetir esse processo incansavelmente, de novo e de novo vai aumentar drasticamente a performance da sua aplicação. Experiências trabalhando com aplicativos maiores como o Visual Studio Code ou o Slack tem mostrado que essa prática é de longe a estratégia mais confiável para aumentar a performance.
\nPara aprender mais sobre como analisar o código da sua aplicação se familiarize com as Ferramentas de Desenvolvedor do Chrome. For advanced analysis looking at multiple processes at once, consider the Chrome Tracing tool.
\nSeu aplicativo pode ser um pouco mais enxuto, rápido e geralmente menos faminto por recursos se você se atentar a esses passos.
\nAntes de adicionar um módulo Node.js em sua aplicação,examine-o primeiro. Quantas dependências esse módulo inclui ? Que tipo de recursos são necessários para ele simplesmente ser chamado em um require() ? Você pode descobrir que o módulo com mais downloads nos pacotes NPM registrados ou com mais estrelas no GitHub, não é de fato o mais enxuto ou menor disponível.
A razão por trás dessa recomendação é melhor ilustrada com um exemplo do mundo real. Durante os primórdios do Electron, garantir a descoberta de conexão de rede era um problema, resultando em muitas aplicações usando um módulo apenas para usar o método isOnline().
O módulo detecta sua conexão tentando chegar a um número conhecido de pontos de extremidade. Para a lista destes pontos, depende de um módulo diferente, que também continha uma lista de portas já conhecidas. Essa dependência por si mesma depende de um módulo contendo informações sobre portas, que vem em forma de um arquivo JSON com mais de 100.000 linhas de conteúdo. Sempre que o módulo é carregado (normalmente em um require('módulo)), isto vai carregar todas as suas dependências e eventualmente ler e transformar esse arquivo JSON. Interpretar milhares de linhas de um JSON é uma operação muito cara. Em uma máquina lenta isso pode levar vários segundos.
Em ambientes de servidores, tempo de inicialização é irrelevante virtualmente. Um servidor Node.js que requer informações sobre todas as portas é provavelmente na verdade \"mais rápido\" se ele carregar todas as informações necessárias em memória sempre que o servidor iniciar para o ter o beneficio de atender às requisições mais rapidamente. O módulo discutido neste exemplo não é um módulo \"ruim\". Aplicativos Electron, contudo, não devem estar carregando, interpretando, e armazenando na memória informações que ele na verdade não precisa.
\nEm suma, um módulo aparentemente ótimo escrito primordialmente para servidores Node.js rodando em Linux pode ser uma má noticia para a performance da sua aplicação. Nesse exemplo em particular, a solução correta era não usar o módulo no final das contas, e ao invés disso usar verificadores de conexão incluídos em versões posteriores do Chromium.
\nQuando considerar um módulo, nos recomendados que você verifique:
\nrequire()) itGerar um perfil de consumo de CPU e de memória para carregar um módulo pode ser feito com um simples comando no terminal. No exemplo abaixo, nós estamos observando o popular módulo request.
node --cpu-prof --heap-prof -e \"require('request')\"\nExecutando esse comando temos um arquivo .cpuprofile e um arquivo .heapprofile no diretório em que você executou. Ambos os arquivos podem ser analisados usando a Ferramenta de Desenvolvedor do Chrome, usando as seções Performance e Memory respectivamente.
Nesse exemplo, na máquina do autor, nós vimos que o request levou quase meio segundo, enquanto o node-fetch levou drasticamente menos memória e menos que 50ms.
Se você tem operações de configurações gastonas, considere adiar elas. Inspecione todo o trabalho executado logo após o início da aplicação. Ao invés de disparar todas as funções imediatamente, considere escalona-las em uma sequencia mais ligada ao caminho do usuário.
\nEm um desenvolvimento tradicional de Node.js, nós estamos acostumados a colocar todos as declarações require() no início. Se você atualmente desenvolve sua aplicação Electron usando a mesma estratégia e usando módulos consideráveis que você não precisa imediatamente, aplique a mesma estratégia e adie o carregamento para um momento mais oportuno.
Carregar módulos é surpreendentemente uma operação cara, especialmente no Windows. Quando sua aplicação inicia, não deve fazer seus usuários aguardarem por coisas que eles não precisam agora.
\nIsto pode parecer óbvio, mas a maioria das aplicações tendem a fazer muitas operações imediatamente após o programa ser aberto - como checar atualizações, baixar conteúdo usado em uma sessão anterior, ou fazer operações I/O pesadas no disco.
\nVamos tomar o Visual Studio Code como exemplo. Quando você abre um arquivo, ele vai imediatamente aparecer para você sem nenhum destaque, priorizando sua capacidade de interagir com o texto. Uma vez que está funcionando, aí sim ele vai destacar o código.
\nVamos considerar um exemplo e assumir que sua aplicação está interpretando arquivos em um formato fictício .foo. Para fazer isso, ele depende do módulo igualmente fictício foo-parser. Em um desenvolvimento tradicional em Node.js, você provavelmente vai escrever um código que vai avidamente carregar dependências:
const fs = require('fs')\nconst fooParser = require('foo-parser')\n\nclass Parser {\n constructor () {\n this.files = fs.readdirSync('.')\n }\n\n getParsedFiles () {\n return fooParser.parse(this.files)\n }\n}\n\nconst parser = new Parser()\n\nmodule.exports = { parser }\nNo exemplo acima, nós estamos fazendo muita coisa assim que o arquivo é carregado. Nós precisamos interpretar os arquivos imediatamente ? Nós podemos fazer isso um pouco mais tarde, quando o getParsedFiles() é realmente utilizado ?
// \"fs\" já está sendo carregado, então o `require()` é \"barato\"\nconst fs = require('fs')\n\nclass Parser {\n async getFiles () {\n // Acesse o disco logo que o `getFiles` é chamado, não antes.\n // Além disso, assegure-se que nós não estamos bloqueando outras operações usando\n// a versão assíncrona.\n this.files = this.files || await fs.readdir('.')\n\n return this.files\n }\n\n async getParsedFiles () {\n // Our fictitious foo-parser is a big and expensive module to load, so\n // defer that work until we actually need to parse files.\n // Já que `require()` vem com um módulo em cache, o `require()` \n // vai sair caro apenas uma vez - as chamadas seguintes de `getParsedFiles()`\n // vão ser mais rápidas.\n const fooParser = require('foo-parser')\n const files = await this.getFiles()\n\n return fooParser.parse(files)\n }\n}\n\n// Essa operação agora é muito mais barata que nosso exemplo anterior\nconst parser = new Parser()\n\nmodule.exports = { parser }\nEm suma, aloque recursos quando precisar em vez de alocar todos eles quando sua aplicação iniciar.
\nO processo principal do Electron (algumas vezes chamado de \"browser process\") é especial: é o processo pai de todos os outros na sua aplicação e o primeiro processo com quem o sistema operacional interage. It handles windows, interactions, and the communication between various components inside your app. It also houses the UI thread.
\nSob nenhuma circunstância você deve bloquear este processo e a thread da UI com operações longas. Bloquear a thread da UI significa que todo o seu programa vai travar até o processo principal estar pronto para continuar.
\nThe main process and its UI thread are essentially the control tower for major operations inside your app. When the operating system tells your app about a mouse click, it'll go through the main process before it reaches your window. Se sua janela está renderizando uma animação suave, ela vai precisar conversar com o processo da GPU sobre isso - mais uma vez passando pelo processo principal.
\nElectron e Chromium são cuidadosos ao colocar tarefas pesadas de I/P e operações pesadas em CPU dentro de novas threads para evitar o bloqueio da thread da UI. Você deve fazer o mesmo.
\nA poderosa arquitetura multi-procedural fica pronta para ajudar você com suas tarefas demoradas, mas também inclue um pequeno número de armadilhas de performance.
\n1) Para longas e pesadas tarefas na CPU, faça uso de worker threads, considere move-las para a BrowserWindow ou (como último recurso) cria um processo dedicado.
\n2) Evite usar o IPC síncrono e o módulo remote o máximo possível. Enquanto há casos legítimos de uso, é de longe muito fácil bloquear a thread da UI sem saber usando o módulo remote.
3) Evite usar operações que bloqueiam I/O no processo principal. Em suma, sempre que um módulo Node.js (como fs ou child_process) oferecer uma versão assíncrona ou síncrona, você deve dar preferência a versão assíncrona e não-bloqueadora.
Desde que o Electron esteja de acordo com a versão do Chrome, você pode usar os mais novos e melhores recursos que a plataforma Web oferece para adiar ou descarregar operações pesadas a fim de manter sua aplicação leve e responsiva.
\nVocê provavelmente tem muito JavaScript para rodar no processo de renderização. A dica é executar operações o mais rápido possível sem deixar de lado recursos necessários para continuar liso, respondendo às entradas do usuário, ou animando a 60fps.
\nOrquestrar o fluxo de operações no código de renderização é particularmente útil se usuários reclamam que seu programa \"engasga\" às vezes.
\nGeralmente, todo conselho para construir aplicativos web melhores para navegadores modernos se aplicam à renderização do Electron também. As duas ferramentas primárias à sua disposição são atualmente requestIdleCallback() para pequenos processos e Web Workers para operações demoradas.
requestIdleCallback() permite ao desenvolvedor enfileirar uma função para ser executada assim que o processo estiver entrando em um período ocioso. Ela permite você fazer tarefas de baixa prioridade ou de fundo sem impactar a experiência do usuário. Para mais informações sobre como usar isso, cheque a sua documentação no MDN.
Web Workers são uma ferramenta poderosa para rodar um código em uma thread separada. Há algumas ressalvas - consulte a documentação de multi-thread do Electron e a documentação do MDN para Web Workers. Elas são a solução ideal para qualquer operação que precise de muito poder de CPU por um longo período de tempo.
\nUm dos maiores benefícios do Electron é que você sabe exatamente qual engine vai interpretar seu JavaScript, HTML e CSS. Se você esta usando código que foi escrito para a web em geral, certifique-se de não sobrecarregar recursos já incluídos no Electron.
\nAo construir uma aplicação web para a internet de hoje, os ambientes mais antigos ditam quais funcionalidades você pode e não pode usar. Embora o Electron suporte filtros e animações CSS de bom desempenho, um navegador mais antigo pode não suportar. Onde você poderia usar WebGL, seus desenvolvedores podem ter escolhido uma solução mais faminta por recursos para suportar telefones antigos.
\nQuando isso vem para o JavaScript, você deve ter incluído bibliotecas ferramentais como JQuery para seletores DOM ou sobrecargas como o regenerator-runtime para suportar async/await.
É raro que uma sobrecarga baseada em JavaScript seja mais rápida que o equivalente em uma funcionalidade nativa do Electron. Não deixe seu aplicativo Electron lento, enviando sua própria versão dos recursos de plataforma web padrão.
\nOpere sobre a suposição que sobrecargas em versões atuais do Electron são desnecessárias. Se você tem dúvidas, cheque caniuse.com e verifique se a versão do Chromium usada em sua aplicação Electron suporta a funcionalidade que deseja.
\nAlém disso, examine cuidadosamente as bibliotecas que você usa. São realmente necessárias? jQuery, por exemplo, foi um sucesso tal que muitos de seus recursos agora fazem parte da configuração padrão de JavaScript disponível.
Se você estiver usando um compilador/transpilador como TypeScript, examine sua configuração e certifique-se de que esteja utilizando a versão mais recente do ECMAScript suportada pelo Electron.
\nEvite buscar raramente recursos da internet se eles podem facilmente ser empacotados com seu aplicativo.
\nMuitos usuários do Electron começam com um aplicativo inteiramente baseado na web que estão transformando em uma aplicação desktop. Como desenvolvedores web, estamos acostumados a carregar recursos de uma variedade de redes de conteúdo. Now that you are shipping a proper desktop application, attempt to \"cut the cord\" where possible and avoid letting your users wait for resources that never change and could easily be included in your app.
\nUm típico exemplo é o Google Fonts. Muitos desenvolvedores usam a incrível coleção de fontes gratuitas do Google, que vem com um rede de entrega de conteúdo. O tom é direto: Inclua algumas linhas de CSS e o Google cuidará do resto.
\nQuando está construindo uma aplicação Electron, seus usuários serão melhor atendidos se você baixar as fontes e incluí-las no pacote de seu programa.
\nEm um mundo ideal, sua aplicação não precisaria de conexão com a internet para funcionar completamente. Para chegar lá, você deve entender quais recursos em sua aplicação estão baixando - e o quão grandes são esses recursos.
\nPara isso, abra suas ferramentas de desenvolvedor. Navegue até a seção Network e marque a opção Disable cache. Em seguida, recarregue seu renderizador. A menos que sua aplicação proíba tais recarregamentos, você pode fazer ativar o recarregamento pressionando Cmd +R ou Ctrl + R com a ferramenta de desenvolvedor em foco.
As ferramentas agora vão meticulosamente gravar todas as requisições de rede. No primeiro passo, faça um balanço de todos os recursos que estão sendo baixados, focando nos arquivos grandes primeiro. Há algumas dessas imagens, fontes ou arquivos de mídia que não mudam e poderiam ser incluídas em seu pacote ? Se sim, inclua elas.
\nComo próximo passo, habilite o Network Throttling. Ache o menu suspenso que está em Online e selecione uma velocidade menor como o Fast 3G. Recarregue seu renderizador e veja se tem algum recurso que sua aplicação está esperando desnecessariamente. Em muitos casos, o programa vai aguardar uma requisição na rede ser concluída apesar de não precisar realmente do recurso envolvido.
Uma dica, carregar recursos da Internet que você pode querer alterar sem enviar uma atualização de aplicativo é uma estratégia poderosa. Para o controle avançado de sobre como os recursos estão sendo carregados, considere investir em Service Workers.
\nComo já apontado em \"Carregando e rodando o código muito cedo\", o require() é uma operação cara. Se você for capaz, comprima sua aplicação em um único arquivo.
Desenvolvimentos modernos de JavaScript normalmente envolvem muitos arquivos e módulos. Enquanto isso é perfeito para desenvolver com Electron, nós recomendamos fortemente que você empacote todo o seu código em um único arquivos para garantir que a sobrecarga inclusa no método require() seja paga apenas uma vez quando sua aplicação inicia.
Tem vários compressores de JavaScript lá fora e nós sabemos que melhor que irritar a comunidade recomendando uma única ferramenta em detrimento de outra. Nós recomendamos contudo que você use um empacotador que seja capaz de lidar com o ambiente único do Electron que precisa lidar com Node.js e Browser.
\nA partir da escrita deste artigo, as escolhas populares incluem Webpack, Parcel, e rollup.js.
", "title": "Performance", "description": "" }, "/docs/api/structures/point": { "locale": "pt-BR", "slug": "point", "href": "/docs/api/structures/point", "crowdinFileId": "256475", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/point.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "x Numbery NumberNote: Both x and y must be whole integers, when providing a point object as input to an Electron API we will automatically round your x and y values to the nearest whole integer.
data (UploadRawData | UploadFile)[] - The post data to be sent to the new window.contentType String - The content-type header used for the data. One of application/x-www-form-urlencoded or multipart/form-data. Corresponds to the enctype attribute of the submitted HTML form.boundary String (optional) - The boundary used to separate multiple parts of the message. Only valid when contentType is multipart/form-data.Note that keys starting with -- are not currently supported. For example, this will errantly submit as multipart/form-data when nativeWindowOpen is set to false in webPreferences:
<form\n target=\"_blank\"\n method=\"POST\"\n enctype=\"application/x-www-form-urlencoded\"\n action=\"https://postman-echo.com/post\"\n>\n <input type=\"text\" name=\"--theKey\">\n <input type=\"submit\">\n</form>\n\n\nMonitor power state changes.
\n
Processo: Main
\nO módulo powerMonitor emite os seguintes eventos:
Emitted when the system is suspending.
\nEmitted when system is resuming.
\nEmitted when the system changes to AC power.
\nEmitted when system changes to battery power.
\nEmitted when the system is about to reboot or shut down. If the event handler invokes e.preventDefault(), Electron will attempt to delay system shutdown in order for the app to exit cleanly. If e.preventDefault() is called, the app should exit as soon as possible by calling something like app.quit().
Emitted when the system is about to lock the screen.
\nEmitted as soon as the systems screen is unlocked.
\nEmitted when a login session is activated. See documentation for more information.
\nEmitted when a login session is deactivated. See documentation for more information.
\nO módulo powerMonitor tem os seguintes métodos:
powerMonitor.getSystemIdleState(idleThreshold)idleThreshold IntegerReturns String - The system's current state. Pode ser active, idle, locked ou unknown.
Calculate the system idle state. idleThreshold is the amount of time (in seconds) before considered idle. locked is available on supported systems only.
powerMonitor.getSystemIdleTime()Returns Integer - Idle time in seconds
Calculate system idle time in seconds.
\npowerMonitor.isOnBatteryPower()Returns Boolean - Whether the system is on battery power.
To monitor for changes in this property, use the on-battery and on-ac events.
powerMonitor.onBatteryPowerA Boolean property. True if the system is on battery power.
See powerMonitor.isOnBatteryPower().
\n\nBlock the system from entering low-power (sleep) mode.
\n
Processo: Main
\nComo por exemplo:
\nconst { powerSaveBlocker } = require('electron')\n\nconst id = powerSaveBlocker.start('prevent-display-sleep')\nconsole.log(powerSaveBlocker.isStarted(id))\n\npowerSaveBlocker.stop(id)\nO módulo powerSaveBlocker tem os seguintes métodos:
powerSaveBlocker.start(type)type String - Power save blocker type.prevent-app-suspension - Prevent the application from being suspended. Keeps system active but allows screen to be turned off. Example use cases: downloading a file or playing audio.prevent-display-sleep - Prevent the display from going to sleep. Keeps system and screen active. Example use case: playing video.Returns Integer - The blocker ID that is assigned to this power blocker.
Starts preventing the system from entering lower-power mode. Returns an integer identifying the power save blocker.
\nNote: prevent-display-sleep has higher precedence over prevent-app-suspension. Only the highest precedence type takes effect. In other words, prevent-display-sleep always takes precedence over prevent-app-suspension.
For example, an API calling A requests for prevent-app-suspension, and another calling B requests for prevent-display-sleep. prevent-display-sleep will be used until B stops its request. After that, prevent-app-suspension is used.
powerSaveBlocker.stop(id)id Integer - The power save blocker id returned by powerSaveBlocker.start.Stops the specified power save blocker.
\npowerSaveBlocker.isStarted(id)id Integer - The power save blocker id returned by powerSaveBlocker.start.Returns Boolean - Whether the corresponding powerSaveBlocker has started.
name String - the name of the printer as understood by the OS.displayName String - the name of the printer as shown in Print Preview.description String - a longer description of the printer's type.status Number - the current status of the printer.isDefault Boolean - whether or not a given printer is set as the default printer on the OS.options Object - an object containing a variable number of platform-specific printer information.The number represented by status means different things on different platforms: on Windows its potential values can be found here, and on Linux and macOS they can be found here.
Below is an example of some of the additional options that may be set which may be different on each platform.
\n{\n name: 'Austin_4th_Floor_Printer___C02XK13BJHD4',\n displayName: 'Austin 4th Floor Printer @ C02XK13BJHD4',\n description: 'TOSHIBA ColorMFP',\n status: 3,\n isDefault: false,\n options: {\n copies: '1',\n 'device-uri': 'dnssd://Austin%204th%20Floor%20Printer%20%40%20C02XK13BJHD4._ipps._tcp.local./?uuid=71687f1e-1147-3274-6674-22de61b110bd',\n finishings: '3',\n 'job-cancel-after': '10800',\n 'job-hold-until': 'no-hold',\n 'job-priority': '50',\n 'job-sheets': 'none,none',\n 'marker-change-time': '0',\n 'number-up': '1',\n 'printer-commands': 'ReportLevels,PrintSelfTestPage,com.toshiba.ColourProfiles.update,com.toshiba.EFiling.update,com.toshiba.EFiling.checkPassword',\n 'printer-info': 'Austin 4th Floor Printer @ C02XK13BJHD4',\n 'printer-is-accepting-jobs': 'true',\n 'printer-is-shared': 'false',\n 'printer-is-temporary': 'false',\n 'printer-location': '',\n 'printer-make-and-model': 'TOSHIBA ColorMFP',\n 'printer-state': '3',\n 'printer-state-change-time': '1573472937',\n 'printer-state-reasons': 'offline-report,com.toshiba.snmp.failed',\n 'printer-type': '10531038',\n 'printer-uri-supported': 'ipp://localhost/printers/Austin_4th_Floor_Printer___C02XK13BJHD4',\n system_driverinfo: 'T'\n }\n}\n\n\n\nExtensões para objeto process.
\n
O objeto process do Electron estende do objeto process do Node.js. Ele adiciona os seguintes eventos, propriedades e métodos:
In sandboxed renderers the process object contains only a subset of the APIs:
crash()hang()getCreationTime()getHeapStatistics()getBlinkMemoryInfo()getProcessMemoryInfo()getSystemMemoryInfo()getSystemVersion()getCPUUsage()getIOCounters()uptime()argvexecPathenvpidarchplataformasandboxedcontextIsolatedtipoversãoversionsmaswindowsStorecontextIdEmitido quando o Electron já carregou seu script de inicialização interno e começa a carregar a página da web ou o script principal.
\nprocess.defaultApp ReadonlyA Boolean. When app is started by being passed as parameter to the default app, this property is true in the main process, otherwise it is undefined.
process.isMainFrame ReadonlyA Boolean, true when the current renderer context is the \"main\" renderer frame. If you want the ID of the current frame you should use webFrame.routingId.
process.mas ReadonlyA Boolean. For Mac App Store build, this property is true, for other builds it is undefined.
process.noAsarA Boolean that controls ASAR support inside your application. Setting this to true will disable the support for asar archives in Node's built-in modules.
process.noDeprecationA Boolean that controls whether or not deprecation warnings are printed to stderr. Setting this to true will silence deprecation warnings. This property is used instead of the --no-deprecation command line flag.
process.resourcesPath ReadonlyUma String que representa o caminho para o diretório de recursos.
process.sandboxed ReadonlyA Boolean. When the renderer process is sandboxed, this property is true, otherwise it is undefined.
process.contextIsolated ReadonlyA Boolean that indicates whether the current renderer context has contextIsolation enabled. It is undefined in the main process.
process.throwDeprecationA Boolean that controls whether or not deprecation warnings will be thrown as exceptions. Setting this to true will throw errors for deprecations. This property is used instead of the --throw-deprecation command line flag.
process.traceDeprecationA Boolean that controls whether or not deprecations printed to stderr include their stack trace. Setting this to true will print stack traces for deprecations. This property is instead of the --trace-deprecation command line flag.
process.traceProcessWarningsA Boolean that controls whether or not process warnings printed to stderr include their stack trace. Setting this to true will print stack traces for process warnings (including deprecations). This property is instead of the --trace-warnings command line flag.
process.type ReadonlyA String representing the current process's type, can be:
browser - The main processrenderer - A renderer processworker - In a web workerprocess.versions.chrome ReadonlyA String representing Chrome's version string.
process.versions.electron ReadonlyA String representing Electron's version string.
process.windowsStore ReadonlyA Boolean. If the app is running as a Windows Store app (appx), this property is true, for otherwise it is undefined.
process.contextId ReadonlyA String (optional) representing a globally unique ID of the current JavaScript context. Each frame has its own JavaScript context. When contextIsolation is enabled, the isolated world also has a separate JavaScript context. This property is only available in the renderer process.
O objeto process tem os seguintes métodos:
process.crash()Causes the main thread of the current process crash.
\nprocess.getCreationTime()Returns Number | null - The number of milliseconds since epoch, or null if the information is unavailable
Indicates the creation time of the application. The time is represented as number of milliseconds since epoch. It returns null if it is unable to get the process creation time.
\nprocess.getCPUUsage()Retorna CPUUsage
process.getIOCounters() Windows LinuxRetorna IOCounters
process.getHeapStatistics()Retorna Object:
totalHeapSize IntegertotalHeapSizeExecutable IntegertotalPhysicalSize IntegertotalAvailableSize IntegerusedHeapSize IntegerheapSizeLimit IntegermallocedMemory IntegerpeakMallocedMemory IntegerdoesZapGarbage BooleanReturns an object with V8 heap statistics. Note-se que todas as estatísticas são relatadas em Kilobytes.
\nprocess.getBlinkMemoryInfo()Retorna Object:
allocated Integer - Size of all allocated objects in Kilobytes.marked Integer - Size of all marked objects in Kilobytes.total Integer - Total allocated space in Kilobytes.Returns an object with Blink memory information. It can be useful for debugging rendering / DOM related memory issues. Note that all values are reported in Kilobytes.
\nprocess.getProcessMemoryInfo()Returns Promise<ProcessMemoryInfo> - Resolves with a ProcessMemoryInfo
Returns an object giving memory usage statistics about the current process. Note that all statistics are reported in Kilobytes. This api should be called after app ready.
\nChromium does not provide residentSet value for macOS. This is because macOS performs in-memory compression of pages that haven't been recently used. As a result the resident set size value is not what one would expect. private memory is more representative of the actual pre-compression memory usage of the process on macOS.
process.getSystemMemoryInfo()Retorna Object:
total Integer - The total amount of physical memory in Kilobytes available to the system.free Integer - The total amount of memory not being used by applications or disk cache.swapTotal Integer Windows Linux - The total amount of swap memory in Kilobytes available to the system.swapFree Integer Windows Linux - The free amount of swap memory in Kilobytes available to the system.Returns an object giving memory usage statistics about the entire system. Note that all statistics are reported in Kilobytes.
\nprocess.getSystemVersion()Returns String - The version of the host operating system.
Exemplo:
\nconst version = process.getSystemVersion()\nconsole.log(version)\n// On macOS -> '10.13.6'\n// On Windows -> '10.0.17763'\n// On Linux -> '4.15.0-45-generic'\nNote: It returns the actual operating system version instead of kernel version on macOS unlike os.release().
process.takeHeapSnapshot(filePath)filePath String - Path to the output file.Returns Boolean - Indicates whether the snapshot has been created successfully.
Takes a V8 heap snapshot and saves it to filePath.
process.hang()Causes the main thread of the current process hang.
\nprocess.setFdLimit(maxDescriptors) macOS LinuxmaxDescriptors IntegerSets the file descriptor soft limit to maxDescriptors or the OS hard limit, whichever is lower for the current process.
residentSet Integer Linux Windows - The amount of memory currently pinned to actual physical RAM in Kilobytes.private Integer - The amount of memory not shared by other processes, such as JS heap or HTML content in Kilobytes.shared Integer - The amount of memory shared between processes, typically memory consumed by the Electron code itself in Kilobytes.pid Integer - Process id of the process.type String - Process type. One of the following values:BrowserTabUtilidadeZygoteAjuda ao SandboxGPUPepper PluginPepper Plugin BrokerDesconhecidoserviceName String (optional) - The non-localized name of the process.name String (optional) - The name of the process. Examples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.cpu CPUUsage - CPU usage of the process.creationTime Number - Creation time for this process. The time is represented as number of milliseconds since epoch. Since the pid can be reused after a process dies, it is useful to use both the pid and the creationTime to uniquely identify a process.memory MemoryInfo - Memory information for the process.sandboxed Boolean (optional) macOS Windows - Whether the process is sandboxed on OS level.integrityLevel String (optional) Windows - One of the following values:untrustedlowmediumhighunknownO Electron herda sua arquitetura multi-processo do Chromium, o que torna o framework muito semelhante a um navegador web moderno. Neste guia, nós vamos expor o conhecimento conceitual do Electron que aplicamos no básico aplicativo de início rápido.
\nNavegadores da web são aplicações incrivelmente complicadas. Além da função principal de mostrar o conteúdo web, eles têm muitas responsabilidades secundárias, tais como gerenciar várias janelas (ou abas) e carregar extensões de terceiros.
\nNos dias anteriores, os navegadores costumavam usar um único processo para todas estas funcionalidades. Embora este padrão significasse menos sobrecarga para cada guia que você tinha aberta, também significava que se um site falhasse ou travasse, isso afetaria todo o navegador.
\nPara resolver este problema, a equipe do Chrome decidiu que cada aba renderizaria seu próprio processo, limitando o dano que códigos defeituosos ou maliciosos em uma página da web poderiam causar ao aplicativo como um todo. Um único processo de navegador, em seguida, controla esses processos, bem como o ciclo de vida da aplicação como um todo. Este diagrama abaixo do Chrome Comic visualiza este modelo:
\n
Aplicações Electron são estruturadas de forma muito semelhante. Como um desenvolvedor, você controla dois tipos de processos: o principal e o renderizador. Essas são análogas ao próprio navegador do Chrome e aos processos de renderização descritos acima.
\nCada aplicativo do Electron tem um único processo principal, que atua como o ponto de entrada do aplicativo. O processo principal é executado em um ambiente de Node.js, o que significa que tem a habilidade de exigir módulos e usar todas as APIs do Node.js.
O objetivo principal do processo é criar e gerenciar as janelas do aplicativo com o módulo BrowserWindow.
Cada instância da classe BrowserWindow cria uma janela do aplicativo que carrega uma página web em um processo de renderização separado. Você pode interagir com este conteúdo web do processo principal usando o objeto webContents da janela.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\n\n\nNota: Um processo de renderização também é criado para a web embeds, como o módulo
\nBrowserView. O objetode conteúdoweb também é acessível para conteúdo web embutido.
Because the BrowserWindow module is an EventEmitter, you can also add handlers for various user events (for example, minimizing or maximizing your window).
When a BrowserWindow instance is destroyed, its corresponding renderer process gets terminated as well.
The main process also controls your application's lifecycle through Electron's app module. This module provides a large set of events and methods that you can use to add custom application behaviour (for instance, programatically quitting your application, modifying the application dock, or showing an About panel).
As a practical example, the app shown in the quick start guide uses app APIs to create a more native application window experience.
// quitting the app when no windows are open on non-macOS platforms\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nTo extend Electron's features beyond being a Chromium wrapper for web contents, the main process also adds custom APIs to interact with the user's operating system. Electron exposes various modules that control native desktop functionality, such as menus, dialogs, and tray icons.
\nFor a full list of Electron's main process modules, check out our API documentation.
\nEach Electron app spawns a separate renderer process for each open BrowserWindow (and each web embed). As its name implies, a renderer is responsible for rendering web content. For all intents and purposes, code ran in renderer processes should behave according to web standards (insofar as Chromium does, at least).
Therefore, all user interfaces and app functionality within a single browser window should be written with the same tools and paradigms that you use on the web.
\nAlthough explaining every web spec is out of scope for this guide, the bare minimum to understand is:
\n<script> elements.Moreover, this also means that the renderer has no direct access to require or other Node.js APIs. In order to directly include NPM modules in the renderer, you must use the same bundler toolchains (for example, webpack or parcel) that you use on the web.
\n\nNote: Renderer processes can be spawned with a full Node.js environment for ease of development. Historically, this used to be the default, but this feature was disabled for security reasons.
\n
At this point, you might be wondering how your renderer process user interfaces can interact with Node.js and Electron's native desktop functionality if these features are only accessible from the main process. In fact, there is no direct way to import Electron's content scripts.
\nA preload script can be attached to the main process in the BrowserWindow constructor's webPreferences option.
const { BrowserWindow } = require('electron')\n//...\nconst win = new BrowserWindow({\n webPreferences: {\n preload: 'path/to/preload.js'\n }\n})\n//...\nBecause the preload script shares a global Window interface with the renderers and can access Node.js APIs, it serves to enhance your renderer by exposing arbitrary APIs in the window global that your web contents can then consume.
Although preload scripts share a window global with the renderer they're attached to, you cannot directly attach any variables from the preload script to window because of the contextIsolation default.
window.myAPI = {\n desktop: true\n}\nconsole.log(window.myAPI)\n// => undefined\nContext Isolation means that preload scripts are isolated from the renderer's main world to avoid leaking any privileged APIs into your web content's code.
\nInstead, use the contextBridge module to accomplish this securely:
const { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n desktop: true\n})\nconsole.log(window.myAPI)\n// => { desktop: true }\nThis feature is incredibly useful for two main purposes:
\nipcRenderer helpers to the renderer, you can use inter-process communication (IPC) to trigger main process tasks from the renderer (and vice-versa).window global that can be used for desktop-only logic on the web client's side.productIdentifier String - The string that identifies the product to the Apple App Store.localizedDescription String - A description of the product.localizedTitle String - The name of the product.contentVersion String - A string that identifies the version of the content.contentLengths Number[] - The total size of the content, in bytes.price Number - The cost of the product in the local currency.formattedPrice String - The locale formatted price of the product.currencyCode String - 3 character code presenting a product's currency based on the ISO 4217 standard.isDownloadable Boolean - A Boolean value that indicates whether the App Store has downloadable content for this product. true if at least one file has been associated with the product.A progress bar enables a window to provide progress information to the user without the need of switching to the window itself.
\nOn Windows, you can use a taskbar button to display a progress bar.
\n![Windows Progress Bar][https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png\\]
\nOn macOS, the progress bar will be displayed as a part of the dock icon.
\n
On Linux, the Unity graphical interface also has a similar feature that allows you to specify the progress bar in the launcher.
\n
\n\nNOTE: on Windows, each window can have its own progress bar, whereas on macOS and Linux (Unity) there can be only one progress bar for the application.
\n
All three cases are covered by the same API - the setProgressBar() method available on an instance of BrowserWindow. To indicate your progress, call this method with a number between 0 and 1. For example, if you have a long-running task that is currently at 63% towards completion, you would call it as setProgressBar(0.63).
Setting the parameter to negative values (e.g. -1) will remove the progress bar. Setting it to a value greater than 1 will indicate an indeterminate progress bar in Windows or clamp to 100% in other operating systems. An indeterminate progress bar remains active but does not show an actual percentage, and is used for situations when you do not know how long an operation will take to complete.
Veja a documentação da API para mais opções e modos.
\nIn this example, we add a progress bar to the main window that increments over time using Node.js timers.
\nconst { app, BrowserWindow } = require('electron')\n\nlet progressInterval\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n\n const INCREMENT = 0.03\n const INTERVAL_DELAY = 100 // ms\n\n let c = 0\n progressInterval = setInterval(() => {\n // update progress bar to next value\n // values between 0 and 1 will show progress, >1 will show indeterminate or stick at 100%\n win.setProgressBar(c)\n\n // increment or reset progress bar\n if (c < 2) c += INCREMENT\n else c = 0\n }, INTERVAL_DELAY)\n}\n\napp.whenReady().then(createWindow)\n\n// before the app is terminated, clear both timers\napp.on('before-quit', () => {\n clearInterval(progressInterval)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nAfter launching the Electron application, the dock (macOS) or taskbar (Windows, Unity) should show a progress bar that starts at zero and progresses through 100% to completion. It should then show indeterminate (Windows) or pin to 100% (other operating systems) briefly and then loop.
\n
For macOS, the progress bar will also be indicated for your application when using Mission Control:
\n
\n\nRegistra um protocolo personalizado e intercepta as solicitações de protocolo existentes.
\n
Processo: Main
\nUm exemplo de implementação de um protocolo que tem o mesmo efeito que o file:// protocol:
const { app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n})\nNota: Todos os métodos, a menos que seja especificados, só podem ser usados após o evento app quando é emitido.
protocol with a custom partition or sessionA protocol is registered to a specific Electron session object. If you don't specify a session, then your protocol will be applied to the default session that Electron uses. However, if you define a partition or session on your browserWindow's webPreferences, then that window will use a different session and your custom protocol will not work if you just use electron.protocol.XXX.
To have your custom protocol work in combination with a custom session, you need to register it to that session explicitly.
\nconst { session, app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const partition = 'persist:example'\n const ses = session.fromPartition(partition)\n\n ses.protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n\n mainWindow = new BrowserWindow({ webPreferences: { partition } })\n})\nO módulo de protocolo possui os seguintes métodos:
\nprotocol.registerSchemesAsPrivileged(customSchemes)customSchemes CustomScheme[]Note: This method can only be used before the ready event of the app module gets emitted and can be called only once.
Registers the scheme as standard, secure, bypasses content security policy for resources, allows registering ServiceWorker, supports fetch API, and streaming video/audio. Specify a privilege with the value of true to enable the capability.
An example of registering a privileged scheme, that bypasses Content Security Policy:
\nconst { protocol } = require('electron')\nprotocol.registerSchemesAsPrivileged([\n { scheme: 'foo', privileges: { bypassCSP: true } }\n])\nUm esquema padrão adere ao que a RFC 3986 chama generic URI syntax. Por exemplo http e https são esquema padrão, enquanto file não é.
Registering a scheme as standard allows relative and absolute resources to be resolved correctly when served. Caso contrário, o esquema se comportará como o protocolo file, mas sem a capacidade de resolver URLs relativos.
Por exemplo, quando você carrega a página seguinte com o protocolo personalizado sem registrando-o como esquema padrão, a imagem não será carregada porque esquemas não padrão não podem reconhecer URLs relativas:
\n<body>\n <img src='test.png'>\n</body>\nRegistrar um esquema como padrão permitirá o acesso aos arquivos através doFileSystem API. Caso contrário, o renderizador lançará um erro de segurança para o esquema.
\nBy default web storage apis (localStorage, sessionStorage, webSQL, indexedDB, cookies) are disabled for non standard schemes. So in general if you want to register a custom protocol to replace the http protocol, you have to register it as a standard scheme.
Protocols that use streams (http and stream protocols) should set stream: true. The <video> and <audio> HTML elements expect protocols to buffer their responses by default. The stream flag configures those elements to correctly expect streaming responses.
protocol.registerFileProtocol(scheme, handler)scheme Stringhandler Funçãorequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a file as the response. The handler will be called with request and callback where request is an incoming request for the scheme.
To handle the request, the callback should be called with either the file's path or an object that has a path property, e.g. callback(filePath) or callback({ path: filePath }). The filePath must be an absolute path.
By default the scheme is treated like http:, which is parsed differently from protocols that follow the \"generic URI syntax\" like file:.
protocol.registerBufferProtocol(scheme, handler)scheme Stringhandler Funçãorequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a Buffer as a response.
The usage is the same with registerFileProtocol, except that the callback should be called with either a Buffer object or an object that has the data property.
Exemplo:
\nprotocol.registerBufferProtocol('atom', (request, callback) => {\n callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })\n})\nprotocol.registerStringProtocol(scheme, handler)scheme Stringhandler Funçãorequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a String as a response.
The usage is the same with registerFileProtocol, except that the callback should be called with either a String or an object that has the data property.
protocol.registerHttpProtocol(scheme, handler)scheme Stringhandler Funçãorequest ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send an HTTP request as a response.
The usage is the same with registerFileProtocol, except that the callback should be called with an object that has the url property.
protocol.registerStreamProtocol(scheme, handler)scheme Stringhandler Funçãorequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a stream as a response.
The usage is the same with registerFileProtocol, except that the callback should be called with either a ReadableStream object or an object that has the data property.
Exemplo:
\nconst { protocol } = require('electron')\nconst { PassThrough } = require('stream')\n\nfunction createStream (text) {\n const rv = new PassThrough() // PassThrough is also a Readable stream\n rv.push(text)\n rv.push(null)\n return rv\n}\n\nprotocol.registerStreamProtocol('atom', (request, callback) => {\n callback({\n statusCode: 200,\n headers: {\n 'content-type': 'text/html'\n },\n data: createStream('<h5>Response</h5>')\n })\n})\nIt is possible to pass any object that implements the readable stream API (emits data/end/error events). For example, here's how a file could be returned:
protocol.registerStreamProtocol('atom', (request, callback) => {\n callback(fs.createReadStream('index.html'))\n})\nprotocol.unregisterProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unregistered
Unregisters the custom protocol of scheme.
protocol.isProtocolRegistered(scheme)scheme StringReturns Boolean - Whether scheme is already registered.
protocol.interceptFileProtocol(scheme, handler)scheme Stringhandler Funçãorequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler which sends a file as a response.
protocol.interceptStringProtocol(scheme, handler)scheme Stringhandler Funçãorequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler which sends a String as a response.
protocol.interceptBufferProtocol(scheme, handler)scheme Stringhandler Funçãorequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler which sends a Buffer as a response.
protocol.interceptHttpProtocol(scheme, handler)scheme Stringhandler Funçãorequest ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler which sends a new HTTP request as a response.
protocol.interceptStreamProtocol(scheme, handler)scheme Stringhandler Funçãorequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Same as protocol.registerStreamProtocol, except that it replaces an existing protocol handler.
protocol.uninterceptProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unintercepted
Remove the interceptor installed for scheme and restore its original handler.
protocol.isProtocolIntercepted(scheme)scheme StringReturns Boolean - Whether scheme is already intercepted.
urlreferrer Stringmethod StringuploadData UploadData[] (optional)headers Record<String, String>error Integer (optional) - When assigned, the request will fail with the error number . For the available error numbers you can use, please see the net error list.statusCode Number (optional) - The HTTP response code, default is 200.charset String (optional) - The charset of response body, default is \"utf-8\".mimeType String (optional) - The MIME type of response body, default is \"text/html\". Setting mimeType would implicitly set the content-type header in response, but if content-type is already set in headers, the mimeType would be ignored.headers Record<string, string | string[]> (optional) - An object containing the response headers. The keys must be String, and values must be either String or Array of String.data (Buffer | String | ReadableStream) (optional) - The response body. When returning stream as response, this is a Node.js readable stream representing the response body. When returning Buffer as response, this is a Buffer. When returning String as response, this is a String. This is ignored for other types of responses.path String (optional) - Path to the file which would be sent as response body. This is only used for file responses.url String (optional) - Download the url and pipe the result as response body. This is only used for URL responses.referrer String (optional) - The referrer URL. This is only used for file and URL responses.method String (optional) - The HTTP method. This is only used for file and URL responses.session Session (optional) - The session used for requesting URL, by default the HTTP request will reuse the current session. Setting session to null would use a random independent session. This is only used for URL responses.uploadData ProtocolResponseUploadData (optional) - The data used as upload data. This is only used for URL responses when method is \"POST\".contentType String - MIME type of the content.data String | Buffer - Content to be sent.Fork the project on GitHub and clone your fork locally.
\n$ git clone git@github.com:username/electron.git\n$ cd electron\n$ git remote add upstream https://github.com/electron/electron.git\n$ git fetch upstream\nBuild steps and dependencies differ slightly depending on your operating system. See these detailed guides on building Electron locally:
\n\nOnce you've built the project locally, you're ready to start making changes!
\nTo keep your development environment organized, create local branches to hold your work. These should be branched directly off of the main branch.
$ git checkout -b my-branch -t upstream/main\nMost pull requests opened against the electron/electron repository include changes to either the C/C++ code in the shell/ folder, the JavaScript code in the lib/ folder, the documentation in docs/api/ or tests in the spec/ folder.
Please be sure to run npm run lint from time to time on any code changes to ensure that they follow the project's code style.
See coding style for more information about best practice when modifying code in different parts of the project.
\nIt is recommended to keep your changes grouped logically within individual commits. Many contributors find it easier to review changes that are split across multiple commits. There is no limit to the number of commits in a pull request.
\n$ git add my/changed/files\n$ git commit\nNote that multiple commits often get squashed when they are landed.
\nA good commit message should describe what changed and why. The Electron project uses semantic commit messages to streamline the release process.
\nBefore a pull request can be merged, it must have a pull request title with a semantic prefix.
\nExamples of commit messages with semantic prefixes:
\nfix: don't overwrite prevent_default if default wasn't preventedfeat: add app.isPackaged() methoddocs: app.isDefaultProtocolClient is now available on LinuxCommon prefixes:
\nOther things to keep in mind when writing a commit message:
\nA commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with Major in semantic versioning). A breaking change can be part of commits of any type. e.g., a fix:, feat: & chore: types would all be valid, in addition to any other type.
See conventionalcommits.org for more details.
\nOnce you have committed your changes, it is a good idea to use git rebase (not git merge) to synchronize your work with the main repository.
$ git fetch upstream\n$ git rebase upstream/main\nThis ensures that your working branch has the latest changes from electron/electron main.
Bug fixes and features should always come with tests. A testing guide has been provided to make the process easier. Looking at other tests to see how they should be structured can also help.
\nBefore submitting your changes in a pull request, always run the full test suite. To run the tests:
\n$ npm run test\nMake sure the linter does not report any issues and that all tests pass. Please do not submit patches that fail either check.
\nIf you are updating tests and want to run a single spec to check it:
\n$ npm run test -match=menu\nThe above would only run spec modules matching menu, which is useful for anyone who's working on tests that would otherwise be at the very end of the testing cycle.
Once your commits are ready to go -- with passing tests and linting -- begin the process of opening a pull request by pushing your working branch to your fork on GitHub.
\n$ git push origin my-branch\nFrom within GitHub, opening a new pull request will present you with a template that should be filled out:
\n<!--\nThank you for your pull request. Please provide a description above and review\nthe requirements below.\n\nBug fixes and new features should include tests and possibly benchmarks.\n\nContributors guide: https://github.com/electron/electron/blob/main/CONTRIBUTING.md\n-->\nYou will probably get feedback or requests for changes to your pull request. This is a big part of the submission process so don't be discouraged! Some contributors may sign off on the pull request right away. Others may have detailed comments or feedback. This is a necessary part of the process in order to evaluate whether the changes are correct and necessary.
\nTo make changes to an existing pull request, make the changes to your local branch, add a new commit with those changes, and push those to your fork. GitHub will automatically update the pull request.
\n$ git add my/changed/files\n$ git commit\n$ git push origin my-branch\nThere are a number of more advanced mechanisms for managing commits using git rebase that can be used, but are beyond the scope of this guide.
Feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer on something. If you encounter words or acronyms that seem unfamiliar, refer to this glossary.
\nAll pull requests require approval from a Code Owner of the area you modified in order to land. Whenever a maintainer reviews a pull request they may request changes. These may be small, such as fixing a typo, or may involve substantive changes. Such requests are intended to be helpful, but at times may come across as abrupt or unhelpful, especially if they do not include concrete suggestions on how to change them.
\nTry not to be discouraged. If you feel that a review is unfair, say so or seek the input of another project contributor. Often such comments are the result of a reviewer having taken insufficient time to review and are not ill-intended. Such difficulties can often be resolved with a bit of patience. That said, reviewers should be expected to provide helpful feedback.
\nIn order to land, a pull request needs to be reviewed and approved by at least one Electron Code Owner and pass CI. After that, if there are no objections from other contributors, the pull request can be merged.
\nCongratulations and thanks for your contribution!
\nEvery pull request is tested on the Continuous Integration (CI) system to confirm that it works on Electron's supported platforms.
\nIdeally, the pull request will pass (\"be green\") on all of CI's platforms. This means that all tests pass and there are no linting errors. However, it is not uncommon for the CI infrastructure itself to fail on specific platforms or for so-called \"flaky\" tests to fail (\"be red\"). Each CI failure must be manually inspected to determine the cause.
\nCI starts automatically when you open a pull request, but only core maintainers can restart a CI run. If you believe CI is giving a false negative, ask a maintainer to restart the tests.
", "title": "Pull Requests", "description": "" }, "/docs/tutorial/quick-start": { "locale": "pt-BR", "slug": "quick-start", "href": "/docs/tutorial/quick-start", "crowdinFileId": "256237", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/quick-start.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Este guia guiará você através do processo de criação de um aplicativo barebones Hello World no Electron, similar a electron/electron-quick-start.
Ao final deste tutorial, sua aplicação abrirá uma janela do navegador que exibe uma página com informações sobre qual Chromium, Node.js, e versões do Electron estão sendo executadas.
\nPara usar o Electron, você precisa instalar o Node.js. Recomendamos que você use a versão mais recente disponível do LTS.
\n\nPor favor, instale o Node.js usando instaladores específicos para sua plataforma. Caso contrário, você pode encontrar problemas de incompatibilidade com ferramentas de desenvolvimento diferentes.
\n
Para verificar se o Node.js foi instalado corretamente, digite os seguintes comandos em seu terminal de comando:
\nnode -v\nnpm -v\nOs comandos devem imprimir as versões do Node.js e npm, respectivamente.
\nObservação: como o Electron incorpora Node.js em seu binário, a versão do Node.js em execução seu código não está relacionado à versão em execução em seu sistema.
\nAplicativos Electron seguem a mesma estrutura geral que outros projetos Node.js. Comece criando uma pasta e inicializando um pacote npm.
\nmkdir my-electron-app && cd my-electron-app\nnpm init\nO comando interativo init solicitará que você defina alguns campos em sua configuração. Existem algumas regras a seguir para os propósitos deste tutorial:
entry point deve ser main.js.author e description podem ser de qualquer valor, mas são necessários para o pacote do aplicativos.Seu arquivo package.json deve ser parecido com isto:
{\n \"name\": \"my-electron-app\",\n \"version\": \"1.0.0\",\n \"description\": \"Hello World!\",\n \"main\": \"main.js\",\n \"author\": \"Jane Doe\",\n \"license\": \"MIT\"\n}\nEm seguida, instale o pacote electron nas devDependencies do seu aplicativo.
$ npm install --save-dev electron\n\n\nNota: Se você estiver encontrando algum problema com a instalação do Electron, por favor consulte o guia de Instalação avançada.
\n
Finalmente, você deve ser capaz de executar o Electron. No campo scripts de sua package.json config, adicione um comando start assim:
{\n \"scripts\": {\n \"start\": \"electron .\"\n }\n}\nEste comando start permitirá que você abra seu aplicativo em modo de desenvolvimento.
npm start\n\n\nNota: Este script diz ao Electron para ser executado na pasta raiz do seu projeto. Neste estágio, o seu aplicativo lançará imediatamente um erro informando que ele não consegue encontrar um aplicativo para executar.
\n
O ponto de entrada de qualquer aplicação Electron é o script main. Este script controla o processo principal, que é executado em um ambiente Node.js completo e é responsável por controlar o ciclo de vida de seu aplicativo, exibindo interfaces nativas, realizando todas as operações necessárias e gerenciando os processos de renderização (mais sobre isso mais tarde).
During execution, Electron will look for this script in the main field of the app's package.json config, which you should have configured during the app scaffolding step.
Para inicializar o script main, crie um arquivo vazio com o nome main.js na pasta raíz do seu projeto.
\n\nNota: Se você executar o script
\nstartnovamente neste ponto, sua aplicação não irá lançar qualquer erro! Entretanto, ela não fará nada, visto que não adicionamos nenhum código no arquivomain.js.
Antes de criarmos uma janela para a nossa aplicação, precisamos criar o conteúdo que será carregado dentro dela. No Electron, cada janela exibe um conteúdo web, que pode ser carregado de um arquivo HTML local ou de um URL remoto.
\nPara este tutorial, você fará a página html primeiro. Crie um arquivo index.html na pasta raíz do seu projeto:
\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n Estamos utilizando Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n e Electron <span id=\"electron-version\"></span>.\n </body>\n</html>\n\n\nNota: Olhando para este documento HTML, você pode observar que os números das versões estão faltando dentro do texto. Nós vamos inserir manualmente mais tarde, utilizando JavaScript.
\n
Agora que você já tem uma página web, carregue-a na janela do aplicativo. Para fazer isso, você precisa de dois módulos do Electron:
\napp, que controla os eventos do ciclo de vida de sua aplicação.BrowserWindow, que cria e gerencia as janelas da sua aplicação.Pelo fato do processo principal ser executado em Node.js, você pode importá-los como módulos CommonJS no topo de seu arquivo:
\nconst { app, BrowserWindow } = require('electron')\nEntão, adicione a função createWindow() que carregará o arquivo index.html em uma nova instância do BrowserWindow.
function createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\nO próximo passo é chamar a função createWindow() que abrirá a janela.
No Electron, janelas do navegador só podem ser criadas após o módulo app disparar o evento ready. Você pode esperar por este evento utilizando a API app.whenReady(). Chame a função createWindow() após whenReady() resolver a Promise.
app.whenReady().then(() => {\n createWindow()\n})\n\n\nNota: Neste ponto do tutorial, sua aplicação Electron deve abrir uma janela que mostra o conteúdo de sua página web!
\n
Although you can now open a browser window, you'll need some additional boilerplate code to make it feel more native to each platform. Application windows behave differently on each OS, and Electron puts the responsibility on developers to implement these conventions in their app.
\nIn general, you can use the process global's platform attribute to run code specifically for certain operating systems.
No Windows e no Linux, fechar todas as janelas geralmente encerra totalmente a aplicação.
\nTo implement this, listen for the app module's 'window-all-closed' event, and call app.quit() if the user is not on macOS (darwin).
app.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nWhereas Linux and Windows apps quit when they have no windows open, macOS apps generally continue running even without any windows open, and activating the app when no windows are available should open a new one.
\nTo implement this feature, listen for the app module's activate event, and call your existing createWindow() method if no browser windows are open.
Because windows cannot be created before the ready event, you should only listen for activate events after your app is initialized. Do this by attaching your event listener from within your existing whenReady() callback.
app.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n\nNote: At this point, your window controls should be fully functional!
\n
Now, the last thing to do is print out the version numbers for Electron and its dependencies onto your web page.
\nAccessing this information is trivial to do in the main process through Node's global process object. However, you can't just edit the DOM from the main process because it has no access to the renderer's document context. They're in entirely different processes!
\n\nNote: If you need a more in-depth look at Electron processes, see the Process Model document.
\n
This is where attaching a preload script to your renderer comes in handy. A preload script runs before the renderer process is loaded, and has access to both renderer globals (e.g. window and document) and a Node.js environment.
Create a new script named preload.js as such:
window.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\nThe above code accesses the Node.js process.versions object and runs a basic replaceText helper function to insert the version numbers into the HTML document.
To attach this script to your renderer process, pass in the path to your preload script to the webPreferences.preload option in your existing BrowserWindow constructor.
// include the Node.js 'path' module at the top of your file\nconst path = require('path')\n\n// modify your existing createWindow() function\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n}\n// ...\nThere are two Node.js concepts that are used here:
\n__dirname string points to the path of the currently executing script (in this case, your project's root folder).path.join API joins multiple path segments together, creating a combined path string that works across all platforms.We use a path relative to the currently executing JavaScript file so that your relative path will work in both development and packaged mode.
\nAt this point, you might be wondering how to add more functionality to your application.
\nFor any interactions with your web contents, you want to add scripts to your renderer process. Because the renderer runs in a normal web environment, you can add a <script> tag right before your index.html file's closing </body> tag to include any arbitrary scripts you want:
<script src=\"./renderer.js\"></script>\nThe code contained in renderer.js can then use the same JavaScript APIs and tooling you use for typical front-end development, such as using webpack to bundle and minify your code or React to manage your user interfaces.
After following the above steps, you should have a fully functional Electron application that looks like this:
\n
The full code is available below:
\n// main.js\n\n// Modules to control application life and create native browser window\nconst { app, BrowserWindow } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n // Create the browser window.\n const mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n // and load the index.html of the app.\n mainWindow.loadFile('index.html')\n\n // Open the DevTools.\n // mainWindow.webContents.openDevTools()\n}\n\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// Algumas APIs podem ser usadas somente depois que este evento ocorre.\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n // On macOS it's common to re-create a window in the app when the\n // dock icon is clicked and there are no other windows open.\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\n\n// In this file you can include the rest of your app's specific main process\n// code. Você também pode colocar eles em arquivos separados e requeridos-as aqui.\n// preload.js\n\n// All of the Node.js APIs are available in the preload process.\n// It has the same sandbox as a Chrome extension.\nwindow.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\n<!--index.html-->\n\n\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n\n <!-- You can also require other files to run in this process -->\n <script src=\"./renderer.js\"></script>\n </body>\n</html>\nTo summarize all the steps we've done:
\nWe bootstrapped a Node.js application and added Electron as a dependency.
\nWe created a main.js script that runs our main process, which controls our app\nand runs in a Node.js environment. In this script, we used Electron's app and\nBrowserWindow modules to create a browser window that displays web content\nin a separate process (the renderer).
In order to access certain Node.js functionality in the renderer, we attached\na preload script to our BrowserWindow constructor.
The fastest way to distribute your newly created app is using\nElectron Forge.
\nAdd Electron Forge as a development dependency of your app, and use its import command to set up\nForge's scaffolding:
```sh npm2yarn\nnpm install --save-dev @electron-forge/cli\nnpx electron-forge import\n\n✔ Checking your system\n✔ Initializing Git Repository\n✔ Writing modified package.json file\n✔ Installing dependencies\n✔ Writing modified package.json file\n✔ Fixing .gitignore\n\nWe have ATTEMPTED to convert your app to be in a format that electron-forge understands.\n\nThanks for using \"electron-forge\"!!!\n```\nCreate a distributable using Forge's make command:
npm run make\n\n> my-electron-app@1.0.0 make /my-electron-app\n> electron-forge make\n\n✔ Checking your system\n✔ Resolving Forge Config\nWe need to package your application before we can make it\n✔ Preparing to Package Application for arch: x64\n✔ Preparing native dependencies\n✔ Packaging Application\nMaking for the following targets: zip\n✔ Making for target: zip - On platform: darwin - For arch: x64\nElectron Forge creates the out folder where your package will be located:
// Example for macOS\nout/\n├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip\n├── ...\n└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app\nCertifique-se de usar a documentação correspondente a versão do Electron que você esta usando. A versão faz parte da URL desta página. Se não, você provavelmente esta usando a documentação da branch de desenvolvimento qual pode conter mudanças da API que pode não ser compatível com a sua versão do Electron. Para ver a documentação de versões anteriores, você pode procurar pelas tags no GitHub, para isso, abra o menu \"Switch branches/tags\" e selecione a tag da versão que você gostaria de ver.
\nThere are questions that are asked quite often. Check this out before creating an issue:
\n\nEsses tutoriais individuais explicam os tópicos discutidos no guia acima.
\nEstes guias destinam-se a pessoas que trabalham no projeto Electron. Para guias sobre o desenvolvimento de aplicativos Electron, consulte /docs/README.md.
\nWindows and macOS provide access to a list of recent documents opened by the application via JumpList or dock menu, respectively.
\nJumpList:
\n
Application dock menu:
\n
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\n\nconst fileName = 'recently-used.md'\nfs.writeFile(fileName, 'Lorem Ipsum', () => {\n app.addRecentDocument(path.join(__dirname, fileName))\n})\n\napp.whenReady().then(createWindow)\n\napp.on('window-all-closed', () => {\n app.clearRecentDocuments()\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nTo add a file to recent documents, use the app.addRecentDocument API.
\nAfter launching the Electron application, right click the application icon. In this guide, the item is a Markdown file located in the root of the project. You should see recently-used.md added to the list of recent files:
To clear the list of recent documents, use the app.clearRecentDocuments API. In this guide, the list of documents is cleared once all windows have been closed.
\nTo use this feature on Windows, your application has to be registered as a handler of the file type of the document, otherwise the file won't appear in JumpList even after you have added it. You can find everything on registering your application in Application Registration.
\nWhen a user clicks a file from the JumpList, a new instance of your application will be started with the path of the file added as a command line argument.
\nYou can add menu items to access and clear recent documents by adding the following code snippet to your menu template:
\n{\n \"submenu\":[\n {\n \"label\":\"Open Recent\",\n \"role\":\"recentdocuments\",\n \"submenu\":[\n {\n \"label\":\"Clear Recent\",\n \"role\":\"clearrecentdocuments\"\n }\n ]\n }\n ]\n}\nMake sure the application menu is added after the 'ready' event and not before, or the menu item will be disabled:
const { app, Menu } = require('electron')\n\nconst template = [\n // Menu template here\n]\nconst menu = Menu.buildFromTemplate(template)\n\napp.whenReady().then(() => {\n Menu.setApplicationMenu(menu)\n})\n
When a file is requested from the recent documents menu, the open-file event of app module will be emitted for it.
x Number - The x coordinate of the origin of the rectangle (must be an integer).y Number - The y coordinate of the origin of the rectangle (must be an integer).width Number - The width of the rectangle (must be an integer).height Number - The height of the rectangle (must be an integer).url String - HTTP Referrer URL.policy String - Can be default, unsafe-url, no-referrer-when-downgrade, no-referrer, origin, strict-origin-when-cross-origin, same-origin or strict-origin. See the Referrer-Policy spec for more details on the meaning of these values.Read-Eval-Print-Loop (REPL) is a simple, interactive computer programming environment that takes single user inputs (i.e. single expressions), evaluates them, and returns the result to the user.
\nElectron exposes the Node.js repl module through the --interactive CLI flag. Assuming you have electron installed as a local project dependency, you should be able to access the REPL with the following command:
./node_modules/.bin/electron --interactive\nNote: electron --interactive is not available on Windows (see electron/electron#5776 for more details).
You can use the DevTools Console tab to get a REPL for any renderer process. To learn more, read the Chrome documentation.
", "title": "REPL", "description": "" }, "/docs/tutorial/represented-file": { "locale": "pt-BR", "slug": "represented-file", "href": "/docs/tutorial/represented-file", "crowdinFileId": "256243", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/represented-file.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "On macOS, you can set a represented file for any window in your application. The represented file's icon will be shown in the title bar, and when users Command-Click or Control-Click, a popup with a path to the file will be shown.
\n\nNOTE: The screenshot above is an example where this feature is used to indicate the currently opened file in the Atom text editor.
\n
You can also set the edited state for a window so that the file icon can indicate whether the document in this window has been modified.
\nPara definir uma representação de arquivo de uma janela, você pode usar as APIs BrowserWindow.setRepresentedFilename e BrowserWindow.setDocumentEdited.
\nconst { app, BrowserWindow } = require('electron')\nconst os = require('os');\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n}\n\napp.whenReady().then(() => {\n const win = new BrowserWindow()\n\n win.setRepresentedFilename(os.homedir())\n win.setDocumentEdited(true)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nAfter launching the Electron application, click on the title with Command or Control key pressed. You should see a popup with the represented file at the top. In this guide, this is the current user's home directory:
\n\nAllows access to simple encryption and decryption of strings for storage on the local machine.
\n
Processo: Main
\nThis module protects data stored on disk from being accessed by other applications or users with full disk access.
\nNote that on Mac, access to the system Keychain is required and these calls can block the current thread to collect user input. The same is true for Linux, if a password management tool is available.
\nO módulo safeStorage tem os seguintes métodos:
safeStorage.isEncryptionAvailable()Returns Boolean - Whether encryption is available.
On Linux, returns true if the secret key is available. On MacOS, returns true if Keychain is available. On Windows, returns true with no other preconditions.
\nsafeStorage.encryptString(plainText)plainText StringReturns Buffer - An array of bytes representing the encrypted string.
This function will throw an error if encryption fails.
\nsafeStorage.decryptString(encrypted)encrypted BufferReturns String - the decrypted string. Decrypts the encrypted buffer obtained with safeStorage.encryptString back into a string.
This function will throw an error if decryption fails.
", "title": "safeStorage", "description": "Allows access to simple encryption and decryption of strings for storage on the local machine." }, "/docs/tutorial/sandbox": { "locale": "pt-BR", "slug": "sandbox", "href": "/docs/tutorial/sandbox", "crowdinFileId": "256245", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/sandbox.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "One key security feature in Chromium is that processes can be executed within a sandbox. The sandbox limits the harm that malicious code can cause by limiting access to most system resources — sandboxed processes can only freely use CPU cycles and memory. In order to perform operations requiring additional privilege, sandboxed processes use dedicated communication channels to delegate tasks to more privileged processes.
\nIn Chromium, sandboxing is applied to most processes other than the main process. This includes renderer processes, as well as utility processes such as the audio service, the GPU service and the network service.
\nSee Chromium's Sandbox design document for more information.
\nElectron comes with a mixed sandbox environment, meaning sandboxed processes can run alongside privileged ones. By default, renderer processes are not sandboxed, but utility processes are. Note that as in Chromium, the main (browser) process is privileged and cannot be sandboxed.
\nHistorically, this mixed sandbox approach was established because having Node.js available in the renderer is an extremely powerful tool for app developers. Unfortunately, this feature is also an equally massive security vulnerability.
\nTheoretically, unsandboxed renderers are not a problem for desktop applications that only display trusted code, but they make Electron less secure than Chromium for displaying untrusted web content. However, even purportedly trusted code may be dangerous — there are countless attack vectors that malicious actors can use, from cross-site scripting to content injection to man-in-the-middle attacks on remotely loaded websites, just to name a few. For this reason, we recommend enabling renderer sandboxing for the vast majority of cases under an abundance of caution.
\n\nNote that there is an active discussion in the issue tracker to enable renderer sandboxing by default. See #28466) for details.
\nSandboxed processes in Electron behave mostly in the same way as Chromium's do, but Electron has a few additional concepts to consider because it interfaces with Node.js.
\nWhen renderer processes in Electron are sandboxed, they behave in the same way as a regular Chrome renderer would. A sandboxed renderer won't have a Node.js environment initialized.
\n\nTherefore, when the sandbox is enabled, renderer processes can only perform privileged tasks (such as interacting with the filesystem, making changes to the system, or spawning subprocesses) by delegating these tasks to the main process via inter-process communication (IPC).
\nIn order to allow renderer processes to communicate with the main process, preload scripts attached to sandboxed renderers will still have a polyfilled subset of Node.js APIs available. A require function similar to Node's require module is exposed, but can only import a subset of Electron and Node's built-in modules:
In addition, the preload script also polyfills certain Node.js primitives as globals:
\nBufferprocessclearImmediatesetImmediateBecause the require function is a polyfill with limited functionality, you will not be able to use CommonJS modules to separate your preload script into multiple files. If you need to split your preload code, use a bundler such as webpack or Parcel.
Note that because the environment presented to the preload script is substantially more privileged than that of a sandboxed renderer, it is still possible to leak privileged APIs to untrusted code running in the renderer process unless contextIsolation is enabled.
In Electron, renderer sandboxing can be enabled on a per-process basis with the sandbox: true preference in the BrowserWindow constructor.
// main.js\napp.whenReady().then(() => {\n const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n })\n win.loadURL('https://google.com')\n})\nIf you want to force sandboxing for all renderers, you can also use the app.enableSandbox API. Note that this API has to be called before the app's ready event.
// main.js\napp.enableSandbox()\napp.whenReady().then(() => {\n // no need to pass `sandbox: true` since `app.enableSandbox()` was called.\n const win = new BrowserWindow()\n win.loadURL('https://google.com')\n})\nYou can also disable Chromium's sandbox entirely with the --no-sandbox CLI flag, which will disable the sandbox for all processes (including utility processes). We highly recommend that you only use this flag for testing purposes, and never in production.
Note that the sandbox: true option will still disable the renderer's Node.js environment.
Rendering untrusted content in Electron is still somewhat uncharted territory, though some apps are finding success (e.g. Beaker Browser). Our goal is to get as close to Chrome as we can in terms of the security of sandboxed content, but ultimately we will always be behind due to a few fundamental issues:
\nWhile we make our best effort to backport Chromium security fixes to older versions of Electron, we do not make a guarantee that every fix will be backported. Your best chance at staying secure is to be on the latest stable version of Electron.
", "title": "Process Sandboxing", "description": "" }, "/docs/api/screen": { "locale": "pt-BR", "slug": "screen", "href": "/docs/api/screen", "crowdinFileId": "256361", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/screen.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRecupere informações sobre o tamanho da tela, monitores, posição do cursor, etc.
\n
Processo: Main
\nEste módulo não pode ser usado até que o evento ready do módulo app seja emitido.
screen é um EventEmitter.
Nota: No renderizador / DevTools, window.screen é uma propriedade reservada do DOM, portanto, escrever let {screen} = require ('electron') pode não funcionar.
Um exemplo de criação de uma janela que preenche a tela inteira:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\napp.whenReady().then(() => {\n const { width, height } = screen.getPrimaryDisplay().workAreaSize\n win = new BrowserWindow({ width, height })\n win.loadURL('https://github.com')\n})\nAnother example of creating a window in the external display:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n const displays = screen.getAllDisplays()\n const externalDisplay = displays.find((display) => {\n return display.bounds.x !== 0 || display.bounds.y !== 0\n })\n\n if (externalDisplay) {\n win = new BrowserWindow({\n x: externalDisplay.bounds.x + 50,\n y: externalDisplay.bounds.y + 50\n })\n win.loadURL('https://github.com')\n }\n})\nO módulo screen emite os seguintes eventos:
Retorna:
\nevent EventnewDisplay DisplayEmitted when newDisplay has been added.
Retorna:
\nevent EventoldDisplay DisplayEmitted when oldDisplay has been removed.
Retorna:
\nevent Eventdisplay DisplaychangedMetrics String[]Emitted when one or more metrics change in a display. The changedMetrics is an array of strings that describe the changes. Possible changes are bounds, workArea, scaleFactor and rotation.
O módulo screen tem os seguintes métodos:
screen.getCursorScreenPoint()Retorna Point
The current absolute position of the mouse pointer.
\nNote: The return value is a DIP point, not a screen physical point.
\nscreen.getPrimaryDisplay()Returns Display - The primary display.
screen.getAllDisplays()Returns Display[] - An array of displays that are currently available.
screen.getDisplayNearestPoint(point)point PointReturns Display - The display nearest the specified point.
screen.getDisplayMatching(rect)rect RectangleReturns Display - The display that most closely intersects the provided bounds.
screen.screenToDipPoint(point) Windowspoint PointRetorna Point
Converts a screen physical point to a screen DIP point. The DPI scale is performed relative to the display containing the physical point.
\nscreen.dipToScreenPoint(point) Windowspoint PointRetorna Point
Converts a screen DIP point to a screen physical point. The DPI scale is performed relative to the display containing the DIP point.
\nscreen.screenToDipRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleRetorna Rectangle
Converts a screen physical rect to a screen DIP rect. The DPI scale is performed relative to the display nearest to window. If window is null, scaling will be performed to the display nearest to rect.
screen.dipToScreenRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleRetorna Rectangle
Converts a screen DIP rect to a screen physical rect. The DPI scale is performed relative to the display nearest to window. If window is null, scaling will be performed to the display nearest to rect.
label String (optional) - The text to appear in this item.icon NativeImage (optional) - The image to appear in this item.Como desenvolvedores web, nós geralmente usufruímos da forte segurança de rede disponibilizada pelos navegadores - os riscos associados com códigos que escrevemos são relativamente baixos. Nossos sites tem poderes limitados em uma caixa de areia e confiamos que nossos usuários desfrutam de num navegador construído por uma grande equipe de engenheiros os quais são capazes de responder rapidamente às ameaças de segurança recém-descobertas.
\nAo trabalhar com Electron, é importante entender que Electron não é um navegador web. Isto permite que você construa aplicações desktop ricas com tecnologias web familiar, mas seu código exerce um poder muito maior. JavaScript pode acessar o sistema de arquivos, o shell do usuário e muito mais. Isto permite que você crie aplicativos nativos de alta qualidade, mas os riscos de segurança inerentes escalam com os poderes adicionais concedidos ao seu código.
\nCom isso em mente, esteja ciente de que exibir conteúdo arbitrário de fontes não confiáveis representa um grave risco de segurança que o Electron não pretende manipular. Na verdade, os mais populares aplicativos do Electron (Atom, Slack, Visual Studio Code, etc) exibem principalmente conteúdo local (ou confiáveis, conteúdo remoto seguro, sem a integração com Node) - se sua aplicação executa código de uma fonte online, é sua responsabilidade que o código não seja malicioso.
\nPara obter informações sobre como divulgar adequadamente uma vulnerabilidade do Electron, consulte SECURITY.md
\nElectron keeps up to date with alternating Chromium releases. For more information, see the Electron Release Cadence blog post.
\nIt is important to remember that the security of your Electron application is the result of the overall security of the framework foundation (Chromium, Node.js), Electron itself, all NPM dependencies and your code. As such, it is your responsibility to follow a few important best practices:
\nMantenha sua aplicação atualizada com a última versão do framework Electron. Ao lançar seu produto, você também está enviando um pacote composto pelo Electron, Biblioteca Compartilhada do Chromium e Node.js. Vulnerabilidades afetando estes componentes podem afetar a segurança do seu aplicativo. Ao atualizar o Electron para a versão mais recente, você garante que as vulnerabilidades críticas (como nodeIntegration bypasses) já estão corrigidas e não podem ser exploradas em seu aplicativo. For more information, see \"Use a current version of Electron\".
\nAvalie suas dependências. O NPM fornece meio milhão de pacotes reutilizáveis, mas é sua responsabilidade escolher bibliotecas de terceiros confiáveis. Se você usar bibliotecas desatualizadas afetadas por vulnerabilidades conhecidas ou se depender de código mal mantido, a segurança do aplicativo pode estar comprometida.
\nAdote práticas seguras de codificação. A primeira linha de defesa para seu aplicativo é seu próprio código. Common web vulnerabilities, such as Cross-Site Scripting (XSS), have a higher security impact on Electron applications hence it is highly recommended to adopt secure software development best practices and perform security testing.
\nA security issue exists whenever you receive code from an untrusted source (e.g. a remote server) and execute it locally. As an example, consider a remote website being displayed inside a default BrowserWindow. If an attacker somehow manages to change said content (either by attacking the source directly, or by sitting between your app and the actual destination), they will be able to execute native code on the user's machine.
\n\n⚠️ Under no circumstances should you load and execute remote code with Node.js integration enabled. Instead, use only local files (packaged together with your application) to execute Node.js code. To display remote content, use the
\n<webview>tag orBrowserView, make sure to disable thenodeIntegrationand enablecontextIsolation.
From Electron 2.0 on, developers will see warnings and recommendations printed to the developer console. They only show up when the binary's name is Electron, indicating that a developer is currently looking at the console.
\nYou can force-enable or force-disable these warnings by setting ELECTRON_ENABLE_SECURITY_WARNINGS or ELECTRON_DISABLE_SECURITY_WARNINGS on either process.env or the window object.
You should at least follow these steps to improve the security of your application:
\nses.setPermissionRequestHandler() in all sessions that load remote contentwebSecurityContent-Security-Policy and use restrictive rules (i.e. script-src 'self')allowRunningInsecureContent to trueenableBlinkFeatures<webview>: Do not use allowpopups<webview>: Verify options and paramsopenExternal with untrusted contentTo automate the detection of misconfigurations and insecure patterns, it is possible to use electronegativity. For additional details on potential weaknesses and implementation bugs when developing applications using Electron, please refer to this guide for developers and auditors
\nAny resources not included with your application should be loaded using a secure protocol like HTTPS. In other words, do not use insecure protocols like HTTP. Similarly, we recommend the use of WSS over WS, FTPS over FTP, and so on.
HTTPS has three main benefits:
1) It authenticates the remote server, ensuring your app connects to the correct host instead of an impersonator. 2) It ensures data integrity, asserting that the data was not modified while in transit between your application and the host. 3) It encrypts the traffic between your user and the destination host, making it more difficult to eavesdrop on the information sent between your app and the host.
\n// Bad\nbrowserWindow.loadURL('http://example.com')\n\n// Good\nbrowserWindow.loadURL('https://example.com')\n<!-- Bad -->\n<script crossorigin src=\"http://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"http://example.com/style.css\">\n\n<!-- Good -->\n<script crossorigin src=\"https://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"https://example.com/style.css\">\nThis recommendation is the default behavior in Electron since 5.0.0.
\nIt is paramount that you do not enable Node.js integration in any renderer (BrowserWindow, BrowserView, or <webview>) that loads remote content. The goal is to limit the powers you grant to remote content, thus making it dramatically more difficult for an attacker to harm your users should they gain the ability to execute JavaScript on your website.
After this, you can grant additional permissions for specific hosts. For example, if you are opening a BrowserWindow pointed at https://example.com/, you can give that website exactly the abilities it needs, but no more.
A cross-site-scripting (XSS) attack is more dangerous if an attacker can jump out of the renderer process and execute code on the user's computer. Cross-site-scripting attacks are fairly common - and while an issue, their power is usually limited to messing with the website that they are executed on. Disabling Node.js integration helps prevent an XSS from being escalated into a so-called \"Remote Code Execution\" (RCE) attack.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n nodeIntegration: true,\n nodeIntegrationInWorker: true\n }\n})\n\nmainWindow.loadURL('https://example.com')\n// Good\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n preload: path.join(app.getAppPath(), 'preload.js')\n }\n})\n\nmainWindow.loadURL('https://example.com')\n<!-- Bad -->\n<webview nodeIntegration src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nWhen disabling Node.js integration, you can still expose APIs to your website that do consume Node.js modules or features. Preload scripts continue to have access to require and other Node.js features, allowing developers to expose a custom API to remotely loaded content.
In the following example preload script, the later loaded website will have access to a window.readConfig() method, but no Node.js features.
const { readFileSync } = require('fs')\n\nwindow.readConfig = function () {\n const data = readFileSync('./config.json')\n return data\n}\nContext isolation is an Electron feature that allows developers to run code in preload scripts and in Electron APIs in a dedicated JavaScript context. In practice, that means that global objects like Array.prototype.push or JSON.parse cannot be modified by scripts running in the renderer process.
Electron uses the same technology as Chromium's Content Scripts to enable this behavior.
\nEven when nodeIntegration: false is used, to truly enforce strong isolation and prevent the use of Node primitives contextIsolation must also be used.
For more information on what contextIsolation is and how to enable it please see our dedicated Context Isolation document.
Sandboxing is a Chromium feature that uses the operating system to significantly limit what renderer processes have access to. You should enable the sandbox in all renderers. Loading, reading or processing any untrusted content in an unsandboxed process, including the main process, is not advised.
\nWhen creating a window, pass the sandbox: true option in webPreferences:
const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n})\nYou may have seen permission requests while using Chrome: They pop up whenever the website attempts to use a feature that the user has to manually approve ( like notifications).
\nThe API is based on the Chromium permissions API and implements the same types of permissions.
\nBy default, Electron will automatically approve all permission requests unless the developer has manually configured a custom handler. While a solid default, security-conscious developers might want to assume the very opposite.
\nconst { session } = require('electron')\n\nsession\n .fromPartition('some-partition')\n .setPermissionRequestHandler((webContents, permission, callback) => {\n const url = webContents.getURL()\n\n if (permission === 'notifications') {\n // Approves the permissions request\n callback(true)\n }\n\n // Verify URL\n if (!url.startsWith('https://example.com/')) {\n // Denies the permissions request\n return callback(false)\n }\n })\nRecommendation is Electron's default
\nYou may have already guessed that disabling the webSecurity property on a renderer process (BrowserWindow, BrowserView, or <webview>) disables crucial security features.
Do not disable webSecurity in production applications.
Disabling webSecurity will disable the same-origin policy and set allowRunningInsecureContent property to true. In other words, it allows the execution of insecure code from different domains.
// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n webSecurity: false\n }\n})\n// Good\nconst mainWindow = new BrowserWindow()\n<!-- Bad -->\n<webview disablewebsecurity src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nA Content Security Policy (CSP) is an additional layer of protection against cross-site-scripting attacks and data injection attacks. We recommend that they be enabled by any website you load inside Electron.
\nCSP allows the server serving content to restrict and control the resources Electron can load for that given web page. https://example.com should be allowed to load scripts from the origins you defined while scripts from https://evil.attacker.com should not be allowed to run. Defining a CSP is an easy way to improve your application's security.
The following CSP will allow Electron to execute scripts from the current website and from apis.example.com.
// Bad\nContent-Security-Policy: '*'\n\n// Good\nContent-Security-Policy: script-src 'self' https://apis.example.com\nElectron respects the Content-Security-Policy HTTP header which can be set using Electron's webRequest.onHeadersReceived handler:
const { session } = require('electron')\n\nsession.defaultSession.webRequest.onHeadersReceived((details, callback) => {\n callback({\n responseHeaders: {\n ...details.responseHeaders,\n 'Content-Security-Policy': ['default-src \\'none\\'']\n }\n })\n})\nCSP's preferred delivery mechanism is an HTTP header, however it is not possible to use this method when loading a resource using the file:// protocol. It can be useful in some cases, such as using the file:// protocol, to set a policy on a page directly in the markup using a <meta> tag:
<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'\">\nallowRunningInsecureContent to trueRecommendation is Electron's default
\nBy default, Electron will not allow websites loaded over HTTPS to load and execute scripts, CSS, or plugins from insecure sources (HTTP). Setting the property allowRunningInsecureContent to true disables that protection.
Loading the initial HTML of a website over HTTPS and attempting to load subsequent resources via HTTP is also known as \"mixed content\".
Loading content over HTTPS assures the authenticity and integrity of the loaded resources while encrypting the traffic itself. See the section on only displaying secure content for more details.
// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n allowRunningInsecureContent: true\n }\n})\n// Good\nconst mainWindow = new BrowserWindow({})\nRecommendation is Electron's default
\nAdvanced users of Electron can enable experimental Chromium features using the experimentalFeatures property.
Experimental features are, as the name suggests, experimental and have not been enabled for all Chromium users. Furthermore, their impact on Electron as a whole has likely not been tested.
\nLegitimate use cases exist, but unless you know what you are doing, you should not enable this property.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n experimentalFeatures: true\n }\n})\n// Good\nconst mainWindow = new BrowserWindow({})\nenableBlinkFeaturesRecommendation is Electron's default
\nBlink is the name of the rendering engine behind Chromium. As with experimentalFeatures, the enableBlinkFeatures property allows developers to enable features that have been disabled by default.
Generally speaking, there are likely good reasons if a feature was not enabled by default. Legitimate use cases for enabling specific features exist. As a developer, you should know exactly why you need to enable a feature, what the ramifications are, and how it impacts the security of your application. Under no circumstances should you enable features speculatively.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n enableBlinkFeatures: 'ExecCommandInJavaScript'\n }\n})\n// Good\nconst mainWindow = new BrowserWindow()\nallowpopupsRecommendation is Electron's default
\nIf you are using <webview>, you might need the pages and scripts loaded in your <webview> tag to open new windows. The allowpopups attribute enables them to create new BrowserWindows using the window.open() method. <webview> tags are otherwise not allowed to create new windows.
If you do not need popups, you are better off not allowing the creation of new BrowserWindows by default. This follows the principle of minimally required access: Don't let a website create new popups unless you know it needs that feature.
<!-- Bad -->\n<webview allowpopups src=\"page.html\"></webview>\n\n<!-- Good -->\n<webview src=\"page.html\"></webview>\nA WebView created in a renderer process that does not have Node.js integration enabled will not be able to enable integration itself. However, a WebView will always create an independent renderer process with its own webPreferences.
It is a good idea to control the creation of new <webview> tags from the main process and to verify that their webPreferences do not disable security features.
Since <webview> live in the DOM, they can be created by a script running on your website even if Node.js integration is otherwise disabled.
Electron enables developers to disable various security features that control a renderer process. In most cases, developers do not need to disable any of those features - and you should therefore not allow different configurations for newly created <webview> tags.
Before a <webview> tag is attached, Electron will fire the will-attach-webview event on the hosting webContents. Use the event to prevent the creation of webViews with possibly insecure options.
app.on('web-contents-created', (event, contents) => {\n contents.on('will-attach-webview', (event, webPreferences, params) => {\n // Strip away preload scripts if unused or verify their location is legitimate\n delete webPreferences.preload\n delete webPreferences.preloadURL\n\n // Disable Node.js integration\n webPreferences.nodeIntegration = false\n\n // Verify URL being loaded\n if (!params.src.startsWith('https://example.com/')) {\n event.preventDefault()\n }\n })\n})\nAgain, this list merely minimizes the risk, it does not remove it. If your goal is to display a website, a browser will be a more secure option.
\nIf your app has no need to navigate or only needs to navigate to known pages, it is a good idea to limit navigation outright to that known scope, disallowing any other kinds of navigation.
\nNavigation is a common attack vector. If an attacker can convince your app to navigate away from its current page, they can possibly force your app to open web sites on the Internet. Even if your webContents are configured to be more secure (like having nodeIntegration disabled or contextIsolation enabled), getting your app to open a random web site will make the work of exploiting your app a lot easier.
A common attack pattern is that the attacker convinces your app's users to interact with the app in such a way that it navigates to one of the attacker's pages. This is usually done via links, plugins, or other user-generated content.
\nIf your app has no need for navigation, you can call event.preventDefault() in a will-navigate handler. If you know which pages your app might navigate to, check the URL in the event handler and only let navigation occur if it matches the URLs you're expecting.
We recommend that you use Node's parser for URLs. Simple string comparisons can sometimes be fooled - a startsWith('https://example.com') test would let https://example.com.attacker.com through.
const URL = require('url').URL\n\napp.on('web-contents-created', (event, contents) => {\n contents.on('will-navigate', (event, navigationUrl) => {\n const parsedUrl = new URL(navigationUrl)\n\n if (parsedUrl.origin !== 'https://example.com') {\n event.preventDefault()\n }\n })\n})\nIf you have a known set of windows, it's a good idea to limit the creation of additional windows in your app.
\nMuch like navigation, the creation of new webContents is a common attack vector. Attackers attempt to convince your app to create new windows, frames, or other renderer processes with more privileges than they had before; or with pages opened that they couldn't open before.
If you have no need to create windows in addition to the ones you know you'll need to create, disabling the creation buys you a little bit of extra security at no cost. This is commonly the case for apps that open one BrowserWindow and do not need to open an arbitrary number of additional windows at runtime.
webContents will delegate to its window open handler before creating new windows. The handler will receive, amongst other parameters, the url the window was requested to open and the options used to create it. We recommend that you register a handler to monitor the creation of windows, and deny any unexpected window creation.
const { shell } = require('electron')\n\napp.on('web-contents-created', (event, contents) => {\n contents.setWindowOpenHandler(({ url }) => {\n // In this example, we'll ask the operating system\n // to open this event's url in the default browser.\n //\n // See the following item for considerations regarding what\n // URLs should be allowed through to shell.openExternal.\n if (isSafeForExternalOpen(url)) {\n setImmediate(() => {\n shell.openExternal(url)\n })\n }\n\n return { action: 'deny' }\n })\n})\nopenExternal with untrusted contentShell's openExternal allows opening a given protocol URI with the desktop's native utilities. On macOS, for instance, this function is similar to the open terminal command utility and will open the specific application based on the URI and filetype association.
Improper use of openExternal can be leveraged to compromise the user's host. When openExternal is used with untrusted content, it can be leveraged to execute arbitrary commands.
// Bad\nconst { shell } = require('electron')\nshell.openExternal(USER_CONTROLLED_DATA_HERE)\n// Good\nconst { shell } = require('electron')\nshell.openExternal('https://example.com/index.html')\nYou should strive for always using the latest available version of Electron. Whenever a new major version is released, you should attempt to update your app as quickly as possible.
\nAn application built with an older version of Electron, Chromium, and Node.js is an easier target than an application that is using more recent versions of those components. Generally speaking, security issues and exploits for older versions of Chromium and Node.js are more widely available.
\nBoth Chromium and Node.js are impressive feats of engineering built by thousands of talented developers. Given their popularity, their security is carefully tested and analyzed by equally skilled security researchers. Many of those researchers disclose vulnerabilities responsibly, which generally means that researchers will give Chromium and Node.js some time to fix issues before publishing them. Your application will be more secure if it is running a recent version of Electron (and thus, Chromium and Node.js) for which potential security issues are not as widely known.
", "title": "Segurança, Capacidades Nativas e Suas Responsabilidades", "description": "⚠️ Under no circumstances should you load and execute remote code with Node.js integration enabled. Instead, use only local files (packaged together with your application) to execute Node.js code. To display remote content, use thelabel String (optional) - The text to appear in this segment.icon NativeImage (optional) - The image to appear in this segment.enabled Boolean (optional) - Whether this segment is selectable. Default: true.portId String - Unique identifier for the port.portName String - Name of the port.displayName String - A string suitable for display to the user for describing this device.vendorId String - Optional USB vendor ID.productId String - Optional USB product ID.serialNumber String - The USB device serial number.usbDriverName String (optional) - Represents a single serial port on macOS can be enumerated by multiple drivers.deviceInstanceId String (optional) - A stable identifier on Windows that can be used for device permissions.scriptUrl String - The full URL to the script that this service worker runsscope String - The base URL that this service worker is active for.renderProcessId Number - The virtual ID of the process that this service worker is running in. This is not an OS level PID. This aligns with the ID set used for webContents.getProcessId().\n\nQuery and receive events from a sessions active service workers.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Instâncias da classe ServiceWorkers são acessadas através da propriedade serviceWorkers de uma Sessão.
Como por exemplo:
\nconst { session } = require('electron')\n\n// Get all service workers.\nconsole.log(session.defaultSession.serviceWorkers.getAllRunning())\n\n// Handle logs and get service worker info\nsession.defaultSession.serviceWorkers.on('console-message', (event, messageDetails) => {\n console.log(\n 'Got service worker message',\n messageDetails,\n 'from',\n session.defaultSession.serviceWorkers.getFromVersionID(messageDetails.versionId)\n )\n})\nOs seguintes eventos estão disponíveis em instâncias de ServiceWorkers:
Retorna:
\nevent EventmessageDetails Object - Information about the console messagemessage String - The actual console messageversionId Number - The version ID of the service worker that sent the log messagesource String - The type of source for this message. Can be javascript, xml, network, console-api, storage, app-cache, rendering, security, deprecation, worker, violation, intervention, recommendation or other.level Number - The log level, from 0 to 3. In order it matches verbose, info, warning and error.sourceUrl String - The URL the message came fromlineNumber Number - The line number of the source that triggered this console messageEmitted when a service worker logs something to the console.
\nRetorna:
\nevent Eventdetails Object - Information about the registered service workerscope String - The base URL that a service worker is registered forEmitted when a service worker has been registered. Can occur after a call to navigator.serviceWorker.register('/sw.js') successfully resolves or when a Chrome extension is loaded.
The following methods are available on instances of ServiceWorkers:
serviceWorkers.getAllRunning()Returns Record<Number, ServiceWorkerInfo> - A ServiceWorkerInfo object where the keys are the service worker version ID and the values are the information about that service worker.
serviceWorkers.getFromVersionID(versionId)versionId NumberReturns ServiceWorkerInfo - Information about this service worker
If the service worker does not exist or is not running this method will throw an exception.
", "title": "ServiceWorkers", "description": "Query and receive events from a sessions active service workers." }, "/docs/api/session": { "locale": "pt-BR", "slug": "session", "href": "/docs/api/session", "crowdinFileId": "256365", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/session.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nManage browser sessions, cookies, cache, proxy settings, etc.
\n
Processo: Main
\nThe session module can be used to create new Session objects.
You can also access the session of existing pages by using the session property of WebContents, or from the session module.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nconst ses = win.webContents.session\nconsole.log(ses.getUserAgent())\nO módulo session tem os seguintes métodos:
session.fromPartition(partition[, options])partition Stringoptions (opcional)cache Boolean - Whether to enable cache.Returns Session - A session instance from partition string. When there is an existing Session with the same partition, it will be returned; otherwise a new Session instance will be created with options.
If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. if there is no persist: prefix, the page will use an in-memory session. If the partition is empty then default session of the app will be returned.
To create a Session with options, you have to ensure the Session with the partition has never been used before. There is no way to change the options of an existing Session object.
The session module has the following properties:
session.defaultsessionA Session object, the default session object of the app.
\n\nGet and set properties of a session.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
You can create a Session object in the session module:
const { session } = require('electron')\nconst ses = session.fromPartition('persist:name')\nconsole.log(ses.getUserAgent())\nOs seguintes eventos estão disponíveis em instâncias de Session:
Retorna:
\nevent Eventitem DownloadItemwebContents WebContentsEmitted when Electron is about to download item in webContents.
Calling event.preventDefault() will cancel the download and item will not be available from next tick of the process.
const { session } = require('electron')\nsession.defaultSession.on('will-download', (event, item, webContents) => {\n event.preventDefault()\n require('got')(item.getURL()).then((response) => {\n require('fs').writeFileSync('/somewhere', response.body)\n })\n})\nRetorna:
\nevent Eventextension ExtensionEmitted after an extension is loaded. This occurs whenever an extension is added to the \"enabled\" set of extensions. Isto inclui:
\nSession.loadExtension.chrome.runtime.reload()).Retorna:
\nevent Eventextension ExtensionEmitted after an extension is unloaded. This occurs when Session.removeExtension is called.
Retorna:
\nevent Eventextension ExtensionEmitted after an extension is loaded and all necessary browser state is initialized to support the start of the extension's background page.
\nRetorna:
\nevent EventpreconnectUrl String - The URL being requested for preconnection by the renderer.allowCredentials Boolean - True if the renderer is requesting that the connection include credentials (see the spec for more details.)Emitted when a render process requests preconnection to a URL, generally due to a resource hint.
\nRetorna:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file has been successfully initialized. This occurs after the file has been downloaded.
\nRetorna:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file starts downloading
\nRetorna:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file has been successfully downloaded
\nRetorna:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file download fails. For details on the failure you should collect a netlog and inspect the download request.
\nRetorna:
\nevent EventdetailsdeviceList HIDDevice[]frame WebFrameMaincallback FunctiondeviceId String | null (optional)Emitted when a HID device needs to be selected when a call to navigator.hid.requestDevice is made. callback should be called with deviceId to be selected; passing no arguments to callback will cancel the request. Additionally, permissioning on navigator.hid can be further managed by using ses.setPermissionCheckHandler(handler) and ses.setDevicePermissionHandler(handler)`.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nRetorna:
\nevent Eventdetailsdevice HIDDevice[]frame WebFrameMainEmitted when a new HID device becomes available. For example, when a new USB device is plugged in.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
Retorna:
\nevent Eventdetailsdevice HIDDevice[]frame WebFrameMainEmitted when a HID device has been removed. For example, this event will fire when a USB device is unplugged.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
Retorna:
\nevent EventportList SerialPort[]webContents WebContentscallback FunctionportId StringEmitted when a serial port needs to be selected when a call to navigator.serial.requestPort is made. callback should be called with portId to be selected, passing an empty string to callback will cancel the request. Additionally, permissioning on navigator.serial can be managed by using ses.setPermissionCheckHandler(handler) with the serial permission.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({\n width: 800,\n height: 600\n })\n win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {\n event.preventDefault()\n const selectedPort = portList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n if (!selectedPort) {\n callback('')\n } else {\n callback(selectedPort.portId)\n }\n })\n})\nRetorna:
\nevent Eventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a new serial port becomes available. For example, this event will fire when a new USB device is plugged in.
Retorna:
\nevent Eventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a serial port has been removed. For example, this event will fire when a USB device is unplugged.
The following methods are available on instances of Session:
ses.getCacheSize()Returns Promise<Integer> - the session's current cache size, in bytes.
ses.clearCache()Returns Promise<void> - resolves when the cache clear operation is complete.
Clears the session’s HTTP cache.
\nses.clearStorageData([options])options (opcional)origin String (optional) - Should follow window.location.origin’s representation scheme://host:port.storages String - The types of storages to clear, can contain: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage. If not specified, clear all storage types.quotas String - The types of quotas to clear, can contain: temporary, persistent, syncable. If not specified, clear all quotas.Returns Promise<void> - resolves when the storage data has been cleared.
ses.flushStorageData()Writes any unwritten DOMStorage data to disk.
\nses.setProxy(config)config Objectmode String (optional) - The proxy mode. Should be one of direct, auto_detect, pac_script, fixed_servers or system. If it's unspecified, it will be automatically determined based on other specified options.direct In direct mode all connections are created directly, without any proxy involved.auto_detect In auto_detect mode the proxy configuration is determined by a PAC script that can be downloaded at http://wpad/wpad.dat.pac_script In pac_script mode the proxy configuration is determined by a PAC script that is retrieved from the URL specified in the pacScript. This is the default mode if pacScript is specified.fixed_servers In fixed_servers mode the proxy configuration is specified in proxyRules. This is the default mode if proxyRules is specified.system In system mode the proxy configuration is taken from the operating system. Note that the system mode is different from setting no proxy configuration. In the latter case, Electron falls back to the system settings only if no command-line options influence the proxy configuration.pacScript String (optional) - The URL associated with the PAC file.proxyRules String (optional) - Rules indicating which proxies to use.proxyBypassRules String (optional) - Rules indicating which URLs should bypass the proxy settings.Returns Promise<void> - Resolves when the proxy setting process is complete.
Sets the proxy settings.
\nWhen mode is unspecified, pacScript and proxyRules are provided together, the proxyRules option is ignored and pacScript configuration is applied.
You may need ses.closeAllConnections to close currently in flight connections to prevent pooled sockets using previous proxy from being reused by future requests.
The proxyRules has to follow the rules below:
proxyRules = schemeProxies[\";\"<schemeProxies>]\nschemeProxies = [<urlScheme>\"=\"]<proxyURIList>\nurlScheme = \"http\" | \"https\" | \"ftp\" | \"socks\"\nproxyURIList = <proxyURL>[\",\"<proxyURIList>]\nproxyURL = [<proxyScheme>\"://\"]<proxyHost>[\":\"<proxyPort>]\nComo por exemplo:
\nhttp=foopy:80;ftp=foopy2 - Use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.foopy:80 - Use HTTP proxy foopy:80 for all URLs.foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing over to bar if foopy:80 is unavailable, and after that using no proxy.socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail over to the SOCKS5 proxy bar.com if foopy is unavailable.http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no proxy if foopy is unavailable.http=foopy;socks=foopy2 - Use HTTP proxy foopy for http URLs, and use socks4://foopy2 for all other URLs.The proxyBypassRules is a comma separated list of rules described below:
[ URL_SCHEME \"://\" ] HOSTNAME_PATTERN [ \":\" <port> ]
Match all hostnames that match the pattern HOSTNAME_PATTERN.
\nExamples: \"foobar.com\", \"foobar.com\", \".foobar.com\", \"foobar.com:99\", \"https://x..y.com:99\"
\n\".\" HOSTNAME_SUFFIX_PATTERN [ \":\" PORT ]
Match a particular domain suffix.
\nExamples: \".google.com\", \".com\", \"http://.google.com\"
\n[ SCHEME \"://\" ] IP_LITERAL [ \":\" PORT ]
Match URLs which are IP address literals.
\nExamples: \"127.0.1\", \"[0:0::1]\", \"[::1]\", \"http://[::1]:99\"
\nIP_LITERAL \"/\" PREFIX_LENGTH_IN_BITS
Match any URL that is to an IP literal that falls between the given range. IP range is specified using CIDR notation.
\nExamples: \"192.168.1.1/16\", \"fefe:13::abc/33\".
\n<local>
Match local addresses. The meaning of <local> is whether the host matches one of: \"127.0.0.1\", \"::1\", \"localhost\".
ses.resolveProxy(url)url URLReturns Promise<String> - Resolves with the proxy information for url.
ses.forceReloadProxyConfig()Returns Promise<void> - Resolves when the all internal states of proxy service is reset and the latest proxy configuration is reapplied if it's already available. The pac script will be fetched from pacScript again if the proxy mode is pac_script.
ses.setDownloadPath(path)path String - The download location.Sets download saving directory. By default, the download directory will be the Downloads under the respective app folder.
ses.enableNetworkEmulation(options)options Objectoffline Boolean (optional) - Whether to emulate network outage. Defaults to false.latency Double (optional) - RTT in ms. Defaults to 0 which will disable latency throttling.downloadThroughput Double (optional) - Download rate in Bps. Defaults to 0 which will disable download throttling.uploadThroughput Double (optional) - Upload rate in Bps. Defaults to 0 which will disable upload throttling.Emulates network with the given configuration for the session.
// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.\nwindow.webContents.session.enableNetworkEmulation({\n latency: 500,\n downloadThroughput: 6400,\n uploadThroughput: 6400\n})\n\n// To emulate a network outage.\nwindow.webContents.session.enableNetworkEmulation({ offline: true })\nses.preconnect(options)options Objecturl String - URL for preconnect. Only the origin is relevant for opening the socket.numSockets Number (optional) - number of sockets to preconnect. Must be between 1 and 6. Defaults to 1.Preconnects the given number of sockets to an origin.
\nses.closeAllConnections()Returns Promise<void> - Resolves when all connections are closed.
Note: It will terminate / fail all requests currently in flight.
\nses.disableNetworkEmulation()Disables any network emulation already active for the session. Resets to the original network configuration.
ses.setCertificateVerifyProc(proc)proc Function | nullrequest Objecthostname Stringcertificate CertificatevalidatedCertificate CertificateverificationResult String - Verification result from chromium.errorCode Integer - Error code.callback FunctionverificationResult Integer - Value can be one of certificate error codes from here. Apart from the certificate error codes, the following special codes can be used.0 - Indicates success and disables Certificate Transparency verification.-2 - Indicates failure.-3 - Uses the verification result from chromium.Sets the certificate verify proc for session, the proc will be called with proc(request, callback) whenever a server certificate verification is requested. Calling callback(0) accepts the certificate, calling callback(-2) rejects it.
Calling setCertificateVerifyProc(null) will revert back to default certificate verify proc.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.webContents.session.setCertificateVerifyProc((request, callback) => {\n const { hostname } = request\n if (hostname === 'github.com') {\n callback(0)\n } else {\n callback(-2)\n }\n})\n\n\nNOTE: The result of this procedure is cached by the network service.
\n
ses.setPermissionRequestHandler(handler)handler Function | nullwebContents WebContents - WebContents requesting the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.permission String - The type of requested permission.clipboard-read - Request access to read from the clipboard.media - Request access to media devices such as camera, microphone and speakers.display-capture - Request access to capture the screen.mediaKeySystem - Request access to DRM protected content.geolocation - Request access to user's current location.notifications - Request notification creation and the ability to display them in the user's system tray.midi - Request MIDI access in the webmidi API.midiSysex - Request the use of system exclusive messages in the webmidi API.pointerLock - Request to directly interpret mouse movements as an input method. Click here to know more.fullscreen - Request for the app to enter fullscreen mode.openExternal - Request to open links in external applications.unknown - An unrecognized permission requestcallback FunctionpermissionGranted Boolean - Allow or deny the permission.details Object - Some properties are only available on certain permission types.externalURL String (optional) - The url of the openExternal request.mediaTypes String - The types of media access being requested, elements can be video or audiorequestingUrl String - The last URL the requesting frame loadedisMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission requests for the session. Calling callback(true) will allow the permission and callback(false) will reject it. To clear the handler, call setPermissionRequestHandler(null). Please note that you must also implement setPermissionCheckHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied.
const { session } = require('electron')\nsession.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {\n if (webContents.getURL() === 'some-host' && permission === 'notifications') {\n return callback(false) // denied.\n }\n\n callback(true)\n})\nses.setPermissionCheckHandler(handler)handler Função\\webContents (WebContents | null) - WebContents checking the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin. All cross origin sub frames making permission checks will pass a null webContents to this handler, while certain other permission checks such as notifications checks will always pass null. You should use embeddingOrigin and requestingOrigin to determine what origin the owning frame and the requesting frame are on respectively.permission String - Type of permission check. Valid values are midiSysex, notifications, geolocation, media,mediaKeySystem,midi, pointerLock, fullscreen, openExternal, hid, or serial.requestingOrigin String - The origin URL of the permission checkdetails Object - Some properties are only available on certain permission types.embeddingOrigin String (optional) - The origin of the frame embedding the frame that made the permission check. Only set for cross-origin sub frames making permission checks.securityOrigin String (optional) - The security origin of the media check.mediaType String (optional) - The type of media access being requested, can be video, audio or unknownrequestingUrl String (optional) - The last URL the requesting frame loaded. This is not provided for cross-origin sub frames making permission checks.isMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission checks for the session. Returning true will allow the permission and false will reject it. Please note that you must also implement setPermissionRequestHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied. To clear the handler, call setPermissionCheckHandler(null).
const { session } = require('electron')\nconst url = require('url')\nsession.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {\n return true // granted\n }\n\n return false // denied\n})\nses.setDevicePermissionHandler(handler)handler Função\\detailsdeviceType String - The type of device that permission is being requested on, can be hid.origin String - The origin URL of the device permission check.device HIDDevice - the device that permission is being requested for.frame WebFrameMain - WebFrameMain checking the device permission.Sets the handler which can be used to respond to device permission checks for the session. Returning true will allow the device to be permitted and false will reject it. To clear the handler, call setDevicePermissionHandler(null). This handler can be used to provide default permissioning to devices without first calling for permission to devices (eg via navigator.hid.requestDevice). If this handler is not defined, the default device permissions as granted through device selection (eg via navigator.hid.requestDevice) will be used. Additionally, the default behavior of Electron is to store granted device permision through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nses.clearHostResolverCache()Returns Promise<void> - Resolves when the operation is complete.
Clears the host resolver cache.
\nses.allowNTLMCredentialsForDomains(domains)domains String - A comma-separated list of servers for which integrated authentication is enabled.Dynamically sets whether to always send credentials for HTTP NTLM or Negotiate authentication.
\nconst { session } = require('electron')\n// consider any url ending with `example.com`, `foobar.com`, `baz`\n// for integrated authentication.\nsession.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')\n\n// consider all urls for integrated authentication.\nsession.defaultSession.allowNTLMCredentialsForDomains('*')\nses.setUserAgent(userAgent[, acceptLanguages])userAgent StringacceptLanguages String (opcional)Overrides the userAgent and acceptLanguages for this session.
The acceptLanguages must a comma separated ordered list of language codes, for example \"en-US,fr,de,ko,zh-CN,ja\".
This doesn't affect existing WebContents, and each WebContents can use webContents.setUserAgent to override the session-wide user agent.
ses.isPersistent()Returns Boolean - Whether or not this session is a persistent one. The default webContents session of a BrowserWindow is persistent. When creating a session from a partition, session prefixed with persist: will be persistent, while others will be temporary.
ses.getUserAgent()Returns String - The user agent for this session.
ses.setSSLConfig(config)config ObjectminVersion String (optional) - Can be tls1, tls1.1, tls1.2 or tls1.3. The minimum SSL version to allow when connecting to remote servers. Padrão sendo tls1.maxVersion String (optional) - Can be tls1.2 or tls1.3. The maximum SSL version to allow when connecting to remote servers. O padrão é tls1.3.disabledCipherSuites Integer - List of cipher suites which should be explicitly prevented from being used in addition to those disabled by the net built-in policy. Supported literal forms: 0xAABB, where AA is cipher_suite[0] and BB is cipher_suite[1], as defined in RFC 2246, Section 7.4.1.2. Unrecognized but parsable cipher suites in this form will not return an error. Ex: To disable TLS_RSA_WITH_RC4_128_MD5, specify 0x0004, while to disable TLS_ECDH_ECDSA_WITH_RC4_128_SHA, specify 0xC002. Note that TLSv1.3 ciphers cannot be disabled using this mechanism.Sets the SSL configuration for the session. All subsequent network requests will use the new configuration. Existing network connections (such as WebSocket connections) will not be terminated, but old sockets in the pool will not be reused for new connections.
\nses.getBlobData(identifier)identifier String - Valid UUID.Returns Promise<Buffer> - resolves with blob data.
ses.downloadURL(url)urlInitiates a download of the resource at url. The API will generate a DownloadItem that can be accessed with the will-download event.
Note: This does not perform any security checks that relate to a page's origin, unlike webContents.downloadURL.
ses.createInterruptedDownload(options)options Objectpath String - Absolute path of the download.urlChain String[] - Complete URL chain for the download.mimeType String (opcional)offset Integer - Start range for the download.length Integer - Total length of the download.lastModified String (optional) - Last-Modified header value.eTag String (optional) - ETag header value.startTime Double (optional) - Time when download was started in number of seconds since UNIX epoch.Allows resuming cancelled or interrupted downloads from previous Session. The API will generate a DownloadItem that can be accessed with the will-download event. The DownloadItem will not have any WebContents associated with it and the initial state will be interrupted. The download will start only when the resume API is called on the DownloadItem.
ses.clearAuthCache()Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.
ses.setPreloads(preloads)preloads String[] - An array of absolute path to preload scriptsAdds scripts that will be executed on ALL web contents that are associated with this session just before normal preload scripts run.
ses.getPreloads()Returns String[] an array of paths to preload scripts that have been registered.
ses.setSpellCheckerEnabled(enable)enable BooleanSets whether to enable the builtin spell checker.
\nses.isSpellCheckerEnabled()Returns Boolean - Whether the builtin spell checker is enabled.
ses.setSpellCheckerLanguages(languages)languages String[] - An array of language codes to enable the spellchecker for.The built in spellchecker does not automatically detect what language a user is typing in. In order for the spell checker to correctly check their words you must call this API with an array of language codes. You can get the list of supported language codes with the ses.availableSpellCheckerLanguages property.
Note: On macOS the OS spellchecker is used and will detect your language automatically. This API is a no-op on macOS.
\nses.getSpellCheckerLanguages()Returns String[] - An array of language codes the spellchecker is enabled for. If this list is empty the spellchecker will fallback to using en-US. By default on launch if this setting is an empty list Electron will try to populate this setting with the current OS locale. This setting is persisted across restarts.
Note: On macOS the OS spellchecker is used and has its own list of languages. This API is a no-op on macOS.
\nses.setSpellCheckerDictionaryDownloadURL(url)url String - A base URL for Electron to download hunspell dictionaries from.By default Electron will download hunspell dictionaries from the Chromium CDN. If you want to override this behavior you can use this API to point the dictionary downloader at your own hosted version of the hunspell dictionaries. We publish a hunspell_dictionaries.zip file with each release which contains the files you need to host here, the file server must be case insensitive you must upload each file twice, once with the case it has in the ZIP file and once with the filename as all lower case.
Se os arquivos presentes em hunspell_dictionaries.zip estiverem disponíveis em https://example.com/dictionaries/language-code.bdic então você deve chamar esta api com ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Tome atenção à barra no final. A URL para os dicionários é formada como ${url}${filename}.
Note: On macOS the OS spellchecker is used and therefore we do not download any dictionary files. This API is a no-op on macOS.
\nses.listWordsInSpellCheckerDictionary()Returns Promise<String[]> - An array of all words in app's custom dictionary. Resolves when the full dictionary is loaded from disk.
ses.addWordToSpellCheckerDictionary(word)word String - The word you want to add to the dictionaryRetorna Boolean - Se a palavra foi escrita com sucesso no dicionário personalizado. This API will not work on non-persistent (in-memory) sessions.
Nota: No macOS e Windows 10, esta palavra será escrita também no dicionário personalizado do sistema operacional
\nses.removeWordFromSpellCheckerDictionary(word)word String - The word you want to remove from the dictionaryReturns Boolean - Whether the word was successfully removed from the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be removed from the OS custom dictionary as well
\nses.loadExtension(path[, options])path String - Path to a directory containing an unpacked Chrome extensionoptions (opcional)allowFileAccess Boolean - Whether to allow the extension to read local files over file:// protocol and inject content scripts into file:// pages. This is required e.g. for loading devtools extensions on file:// URLs. Defaults to false.Returns Promise<Extension> - resolves when the extension is loaded.
This method will raise an exception if the extension could not be loaded. If there are warnings when installing the extension (e.g. if the extension requests an API that Electron does not support) then they will be logged to the console.
\nNote that Electron does not support the full range of Chrome extensions APIs. See Supported Extensions APIs for more details on what is supported.
\nNote that in previous versions of Electron, extensions that were loaded would be remembered for future runs of the application. This is no longer the case: loadExtension must be called on every boot of your app if you want the extension to be loaded.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.on('ready', async () => {\n await session.defaultSession.loadExtension(\n path.join(__dirname, 'react-devtools'),\n // allowFileAccess is required to load the devtools extension on file:// URLs.\n { allowFileAccess: true }\n )\n // Note that in order to use the React DevTools extension, you'll need to\n // download and unzip a copy of the extension.\n})\nThis API does not support loading packed (.crx) extensions.
\nNote: This API cannot be called before the ready event of the app module is emitted.
Note: Loading extensions into in-memory (non-persistent) sessions is not supported and will throw an error.
\nses.removeExtension(extensionId)extensionId String - ID of extension to removeUnloads an extension.
\nNote: This API cannot be called before the ready event of the app module is emitted.
ses.getExtension(extensionId)extensionId String - ID of extension to queryReturns Extension | null - The loaded extension with the given ID.
Note: This API cannot be called before the ready event of the app module is emitted.
ses.getAllExtensions()Returns Extension[] - A list of all loaded extensions.
Note: This API cannot be called before the ready event of the app module is emitted.
ses.getStoragePath()A String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
As seguintes propriedades estão disponíveis em instâncias de Session:
ses.availableSpellCheckerLanguages ReadonlyUma matriz String[] que consiste em todas as linguagens de correção ortográfica disponíveis. Fornecer um código de idioma para a API setSpellCheckerLanguages que não está nesta matriz resultará em um erro.
ses.spellCheckerEnabledA Boolean indicating whether builtin spell checker is enabled.
ses.storagePath ReadonlyA String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
ses.cookies ReadonlyUm objeto Cookies para esta sessão.
ses.serviceWorkers ReadonlyUm objeto ServiceWorkers para esta sessão.
ses.webRequest ReadonlyUm objeto WebRequest para esta sessão.
ses.protocol ReadonlyUm objeto Protocol para esta sessão.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const protocol = session.fromPartition('some-partition').protocol\n if (!protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })) {\n console.error('Failed to register protocol')\n }\n})\nses.netLog ReadonlyUm objeto NetLog para esta sessão.
const { app, session } = require('electron')\n\napp.whenReady().then(async () => {\n const netLog = session.fromPartition('some-partition').netLog\n netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nDebug symbols allow you to have better debugging sessions. They have information about the functions contained in executables and dynamic libraries and provide you with information to get clean call stacks. A Symbol Server allows the debugger to load the correct symbols, binaries and sources automatically without forcing users to download large debugging files. The server functions like Microsoft's symbol server so the documentation there can be useful.
\nNote that because released Electron builds are heavily optimized, debugging is not always easy. The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations. The only workaround is to build an unoptimized local build.
\nThe official symbol server URL for Electron is https://symbols.electronjs.org. You cannot visit this URL directly, you must add it to the symbol path of your debugging tool. In the examples below, a local cache directory is used to avoid repeatedly fetching the PDB from the server. Replace c:\\code\\symbols with an appropriate cache directory on your machine.
The Windbg symbol path is configured with a string value delimited with asterisk characters. To use only the Electron symbol server, add the following entry to your symbol path (Note: you can replace c:\\code\\symbols with any writable directory on your computer, if you'd prefer a different location for downloaded symbols):
SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\nSet this string as _NT_SYMBOL_PATH in the environment, using the Windbg menus, or by typing the .sympath command. If you would like to get symbols from Microsoft's symbol server as well, you should list that first:
SRV*c:\\code\\symbols\\*https://msdl.microsoft.com/download/symbols;SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\n Options\">
Type the following commands in Windbg to print why symbols are not loading:
\n> !sym noisy\n> .reload /f electron.exe\nThe ShareMenu class creates Share Menu on macOS, which can be used to share information from the current context to apps, social media accounts, and other services.
For including the share menu as a submenu of other menus, please use the shareMenu role of MenuItem.
\n\nCreate share menu on macOS.
\n
Processo: Main
\nnew ShareMenu(sharingItem)sharingItem SharingItem - The item to share.Creates a new share menu.
\nO objeto shareMenu possui os seguintes métodos de instância:
shareMenu.popup([options])options PopupOptions (optional)browserWindow BrowserWindow (optional) - Default is the focused window.x Number (optional) - Default is the current mouse cursor position. Must be declared if y is declared.y Number (optional) - Default is the current mouse cursor position. Must be declared if x is declared.positioningItem Number (optional) macOS - The index of the menu item to be positioned under the mouse cursor at the specified coordinates. Default is -1.callback Function (optional) - Called when menu is closed.Pops up this menu as a context menu in the BrowserWindow.
shareMenu.closePopup([browserWindow])browserWindow BrowserWindow (optional) - Default is the focused window.Fecha o menu de contexto em browserWindow.
id String - The unique id of the shared worker.url String - The url of the shared worker.texts String - An array of text to share.filePaths String - An array of files to share.urls String - An array of URLs to share.\n\nGerencia arquivos e URLs usando seus aplicativos padrão.
\n
Process: Main, Renderer (non-sandboxed only)
\nO módulo shell fornece funções relacionadas à integração com a área de trabalho.
Um exemplo de como abrir uma URL no navegador padrão do usuário:
\nconst { shell } = require('electron')\n\nshell.openExternal('https://github.com')\nNote: While the shell module can be used in the renderer process, it will not function in a sandboxed renderer.
O módulo shell tem os seguintes métodos:
shell.showItemInFolder(fullPath)fullPath StringShow the given file in a file manager. If possible, select the file.
\nshell.openPath(path)path StringReturns Promise<String> - Resolves with a string containing the error message corresponding to the failure if a failure occurred, otherwise \"\".
Abre o arquivo fornecido na maneira padrão da área de trabalho.
\nshell.openExternal(url[, options])url String - Max 2081 characters on windows.options (opcional)activate Boolean (optional) macOS - true to bring the opened application to the foreground. O padrão é verdadeiro.workingDirectory String (optional) Windows - The working directory.Retorna Promise<void>
Open the given external protocol URL in the desktop's default manner. (For example, mailto: URLs in the user's default mail agent).
\nshell.trashItem(path)path String - path to the item to be moved to the trash.Returns Promise<void> - Resolves when the operation has been completed. Rejects if there was an error while deleting the requested item.
This moves a path to the OS-specific trash location (Trash on macOS, Recycle Bin on Windows, and a desktop-environment-specific location on Linux).
\nshell.beep()Toca o sinal sonoro.
\nshell.writeShortcutLink(shortcutPath[, operation], options) WindowsshortcutPath Stringoperation String (optional) - Default is create, can be one of following:create - Cria um novo atalho, sobrescrevendo se necessário.update - Atualiza propriedades especificadas apenas em um atalho existente.replace - Sobrescreve um atalho existente, falha se o atalho não existir.options ShortcutDetailsReturns Boolean - Whether the shortcut was created successfully.
Creates or updates a shortcut link at shortcutPath.
shell.readShortcutLink(shortcutPath) WindowsshortcutPath StringRetorna ShortcutDetails
Resolves the shortcut link at shortcutPath.
Uma exceção será lançada quando qualquer erro acontecer.
", "title": "shell", "description": "Gerencia arquivos e URLs usando seus aplicativos padrão." }, "/docs/api/structures/shortcut-details": { "locale": "pt-BR", "slug": "shortcut-details", "href": "/docs/api/structures/shortcut-details", "crowdinFileId": "256509", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/shortcut-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "target String - The target to launch from this shortcut.cwd String (optional) - The working directory. Default is empty.args String (optional) - The arguments to be applied to target when launching from this shortcut. Default is empty.description String (optional) - The description of the shortcut. Default is empty.icon String (optional) - The path to the icon, can be a DLL or EXE. icon and iconIndex have to be set together. Default is empty, which uses the target's icon.iconIndex Number (optional) - The resource ID of icon when icon is a DLL or EXE. Default is 0.appUserModelId String (optional) - The Application User Model ID. Default is empty.toastActivatorClsid String (optional) - The Application Toast Activator CLSID. Needed for participating in Action Center.width Numberheight NumberThis guide provides information on how to package your Electron application for any Snapcraft environment, including the Ubuntu Software Center.
\nTogether with the broader Linux community, Canonical aims to fix many of the common software installation problems with the snapcraft project. Snaps are containerized software packages that include required dependencies, auto-update, and work on all major Linux distributions without system modification.
There are three ways to create a .snap file:
1) Using electron-forge or electron-builder, both tools that come with snap support out of the box. This is the easiest option. 2) Using electron-installer-snap, which takes electron-packager's output. 3) Using an already created .deb package.
Em alguns casos, você precisará ter a ferramenta snapcraft instalada. Instruções para instalar snapcraft para sua distribuição específica estão disponíveis aqui.
electron-installer-snapO módulo funciona como o electron_winstallere módulos semelhantes em que seu escopo é limitado a construir pacotes snap. Você pode testá-lo com:
npm install --save-dev electron-installer-snap\nPackage the application using electron-packager (or a similar tool). Make sure to remove node_modules that you don't need in your final application, since any module you don't actually need will increase your application's size.
A saída deve ser algo mais ou menos assim:
\n.\n└── dist\n └── app-linux-x64\n ├── LICENSE\n ├── LICENSES.chromium.html\n ├── content_shell.pak\n ├── app\n ├── icudtl.dat\n ├── libgcrypt.so.11\n ├── libnode.so\n ├── locales\n ├── resources\n ├── v8_context_snapshot.bin\n └── version\nelectron-installer-snapFrom a terminal that has snapcraft in its PATH, run electron-installer-snap with the only required parameter --src, which is the location of your packaged Electron application created in the first step.
npx electron-installer-snap --src=out/myappname-linux-x64\nIf you have an existing build pipeline, you can use electron-installer-snap programmatically. For more information, see the Snapcraft API docs.
const snap = require('electron-installer-snap')\n\nsnap(options)\n .then(snapPath => console.log(`Created snap at ${snapPath}!`))\nsnapcraft with electron-packagerCreate your project directory and add the following to snap/snapcraft.yaml:
name: electron-packager-hello-world\nversion: '0.1'\nsummary: Hello World Electron app\ndescription: |\n Simple Hello World Electron app as an example\nbase: core18\nconfinement: strict\ngrade: stable\n\napps:\n electron-packager-hello-world:\n command: electron-quick-start/electron-quick-start --no-sandbox\n extensions: [gnome-3-34]\n plugs:\n - browser-support\n - network\n - network-bind\n environment:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n TMPDIR: $XDG_RUNTIME_DIR\n\nparts:\n electron-quick-start:\n plugin: nil\n source: https://github.com/electron/electron-quick-start.git\n override-build: |\n npm install electron electron-packager\n npx electron-packager . --overwrite --platform=linux --output=release-build --prune=true\n cp -rv ./electron-quick-start-linux-* $SNAPCRAFT_PART_INSTALL/electron-quick-start\n build-snaps:\n - node/14/stable\n build-packages:\n - unzip\n stage-packages:\n - libnss3\n - libnspr4\nIf you want to apply this example to an existing project:
\nsource: https://github.com/electron/electron-quick-start.git with source: ..electron-quick-start with your project's name.$ snapcraft\n\n<output snipped>\nSnapped electron-packager-hello-world_0.1_amd64.snap\nsudo snap install electron-packager-hello-world_0.1_amd64.snap --dangerous\nelectron-packager-hello-world\nSnapcraft is capable of taking an existing .deb file and turning it into a .snap file. The creation of a snap is configured using a snapcraft.yaml file that describes the sources, dependencies, description, and other core building blocks.
If you do not already have a .deb package, using electron-installer-snap might be an easier path to create snap packages. However, multiple solutions for creating Debian packages exist, including electron-forge, electron-builder or electron-installer-debian.
For more information on the available configuration options, see the documentation on the snapcraft syntax. Let's look at an example:
\nname: myApp\nversion: '2.0.0'\nsummary: A little description for the app.\ndescription: |\n You know what? This app is amazing! It does all the things\n for you. Some say it keeps you young, maybe even happy.\n\ngrade: stable\nconfinement: classic\n\nparts:\n slack:\n plugin: dump\n source: my-deb.deb\n source-type: deb\n after:\n - desktop-gtk3\n stage-packages:\n - libasound2\n - libnotify4\n - libnspr4\n - libnss3\n - libpcre3\n - libpulse0\n - libxss1\n - libxtst6\n electron-launch:\n plugin: dump\n source: files/\n prepare: |\n chmod +x bin/electron-launch\n\napps:\n myApp:\n command: bin/electron-launch $SNAP/usr/lib/myApp/myApp\n desktop: usr/share/applications/myApp.desktop\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n environment:\n TMPDIR: $XDG_RUNTIME_DIR\nAs you can see, the snapcraft.yaml instructs the system to launch a file called electron-launch. In this example, it passes information on to the app's binary:
\nexec \"$@\" --executed-from=\"$(pwd)\" --pid=$$ > /dev/null 2>&1 &\nAlternatively, if you're building your snap with strict confinement, you can use the desktop-launch command:
apps:\n myApp:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n command: env TMPDIR=$XDG_RUNTIME_DIR PATH=/usr/local/bin:${PATH} ${SNAP}/bin/desktop-launch $SNAP/myApp/desktop\n desktop: usr/share/applications/desktop.desktop\nThe source code of Electron is separated into a few parts, mostly following Chromium on the separation conventions.
\nYou may need to become familiar with Chromium's multi-process architecture to understand the source code better.
\nElectron\n├── build/ - Build configuration files needed to build with GN.\n├── buildflags/ - Determines the set of features that can be conditionally built.\n├── chromium_src/ - Source code copied from Chromium that isn't part of the content layer.\n├── default_app/ - A default app run when Electron is started without\n| providing a consumer app.\n├── docs/ - Electron's documentation.\n| ├── api/ - Documentation for Electron's externally-facing modules and APIs.\n| ├── development/ - Documentation to aid in developing for and with Electron.\n| ├── fiddles/ - A set of code snippets one can run in Electron Fiddle.\n| ├── images/ - Images used in documentation.\n| └── tutorial/ - Tutorial documents for various aspects of Electron.\n├── lib/ - JavaScript/TypeScript source code.\n| ├── browser/ - Main process initialization code.\n| | ├── api/ - API implementation for main process modules.\n| | └── remote/ - Code related to the remote module as it is\n| | used in the main process.\n| ├── common/ - Relating to logic needed by both main and renderer processes.\n| | └── api/ - API implementation for modules that can be used in\n| | both the main and renderer processes\n| ├── isolated_renderer/ - Handles creation of isolated renderer processes when\n| | contextIsolation is enabled.\n| ├── renderer/ - Renderer process initialization code.\n| | ├── api/ - API implementation for renderer process modules.\n| | ├── extension/ - Code related to use of Chrome Extensions\n| | | in Electron's renderer process.\n| | ├── remote/ - Logic that handles use of the remote module in\n| | | the main process.\n| | └── web-view/ - Logic that handles the use of webviews in the\n| | renderer process.\n| ├── sandboxed_renderer/ - Logic that handles creation of sandboxed renderer\n| | | processes.\n| | └── api/ - API implementation for sandboxed renderer processes.\n| └── worker/ - Logic that handles proper functionality of Node.js\n| environments in Web Workers.\n├── patches/ - Patches applied on top of Electron's core dependencies\n| | in order to handle differences between our use cases and\n| | default functionality.\n| ├── boringssl/ - Patches applied to Google's fork of OpenSSL, BoringSSL.\n| ├── chromium/ - Patches applied to Chromium.\n| ├── node/ - Patches applied on top of Node.js.\n| └── v8/ - Patches applied on top of Google's V8 engine.\n├── shell/ - C++ source code.\n| ├── app/ - System entry code.\n| ├── browser/ - The frontend including the main window, UI, and all of the\n| | | main process things. This talks to the renderer to manage web\n| | | pages.\n| | ├── ui/ - Implementation of UI stuff for different platforms.\n| | | ├── cocoa/ - Cocoa specific source code.\n| | | ├── win/ - Windows GUI specific source code.\n| | | └── x/ - X11 specific source code.\n| | ├── api/ - The implementation of the main process APIs.\n| | ├── net/ - Network related code.\n| | ├── mac/ - Mac specific Objective-C source code.\n| | └── resources/ - Icons, platform-dependent files, etc.\n| ├── renderer/ - Code that runs in renderer process.\n| | └── api/ - The implementation of renderer process APIs.\n| └── common/ - Code that used by both the main and renderer processes,\n| | including some utility functions and code to integrate node's\n| | message loop into Chromium's message loop.\n| └── api/ - The implementation of common APIs, and foundations of\n| Electron's built-in modules.\n├── spec/ - Components of Electron's test suite run in the renderer process.\n├── spec-main/ - Components of Electron's test suite run in the main process.\n└── BUILD.gn - Building rules of Electron.\nscript/create-dist.py script when creating a distribution.ninja.script/ - The set of all scripts Electron runs for a variety of purposes.\n├── codesign/ - Fakes codesigning for Electron apps; used for testing.\n├── lib/ - Miscellaneous python utility scripts.\n└── release/ - Scripts run during Electron's release process.\n ├── notes/ - Generates release notes for new Electron versions.\n └── uploaders/ - Uploads various release-related files during release.\nElectron has built-in support for Chromium's spellchecker since Electron 8. On Windows and Linux this is powered by Hunspell dictionaries, and on macOS it makes use of the native spellchecker APIs.
\nFor Electron 9 and higher the spellchecker is enabled by default. For Electron 8 you need to enable it in webPreferences.
const myWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: true\n }\n})\nOn macOS as we use the native APIs there is no way to set the language that the spellchecker uses. By default on macOS the native spellchecker will automatically detect the language being used for you.
\nFor Windows and Linux there are a few Electron APIs you should use to set the languages for the spellchecker.
\n// Sets the spellchecker to check English US and French\nmyWindow.session.setSpellCheckerLanguages(['en-US', 'fr'])\n\n// An array of all available language codes\nconst possibleLanguages = myWindow.session.availableSpellCheckerLanguages\nBy default the spellchecker will enable the language matching the current OS locale.
\nAll the required information to generate a context menu is provided in the context-menu event on each webContents instance. A small example of how to make a context menu with this information is provided below.
const { Menu, MenuItem } = require('electron')\n\nmyWindow.webContents.on('context-menu', (event, params) => {\n const menu = new Menu()\n\n // Add each spelling suggestion\n for (const suggestion of params.dictionarySuggestions) {\n menu.append(new MenuItem({\n label: suggestion,\n click: () => mainWindow.webContents.replaceMisspelling(suggestion)\n }))\n }\n\n // Allow users to add the misspelled word to the dictionary\n if (params.misspelledWord) {\n menu.append(\n new MenuItem({\n label: 'Add to dictionary',\n click: () => mainWindow.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord)\n })\n )\n }\n\n menu.popup()\n})\nAlthough the spellchecker itself does not send any typings, words or user input to Google services the hunspell dictionary files are downloaded from a Google CDN by default. If you want to avoid this you can provide an alternative URL to download the dictionaries from.
\nmyWindow.session.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/')\nCheck out the docs for session.setSpellCheckerDictionaryDownloadURL for more information on where to get the dictionary files from and how you need to host them.
Estas são as diretrizes para escrever a documentação do Electron.
\n# no nível de título na parte superior.##-level headings.# in the heading according to their nesting depth.Usado o Inicio Rápido como exemplo:
# Quick Start\n\n...\n\n## Main process\n\n...\n\n## Renderer process\n\n...\n\n## Run your app\n\n...\n\n### Run as a distribution\n\n...\n\n### Manually downloaded Electron binary\n\n...\nPara referencias à API, existem exceções a está regra.
\nThis repository uses the markdownlint package to enforce consistent Markdown styling. For the exact rules, see the .markdownlint.json file in the root folder.
There are a few style guidelines that aren't covered by the linter rules:
\n\nsh ao invés de cmd nos blocos de código (devido ao destaque de sintaxe).js and javascript code blocks are linted with standard-markdown.The following rules only apply to the documentation of APIs.
\nEach module's API doc must use the actual object name returned by require('electron') as its title (such as BrowserWindow, autoUpdater, and session).
Directly under the page title, add a one-line description of the module as a markdown quote (beginning with >).
Using the session module as an example:
# session\n\n> Manage browser sessions, cookies, cache, proxy settings, etc.\nFor modules that are not classes, their methods and events must be listed under the ## Methods and ## Events chapters.
Using autoUpdater as an example:
# autoUpdater\n\n## Events\n\n### Event: 'error'\n\n## Methods\n\n### `autoUpdater.setFeedURL(url[, requestHeaders])`\n## Class: TheClassName chapter.###-level headings.### Static Methods chapter.### Instance Methods chapter.[TYPE] - [Return description]\"Object, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.### Eventos de Instancia.### Instance Properties chapter.Usando as classes Session e Cookies como exemplo:
# session\n\n## Métodos\n\n### session.fromPartition(partition)\n\n## Propriedades Estáticas\n\n### session.defaultSession\n\n## Classe: Session\n\n### Eventos de Instância\n\n#### Event: 'will-download'\n\n### Métodos de Instância\n\n#### `ses.getCacheSize()`\n\n### Propriedades de Instância\n\n#### `ses.cookies`\n\n## Classe: Cookies\n\n### Métodos de Instância\n\n#### `cookies.get(filter, callback)`\nO capítulo de métodos deve estar no seguinte formato:
\n### `objectName.methodName(required[, optional]))`\n\n* `required` String - A parameter description.\n* `optional` Integer (optional) - Another parameter description.\n\n...\nThe heading can be ### or ####-levels depending on whether the method belongs to a module or a class.
For modules, the objectName is the module's name. For classes, it must be the name of the instance of the class, and must not be the same as the module's name.
Por exemplo, os métodos da classe Session sob o módulo session usa ses como objectName.
Optional arguments are notated by square brackets [] surrounding the optional argument as well as the comma required if this optional argument follows another argument:
obrigatório[, opcional]\nMore detailed information on each of the arguments is noted in an unordered list below the method. The type of argument is notated by either JavaScript primitives (e.g. String, Promise, or Object), a custom API structure like Electron's Cookie, or the wildcard any.
If the argument is of type Array, use [] shorthand with the type of value inside the array (for example,any[] or String[]).
If the argument is of type Promise, parametrize the type with what the promise resolves to (for example, Promise<void> or Promise<String>).
If an argument can be of multiple types, separate the types with |.
The description for Function type arguments should make it clear how it may be called and list the types of the parameters that will be passed to it.
Se um argumento ou um método for exclusivo para determinadas plataformas, essas plataformas são denotadas usando uma lista itálica delimitada pelo espaço seguindo o tipo de dados. Os valores podem ser macOS, Windows ou Linux.
* 'animar' Boolean (opcional) _macOS_ _Windows_ - Animar a coisa.\nO capítulo de eventos deve estar na seguinte forma:
\n### Evento: 'wake-up'\n\nRetorno:\n\n* `time` String\n\n...\nThe heading can be ### or ####-levels depending on whether the event belongs to a module or a class.
Os argumentos de um evento seguem as mesmas regras e métodos.
\nO capítulo de propriedades deve estar no seguinte formulário:
\n### session.defaultsession\n\n...\nThe heading can be ### or ####-levels depending on whether the property belongs to a module or a class.
Veja electron/i18n
", "title": "Guia de estilo de Documentação do Electron", "description": "" }, "/docs/tutorial/support": { "locale": "pt-BR", "slug": "support", "href": "/docs/tutorial/support", "crowdinFileId": "256253", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/support.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "If you have a security concern, please see the security document.
\nIf you're looking for programming help, for answers to questions, or to join in discussion with other developers who use Electron, you can interact with the community in these locations:
\nElectron's Discord has channels for:electron category on the Atom forums#electron channel on Atom's Slackelectron-ru (Russian)electron-br (Brazilian Portuguese)electron-kr (Korean)electron-jp (Japanese)electron-tr (Turkish)electron-id (Indonesia)electron-pl (Poland)If you'd like to contribute to Electron, see the contributing document.
\nIf you've found a bug in a supported version of Electron, please report it with the issue tracker.
\nawesome-electron is a community-maintained list of useful example apps, tools and resources.
\nNote: Beginning in September 2021 with Electron 15, the Electron team will temporarily support the latest four stable major versions. This extended support is intended to help Electron developers transition to the new eight week release cadence, and will continue until May 2022, with the release of Electron 19. At that time, the Electron team will drop support back to the latest three stable major versions.
\nThe latest three stable major versions are supported by the Electron team. For example, if the latest release is 6.1.x, then the 5.0.x as well as the 4.2.x series are supported. We only support the latest minor release for each stable release series. This means that in the case of a security fix 6.1.x will receive the fix, but we will not release a new version of 6.0.x.
\nThe latest stable release unilaterally receives all fixes from main, and the version prior to that receives the vast majority of those fixes as time and bandwidth warrants. The oldest supported release line will receive only security fixes directly.
All supported release lines will accept external pull requests to backport fixes previously merged to main, though this may be on a case-by-case basis for some older supported lines. All contested decisions around release line backports will be resolved by the Releases Working Group as an agenda item at their weekly meeting the week the backport PR is raised.
When an API is changed or removed in a way that breaks existing functionality, the previous functionality will be supported for a minimum of two major versions when possible before being removed. For example, if a function takes three arguments, and that number is reduced to two in major version 10, the three-argument version would continue to work until, at minimum, major version 12. Past the minimum two-version threshold, we will attempt to support backwards compatibility beyond two versions until the maintainers feel the maintenance burden is too high to continue doing so.
\nWhen a release branch reaches the end of its support cycle, the series will be deprecated in NPM and a final end-of-support release will be made. This release will add a warning to inform that an unsupported version of Electron is in use.
\nThese steps are to help app developers learn when a branch they're using becomes unsupported, but without being excessively intrusive to end users.
\nIf an application has exceptional circumstances and needs to stay on an unsupported series of Electron, developers can silence the end-of-support warning by omitting the final release from the app's package.json devDependencies. For example, since the 1-6-x series ended with an end-of-support 1.6.18 release, developers could choose to stay in the 1-6-x series without warnings with devDependency of \"electron\": 1.6.0 - 1.6.17.
Seguintes plataformas são suportadas pelo Electron:
\nOnly 64bit binaries are provided for macOS, and the minimum macOS version supported is macOS 10.11 (El Capitan).
\nNative support for Apple Silicon (arm64) devices was added in Electron 11.0.0.
Windows 7 e versões posteriores têm suporte, sistemas operacionais mais antigos não são suportados (e não funcionam).
\nBoth ia32 (x86) and x64 (amd64) binaries are provided for Windows. Native support for Windows on Arm (arm64) devices was added in Electron 6.0.8.. Running apps packaged with previous versions is possible using the ia32 binary.
The prebuilt binaries of Electron are built on Ubuntu 18.04.
\nWhether the prebuilt binary can run on a distribution depends on whether the distribution includes the libraries that Electron is linked to on the building platform, so only Ubuntu 18.04 is guaranteed to work, but following platforms are also verified to be able to run the prebuilt binaries of Electron:
\n\n\nComo usar APIs Node.js e Electron.
\n
All of Node.js's built-in modules are available in Electron and third-party node modules also fully supported as well (including the native modules).
\nO Electron também fornece alguns módulos extras para o desenvolvimento de aplicativos desktop. Some modules are only available in the main process, some are only available in the renderer process (web page), and some can be used in either process type.
\nA regra básica é: se um módulo for GUI ou relacionado ao sistema de baixo nível, então deve estar disponível apenas no processo principal. You need to be familiar with the concept of main process vs. renderer process scripts to be able to use those modules.
\nThe main process script is like a normal Node.js script:
\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL('https://github.com')\n})\nThe renderer process is no different than a normal web page, except for the extra ability to use node modules if nodeIntegration is enabled:
\n<html>\n<body>\n<script>\n const fs = require('fs')\n console.log(fs.readFileSync(__filename, 'utf8'))\n</script>\n</body>\n</html>\nA partir de 0,37, você pode usar tarefa de desestruturação para facilitar a utilização módulos internos.
\nconst { app, BrowserWindow } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nSe você precisar de todo o módulo electron, você pode exigi-lo e depois usar desestruturação para acessar os módulos individuais do electron.
const electron = require('electron')\nconst { app, BrowserWindow } = electron\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nIsto equivale ao seguinte código:
\nconst electron = require('electron')\nconst app = electron.app\nconst BrowserWindow = electron.BrowserWindow\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\n\n\nObtenha preferências do sistema.
\n
Processo: Main
\nconst { systemPreferences } = require('electron')\nconsole.log(systemPreferences.isDarkMode())\nO objeto systemPreferences emite os seguintes eventos:
Retorna:
\nevent EventnewColor String - The new RGBA color the user assigned to be their system accent color.Retorna:
\nevent EventRetorna:
\nevent EventinvertedColorScheme Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is being used, false otherwise.Deprecated: Should use the new updated event on the nativeTheme module.
Retorna:
\nevent EventhighContrastColorScheme Boolean - true if a high contrast theme is being used, false otherwise.Deprecated: Should use the new updated event on the nativeTheme module.
systemPreferences.isDarkMode() macOS Windows DeprecatedReturns Boolean - Whether the system is in Dark Mode.
Deprecated: Should use the new nativeTheme.shouldUseDarkColors API.
systemPreferences.isSwipeTrackingFromScrollEventsEnabled() no macOSReturns Boolean - Whether the Swipe between pages setting is on.
systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOSevent StringuserInfo Record<String, any>deliverImmediately Boolean (optional) - true to post notifications immediately even when the subscribing app is inactive.Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postLocalNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postWorkspaceNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.subscribeNotification(event, callback) no macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object StringReturns Number - The ID of this subscription
Subscribes to native notifications of macOS, callback will be called with callback(event, userInfo) when the corresponding event happens. The userInfo is an Object that contains the user information dictionary sent along with the notification. The object is the sender of the notification, and only supports NSString values for now.
The id of the subscriber is returned, which can be used to unsubscribe the event.
Under the hood this API subscribes to NSDistributedNotificationCenter, example values of event are:
AppleInterfaceThemeChangedNotificationAppleAquaColorVariantChangedAppleColorPreferencesChangedNotificationAppleShowScrollBarsSettingChangedsystemPreferences.subscribeLocalNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object StringReturns Number - The ID of this subscription
Same as subscribeNotification, but uses NSNotificationCenter for local defaults. This is necessary for events such as NSUserDefaultsDidChangeNotification.
systemPreferences.subscribeWorkspaceNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object StringReturns Number - The ID of this subscription
Same as subscribeNotification, but uses NSWorkspace.sharedWorkspace.notificationCenter. This is necessary for events such as NSWorkspaceDidActivateApplicationNotification.
systemPreferences.unsubscribeNotification(id) macOSid InteiroRemoves the subscriber with id.
systemPreferences.unsubscribeLocalNotification(id) macOSid InteiroSame as unsubscribeNotification, but removes the subscriber from NSNotificationCenter.
systemPreferences.unsubscribeWorkspaceNotification(id) macOSid InteiroSame as unsubscribeNotification, but removes the subscriber from NSWorkspace.sharedWorkspace.notificationCenter.
systemPreferences.registerDefaults(defaults) no macOSdefaults Record<String, String | Boolean | Number> - a dictionary of (key: value) user defaultsAdd the specified defaults to your application's NSUserDefaults.
systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOSkey Stringtype Type - Can be string, boolean, integer, float, double, url, array or dictionary.Returns UserDefaultTypes[Type] - The value of key in NSUserDefaults.
Some popular key and types are:
AppleInterfaceStyle: stringAppleAquaColorVariant: integerAppleHighlightColor: stringAppleShowScrollBars: stringNSNavRecentPlaces: arrayNSPreferredWebServices: dictionaryNSUserDictionaryReplacementItems: arraysystemPreferences.setUserDefault(key, type, value) macOSkey Stringtype String - Can be string, boolean, integer, float, double, url, array or dictionary.value StringSet the value of key in NSUserDefaults.
Note that type should match actual type of value. An exception is thrown if they don't.
Some popular key and types are:
ApplePressAndHoldEnabled: booleansystemPreferences.removeUserDefault(key) no macOSkey StringRemoves the key in NSUserDefaults. This can be used to restore the default or global value of a key previously set with setUserDefault.
systemPreferences.isAeroGlassEnabled() WindowsReturns Boolean - true if DWM composition (Aero Glass) is enabled, and false otherwise.
An example of using it to determine if you should create a transparent window or not (transparent windows won't work correctly when DWM composition is disabled):
\nconst { BrowserWindow, systemPreferences } = require('electron')\nconst browserOptions = { width: 1000, height: 800 }\n\n// Make the window transparent only if the platform supports it.\nif (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {\n browserOptions.transparent = true\n browserOptions.frame = false\n}\n\n// Create the window.\nconst win = new BrowserWindow(browserOptions)\n\n// Navigate.\nif (browserOptions.transparent) {\n win.loadURL(`file://${__dirname}/index.html`)\n} else {\n // No transparency, so we load a fallback that uses basic styles.\n win.loadURL(`file://${__dirname}/fallback.html`)\n}\nsystemPreferences.getAccentColor() Windows macOSReturns String - The users current system wide accent color preference in RGBA hexadecimal form.
const color = systemPreferences.getAccentColor() // `\"aabbccdd\"`\nconst red = color.substr(0, 2) // \"aa\"\nconst green = color.substr(2, 2) // \"bb\"\nconst blue = color.substr(4, 2) // \"cc\"\nconst alpha = color.substr(6, 2) // \"dd\"\nThis API is only available on macOS 10.14 Mojave or newer.
\nsystemPreferences.getColor(color) Windows macOScolor String - One of the following values:3d-dark-shadow - Dark shadow for three-dimensional display elements.3d-face - Face color for three-dimensional display elements and for dialog box backgrounds.3d-highlight - Highlight color for three-dimensional display elements.3d-light - Light color for three-dimensional display elements.3d-shadow - Shadow color for three-dimensional display elements.active-border - Active window border.active-caption - Active window title bar. Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.active-caption-gradient - Right side color in the color gradient of an active window's title bar.app-workspace - Background color of multiple document interface (MDI) applications.button-text - Text on push buttons.caption-text - Text in caption, size box, and scroll bar arrow box.desktop - Desktop background color.disabled-text - Grayed (disabled) text.highlight - Item(s) selected in a control.highlight-text - Text of item(s) selected in a control.hotlight - Color for a hyperlink or hot-tracked item.inactive-border - Inactive window border.inactive-caption - Inactive window caption. Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.inactive-caption-gradient - Right side color in the color gradient of an inactive window's title bar.inactive-caption-text - Color of text in an inactive caption.info-background - Background color for tooltip controls.info-text - Text color for tooltip controls.menu - Menu background.menu-highlight - The color used to highlight menu items when the menu appears as a flat menu.menubar - The background color for the menu bar when menus appear as flat menus.menu-text - Text in menus.scrollbar - Scroll bar gray area.window - Window background.window-frame - Window frame.window-text - Text in windows.alternate-selected-control-text - The text on a selected surface in a list or table. descontinuadocontrol-background - The background of a large interface element, such as a browser or table.control - The surface of a control.control-text -The text of a control that isn’t disabled.disabled-control-text - The text of a control that’s disabled.find-highlight - The color of a find indicator.grid - The gridlines of an interface element such as a table.header-text - The text of a header cell in a table.highlight - The virtual light source onscreen.keyboard-focus-indicator - The ring that appears around the currently focused control when using the keyboard for interface navigation.label - The text of a label containing primary content.link - A link to other content.placeholder-text - A placeholder string in a control or text view.quaternary-label - The text of a label of lesser importance than a tertiary label such as watermark text.scrubber-textured-background - The background of a scrubber in the Touch Bar.secondary-label - The text of a label of lesser importance than a normal label such as a label used to represent a subheading or additional information.selected-content-background - The background for selected content in a key window or view.selected-control - The surface of a selected control.selected-control-text - The text of a selected control.selected-menu-item-text - The text of a selected menu.selected-text-background - The background of selected text.selected-text - Selected text.separator - A separator between different sections of content.shadow - The virtual shadow cast by a raised object onscreen.tertiary-label - The text of a label of lesser importance than a secondary label such as a label used to represent disabled text.text-background - Text background.text - The text in a document.under-page-background - The background behind a document's content.unemphasized-selected-content-background - The selected content in a non-key window or view.unemphasized-selected-text-background - A background for selected text in a non-key window or view.unemphasized-selected-text - Selected text in a non-key window or view.window-background - The background of a window.window-frame-text - The text in the window's titlebar area.Returns String - The system color setting in RGB hexadecimal form (#ABCDEF). See the Windows docs and the macOS docs for more details.
The following colors are only available on macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, and unemphasized-selected-text.
systemPreferences.getSystemColor(color) no macOScolor String - One of the following values:bluebrowngraygreenorangepinkpurpleredyellowReturns String - The standard system color formatted as #RRGGBBAA.
Returns one of several standard system colors that automatically adapt to vibrancy and changes in accessibility settings like 'Increase contrast' and 'Reduce transparency'. See Apple Documentation for more details.
\nsystemPreferences.isInvertedColorScheme() Windows DeprecatedReturns Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is active, false otherwise.
Deprecated: Should use the new nativeTheme.shouldUseInvertedColorScheme API.
systemPreferences.isHighContrastColorScheme() macOS Windows DeprecatedReturns Boolean - true if a high contrast theme is active, false otherwise.
Deprecated: Should use the new nativeTheme.shouldUseHighContrastColors API.
systemPreferences.getEffectiveAppearance() no macOSReturns String - Can be dark, light or unknown.
Gets the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance
\nsystemPreferences.getAppLevelAppearance() macOS DeprecatedReturns String | null - Can be dark, light or unknown.
Gets the macOS appearance setting that you have declared you want for your application, maps to NSApplication.appearance. You can use the setAppLevelAppearance API to set this value.
systemPreferences.setAppLevelAppearance(appearance) macOS Deprecatedappearance String | null - Can be dark or lightSets the appearance setting for your application, this should override the system default and override the value of getEffectiveAppearance.
systemPreferences.canPromptTouchID() no macOSReturns Boolean - whether or not this device has the ability to use Touch ID.
NOTE: This API will return false on macOS systems older than Sierra 10.12.2.
systemPreferences.promptTouchID(reason) no macOSreason String - The reason you are asking for Touch ID authenticationReturns Promise<void> - resolves if the user has successfully authenticated with Touch ID.
const { systemPreferences } = require('electron')\n\nsystemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {\n console.log('You have successfully authenticated with Touch ID!')\n}).catch(err => {\n console.log(err)\n})\nThis API itself will not protect your user data; rather, it is a mechanism to allow you to do so. Native apps will need to set Access Control Constants like kSecAccessControlUserPresence on their keychain entry so that reading it would auto-prompt for Touch ID biometric consent. This could be done with node-keytar, such that one would store an encryption key with node-keytar and only fetch it if promptTouchID() resolves.
NOTE: This API will return a rejected Promise on macOS systems older than Sierra 10.12.2.
\nsystemPreferences.isTrustedAccessibilityClient(prompt) no macOSprompt Boolean - whether or not the user will be informed via prompt if the current process is untrusted.Returns Boolean - true if the current process is a trusted accessibility client and false if it is not.
systemPreferences.getMediaAccessStatus(mediaType) Windows macOSmediaType String - Can be microphone, camera or screen.Returns String - Can be not-determined, granted, denied, restricted or unknown.
This user consent was not required on macOS 10.13 High Sierra or lower so this method will always return granted. macOS 10.14 Mojave or higher requires consent for microphone and camera access. macOS 10.15 Catalina or higher requires consent for screen access.
Windows 10 has a global setting controlling microphone and camera access for all win32 applications. It will always return granted for screen and for all media types on older versions of Windows.
systemPreferences.askForMediaAccess(mediaType) no macOSmediaType String - the type of media being requested; can be microphone, camera.Returns Promise<Boolean> - A promise that resolves with true if consent was granted and false if it was denied. If an invalid mediaType is passed, the promise will be rejected. If an access request was denied and later is changed through the System Preferences pane, a restart of the app will be required for the new permissions to take effect. If access has already been requested and denied, it must be changed through the preference pane; an alert will not pop up and the promise will resolve with the existing access status.
Important: In order to properly leverage this API, you must set the NSMicrophoneUsageDescription and NSCameraUsageDescription strings in your app's Info.plist file. The values for these keys will be used to populate the permission dialogs so that the user will be properly informed as to the purpose of the permission request. See Electron Application Distribution for more information about how to set these in the context of Electron.
This user consent was not required until macOS 10.14 Mojave, so this method will always return true if your system is running 10.13 High Sierra or lower.
systemPreferences.getAnimationSettings()Retorna Object:
shouldRenderRichAnimation Boolean - Returns true if rich animations should be rendered. Looks at session type (e.g. remote desktop) and accessibility settings to give guidance for heavy animations.scrollAnimationsEnabledBySystem Boolean - Determines on a per-platform basis whether scroll animations (e.g. produced by home/end key) should be enabled.prefersReducedMotion Boolean - Determines whether the user desires reduced motion based on platform APIs.Returns an object with system animation settings.
\nsystemPreferences.appLevelAppearance no macOSA String property that can be dark, light or unknown. It determines the macOS appearance setting for your application. This maps to values in: NSApplication.appearance. Setting this will override the system default as well as the value of getEffectiveAppearance.
Possible values that can be set are dark and light, and possible return values are dark, light, and unknown.
This property is only available on macOS 10.14 Mojave or newer.
\nsystemPreferences.effectiveAppearance macOS ReadonlyA String property that can be dark, light or unknown.
Returns the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance
", "title": "systemPreferences", "description": "Obtenha preferências do sistema." }, "/docs/api/structures/task": { "locale": "pt-BR", "slug": "task", "href": "/docs/api/structures/task", "crowdinFileId": "256513", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/task.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "program String - Path of the program to execute, usually you should specify process.execPath which opens the current program.arguments String - The command line arguments when program is executed.title String - The string to be displayed in a JumpList.description String - Description of this task.iconPath String - The absolute path to an icon to be displayed in a JumpList, which can be an arbitrary resource file that contains an icon. You can usually specify process.execPath to show the icon of the program.iconIndex Number - The icon index in the icon file. If an icon file consists of two or more icons, set this value to identify the icon. If an icon file consists of one icon, this value is 0.workingDirectory String (optional) - The working directory. Default is empty.We aim to keep the code coverage of Electron high. We ask that all pull request not only pass all existing tests, but ideally also add new tests to cover changed code and new scenarios. Ensuring that we capture as many code paths and use cases of Electron as possible ensures that we all ship apps with fewer bugs.
\nThis repository comes with linting rules for both JavaScript and C++ – as well as unit and integration tests. To learn more about Electron's coding style, please see the coding-style document.
\nTo ensure that your JavaScript is in compliance with the Electron coding style, run npm run lint-js, which will run standard against both Electron itself as well as the unit tests. If you are using an editor with a plugin/addon system, you might want to use one of the many StandardJS addons to be informed of coding style violations before you ever commit them.
To run standard with parameters, run npm run lint-js -- followed by arguments you want passed to standard.
To ensure that your C++ is in compliance with the Electron coding style, run npm run lint-cpp, which runs a cpplint script. We recommend that you use clang-format and prepared a short tutorial.
There is not a lot of Python in this repository, but it too is governed by coding style rules. npm run lint-py will check all Python, using pylint to do so.
If you are not using build-tools, ensure that that name you have configured for your local build of Electron is one of Testing, Release, Default, Debug, or you have set process.env.ELECTRON_OUT_DIR. Without these set, Electron will fail to perform some pre-testing steps.
Para executar todos os testes unitários, execute: npm run test. Em uma aplicação Electron os testes podem ser encontrados na pasta spec. Note that it has its own package.json and that its dependencies are therefore not defined in the top-level package.json.
To run only specific tests matching a pattern, run npm run test -- -g=PATTERN, replacing the PATTERN with a regex that matches the tests you would like to run. As an example: If you want to run only IPC tests, you would run npm run test -- -g ipc.
Visual Studio 2019 must be installed.
\nNode headers have to be compiled for your configuration.
\nninja -C out\\Testing third_party\\electron_node:headers\nThe electron.lib has to be copied as node.lib.
\ncd out\\Testing\nmkdir gen\\node_headers\\Release\ncopy electron.lib gen\\node_headers\\Release\\node.lib\nSome Windows 10 devices do not ship with the Meiryo font installed, which may cause a font fallback test to fail. To install Meiryo:
\nSome tests which rely on precise pixel measurements may not work correctly on devices with Hi-DPI screen settings due to floating point precision errors. To run these tests correctly, make sure the device is set to 100% scaling.
\nTo configure display scaling:
\nSendo baseado no Chromium, o Electron necessita de um driver de vídeo para rodar. If Chromium can't find a display driver, Electron will fail to launch - and therefore not executing any of your tests, regardless of how you are running them. Para testar aplicativos com base no Electron em sistemas como Travis, Circle, Jenkins ou similares requer que algumas configurações sejam feitas. Basicamente, precisamos usar um driver de vídeo virtual.
\nPrimeiramente instale o Xvfb. É um framebuffer que implementa o protocolo de servidor de vídeo do X11 - ele realiza todas as operações gráficas na memória sem mostrar nenhuma mensagem, o que é exatamente o que precisamos.
\nThen, create a virtual Xvfb screen and export an environment variable called DISPLAY that points to it. No Electron o Chromium irá procurar automaticamente pela variável $DISPLAY, sendo assim dispensáveis configurações adicionais em seu aplicativo. Esta etapa pode ser automatizada com o pacote xvfb-maybe: Preceda seus comandos de teste com xvfb-maybe e a ferramenta fará a configuração automaticamente do Xvfb, se requerido pelo sistema. On Windows or macOS, it will do nothing.
## On Windows or macOS, this invokes electron-mocha\n## On Linux, if we are in a headless environment, this will be equivalent\n## to xvfb-run electron-mocha ./test/*.js\nxvfb-maybe electron-mocha ./test/*.js\nNo Travis, o seu .travis;yml deverá se parecer basicamente desta forma:
addons:\n apt:\n packages:\n - xvfb\n\ninstall:\n - export DISPLAY=':99.0'\n - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &\nPara o Jenkins, um plugin Xvfb está disponível.
\nCircle CI is awesome and has Xvfb and $DISPLAY already set up, so no further configuration is required.
AppVeyor roda no Windows, tendo suporte para Selenium, Chomium, Electron e ferramentas similares de fora - configuração adicional é dispensada.
", "title": "Testing on Headless CI Systems (Travis CI, Jenkins)", "description": "" }, "/docs/tutorial/testing-widevine-cdm": { "locale": "pt-BR", "slug": "testing-widevine-cdm", "href": "/docs/tutorial/testing-widevine-cdm", "crowdinFileId": "256257", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/testing-widevine-cdm.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "No Electron você pode usar a biblioteca Widevine CDM inclusa no navegador Chrome.
\nWidevine Content Decryption Modules (CDMs) are how streaming services protect content using HTML5 video to web browsers without relying on an NPAPI plugin like Flash or Silverlight. Widevine support is an alternative solution for streaming services that currently rely on Silverlight for playback of DRM-protected video content. It will allow websites to show DRM-protected video content in Firefox without the use of NPAPI plugins. The Widevine CDM runs in an open-source CDM sandbox providing better user security than NPAPI plugins.
\nAs of Electron v1.8.0 (Chrome v59), the below steps are may only be some of the necessary steps to enable Widevine; any app on or after that version intending to use the Widevine CDM may need to be signed using a license obtained from Widevine itself.
Per Widevine:
\n\n\nChrome 59 (and later) includes support for Verified Media Path (VMP). VMP provides a method to verify the authenticity of a device platform. For browser deployments, this will provide an additional signal to determine if a browser-based implementation is reliable and secure.
\nThe proxy integration guide has been updated with information about VMP and how to issue licenses.
\nWidevine recommends our browser-based integrations (vendors and browser-based applications) add support for VMP.
\n
To enable video playback with this new restriction, castLabs has created a fork that has implemented the necessary changes to enable Widevine to be played in an Electron application if one has obtained the necessary licenses from widevine.
\nOpen chrome://components/ in Chrome browser, find Widevine Content Decryption Module and make sure it is up to date, then you can find the library files from the application directory.
The library file widevinecdm.dll will be under Program Files(x86)/Google/Chrome/Application/CHROME_VERSION/WidevineCdm/_platform_specific/win_(x86|x64)/ directory.
The library file libwidevinecdm.dylib will be under /Applications/Google Chrome.app/Contents/Versions/CHROME_VERSION/Google Chrome Framework.framework/Versions/A/Libraries/WidevineCdm/_platform_specific/mac_(x86|x64)/ directory.
Note: Make sure that chrome version used by Electron is greater than or equal to the min_chrome_version value of Chrome's widevine cdm component. The value can be found in manifest.json under WidevineCdm directory.
After getting the library files, you should pass the path to the file with --widevine-cdm-path command line switch, and the library's version with --widevine-cdm-version switch. The command line switches have to be passed before the ready event of app module gets emitted.
Example code:
\nconst { app, BrowserWindow } = require('electron')\n\n// You have to pass the directory that contains widevine library here, it is\n// * `libwidevinecdm.dylib` on macOS,\n// * `widevinecdm.dll` on Windows.\napp.commandLine.appendSwitch('widevine-cdm-path', '/path/to/widevine_library')\n// The version of plugin can be got from `chrome://components` page in Chrome.\napp.commandLine.appendSwitch('widevine-cdm-version', '1.4.8.866')\n\nlet win = null\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.show()\n})\nTo verify whether widevine works, you can use following ways:
\nWidevine.bitdash uses Widevine in your browser, then play the video.icon NativeImage - The icon showing in thumbnail toolbar.click Functiontooltip String (optional) - The text of the button's tooltip.flags String - Control specific states and behaviors of the button. By default, it is ['enabled'].The flags is an array that can include following Strings:
enabled - The button is active and available to the user.disabled - The button is disabled. It is present, but has a visual state indicating it will not respond to user action.dismissonclick - When the button is clicked, the thumbnail window closes immediately.nobackground - Do not draw a button border, use only the image.hidden - The button is not shown to the user.noninteractive - The button is enabled but not interactive; no pressed button state is drawn. This value is intended for instances where the button is used in a notification.\n\nCreate TouchBar layouts for native macOS applications
\n
Processo: Main
\nnew TouchBar(options)options Objectitems (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer)escapeItem (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer | null) (optional)Creates a new touch bar with the specified items. Use BrowserWindow.setTouchBar to add the TouchBar to a window.
Note: The TouchBar API is currently experimental and may change or be removed in future Electron releases.
\nTip: If you don't have a MacBook with Touch Bar, you can use Touch Bar Simulator to test Touch Bar usage in your app.
\nTouchBarButtonA typeof TouchBarButton reference to the TouchBarButton class.
TouchBarColorPickerA typeof TouchBarColorPicker reference to the TouchBarColorPicker class.
TouchBarGroupA typeof TouchBarGroup reference to the TouchBarGroup class.
TouchBarLabelA typeof TouchBarLabel reference to the TouchBarLabel class.
TouchBarPopoverA typeof TouchBarPopover reference to the TouchBarPopover class.
TouchBarScrubberA typeof TouchBarScrubber reference to the TouchBarScrubber class.
TouchBarSegmentedControlA typeof TouchBarSegmentedControl reference to the TouchBarSegmentedControl class.
TouchBarSliderA typeof TouchBarSlider reference to the TouchBarSlider class.
TouchBarSpacerA typeof TouchBarSpacer reference to the TouchBarSpacer class.
TouchBarOtherItemsProxyA typeof TouchBarOtherItemsProxy reference to the TouchBarOtherItemsProxy class.
The following properties are available on instances of TouchBar:
touchBar.escapeItemA TouchBarItem that will replace the \"esc\" button on the touch bar when set. Setting to null restores the default \"esc\" button. Changing this value immediately updates the escape item in the touch bar.
Below is an example of a simple slot machine touch bar game with a button and some labels.
\nconst { app, BrowserWindow, TouchBar } = require('electron')\n\nconst { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar\n\nlet spinning = false\n\n// Reel labels\nconst reel1 = new TouchBarLabel()\nconst reel2 = new TouchBarLabel()\nconst reel3 = new TouchBarLabel()\n\n// Spin result label\nconst result = new TouchBarLabel()\n\n// Spin button\nconst spin = new TouchBarButton({\n label: '🎰 Spin',\n backgroundColor: '#7851A9',\n click: () => {\n // Ignore clicks if already spinning\n if (spinning) {\n return\n }\n\n spinning = true\n result.label = ''\n\n let timeout = 10\n const spinLength = 4 * 1000 // 4 seconds\n const startTime = Date.now()\n\n const spinReels = () => {\n updateReels()\n\n if ((Date.now() - startTime) >= spinLength) {\n finishSpin()\n } else {\n // Slow down a bit on each spin\n timeout *= 1.1\n setTimeout(spinReels, timeout)\n }\n }\n\n spinReels()\n }\n})\n\nconst getRandomValue = () => {\n const values = ['🍒', '💎', '7️⃣', '🍊', '🔔', '⭐', '🍇', '🍀']\n return values[Math.floor(Math.random() * values.length)]\n}\n\nconst updateReels = () => {\n reel1.label = getRandomValue()\n reel2.label = getRandomValue()\n reel3.label = getRandomValue()\n}\n\nconst finishSpin = () => {\n const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size\n if (uniqueValues === 1) {\n // All 3 values are the same\n result.label = '💰 Jackpot!'\n result.textColor = '#FDFF00'\n } else if (uniqueValues === 2) {\n // 2 values are the same\n result.label = '😍 Winner!'\n result.textColor = '#FDFF00'\n } else {\n // No values are the same\n result.label = '🙁 Spin Again'\n result.textColor = null\n }\n spinning = false\n}\n\nconst touchBar = new TouchBar({\n items: [\n spin,\n new TouchBarSpacer({ size: 'large' }),\n reel1,\n new TouchBarSpacer({ size: 'small' }),\n reel2,\n new TouchBarSpacer({ size: 'small' }),\n reel3,\n new TouchBarSpacer({ size: 'large' }),\n result\n ]\n})\n\nlet window\n\napp.whenReady().then(() => {\n window = new BrowserWindow({\n frame: false,\n titleBarStyle: 'hiddenInset',\n width: 200,\n height: 200,\n backgroundColor: '#000'\n })\n window.loadURL('about:blank')\n window.setTouchBar(touchBar)\n})\nTo run the example above, you'll need to (assuming you've got a terminal open in the directory you want to run the example):
\ntouchbar.jsnpm install electron./node_modules/.bin/electron touchbar.jsYou should then see a new Electron window and the app running in your touch bar (or touch bar emulator).
", "title": "TouchBar", "description": "Create TouchBar layouts for native macOS applications" }, "/docs/api/touch-bar-button": { "locale": "pt-BR", "slug": "touch-bar-button", "href": "/docs/api/touch-bar-button", "crowdinFileId": "256375", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/touch-bar-button.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCreate a button in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarButton(options)options Objectlabel String (optional) - Button text.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.backgroundColor String (optional) - Button background color in hex format, i.e #ABCDEF.icon NativeImage | String (optional) - Button icon.iconPosition String (optional) - Can be left, right or overlay. O padrão é overlay.click Function (optional) - Function to call when the button is clicked.enabled Boolean (optional) - Whether the button is in an enabled state. Por padrão é true.When defining accessibilityLabel, ensure you have considered macOS best practices.
As seguintes propriedades estão disponíveis em instâncias de TouchBarButton:
touchBarButton.accessibilityLabelA String representing the description of the button to be read by a screen reader. Will only be read by screen readers if no label is set.
touchBarButton.labelA String representing the button's current text. Changing this value immediately updates the button in the touch bar.
touchBarButton.backgroundColorA String hex code representing the button's current background color. Changing this value immediately updates the button in the touch bar.
touchBarButton.iconA NativeImage representing the button's current icon. Changing this value immediately updates the button in the touch bar.
touchBarButton.iconPositionA String - Can be left, right or overlay. O padrão é overlay.
touchBarButton.enabledA Boolean representing whether the button is in an enabled state.
\n\nCreate a color picker in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarColorPicker(options)options ObjectavailableColors String - Array of hex color strings to appear as possible colors to select.selectedColor String (optional) - The selected hex color in the picker, i.e #ABCDEF.change Function (optional) - Function to call when a color is selected.color String - The color that the user selected from the picker.As seguintes propriedades estão disponíveis em instâncias de TouchBarColorPicker:
touchBarColorPicker.availableColorsA String[] array representing the color picker's available colors to select. Changing this value immediately updates the color picker in the touch bar.
touchBarColorPicker.selectedColorA String hex code representing the color picker's currently selected color. Changing this value immediately updates the color picker in the touch bar.
\n\nCreate a group in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarGroup(options)options Objectitems TouchBar - Items to display as a group.\n\nCreate a label in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarLabel(options)options Objectlabel String (optional) - Text to display.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.textColor String (optional) - Hex color of text, i.e #ABCDEF.When defining accessibilityLabel, ensure you have considered macOS best practices.
As seguintes propriedades estão disponíveis em instâncias de TouchBarLabel:
touchBarLabel.labelA String representing the label's current text. Changing this value immediately updates the label in the touch bar.
touchBarLabel.accessibilityLabelA String representing the description of the label to be read by a screen reader.
touchBarLabel.textColorA String hex code representing the label's current text color. Changing this value immediately updates the label in the touch bar.
\n\nInstantiates a special \"other items proxy\", which nests TouchBar elements inherited from Chromium at the space indicated by the proxy. By default, this proxy is added to each TouchBar at the end of the input. For more information, see the AppKit docs on NSTouchBarItemIdentifierOtherItemsProxy
\nNote: Only one instance of this class can be added per TouchBar.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarOtherItemsProxy()\n\nCreate a popover in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarPopover(options)options Objectlabel String (optional) - Popover button text.icon NativeImage (optional) - Popover button icon.items TouchBar - Items to display in the popover.showCloseButton Boolean (optional) - true to display a close button on the left of the popover, false to not show it. Por padrão é true.As seguintes propriedades estão disponíveis em instâncias de TouchBarPopover:
touchBarPopover.labelA String representing the popover's current button text. Changing this value immediately updates the popover in the touch bar.
touchBarPopover.iconA NativeImage representing the popover's current button icon. Changing this value immediately updates the popover in the touch bar.
\n\nCreate a scrubber (a scrollable selector)
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarScrubber(options)options Objectitems ScrubberItem[] - An array of items to place in this scrubber.select Function (optional) - Called when the user taps an item that was not the last tapped item.selectedIndex Integer - The index of the item the user selected.highlight Function (optional) - Called when the user taps any item.highlightedIndex Integer - The index of the item the user touched.selectedStyle String (optional) - Selected item style. Can be background, outline or none. O padrão é none.overlayStyle String (optional) - Selected overlay item style. Can be background, outline or none. O padrão é none.showArrowButtons Boolean (optional) - Whether to show arrow buttons. Defaults to false and is only shown if items is non-empty.mode String (optional) - Can be fixed or free. O padrão é free.continuous Boolean (optional) - Defaults to true.As seguintes propriedades estão disponíveis em instâncias de TouchBarScrubber:
touchBarScrubber.itemsA ScrubberItem[] array representing the items in this scrubber. Updating this value immediately updates the control in the touch bar. Updating deep properties inside this array does not update the touch bar.
touchBarScrubber.selectedStyleA String representing the style that selected items in the scrubber should have. Updating this value immediately updates the control in the touch bar. Valores possíveis:
background - Maps to [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Maps to [NSScrubberSelectionStyle outlineOverlayStyle].none - Removes all styles.touchBarScrubber.overlayStyleA String representing the style that selected items in the scrubber should have. This style is overlayed on top of the scrubber item instead of being placed behind it. Updating this value immediately updates the control in the touch bar. Valores possíveis:
background - Maps to [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Maps to [NSScrubberSelectionStyle outlineOverlayStyle].none - Removes all styles.touchBarScrubber.showArrowButtonsA Boolean representing whether to show the left / right selection arrows in this scrubber. Updating this value immediately updates the control in the touch bar.
touchBarScrubber.modeA String representing the mode of this scrubber. Updating this value immediately updates the control in the touch bar. Valores possíveis:
fixed - Maps to NSScrubberModeFixed.free - Maps to NSScrubberModeFree.touchBarScrubber.continuousA Boolean representing whether this scrubber is continuous or not. Updating this value immediately updates the control in the touch bar.
\n\nCreate a segmented control (a button group) where one button has a selected state
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSegmentedControl(options)options ObjectsegmentStyle String (optional) - Style of the segments:automatic - Default. The appearance of the segmented control is automatically determined based on the type of window in which the control is displayed and the position within the window. Maps to NSSegmentStyleAutomatic.rounded - The control is displayed using the rounded style. Maps to NSSegmentStyleRounded.textured-rounded - The control is displayed using the textured rounded style. Maps to NSSegmentStyleTexturedRounded.round-rect - The control is displayed using the round rect style. Maps to NSSegmentStyleRoundRect.textured-square - The control is displayed using the textured square style. Maps to NSSegmentStyleTexturedSquare.capsule - The control is displayed using the capsule style. Maps to NSSegmentStyleCapsule.small-square - The control is displayed using the small square style. Maps to NSSegmentStyleSmallSquare.separated - The segments in the control are displayed very close to each other but not touching. Maps to NSSegmentStyleSeparated.mode String (optional) - The selection mode of the control:single - Default. One item selected at a time, selecting one deselects the previously selected item. Maps to NSSegmentSwitchTrackingSelectOne.multiple - Multiple items can be selected at a time. Maps to NSSegmentSwitchTrackingSelectAny.buttons - Make the segments act as buttons, each segment can be pressed and released but never marked as active. Maps to NSSegmentSwitchTrackingMomentary.segments SegmentedControlSegment[] - An array of segments to place in this control.selectedIndex Integer (optional) - The index of the currently selected segment, will update automatically with user interaction. When the mode is multiple it will be the last selected item.change Function (optional) - Called when the user selects a new segment.selectedIndex Integer - The index of the segment the user selected.isSelected Boolean - Whether as a result of user selection the segment is selected or not.As seguintes propriedades estão disponíveis em instâncias de TouchBarSegmentedControl:
touchBarSegmentedControl.segmentStyleA String representing the controls current segment style. Updating this value immediately updates the control in the touch bar.
touchBarSegmentedControl.segmentsA SegmentedControlSegment[] array representing the segments in this control. Updating this value immediately updates the control in the touch bar. Updating deep properties inside this array does not update the touch bar.
touchBarSegmentedControl.selectedIndexAn Integer representing the currently selected segment. Changing this value immediately updates the control in the touch bar. User interaction with the touch bar will update this value automatically.
touchBarSegmentedControl.modeA String representing the current selection mode of the control. Can be single, multiple or buttons.
\n\nCreate a slider in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSlider(options)options Objectlabel String (optional) - Label text.value Integer (optional) - Selected value.minValue Integer (optional) - Minimum value.maxValue Integer (optional) - Maximum value.change Function (optional) - Function to call when the slider is changed.newValue Number - The value that the user selected on the Slider.As seguintes propriedades estão disponíveis em instâncias de TouchBarSlider:
touchBarSlider.labelA String representing the slider's current text. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.valueA Number representing the slider's current value. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.minValueA Number representing the slider's current minimum value. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.maxValueA Number representing the slider's current maximum value. Changing this value immediately updates the slider in the touch bar.
\n\nCreate a spacer between two items in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSpacer(options)options Objectsize String (optional) - Size of spacer, possible values are:small - Small space between items. Maps to NSTouchBarItemIdentifierFixedSpaceSmall. This is the default.large - Large space between items. Maps to NSTouchBarItemIdentifierFixedSpaceLarge.flexible - Take up all available space. Maps to NSTouchBarItemIdentifierFlexibleSpace.As seguintes propriedades estão disponíveis em instâncias de TouchBarSpacer:
touchBarSpacer.sizeA String representing the size of the spacer. Can be small, large or flexible.
categoryFilter String - A filter to control what category groups should be traced. A filter can have an optional '-' prefix to exclude category groups that contain a matching category. Having both included and excluded category patterns in the same list is not supported. Examples: test_MyTest*, test_MyTest*,test_OtherStuff, -excluded_category1,-excluded_category2.traceOptions String - Controls what kind of tracing is enabled, it is a comma-delimited sequence of the following strings: record-until-full, record-continuously, trace-to-console, enable-sampling, enable-systrace, e.g. 'record-until-full,enable-sampling'. The first 3 options are trace recording modes and hence mutually exclusive. If more than one trace recording modes appear in the traceOptions string, the last one takes precedence. If none of the trace recording modes are specified, recording mode is record-until-full. The trace option will first be reset to the default option (record_mode set to record-until-full, enable_sampling and enable_systrace set to false) before options parsed from traceOptions are applied on it.recording_mode String (optional) - Can be record-until-full, record-continuously, record-as-much-as-possible or trace-to-console. Defaults to record-until-full.trace_buffer_size_in_kb number (optional) - maximum size of the trace recording buffer in kilobytes. Defaults to 100MB.trace_buffer_size_in_events number (optional) - maximum size of the trace recording buffer in events.enable_argument_filter boolean (optional) - if true, filter event data according to a specific list of events that have been manually vetted to not include any PII. See the implementation in Chromium for specifics.included_categories String - a list of tracing categories to include. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.excluded_categories String - a list of tracing categories to exclude. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.included_process_ids number - a list of process IDs to include in the trace. If not specified, trace all processes.histogram_names String - a list of histogram names to report with the trace.memory_dump_config Record<String, any> (optional) - if the disabled-by-default-memory-infra category is enabled, this contains optional additional configuration for data collection. See the Chromium memory-infra docs for more information.An example TraceConfig that roughly matches what Chrome DevTools records:
\n{\n recording_mode: 'record-until-full',\n included_categories: [\n 'devtools.timeline',\n 'disabled-by-default-devtools.timeline',\n 'disabled-by-default-devtools.timeline.frame',\n 'disabled-by-default-devtools.timeline.stack',\n 'v8.execute',\n 'blink.console',\n 'blink.user_timing',\n 'latencyInfo',\n 'disabled-by-default-v8.cpu_profiler',\n 'disabled-by-default-v8.cpu_profiler.hires'\n ],\n excluded_categories: ['*']\n}\ntransactionIdentifier String - A string that uniquely identifies a successful payment transaction.transactionDate String - The date the transaction was added to the App Store’s payment queue.originalTransactionIdentifier String - The identifier of the restored transaction by the App Store.transactionState String - The transaction state, can be purchasing, purchased, failed, restored or deferred.errorCode Integer - The error code if an error occurred while processing the transaction.errorMessage String - The error message if an error occurred while processing the transaction.payment ObjectproductIdentifier String - The identifier of the purchased product.quantity Integer - The quantity purchased.\n\nAdd icons and context menus to the system's notification area.
\n
Processo: Main
\nTray é um EventEmitter.
const { app, Menu, Tray } = require('electron')\n\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n ])\n tray.setToolTip('This is my application.')\n tray.setContextMenu(contextMenu)\n})\nLimitações de plataforma:
\nGtkStatusIcon will be used instead.libappindicator1 to make the tray icon work.click event is ignored.MenuItems to take effect, you have to call setContextMenu again. Como por exemplo:const { app, Menu, Tray } = require('electron')\n\nlet appIcon = null\napp.whenReady().then(() => {\n appIcon = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' }\n ])\n\n // Make a change to the context menu\n contextMenu.items[1].checked = false\n\n // Call this again for Linux because we modified the context menu\n appIcon.setContextMenu(contextMenu)\n})\nICO icons to get best visual effects.If you want to keep exact same behaviors on all platforms, you should not rely on the click event and always attach a context menu to the tray icon.
new Tray(image, [guid])image (NativeImage | String)guid String (optional) Windows - Assigns a GUID to the tray icon. If the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. OS level settings like the position of the tray icon in the system tray will persist even if the path to the executable changes. If the executable is not code-signed then the GUID is permanently associated with the path to the executable. Changing the path to the executable will break the creation of the tray icon and a new GUID must be used. However, it is highly recommended to use the GUID parameter only in conjunction with code-signed executable. If an App defines multiple tray icons then each icon must use a separate GUID.Creates a new tray icon associated with the image.
O módulo Tray emite os seguintes eventos:
Retorna:
\nevent KeyboardEventbounds Rectangle - The bounds of tray icon.position Point - The position of the event.Emitted when the tray icon is clicked.
\nRetorna:
\nevent KeyboardEventbounds Rectangle - The bounds of tray icon.Emitted when the tray icon is right clicked.
\nRetorna:
\nevent KeyboardEventbounds Rectangle - The bounds of tray icon.Emitted when the tray icon is double clicked.
\nEmitted when the tray balloon shows.
\nEmitted when the tray balloon is clicked.
\nEmitted when the tray balloon is closed because of timeout or user manually closes it.
\nEmitted when any dragged items are dropped on the tray icon.
\nRetorna:
\nevent Eventfiles String[] - The paths of the dropped files.Emitted when dragged files are dropped in the tray icon.
\nRetorna:
\nevent Eventtext String - the dropped text string.Emitted when dragged text is dropped in the tray icon.
\nEmitted when a drag operation enters the tray icon.
\nEmitted when a drag operation exits the tray icon.
\nEmitted when a drag operation ends on the tray or ends at another location.
\nRetorna:
\nevent KeyboardEventposition Point - The position of the event.Emitted when the mouse is released from clicking the tray icon.
\nNote: This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.
Retorna:
\nevent KeyboardEventposition Point - The position of the event.Emitted when the mouse clicks the tray icon.
\nRetorna:
\nevent KeyboardEventposition Point - The position of the event.Emitted when the mouse enters the tray icon.
\nRetorna:
\nevent KeyboardEventposition Point - The position of the event.Emitted when the mouse exits the tray icon.
\nRetorna:
\nevent KeyboardEventposition Point - The position of the event.Emitted when the mouse moves in the tray icon.
\nThe Tray class has the following methods:
tray.destroy()Destroys the tray icon immediately.
\ntray.setImage(image)image (NativeImage | String)Sets the image associated with this tray icon.
tray.setPressedImage(image) macOSimage (NativeImage | String)Sets the image associated with this tray icon when pressed on macOS.
tray.setToolTip(toolTip)toolTip StringSets the hover text for this tray icon.
\ntray.setTitle(title[, options]) macOStitle Stringoptions (opcional)fontType String (optional) - The font family variant to display, can be monospaced or monospacedDigit. monospaced is available in macOS 10.15+ and monospacedDigit is available in macOS 10.11+. When left blank, the title uses the default system font.Sets the title displayed next to the tray icon in the status bar (Support ANSI colors).
\ntray.getTitle() macOSReturns String - the title displayed next to the tray icon in the status bar
tray.setIgnoreDoubleClickEvents(ignore) macOSignore BooleanSets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.
\nThis value is set to false by default.
\ntray.getIgnoreDoubleClickEvents() macOSReturns Boolean - Whether double click events will be ignored.
tray.displayBalloon(options) Windowsoptions Objecticon (NativeImage | String) (optional) - Icon to use when iconType is custom.iconType String (optional) - Can be none, info, warning, error or custom. Padrão é custom.title Stringcontent StringlargeIcon Boolean (optional) - The large version of the icon should be used. Por padrão é true. Maps to NIIF_LARGE_ICON.noSound Boolean (optional) - Do not play the associated sound. Por padrão é false. Maps to NIIF_NOSOUND.respectQuietTime Boolean (optional) - Do not display the balloon notification if the current user is in \"quiet time\". Por padrão é false. Maps to NIIF_RESPECT_QUIET_TIME.Displays a tray balloon.
\ntray.removeBalloon() WindowsRemoves a tray balloon.
\ntray.focus() WindowsReturns focus to the taskbar notification area. Notification area icons should use this message when they have completed their UI operation. For example, if the icon displays a shortcut menu, but the user presses ESC to cancel it, use tray.focus() to return focus to the notification area.
tray.popUpContextMenu([menu, position]) macOS Windowsmenu Menu (optional)position Point (optional) - The pop up position.Pops up the context menu of the tray icon. When menu is passed, the menu will be shown instead of the tray icon's context menu.
position está apenas disponível no Windows, sendo (0, 0) por padrão.
tray.closeContextMenu() macOS WindowsCloses an open context menu, as set by tray.setContextMenu().
tray.setContextMenu(menu)menu Menu | nullSets the context menu for this icon.
\ntray.getBounds() macOS WindowsRetorna Rectangle
The bounds of this tray icon as Object.
tray.isDestroyed()Returns Boolean - Whether the tray icon is destroyed.
title: Tray\ndescription: This guide will take you through the process of creating a Tray icon with its own context menu to the system's notification area.\nslug: tray
\nThis guide will take you through the process of creating a Tray icon with its own context menu to the system's notification area.
\nOn MacOS and Ubuntu, the Tray will be located on the top right corner of your screen, adjacent to your battery and wifi icons. On Windows, the Tray will usually be located in the bottom right corner.
\nFirst we must import app, Tray, Menu, nativeImage from electron.
const { app, Tray, Menu, nativeImage } = require('electron')\nNext we will create our Tray. To do this, we will use a NativeImage icon, which can be created through any one of these methods. Note that we wrap our Tray creation code within an app.whenReady as we will need to wait for our electron app to finish initializing.
let tray\n\napp.whenReady().then(() => {\n const icon = nativeImage.createFromPath('path/to/asset.png')\n tray = new Tray(icon)\n\n // note: your contextMenu, Tooltip and Title code will go here!\n})\nÓtimo! Now we can start attaching a context menu to our Tray, like so:
\nconst contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n])\n\ntray.setContextMenu(contextMenu)\nThe code above will create 4 separate radio-type items in the context menu. To read more about constructing native menus, click here.
\nFinally, let's give our tray a tooltip and a title.
\ntray.setToolTip('This is my application')\ntray.setTitle('This is my title')\nAfter you start your electron app, you should see the Tray residing in either the top or bottom right of your screen, depending on your operating system.\nfiddle docs/fiddles/native-ui/tray
Existem várias maneiras de atualizar uma aplicação em Electron. A maneira mais fácil, suportada oficialmente é utilizando o framework embutido Squirrel e o módulo de autoUpdater do Electron.
\nupdate.electronjs.orgThe Electron team maintains update.electronjs.org, a free and open-source webservice that Electron apps can use to self-update. The service is designed for Electron apps that meet the following criteria:
\nA forma mais fácil de usar este serviço é instalando o update-electron-app, um módulo Node.js pre-configurado para ser usado com update.electronjs.org.
\nInstalando o módulo:
\nnpm install update-electron-app\nInvoke the updater from your app's main process file:
\nrequire('update-electron-app')()\nBy default, this module will check for updates at app startup, then every ten minutes. When an update is found, it will automatically be downloaded in the background. When the download completes, a dialog is displayed allowing the user to restart the app.
\nIf you need to customize your configuration, you can pass options to update-electron-app or use the update service directly.
If you're developing a private Electron application, or if you're not publishing releases to GitHub Releases, it may be necessary to run your own update server.
\nDependendo de suas necessidades, você pode escolher um destes:
\nUma vez que implantou em seu servidor de atualização, continue com a importação dos módulos em seu código. The following code might vary for different server software, but it works like described when using Hazel.
\nImportant: Please ensure that the code below will only be executed in your packaged app, and not in development. You can use electron-is-dev to check for the environment.
\nconst { app, autoUpdater, dialog } = require('electron')\nNext, construct the URL of the update server and tell autoUpdater about it:
\nconst server = 'https://your-deployment-url.com'\nconst url = `${server}/update/${process.platform}/${app.getVersion()}`\n\nautoUpdater.setFeedURL({ url })\nAs the final step, check for updates. The example below will check every minute:
\nsetInterval(() => {\n autoUpdater.checkForUpdates()\n}, 60000)\nOnce your application is packaged, it will receive an update for each new GitHub Release that you publish.
\nNow that you've configured the basic update mechanism for your application, you need to ensure that the user will get notified when there's an update. This can be achieved using the autoUpdater API events:
\nautoUpdater.on('update-downloaded', (event, releaseNotes, releaseName) => {\n const dialogOpts = {\n type: 'info',\n buttons: ['Restart', 'Later'],\n title: 'Application Update',\n message: process.platform === 'win32' ? releaseNotes : releaseName,\n detail: 'A new version has been downloaded. Restart the application to apply the updates.'\n }\n\n dialog.showMessageBox(dialogOpts).then((returnValue) => {\n if (returnValue.response === 0) autoUpdater.quitAndInstall()\n })\n})\nAlso make sure that errors are being handled. Here's an example for logging them to stderr:
autoUpdater.on('error', message => {\n console.error('Erro ao atualizar o aplicativo')\n console.error(message)\n})\nBecause the requests made by Auto Update aren't under your direct control, you may find situations that are difficult to handle (such as if the update server is behind authentication). The url field does support files, which means that with some effort, you can sidestep the server-communication aspect of the process. Here's an example of how this could work.
bytes Buffer - Content being sent.file String (optional) - Path of file being uploaded.blobUUID String (optional) - UUID of blob data. Use ses.getBlobData method to retrieve the data.type 'file' - file.filePath String - Path of file to be uploaded.offset Integer - Defaults to 0.length Integer - Number of bytes to read from offset. Defaults to 0.modificationTime Double - Last Modification time in number of seconds since the UNIX epoch.type 'rawData' - rawData.bytes Buffer - Data to be uploaded.string Stringboolean Booleaninteger Numberfloat Numberdouble Numberurlarray Array\\dictionary Record\\<string, unknown>This type is a helper alias, no object will never exist of this type.
", "title": "UserDefaultTypes Object", "description": "" }, "/docs/tutorial/using-native-node-modules": { "locale": "pt-BR", "slug": "using-native-node-modules", "href": "/docs/tutorial/using-native-node-modules", "crowdinFileId": "256263", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-native-node-modules.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Módulos Node,js nativos são suportados pelo Electron, mas, como Electron tem uma interface binária de aplicação (ABI) diferente da interface do Node.js (devido a diferenças como o uso do BoringSSL do Chromium ao invés do OpenSSL), os módulos nativos que você usar precisam ser recompilados para Electron. Otherwise, you will get the following class of error when you try to run your app:
\nError: The module '/path/to/native/module.node'\nwas compiled against a different Node.js version using\nNODE_MODULE_VERSION $XYZ. This version of Node.js requires\nNODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing\nthe module (for instance, using `npm rebuild` or `npm install`).\nThere are several different ways to install native modules:
\nYou can install modules like other Node projects, and then rebuild the modules for Electron with the electron-rebuild package. This module can automatically determine the version of Electron and handle the manual steps of downloading headers and rebuilding native modules for your app. If you are using Electron Forge, this tool is used automatically in both development mode and when making distributables.
Por exemplo, para instalar a ferramenta standalone electron-rebuild e então reconstruir módulos com ela via linha de comando:
npm install --save-dev electron-rebuild\n\n# Every time you run \"npm install\", run this:\n./node_modules/.bin/electron-rebuild\n\n# If you have trouble on Windows, try:\n.\\node_modules\\.bin\\electron-rebuild.cmd\nPara mais informações sobre uso e integração com outras ferramentas como Electron Packager, consulte o README do projeto.
\nnpmDefinindo algumas variáveis de ambiente, você pode usar npm para instalar módulos diretamente.
For example, to install all dependencies for Electron:
\n# Versão do Electron.\nexport npm_config_target=1.2.3\n# The architecture of Electron, see https://electronjs.org/docs/tutorial/support#supported-platforms\n# for supported architectures.\nexport npm_config_arch=x64\nexport npm_config_target_arch=x64\n# Download de headers para Electron.\nexport npm_config_disturl=https://electronjs.org/headers \n# Diga ao node-pre-gyp que estamos copilando para o Electron.\nexport npm_config_runtime=electron \n# Diga ao node-pre-gyp para copilar os módulos do código fonte.\nexport npm_config_build_from_source=true\n# Instale todas as dependências e armazene cache para ~/.electron-gyp.\nHOME=~/.electron-gyp npm install\nIf you are a developer developing a native module and want to test it against Electron, you might want to rebuild the module for Electron manually. You can use node-gyp directly to build for Electron:
cd /path-to-module/\nHOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://electronjs.org/headers\nHOME=~/.electron-gyp changes where to find development headers.--target=1.2.3 is the version of Electron.--dist-url=... specifies where to download the headers.--arch=x64 says the module is built for a 64-bit system.To compile native Node modules against a custom build of Electron that doesn't match a public release, instruct npm to use the version of Node you have bundled with your custom build.
npm rebuild --nodedir=/path/to/src/out/Default/gen/node_headers\nIf you installed a native module and found it was not working, you need to check the following things:
\nelectron-rebuild first.win_delay_load_hook is not set to false in the module's binding.gyp.win_delay_load_hookOn Windows, by default, node-gyp links native modules against node.dll. However, in Electron 4.x and higher, the symbols needed by native modules are exported by electron.exe, and there is no node.dll. In order to load native modules on Windows, node-gyp installs a delay-load hook that triggers when the native module is loaded, and redirects the node.dll reference to use the loading executable instead of looking for node.dll in the library search path (which would turn up nothing). As such, on Electron 4.x and higher, 'win_delay_load_hook': 'true' is required to load native modules.
If you get an error like Module did not self-register, or The specified procedure could not be found, it may mean that the module you're trying to use did not correctly include the delay-load hook. If the module is built with node-gyp, ensure that the win_delay_load_hook variable is set to true in the binding.gyp file, and isn't getting overridden anywhere. If the module is built with another system, you'll need to ensure that you build with a delay-load hook installed in the main .node file. Your link.exe invocation should look like this:
link.exe /OUT:\"foo.node\" \"...\\node.lib\" delayimp.lib /DELAYLOAD:node.exe /DLL\n \"my_addon.obj\" \"win_delay_load_hook.obj\"\nIn particular, it's important that:
\nnode.lib from Electron and not Node. If you link against the wrong node.lib you will get load-time errors when you require the module in Electron./DELAYLOAD:node.exe. If the node.exe link is not delayed, then the delay-load hook won't get a chance to fire and the node symbols won't be correctly resolved.win_delay_load_hook.obj is linked directly into the final DLL. If the hook is set up in a dependent DLL, it won't fire at the right time.See node-gyp for an example delay-load hook if you're implementing your own.
prebuildprebuild provides a way to publish native Node modules with prebuilt binaries for multiple versions of Node and Electron.
If the prebuild-powered module provide binaries for the usage in Electron, make sure to omit --build-from-source and the npm_config_build_from_source environment variable in order to take full advantage of the prebuilt binaries.
node-pre-gypThe node-pre-gyp tool provides a way to deploy native Node modules with prebuilt binaries, and many popular modules are using it.
Sometimes those modules work fine under Electron, but when there are no Electron-specific binaries available, you'll need to build from source. Because of this, it is recommended to use electron-rebuild for these modules.
If you are following the npm way of installing modules, you'll need to pass --build-from-source to npm, or set the npm_config_build_from_source environment variable.
Electron no longer supports the Pepper Flash plugin, as Chrome has removed support.
\nSee Chromium's Flash Roadmap for more details.
", "title": "Pepper Flash Plugin", "description": "" }, "/docs/tutorial/using-selenium-and-webdriver": { "locale": "pt-BR", "slug": "using-selenium-and-webdriver", "href": "/docs/tutorial/using-selenium-and-webdriver", "crowdinFileId": "256267", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-selenium-and-webdriver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "From ChromeDriver - WebDriver for Chrome:
\n\n\nWebDriver 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.
\n
Spectron is the officially supported ChromeDriver testing framework for Electron. It is built on top of WebdriverIO and has helpers to access Electron APIs in your tests and bundles ChromeDriver.
\n$ npm install --save-dev spectron\n// A simple test to verify a visible window is opened with a title\nconst Application = require('spectron').Application\nconst assert = require('assert')\n\nconst myApp = new Application({\n path: '/Applications/MyApp.app/Contents/MacOS/MyApp'\n})\n\nconst verifyWindowIsVisibleWithTitle = async (app) => {\n await app.start()\n try {\n // Check if the window is visible\n const isVisible = await app.browserWindow.isVisible()\n // Verify the window is visible\n assert.strictEqual(isVisible, true)\n // Get the window's title\n const title = await app.client.getTitle()\n // Verify the window's title\n assert.strictEqual(title, 'My App')\n } catch (error) {\n // Log any failures\n console.error('Test failed', error.message)\n }\n // Stop the application\n await app.stop()\n}\n\nverifyWindowIsVisibleWithTitle(myApp)\nWebDriverJs provides a Node package for testing with web driver, we will use it as an example.
\nFirst you need to download the chromedriver binary, and run it:
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver\nComeçando ChromeDriver (v2.10.291558) na porta 9515\nSomente conexão local é permitido.\nRemember the port number 9515, which will be used later
$ npm install selenium-webdriver\nThe usage of selenium-webdriver with Electron is the same with upstream, except that you have to manually specify how to connect chrome driver and where to find Electron's binary:
const webdriver = require('selenium-webdriver')\n\nconst driver = new webdriver.Builder()\n // The \"9515\" is the port opened by chrome driver.\n .usingServer('http://localhost:9515')\n .withCapabilities({\n 'goog:chromeOptions': {\n // Here is the path to your Electron binary.\n binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'\n }\n })\n .forBrowser('chrome') // note: use .forBrowser('electron') for selenium-webdriver <= 3.6.0\n .build()\n\ndriver.get('http://www.google.com')\ndriver.findElement(webdriver.By.name('q')).sendKeys('webdriver')\ndriver.findElement(webdriver.By.name('btnG')).click()\ndriver.wait(() => {\n return driver.getTitle().then((title) => {\n return title === 'webdriver - Google Search'\n })\n}, 1000)\n\ndriver.quit()\nWebdriverIO provides a Node package for testing with web driver.
\nFirst you need to download the chromedriver binary, and run it:
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver --url-base=wd/hub --port=9515\nComeçando ChromeDriver (v2.10.291558) na porta 9515\nSomente conexão local é permitido.\nRemember the port number 9515, which will be used later
$ npm install webdriverio\nconst webdriverio = require('webdriverio')\nconst options = {\n host: 'localhost', // Use localhost as chrome driver server\n port: 9515, // \"9515\" is the port opened by chrome driver.\n desiredCapabilities: {\n browserName: 'chrome',\n 'goog:chromeOptions': {\n binary: '/Path-to-Your-App/electron', // Path to your Electron binary.\n args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/\n }\n }\n}\n\nconst client = webdriverio.remote(options)\n\nclient\n .init()\n .url('http://google.com')\n .setValue('#q', 'webdriverio')\n .click('#btnG')\n .getTitle().then((title) => {\n console.log('Title was: ' + title)\n })\n .end()\nTo test your application without rebuilding Electron, place your app source into Electron's resource directory.
\nAlternatively, 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.
", "title": "Selenium and WebDriver", "description": "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." }, "/docs/development/v8-development": { "locale": "pt-BR", "slug": "v8-development", "href": "/docs/development/v8-development", "crowdinFileId": "256171", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/v8-development.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "\n\nUma coleção de recursos para aprender e usar o V8
\n
--prof, --trace-ic, --trace-opt, --trace-deopt, --print-bytecode, --print-opt-codeVeja também Chromium Desenvolvimento
", "title": "V8 Desenvolvimento", "description": "Uma coleção de recursos para aprender e usar o V8" }, "/docs/api/web-contents": { "locale": "pt-BR", "slug": "web-contents", "href": "/docs/api/web-contents", "crowdinFileId": "256399", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-contents.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRender and control web pages.
\n
Processo: Main
\nwebContents é um EventEmitter. It is responsible for rendering and controlling a web page and is a property of the BrowserWindow object. An example of accessing the webContents object:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('http://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\nThese methods can be accessed from the webContents module:
const { webContents } = require('electron')\nconsole.log(webContents)\nwebContents.getAllWebContents()Returns WebContents[] - An array of all WebContents instances. This will contain web contents for all windows, webviews, opened devtools, and devtools extension background pages.
webContents.getFocusedWebContents()Returns WebContents - The web contents that is focused in this application, otherwise returns null.
webContents.fromId(id)id InteiroReturns WebContents | undefined - A WebContents instance with the given ID, or undefined if there is no WebContents associated with the given ID.
webContents.fromDevToolsTargetId(targetId)targetId String - The Chrome DevTools Protocol TargetID associated with the WebContents instance.Returns WebContents | undefined - A WebContents instance with the given TargetID, or undefined if there is no WebContents associated with the given TargetID.
When communicating with the Chrome DevTools Protocol, it can be useful to lookup a WebContents instance based on its assigned TargetID.
\nasync function lookupTargetId (browserWindow) {\n const wc = browserWindow.webContents\n await wc.debugger.attach('1.3')\n const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')\n const { targetId } = targetInfo\n const targetWebContents = await webContents.fromDevToolsTargetId(targetId)\n}\n\n\nRender and control the contents of a BrowserWindow instance.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emitted when the navigation is done, i.e. the spinner of the tab has stopped spinning, and the onload event was dispatched.
Retorna:
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerThis event is like did-finish-load but emitted when the load failed. The full list of error codes and their meaning is available here.
Retorna:
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerThis event is like did-fail-load but emitted when the load was cancelled (e.g. window.stop() was invoked).
Retorna:
\nevent EventisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when a frame has done navigation.
\nCorresponds to the points in time when the spinner of the tab started spinning.
\nCorresponds to the points in time when the spinner of the tab stopped spinning.
\nRetorna:
\nevent EventEmitted when the document in the top-level frame is loaded.
\nRetorna:
\nevent Eventtitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when title is synthesized from file url.
Retorna:
\nevent Eventfavicons String[] - Array de URLs.Emitido quando a página recebe urls de favicon.
\nRetorna:
\nevent NewWindowWebContentsEventurlframeName Stringdisposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.options BrowserWindowConstructorOptions - The options which will be used for creating the new BrowserWindow.additionalFeatures String[] - The non-standard features (features not handled by Chromium or Electron) given to window.open(). Deprecated, and will now always be the empty array [].referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.Deprecated in favor of webContents.setWindowOpenHandler.
Emitted when the page requests to open a new window for a url. It could be requested by window.open or an external link like <a target='_blank'>.
By default a new BrowserWindow will be created for the url.
Calling event.preventDefault() will prevent Electron from automatically creating a new BrowserWindow. If you call event.preventDefault() and manually create a new BrowserWindow then you must set event.newGuest to reference the new BrowserWindow instance, failing to do so may result in unexpected behavior. Como por exemplo:
myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {\n event.preventDefault()\n const win = new BrowserWindow({\n webContents: options.webContents, // use existing webContents if provided\n show: false\n })\n win.once('ready-to-show', () => win.show())\n if (!options.webContents) {\n const loadOptions = {\n httpReferrer: referrer\n }\n if (postBody != null) {\n const { data, contentType, boundary } = postBody\n loadOptions.postData = postBody.data\n loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`\n }\n\n win.loadURL(url, loadOptions) // existing webContents will be navigated automatically\n }\n event.newGuest = win\n})\nRetorna:
\nwindow BrowserWindowdetailsurl String - URL for the created window.frameName String - Name given to the created window in the window.open() call.options BrowserWindowConstructorOptions - The options used to create the BrowserWindow. They are merged in increasing precedence: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Unrecognized options are not filtered out.referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.Emitted after successful creation of a window via window.open in the renderer. Not emitted if the creation of the window is canceled from webContents.setWindowOpenHandler.
See window.open() for more details and how to use this in conjunction with webContents.setWindowOpenHandler.
Retorna:
\nevent EventurlEmitted when a user or the page wants to start navigation. It can happen when the window.location object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with APIs like webContents.loadURL and webContents.back.
It is also not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Calling event.preventDefault() will prevent the navigation.
Retorna:
\nevent EventurlisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be true for in-page navigations.
Retorna:
\nevent EventurlisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted as a server side redirect occurs during navigation. For example a 302 redirect.
\nThis event will be emitted after did-start-navigation and always before the did-redirect-navigation event for the same navigation.
Calling event.preventDefault() will prevent the navigation (not just the redirect).
Retorna:
\nevent EventurlisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nThis event cannot be prevented, if you want to prevent redirects you should checkout out the will-redirect event above.
Retorna:
\nevent EventurlhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigationsEmitted when a main frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Retorna:
\nevent EventurlhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigations,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Retorna:
\nevent EventurlisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when an in-page navigation happened in any frame.
\nWhen in-page navigation happens, the page URL changes but does not cause navigation outside of the page. Examples of this occurring are when anchor links are clicked or when the DOM hashchange event is triggered.
Retorna:
\nevent EventEmitted when a beforeunload event handler is attempting to cancel a page unload.
Calling event.preventDefault() will ignore the beforeunload event handler and allow the page to be unloaded.
const { BrowserWindow, dialog } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.webContents.on('will-prevent-unload', (event) => {\n const choice = dialog.showMessageBoxSync(win, {\n type: 'question',\n buttons: ['Leave', 'Stay'],\n title: 'Do you want to leave this site?',\n message: 'Changes you made may not be saved.',\n defaultId: 0,\n cancelId: 1\n })\n const leave = (choice === 0)\n if (leave) {\n event.preventDefault()\n }\n})\nNote: This will be emitted for BrowserViews but will not be respected - this is because we have chosen not to tie the BrowserView lifecycle to its owning BrowserWindow should one exist per the specification.
Retorna:
\nevent Eventkilled BooleanEmitted when the renderer process crashes or is killed.
\nDeprecated: This event is superceded by the render-process-gone event which contains more information about why the render process disappeared. It isn't always because it crashed. The killed boolean can be replaced by checking reason === 'killed' when you switch to that event.
Retorna:
\nevent Eventdetailsreason String - The reason the render process is gone. Valores possíveis:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Integer - The exit code of the process, unless reason is launch-failed, in which case exitCode will be a platform-specific launch failure error code.Emitted when the renderer process unexpectedly disappears. This is normally because it was crashed or killed.
\nEmitted when the web page becomes unresponsive.
\nEmitted when the unresponsive web page becomes responsive again.
\nRetorna:
\nevent Eventname Stringversion StringEmitted when a plugin process has crashed.
\nEmitted when webContents is destroyed.
Retorna:
\nevent Eventinput Object - Input properties.type String - Either keyUp or keyDown.key String - Equivalent to KeyboardEvent.key.code String - Equivalent to KeyboardEvent.code.isAutoRepeat Boolean - Equivalent to KeyboardEvent.repeat.isComposing Boolean - Equivalent to KeyboardEvent.isComposing.shift Boolean - Equivalent to KeyboardEvent.shiftKey.control Boolean - Equivalent to KeyboardEvent.controlKey.alt Boolean - Equivalent to KeyboardEvent.altKey.meta Boolean - Equivalent to KeyboardEvent.metaKey.location Number - Equivalent to KeyboardEvent.location.modifiers String[] - See InputEvent.modifiers.Emitted before dispatching the keydown and keyup events in the page. Calling event.preventDefault will prevent the page keydown/keyup events and the menu shortcuts.
To only prevent the menu shortcuts, use setIgnoreMenuShortcuts:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nwin.webContents.on('before-input-event', (event, input) => {\n // For example, only enable application menu keyboard shortcuts when\n // Ctrl/Cmd are down.\n win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)\n})\nEmitted when the window enters a full-screen state triggered by HTML API.
\nEmitted when the window leaves a full-screen state triggered by HTML API.
\nRetorna:
\nevent EventzoomDirection String - Can be in or out.Emitted when the user is requesting to change the zoom level using the mouse wheel.
\nEmitted when DevTools is opened.
\nEmitted when DevTools is closed.
\nEmitted when DevTools is focused / opened.
\nRetorna:
\nevent Eventurlerror String - The error code.certificate Certificatecallback FunctionisTrusted Boolean - Indicates whether the certificate can be considered trusted.isMainFrame BooleanEmitted when failed to verify the certificate for url.
The usage is the same with the certificate-error event of app.
Retorna:
\nevent Eventurl URLcertificateList Certificate[]callback Functioncertificate Certificate - Must be a certificate from the given list.Emitido quando um certificado de cliente é solicitado.
\nThe usage is the same with the select-client-certificate event of app.
Retorna:
\nevent EventauthenticationResponseDetailsurl URLauthInfoisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (opcional)password String (opcional)Emitido quando webContents quer fazer uma autenticação básica.
The usage is the same with the login event of app.
Retorna:
\nevent Eventresult ObjectrequestId IntegeractiveMatchOrdinal Integer - Position of the active match.matches Integer - Number of Matches.selectionArea Rectangle - Coordinates of first match region.finalUpdate BooleanEmitted when a result is available for [webContents.findInPage] request.
Emitted when media starts playing.
\nEmitted when media is paused or done playing.
\nRetorna:
\nevent Eventcolor (String | null) - Theme color is in format of '#rrggbb'. It is null when no theme color is set.Emitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nRetorna:
\nevent EventurlEmitted when mouse moves over a link or the keyboard moves the focus to a link.
\nRetorna:
\nevent Eventtype Stringimage NativeImage (opcional)scale Float (optional) - scaling factor for the custom cursor.size Size (optional) - the size of the image.hotspot Point (optional) - coordinates of the custom cursor's hotspot.Emitted when the cursor's type changes. The type parameter can be default, crosshair, pointer, text, wait, help, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ns-resize, ew-resize, nesw-resize, nwse-resize, col-resize, row-resize, m-panning, e-panning, n-panning, ne-panning, nw-panning, s-panning, se-panning, sw-panning, w-panning, move, vertical-text, cell, context-menu, alias, progress, nodrop, copy, none, not-allowed, zoom-in, zoom-out, grab, grabbing or custom.
If the type parameter is custom, the image parameter will hold the custom cursor image in a NativeImage, and scale, size and hotspot will hold additional information about the custom cursor.
Retorna:
\nevent Eventparams Objectx Integer - x coordinate.y Integer - y coordinate.frame WebFrameMain - Frame from which the context menu was invoked.linkURL String - URL of the link that encloses the node the context menu was invoked on.linkText String - Text associated with the link. May be an empty string if the contents of the link are an image.pageURL String - URL of the top level page that the context menu was invoked on.frameURL String - URL of the subframe that the context menu was invoked on.srcURL String - Source URL for the element that the context menu was invoked on. Elements with source URLs are images, audio and video.mediaType String - Type of the node the context menu was invoked on. Can be none, image, audio, video, canvas, file or plugin.hasImageContents Boolean - Whether the context menu was invoked on an image which has non-empty contents.isEditable Boolean - Whether the context is editable.selectionText String - Text of the selection that the context menu was invoked on.titleText String - Title text of the selection that the context menu was invoked on.altText String - Alt text of the selection that the context menu was invoked on.suggestedFilename String - Suggested filename to be used when saving file through 'Save Link As' option of context menu.selectionRect Rectangle - Rect representing the coordinates in the document space of the selection.selectionStartOffset Number - Start position of the selection text.referrerPolicy Referrer - The referrer policy of the frame on which the menu is invoked.misspelledWord String - The misspelled word under the cursor, if any.dictionarySuggestions String[] - An array of suggested words to show the user to replace the misspelledWord. Only available if there is a misspelled word and spellchecker is enabled.frameCharset String - The character encoding of the frame on which the menu was invoked.inputFieldType String - If the context menu was invoked on an input field, the type of that field. Possible values are none, plainText, password, other.spellcheckEnabled Boolean - If the context is editable, whether or not spellchecking is enabled.menuSourceType String - Input source that invoked the context menu. Pode ser none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection ou adjustSelectionReset.mediaFlags Object - The flags for the media element the context menu was invoked on.inError Boolean - Whether the media element has crashed.isPaused Boolean - Whether the media element is paused.isMuted Boolean - Whether the media element is muted.hasAudio Boolean - Whether the media element has audio.isLooping Boolean - Whether the media element is looping.isControlsVisible Boolean - Whether the media element's controls are visible.canToggleControls Boolean - Whether the media element's controls are toggleable.canPrint Boolean - Whether the media element can be printed.canSave Boolean - Whether or not the media element can be downloaded.canShowPictureInPicture Boolean - Whether the media element can show picture-in-picture.isShowingPictureInPicture Boolean - Whether the media element is currently showing picture-in-picture.canRotate Boolean - Whether the media element can be rotated.canLoop Boolean - Whether the media element can be looped.editFlags Object - These flags indicate whether the renderer believes it is able to perform the corresponding action.canUndo Boolean - Whether the renderer believes it can undo.canRedo Boolean - Whether the renderer believes it can redo.canCut Boolean - Whether the renderer believes it can cut.canCopy Boolean - Whether the renderer believes it can copy.canPaste Boolean - Whether the renderer believes it can paste.canDelete Boolean - Whether the renderer believes it can delete.canSelectAll Boolean - Whether the renderer believes it can select all.canEditRichly Boolean - Whether the renderer believes it can edit text richly.Emitted when there is a new context menu that needs to be handled.
\nRetorna:
\nevent Eventdevices BluetoothDevice[]callback FunctiondeviceId StringEmitted when bluetooth device needs to be selected on call to navigator.bluetooth.requestDevice. To use navigator.bluetooth api webBluetooth should be enabled. If event.preventDefault is not called, first available device will be selected. callback should be called with deviceId to be selected, passing empty string to callback will cancel the request.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\napp.commandLine.appendSwitch('enable-experimental-web-platform-features')\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {\n event.preventDefault()\n const result = deviceList.find((device) => {\n return device.deviceName === 'test'\n })\n if (!result) {\n callback('')\n } else {\n callback(result.deviceId)\n }\n })\n})\nRetorna:
\nevent EventdirtyRect Rectangleimage NativeImage - The image data of the whole frame.Emitted when a new frame is generated. Only the dirty area is passed in the buffer.
\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ webPreferences: { offscreen: true } })\nwin.webContents.on('paint', (event, dirty, image) => {\n // updateBitmap(dirty, image.getBitmap())\n})\nwin.loadURL('http://github.com')\nEmitted when the devtools window instructs the webContents to reload
\nRetorna:
\nevent EventwebPreferences WebPreferences - The web preferences that will be used by the guest page. This object can be modified to adjust the preferences for the guest page.params Record<string, string> - The other <webview> parameters such as the src URL. This object can be modified to adjust the parameters of the guest page.Emitted when a <webview>'s web contents is being attached to this web contents. Calling event.preventDefault() will destroy the guest page.
This event can be used to configure webPreferences for the webContents of a <webview> before it's loaded, and provides the ability to set settings that can't be set via <webview> attributes.
Note: The specified preload script option will appear as preloadURL (not preload) in the webPreferences object emitted with this event.
Retorna:
\nevent EventwebContents WebContents - The guest web contents that is used by the <webview>.Emitted when a <webview> has been attached to this web contents.
Retorna:
\nevent Eventlevel Integer - The log level, from 0 to 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Integer - The line number of the source that triggered this console messagesourceId StringEmitted when the associated window logs a console message.
\nRetorna:
\nevent EventpreloadPath StringerrorEmitted when the preload script preloadPath throws an unhandled exception error.
Retorna:
\nevent Eventchannel String...args any[]Emitted when the renderer process sends an asynchronous message via ipcRenderer.send().
Retorna:
\nevent Eventchannel String...args any[]Emitted when the renderer process sends a synchronous message via ipcRenderer.sendSync().
Retorna:
\nevent EventEmitted when desktopCapturer.getSources() is called in the renderer process. Calling event.preventDefault() will make it return empty sources.
Retorna:
\nevent EventpreferredSize Size - The minimum size needed to contain the layout of the document—without requiring scrolling.Emitted when the WebContents preferred size has changed.
This event will only be emitted when enablePreferredSizeMode is set to true in webPreferences.
Retorna:
\nevent Eventdetailsframe WebFrameMainEmitted when the mainFrame, an <iframe>, or a nested <iframe> is loaded within the page.
contents.loadURL(url[, options])urloptions (opcional)httpReferrer (String | Referrer) (optional) - An HTTP Referrer url.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\".postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url is a data url and needs to load other files.Returns Promise<void> - the promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load). A noop rejection handler is already attached, which avoids unhandled rejection errors.
Loads the url in the window. The url must contain the protocol prefix, e.g. the http:// or file://. If the load should bypass http cache then use the pragma header to achieve it.
const { webContents } = require('electron')\nconst options = { extraHeaders: 'pragma: no-cache\\n' }\nwebContents.loadURL('https://github.com', options)\ncontents.loadFile(filePath[, options])filePath Stringoptions (opcional)query Record<String, String> (optional) - Passed to url.format().search String (optional) - Passed to url.format().hash String (optional) - Passed to url.format().Returns Promise<void> - the promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load).
Loads the given file in the window, filePath should be a path to an HTML file relative to the root of your application. For instance an app structure like this:
| root\n| - package.json\n| - src\n| - main.js\n| - index.html\nWould require code like this
\nwin.loadFile('src/index.html')\ncontents.downloadURL(url)urlInitiates a download of the resource at url without navigating. The will-download event of session will be triggered.
contents.getURL()Returns String - The URL of the current web page.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com').then(() => {\n const currentURL = win.webContents.getURL()\n console.log(currentURL)\n})\ncontents.getTitle()Returns String - The title of the current web page.
contents.isDestroyed()Returns Boolean - Whether the web page is destroyed.
contents.focus()Focuses the web page.
\ncontents.isFocused()Returns Boolean - Whether the web page is focused.
contents.isLoading()Returns Boolean - Whether web page is still loading resources.
contents.isLoadingMainFrame()Returns Boolean - Whether the main frame (and not just iframes or frames within it) is still loading.
contents.isWaitingForResponse()Returns Boolean - Whether the web page is waiting for a first-response from the main resource of the page.
contents.stop()Stops any pending navigation.
\ncontents.reload()Reloads the current web page.
\ncontents.reloadIgnoringCache()Reloads current page and ignores cache.
\ncontents.canGoBack()Returns Boolean - Whether the browser can go back to previous web page.
contents.canGoForward()Returns Boolean - Whether the browser can go forward to next web page.
contents.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the web page can go to offset.
contents.clearHistory()Clears the navigation history.
\ncontents.goBack()Makes the browser go back a web page.
\ncontents.goForward()Makes the browser go forward a web page.
\ncontents.goToIndex(index)index IntegerNavigates browser to the specified absolute web page index.
\ncontents.goToOffset(offset)offset IntegerNavigates to the specified offset from the \"current entry\".
\ncontents.isCrashed()Returns Boolean - Whether the renderer process has crashed.
contents.forcefullyCrashRenderer()Forcefully terminates the renderer process that is currently hosting this webContents. This will cause the render-process-gone event to be emitted with the reason=killed || reason=crashed. Please note that some webContents share renderer processes and therefore calling this method may also crash the host process for other webContents as well.
Calling reload() immediately after calling this method will force the reload to occur in a new process. This should be used when this process is unstable or unusable, for instance in order to recover from the unresponsive event.
contents.on('unresponsive', async () => {\n const { response } = await dialog.showMessageBox({\n message: 'App X has become unresponsive',\n title: 'Do you want to try forcefully reloading the app?',\n buttons: ['OK', 'Cancel'],\n cancelId: 1\n })\n if (response === 0) {\n contents.forcefullyCrashRenderer()\n contents.reload()\n }\n})\ncontents.setUserAgent(userAgent)userAgent StringOverrides the user agent for this web page.
\ncontents.getUserAgent()Returns String - The user agent for this web page.
contents.insertCSS(css[, options])css Stringoptions (opcional)cssOrigin String (optional) - Can be either 'user' or 'author'; Specifying 'user' enables you to prevent websites from overriding the CSS you insert. Default is 'author'.Returns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via contents.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\ncontents.on('did-finish-load', () => {\n contents.insertCSS('html, body { background-color: #f00; }')\n})\ncontents.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from contents.insertCSS(css).
contents.on('did-finish-load', async () => {\n const key = await contents.insertCSS('html, body { background-color: #f00; }')\n contents.removeInsertedCSS(key)\n})\ncontents.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (optional) - Default is false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Evaluates code in page.
In the browser window some HTML APIs like requestFullScreen can only be invoked by a gesture from the user. Setting userGesture to true will remove this limitation.
Code execution will be suspended until web page stop loading.
\ncontents.executeJavaScript('fetch(\"https://jsonplaceholder.typicode.com/users/1\").then(resp => resp.json())', true)\n .then((result) => {\n console.log(result) // Will be the JSON object from the fetch call\n })\ncontents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electron's contextIsolation feature. You can provide any integer here.scripts WebSource[]userGesture Boolean (optional) - Default is false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Works like executeJavaScript but evaluates scripts in an isolated context.
contents.setIgnoreMenuShortcuts(ignore)ignore BooleanIgnore application menu shortcuts while this web contents is focused.
\ncontents.setWindowOpenHandler(handler)handler Função<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>
detailsurl String - The resolved version of the URL passed to window.open(). e.g. opening a window with window.open('foo') will yield something like https://the-origin/the/current/path/foo.frameName String - Name of the window provided in window.open()features String - Comma separated list of window features provided to window.open().disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk or other.referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.Returns {action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny cancels the creation of the new window. allow will allow the new window to be created. Specifying overrideBrowserWindowOptions allows customization of the created window. Returning an unrecognized value such as a null, undefined, or an object without a recognized 'action' value will result in a console error and have the same effect as returning {action: 'deny'}.
Called before creating a window a new window is requested by the renderer, e.g. by window.open(), a link with target=\"_blank\", shift+clicking on a link, or submitting a form with <form target=\"_blank\">. See window.open() for more details and how to use this in conjunction with did-create-window.
contents.setAudioMuted(muted)muted BooleanMute the audio on the current web page.
\ncontents.isAudioMuted()Returns Boolean - Whether this page has been muted.
contents.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
contents.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\nThe factor must be greater than 0.0.
\ncontents.getZoomFactor()Returns Number - the current zoom factor.
contents.setZoomLevel(level)level Number - Zoom level.Changes the zoom level to the specified level. The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
contents.getZoomLevel()Returns Number - the current zoom level.
contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberRetorna Promise<void>
Sets the maximum and minimum pinch-to-zoom level.
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\ncontents.setVisualZoomLevelLimits(1, 3)\n
contents.undo()Executes the editing command undo in web page.
contents.redo()Executes the editing command redo in web page.
contents.cut()Executes the editing command cut in web page.
contents.copy()Executes the editing command copy in web page.
contents.copyImageAt(x, y)x Integery IntegerCopy the image at the given position to the clipboard.
\ncontents.paste()Executes the editing command paste in web page.
contents.pasteAndMatchStyle()Executes the editing command pasteAndMatchStyle in web page.
contents.delete()Executes the editing command delete in web page.
contents.selectAll()Executes the editing command selectAll in web page.
contents.unselect()Executes the editing command unselect in web page.
contents.replace(text)text StringExecutes the editing command replace in web page.
contents.replaceMisspelling(text)text StringExecutes the editing command replaceMisspelling in web page.
contents.insertText(text)text StringRetorna Promise<void>
Inserts text to the focused element.
contents.findInPage(text[, options])text String - Content to be searched, must not be empty.options (opcional)forward Boolean (optional) - Whether to search forward or backward, defaults to true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Defaults to false.matchCase Boolean (optional) - Whether search should be case-sensitive, defaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. The result of the request can be obtained by subscribing to found-in-page event.
contents.stopFindInPage(action)action String - Specifies the action to take place when ending [webContents.findInPage] request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webContents with the provided action.
const { webContents } = require('electron')\nwebContents.on('found-in-page', (event, result) => {\n if (result.finalUpdate) webContents.stopFindInPage('clearSelection')\n})\n\nconst requestId = webContents.findInPage('api')\nconsole.log(requestId)\ncontents.capturePage([rect])rect Rectangle (optional) - The area of the page to be captured.Returns Promise<NativeImage> - Resolves with a NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page.
contents.isBeingCaptured()Returns Boolean - Whether this page is being captured. It returns true when the capturer count is large then 0.
contents.incrementCapturerCount([size, stayHidden, stayAwake])size Size (optional) - The preferred size for the capturer.stayHidden Boolean (optional) - Keep the page hidden instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Increase the capturer count by one. The page is considered visible when its browser window is hidden and the capturer count is non-zero. If you would like the page to stay hidden, you should ensure that stayHidden is set to true.
This also affects the Page Visibility API.
\ncontents.decrementCapturerCount([stayHidden, stayAwake])stayHidden Boolean (optional) - Keep the page in hidden state instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Decrease the capturer count by one. The page will be set to hidden or occluded state when its browser window is hidden or occluded and the capturer count reaches zero. If you want to decrease the hidden capturer count instead you should set stayHidden to true.
contents.getPrinters()Get the system printer list.
\nRetorna PrinterInfo[]
contents.print([options], [callback])options (opcional)silent Boolean (optional) - Don't ask user for print settings. Por padrão é false.printBackground Boolean (optional) - Prints the background color and image of the web page. Por padrão é false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. Por padrão é true.margins (opcional)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. Por padrão é false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print. On macOS, only one range is honored.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Pode ser simplex, shortEdge ou longEdge.dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.callback Function (optional)success Boolean - Indicates success of the print call.failureReason String - Error description called back if the print fails.When a custom pageSize is passed, Chromium attempts to validate platform specific minimum values for width_microns and height_microns. Width and height must both be minimum 353 microns but may be higher on some operating systems.
Prints window's web page. When silent is set to true, Electron will pick the system's default printer if deviceName is empty and the default settings for printing.
Use page-break-before: always; CSS style to force to print to a new page.
Example usage:
\nconst options = {\n silent: true,\n deviceName: 'My-Printer',\n pageRanges: [{\n from: 0,\n to: 1\n }]\n}\nwin.webContents.print(options, (success, errorType) => {\n if (!success) console.log(errorType)\n})\ncontents.printToPDF(options)options ObjectheaderFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height and width in microns.printBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Buffer> - Resolves with the generated PDF data.
Prints window's web page as PDF with Chromium's preview printing custom settings.
\nThe landscape will be ignored if @page CSS at-rule is used in the web page.
By default, an empty options will be regarded as:
{\n marginsType: 0,\n printBackground: false,\n printSelectionOnly: false,\n landscape: false,\n pageSize: 'A4',\n scaleFactor: 100\n}\nUse page-break-before: always; CSS style to force to print to a new page.
An example of webContents.printToPDF:
const { BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\nconst os = require('os')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nwin.webContents.on('did-finish-load', () => {\n // Use default printing options\n win.webContents.printToPDF({}).then(data => {\n const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')\n fs.writeFile(pdfPath, data, (error) => {\n if (error) throw error\n console.log(`Wrote PDF successfully to ${pdfPath}`)\n })\n }).catch(error => {\n console.log(`Failed to write PDF to ${pdfPath}: `, error)\n })\n})\ncontents.addWorkSpace(path)path StringAdds the specified path to DevTools workspace. Must be used after DevTools creation:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.on('devtools-opened', () => {\n win.webContents.addWorkSpace(__dirname)\n})\ncontents.removeWorkSpace(path)path StringRemoves the specified path from DevTools workspace.
\ncontents.setDevToolsWebContents(devToolsWebContents)devToolsWebContents WebContentsUses the devToolsWebContents as the target WebContents to show devtools.
The devToolsWebContents must not have done any navigation, and it should not be used for other purposes after the call.
By default Electron manages the devtools by creating an internal WebContents with native view, which developers have very limited control of. With the setDevToolsWebContents method, developers can use any WebContents to show the devtools in it, including BrowserWindow, BrowserView and <webview> tag.
Note that closing the devtools does not destroy the devToolsWebContents, it is caller's responsibility to destroy devToolsWebContents.
An example of showing devtools in a <webview> tag:
<html>\n<head>\n <style type=\"text/css\">\n * { margin: 0; }\n #browser { height: 70%; }\n #devtools { height: 30%; }\n </style>\n</head>\n<body>\n <webview id=\"browser\" src=\"https://github.com\"></webview>\n <webview id=\"devtools\" src=\"about:blank\"></webview>\n <script>\n const { ipcRenderer } = require('electron')\n const emittedOnce = (element, eventName) => new Promise(resolve => {\n element.addEventListener(eventName, event => resolve(event), { once: true })\n })\n const browserView = document.getElementById('browser')\n const devtoolsView = document.getElementById('devtools')\n const browserReady = emittedOnce(browserView, 'dom-ready')\n const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')\n Promise.all([browserReady, devtoolsReady]).then(() => {\n const targetId = browserView.getWebContentsId()\n const devtoolsId = devtoolsView.getWebContentsId()\n ipcRenderer.send('open-devtools', targetId, devtoolsId)\n })\n </script>\n</body>\n</html>\n// Main process\nconst { ipcMain, webContents } = require('electron')\nipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {\n const target = webContents.fromId(targetContentsId)\n const devtools = webContents.fromId(devtoolsContentsId)\n target.setDevToolsWebContents(devtools)\n target.openDevTools()\n})\nAn example of showing devtools in a BrowserWindow:
const { app, BrowserWindow } = require('electron')\n\nlet win = null\nlet devtools = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n devtools = new BrowserWindow()\n win.loadURL('https://github.com')\n win.webContents.setDevToolsWebContents(devtools.webContents)\n win.webContents.openDevTools({ mode: 'detach' })\n})\ncontents.openDevTools([options])options (opcional)mode String - Opens the devtools with specified dock state, can be right, bottom, undocked, detach. Defaults to last used dock state. In undocked mode it's possible to dock back. In detach mode it's not.activate Boolean (optional) - Whether to bring the opened devtools window to the foreground. O padrão é verdadeiro.Opens the devtools.
\nWhen contents is a <webview> tag, the mode would be detach by default, explicitly passing an empty mode can force using last used dock state.
contents.closeDevTools()Closes the devtools.
\ncontents.isDevToolsOpened()Returns Boolean - Whether the devtools is opened.
contents.isDevToolsFocused()Returns Boolean - Whether the devtools view is focused .
contents.toggleDevTools()Toggles the developer tools.
\ncontents.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y).
contents.inspectSharedWorker()Opens the developer tools for the shared worker context.
\ncontents.inspectSharedWorkerById(workerId)workerId StringInspects the shared worker based on its ID.
\ncontents.getAllSharedWorkers()Returns SharedWorkerInfo[] - Information about all Shared Workers.
contents.inspectServiceWorker()Opens the developer tools for the service worker context.
\ncontents.send(channel, ...args)channel String...args any[]Send an asynchronous message to the renderer process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like postMessage, so prototype chains will not be included. O envio de funções, promessas, símbolos, weakmaps ou WeakSets lançará uma exceção.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the ipcRenderer module.
An example of sending messages from the main process to the renderer process:
\n// No processo main.\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL(`file://${__dirname}/index.html`)\n win.webContents.on('did-finish-load', () => {\n win.webContents.send('ping', 'whoooooooh!')\n })\n})\n<!-- index.html -->\n<html>\n<body>\n <script>\n require('electron').ipcRenderer.on('ping', (event, message) => {\n console.log(message) // Prints 'whoooooooh!'\n })\n </script>\n</body>\n</html>\ncontents.sendToFrame(frameId, channel, ...args)frameId Integer | [number, number] - the ID of the frame to send to, or a pair of [processId, frameId] if the frame is in a different process to the main frame.channel String...args any[]Send an asynchronous message to a specific frame in a renderer process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the ipcRenderer module.
If you want to get the frameId of a given renderer context you should use the webFrame.routingId value. Ex.
// In a renderer process\nconsole.log('My frameId is:', require('electron').webFrame.routingId)\nYou can also read frameId from all incoming IPC messages in the main process.
// In the main process\nipcMain.on('ping', (event) => {\n console.info('Message came from frameId:', event.frameId)\n})\ncontents.postMessage(channel, message, [transfer])Send a message to the renderer process, optionally transferring ownership of zero or more [MessagePortMain][] objects.
The transferred MessagePortMain objects will be available in the renderer process by accessing the ports property of the emitted event. When they arrive in the renderer, they will be native DOM MessagePort objects.
Como por exemplo:
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\ncontents.enableDeviceEmulation(parameters)parametersscreenPosition String - Specify the screen type to emulate (default: desktop):desktop - Desktop screen type.mobile - Mobile screen type.screenSize Size - Set the emulated screen size (screenPosition == mobile).viewPosition Point - Position the view on the screen (screenPosition == mobile) (default: { x: 0, y: 0 }).deviceScaleFactor Integer - Set the device scale factor (if zero defaults to original device scale factor) (default: 0).viewSize Size - Set the emulated view size (empty means no override)scale Float - Scale of emulated view inside available space (not in fit to view mode) (default: 1).Enable device emulation with the given parameters.
\ncontents.disableDeviceEmulation()Disable device emulation enabled by webContents.enableDeviceEmulation.
contents.sendInputEvent(inputEvent)inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventSends an input event to the page. Note: The BrowserWindow containing the contents needs to be focused for sendInputEvent() to work.
contents.beginFrameSubscription([onlyDirty ,]callback)onlyDirty Boolean (optional) - Defaults to false.callback Functionimage NativeImagedirtyRect RectangleBegin subscribing for presentation events and captured frames, the callback will be called with callback(image, dirtyRect) when there is a presentation event.
The image is an instance of NativeImage that stores the captured frame.
The dirtyRect is an object with x, y, width, height properties that describes which part of the page was repainted. If onlyDirty is set to true, image will only contain the repainted area. onlyDirty defaults to false.
contents.endFrameSubscription()End subscribing for frame presentation events.
\ncontents.startDrag(item)itemfile String - The path to the file being dragged.files String - The paths to the files being dragged. (files will override file field)icon NativeImage | String - The image must be non-empty on macOS.Sets the item as dragging item for current drag-drop operation, file is the absolute path of the file to be dragged, and icon is the image showing under the cursor when dragging.
contents.savePage(fullPath, saveType)fullPath String - The full file path.saveType String - Specify the save type.HTMLOnly - Save only the HTML of the page.HTMLComplete - Save complete-html page.MHTML - Save complete-html page as MHTML.Returns Promise<void> - resolves if the page is saved.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.loadURL('https://github.com')\n\nwin.webContents.on('did-finish-load', async () => {\n win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {\n console.log('Page was saved successfully.')\n }).catch(err => {\n console.log(err)\n })\n})\ncontents.showDefinitionForSelection() no macOSShows pop-up dictionary that searches the selected word on the page.
\ncontents.isOffscreen()Returns Boolean - Indicates whether offscreen rendering is enabled.
contents.startPainting()If offscreen rendering is enabled and not painting, start painting.
\ncontents.stopPainting()If offscreen rendering is enabled and painting, stop painting.
\ncontents.isPainting()Returns Boolean - If offscreen rendering is enabled returns whether it is currently painting.
contents.setFrameRate(fps)fps IntegerIf offscreen rendering is enabled sets the frame rate to the specified number. Only values between 1 and 240 are accepted.
\ncontents.getFrameRate()Returns Integer - If offscreen rendering is enabled returns the current frame rate.
contents.invalidate()Schedules a full repaint of the window this web contents is in.
\nIf offscreen rendering is enabled invalidates the frame and generates a new one through the 'paint' event.
contents.getWebRTCIPHandlingPolicy()Returns String - Returns the WebRTC IP Handling Policy.
contents.setWebRTCIPHandlingPolicy(policy)policy String - Specify the WebRTC IP Handling Policy.default - Exposes user's public and local IPs. This is the default behavior. When this policy is used, WebRTC has the right to enumerate all interfaces and bind them to discover public interfaces.default_public_interface_only - Exposes user's public IP, but does not expose user's local IP. When this policy is used, WebRTC should only use the default route used by http. This doesn't expose any local addresses.default_public_and_private_interfaces - Exposes user's public and local IPs. When this policy is used, WebRTC should only use the default route used by http. This also exposes the associated default private address. Default route is the route chosen by the OS on a multi-homed endpoint.disable_non_proxied_udp - Does not expose public or local IPs. When this policy is used, WebRTC should only use TCP to contact peers or servers unless the proxy server supports UDP.Setting the WebRTC IP handling policy allows you to control which IPs are exposed via WebRTC. See BrowserLeaks for more details.
\ncontents.getOSProcessId()Returns Integer - The operating system pid of the associated renderer process.
contents.getProcessId()Returns Integer - The Chromium internal pid of the associated renderer. Can be compared to the frameProcessId passed by frame specific navigation events (e.g. did-frame-navigate)
contents.takeHeapSnapshot(filePath)filePath String - Path to the output file.Returns Promise<void> - Indicates whether the snapshot has been created successfully.
Takes a V8 heap snapshot and saves it to filePath.
contents.getBackgroundThrottling()Returns Boolean - whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
contents.setBackgroundThrottling(allowed)allowed BooleanControls whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
\ncontents.getType()Returns String - the type of the webContent. Can be backgroundPage, window, browserView, remote, webview or offscreen.
contents.setImageAnimationPolicy(policy)policy String - Can be animate, animateOnce or noAnimation.Sets the image animation policy for this webContents. The policy only affects new images, existing images that are currently being animated are unaffected. This is a known limitation in Chromium, you can force image animation to be recalculated with img.src = img.src which will result in no network traffic but will update the animation policy.
This corresponds to the animationPolicy accessibility feature in Chromium.
\ncontents.audioMutedA Boolean property that determines whether this page is muted.
contents.userAgentA String property that determines the user agent for this web page.
contents.zoomLevelA Number property that determines the zoom level for this web contents.
The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
contents.zoomFactorA Number property that determines the zoom factor for this web contents.
The zoom factor is the zoom percent divided by 100, so 300% = 3.0.
\ncontents.frameRateAn Integer property that sets the frame rate of the web contents to the specified number. Only values between 1 and 240 are accepted.
Only applicable if offscreen rendering is enabled.
\ncontents.id ReadonlyA Integer representing the unique ID of this WebContents. Each ID is unique among all WebContents instances of the entire Electron application.
contents.session ReadonlyA Session used by this webContents.
contents.hostWebContents ReadonlyA WebContents instance that might own this WebContents.
contents.devToolsWebContents ReadonlyA WebContents | null property that represents the of DevTools WebContents associated with a given WebContents.
Note: Users should never store this object because it may become null when the DevTools has been closed.
contents.debugger ReadonlyA Debugger instance for this webContents.
contents.backgroundThrottlingA Boolean property that determines whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
contents.mainFrame ReadonlyA WebFrameMain property that represents the top frame of the page's frame hierarchy.
If you want to embed (third-party) web content in an Electron BrowserWindow, there are three options available to you: <iframe> tags, <webview> tags, and BrowserViews. Each one offers slightly different functionality and is useful in different situations. To help you choose between these, this guide explains the differences and capabilities of each option.
Iframes no Electron se comportam como em navegadores regulares. An <iframe> element in your page can show external web pages, provided that their Content Security Policy allows it. To limit the number of capabilities of a site in an <iframe> tag, it is recommended to use the sandbox attribute and only allow the capabilities you want to support.
\n\nImportant Note: we do not recommend you to use WebViews, as this tag undergoes dramatic architectural changes that may affect stability of your application. Consider switching to alternatives, like
\niframeand Electron'sBrowserView, or an architecture that avoids embedded content by design.
WebViews are based on Chromium's WebViews and are not explicitly supported by Electron. We do not guarantee that the WebView API will remain available in future versions of Electron. To use <webview> tags, you will need to set webviewTag to true in the webPreferences of your BrowserWindow.
WebView is a custom element (<webview>) that will only work inside Electron. Eles são implementados como um \"iframe fora de processo\". This means that all communication with the <webview> is done asynchronously using IPC. The <webview> element has many custom methods and events, similar to webContents, that provide you with greater control over the content.
Compared to an <iframe>, <webview> tends to be slightly slower but offers much greater control in loading and communicating with the third-party content and handling various events.
BrowserViews are not a part of the DOM - instead, they are created in and controlled by your Main process. They are simply another layer of web content on top of your existing window. This means that they are completely separate from your own BrowserWindow content and their position is not controlled by the DOM or CSS. Instead, it is controlled by setting the bounds in the Main process.
BrowserViews offer the greatest control over their contents, since they implement the webContents similarly to how the BrowserWindow does it. However, as BrowserViews are not a part of your DOM, but are rather overlaid on top of them, you will have to manage their position manually.
\n\nCustomize the rendering of the current web page.
\n
Processo: Renderizador
\nwebFrame export of the Electron module is an instance of the WebFrame class representing the top frame of the current BrowserWindow. Sub-frames can be retrieved by certain properties and methods (e.g. webFrame.firstChild).
An example of zooming current page to 200%.
\nconst { webFrame } = require('electron')\n\nwebFrame.setZoomFactor(2)\nThe WebFrame class has the following instance methods:
webFrame.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\nThe factor must be greater than 0.0.
\nwebFrame.getZoomFactor()Returns Number - The current zoom factor.
webFrame.setZoomLevel(level)level Number - Zoom level.Changes the zoom level to the specified level. The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively.
\n\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
webFrame.getZoomLevel()Returns Number - The current zoom level.
webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberSets the maximum and minimum pinch-to-zoom level.
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\nwebFrame.setVisualZoomLevelLimits(1, 3)\n
\n\nNOTE: Visual zoom only applies to pinch-to-zoom behavior. Cmd+/-/0 zoom shortcuts are controlled by the 'zoomIn', 'zoomOut', and 'resetZoom' MenuItem roles in the application Menu. To disable shortcuts, manually define the Menu and omit zoom roles from the definition.
\n
webFrame.setSpellCheckProvider(language, provider)language StringproviderspellCheck Funçãowords String[]callback FunctionmisspeltWords String[]Sets a provider for spell checking in input fields and text areas.
\nIf you want to use this method you must disable the builtin spellchecker when you construct the window.
\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: false\n }\n})\nThe provider must be an object that has a spellCheck method that accepts an array of individual words for spellchecking. The spellCheck function runs asynchronously and calls the callback function with an array of misspelt words when complete.
An example of using node-spellchecker as provider:
\nconst { webFrame } = require('electron')\nconst spellChecker = require('spellchecker')\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck (words, callback) {\n setTimeout(() => {\n const spellchecker = require('spellchecker')\n const misspelled = words.filter(x => spellchecker.isMisspelled(x))\n callback(misspelled)\n }, 0)\n }\n})\nwebFrame.insertCSS(css)css String - CSS source code.Returns String - A key for the inserted CSS that can later be used to remove the CSS via webFrame.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\nwebFrame.removeInsertedCSS(key)key StringRemoves the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from webFrame.insertCSS(css).
webFrame.insertText(text)text StringInserts text to the focused element.
webFrame.executeJavaScript(code[, userGesture, callback])code StringuserGesture Boolean (optional) - Default is false.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.result AnyerrorReturns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
Evaluates code in page.
In the browser window some HTML APIs like requestFullScreen can only be invoked by a gesture from the user. Setting userGesture to true will remove this limitation.
webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])worldId Integer - The ID of the world to run the javascript in, 0 is the default main world (where content runs), 999 is the world used by Electron's contextIsolation feature. Accepts values in the range 1..536870911.scripts WebSource[]userGesture Boolean (optional) - Default is false.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.result AnyerrorReturns Promise<any> - A promise that resolves with the result of the executed code or is rejected if execution could not start.
Works like executeJavaScript but evaluates scripts in an isolated context.
Note that when the execution of script fails, the returned promise will not reject and the result would be undefined. This is because Chromium does not dispatch errors of isolated worlds to foreign worlds.
webFrame.setIsolatedWorldInfo(worldId, info)worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electrons contextIsolation feature. Chrome extensions reserve the range of IDs in [1 << 20, 1 << 29). You can provide any integer here.infosecurityOrigin String (optional) - Security origin for the isolated world.csp String (optional) - Content Security Policy for the isolated world.name String (optional) - Name for isolated world. Useful in devtools.Set the security origin, content security policy and name of the isolated world. Note: If the csp is specified, then the securityOrigin also has to be specified.
webFrame.getResourceUsage()Retorna Object:
images MemoryUsageDetailsscripts MemoryUsageDetailscssStyleSheets MemoryUsageDetailsxslStyleSheets MemoryUsageDetailsfonts MemoryUsageDetailsother MemoryUsageDetailsReturns an object describing usage information of Blink's internal memory caches.
\nconst { webFrame } = require('electron')\nconsole.log(webFrame.getResourceUsage())\nThis will generate:
\n{\n images: {\n count: 22,\n size: 2549,\n liveSize: 2542\n },\n cssStyleSheets: { /* same with \"images\" */ },\n xslStyleSheets: { /* same with \"images\" */ },\n fonts: { /* same with \"images\" */ },\n other: { /* same with \"images\" */ }\n}\nwebFrame.clearCache()Attempts to free memory that is no longer being used (like images from a previous navigation).
\nNote that blindly calling this method probably makes Electron slower since it will have to refill these emptied caches, you should only call it if an event in your app has occurred that makes you think your page is actually using less memory (i.e. you have navigated from a super heavy page to a mostly empty one, and intend to stay there).
\nwebFrame.getFrameForSelector(selector)selector String - CSS selector for a frame element.Returns WebFrame - The frame element in webFrame's document selected by selector, null would be returned if selector does not select a frame or if the frame is not in the current renderer process.
webFrame.findFrameByName(name)name StringReturns WebFrame - A child of webFrame with the supplied name, null would be returned if there's no such frame or if the frame is not in the current renderer process.
webFrame.findFrameByRoutingId(routingId)routingId Integer - An Integer representing the unique frame id in the current renderer process. Routing IDs can be retrieved from WebFrame instances (webFrame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate)Returns WebFrame - that has the supplied routingId, null if not found.
webFrame.isWordMisspelled(word)word String - The word to be spellchecked.Returns Boolean - True if the word is misspelled according to the built in spellchecker, false otherwise. If no dictionary is loaded, always return false.
webFrame.getWordSuggestions(word)word String - The misspelled word.Returns String[] - A list of suggested words for a given word. If the word is spelled correctly, the result will be empty.
webFrame.top ReadonlyA WebFrame | null representing top frame in frame hierarchy to which webFrame belongs, the property would be null if top frame is not in the current renderer process.
webFrame.opener ReadonlyA WebFrame | null representing the frame which opened webFrame, the property would be null if there's no opener or opener is not in the current renderer process.
webFrame.parent ReadonlyA WebFrame | null representing parent frame of webFrame, the property would be null if webFrame is top or parent is not in the current renderer process.
webFrame.firstChild ReadonlyA WebFrame | null representing the first child frame of webFrame, the property would be null if webFrame has no children or if first child is not in the current renderer process.
webFrame.nextSibling ReadonlyA WebFrame | null representing next sibling frame, the property would be null if webFrame is the last frame in its parent or if the next sibling is not in the current renderer process.
webFrame.routingId ReadonlyAn Integer representing the unique frame id in the current renderer process. Distinct WebFrame instances that refer to the same underlying frame will have the same routingId.
\n\nControl web pages and iframes.
\n
Processo: Main
\nThe webFrameMain module can be used to lookup frames across existing WebContents instances. Navigation events are the common use case.
const { BrowserWindow, webFrameMain } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://twitter.com')\n\nwin.webContents.on(\n 'did-frame-navigate',\n (event, url, isMainFrame, frameProcessId, frameRoutingId) => {\n const frame = webFrameMain.fromId(frameProcessId, frameRoutingId)\n if (frame) {\n const code = 'document.body.innerHTML = document.body.innerHTML.replaceAll(\"heck\", \"h*ck\")'\n frame.executeJavaScript(code)\n }\n }\n)\nYou can also access frames of existing pages by using the mainFrame property of WebContents.
const { BrowserWindow } = require('electron')\n\nasync function main () {\n const win = new BrowserWindow({ width: 800, height: 600 })\n await win.loadURL('https://reddit.com')\n\n const youtubeEmbeds = win.webContents.mainFrame.frames.filter((frame) => {\n try {\n const url = new URL(frame.url)\n return url.host === 'www.youtube.com'\n } catch {\n return false\n }\n })\n\n console.log(youtubeEmbeds)\n}\n\nmain()\nThese methods can be accessed from the webFrameMain module:
webFrameMain.fromId(processId, routingId)processId Integer - An Integer representing the internal ID of the process which owns the frame.routingId Integer - An Integer representing the unique frame ID in the current renderer process. Routing IDs can be retrieved from WebFrameMain instances (frame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate).Returns WebFrameMain | undefined - A frame with the given process and routing IDs, or undefined if there is no WebFrameMain associated with the given IDs.
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emitted when the document is loaded.
\nframe.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (optional) - Default is false.Returns Promise<unknown> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
Evaluates code in page.
In the browser window some HTML APIs like requestFullScreen can only be invoked by a gesture from the user. Setting userGesture to true will remove this limitation.
frame.reload()Returns boolean - Whether the reload was initiated successfully. Only results in false when the frame has no history.
frame.send(channel, ...args)channel String...args any[]Send an asynchronous message to the renderer process via channel, along with arguments. Arguments will be serialized with the [Structured Clone Algorithm][SCA], just like [postMessage][], so prototype chains will not be included. O envio de funções, promessas, símbolos, weakmaps ou WeakSets lançará uma exceção.
The renderer process can handle the message by listening to channel with the ipcRenderer module.
frame.postMessage(channel, message, [transfer])Send a message to the renderer process, optionally transferring ownership of zero or more [MessagePortMain][] objects.
The transferred MessagePortMain objects will be available in the renderer process by accessing the ports property of the emitted event. When they arrive in the renderer, they will be native DOM MessagePort objects.
Como por exemplo:
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nframe.url ReadonlyA string representing the current URL of the frame.
frame.top ReadonlyA WebFrameMain | null representing top frame in the frame hierarchy to which frame belongs.
frame.parent ReadonlyA WebFrameMain | null representing parent frame of frame, the property would be null if frame is the top frame in the frame hierarchy.
frame.frames ReadonlyA WebFrameMain[] collection containing the direct descendents of frame.
frame.framesInSubtree ReadonlyA WebFrameMain[] collection containing every frame in the subtree of frame, including itself. This can be useful when traversing through all frames.
frame.frameTreeNodeId ReadonlyAn Integer representing the id of the frame's internal FrameTreeNode instance. This id is browser-global and uniquely identifies a frame that hosts content. The identifier is fixed at the creation of the frame and stays constant for the lifetime of the frame. When the frame is removed, the id is not used again.
frame.name ReadonlyA String representing the frame name.
frame.osProcessId ReadonlyAn Integer representing the operating system pid of the process which owns this frame.
frame.processId ReadonlyAn Integer representing the Chromium internal pid of the process which owns this frame. This is not the same as the OS process ID; to read that use frame.osProcessId.
frame.routingId ReadonlyAn Integer representing the unique frame id in the current renderer process. Distinct WebFrameMain instances that refer to the same underlying frame will have the same routingId.
frame.visibilityState ReadonlyA string representing the visibility state of the frame.
See also how the Page Visibility API is affected by other Electron APIs.
", "title": "webFrameMain", "description": "Control web pages and iframes." }, "/docs/api/web-request": { "locale": "pt-BR", "slug": "web-request", "href": "/docs/api/web-request", "crowdinFileId": "256405", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-request.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nIntercept and modify the contents of a request at various stages of its lifetime.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Instances of the WebRequest class are accessed by using the webRequest property of a Session.
The methods of WebRequest accept an optional filter and a listener. The listener will be called with listener(details) when the API's event has happened. The details object describes the request.
⚠️ Only the last attached listener will be used. Passing null as listener will unsubscribe from the event.
The filter object has a urls property which is an Array of URL patterns that will be used to filter out the requests that do not match the URL patterns. If the filter is omitted then all requests will be matched.
For certain events the listener is passed with a callback, which should be called with a response object when listener has done its work.
An example of adding User-Agent header for requests:
const { session } = require('electron')\n\n// Modify the user agent for all requests to the following urls.\nconst filter = {\n urls: ['https://*.github.com/*', '*://electron.github.io']\n}\n\nsession.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {\n details.requestHeaders['User-Agent'] = 'MyAgent'\n callback({ requestHeaders: details.requestHeaders })\n})\nThe following methods are available on instances of WebRequest:
webRequest.onBeforeRequest([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Inteirourlmethod StringwebContentsId Integer (opcional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleuploadData UploadData[]callback Functionresponse Objectcancel Boolean (opcional)redirectURL String (optional) - The original request is prevented from being sent or completed and is instead redirected to the given URL.The listener will be called with listener(details, callback) when a request is about to occur.
The uploadData is an array of UploadData objects.
O callback tem que ser chamado com um objeto response.
Alguns exemplos de urls válidas:
'http://foo:1234/'\n'http://foo.com/'\n'http://foo:1234/bar'\n'*://*/*'\n'*://example.com/*'\n'*://example.com/foo/*'\n'http://*.foo:1234/'\n'file://foo:1234/bar'\n'http://foo:*/'\n'*://www.foo.com/'\nwebRequest.onBeforeSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Inteirourlmethod StringwebContentsId Integer (opcional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders Record<string, string>callback FunctionbeforeSendResponse Objectcancel Boolean (opcional)requestHeaders Record<string, string | string[]> (optional) - When provided, request will be made with these headers.The listener will be called with listener(details, callback) before sending an HTTP request, once the request headers are available. Isto pode ocorrer após uma conexão TCP ser feita ao servidor, mas antes que qualquer dado http seja enviado.
The callback has to be called with a response object.
webRequest.onSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Inteirourlmethod StringwebContentsId Integer (opcional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders Record<string, string>The listener will be called with listener(details) just before a request is going to be sent to the server, modifications of previous onBeforeSendHeaders response are visible by the time this listener is fired.
webRequest.onHeadersReceived([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Inteirourlmethod StringwebContentsId Integer (opcional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublestatusLine StringstatusCode IntegerresponseHeaders Record<string, string[]> (optional)callback FunctionheadersReceivedResponse Objectcancel Boolean (opcional)responseHeaders Record<string, string | string[]> (optional) - When provided, the server is assumed to have responded with these headers.statusLine String (optional) - Should be provided when overriding responseHeaders to change header status otherwise original response header's status will be used.The listener will be called with listener(details, callback) when HTTP response headers of a request have been received.
The callback has to be called with a response object.
webRequest.onResponseStarted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Inteirourlmethod StringwebContentsId Integer (opcional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache Boolean - Indicates whether the response was fetched from disk cache.statusCode IntegerstatusLine StringThe listener will be called with listener(details) when first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.
webRequest.onBeforeRedirect([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Inteirourlmethod StringwebContentsId Integer (opcional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleredirectURL StringstatusCode IntegerstatusLine Stringip String (optional) - The server IP address that the request was actually sent to.fromCache BooleanresponseHeaders Record<string, string[]> (optional)The listener will be called with listener(details) when a server initiated redirect is about to occur.
webRequest.onCompleted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Inteirourlmethod StringwebContentsId Integer (opcional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache BooleanstatusCode IntegerstatusLine Stringerror StringThe listener will be called with listener(details) when a request is completed.
webRequest.onErrorOccurred([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetailsid Inteirourlmethod StringwebContentsId Integer (opcional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublefromCache Booleanerror String - The error description.The listener will be called with listener(details) when an error occurs.
urls String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.code Stringurl String (optional)startLine Integer (optional) - Default is 1.<webview> TagElectron's webview tag is based on Chromium's webview, which is undergoing dramatic architectural changes. This impacts the stability of webviews, including rendering, navigation, and event routing. We currently recommend to not use the webview tag and to consider alternatives, like iframe, Electron's BrowserView, or an architecture that avoids embedded content altogether.
By default the webview tag is disabled in Electron >= 5. You need to enable the tag by setting the webviewTag webPreferences option when constructing your BrowserWindow. For more information see the BrowserWindow constructor docs.
\n\nDisplay external web content in an isolated frame and process.
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Use the webview tag to embed 'guest' content (such as web pages) in your Electron app. The guest content is contained within the webview container. An embedded page within your app controls how the guest content is laid out and rendered.
Unlike an 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. Note: Most methods called on the webview from the host page require a synchronous call to the main process.
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:
<webview id=\"foo\" src=\"https://www.github.com/\" style=\"display:inline-flex; width:640px; height:480px\"></webview>\nIf 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:
<script>\n onload = () => {\n const webview = document.querySelector('webview')\n const indicator = document.querySelector('.indicator')\n\n const loadstart = () => {\n indicator.innerText = 'loading...'\n }\n\n const loadstop = () => {\n indicator.innerText = ''\n }\n\n webview.addEventListener('did-start-loading', loadstart)\n webview.addEventListener('did-stop-loading', loadstop)\n }\n</script>\nUnder the hood webview is implemented with Out-of-Process iframes (OOPIFs). The webview tag is essentially a custom element using shadow DOM to wrap an iframe element inside it.
So the behavior of webview is very similar to a cross-domain iframe, as examples:
webview, the page focus will move from the embedder frame to webview.webview.webview are asynchronous.Please note that the webview tag's style uses display:flex; internally to ensure the child iframe element fills the full height and width of its webview container when used with traditional and flexbox layouts. Please do not overwrite the default display:flex; CSS property, unless specifying display:inline-flex; for inline layout.
The webview tag has the following attributes:
src<webview src=\"https://www.github.com/\"></webview>\nA String representing 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!.
nodeintegration<webview src=\"http://www.google.com/\" nodeintegration></webview>\nA Boolean. When this attribute is present the guest page in webview will have node integration and can use node APIs like require and process to access low level system resources. Node integration is disabled by default in the guest page.
nodeintegrationinsubframes<webview src=\"http://www.google.com/\" nodeintegrationinsubframes></webview>\nA Boolean for the experimental option for enabling NodeJS support in sub-frames such as iframes inside the webview. All your preloads will load for every iframe, you can use process.isMainFrame to determine if you are in the main frame or not. This option is disabled by default in the guest page.
plugins<webview src=\"https://www.github.com/\" plugins></webview>\nA Boolean. When this attribute is present the guest page in webview will be able to use browser plugins. Plugins are disabled by default.
preload<!-- from a file -->\n<webview src=\"https://www.github.com/\" preload=\"./test.js\"></webview>\n<!-- or if you want to load from an asar archive -->\n<webview src=\"https://www.github.com/\" preload=\"./app.asar/test.js\"></webview>\nA String that specifies a script that will be loaded before other scripts run in the guest page. The protocol of script's URL must be file: (even when using asar: archives) because it will be loaded by Node's require under the hood, which treats asar: archives as virtual directories.
When the guest page doesn't have node integration this script will still have access to all Node APIs, but global objects injected by Node will be deleted after this script has finished executing.
\nNote: This option will appear as preloadURL (not preload) in the webPreferences specified to the will-attach-webview event.
httpreferrer<webview src=\"https://www.github.com/\" httpreferrer=\"http://cheng.guru\"></webview>\nA String that sets the referrer URL for the guest page.
useragent<webview src=\"https://www.github.com/\" useragent=\"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko\"></webview>\nA String that sets the user agent for the guest page before the page is navigated to. Once the page is loaded, use the setUserAgent method to change the user agent.
disablewebsecurity<webview src=\"https://www.github.com/\" disablewebsecurity></webview>\nA Boolean. When this attribute is present the guest page will have web security disabled. Web security is enabled by default.
partition<webview src=\"https://github.com\" partition=\"persist:github\"></webview>\n<webview src=\"https://electronjs.org\" partition=\"electron\"></webview>\nA String that sets the session used by the page. If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. if there is no persist: prefix, the page will use an in-memory session. By assigning the same partition, multiple pages can share the same session. If the partition is unset then default session of the app will be used.
This value can only be modified before the first navigation, since the session of an active renderer process cannot change. Subsequent attempts to modify the value will fail with a DOM exception.
\nallowpopups<webview src=\"https://www.github.com/\" allowpopups></webview>\nA Boolean. When this attribute is present the guest page will be allowed to open new windows. Popups are disabled by default.
webpreferences<webview src=\"https://github.com\" webpreferences=\"allowRunningInsecureContent, javascript=no\"></webview>\nA String which is a comma separated list of strings which specifies the web preferences to be set on the webview. The full list of supported preference strings can be found in BrowserWindow.
The string follows the same format as the features string in window.open. A name by itself is given a true boolean value. A preference can be set to another value by including an =, followed by the value. Special values yes and 1 are interpreted as true, while no and 0 are interpreted as false.
enableblinkfeatures<webview src=\"https://www.github.com/\" enableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be enabled separated by ,. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
disableblinkfeatures<webview src=\"https://www.github.com/\" disableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be disabled separated by ,. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
The webview tag has the following methods:
Note: The webview element must be loaded before using the methods.
\nExemplo
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('dom-ready', () => {\n webview.openDevTools()\n})\n<webview>.loadURL(url[, options])url URLoptions (opcional)httpReferrer (String | Referrer) (optional) - An HTTP Referrer url.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url is a data url and needs to load other files.Returns Promise<void> - The promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load).
Loads the url in the webview, the url must contain the protocol prefix, e.g. the http:// or file://.
<webview>.downloadURL(url)urlInitiates a download of the resource at url without navigating.
<webview>.getURL()Returns String - The URL of guest page.
<webview>.getTitle()Returns String - The title of guest page.
<webview>.isLoading()Returns Boolean - Whether guest page is still loading resources.
<webview>.isLoadingMainFrame()Returns Boolean - Whether the main frame (and not just iframes or frames within it) is still loading.
<webview>.isWaitingForResponse()Returns Boolean - Whether the guest page is waiting for a first-response for the main resource of the page.
<webview>.stop()Stops any pending navigation.
\n<webview>.reload()Reloads the guest page.
\n<webview>.reloadIgnoringCache()Reloads the guest page and ignores cache.
\n<webview>.canGoBack()Returns Boolean - Whether the guest page can go back.
<webview>.canGoForward()Returns Boolean - Whether the guest page can go forward.
<webview>.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the guest page can go to offset.
<webview>.clearHistory()Clears the navigation history.
\n<webview>.goBack()Makes the guest page go back.
\n<webview>.goForward()Makes the guest page go forward.
\n<webview>.goToIndex(index)index IntegerNavigates to the specified absolute index.
\n<webview>.goToOffset(offset)offset IntegerNavigates to the specified offset from the \"current entry\".
\n<webview>.isCrashed()Returns Boolean - Whether the renderer process has crashed.
<webview>.setUserAgent(userAgent)userAgent StringOverrides the user agent for the guest page.
\n<webview>.getUserAgent()Returns String - The user agent for guest page.
<webview>.insertCSS(css)css StringReturns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via <webview>.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\n<webview>.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from <webview>.insertCSS(css).
<webview>.executeJavaScript(code[, userGesture])code StringuserGesture Boolean (optional) - Default false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Evaluates code in page. If userGesture is set, it will create the user gesture context in the page. HTML APIs like requestFullScreen, which require user action, can take advantage of this option for automation.
<webview>.openDevTools()Opens a DevTools window for guest page.
\n<webview>.closeDevTools()Closes the DevTools window of guest page.
\n<webview>.isDevToolsOpened()Returns Boolean - Whether guest page has a DevTools window attached.
<webview>.isDevToolsFocused()Returns Boolean - Whether DevTools window of guest page is focused.
<webview>.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y) of guest page.
<webview>.inspectSharedWorker()Opens the DevTools for the shared worker context present in the guest page.
\n<webview>.inspectServiceWorker()Opens the DevTools for the service worker context present in the guest page.
\n<webview>.setAudioMuted(muted)muted BooleanSet guest page muted.
\n<webview>.isAudioMuted()Returns Boolean - Whether guest page has been muted.
<webview>.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
<webview>.undo()Executes editing command undo in page.
<webview>.redo()Executes editing command redo in page.
<webview>.cut()Executes editing command cut in page.
<webview>.copy()Executes editing command copy in page.
<webview>.paste()Executes editing command paste in page.
<webview>.pasteAndMatchStyle()Executes editing command pasteAndMatchStyle in page.
<webview>.delete()Executes editing command delete in page.
<webview>.selectAll()Executes editing command selectAll in page.
<webview>.unselect()Executes editing command unselect in page.
<webview>.replace(text)text StringExecutes editing command replace in page.
<webview>.replaceMisspelling(text)text StringExecutes editing command replaceMisspelling in page.
<webview>.insertText(text)text StringRetorna Promise<void>
Inserts text to the focused element.
<webview>.findInPage(text[, options])text String - Content to be searched, must not be empty.options (opcional)forward Boolean (optional) - Whether to search forward or backward, defaults to true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Defaults to false.matchCase Boolean (optional) - Whether search should be case-sensitive, defaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. The result of the request can be obtained by subscribing to found-in-page event.
<webview>.stopFindInPage(action)action String - Specifies the action to take place when ending <webview>.findInPage request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webview with the provided action.
<webview>.print([options])options (opcional)silent Boolean (optional) - Don't ask user for print settings. Por padrão é false.printBackground Boolean (optional) - Prints the background color and image of the web page. Por padrão é false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. Por padrão é true.margins (opcional)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. Por padrão é false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Pode ser simplex, shortEdge ou longEdge.dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.Retorna Promise<void>
Prints webview's web page. Same as webContents.print([options]).
<webview>.printToPDF(options)options ObjectheaderFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin. and width in microns.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print. On macOS, only the first range is honored.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing heightprintBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Uint8Array> - Resolves with the generated PDF data.
Prints webview's web page as PDF, Same as webContents.printToPDF(options).
<webview>.capturePage([rect])rect Rectangle (optional) - The area of the page to be captured.Returns Promise<NativeImage> - Resolves with a NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page.
<webview>.send(channel, ...args)channel String...args any[]Retorna Promise<void>
Send an asynchronous message to renderer process via channel, you can also send arbitrary arguments. The renderer process can handle the message by listening to the channel event with the ipcRenderer module.
See webContents.send for examples.
\n<webview>.sendToFrame(frameId, channel, ...args)frameId [number, number] - [processId, frameId]channel String...args any[]Retorna Promise<void>
Send an asynchronous message to renderer process via channel, you can also send arbitrary arguments. The renderer process can handle the message by listening to the channel event with the ipcRenderer module.
See webContents.sendToFrame for examples.
\n<webview>.sendInputEvent(event)event MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventRetorna Promise<void>
Sends an input event to the page.
See webContents.sendInputEvent for detailed description of event object.
<webview>.setZoomFactor(factor)factor Number - Zoom factor.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\n<webview>.setZoomLevel(level)level Number - Zoom level.Changes the zoom level to the specified level. The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
<webview>.getZoomFactor()Returns Number - the current zoom factor.
<webview>.getZoomLevel()Returns Number - the current zoom level.
<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberRetorna Promise<void>
Sets the maximum and minimum pinch-to-zoom level.
\n<webview>.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\n<webview>.getWebContentsId()Returns Number - The WebContents ID of this webview.
The following DOM events are available to the webview tag:
Retorna:
\nurlisMainFrame BooleanFired when a load has committed. This includes navigation within the current document as well as subframe document-level loads, but does not include asynchronous resource loads.
\nFired when the navigation is done, i.e. the spinner of the tab will stop spinning, and the onload event is dispatched.
Retorna:
\nerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanThis event is like did-finish-load, but fired when the load failed or was cancelled, e.g. window.stop() is invoked.
Retorna:
\nisMainFrame BooleanFired when a frame has done navigation.
\nCorresponds to the points in time when the spinner of the tab starts spinning.
\nCorresponds to the points in time when the spinner of the tab stops spinning.
\nFired when attached to the embedder web contents.
\nFired when document in the given frame is loaded.
\nRetorna:
\ntitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when title is synthesized from file url.
Retorna:
\nfavicons String[] - Array de URLs.Fired when page receives favicon urls.
\nFired when page enters fullscreen triggered by HTML API.
\nFired when page leaves fullscreen triggered by HTML API.
\nRetorna:
\nlevel Integer - The log level, from 0 to 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Integer - The line number of the source that triggered this console messagesourceId StringFired when the guest window logs a console message.
\nThe following example code forwards all log messages to the embedder's console without regard for log level or other properties.
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('console-message', (e) => {\n console.log('Guest page logged a message:', e.message)\n})\nRetorna:
\nresult ObjectrequestId IntegeractiveMatchOrdinal Integer - Position of the active match.matches Integer - Number of Matches.selectionArea Rectangle - Coordinates of first match region.finalUpdate BooleanFired when a result is available for webview.findInPage request.
const webview = document.querySelector('webview')\nwebview.addEventListener('found-in-page', (e) => {\n webview.stopFindInPage('keepSelection')\n})\n\nconst requestId = webview.findInPage('test')\nconsole.log(requestId)\nRetorna:
\nurlframeName Stringdisposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.options BrowserWindowConstructorOptions - The options which should be used for creating the new BrowserWindow.Fired when the guest page attempts to open a new browser window.
\nThe following example code opens the new url in system's default browser.
\nconst { shell } = require('electron')\nconst webview = document.querySelector('webview')\n\nwebview.addEventListener('new-window', async (e) => {\n const protocol = (new URL(e.url)).protocol\n if (protocol === 'http:' || protocol === 'https:') {\n await shell.openExternal(e.url)\n }\n})\nRetorna:
\nurlEmitted when a user or the page wants to start navigation. It can happen when the window.location object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with APIs like <webview>.loadURL and <webview>.back.
It is also not emitted during in-page navigation, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Calling event.preventDefault() does NOT have any effect.
Retorna:
\nurlisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be true for in-page navigations.
Retorna:
\nurlisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nRetorna:
\nurlEmitted when a navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Retorna:
\nurlhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigations,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Retorna:
\nisMainFrame BooleanurlEmitted when an in-page navigation happened.
\nWhen in-page navigation happens, the page URL changes but does not cause navigation outside of the page. Examples of this occurring are when anchor links are clicked or when the DOM hashchange event is triggered.
Fired when the guest page attempts to close itself.
\nThe following example code navigates the webview to about:blank when the guest attempts to close itself.
const webview = document.querySelector('webview')\nwebview.addEventListener('close', () => {\n webview.src = 'about:blank'\n})\nRetorna:
\nframeId [number, number] - pair of [processId, frameId].channel Stringargs any[]Fired when the guest page has sent an asynchronous message to embedder page.
\nWith sendToHost method and ipc-message event you can communicate between guest page and embedder page:
// In embedder page.\nconst webview = document.querySelector('webview')\nwebview.addEventListener('ipc-message', (event) => {\n console.log(event.channel)\n // Prints \"pong\"\n})\nwebview.send('ping')\n// In guest page.\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('ping', () => {\n ipcRenderer.sendToHost('pong')\n})\nFired when the renderer process is crashed.
\nRetorna:
\nname Stringversion StringFired when a plugin process is crashed.
\nFired when the WebContents is destroyed.
\nEmitted when media starts playing.
\nEmitted when media is paused or done playing.
\nRetorna:
\nthemeColor StringEmitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nRetorna:
\nurlEmitted when mouse moves over a link or the keyboard moves the focus to a link.
\nEmitted when DevTools is opened.
\nEmitted when DevTools is closed.
\nEmitted when DevTools is focused / opened.
", "title": "Existem várias maneiras de controlar como as janelas são criadas a partir de conteúdo confiável ou não confiável dentro de um renderizador. Windows can be created from the renderer in two ways:
\ntarget=_blankwindow.open()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.
When nativeWindowOpen is set to false, window.open instead results in the creation of a BrowserWindowProxy, 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 BrowserWindow in the main process by using webContents.setWindowOpenHandler() for renderer-created windows.
BrowserWindow constructor options are set by, in increasing precedence order: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Note that webContents.setWindowOpenHandler has final say and full privilege because it is invoked in the main process.
window.open(url[, frameName][, features])urlframeName String (opcional)features String (opcional)Returns BrowserWindowProxy | Window
features is a comma-separated key-value list, following the standard format of the browser. Electron will parse BrowserWindowConstructorOptions out of this list where possible, for convenience. For full control and better ergonomics, consider using webContents.setWindowOpenHandler to customize the BrowserWindow creation.
A subset of WebPreferences can be set directly, unnested, from the features string: zoomFactor, nodeIntegration, preload, javascript, contextIsolation, and webviewTag.
Como por exemplo:
\nwindow.open('https://github.com', '_blank', 'top=500,left=200,frame=false,nodeIntegration=no')\nNotas:
\nwindow if it is disabled on the parent window.window if it is enabled on the parent window.window if it is disabled on the parent window.features will be passed to any registered webContents's did-create-window event handler in the options argument.frameName follows the specification of windowName located in the native documentation.To customize or cancel the creation of the window, you can optionally set an override handler with webContents.setWindowOpenHandler() from the main 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.
Window example// main.js\nconst mainWindow = new BrowserWindow()\n\n// In this example, only windows with the `about:blank` url will be created.\n// All other urls will be blocked.\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url === 'about:blank') {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n frame: false,\n fullscreenable: false,\n backgroundColor: 'black',\n webPreferences: {\n preload: 'my-child-window-preload-script.js'\n }\n }\n }\n }\n return { action: 'deny' }\n})\n// renderer process (mainWindow)\nconst childWindow = window.open('', 'modal')\nchildWindow.document.write('<h1>Hello</h1>')\nBrowserWindowProxy example\n// main.js\nconst mainWindow = new BrowserWindow({\n webPreferences: { nativeWindowOpen: false }\n})\n\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url.startsWith('https://github.com/')) {\n return { action: 'allow' }\n }\n return { action: 'deny' }\n})\n\nmainWindow.webContents.on('did-create-window', (childWindow) => {\n // For example...\n childWindow.webContents.on('will-navigate', (e) => {\n e.preventDefault()\n })\n})\n// renderer.js\nconst windowProxy = window.open('https://github.com/', null, 'minimizable=false')\nwindowProxy.postMessage('hi', '*')\nSe seu aplicativo roda com o Electron 6.0.8 ou superior, agora você pode construí-lo para o Windows 10 no ARM. This considerably improves performance, but requires recompilation of any native modules used in your app. It may also require small fixups to your build and packaging scripts.
\nSe o seu aplicativo não usa nenhum módulo nativo, então é muito mais fácil criar uma versão do ARM do seu aplicativo.
\nnode_modules do seu app esteja vazio.set npm_config_arch=arm64 antes de executar npm install/yarn install como de costume.Lots of Windows-specific code contains if... else logic that selects between either the x64 or x86 architectures.
\nif (process.arch === 'x64') {\n // Do 64-bit thing...\n} else {\n // Do 32-bit thing...\n}\nSe você quiser o arm64 como arquitetura de destino, uma lógica como essa normalmente vai selecionar a arquitetura errada, então verifique com muita atenção o seu aplicativo e seus scripts de compilação em busca de condições como essa. Em scripts de compilação e empacotamento personalizados, você sempre deve verificar o valor de npm_config_arch no ambiente, em vez de depender da arquitetura no processo atual.
If you use native modules, you must make sure that they compile against v142 of the MSVC compiler (provided in Visual Studio 2017). You must also check that any pre-built .dll or .lib files provided or referenced by the native module are available for Windows on Arm.
Para testar seu aplicativo, use um dispositivo ARM executando o Windows 10 ARM (versão 1903 ou mais tarde). Certifique-se de copiar seu aplicativo para o dispositivo de destino - a sandbox do Chromium não funcionará corretamente ao carregar seus recursos de aplicativo a partir de um local de rede.
\nRecomenda-se o Node.js v12.9.0 ou posterior. Se atualizar para uma nova versão do Node não for desejável, em vez disso, atualize a cópia do npm do node-gyp manualmente para a versão 5.0.2 ou posterior, que contém as alterações necessárias para compilar módulos nativos para ARM.
\nO Visual Studio 2017 (qualquer edição) é necessário para a compilação de módulos nativos. Você pode baixar o Visual Studio Community 2017 através do programa Visual Studio Dev Essentials da Microsoft. Após a instalação, você pode adicionar os componentes específicos do ARM executando o seguinte comando a partir de um Prompt de Comando:
\nvs_installer.exe ^\n--add Microsoft.VisualStudio.Workload.NativeDesktop ^\n--add Microsoft.VisualStudio.Component.VC.ATLMFC ^\n--add Microsoft.VisualStudio.Component.VC.Tools.ARM64 ^\n--add Microsoft.VisualStudio.Component.VC.MFC.ARM64 ^\n--includeRecommended\nDefinir npm_config_arch=arm64 no ambiente cria os arquivos .obj corretos para arm64, mas o Prompt de Comando do Desenvolvedor para VS 2017 padrão utilizará o vinculador x64. Para corrigir isto:
vcvarsamd64_arm64.bat ao invés de vcvarsamd64_x86.bat.Se feito com sucesso, o prompt de comando deverá imprimir algo semelhante a isso na inicialização:
\n**********************************************************************\n** Visual Studio 2017 Developer Command Prompt v15.9.15\n** Copyright (c) 2017 Microsoft Corporation\n**********************************************************************\n[vcvarsall.bat] Environment initialized for: 'x64_arm64'\nSe você deseja desenvolver seu aplicativo diretamente em um dispositivo do Arm, substitua vcvarsx86_arm64.bat no Destino para que a compilação cruzada ocorra com a emulação x86 do dispositivo.
node.lib corretoBy default, node-gyp unpacks Electron's node headers and downloads the x86 and x64 versions of node.lib into %APPDATA%\\..\\Local\\node-gyp\\Cache, but it does not download the arm64 version (a fix for this is in development.) Para corrigir isto:
node.lib de https://electronjs.org/headers/v6.0.9/win-arm64/node.lib%APPDATA%\\..\\Local\\node-gyp\\Cache\\6.0.9\\arm64\\node.libSubstitua 6.0.9 pela versão que você está usando.
Depois de completar tudo acima, abra o seu prompt de comando de compilação cruzada e execute set npm_config_arch=arm64. Então use o npm install para construir seu projeto normalmente. Como com a compilação cruzada de módulos x86, você pode precisar excluir a pasta node_modules para forçar a recompilação de módulos nativos se eles tiverem sido compilados anteriormente para outra arquitetura.
Módulos nativos podem ser depurados com o Visual Studio 2017 (funcionando na sua máquina de desenvolvimento) e o depurador remoto do Visual Studio correspondente rodando no dispositivo de destino. Para depurar:
\n.exe on the target device via the Command Prompt (passing --inspect-brk to pause it before any native modules are loaded)..pdb symbols under Debugging > Symbols.Se você encontrar um problema com esta documentação, ou se seu aplicativo funciona quando compilado para x86, mas não para arm64, por favor registre um problema com \"Windows on Arm\" no título.
", "title": "Windows on ARM", "description": "" }, "/docs/tutorial/windows-store-guide": { "locale": "pt-BR", "slug": "windows-store-guide", "href": "/docs/tutorial/windows-store-guide", "crowdinFileId": "256273", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-store-guide.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Com o Windows 10, o bom e velho executável win32 ganhou uma nova irmã: A Plataforma Universal do Windows. O novo formato .appx não apenas disponibiliza várias APIs poderosas como Cortana e Notificações Push, mas através da Windows Store, também simplifica a instalação e atualização das aplicações.
A Microsoft desenvolveu uma ferramenta que compila aplicações Electron em formato .appx, possibilitando que desenvolvedores utilizem algumas das facilidades no novo modelo de aplicação. Este modelo explica como utilizá-lo e quais as capacidades e limitações de uma aplicação Electron AppX.
A \"Atualização de Aniversário\" do Windows 10 é capaz de rodar binários win32 .exe os executando juntamente com um sistema de arquivos e de registros virtualizados. Ambos são criados durante a compilação ao executar a aplicação e o instalador dentro de um Container Windows, permitindo que o Windows identifique exatamente quais modificações ao sistema operacional são realizadas durante a instalação. Parear o executável com um sistema de arquivos e de registros virtualizados permite com que o Windows habilite a instalação e desinstalação de um clique.
Adicionalmente, o exe é executado dentro do modelo appx, ou seja, ele pode utilizar muitas das APIs disponívels para a Plataforma Universal do Windows. Para ganhar ainda mais recursos, uma aplicação Electron pode parear com um processo em segundo plano da UWP (Plataforma Universal do Windows), que é executado juntamente com o exe, ou seja, uma espécie de ajudante para rodar processos em segundo plano, receber notificações push ou para se comunicar com outras aplicações UWP.
Para compilar qualquer aplicação Electron já existente, certifique-se de que você está de acordo com os seguintes requisitos:
\nnode -v)Então, instale o electron-windows-store CLI:
npm install -g electron-windows-store\nEmpacote a aplicação utilizando electron-packager (ou uma ferramenta similar). Make sure to remove node_modules that you don't need in your final application, since any module you don't actually need will increase your application's size.
A saída deve ser algo mais ou menos assim:
\n├── Ghost.exe\n├── LICENSE\n├── content_resources_200_percent.pak\n├── content_shell.pak\n├── d3dcompiler_47.dll\n├── ffmpeg.dll\n├── icudtl.dat\n├── libEGL.dll\n├── libGLESv2.dll\n├── locales\n│ ├── am.pak\n│ ├── ar.pak\n│ ├── [...]\n├── node.dll\n├── resources\n│ └── app.asar\n├── v8_context_snapshot.bin\n├── squirrel.exe\n└── ui_resources_200_percent.pak\nAbra o PowerShell em modo de administrador e execute electron-windows-store com os parâmetros necessários, informando tanto o diretório de origem quanto o diretório de destino, o nome da aplicação, sua versão e a confirmação de que os node_modules devem estar achatados.
electron-windows-store `\n --input-directory C:\\myelectronapp `\n --output-directory C:\\output\\myelectronapp `\n --package-version 1.0.0.0 `\n --package-name myelectronapp\nAssim que executada, a ferramenta faz seu trabalho: Ela aceita sua aplicação Electron como entrada, achatando os node_modules. Então, ela empacota sua aplicação como app.zip. Utilizando um instalador e um container Windows, a ferramenta cria um pacote AppX \"expandido\" - incluindo o Manifesto de Aplicação Windows (AppXManifest.xml), assim como o sistema de arquivos e sistema de registros virtual dentro da pasta de destino.
Assim que os arquivos AppX expandidos são criados, a ferramente utiliza o Windows App Packager (MakeAppx.exe) para criar um arquivo AppX único baseado em aqueles arquivos no disco. Finalmente, a ferramenta pode ser utilizada para criar um certificado confiável em seu computador para assinar a nova aplicação AppX. Com a aplicação AppX assinada, o CLI pode também instalar automaticamente a mesma em sua máquina.
Para conseguir executar sua aplicação, seus usuários precisarão do Windows 10 com sua então chamada \"Atualização de Aniversário\" - detalhes em como atualizar o Windows podem ser encontrados aqui.
\nAo contrário de aplicações UWP tradicionais, aplicações empacotadas deverão seguir um processo de verificação manual, em qual você pode se increver aqui. In the meantime, all users will be able to install your package by double-clicking it, so a submission to the store might not be necessary if you're looking for an easier installation method. Em ambientes gerenciados (geralmente empresas) o Add-AppxPackage, que é um Cmdlet do PowerShell, pode ser utilizado para instalá-lo de uma forma automatizada.
Outra limitação importante é que a aplicação AppX compilada contém um executável win32 - e, portanto, não pode ser executado no Xbox, Hololens ou smartphones.
\nVocê pode parear sua aplicação Electron com um processo UWP em segundo plano, esta, pode fazer pleno uso dos recursos do Windows 10 - como notificações em push, Cortana ou Live Tiles.
\nPara verificar como uma aplicação Electron utiliza um processo em segundo plano para enviar notificações e Live Tiles, confira a amostra fornecida pela própria Microsoft.
\nPara gerar a aplicação AppX, o electron-windows-store CLI utiliza um template que deve funcionar para a maioria das aplicações Electron. De qualquer maneira, se você estiver utilizando um instalador customizado ou você tiver algum problema com o pacote gerado, você pode tentar criar um pacote utilizando compilação com um Container Windows. Neste modo, o CLI irá instalar e rodar sua aplicação em um Container Windows cru para determinar quais modificações sua aplicação sua aplicação esta fazendo no sistema operacional.
Antes de executar o CLI pela primeira vez, você deverá configurar o \"Windows Desktop App Converter\". Isso deverá levar alguns minutos, mas não se preocupe - você só terá de fazer isso uma vez. Faça o Download do Desktop App Converter aqui. Você receberá dois arquivos: DesktopAppConverter.zip e BaseImage-14316.wim.
DesktopAppConverter.zip. De um PowerShell com poderes administrativos (aberto com \"executar como Administrador\", certifique-se de que a política de execução do seu sistema nos permita executar tudo que temos a intenção chamando Set-ExecutionPolicybypass.BaseImage-14316.wim), chamando .\\DesktopAppConverter.ps1-Setup-BaseImage.\\BaseImage-14316.wim.Assim que instalação estiver bem sucedida, você pode seguir e compilar sua aplicação Electron.
", "title": "Guia para Windows Store", "description": "" }, "/docs/tutorial/windows-taskbar": { "locale": "pt-BR", "slug": "windows-taskbar", "href": "/docs/tutorial/windows-taskbar", "crowdinFileId": "256275", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-taskbar.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "O Electron possui APIs para a configuração do ícone do aplicativo na barra de tarefas do Windows. This API supports both Windows-only features like creation of a JumpList, custom thumbnails and toolbars, icon overlays, and the so-called \"Flash Frame\" effect, and cross-platform features like recent documents and application progress.
Windows allows apps to define a custom context menu that shows up when users right-click the app's icon in the taskbar. Esse menu de contexto é chamado JumpList. You specify custom actions in the Tasks category of JumpList, as quoted from MSDN:
\n\nAplicativos definem tarefas com base em recursos do programa e as principais coisas que um usuário espera fazer com eles. Tasks should be context-free, in that the application does not need to be running for them to work. They should also be the statistically most common actions that a normal user would perform in an application, such as compose an email message or open the calendar in a mail program, create a new document in a word processor, launch an application in a certain mode, or launch one of its subcommands. An application should not clutter the menu with advanced features that standard users won't need or one-time actions such as registration. Do not use tasks for promotional items such as upgrades or special offers.
\nIt is strongly recommended that the task list be static. It should remain the same regardless of the state or status of the application. While it is possible to vary the list dynamically, you should consider that this could confuse the user who does not expect that portion of the destination list to change.
\n
\n\nNOTE: The screenshot above is an example of general tasks of Internet Explorer
\n
Unlike the dock menu in macOS which is a real menu, user tasks in Windows work like application shortcuts. For example, when a user clicks a task, the program will be executed with specified arguments.
\nTo set user tasks for your application, you can use app.setUserTasks API.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app } = require('electron')\n\napp.setUserTasks([\n {\n program: process.execPath,\n arguments: '--new-window',\n iconPath: process.execPath,\n iconIndex: 0,\n title: 'New Window',\n description: 'Create a new window'\n }\n])\nTo clear your tasks list, you need to call app.setUserTasks with an empty array in the main.js file.
const { app } = require('electron')\n\napp.setUserTasks([])\n\n\nNOTE: The user tasks will still be displayed even after closing your application, so the icon and program path specified for a task should exist until your application is uninstalled.
\n
On Windows, you can add a thumbnail toolbar with specified buttons to a taskbar layout of an application window. It provides users with a way to access a particular window's command without restoring or activating the window.
\nAs quoted from MSDN:
\n\n\nThis toolbar is the familiar standard toolbar common control. It has a maximum of seven buttons. Each button's ID, image, tooltip, and state are defined in a structure, which is then passed to the taskbar. The application can show, enable, disable, or hide buttons from the thumbnail toolbar as required by its current state.
\nFor example, Windows Media Player might offer standard media transport controls such as play, pause, mute, and stop.
\n
\n\nNOTE: The screenshot above is an example of thumbnail toolbar of Windows Media Player
\n
To set thumbnail toolbar in your application, you need to use BrowserWindow.setThumbarButtons
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { BrowserWindow } = require('electron')\nconst path = require('path')\n\nconst win = new BrowserWindow()\n\nwin.setThumbarButtons([\n {\n tooltip: 'button1',\n icon: path.join(__dirname, 'button1.png'),\n click () { console.log('button1 clicked') }\n }, {\n tooltip: 'button2',\n icon: path.join(__dirname, 'button2.png'),\n flags: ['enabled', 'dismissonclick'],\n click () { console.log('button2 clicked.') }\n }\n])\nTo clear thumbnail toolbar buttons, you need to call BrowserWindow.setThumbarButtons with an empty array in the main.js file.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.setThumbarButtons([])\nOn Windows, a taskbar button can use a small overlay to display application status.
\nAs quoted from MSDN:
\n\n\nIcon overlays serve as a contextual notification of status, and are intended to negate the need for a separate notification area status icon to communicate that information to the user. For instance, the new mail status in Microsoft Outlook, currently shown in the notification area, can now be indicated through an overlay on the taskbar button. Again, you must decide during your development cycle which method is best for your application. Overlay icons are intended to supply important, long-standing status or notifications such as network status, messenger status, or new mail. The user should not be presented with constantly changing overlays or animations.
\n
\n\nNOTE: The screenshot above is an example of overlay on a taskbar button
\n
To set the overlay icon for a window, you need to use the BrowserWindow.setOverlayIcon API.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.setOverlayIcon('path/to/overlay.png', 'Description for overlay')\nOn Windows, you can highlight the taskbar button to get the user's attention. This is similar to bouncing the dock icon in macOS.
\nAs quoted from MSDN:
\n\n\nTypically, a window is flashed to inform the user that the window requires attention but that it does not currently have the keyboard focus.
\n
To flash the BrowserWindow taskbar button, you need to use the BrowserWindow.flashFrame API.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.once('focus', () => win.flashFrame(false))\nwin.flashFrame(true)\n\n", "title": "Taskbar Customization (Windows)", "description": "Aplicativos definem tarefas com base em recursos do programa e as principais coisas que um usuário espera fazer com eles. Tasks should be context-free, in that the application does not need to be running for them to work. They should also be the statistically most common actions that a normal user would perform in an application, such as compose an email message or open the calendar in a mail program, create a new document in a word processor, launch an application in a certain mode, or launch one of its subcommands. An application should not clutter the menu with advanced features that standard users won't need or one-time actions such as registration. Do not use tasks for promotional items such as upgrades or special offers.\nIt is strongly recommended that the task list be static. It should remain the same regardless of the state or status of the application. While it is possible to vary the list dynamically, you should consider that this could confuse the user who does not expect that portion of the destination list to change." } }, "de-DE": { "/docs/api/accelerator": { "locale": "de-DE", "slug": "accelerator", "href": "/docs/api/accelerator", "crowdinFileId": "256277", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/accelerator.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "NOTE: Don't forget to call
\nwin.flashFrame(false)to turn off the flash. In the above example, it is called when the window comes into focus, but you might use a timeout or some other event to disable it.
\n\nDefiniere Tastenkürzel
\n
Acceleratoren sind String die mehrere Modifikatoren und einzelne Key Codes enthalten können. Diese werden mit einem + Zeichen verknüpft und werden dazu verwendet, Tastenkürzel für deine App zu definieren.
Beispiele:
\nCommandOrControl+ACommandOrControl+Shift+ZTastenkürzel werden registriert mit dem globalShortcut Modul durch die register Methode, z.B.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+Y' shortcut listener.\n globalShortcut.register('CommandOrControl+Y', () => {\n // Do stuff when Y and either Command/Control is pressed.\n })\n})\nUnter Linux und Windows hat die Command Taste keinen Effekt, weshalb CommandOrControl benutzt werden sollte. Es repräsentiert Command unter macOS und Control unter Linux und Windows um Tastenkürzel zu definieren.
Verwenden Sie Alt anstelle von Option. Option existiert nur unter macOS, wohingegen Alt in allen Betriebssystemen verfügbar ist.
The Super (or Meta) key is mapped to the Windows key on Windows and Linux and Cmd on macOS.
Command (oder kurz Cmd)Control (oder kurz Ctrl)CommandOrControl (oder kurz CmdOrCtrl)AltOptionAltGrShiftSuperMeta0 bis 9A bis ZF1 bis F24~, !, @, #, $, etc.PlusSpace (Leerzeichen)TabCapslockNumlockScrolllockBackspaceDeleteInsertReturn (Oder Enter als Alias)Up, Down, Left und RightHome und EndPageUp und PageDownEscape (oder Esc als Abkürzung)VolumeUp, VolumeDown und VolumeMuteMediaNextTrack, MediaPreviousTrack, MediaStop und MediaPlayPausePrintScreennum0 - num9numdec - decimal keynumadd - numpad + keynumsub - numpad - keynummult - numpad * keynumdiv - numpad ÷ keyMaking accessible applications is important and we're happy to provide functionality to Devtron and Spectron that gives developers the opportunity to make their apps better for everyone.
\nAccessibility concerns in Electron applications are similar to those of websites because they're both ultimately HTML. With Electron apps, however, you can't use the online resources for accessibility audits because your app doesn't have a URL to point the auditor to.
\nThese features bring those auditing tools to your Electron app. You can choose to add audits to your tests with Spectron or use them within DevTools with Devtron. Lesen Sie weiter für eine Zusammenfassung der Werkzeuge.
\nIn the testing framework Spectron, you can now audit each window and <webview> tag in your application. Ein Beispiel:
app.client.auditAccessibility().then(function (audit) {\n if (audit.failed) {\n console.error(audit.message)\n }\n})\nErfahren Sie mehr über dieses Feature in der Spectron Dokumentation.
\nIn Devtron, there is an accessibility tab which will allow you to audit a page in your app, sort and filter the results.
\n
Both of these tools are using the Accessibility Developer Tools library built by Google for Chrome. You can learn more about the accessibility audit rules this library uses on that repository's wiki.
\nIf you know of other great accessibility tools for Electron, add them to the accessibility documentation with a pull request.
\nElectron applications will automatically enable accessibility features in the presence of assistive technology (e.g. JAWS on Windows or VoiceOver on macOS). Schauen Sie in die Dokumentation für Barrierefreiheit für weitere Informationen.
\nYou can also manually toggle these features either within your Electron application or by setting flags in third-party native software.
\nBy using the app.setAccessibilitySupportEnabled(enabled) API, you can manually expose Chrome's accessibility tree to users in the application preferences. Note that the user's system assistive utilities have priority over this setting and will override it.
On macOS, third-party assistive technology can toggle accessibility features inside Electron applications by setting the AXManualAccessibility attribute programmatically:
CFStringRef kAXManualAccessibility = CFSTR(\"AXManualAccessibility\");\n\n+ (void)enableAccessibility:(BOOL)enable inElectronApplication:(NSRunningApplication *)app\n{\n AXUIElementRef appRef = AXUIElementCreateApplication(app.processIdentifier);\n if (appRef == nil)\n return;\n\n CFBooleanRef value = enable ? kCFBooleanTrue : kCFBooleanFalse;\n AXUIElementSetAttributeValue(appRef, kAXManualAccessibility, value);\n CFRelease(appRef);\n}\n\n\nKontrolliere den Ereignisverlauf deiner Anwendung.
\n
Prozess: Haupt
\nDas folgende Beispiel zeigt, wie die Applikation beendet wird, wenn das letzte Fenster geschlossen wurde:
\nconst { app } = require('electron')\napp.on('window-all-closed', () => {\n app.quit()\n})\nDas app Objekt stellt folgende Event zur Verfügung:
Wird ausgelöst wenn die Anwendung den grundlegenenden Start abgeschlossen hat. Unter Windows und Linux, hat das will-finish-launching-Ereignis das gleiche Verhalten wie das ready-Event; unter macOS, repräsentiert dieses Event die applicationWillFinishLaunching-Benachrichtung von NSApplication. In der Regel würden hier Listener für die Events open-file und open-url registriert und der Crash Reporter und Auto-Updater gestartet werden.
In den meisten Fällen, sollte man alles im ready Eventhandler machen.
Kehrt zurück:
\nevent EventlaunchInfo Record<string, any> | NotificationResponse macOSWird einmal ausgesendet, wenn Electron die Initialisierung beendet hat. On macOS, launchInfo holds the userInfo of the NSUserNotification or information from UNNotificationResponse that was used to open the application, if it was launched from Notification Center. Sie können auch app.isReady() um zu prüfen, ob dieses Ereignis bereits ausgelöst wurde und app.whenReady() um ein Promise zu initialisieren, das ausgeführt wird, wenn Electron initialisiert wird.
Wird gefeuert, wenn alle Fenster geschlossen wurden.
\nWenn du keinen einzigen Listener für dieses Event nutzt und alle Fenster geschlossen sind, ist die standardmäßige Handhabung des Events das Beenden der App. Wenn du allerdings auf das Event hörst, hast du die Kontrolle darüber, ob die App beendet werden soll oder nicht. Wenn entweder der Nutzer durch Drücken von Cmd + Q oder der Entwickler durch einen Aufruf von app.quit() die App zum Beenden bewegt, wird Electron zuerst versuchen alle Fenster zu schließen und danach erst das will-emit auslösen. In einem solchen Fall wird das window-all-closed Event übrigens überhaupt nicht ausgelöst.
Kehrt zurück:
\nevent EventAusgelöst, bevor sich die Fenster der Anwendung schließen. Ein Aufruf von event.preventDefault() verhindert das Standardverhalten, welches die Anwendung schließt.
Wichtig: Wenn das Beenden der App durch einen Aufruf von autoUpdater.quitAndInstall() initiiert wurde, wird das before-quit Event nach der Auslösung aller close Events für alle Fenster ausgelöst und diese werden geschlossen.
Hinweis: Wenn die Anwendung unter Windows beendet wird, weil das System heruntergefahren oder neu gestartet wird oder der Benutzer sich abmeldet, wird dieses Event nicht ausgelöst.
\nKehrt zurück:
\nevent EventAusgelöst, wenn alle Fenster geschlossen sind und sich die Anwendung beenden wird. Ein Aufruf von event.preventDefault() verhindert das Standardverhalten, welches die Anwendung schließt.
Schau dir die Beschreibung/Dokumentation des window-all-closed Events an um die Unterschiede zwischen dem will-quit und dem window-all-closed Event zu verstehen.
Hinweis: Wenn die Anwendung unter Windows beendet wird, weil das System heruntergefahren oder neu gestartet wird oder der Benutzer sich abmeldet, wird dieses Event nicht ausgelöst.
\nKehrt zurück:
\nevent EventexitCode IntegerWird ausgelöst wenn die App beendet wird.
\nHinweis: Wenn die Anwendung unter Windows beendet wird, weil das System heruntergefahren oder neu gestartet wird oder der Benutzer sich abmeldet, wird dieses Event nicht ausgelöst.
\nKehrt zurück:
\nevent Eventpath StringWird ausgelöst wenn der Nutzer versucht eine Datei mit der App zu öffnen. The open-file Event wird auch ausgelöst wenn die App bereits offen ist und das Betriebssystem die App nochmal zum Öffnen einer Datei benutzen will. open-file wird auch ausgelöst wenn eine Datei auf das Dock-Icon der App gezogen wird (macOS) und die App noch nicht gestartet ist. Behandle das open-file Event so früh wie möglich in deiner App um diesen Fall zu berücksichtigen (Also definitiv bevor das ready Event ausgelöst wird).
Du musst event.preventDefault() aufrufen um dieses Event selbst zu nutzen.
In Windows musst du process.argv (im Main-Prozess) parsen, um den Dateipfad zu erhalten.
Kehrt zurück:
\nevent Eventurl StringWird ausgelöst wenn der Nutzer versucht, eine URL mit der App zu öffnen. Your application's Info.plist file must define the URL scheme within the CFBundleURLTypes key, and set NSPrincipalClass to AtomApplication.
Du musst event.preventDefault() aufrufen um dieses Event selbst zu nutzen.
Kehrt zurück:
\nevent EventhasVisibleWindows BooleanWird ausgelöst wenn die App aktiviert wird. Eine ganze Menge an Aktionen können dieses Event auslösen. So zum Beispiel das Starten der App zum ersten mal als solches, eine Wiederbenutzung der App während sie bereits läuft oder einfach ein Klick auf das Dock oder Tastbar Icon der App.
\nKehrt zurück:
\nevent EventEmitted when mac application become active. Difference from activate event is that did-become-active is emitted every time the app becomes active, not only when Dock icon is clicked or application is re-launched.
Kehrt zurück:
\nevent Eventtype String - Ein string zum identifizieren einer Aktivität. Maped auf NSUserActivity.activityType.userInfo Object - Enthält den app-spezifischen Zustand, der von einer Aktivität auf einem anderen Gerät gespeichert wurde.details ObjektwebpageURL String (optional) - A string identifying the URL of the webpage accessed by the activity on another device, if available.Wird während Handoff ausgelöst, wenn eine Aktivität von einem anderen Gerät wieder aufgenommen werden soll. Du solltest event.preventDefault() aufrufen wenn du dieses Event verwenden willst.
Eine Benutzeraktivität kann nur in einer App fortgesetzt werden, die die gleiche Entwicklerteam-ID als die Quell-App der Aktivität hat und den Typ der Aktivität unterstützt. Unterstützte Aktivitätstypen sind spezifiziert in Info.plist unter dem NSUserActivityTypes Schlüssel.
Kehrt zurück:
\nevent Eventtype String - Ein string zum identifizieren einer Aktivität. Maped auf NSUserActivity.activityType.Wird während Handoff ausgelöst, bevor eine Aktivität von einem anderen Gerät wieder aufgenommen werden soll. Du solltest event.preventDefault() aufrufen wenn du dieses Event verwenden willst.
Kehrt zurück:
\nevent Eventtype String - Ein string zum identifizieren einer Aktivität. Maped auf NSUserActivity.activityType.error String - Ein String mit der lokalisierten Beschreibung des Fehlers.Wird während Handoff ausgelöst, wenn eine Aktivität von einem anderen Gerät nicht wieder aufgenommen werden kann.
\nKehrt zurück:
\nevent Eventtype String - Ein string zum identifizieren einer Aktivität. Maped auf NSUserActivity.activityType.userInfo unknown - Enthält app-spezifischen Zustand, der von der Aktivität gespeichert wird.Wird während Handoff ausgelöst, wenn eine Aktivität von diesem Gerät auf einem anderen Gerät erfolgreich fortgesetzt wurde.
\nKehrt zurück:
\nevent Eventtype String - Ein string zum identifizieren einer Aktivität. Maped auf NSUserActivity.activityType.userInfo unknown - Enthält app-spezifischen Zustand, der von der Aktivität gespeichert wird.Wird ausgelöst wenn Handoff auf einem anderen Gerät fortgesetzt wird. Wenn Sie den zu übertragenden Status aktualisieren müssen, sollten Sie event.preventDefault() sofort aufrufen, ein neues userInfo-Wörterbuch erstellen und app.updateCurrentActivity() zeitnah aufrufen. Andernfalls wird die Operation fehlschlagen und Continue-Activity-error wird aufgerufen.
Kehrt zurück:
\nevent EventEmittiert, wenn der Benutzer auf die neue Registerkarte macOS mit systemeigenem MacOS klickt. The new tab button is only visible if the current BrowserWindow has a tabbingIdentifier
Kehrt zurück:
\nevent Eventwindow BrowserWindowWird ausgegeben, wenn ein browserWindow ausgeblendet wird.
\nKehrt zurück:
\nevent Eventwindow BrowserWindowEmittiert wenn ein browserWindow in den Fokus kommt.
\nKehrt zurück:
\nevent Eventwindow BrowserWindowEmittiert wenn ein neues browserWindow erstellt wird.
\nKehrt zurück:
\nevent EventwebContents WebContentsEmittiert wen ein neues webContents erstellt wird.
\nKehrt zurück:
\nevent EventwebContents WebContentsurl Stringerror String - Der error codecertificate Certificatecallback FunctionisTrusted Boolean - Gibt an ob das Zertifikat als vertrauenswürdig angesehen werden sollisMainFrame BooleanEmittiert wenn die Verifizierung des certificate für die url fehlschlägt, um dem Zertifikat dennoch zu vertrauen müssen die das normale Verhalten abschalten mit event.preventDefault() und callback(true) aufrufen.
const { app } = require('electron')\n\napp.on('certificate-error', (event, webContents, url, error, certificate, callback) => {\n if (url === 'https://github.com') {\n // Verification logic.\n event.preventDefault()\n callback(true)\n } else {\n callback(false)\n }\n})\nKehrt zurück:
\nevent EventwebContents WebContentsurl URLcertificateList Certificate[]callback Functioncertificate Certificate (optional)Emittiert wenn ein Client Zertifikat angefordert wird.
\nDie url entspricht dem Navigationseintrag, der das Client-Zertifikat anfordert und Callback kann mit einem Eintrag aufgerufen werden, der aus der Liste gefiltert wird. Die Verwendung von event.preventDefault() verhindert, dass die App das erste Zertifikat aus dem Store verwendet.
const { app } = require('electron')\n\napp.on('select-client-certificate', (event, webContents, url, list, callback) => {\n event.preventDefault()\n callback(list[0])\n})\nKehrt zurück:
\nevent EventwebContents WebContentsauthenticationResponseDetails Objekturl URLauthInfo ObjektisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (optional)password String (optional)Wird ausgelöst wenn webContents grundlegende Authentifizierung durchführen will.
Standardmäßig werden alle Authentifizierungen abgebrochen. To override this you should prevent the default behavior with event.preventDefault() and call callback(username, password) with the credentials.
const { app } = require('electron')\n\napp.on('login', (event, webContents, details, authInfo, callback) => {\n event.preventDefault()\n callback('username', 'secret')\n})\nIf callback is called without a username or password, the authentication request will be cancelled and the authentication error will be returned to the page.
Emitted whenever there is a GPU info update.
\nKehrt zurück:
\nevent Eventkilled BooleanEmitted when the GPU process crashes or is killed.
\nDeprecated: This event is superceded by the child-process-gone event which contains more information about why the child process disappeared. Ist es nicht immer, wenn es abgestürzt ist. Der Boolesche Wert killed kann ersetzt werden durch Überprüfung von reason === 'killed', wenn Sie zu diesem Ereignis wechseln.
Kehrt zurück:
\nevent EventwebContents WebContentskilled BooleanEmitted when the renderer process of webContents crashes or is killed.
Deprecated: This event is superceded by the render-process-gone event which contains more information about why the render process disappeared. Ist es nicht immer, wenn es abgestürzt ist. Der Boolesche Wert killed kann ersetzt werden durch Überprüfung von reason === 'killed', wenn Sie zu diesem Ereignis wechseln.
Kehrt zurück:
\nevent EventwebContents WebContentsdetails Objektreason String - The reason the render process is gone. Mögliche werte:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Integer - The exit code of the process, unless reason is launch-failed, in which case exitCode will be a platform-specific launch failure error code.Emitted when the renderer process unexpectedly disappears. This is normally because it was crashed or killed.
\nKehrt zurück:
\nevent Eventdetails ObjektTyp String - Prozess-Typ. Einer der folgenden Werte:UtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownreason String - The reason the child process is gone. Mögliche werte:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Number - The exit code for the process (e.g. status from waitpid if on posix, from GetExitCodeProcess on Windows).serviceName String (optional) - The non-localized name of the process.name String (optional) - The name of the process. Examples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.Emitted when the child process unexpectedly disappears. This is normally because it was crashed or killed. It does not include renderer processes.
\nKehrt zurück:
\nevent EventaccessibilitySupportEnabled Boolean - true when Chrome's accessibility support is enabled, false otherwise.Emitted when Chrome's accessibility support changes. This event fires when assistive technologies, such as screen readers, are enabled or disabled. See https://www.chromium.org/developers/design-documents/accessibility for more details.
\nKehrt zurück:
\nsession SessionEmittiert wenn Electron eine neue Session erstellt.
const { app } = require('electron')\n\napp.on('session-created', (session) => {\n console.log(session)\n})\nKehrt zurück:
\nevent Eventargv String[] - An array of the second instance's command line argumentsworkingDirectory String - The second instance's working directoryThis event will be emitted inside the primary instance of your application when a second instance has been executed and calls app.requestSingleInstanceLock().
argv is an Array of the second instance's command line arguments, and workingDirectory is its current working directory. Usually applications respond to this by making their primary window focused and non-minimized.
Note: If the second instance is started by a different user than the first, the argv array will not include the arguments.
This event is guaranteed to be emitted after the ready event of app gets emitted.
Hinweis: Zusätzliche Kommandozeilenargumente könnten von Chromium hinzugefügt werden, wie --original-process-start-time.
Kehrt zurück:
\nevent EventwebContents WebContentsEmitted when desktopCapturer.getSources() is called in the renderer process of webContents. Calling event.preventDefault() will make it return empty sources.
Das app Objekt enthält die folgenden Methoden:
Hinweis: Manche Methoden sind nur auf spezifischen Betriebssystemen verfügbar und sind dementsprechend gekennzeichnet.
\napp.quit()Versucht sämtliche Fenster zu schließen. Das before-quit Ereignis wird zuerst aufgerufen. Wurden alle Fenster erfolgreich geschlossen, wird das will-quit Ereignis aufgerufen und die Anwendung wird standardmäßig terminiert.
This method guarantees that all beforeunload and unload event handlers are correctly executed. It is possible that a window cancels the quitting by returning false in the beforeunload event handler.
app.exit([exitCode])exitCode Integer (optional)Exits immediately with exitCode. exitCode defaults to 0.
All windows will be closed immediately without asking the user, and the before-quit and will-quit events will not be emitted.
app.relaunch([options])Relaunches the app when current instance exits.
\nBy default, the new instance will use the same working directory and command line arguments with current instance. When args is specified, the args will be passed as command line arguments instead. When execPath is specified, the execPath will be executed for relaunch instead of current app.
Note that this method does not quit the app when executed, you have to call app.quit or app.exit after calling app.relaunch to make the app restart.
When app.relaunch is called for multiple times, multiple instances will be started after current instance exited.
An example of restarting current instance immediately and adding a new command line argument to the new instance:
\nconst { app } = require('electron')\n\napp.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) })\napp.exit(0)\napp.isReady()Gibt Boolean - true zurück, wenn Electron das Initialisieren beendet hat, ansonsten false. See also app.whenReady().
app.whenReady()Returns Promise<void> - fulfilled when Electron is initialized. May be used as a convenient alternative to checking app.isReady() and subscribing to the ready event if the app is not ready yet.
app.focus([options])options Object (optional)steal Boolean macOS - Make the receiver the active app even if another app is currently active.On Linux, focuses on the first visible window. On macOS, makes the application the active app. On Windows, focuses on the application's first window.
\nDu solltest versuchen, die steal Option so selten wie möglich zu verwenden.
app.hide() macOSBlendet alle Anwendungsfenster aus ohne sie zu minimieren.
\napp.show() macOSShows application windows after they were hidden. Does not automatically focus them.
\napp.setAppLogsPath([path])path String (optional) - A custom path for your logs. Must be absolute.Sets or creates a directory your app's logs which can then be manipulated with app.getPath() or app.setPath(pathName, newPath).
Calling app.setAppLogsPath() without a path parameter will result in this directory being set to ~/Library/Logs/YourAppName on macOS, and inside the userData directory on Linux and Windows.
app.getAppPath()Returns String - The current application directory.
app.getPath(name)name String - You can request the following paths by the name:home Des Benutzers Home Verzeichnis.appData Per-user application data directory, which by default points to:%APPDATA% in Windows$XDG_CONFIG_HOME oder ~/.config in Linux~/Library/Application Support in macOSuserData The directory for storing your app's configuration files, which by default it is the appData directory appended with your app's name.Cachetemp Temporäres Verzeichnis.exe Die aktuell ausführbare Datei.module Die libchromiumcontent Bibliothek.desktop Das Desktop Verzeichnis des aktuellen Benuters.documents Directory for a user's \"My Documents\".downloads \"Downloads\" Verzeichnis des aktuellen Benutzers.music Musik Verzeichnis des aktuellen Benutzers.pictures Bilder Verzeichnis des aktuellen Benutzers.videos Filme Verzeichnis des aktuellen Benutzers.recent Directory for the user's recent files (Windows only).logs Verzeichnis für die Logfiles deiner App.crashDumps Directory where crash dumps are stored.Returns String - A path to a special directory or file associated with name. On failure, an Error is thrown.
If app.getPath('logs') is called without called app.setAppLogsPath() being called first, a default log directory will be created equivalent to calling app.setAppLogsPath() without a path parameter.
app.getFileIcon(path[, options])path Stringoptions Object (optional)size Stringsmall - 16x16normal - 32x32large - 48x48 in Linux, 32x32 in Windows, wird in macOS nicht unterstützt.Returns Promise<NativeImage> - fulfilled with the app's icon, which is a NativeImage.
Ruft das zugeordnete Symbol eines Pfades ab.
\nIn Windows gibt es zwei arten von Icons:
\n.mp3, .png, usw..exe, .dll, .ico.On Linux and macOS, icons depend on the application associated with file mime type.
\napp.setPath(name, path)name Zeichenfolgepath StringOverrides the path to a special directory or file associated with name. If the path specifies a directory that does not exist, an Error is thrown. In that case, the directory should be created with fs.mkdirSync or similar.
You can only override paths of a name defined in app.getPath.
By default, web pages' cookies and caches will be stored under the userData directory. If you want to change this location, you have to override the userData path before the ready event of the app module is emitted.
app.getVersion()Returns String - The version of the loaded application. If no version is found in the application's package.json file, the version of the current bundle or executable is returned.
app.getName()Returns String - The current application's name, which is the name in the application's package.json file.
Usually the name field of package.json is a short lowercase name, according to the npm modules spec. You should usually also specify a productName field, which is your application's full capitalized name, and which will be preferred over name by Electron.
app.setName(name)name ZeichenfolgeÜberschreibt den Namen der aktuellen Anwendung.
\nNote: This function overrides the name used internally by Electron; it does not affect the name that the OS uses.
\napp.getLocale()Returns String - The current application locale, fetched using Chromium's l10n_util library. Possible return values are documented here.
To set the locale, you'll want to use a command line switch at app startup, which may be found here.
\nNote: When distributing your packaged app, you have to also ship the locales folder.
Note: On Windows, you have to call it after the ready events gets emitted.
app.getLocaleCountryCode()Returns String - User operating system's locale two-letter ISO 3166 country code. The value is taken from native OS APIs.
Note: When unable to detect locale country code, it returns empty string.
\napp.addRecentDocument(path) macOS Windowspath StringAdds path to the recent documents list.
This list is managed by the OS. On Windows, you can visit the list from the task bar, and on macOS, you can visit it from dock menu.
\napp.clearRecentDocuments() macOS WindowsLeere die zuletzt verwendete Dokumenten Liste.
\napp.setAsDefaultProtocolClient(protocol[, path, args])protocol String - The name of your protocol, without ://. For example, if you want your app to handle electron:// links, call this method with electron as the parameter.path String (optional) Windows - The path to the Electron executable. Standardwert ist process.execPathargs String Windows - Arguments passed to the executable. Defaults to an empty arrayReturns Boolean - Whether the call succeeded.
Sets the current executable as the default handler for a protocol (aka URI scheme). It allows you to integrate your app deeper into the operating system. Once registered, all links with your-protocol:// will be opened with the current executable. The whole link, including protocol, will be passed to your application as a parameter.
Note: On macOS, you can only register protocols that have been added to your app's info.plist, which cannot be modified at runtime. However, you can change the file during build time via Electron Forge, Electron Packager, or by editing info.plist with a text editor. Please refer to Apple's documentation for details.
Note: In a Windows Store environment (when packaged as an appx) this API will return true for all calls but the registry key it sets won't be accessible by other applications. In order to register your Windows Store application as a default protocol handler you must declare the protocol in your manifest.
The API uses the Windows Registry and LSSetDefaultHandlerForURLScheme internally.
app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windowsprotocol String - The name of your protocol, without ://.path String (optional) Windows - Defaults to process.execPathargs String Windows - Defaults to an empty arrayReturns Boolean - Whether the call succeeded.
This method checks if the current executable as the default handler for a protocol (aka URI scheme). If so, it will remove the app as the default handler.
\napp.isDefaultProtocolClient(protocol[, path, args])protocol String - The name of your protocol, without ://.path String (optional) Windows - Defaults to process.execPathargs String Windows - Defaults to an empty arrayReturns Boolean - Whether the current executable is the default handler for a protocol (aka URI scheme).
Note: On macOS, you can use this method to check if the app has been registered as the default protocol handler for a protocol. You can also verify this by checking ~/Library/Preferences/com.apple.LaunchServices.plist on the macOS machine. Please refer to Apple's documentation for details.
The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internally.
app.getApplicationNameForProtocol(url)url String - a URL with the protocol name to check. Unlike the other methods in this family, this accepts an entire URL, including :// at a minimum (e.g. https://).Returns String - Name of the application handling the protocol, or an empty string if there is no handler. For instance, if Electron is the default handler of the URL, this could be Electron on Windows and Mac. However, don't rely on the precise format which is not guaranteed to remain unchanged. Expect a different format on Linux, possibly with a .desktop suffix.
This method returns the application name of the default handler for the protocol (aka URI scheme) of a URL.
\napp.getApplicationInfoForProtocol(url) macOS Windowsurl String - a URL with the protocol name to check. Unlike the other methods in this family, this accepts an entire URL, including :// at a minimum (e.g. https://).Returns Promise<Object> - Resolve with an object containing the following:
icon NativeImage - the display icon of the app handling the protocol.path String - installation path of the app handling the protocol.name String - display name of the app handling the protocol.This method returns a promise that contains the application name, icon and path of the default handler for the protocol (aka URI scheme) of a URL.
\napp.setUserTasks(tasks) Windowstasks Task[] - Array mit Task ObjektenAdds tasks to the Tasks category of the Jump List on Windows.
tasks Ein Array mit Task Objekten.
Returns Boolean - Whether the call succeeded.
Hinweis: Wenn du die Jump List weiter anpassen möchtest, dann verwende statt dessen die app.setJumpList(categories).
app.getJumpListSettings() WindowsGibt das Object zurück:
minItems Integer - The minimum number of items that will be shown in the Jump List (for a more detailed description of this value see the MSDN docs).removedItems JumpListItem[] - Array of JumpListItem objects that correspond to items that the user has explicitly removed from custom categories in the Jump List. These items must not be re-added to the Jump List in the next call to app.setJumpList(), Windows will not display any custom category that contains any of the removed items.app.setJumpList(categories) Windowscategories JumpListCategory[] | null - Array of JumpListCategory objects.Sets or removes a custom Jump List for the application, and returns one of the following strings:
\nok - Nichts ist schief gelaufen.error - One or more errors occurred, enable runtime logging to figure out the likely cause.invalidSeparatorError - An attempt was made to add a separator to a custom category in the Jump List. Separators are only allowed in the standard Tasks category.fileTypeRegistrationError - An attempt was made to add a file link to the Jump List for a file type the app isn't registered to handle.customCategoryAccessDeniedError - Custom categories can't be added to the Jump List due to user privacy or group policy settings.If categories is null the previously set custom Jump List (if any) will be replaced by the standard Jump List for the app (managed by Windows).
Anmerkung: Wenn eine JumpListCategoryObjekt nie den Typ nie den <code>Namen hat Die eingestellte Funktion von seinem Typ ist dann als <code>taskswahrgenommen. Wenn die Eigenschaft name gesetzt ist, aber die Eigenschaft type weggelassen wird, dann wird angenommen, dass die Eigenschaft type custom ist.
Note: Users can remove items from custom categories, and Windows will not allow a removed item to be added back into a custom category until after the next successful call to app.setJumpList(categories). Any attempt to re-add a removed item to a custom category earlier than that will result in the entire custom category being omitted from the Jump List. The list of removed items can be obtained using app.getJumpListSettings().
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
Hier ist ein einfaches Beispiel, wie man eine eigene Jump List anlegt:
\nconst { app } = require('electron')\n\napp.setJumpList([\n {\n type: 'custom',\n name: 'Recent Projects',\n items: [\n { type: 'file', path: 'C:\\\\Projects\\\\project1.proj' },\n { type: 'file', path: 'C:\\\\Projects\\\\project2.proj' }\n ]\n },\n { // has a name so `type` is assumed to be \"custom\"\n name: 'Tools',\n items: [\n {\n type: 'task',\n title: 'Tool A',\n program: process.execPath,\n args: '--run-tool-a',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool A'\n },\n {\n type: 'task',\n title: 'Tool B',\n program: process.execPath,\n args: '--run-tool-b',\n icon: process.execPath,\n iconIndex: 0,\n description: 'Runs Tool B'\n }\n ]\n },\n { type: 'frequent' },\n { // has no name and no type so `type` is assumed to be \"tasks\"\n items: [\n {\n type: 'task',\n title: 'New Project',\n program: process.execPath,\n args: '--new-project',\n description: 'Create a new project.'\n },\n { type: 'separator' },\n {\n type: 'task',\n title: 'Recover Project',\n program: process.execPath,\n args: '--recover-project',\n description: 'Recover Project'\n }\n ]\n }\n])\napp.requestSingleInstanceLock()Gibt Boolean zurück
The return value of this method indicates whether or not this instance of your application successfully obtained the lock. If it failed to obtain the lock, you can assume that another instance of your application is already running with the lock and exit immediately.
\nI.e. This method returns true if your process is the primary instance of your application and your app should continue loading. It returns false if your process should immediately quit as it has sent its parameters to another instance that has already acquired the lock.
On macOS, the system enforces single instance automatically when users try to open a second instance of your app in Finder, and the open-file and open-url events will be emitted for that. However when users start your app in command line, the system's single instance mechanism will be bypassed, and you have to use this method to ensure single instance.
An example of activating the window of primary instance when a second instance starts:
\nconst { app } = require('electron')\nlet myWindow = null\n\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Someone tried to run a second instance, we should focus our window.\n if (myWindow) {\n if (myWindow.isMinimized()) myWindow.restore()\n myWindow.focus()\n }\n })\n\n // Create myWindow, load the rest of the app, etc...\n app.whenReady().then(() => {\n myWindow = createWindow()\n })\n}\napp.hasSingleInstanceLock()Gibt Boolean zurück
This method returns whether or not this instance of your app is currently holding the single instance lock. You can request the lock with app.requestSingleInstanceLock() and release with app.releaseSingleInstanceLock()
app.releaseSingleInstanceLock()Releases all locks that were created by requestSingleInstanceLock. This will allow multiple instances of the application to once again run side by side.
app.setUserActivity(type, userInfo[, webpageURL]) macOStype String - Uniquely identifies the activity. Maped auf NSUserActivity.activityType.userInfo any - App-specific state to store for use by another device.webpageURL String (optional) - The webpage to load in a browser if no suitable app is installed on the resuming device. The scheme must be http or https.Creates an NSUserActivity and sets it as the current activity. The activity is eligible for Handoff to another device afterward.
app.getCurrentActivityType() macOSReturns String - Typ der aktuell laufenden Aktivität.
app.invalidateCurrentActivity() macOSInvalidates the current Handoff user activity.
\napp.resignCurrentActivity() macOSMarks the current Handoff user activity as inactive without invalidating it.
\napp.updateCurrentActivity(type, userInfo) macOStype String - Uniquely identifies the activity. Maped auf NSUserActivity.activityType.userInfo any - App-specific state to store for use by another device.Updates the current activity if its type matches type, merging the entries from userInfo into its current userInfo dictionary.
app.setAppUserModelId(id) Windowsid ZeichenfolgeChanges the Application User Model ID to id.
app.setActivationPolicy(policy) macOSpolicy String - Can be 'regular', 'accessory', or 'prohibited'.Sets the activation policy for a given app.
\nActivation policy types:
\napp.importCertificate(options, callback) Linuxoptions Objektcertificate String - Pfad zur pkcs12 Datei.password String - Passphrase des Zertifikats.callback Functionresult Integer - Resultat des Imports.Imports the certificate in pkcs12 format into the platform certificate store. callback is called with the result of import operation, a value of 0 indicates success while any other value indicates failure according to Chromium net_error_list.
app.configureHostResolver(options)options ObjektenableBuiltInResolver Boolean (optional) - Whether the built-in host resolver is used in preference to getaddrinfo. When enabled, the built-in resolver will attempt to use the system's DNS settings to do DNS lookups itself. Enabled by default on macOS, disabled by default on Windows and Linux.secureDnsMode String (optional) - Can be \"off\", \"automatic\" or \"secure\". Configures the DNS-over-HTTP mode. When \"off\", no DoH lookups will be performed. When \"automatic\", DoH lookups will be performed first if DoH is available, and insecure DNS lookups will be performed as a fallback. When \"secure\", only DoH lookups will be performed. Defaults to \"automatic\".secureDnsServers String[] (optional) - A list of DNS-over-HTTP server templates. See RFC8484 § 3 for details on the template format. Most servers support the POST method; the template for such servers is simply a URI. Note that for some DNS providers, the resolver will automatically upgrade to DoH unless DoH is explicitly disabled, even if there are no DoH servers provided in this list.enableAdditionalDnsQueryTypes Boolean (optional) - Controls whether additional DNS query types, e.g. HTTPS (DNS type 65) will be allowed besides the traditional A and AAAA queries when a request is being made via insecure DNS. Has no effect on Secure DNS which always allows additional types. Standard ist true.Configures host resolution (DNS and DNS-over-HTTPS). By default, the following resolvers will be used, in order:
\ngetaddrinfo).This can be configured to either restrict usage of non-encrypted DNS (secureDnsMode: \"secure\"), or disable DNS-over-HTTPS (secureDnsMode: \"off\"). It is also possible to enable or disable the built-in resolver.
To disable insecure DNS, you can specify a secureDnsMode of \"secure\". If you do so, you should make sure to provide a list of DNS-over-HTTPS servers to use, in case the user's DNS configuration does not include a provider that supports DoH.
app.configureHostResolver({\n secureDnsMode: 'secure',\n secureDnsServers: [\n 'https://cloudflare-dns.com/dns-query'\n ]\n})\nThis API must be called after the ready event is emitted.
app.disableHardwareAcceleration()Schaltet die Hardware Beschleunigung für die aktuelle App ab.
\nDiese Methode kann nur vor dem Start der App aufgerufen werden.
\napp.disableDomainBlockingFor3DAPIs()By default, Chromium disables 3D APIs (e.g. WebGL) until restart on a per domain basis if the GPU processes crashes too frequently. This function disables that behavior.
\nDiese Methode kann nur vor dem Start der App aufgerufen werden.
\napp.getAppMetrics()Returns ProcessMetric[]: Array of ProcessMetric objects that correspond to memory and CPU usage statistics of all the processes associated with the app.
app.getGPUFeatureStatus()Returns GPUFeatureStatus - The Graphics Feature Status from chrome://gpu/.
Note: This information is only usable after the gpu-info-update event is emitted.
app.getGPUInfo(infoType)infoType String - Kann basic oder complete sein.Gibt das Promise<unknown> zurück
For infoType equal to complete: Promise is fulfilled with Object containing all the GPU Information as in chromium's GPUInfo object. This includes the version and driver information that's shown on chrome://gpu page.
For infoType equal to basic: Promise is fulfilled with Object containing fewer attributes than when requested with complete. Here's an example of basic response:
{\n auxAttributes:\n {\n amdSwitchable: true,\n canSupportThreadedTextureMailbox: false,\n directComposition: false,\n directRendering: true,\n glResetNotificationStrategy: 0,\n inProcessGpu: true,\n initializationTime: 0,\n jpegDecodeAcceleratorSupported: false,\n optimus: false,\n passthroughCmdDecoder: false,\n sandboxed: false,\n softwareRendering: false,\n supportsOverlays: false,\n videoDecodeAcceleratorFlags: 0\n },\n gpuDevice:\n [{ active: true, deviceId: 26657, vendorId: 4098 },\n { active: false, deviceId: 3366, vendorId: 32902 }],\n machineModelName: 'MacBookPro',\n machineModelVersion: '11.5'\n}\nUsing basic should be preferred if only basic information like vendorId or driverId is needed.
app.setBadgeCount([count]) Linux macOScount Integer (optional) - If a value is provided, set the badge to the provided value otherwise, on macOS, display a plain white dot (e.g. unknown number of notifications). On Linux, if a value is not provided the badge will not display.Returns Boolean - Whether the call succeeded.
Sets the counter badge for current app. Setting the count to 0 will hide the badge.
On macOS, it shows on the dock icon. On Linux, it only works for Unity launcher.
\nNote: Unity launcher requires a .desktop file to work. For more information, please read the Unity integration documentation.
app.getBadgeCount() Linux macOSReturns Integer - The current value displayed in the counter badge.
app.isUnityRunning() LinuxReturns Boolean - Whether the current desktop environment is Unity launcher.
app.getLoginItemSettings([options]) macOS Windowsoptions Object (optional)If you provided path and args options to app.setLoginItemSettings, then you need to pass the same arguments here for openAtLogin to be set correctly.
Gibt das Object zurück:
openAtLogin Boolean - true wenn die App definiert wurde, sich bei Login zu öffnen.openAsHidden Boolean macOS - true if the app is set to open as hidden at login. This setting is not available on MAS builds.wasOpenedAtLogin Boolean macOS - true if the app was opened at login automatically. This setting is not available on MAS builds.wasOpenedAsHidden Boolean macOS - true if the app was opened as a hidden login item. This indicates that the app should not open any windows at startup. This setting is not available on MAS builds.restoreState Boolean macOS - true if the app was opened as a login item that should restore the state from the previous session. This indicates that the app should restore the windows that were open the last time the app was closed. This setting is not available on MAS builds.executableWillLaunchAtLogin Boolean Windows - true if app is set to open at login and its run key is not deactivated. This differs from openAtLogin as it ignores the args option, this property will be true if the given executable would be launched at login with any arguments.launchItems Object[] Windowsname String Windows - name value of a registry entry.path String Windows - The executable to an app that corresponds to a registry entry.args String[] Windows - the command-line arguments to pass to the executable.scope String Windows - one of user or machine. Indicates whether the registry entry is under HKEY_CURRENT USER or HKEY_LOCAL_MACHINE.enabled Boolean Windows - true if the app registry key is startup approved and therefore shows as enabled in Task Manager and Windows settings.app.setLoginItemSettings(settings) macOS Windowssettings ObjectopenAtLogin Boolean (optional) - true to open the app at login, false to remove the app as a login item. Defaults to false.openAsHidden Boolean (optional) macOS - true to open the app as hidden. Defaults to false. The user can edit this setting from the System Preferences so app.getLoginItemSettings().wasOpenedAsHidden should be checked when the app is opened to know the current value. This setting is not available on MAS builds.path String (optional) Windows - The executable to launch at login. Defaults to process.execPath.args String Windows - The command-line arguments to pass to the executable. Defaults to an empty array. Take care to wrap paths in quotes.enabled Boolean (optional) Windows - true will change the startup approved registry key and enable / disable the App in Task Manager and Windows Settings. Defaults to true.name String (optional) Windows - value name to write into registry. Defaults to the app's AppUserModelId(). Set the app's login item settings.To work with Electron's autoUpdater on Windows, which uses Squirrel, you'll want to set the launch path to Update.exe, and pass arguments that specify your application name. Ein Beispiel:
const appFolder = path.dirname(process.execPath)\nconst updateExe = path.resolve(appFolder, '..', 'Update.exe')\nconst exeName = path.basename(process.execPath)\n\napp.setLoginItemSettings({\n openAtLogin: true,\n path: updateExe,\n args: [\n '--processStart', `\"${exeName}\"`,\n '--process-start-args', `\"--hidden\"`\n ]\n})\napp.isAccessibilitySupportEnabled() macOS WindowsReturns Boolean - true if Chrome's accessibility support is enabled, false otherwise. This API will return true if the use of assistive technologies, such as screen readers, has been detected. See https://www.chromium.org/developers/design-documents/accessibility for more details.
app.setAccessibilitySupportEnabled(enabled) macOS Windowsenabled Boolean - Enable or disable accessibility tree renderingManually enables Chrome's accessibility support, allowing to expose accessibility switch to users in application settings. See Chromium's accessibility docs for more details. Disabled by default.
\nThis API must be called after the ready event is emitted.
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
\napp.showAboutPanel()Show the app's about panel options. These options can be overridden with app.setAboutPanelOptions(options).
app.setAboutPanelOptions(options)options ObjektapplicationName String (optional) - Der Name der App.applicationVersion String (optional) - Die Version der App.copyright String (optional) - Copyright Information.version String (optional) macOS - The app's build version number.credits String (optional) macOS Windows - Credit information.authors String Linux - List of app authors.website String (optional) Linux - The app's website.iconPath String (optional) Linux Windows - Path to the app's icon in a JPEG or PNG file format. On Linux, will be shown as 64x64 pixels while retaining aspect ratio.Set the about panel options. This will override the values defined in the app's .plist file on macOS. See the Apple docs for more details. On Linux, values must be set in order to be shown; there are no defaults.
If you do not set credits but still wish to surface them in your app, AppKit will look for a file named \"Credits.html\", \"Credits.rtf\", and \"Credits.rtfd\", in that order, in the bundle returned by the NSBundle class method main. The first file found is used, and if none is found, the info area is left blank. See Apple documentation for more information.
app.isEmojiPanelSupported()Returns Boolean - whether or not the current OS version allows for native emoji pickers.
app.showEmojiPanel() macOS WindowsShow the platform's native emoji picker.
\napp.startAccessingSecurityScopedResource(bookmarkData) masbookmarkData String - The base64 encoded security scoped bookmark data returned by the dialog.showOpenDialog or dialog.showSaveDialog methods.Returns Function - This function must be called once you have finished accessing the security scoped file. If you do not remember to stop accessing the bookmark, kernel resources will be leaked and your app will lose its ability to reach outside the sandbox completely, until your app is restarted.
// Start accessing the file.\nconst stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)\n// You can now access the file outside of the sandbox 🎉\n\n// Remember to stop accessing the file once you've finished with it.\nstopAccessingSecurityScopedResource()\nStart accessing a security scoped resource. With this method Electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See Apple's documentation for a description of how this system works.
\napp.enableSandbox()Aktiviert den vollen Sandbox-Modus auf der App. This means that all renderers will be launched sandboxed, regardless of the value of the sandbox flag in WebPreferences.
Diese Methode kann nur vor dem Start der App aufgerufen werden.
\napp.isInApplicationsFolder() macOSReturns Boolean - Whether the application is currently running from the systems Application folder. Use in combination with app.moveToApplicationsFolder()
app.moveToApplicationsFolder([options]) macOSoptions Object (optional)conflictHandler Function\\conflictType String - The type of move conflict encountered by the handler; can be exists or existsAndRunning, where exists means that an app of the same name is present in the Applications directory and existsAndRunning means both that it exists and that it's presently running.Returns Boolean - Whether the move was successful. Please note that if the move is successful, your application will quit and relaunch.
No confirmation dialog will be presented by default. If you wish to allow the user to confirm the operation, you may do so using the dialog API.
NOTE: This method throws errors if anything other than the user causes the move to fail. For instance if the user cancels the authorization dialog, this method returns false. If we fail to perform the copy, then this method will throw an error. The message in the error should be informative and tell you exactly what went wrong.
\nBy default, if an app of the same name as the one being moved exists in the Applications directory and is not running, the existing app will be trashed and the active app moved into its place. If it is running, the pre-existing running app will assume focus and the previously active app will quit itself. This behavior can be changed by providing the optional conflict handler, where the boolean returned by the handler determines whether or not the move conflict is resolved with default behavior. i.e. returning false will ensure no further action is taken, returning true will result in the default behavior and the method continuing.
Ein Beispiel:
\napp.moveToApplicationsFolder({\n conflictHandler: (conflictType) => {\n if (conflictType === 'exists') {\n return dialog.showMessageBoxSync({\n type: 'question',\n buttons: ['Halt Move', 'Continue Move'],\n defaultId: 0,\n message: 'An app of this name already exists'\n }) === 1\n }\n }\n})\nWould mean that if an app already exists in the user directory, if the user chooses to 'Continue Move' then the function would continue with its default behavior and the existing app will be trashed and the active app moved into its place.
\napp.isSecureKeyboardEntryEnabled() macOSReturns Boolean - whether Secure Keyboard Entry is enabled.
By default this API will return false.
app.setSecureKeyboardEntryEnabled(enabled) macOSenabled Boolean - Enable or disable Secure Keyboard EntrySet the Secure Keyboard Entry is enabled in your application.
By using this API, important information such as password and other sensitive information can be prevented from being intercepted by other processes.
\nSee Apple's documentation for more details.
\nNote: Enable Secure Keyboard Entry only when it is needed and disable it when it is no longer needed.
app.accessibilitySupportEnabled macOS WindowsA Boolean property that's true if Chrome's accessibility support is enabled, false otherwise. This property will be true if the use of assistive technologies, such as screen readers, has been detected. Setting this property to true manually enables Chrome's accessibility support, allowing developers to expose accessibility switch to users in application settings.
See Chromium's accessibility docs for more details. Disabled by default.
\nThis API must be called after the ready event is emitted.
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
\napp.applicationMenuA Menu | null property that returns Menu if one has been set and null otherwise. Users can pass a Menu to set this property.
app.badgeCount Linux macOSAn Integer property that returns the badge count for current app. Setting the count to 0 will hide the badge.
On macOS, setting this with any nonzero integer shows on the dock icon. On Linux, this property only works for Unity launcher.
\nNote: Unity launcher requires a .desktop file to work. For more information, please read the Unity integration documentation.
Note: On macOS, you need to ensure that your application has the permission to display notifications for this property to take effect.
\napp.commandLine ReadonlyA CommandLine object that allows you to read and manipulate the command line arguments that Chromium uses.
app.dock macOS ReadonlyA Dock | undefined object that allows you to perform actions on your app icon in the user's dock on macOS.
app.isPackaged ReadonlyEine Boolean Eigenschaft, die true zurückgegeben, wenn die App gepackt ist, ansonsten false. Für viele Apps kann diese Eigenschaft verwendet werden, um Entwicklungs- und Produktionsumgebungen zu unterscheiden.
app.nameA String property that indicates the current application's name, which is the name in the application's package.json file.
Usually the name field of package.json is a short lowercase name, according to the npm modules spec. You should usually also specify a productName field, which is your application's full capitalized name, and which will be preferred over name by Electron.
app.userAgentFallbackA String which is the user agent string Electron will use as a global fallback.
This is the user agent that will be used when no user agent is set at the webContents or session level. It is useful for ensuring that your entire app has the same user agent. Set to a custom value as early as possible in your app's initialization to ensure that your overridden value is used.
app.runningUnderRosettaTranslation macOS Readonly DeprecatedA Boolean which when true indicates that the app is currently running under the Rosetta Translator Environment.
You can use this property to prompt users to download the arm64 version of your application when they are running the x64 version under Rosetta incorrectly.
\nDeprecated: This property is superceded by the runningUnderARM64Translation property which detects when the app is being translated to ARM64 in both macOS and Windows.
app.runningUnderARM64Translation Readonly macOS WindowsA Boolean which when true indicates that the app is currently running under an ARM64 translator (like the macOS Rosetta Translator Environment or Windows WOW).
You can use this property to prompt users to download the arm64 version of your application when they are running the x64 version under Rosetta incorrectly.
", "title": "app", "description": "Kontrolliere den Ereignisverlauf deiner Anwendung." }, "/docs/tutorial/application-debugging": { "locale": "de-DE", "slug": "application-debugging", "href": "/docs/tutorial/application-debugging", "crowdinFileId": "256175", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/application-debugging.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Wann auch immer deine Electron App sich nicht so verhält wie gewünscht, dann stehen dir eine Vielzahl von Debugging-Tools zur Verfügung um Fehler im Code, einen Flaschenhals für die Pervormance oder Möglichkeiten zur Optimierung zu finden.
\nDas umfassendste Tool zum Debuggen individueller Render-Pozesse ist das Chromium Developer Toolset. Das Toolset steht zur Verfügung in allen Render-Prozessen, inklusive Instanzen von BrowserWindow, BrowserView und WebView. Du kannst diese programmatisch öffnen durch Aufruf der openDevTools() API auf webContents der Instanz:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.webContents.openDevTools()\nGoogle bietet ausgezeichnete Dokumentation für ihre Entwickler-Tools. Wir empfehlen Ihnen, sich mit ihnen vertraut zu machen - sie sind in der Regel ein der leistungsstärksten Werkzeuge in jedem Werkzeuggurt von Electron Developer.
\nDebugging des Main-Prozess ist etwas schwieriger, denn du kannst die Developer Tools hier nicht öffnen. Die Chromium Developer Tools können verwendet werden um Electrons Main-Prozess zu Debuggen dank einer engen Zusammenarbeit zwischen Google / Chrome und Node.js. Du wirst aber vielleicht auch auf Eigenartiges stoßen, so ist require zum Beispiel nicht verfügbar in der Console.
Für weitere Informationen, ließ einfach die Debugging des Main-Prozess Dokumentation.
\nWenn der V8-Kontext abstützen sollte, wird folgende Nachricht in DevTools angezeigt:
\nDevTools was disconnected from the page. Once page is reloaded, DevTools will automatically reconnect.
Chromium Logs können durch das Einstellen der Umgebungsvariabel ELECTRON_ENABLE_LOGGING aktiviert werden. Weitere Informationen könenn in der Dokumentation zu den Umgebungsvariablen gefunden werden.
Alternativ kann dies aber auch durch das Argument --enable-logging im Terminal aktiviert werden. Weitere Informationen hierzu kann in der Dokumentation der Konsolen-Argumente gefunden werden.
To distribute your app with Electron, you need to package and rebrand it. To do this, you can either use specialized tooling or manual approaches.
\nYou can use the following tools to distribute your application:
\n\nThese tools will take care of all the steps you need to take to end up with a distributable Electron application, such as bundling your application, rebranding the executable, and setting the right icons.
\nYou can check the example of how to package your app with electron-forge in the Quick Start guide.
To distribute your app manually, you need to download Electron's prebuilt binaries. Als nächstes sollte der Ordner, der die App beinhaltet, app genannt werden und in das Electron-Resources-Verzeichnis verschoben werden, wie in den unten stehenden Beispielen zu erkennnen ist.
\n\nNOTE: the location of Electron's prebuilt binaries is indicated with
\nelectron/in the examples below.
Unter macOS:
\nelectron/Electron.app/Contents/Resources/app/\n├── package.json\n├── main.js\n└── index.html\nUnter Windows und Linux:
\nelectron/resources/app\n├── package.json\n├── main.js\n└── index.html\nThen execute Electron.app on macOS, electron on Linux, or electron.exe on Windows, and Electron will start as your app. The electron directory will then be your distribution to deliver to users.
Instead of from shipping your app by copying all of its source files, you can package your app into an asar archive to improve the performance of reading files on platforms like Windows, if you are not already using a bundler such as Parcel or Webpack.
\nUm ein asar-Archiv zu nutzen, um den app Ordner zu ersetzen, müssen Sie das Archiv in app.asar umbenennen und, wie unten, in das Resources-Verzeichnis von Electron verschieben. Erst dann wird Electron versuchen das Archiv zu lesen und daraus starten.
Unter macOS:
\nelectron/Electron.app/Contents/Resources/\n└── app.asar\nUnter Windows und Linux:
\nelectron/resources/\n└── app.asar\nYou can find more details on how to use asar in the electron/asar repository.
Nachdem Sie Ihre App in Electron gebündelt haben, sollten Sie Electron umbennen, bevor Sie es an Ihre Nutzer weiterreichen.
\nSie können Electron.app einen beliebigen Namen geben, aber Sie müssen zusätzlich die Felder CFBundleDisplayName, CFBundleIdentifier und CFBundleName in den folgenden Dateien umbenennen:
Electron.app/Contents/Info.plistElectron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plistSie können desweiteren die 'Helper App' von Electron umbenennen um das Auftauchen von Electron Helper im Activity Monitor zu vermeiden. Stellen Sie dabei sicher, dass Sie die ausführbare Datei der 'Helper App' umbenannt haben.
Die Struktur der umbenannten App könnte so aussehen:
\nMyApp.app/Contents\n├── Info.plist\n├── MacOS/\n│ └── MyApp\n└── Frameworks/\n └── MyApp Helper.app\n ├── Info.plist\n └── MacOS/\n └── MyApp Helper\nSie können electron.exe einen beliebigen Namen geben und das Icon der App bzw. weitere Metadaten mit Tools wie rcedit bearbeiten.
Sie können der ausführbaren electron-Datei einen beliebigen Namen geben.
Es ist auch möglich Electron zu rebranden, indem man den Produktnamen ändert und es vom Sourcecode buildet. Um dies zu Tun müssen sie das Buildargument, das zum Produktnamen gehört (electron_product_name = \"IhrProduktName\") in der args.gn Datei setzen und rebuilden.
\n\nAktivieren Sie Apps, um sich automatisch selbst zu aktualisieren.
\n
Prozess: Haupt
\nSiehe auch: Eine detaillierte Anleitung zur Implementierung von Updates in Ihrer Anwendung.
\nautoUpdater ist ein EventEmitter.
Aktuell werden nur macOS und Windows unterstützt. Da es keinen eingebauten auto-updater auf den meisten Linux-Basierenden Betriebssystemen gibt, wird empfohlen, den eingebauten Pakete-Verwalter der Distribution zu verwenden, um die App zu updaten.
\nAußerdem gibt es auf jeder Plattform einige subtile Unterschiede:
\nUnter MacOS basiert das autoUpdater Modul auf Squirrel.Mac, was bedeutet daß keine spezifische Konfiguration vonnöten ist. Für serverseitige Anforderungen können Sie Serverunterstützung lesen. Beachten Sie, dass App-Transportsicherheit (ATS) für alle Anforderungen gilt, die im Rahmen des Aktualisierungsprozesses vorgenommen werden. Apps, die ATS deaktivieren müssen, können den Schlüssel NSAllowsArbitraryLoads zu ihrer App hinzufügen.
Notiz: Eine App muss zuerst signiert werden, um automatisch auf macOS updatet zu werden. Dies ist eine Voraussetzung von Squirrel.Mac.
Unter Windows muss die App zuerst auf dem Gerät des Benutzers installiert werden, bevor autoUpdater genutzt werden kann. Deswegen wird empfohlen electron-winstaller, electron-forge oder grunt-electron-installer zu verwenden, um einen Installer zu generieren.
Bei der Benutzung von electron-winstaller oder electron-forge ist zu Beachten, dass die App nicht versucht, sich selbst zu update, wenn sie zum Ersten mal ausgeführt wird (Weitere Informationen in diesem issue). Es wird auch empfohlen, electron-squirrel-startup zu verwenden, um Desktop-Verknüpfungen für Ihre App zu erhalten.
\nDer Squirrel-Installer wird eine Desktop-Verknüpfung erstellen mit der Application User Model ID im Format com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE, zum Beispiel: com.squirrel.slack.Slack oder com.squirrel.code.Code. Sie müssen dieselbe ID für Ihre App mit der app.setAppUserModelId API verwenden, da Windows sonst Ihre App nicht ordnungsgemäß in der Taskleiste anheften kann.
Like Squirrel.Mac, Windows can host updates on S3 or any other static file host. Weitere Informationen können in der Dokumentation von Squirrel.Windows gefunden werden.
\nDas autoUpdater - Object gibt die folgenden Ereignisse aus:
Kehrt zurück:
\nerror FehlerWird gesendet, wenn beim Aktualisieren ein Fehler auftritt.
\nWird gesendet, wenn geprüft wird, ob ein Update gestartet wurde.
\nWird ausgelöst, wenn ein Update verfügbar ist. Das Update wird automatisch heruntergeladen.
\nWird gesendet, wenn kein Update verfügbar ist.
\nKehrt zurück:
\nevent EventreleaseNotes StringreleaseName StringreleaseDate DateupdateURL StringWird gesendet, wenn ein Update heruntergeladen wurde.
\nUnter Windows ist nur releaseName verfügbar.
Hinweis: Es ist nicht unbedingt notwendig, dieses Ereignis zu behandeln. Ein fehlerfreie Heruntergeladenes Update wird automatisch übernommen, wenn die App das nächste mal gestartet wird.
\nDieses Event wird ausgelöst, wenn die Funktion quitAndInstall() aufgerufen wird.
Das before-quit Event wird erst ausgelöst nachdem alle Fenster geschlossen sind. Daher sollten Sie Aktionen, die Sie vor dem Beenden Ihrer Anwendung ausführen möchten, sowohl in diesem Event als auch im before-quit Event einbauen.
Das Objekt autoUpdater verfügt über die folgenden Methoden:
autoUpdater.setFeedURL(optionen)options Objekturl Stringheaders Record<String, String> (optional) macOS - HTTP-Anfrage-Header.serverType String (optional) macOS - Kann json oder default sein, siehe dazu Squirrel.Mac README für weitere informationen.Setzt die url und initialisiert den automatischen Updater.
autoUpdater.getFeedURL()Gibt String - Die aktuelle URL des Aktualisierungsfeeds.
autoUpdater.checkForUpdates()Fragt den Server, ob es ein Update gibt. Es muss zuerst setFeedURL aufrufen werden, bevor diese API verwendet werden kann.
Note: If an update is available it will be downloaded automatically. Calling autoUpdater.checkForUpdates() twice will download the update two times.
autoUpdater.quitAndInstall()Startet die App neu und installiert damit das Update, sofern es heruntergeladen wurde. Diese Funktion sollte nur aufgerufen werden, nachdem update-downloaded ausgelöst wurde.
Unter der Haube schließt autoUpdater.quitAndInstall() zuerst alle Fenster und führt danach automatisch app.quit() aus.
Hinweis.: Es ist nicht unbedingt notwendig, diese Funktion auszulösen, denn ein fehlerfrei heruntergeladenes Update wird immer automatisch installiert, wenn die App das nächste mal startet.
", "title": "autoUpdater", "description": "Aktivieren Sie Apps, um sich automatisch selbst zu aktualisieren." }, "/docs/tutorial/automated-testing-with-a-custom-driver": { "locale": "de-DE", "slug": "automated-testing-with-a-custom-driver", "href": "/docs/tutorial/automated-testing-with-a-custom-driver", "crowdinFileId": "256179", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/automated-testing-with-a-custom-driver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "To write automated tests for your Electron app, you will need a way to \"drive\" your application. Spectron is a commonly-used solution which lets you emulate user actions via WebDriver. However, it's also possible to write your own custom driver using node's builtin IPC-over-STDIO. The benefit of a custom driver is that it tends to require less overhead than Spectron, and lets you expose custom methods to your test suite.
\nTo create a custom driver, we'll use Node.js' child_process API. The test suite will spawn the Electron process, then establish a simple messaging protocol:
\nconst childProcess = require('child_process')\nconst electronPath = require('electron')\n\n// spawn the process\nconst env = { /* ... */ }\nconst stdio = ['inherit', 'inherit', 'inherit', 'ipc']\nconst appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })\n\n// listen for IPC messages from the app\nappProcess.on('message', (msg) => {\n // ...\n})\n\n// send an IPC message to the app\nappProcess.send({ my: 'message' })\nFrom within the Electron app, you can listen for messages and send replies using the Node.js process API:
\n// listen for IPC messages from the test suite\nprocess.on('message', (msg) => {\n // ...\n})\n\n// send an IPC message to the test suite\nprocess.send({ my: 'message' })\nWe can now communicate from the test suite to the Electron app using the appProcess object.
For convenience, you may want to wrap appProcess in a driver object that provides more high-level functions. Here is an example of how you can do this:
class TestDriver {\n constructor ({ path, args, env }) {\n this.rpcCalls = []\n\n // start child process\n env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages\n this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })\n\n // handle rpc responses\n this.process.on('message', (message) => {\n // pop the handler\n const rpcCall = this.rpcCalls[message.msgId]\n if (!rpcCall) return\n this.rpcCalls[message.msgId] = null\n // reject/resolve\n if (message.reject) rpcCall.reject(message.reject)\n else rpcCall.resolve(message.resolve)\n })\n\n // wait for ready\n this.isReady = this.rpc('isReady').catch((err) => {\n console.error('Application failed to start', err)\n this.stop()\n process.exit(1)\n })\n }\n\n // simple RPC call\n // to use: driver.rpc('method', 1, 2, 3).then(...)\n async rpc (cmd, ...args) {\n // send rpc request\n const msgId = this.rpcCalls.length\n this.process.send({ msgId, cmd, args })\n return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))\n }\n\n stop () {\n this.process.kill()\n }\n}\nIn the app, you'd need to write a simple handler for the RPC calls:
\nif (process.env.APP_TEST_DRIVER) {\n process.on('message', onMessage)\n}\n\nasync function onMessage ({ msgId, cmd, args }) {\n let method = METHODS[cmd]\n if (!method) method = () => new Error('Invalid method: ' + cmd)\n try {\n const resolve = await method(...args)\n process.send({ msgId, resolve })\n } catch (err) {\n const reject = {\n message: err.message,\n stack: err.stack,\n name: err.name\n }\n process.send({ msgId, reject })\n }\n}\n\nconst METHODS = {\n isReady () {\n // do any setup needed\n return true\n }\n // define your RPC-able methods here\n}\nThen, in your test suite, you can use your test-driver as follows:
\nconst test = require('ava')\nconst electronPath = require('electron')\n\nconst app = new TestDriver({\n path: electronPath,\n args: ['./app'],\n env: {\n NODE_ENV: 'test'\n }\n})\ntest.before(async t => {\n await app.isReady\n})\ntest.after.always('cleanup', async t => {\n await app.stop()\n})\nElectron CI on Windows uses AppVeyor, which in turn uses Azure VM images to run. Occasionally, these VM images need to be updated due to changes in Chromium requirements. In order to update you will need PowerShell and the Azure PowerShell module.
\nOccasionally we need to update these images owing to changes in Chromium or other miscellaneous build requirement changes.
\nExample Use Case:\n* We need VS15.9 and we have VS15.7 installed; this would require us to update an Azure image.
Identify the image you wish to modify.
\nGet the Azure storage account key
\nappveyorlibccbuilds Disk Storage Account Name you'd look for appveyorlibccbuilds in the list of storage accounts @ Home < Storage AccountsAccess Keys, and then you can use any of the keys present in the list.Get the full virtual machine image URI from Azure
\n$ACCT_NAME < Blobs < ImagesCopy the image using the Copy Master Image PowerShell script.
\n(images)libcc-20core-vs2017-15.9-2019-04-15.vhdSpin up a new VM using the Create Master VM from VHD PowerShell.
\nps1 file with ./create_master_vm_from_vhd.ps1Standard_F32s_v2East USLog back into Azure and find the VM you just created in Home < Virtual Machines < $YOUR_NEW_VM
Using Microsoft Remote Desktop, click Connect to connect to the VM.
AppVeyor Enterprise master VM credentials.Modify the VM as required.
\nShut down the VM and then delete it in Azure.
\nAdd the new image to the Appveyor Cloud settings or modify an existing image to point to the new VHD.
\ndeviceName StringdeviceId StringDie Entwicklung von Electron ist nicht dogmatisch - es gibt nicht \"die richtige Methode\", um eine Electron-Anwendung zu entwickeln, bauen, verpacken oder veröffentlichen. Zusätzliche Funktionen für Electron, sowohl für die Build- als auch für die Laufzeit, können im npm in Form von individuellen Paketen gefunden werden, was Entwicklern erlaubt, sowohl App als auch Build-Pipeline zu erstellen, die sie brauchen.
\nDieses Level an Modularität und Erweiterbarkeit stellt sicher, dass jede Entwickler, die mit Electron arbeiten, im kleinem wie auch im großen Team, zu keinem Zeitpunkt in ihrem Entwicklungszyklus in dem was sie tun oder nicht tun können eingeschränkt sind. Allerdings können von der Community getragene Boilerplates oder Befehlszeilentools das Kompilieren, Verpacken und Veröffentlichen einer App für viele Entwickler erheblich vereinfachen.
\n\"Boilerplates\" kann man sich wie eine unbemalte Leinwand vorstellen, die als Einstiegspunkt für die Entwicklung einer Anwendung dienen. Sie liegen in der Regel in Form eines Repositories vor, das man klonen und anschließend nach eigenen Wünschen individualisieren kann.
\nKommandozeilenwerkzeuge (CLI) hingegen unterstützen den Entwickler auch weiterhin während den verschiedenen Phasen der Entwicklung und Veröffentlichung. Sie sind hilfreicher und wirken unterstützend, erzwingen aber diverse Richtlinien bezogen auf den Aufbau und die Struktur des Programms. Speziell für Anfänger ist die Verwendung eines Befehlszeilenwerkzeugs häufig hilfreich.
\nEin \"vollständiges Werkzeug für die Erstellung moderner Electron-Anwendungen\". Electron Forge vereint die vorhandenen (und gut gepflegten) Build-Werkzeuge für die Electron-Entwicklung in ein zusammenhängendes Paket, mit dessen Hilfe jeder direkt in die Electron-Entwicklung einsteigen kann.
\nForge wird mit einer einsatzbereiten Schablone geliefert und nutzt Webpack als Modul-Packer. Es enthält eine beispielhafte TypeScript-Konfiguration und bietet zwei Konfigurationsdateien, um so eine einfache Anpassung zu ermöglichen. It uses the same core modules used by the greater Electron community (like electron-packager) – changes made by Electron maintainers (like Slack) benefit Forge's users, too.
Weitere Informationen und die Dokumentation ist auf electronforge.io verfügbar.
\nA \"complete solution to package and build a ready-for-distribution Electron app\" that focuses on an integrated experience. electron-builder adds one single dependency focused on simplicity and manages all further requirements internally.
electron-builder replaces features and modules used by the Electron maintainers (such as the auto-updater) with custom ones. They are generally tighter integrated but will have less in common with popular Electron apps like Atom, Visual Studio Code, or Slack.
You can find more information and documentation in the repository.
\nWenn du kein Tool benötigst, sondern nur ein stabiles Fundament auf dem du bauen kannst, dann könnte CT Lins electron-react-boilerplate einen Blick wert sein. Es ist recht beliebt in der Community und verwendet intern elektron-builder.
The \"Awesome Electron\" list contains more tools and boilerplates to choose from. Wenn du die Länge der Liste einschüchternd findest, vergesse nicht, dass das spätere Hinzufügen von Tools auch ein brauchbarer Ansatz ist.
", "title": "Boilerplates und CLIs", "description": "" }, "/docs/breaking-changes": { "locale": "de-DE", "slug": "breaking-changes", "href": "/docs/breaking-changes", "crowdinFileId": "256117", "githubUrl": "https://github.com/electron/electron/tree/main/docs/breaking-changes.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Breaking-Änderungen werden hier dokumentiert, und Veraltungswarnungen werden js-Code nach Möglichkeit hinzugefügt, mindestens eine Hauptversion, bevor die Änderung vorgenommen wird.
\nIn diesem Dokument wird die folgende Konvention zur Kategorisierung von Breaking-Änderungen verwendet:
\nremote moduleThe remote module was deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.
// Deprecated in Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// Replace with:\nconst { BrowserWindow } = require('@electron/remote')\n\n// In the main process:\nrequire('@electron/remote/main').initialize()\napp.allowRendererProcessReuseThe app.allowRendererProcessReuse property will be removed as part of our plan to more closely align with Chromium's process model for security, performance and maintainability.
Weitere Informationen findest du unter #18397.
\nDie Einstellung Affinität beim Erstellen eines neuen BrowserWindow wird entfernt als Teil unseres Plans, sich stärker an das Prozessmodell von Chromium für Sicherheit, Leistung und Wartbarkeit anzupassen.
Weitere Informationen findest du unter #18397.
\nwindow.open()Der optionale Parameter FrameName legt nicht mehr den Titel des Fensters fest. Dies folgt nun der Spezifikation, die in der nativen Dokumentation unter dem zugehörigen Parameter windowName beschrieben wird.
Wenn Sie diesen Parameter verwenden, um den Titel eines Fensters festzulegen, können Sie stattdessen win.setTitle(title) verwenden.
\nworldSafeExecuteJavaScriptIn Electron 14 wird worldSafeExecuteJavaScript entfernt. Es gibt keine Alternative, bitte stelle sicher, dass dein Code mit dieser Eigenschaft funktioniert. Es wurde standardmäßig aktiviert, da Electron\n12.
Sie werden von dieser Änderung betroffen sein, wenn Sie entweder webFrame.executeJavaScript oder webFrame.executeJavaScriptInIsolatedWorld verwenden. Sie müssen sicherstellen, dass die von einer dieser Methoden zurückgegebenen Werte von der Context Bridge API unterstützt werden, da diese Methoden denselben Wert verwenden, der die Semantik übergeht.
nativeWindowOpen ist standardmäßig auf true eingestelltPrior to Electron 14, window.open was by default shimmed to use BrowserWindowProxy. This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. nativeWindowOpen is no longer experimental, and is now the default.
See the documentation for window.open in Electron for more details.
\nPrior to Electron 14, windows opened with window.open would inherit BrowserWindow constructor options such as transparent and resizable from their parent window. Beginning with Electron 14, this behavior is removed, and windows will not inherit any BrowserWindow constructor options from their parents.
Instead, explicitly set options for the new window with setWindowOpenHandler:
webContents.setWindowOpenHandler((details) => {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n // ...\n }\n }\n})\nadditionalFeaturesThe deprecated additionalFeatures property in the new-window and did-create-window events of WebContents has been removed. Since new-window uses positional arguments, the argument is still present, but will always be the empty array []. (Though note, the new-window event itself is deprecated, and is replaced by setWindowOpenHandler.) Bare keys in window features will now present as keys with the value true in the options object.
// Removed in Electron 14\n// Triggered by window.open('...', '', 'my-key')\nwebContents.on('did-create-window', (window, details) => {\n if (details.additionalFeatures.includes('my-key')) {\n // ...\n }\n})\n\n// Replace with\nwebContents.on('did-create-window', (window, details) => {\n if (details.options['my-key']) {\n // ...\n }\n})\nsession.setPermissionCheckHandler(handler)Die Handler Methoden ersten Parameters waren zuvor immer ein webContents, es kann jetzt manchmal null sein. Sie sollten die requestingOrigin, einbettenOrigin und securityOrigin Eigenschaften verwenden, um auf die Berechtigungsprüfung korrekt zu reagieren. Da der Webcontent null sein kann nicht mehr auf ihn angewiesen werden.
// Alter Code\nsession.setPermissionCheckHandler((webContents, permission) => {\n if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {\n return true\n }\n return false\n})\n\n// Ersetzen mit\nsession.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {\n return true\n }\n return false\n})\nshell.moveItemToTrash()Die veraltete synchrone shell.moveItemToTrash() API wurde entfernt. Verwende stattdessen die asynchrone shell.trashItem().
// Entfernt in Electron 13\nshell.moveItemTosh(path)\n// Ersetzen durch\nshell.trashItem(path).then(/* ... */)\nBrowserWindow Erweiterungs-APIsDie veralteten Erweiterungs-APIs wurden entfernt:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()Use the session APIs instead:
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// In Electron 13 entfernt\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Ersetzen durch\nsession.defaultSession.loadExtension(path)\n// In Electron 13 entfernt\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Ersetzen durch\nsession.defaultSession.loadExtension(path)\n// In Electron 13 entfernt\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Ersetzen durch\nsession.defaultSession.getAllExtensions()\nsystemPreferencesDie folgenden systemPreferences Methoden wurden veraltet:
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()Verwende stattdessen die folgenden nativeTheme Eigenschaften:
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Entfernt in Electron 13\nsystemPreferences.isDarkMode()\n// Ersetzen durch\nnativeTheme.shouldUseDarkColors\n\n// Entfernt in Electron 13\nsystemPreferences. sInvertedColorScheme()\n// Ersetzen durch\nnativeTheme.shouldUseInvertedColorScheme\n\n// In Electron 13 entfernt\nsystemPreferences.isHighContrastColorScheme()\n// Ersetzen durch\nnativeTheme.shouldUseHighContrastColorColorScheme\nnew-window EreignisDas new-window Ereignis von WebContents wurde veraltet. It is replaced by webContents.setWindowOpenHandler().
// Veraltet in Electron 13\nwebContents.on('new-window', (event) => {\n event. reventDefault()\n})\n\n// Ersetzen durch\nwebContents.setWindowOpenHandler((details) => {\n return { action: 'deny' }\n})\nChromium hat die Unterstützung für Flash entfernt, und deshalb müssen wir diesem Beispiel folgen. Weitere Details findest du in der Flash-Roadmap von Chromium.
\nworldSafeExecuteJavaScript ist standardmäßig auf true eingestelltIn Electron 12, worldSafeExecuteJavaScript wird standardmäßig aktiviert. Um das vorherige Verhalten wiederherzustellen, muss worldSafeExecuteJavaScript: false in WebPreferences angegeben werden. Bitte beachte, dass die Einstellung dieser Option auf false unsicher ist.
Diese Einstellung wird in Electron 14 entfernt, also migriere bitte deinen Code um den Standardwert zu unterstützen.
\ncontextIsolation defaults to trueIn Electron 12, contextIsolation will be enabled by default. To restore the previous behavior, contextIsolation: false must be specified in WebPreferences.
We recommend having contextIsolation enabled for the security of your application.
\nAnother implication is that require() cannot be used in the renderer process unless nodeIntegration is true and contextIsolation is false.
For more details see: https://github.com/electron/electron/issues/23506
\ncrashReporter.getCrashesDirectory()The crashReporter.getCrashesDirectory method has been removed. Usage should be replaced by app.getPath('crashDumps').
// Removed in Electron 12\ncrashReporter.getCrashesDirectory()\n// Replace with\napp.getPath('crashDumps')\ncrashReporter methods in the renderer processThe following crashReporter methods are no longer available in the renderer process:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryThey should be called only from the main process.
\nSee #23265 for more details.
\ncrashReporter.start({ compress: true })The default value of the compress option to crashReporter.start has changed from false to true. This means that crash dumps will be uploaded to the crash ingestion server with the Content-Encoding: gzip header, and the body will be compressed.
If your crash ingestion server does not support compressed payloads, you can turn off compression by specifying { compress: false } in the crash reporter options.
remote moduleThe remote module is deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.
// Deprecated in Electron 12:\nconst { BrowserWindow } = require('electron').remote\n// Replace with:\nconst { BrowserWindow } = require('@electron/remote')\n\n// In the main process:\nrequire('@electron/remote/main').initialize()\nshell.moveItemToTrash()The synchronous shell.moveItemToTrash() has been replaced by the new, asynchronous shell.trashItem().
// Deprecated in Electron 12\nshell.moveItemToTrash(path)\n// Replace with\nshell.trashItem(path).then(/* ... */)\nBrowserView.{destroy, fromId, fromWebContents, getAllViews} and id property of BrowserViewThe experimental APIs BrowserView.{destroy, fromId, fromWebContents, getAllViews} have now been removed. Additionally, the id property of BrowserView has also been removed.
For more detailed information, see #23578.
\ncompanyName Argument, um crashReporter.start()The companyName argument to crashReporter.start(), which was previously required, is now optional, and further, is deprecated. Um das gleiche Verhalten auf nicht veraltete Weise zu erhalten, können Sie einen companyName Wert in globalExtraübergeben.
// Deprecated in Electron 10\ncrashReporter.start({ companyName: 'Umbrella Corporation' })\n// Replace with\ncrashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })\ncrashReporter.getCrashesDirectory()The crashReporter.getCrashesDirectory method has been deprecated. Usage should be replaced by app.getPath('crashDumps').
// Deprecated in Electron 10\ncrashReporter.getCrashesDirectory()\n// Replace with\napp.getPath('crashDumps')\ncrashReporter methods in the renderer processCalling the following crashReporter methods from the renderer process is deprecated:
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectoryThe only non-deprecated methods remaining in the crashReporter module in the renderer are addExtraParameter, removeExtraParameter and getParameters.
All above methods remain non-deprecated when called from the main process.
\nSee #23265 for more details.
\ncrashReporter.start({ compress: false })Setting { compress: false } in crashReporter.start is deprecated. Nearly all crash ingestion servers support gzip compression. This option will be removed in a future version of Electron.
enableRemoteModule defaults to falseIn Electron 9, using the remote module without explicitly enabling it via the enableRemoteModule WebPreferences option began emitting a warning. In Electron 10, the remote module is now disabled by default. To use the remote module, enableRemoteModule: true must be specified in WebPreferences:
const w = new BrowserWindow({\n webPreferences: {\n enableRemoteModule: true\n }\n})\nWe recommend moving away from the remote module.
\nprotocol.unregisterProtocolprotocol.uninterceptProtocolDiese Schnittstelle ist jetzt Synchron und der optionale callback wird nicht länger gebraucht.
\n// Deprecated\nprotocol.unregisterProtocol(scheme, () => { /* ... */ })\n// Replace with\nprotocol.unregisterProtocol(scheme)\nprotocol.registerFileProtocolprotocol.registerBufferProtocolprotocol.registerStringProtocolprotocol.registerHttpProtocolprotocol.registerStreamProtocolprotocol.interceptFileProtocolprotocol.interceptStringProtocolprotocol.interceptBufferProtocolprotocol.interceptHttpProtocolprotocol.interceptStreamProtocolDiese Schnittstelle ist jetzt Synchron und der optionale callback wird nicht länger gebraucht.
\n// Deprecated\nprotocol.registerFileProtocol(scheme, handler, () => { /* ... */ })\n// Replace with\nprotocol.registerFileProtocol(scheme, handler)\nDas registrierte oder abgefangene Protokoll hat keine Auswirkungen auf die aktuelle Seite, bis eine Navigation stattfindet.
\nprotocol.isProtocolHandledDiese Schnittstelle ist veraltet anstatt dessen sollten Benutzer protocol.isProtocolRegistered und protocol.isProtocolIntercepted nutzen.
// Deprecated\nprotocol.isProtocolHandled(scheme).then(() => { /* ... */ })\n// Replace with\nconst isRegistered = protocol.isProtocolRegistered(scheme)\nconst isIntercepted = protocol.isProtocolIntercepted(scheme)\nAs of Electron 9 we do not allow loading of non-context-aware native modules in the renderer process. This is to improve security, performance and maintainability of Electron as a project.
\nIf this impacts you, you can temporarily set app.allowRendererProcessReuse to false to revert to the old behavior. This flag will only be an option until Electron 11 so you should plan to update your native modules to be context aware.
Weitere Informationen findest du unter #18397.
\nBrowserWindow extension APIsThe following extension APIs have been deprecated:
\nBrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()Use the session APIs instead:
\nses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()// Deprecated in Electron 9\nBrowserWindow.addExtension(path)\nBrowserWindow.addDevToolsExtension(path)\n// Replace with\nsession.defaultSession.loadExtension(path)\n// Deprecated in Electron 9\nBrowserWindow.removeExtension(name)\nBrowserWindow.removeDevToolsExtension(name)\n// Replace with\nsession.defaultSession.removeExtension(extension_id)\n// Deprecated in Electron 9\nBrowserWindow.getExtensions()\nBrowserWindow.getDevToolsExtensions()\n// Replace with\nsession.defaultSession.getAllExtensions()\n<webview>.getWebContents()Diese API, die seit Electron 8.0 veraltet ist, wird nun entfernt.
\n// Removed in Electron 9.0\nwebview.getWebContents()\n// Replace with\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium hat die Unterstützung für das Ändern des Layout-Zoomniveaus entfernt und es übersteigt die Möglichkeiten von uns, dies zu pflegen. The function was deprecated in Electron 8.x, and has been removed in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.
\nIn Electron 8.0, IPC was changed to use the Structured Clone Algorithm, bringing significant performance improvements. To help ease the transition, the old IPC serialization algorithm was kept and used for some objects that aren't serializable with Structured Clone. In particular, DOM objects (e.g. Element, Location and DOMMatrix), Node.js objects backed by C++ classes (e.g. process.env, some members of Stream), and Electron objects backed by C++ classes (e.g. WebContents, BrowserWindow and WebFrame) are not serializable with Structured Clone. Whenever the old algorithm was invoked, a deprecation warning was printed.
In Electron 9.0, the old serialization algorithm has been removed, and sending such non-serializable objects will now throw an \"object could not be cloned\" error.
\nshell.openItem is now shell.openPathThe shell.openItem API has been replaced with an asynchronous shell.openPath API. You can see the original API proposal and reasoning here.
The algorithm used to serialize objects sent over IPC (through ipcRenderer.send, ipcRenderer.sendSync, WebContents.send and related methods) has been switched from a custom algorithm to V8's built-in Structured Clone Algorithm, the same algorithm used to serialize messages for postMessage. This brings about a 2x performance improvement for large messages, but also brings some breaking changes in behavior.
undefined.// Previously:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => results in { value: 3 } arriving in the main process\n\n// From Electron 8:\nipcRenderer.send('channel', { value: 3, someFunction: () => {} })\n// => throws Error(\"() => {} could not be cloned.\")\nNaN, Infinity and -Infinity will now be correctly serialized, instead of being converted to null.null.Set, Map, Error and RegExp values will be correctly serialized, instead of being converted to {}.BigInt values will be correctly serialized, instead of being converted to null.nulls.Date objects will be transferred as Date objects, instead of being converted to their ISO string representation.Uint8Array, Uint16Array, Uint32Array and so on) will be transferred as such, instead of being converted to Node.js Buffer.Buffer objects will be transferred as Uint8Arrays. You can convert a Uint8Array back to a Node.js Buffer by wrapping the underlying ArrayBuffer:Buffer.from(value.buffer, value.byteOffset, value.byteLength)\nSending any objects that aren't native JS types, such as DOM objects (e.g. Element, Location, DOMMatrix), Node.js objects (e.g. process.env, Stream), or Electron objects (e.g. WebContents, BrowserWindow, WebFrame) is deprecated. In Electron 8, these objects will be serialized as before with a DeprecationWarning message, but starting in Electron 9, sending these kinds of objects will throw a 'could not be cloned' error.
<webview>.getWebContents()This API is implemented using the remote module, which has both performance and security implications. Therefore its usage should be explicit.
// Deprecated\nwebview.getWebContents()\n// Replace with\nconst { remote } = require('electron')\nremote.webContents.fromId(webview.getWebContentsId())\nHowever, it is recommended to avoid using the remote module altogether.
// main\nconst { ipcMain, webContents } = require('electron')\n\nconst getGuestForWebContents = (webContentsId, contents) => {\n const guest = webContents.fromId(webContentsId)\n if (!guest) {\n throw new Error(`Invalid webContentsId: ${webContentsId}`)\n }\n if (guest.hostWebContents !== contents) {\n throw new Error('Access denied to webContents')\n }\n return guest\n}\n\nipcMain.handle('openDevTools', (event, webContentsId) => {\n const guest = getGuestForWebContents(webContentsId, event.sender)\n guest.openDevTools()\n})\n\n// renderer\nconst { ipcRenderer } = require('electron')\n\nipcRenderer.invoke('openDevTools', webview.getWebContentsId())\nwebFrame.setLayoutZoomLevelLimits()Chromium hat die Unterstützung für das Ändern des Layout-Zoomniveaus entfernt und es übersteigt die Möglichkeiten von uns, dies zu pflegen. The function will emit a warning in Electron 8.x, and cease to exist in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.
\nsystemPreferencesThe following systemPreferences events have been deprecated:
inverted-color-scheme-changedhigh-contrast-color-scheme-changedUse the new updated event on the nativeTheme module instead.
// Deprecated\nsystemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })\nsystemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })\n\n// Replace with\nnativeTheme.on('updated', () => { /* ... */ })\nsystemPreferencesDie folgenden systemPreferences Methoden wurden veraltet:
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()Verwende stattdessen die folgenden nativeTheme Eigenschaften:
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors// Deprecated\nsystemPreferences.isDarkMode()\n// Replace with\nnativeTheme.shouldUseDarkColors\n\n// Deprecated\nsystemPreferences.isInvertedColorScheme()\n// Replace with\nnativeTheme.shouldUseInvertedColorScheme\n\n// Deprecated\nsystemPreferences.isHighContrastColorScheme()\n// Replace with\nnativeTheme.shouldUseHighContrastColors\nThis is the URL specified as disturl in a .npmrc file or as the --dist-url command line flag when building native Node modules. Both will be supported for the foreseeable future but it is recommended that you switch.
Deprecated: https://atom.io/download/electron
\nReplace with: https://electronjs.org/headers
\nsession.clearAuthCache() no longer accepts optionsThe session.clearAuthCache API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.
// Deprecated\nsession.clearAuthCache({ type: 'password' })\n// Replace with\nsession.clearAuthCache()\npowerMonitor.querySystemIdleState is now powerMonitor.getSystemIdleState// Removed in Electron 7.0\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime is now powerMonitor.getSystemIdleTime// Removed in Electron 7.0\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\nwebFrame.setIsolatedWorldInfo replaces separate methods// Removed in Electron 7.0\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Replace with\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nmarked property on getBlinkMemoryInfoThis property was removed in Chromium 77, and as such is no longer available.
\nwebkitdirectory attribute for <input type=\"file\"/> now lists directory contentsThe webkitdirectory property on HTML file inputs allows them to select folders. Previous versions of Electron had an incorrect implementation where the event.target.files of the input returned a FileList that returned one File corresponding to the selected folder.
As of Electron 7, that FileList is now list of all files contained within the folder, similarly to Chrome, Firefox, and Edge (link to MDN docs).
As an illustration, take a folder with this structure:
\nfolder\n├── file1\n├── file2\n└── file3\nIn Electron <=6, this would return a FileList with a File object for:
path/to/folder\nIn Electron 7, this now returns a FileList with a File object for:
/path/to/folder/file3\n/path/to/folder/file2\n/path/to/folder/file1\nNote that webkitdirectory no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).
Electron 5 and Electron 6 introduced Promise-based versions of existing asynchronous APIs and deprecated their older, callback-based counterparts. In Electron 7, all deprecated callback-based APIs are now removed.
\nThese functions now only return Promises:
\napp.getFileIcon() #15742app.dock.show() #16904contentTracing.getCategories() #16583contentTracing.getTraceBufferUsage() #16600contentTracing.startRecording() #16584contentTracing.stopRecording() #16584contents.executeJavaScript() #17312cookies.flushStore() #16464cookies.get() #16464cookies.remove() #16464cookies.set() #16464debugger.sendCommand() #16861dialog.showCertificateTrustDialog() #17181inAppPurchase.getProducts() #17355inAppPurchase.purchaseProduct()#17355netLog.stopLogging() #16862session.clearAuthCache() #17259session.clearCache() #17185session.clearHostResolverCache() #17229session.clearStorageData() #17249session.getBlobData() #17303session.getCacheSize() #17185session.resolveProxy() #17222session.setProxy() #17222shell.openExternal() #16176webContents.loadFile() #15855webContents.loadURL() #15855webContents.hasServiceWorker() #16535webContents.printToPDF() #16795webContents.savePage() #16742webFrame.executeJavaScript() #17312webFrame.executeJavaScriptInIsolatedWorld() #17312webviewTag.executeJavaScript() #17312win.capturePage() #15743These functions now have two forms, synchronous and Promise-based asynchronous:
\ndialog.showMessageBox()/dialog.showMessageBoxSync() #17298dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054win.setMenu(null) is now win.removeMenu()// Deprecated\nwin.setMenu(null)\n// Replace with\nwin.removeMenu()\nelectron.screen in the renderer process should be accessed via remote// Deprecated\nrequire('electron').screen\n// Replace with\nrequire('electron').remote.screen\nrequire()ing node builtins in sandboxed renderers no longer implicitly loads the remote version// Deprecated\nrequire('child_process')\n// Replace with\nrequire('electron').remote.require('child_process')\n\n// Deprecated\nrequire('fs')\n// Replace with\nrequire('electron').remote.require('fs')\n\n// Deprecated\nrequire('os')\n// Replace with\nrequire('electron').remote.require('os')\n\n// Deprecated\nrequire('path')\n// Replace with\nrequire('electron').remote.require('path')\npowerMonitor.querySystemIdleState replaced with powerMonitor.getSystemIdleState// Deprecated\npowerMonitor.querySystemIdleState(threshold, callback)\n// Replace with synchronous API\nconst idleState = powerMonitor.getSystemIdleState(threshold)\npowerMonitor.querySystemIdleTime replaced with powerMonitor.getSystemIdleTime// Deprecated\npowerMonitor.querySystemIdleTime(callback)\n// Replace with synchronous API\nconst idleTime = powerMonitor.getSystemIdleTime()\napp.enableMixedSandbox() is no longer needed// Deprecated\napp.enableMixedSandbox()\nMixed-sandbox mode is now enabled by default.
\nTray.setHighlightModeUnder macOS Catalina our former Tray implementation breaks. Apple's native substitute doesn't support changing the highlighting behavior.
\n// Deprecated\ntray.setHighlightMode(mode)\n// API will be removed in v7.0 without replacement.\nnodeIntegration and webviewTag default to false, contextIsolation defaults to trueThe following webPreferences option default values are deprecated in favor of the new defaults listed below.
| Property | Deprecated Default | New Default |
|---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration if set else true | false |
z.B. Re-enabling the webviewTag
\nconst w = new BrowserWindow({\n webPreferences: {\n webviewTag: true\n }\n})\nnodeIntegration in child windows opened via nativeWindowOpenChild windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is true.
Renderer process APIs webFrame.registerURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. A new API, protocol.registerSchemesAsPrivileged has been added and should be used for registering custom schemes with the required privileges. Custom schemes are required to be registered before app ready.
webFrame.setIsolatedWorld* replaced with webFrame.setIsolatedWorldInfo// Deprecated\nwebFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)\nwebFrame.setIsolatedWorldHumanReadableName(worldId, name)\nwebFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)\n// Replace with\nwebFrame.setIsolatedWorldInfo(\n worldId,\n {\n securityOrigin: 'some_origin',\n name: 'human_readable_name',\n csp: 'content_security_policy'\n })\nwebFrame.setSpellCheckProvider now takes an asynchronous callbackThe spellCheck callback is now asynchronous, and autoCorrectWord parameter has been removed.
// Deprecated\nwebFrame.setSpellCheckProvider('en-US', true, {\n spellCheck: (text) => {\n return !spellchecker.isMisspelled(text)\n }\n})\n// Replace with\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck: (words, callback) => {\n callback(words.filter(text => spellchecker.isMisspelled(text)))\n }\n})\nwebContents.getZoomLevel and webContents.getZoomFactor are now synchronouswebContents.getZoomLevel and webContents.getZoomFactor no longer take callback parameters, instead directly returning their number values.
// Deprecated\nwebContents.getZoomLevel((level) => {\n console.log(level)\n})\n// Replace with\nconst level = webContents.getZoomLevel()\nconsole.log(level)\n// Deprecated\nwebContents.getZoomFactor((factor) => {\n console.log(factor)\n})\n// Replace with\nconst factor = webContents.getZoomFactor()\nconsole.log(factor)\nThe following list includes the breaking API changes made in Electron 4.0.
\napp.makeSingleInstance// Deprecated\napp.makeSingleInstance((argv, cwd) => {\n /* ... */\n})\n// Replace with\napp.requestSingleInstanceLock()\napp.on('second-instance', (event, argv, cwd) => {\n /* ... */\n})\napp.releaseSingleInstance// Veraltet\napp.releaseSingleInstance()\n// Ersetze mit\napp.releaseSingleInstanceLock()\napp.getGPUInfoapp.getGPUInfo('complete')\n// Verhält sich jetzt gleich wie `basic` auf macOS\napp.getGPUInfo('basic')\nwin_delay_load_hookWhen building native modules for windows, the win_delay_load_hook variable in the module's binding.gyp must be true (which is the default). If this hook is not present, then the native module will fail to load on Windows, with an error message like Cannot find module. See the native module guide for more.
The following list includes the breaking API changes in Electron 3.0.
\napp// Veraltet\napp.getAppMemoryInfo()\n// Ersetze mit\napp.getAppMetrics()\n\n// Veraltet\nconst metrics = app.getAppMetrics()\nconst { memory } = metrics[0] // Deprecated property\nBrowserfenster// Deprecated\nconst optionsA = { webPreferences: { blinkFeatures: '' } }\nconst windowA = new BrowserWindow(optionsA)\n// Replace with\nconst optionsB = { webPreferences: { enableBlinkFeatures: '' } }\nconst windowB = new BrowserWindow(optionsB)\n\n// Deprecated\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play_pause') {\n // do something\n }\n})\n// Replace with\nwindow.on('app-command', (e, cmd) => {\n if (cmd === 'media-play-pause') {\n // do something\n }\n})\nclipboard// Veraltet\nclipboard.readRtf()\n// Ersetze mit\nclipboard.readRTF()\n\n// Veraltet\nclipboard.writeRtf()\n// Ersetze mit\nclipboard.writeRTF()\n\n// Veraltet\nclipboard.readHtml()\n// Ersetze mit\nclipboard.readHTML()\n\n// Veraltet\nclipboard.writeHtml()\n// Ersetze mit\nclipboard.writeHTML()\ncrashReporter// Veraltet\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n autoSubmit: true\n})\n// Ersetze mit\ncrashReporter.start({\n companyName: 'Crashly',\n submitURL: 'https://crash.server.com',\n uploadToServer: true\n})\nnativeImage// Veraltet\nnativeImage.createFromBuffer(buffer, 1.0)\n// Ersetze mit\nnativeImage.createFromBuffer(buffer, {\n scaleFactor: 1.0\n})\nprocess// Veraltet\nconst info = process.getProcessMemoryInfo()\nscreen// Veraltet\nscreen.getMenuBarHeight()\n// Ersetze mit\nscreen.getPrimaryDisplay().workArea\nsession// Deprecated\nses.setCertificateVerifyProc((hostname, certificate, callback) => {\n callback(true)\n})\n// Replace with\nses.setCertificateVerifyProc((request, callback) => {\n callback(0)\n})\nFach// Veraltet\ntray.setHighlightMode(true)\n// Ersetze mit\ntray.setHighlightMode('on')\n\n// Veraltet\ntray.setHighlightMode(false)\n// Ersetze mit\ntray.setHighlightMode('off')\nwebContents// Veraltet\nwebContents.openDevTools({ detach: true })\n// Ersetze mit\nwebContents.openDevTools({ mode: 'detach' })\n\n// Entfernt\nwebContents.setSize(options)\n// Für diese API gibt es keinen Ersatz\nwebFrame// Veraltet\nwebFrame.registerURLSchemeAsSecure('app')\n// Ersetze mit\nprotocol.registerStandardSchemes(['app'], { secure: true })\n\n// Veraltet\nwebFrame.registerURLSchemeAsPrivileged('app', { secure: true })\n// Ersetze mit\nprotocol.registerStandardSchemes(['app'], { secure: true })\n<webview>// Entfernt\nwebview.setAttribute('disableguestresize', '')\n// Für diese API gibt es keinen Ersatz\n\n// Entfernt\nwebview.setAttribute('guestinstance', instanceId)\n// Für diese API gibt es keinen Ersatz\n\n// Keyboard listener funktionieren nicht länger für webview tag\nwebview.onkeydown = () => { /* handler */ }\nwebview.onkeyup = () => { /* handler */ }\nThis is the URL specified as disturl in a .npmrc file or as the --dist-url command line flag when building native Node modules.
Deprecated: https://atom.io/download/atom-shell
\nReplace with: https://atom.io/download/electron
\nThe following list includes the breaking API changes made in Electron 2.0.
\nBrowserfenster// Deprecated\nconst optionsA = { titleBarStyle: 'hidden-inset' }\nconst windowA = new BrowserWindow(optionsA)\n// Replace with\nconst optionsB = { titleBarStyle: 'hiddenInset' }\nconst windowB = new BrowserWindow(optionsB)\nmenu// Entfernt\nmenu.popup(browserWindow, 100, 200, 2)\n// Ersetze mit\nmenu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })\nnativeImage// Entfernt\nnativeImage.toPng()\n// Ersetze mit\nnativeImage.toPNG()\n\n// Entfernt\nnativeImage.toJpeg()\n// Ersetze mit\nnativeImage.toJPEG()\nprocessprocess.versions.electron and process.version.chrome will be made read-only properties for consistency with the other process.versions properties set by Node.webContents// Entfernt\nwebContents.setZoomLevelLimits(1, 2)\n// Ersetze mit\nwebContents.setVisualZoomLevelLimits(1, 2)\nwebFrame// Entfernt\nwebFrame.setZoomLevelLimits(1, 2)\n// Ersetze mit\nwebFrame.setVisualZoomLevelLimits(1, 2)\n<webview>// Entfernt\nwebview.setZoomLevelLimits(1, 2)\n// Ersetze mit\nwebview.setVisualZoomLevelLimits(1, 2)\nEach Electron release includes two identical ARM builds with slightly different filenames, like electron-v1.7.3-linux-arm.zip and electron-v1.7.3-linux-armv7l.zip. The asset with the v7l prefix was added to clarify to users which ARM version it supports, and to disambiguate it from future armv6l and arm64 assets that may be produced.
The file without the prefix is still being published to avoid breaking any setups that may be consuming it. Starting at 2.0, the unprefixed file will no longer be published.
\nFor details, see 6986 and 7189.
", "title": "Breaking Changes", "description": "" }, "/docs/api/browser-view": { "locale": "de-DE", "slug": "browser-view", "href": "/docs/api/browser-view", "crowdinFileId": "256283", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-view.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Eine Browseransicht kann verwendet werden, um zusätzliche Webinhalte in ein BrowserWindow einzubetten. Es ist wie ein untergeordnetes Fenster, mit der Ausnahme, dass es relativ zu dem übergeordneten Fenster positioniert ist. Es ist als Alternative zum Webview Tag gedacht.
\n\nErstelle und kontrolliere Ansichten.
\n
Prozess: Haupt
\n// Im Hauptprozess.\nconst { BrowserView, BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nconst view = new BrowserView()\nwin.setBrowserView(view)\nview.setBounds({ x: 0, y: 0, width: 300, height: 300 })\nview.webContents.loadURL('https://electronjs.org')\nnew BrowserView([options]) Experimentaloptions Object (optional)webPreferences Object (optional) - Siehe BrowserWindow.Objekte, die mit new BrowserView erstellt wurden, haben folgende Eigenschaften:
view.webContents ExperimentalA WebContents object owned by this view.
Objekte, die mit new BrowserView erstellt wurden, haben folgende Instanzmethoden:
view.setAutoResize(options) Experimentaloptions Objektwidth Boolean (optional) - Wenn true, wächst und schrumpft die Breite der Ansicht zusammen mit dem übergeordneten Fenster. Automatisch false.height Boolean (optional) - Wenn true, wächst und schrumpft die Höhe der Ansicht zusammen mit dem übergeordneten Fenster. Automatisch false.horizontal Boolean (optional) - Wenn true, ändert sich sowohl die X-Position als auch die Breite der Ansicht zusammen mit dem übergeordneten Fenster. Automatisch false.vertical Boolean (optional) - Wenn true, ändert sich sowohl die Y-Position als auch die Höhe der Ansicht zusammen mit dem übergeordneten Fenster. Automatisch false.view.setBounds(bounds) Experimentalbounds Rectangle Die Grenzen der Ansicht als RechteckPasst die Ansicht an die Dimensionen und die Ausrichtung des Rechteckes relativ zum übergeordneten Fenster an.
\nview.getBounds() ExperimentalGibt Rectangle zurück
Die bounds dieser BrowserView-Instanz als Object.
view.setBackgroundColor(color) Experimentalcolor String - Farbe in #aarrggbb oder #argb Form. Der Alpha-Kanal ist optional.\n\nErstellung und Steuerung von Browserfenstern.
\n
Prozess: Haupt
\n// Im Hauptprozess.\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\n// Load a remote URL\nwin.loadURL('https://github.com')\n\n// Or load a local HTML file\nwin.loadFile('index.html')\nUm ein Fenster ohne Chrome, ein transparentes Fenster oder ein Fenster in einer beliebigen Form zu erzeugen, können sie die Frameless Window API verwenden.
\nWhen loading a page in the window directly, users may see the page load incrementally, which is not a good experience for a native app. To make the window display without a visual flash, there are two solutions for different situations.
\nready-to-show eventDas ready-to-show Ereignis wird während des Ladens der Seite ausgelöst, falls das Fenster noch nicht angezeigt wurde nachdem der Rendererprozess die Seite erstmalig gerendert hat. Wenn das Fenster nach diesem Ereignis gezeigt wird, gibt es keinen bemerkbaren Seitenaufbau:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ show: false })\nwin.once('ready-to-show', () => {\n win.show()\n})\nFür gewöhnlich wird dieses Ereignis nach dem did-finish-load Ereignis ausgelöst. Bei Seiten mit vielen Remoteressourcen kann es aber passieren dass das Event vor dem did-finish-load Ereignis ausgelöst wird.
Bitte beachten Sie, dass die Verwendung dieses Ereignisses impliziert, dass der Renderer als \"sichtbar\" und bemalt betrachtet wird, obwohl show falsch ist. Dieses Ereignis wird nie abfeuern, wenn paintWhenInitiallyHidden: false gesetzt ist.
backgroundColor propertyBei umfangreichen Apps könnte das ready-to-show Ereignis zu spät ausgelöst werden, sodass sich die App langsam anfühlt. In diesem Fall empfiehlt es sich, das Fenster sofort anzuzeigen und die backgroundColor auf einen Wert zu setzen der dem Hintergrund ihrer App ähnelt:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ backgroundColor: '#2e2c29' })\nwin.loadURL('https://github.com')\nBeachten Sie dass es sich auch bei Apps die das ready-to-show Ereignis verwenden empfiehlt die backgroundColor zu setzen, damit sich die App nativer anfühlt.
Mithilfe der parent Option können Sie untergeordnete Fenster erstellen:
const { BrowserWindow } = require('electron')\n\nconst top = new BrowserWindow()\nconst child = new BrowserWindow({ parent: top })\nchild.show()\ntop.show()\nDas child Fenster wird stets über dem top Fenster angezeigt.
Ein modales Fenster ist ein untergeordnetes Fenster, das das übergeordnete Fenster sperrt. Um ein modales Fenster zu erzeugen müssen sie sowohl die parent als auch die modal Optionen setzen:
const { BrowserWindow } = require('electron')\n\nconst child = new BrowserWindow({ parent: top, modal: true, show: false })\nchild.loadURL('https://github.com')\nchild.once('ready-to-show', () => {\n child.show()\n})\nDie Page Visibility API Funktioniert wie folgt:
\nhidden. Auf den anderen Plattformen ist der Sichtbarkeitszustand nur hidden, wenn das Fenster minimiert oder explizit durch win.hide() verseckt wurde.BrowserWindow mit der Option show: false erzeugt wurde, ist der anfängliche Sichtbarkeitszustand visible, obwohl das Fenster eigentlich versteckt ist.backgroundThrottling deaktiviert ist, bleibt der Sichtbarkeitszustand visible, selbst wenn das Fenster minimiert, verdeckt oder versteckt wird.Es wird empfohlen aufwendige Aufgaben zu pausieren wenn der Sichtbarkeitszustand hidden ist, um Energie zu sparen.
dialog geändert.\n\nErstellung und Steuerung von Browserfenstern.
\n
Prozess: Haupt
\nBrowserWindow ist ein EventEmitter.
Es erzeugt ein neues BrowserWindow mit nativen Eigenschaften die durch options gesetzt wurden.
new BrowserWindow([options])options Object (optional)width Integer (optional) - Fensterbreite in Pixel. Standard ist 800.height Integer (optional) - Fensterhöhe in Pixel. Standard ist 600.x Integer (optional) - (notwendig wenn y gegeben wird) der x-Versatz des Fensters zum Bildschirm. Standardmäßig wird das Fenster zentriert.y Integer (optional) - (notwendig wenn x gegeben wird) der y-Versatz des Fensters zum Bildschirm. Standardmäßig wird das Fenster zentriert.useContentSize Boolean (optional) - Die width und height Werte werden als Größe der angezeigten Webseite verwendet. D.h. die tatsächliche Größe des Fensters beinhaltet noch die Rahmengröße und ist deshalb etwas größer. Standard ist false.center Boolean (optional) - Zeige das Fenster in der Mitte des Bildschirms.minWidth Integer (optional) - die minimale Fensterbreite. Standard ist 0.minHeight Integer (optional) - die minimale Fensterhöhe. Standard ist 0.maxWidth Integer (optional) - die maximale Fensterbreite. Der Standardwert ist kein Limit.maxHeight Integer (optional) - die maximale Fensterhöhe. Der Standardwert ist kein Limit.resizable Boolean (optional) - Gibt an, ob die Fenstergröße geändert werden kann. Standard ist true.movable Boolean (optional) - Gibt an, ob das Fenster verschoben werden kann. Diese Option ist unter Linux noch nicht implementiert. Standard ist true.minimizable Boolean (optional) - ob das Fenster minimiert werden kann. Diese Option ist unter Linux noch nicht implementiert. Standard ist true.maximizable Boolean (optional) - ob das Fenster maximiert werden kann. Diese Option ist unter Linux noch nicht implementiert. Standard ist true.closable Boolean (optional) - Gibt an, ob das Fenster geschlossen werden kann. Diese Option ist unter Linux noch nicht implementiert. Standard ist true.focusable Boolean (optional) - Gibt an ob das Fenster fokussiert werden kann. Standard ist true. Unter Windows impliziert die Option focusable: false die Option skipTaskbar: true. Unter Linux sorgt focusable: false dafür dass das Fenster nicht mehr mit dem Fenstermanager interagiert, d.h. das Fenster bleibt in allen Arbeitsoberflächen ganz oben.alwaysOnTop Boolean (optional) - Gibt an ob das Fenster immer über anderen Fenstern angezeigt werden soll. Standard ist false.fullscreen Boolean (optional) - Gibt an ob das Fenster im Vollbildmodus angezeigt werden soll. Wenn diese Option explizit auf false gesetzt wird, wird der Button für Vollbildmodus unter macOS versteckt oder deaktiviert. Standard ist false.fullscreenable Boolean (optional) - Gibt an ob das Fenster in den Vollbildmodus versetzt werden kann. Unter macOS gibt diese Option auch an, ob der Maximieren/Zoom Button das Fenster in den Vollbildmodus versetzt oder maximiert. Standard ist true.simpleFullscreenBoolean (optional) - Gibt an ob der pre-Lion Vollbildmodus unter macOS verwendet werden soll. Standard ist false.skipTaskbar Boolean (optional) - Gibt an ob das Fenster in der Taskbar anzeigt werden soll. Standard ist false.kiosk Boolean (optional) - Gibt an, ob der Benutzer eingeschränkte Rechte besitzt (Kiosk-Modus). Standard ist false.Titel String (optional) - der Standardfenstertitel. Standard ist \"Electron\". Wenn der HTML-Tag <title> in der von loadUrl() geladenen HTML-Datei festgelegt ist, dann wird dieser Wert ignoriert.icon (NativeImage | String) (optional) - Das Fenstericon. Es empfiehlt sich unter Windows ein ICO Icon zu verwenden um die besten visuellen Effekte zu erreichen. Das Icon der Executable wird verwendet wenn dieser Wert nicht definiert wird.show Boolean (optional) - Gibt an ob das Fenster angezeigt wird, sobald es erstellt wurde. Standard ist true.paintWhenInitiallyHidden Boolean (optional) - Gibt an, ob der Renderer aktiv sein soll, wenn show false ist und das Fenster gerade erstellt wurde. Damit document.visibilityState beim ersten Laden mit show: false korrekt funktioniert, sollten Sie diesen Wert auf falsesetzen. Wenn Sie diese Einstellung auf false festlegen, wird das ready-to-show -Ereignis nicht ausgelöst. Standard ist true.frame Boolean (optional) - Geben Sie false an, um ein Frameless Windowzu erstellen. Standard ist true.parent BrowserWindow (optional) - Geben Sie das übergeordnete Fenster an. Standard ist null.modal Boolean (optional) - Gibt an, ob es das Fenster ein modales Fenster sein soll. Diese Funktion funktioniert nur, wenn das Fenster ein untergeordnetes Fenster ist. Standard ist false.acceptFirstMouse Boolean (optional) - Whether clicking an inactive window will also click through to the web contents. Default is false on macOS. This option is not configurable on other platforms.disableAutoHideCursor Boolean (optional) - Ob der Cursor ausgeblendet werden soll, wenn der Benutzer tippt. Standard ist false.autoHideMenuBar Boolean (optional) - Blendet die Menüleiste automatisch aus, es sei denn, die Alt Taste wird gedrückt. Standard ist false.enableLargerThanScreen Boolean (optional) - Dieser Wert gibt an, ob das Fenster größer als der Bildschirm sein kann. Nur relevant für macOS, da andere Betriebssysteme standardmäßig Fenster erlauben, die größer als der Bildschirm sind. Standard ist false.backgroundColor String (optional) - Die Hintergrundfarbe des Fensters als hexadezimaler Wert, wie zum Beispiel #66CD00 oder #FFF oder #80FFFFFF (alpha im #AARRGGBB Format wird unterstützt, wenn transparent auf true gesetzt ist). Der Standardwert ist #FFF (weiß).hasShadow Boolean (optional) - Gibt an, ob das Fenster einen Schatten haben soll. Standard ist true.opacity Zahl (optional) - Setzt die anfängliche Deckkraft des Fensters zwischen 0,0 (vollständig transparent) und 1,0 (vollständig undurchsichtig). Dies ist nur unter Windows und macOS implementiert.darkTheme Boolean (optional) - Erzwingt ein dunkles Farbschema. Funktioniert nur mit manchen GTK+3 Desktopumgebungen. Standard ist false.transparent Boolean (optional) - Macht das Fenster transparent. Standard ist false. Unter Windows funktioniert es nur, wenn das Fenster rahmenlos ist.type String (optional) - Der Fenstertyp. Standard ist ein normales Fenster. Mehr dazu kann weiter unten gelesen werden.visualEffectState String (optional) - Specify how the material appearance should reflect window activity state on macOS. Must be used with the vibrancy property. Mögliche Werte sind:followWindow - The backdrop should automatically appear active when the window is active, and inactive when it is not. This is the default.active - The backdrop should always appear active.inactive - The backdrop should always appear inactive.titleBarStyle String (optional) macOS Windows - The style of window title bar. Standard ist default. Mögliche Werte sind:default - Results in the standard title bar for macOS or Windows respectively.hidden - Results in a hidden title bar and a full size content window. On macOS, the window still has the standard window controls (“traffic lights”) in the top left. On Windows, when combined with titleBarOverlay: true it will activate the Window Controls Overlay (see titleBarOverlay for more information), otherwise no window controls will be shown.hiddenInset - Only on macOS, results in a hidden title bar with an alternative look where the traffic light buttons are slightly more inset from the window edge.customButtonsOnHover - Only on macOS, results in a hidden title bar and a full size content window, the traffic light buttons will display when being hovered over in the top left of the window. Note: This option is currently experimental.trafficLightPosition Point (optional) - Set a custom position for the traffic light buttons in frameless windows.roundedCorners Boolean (optional) - Whether frameless window should have rounded corners on macOS. Standard ist true.fullscreenWindowTitle Boolean (optional) Deprecated - Shows the title in the title bar in full screen mode on macOS for hiddenInset titleBarStyle. Standard ist false.thickFrame Boolean (optional) - Use WS_THICKFRAME style for frameless windows on Windows, which adds standard window frame. Fensterschatten und Fensteranimationen werden entfernt wenn dieser Wert false ist. Standard ist true.vibrancy String (optional) - Add a type of vibrancy effect to the window, only on macOS. Can be appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, or under-page. Please note that appearance-based, light, dark, medium-light, and ultra-dark are deprecated and have been removed in macOS Catalina (10.15).zoomToPageWidth Boolean (optional) - Controls the behavior on macOS when option-clicking the green stoplight button on the toolbar or by clicking the Window > Zoom menu item. If true, the window will grow to the preferred width of the web page when zoomed, false will cause it to zoom to the width of the screen. This will also affect the behavior when calling maximize() directly. Standard ist false.tabbingIdentifier String (optional) - Reitergruppenname, erlaubt das öffnen des Fensters als nativen Reiter unter macOS 10.12+. Fenster mit dem selben Reitergruppennamen werden gruppiert. This also adds a native new tab button to your window's tab bar and allows your app and window to receive the new-window-for-tab event.webPreferences Object (optional) - Settings of web page's features.devTools Boolean (optional) - Gibt an ob die Entwicklerwerkzeuge aktiviert sind. Falls dies auf false gesetzt ist, kann BrowserWindow.webContents.openDevTools() nicht verwendet werden um die Entwicklerwerkzeuge zu öffnen. Standard ist true.nodeIntegration Boolean (optional) - Whether node integration is enabled. Standard ist false.nodeIntegrationsInWorker Boolean (optional) - Gibt an ob die Node Integration in Web Workern aktiviert ist. Standard ist false. Mehr dazu kann in Multithreading gefunden werden.nodeIntegrationInSubFrames Boolean (optional) - Experimental option for enabling Node.js support in sub-frames such as iframes and child windows. All your preloads will load for every iframe, you can use process.isMainFrame to determine if you are in the main frame or not.preload String (optional) - Gibt ein Skript an das vor allen anderen Skripten geladen wird bevor andere Skripte der Seite ausgeführt werden. Dieses Skript hat immer Zugriff auf die Node APIs, unabhängig davon ob die Node Integration aktiviert ist oder nicht. Der Wert sollte der absolute Pfad zum Skript sein. Wenn die Node Integration ausgeschaltet ist, kann das Preload Skript globale Node Symbole in den Globalen Scope zurückbringen. Siehe dieses Beispiel.sandbox Boolean (optional) - Wenn gesetzt, wird der Renderer des Fensters in einer Sandbox ausgeführt, wodurch es kompatibel mit der Chromium Sandbox wird und die Node.js Integration deaktiviert wird. Dies ist nicht das gleiche wie nodeIntegration, da die APIs die dem Preload Skript zur Verfügung stehen stärker limitiert sind. Lesen sie hier mehr über diese Option.session Session (optional) - Sets the session used by the page. Instead of passing the Session object directly, you can also choose to use the partition option instead, which accepts a partition string. When both session and partition are provided, session will be preferred. Default is the default session.partition String (optional) - Sets the session used by the page according to the session's partition string. If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. If there is no persist: prefix, the page will use an in-memory session. By assigning the same partition, multiple pages can share the same session. Default is the default session.zoomFactor Number (optional) - The default zoom factor of the page, 3.0 represents 300%. Standard ist 1.0.javascript Boolean (optional) - Enables JavaScript support. Standard ist true.webSecurity Boolean (optional) - When false, it will disable the same-origin policy (usually using testing websites by people), and set allowRunningInsecureContent to true if this options has not been set by user. Standard ist true.allowRunningInsecureContent Boolean (optional) - Allow an https page to run JavaScript, CSS or plugins from http URLs. Standard ist false.images Boolean (optional) - Enables image support. Standard ist true.imageAnimationPolicy String (optional) - Specifies how to run image animations (E.g. GIFs). Can be animate, animateOnce or noAnimation. Standard ist animate.textAreasAreResizable Boolean (optional) - Make TextArea elements resizable. Default is true.webgl Boolean (optional) - Enables WebGL support. Standard ist true.plugins Boolean (optional) - Whether plugins should be enabled. Standard ist false.experimentalFeatures Boolean (optional) - Enables Chromium's experimental features. Standard ist false.scrollBounce Boolean (optional) - Enables scroll bounce (rubber banding) effect on macOS. Standard ist false.enableBlinkFeatures String (optional) - A list of feature strings separated by ,, like CSSVariables,KeyboardEventKey to enable. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.disableBlinkFeatures String (optional) - A list of feature strings separated by ,, like CSSVariables,KeyboardEventKey to disable. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.defaultFontFamily Object (optional) - Sets the default font for the font-family.standard String (optional) - Defaults to Times New Roman.serif String (optional) - Defaults to Times New Roman.sansSerif String (optional) - Defaults to Arial.monospace String (optional) - Defaults to Courier New.cursive String (optional) - Defaults to Script.fantasy String (optional) - Defaults to Impact.defaultFontSize Integer (optional) - Defaults to 16.defaultMonospaceFontSize Integer (optional) - Defaults to 13.minimumFontSize Integer (optional) - Defaults to 0.defaultEncoding String (optional) - Defaults to ISO-8859-1.backgroundThrottling Boolean (optional) - Whether to throttle animations and timers when the page becomes background. This also affects the Page Visibility API. Defaults to true.offscreen Boolean (optional) - Whether to enable offscreen rendering for the browser window. Defaults to false. See the offscreen rendering tutorial for more details.contextIsolation Boolean (optional) - Whether to run Electron APIs and the specified preload script in a separate JavaScript context. Defaults to true. The context that the preload script runs in will only have access to its own dedicated document and window globals, as well as its own set of JavaScript builtins (Array, Object, JSON, etc.), which are all invisible to the loaded content. The Electron API will only be available in the preload script and not the loaded page. This option should be used when loading potentially untrusted remote content to ensure the loaded content cannot tamper with the preload script and any Electron APIs being used. This option uses the same technique used by Chrome Content Scripts. You can access this context in the dev tools by selecting the 'Electron Isolated Context' entry in the combo box at the top of the Console tab.nativeWindowOpen Boolean (optional) - Whether to use native window.open(). Defaults to true. Child windows will always have node integration disabled unless nodeIntegrationInSubFrames is true.webviewTag Boolean (optional) - Whether to enable the <webview> tag. Defaults to false. Note: The preload script configured for the <webview> will have node integration enabled when it is executed so you should ensure remote/untrusted content is not able to create a <webview> tag with a possibly malicious preload script. You can use the will-attach-webview event on webContents to strip away the preload script and to validate or alter the <webview>'s initial settings.additionalArguments String - A list of strings that will be appended to process.argv in the renderer process of this app. Useful for passing small bits of data down to renderer process preload scripts.safeDialogs Boolean (optional) - Whether to enable browser style consecutive dialog protection. Standard ist false.safeDialogsMessage String (optional) - The message to display when consecutive dialog protection is triggered. If not defined the default message would be used, note that currently the default message is in English and not localized.disableDialogs Boolean (optional) - Whether to disable dialogs completely. Overrides safeDialogs. Standard ist false.navigateOnDragDrop Boolean (optional) - Whether dragging and dropping a file or link onto the page causes a navigation. Standard ist false.autoplayPolicy String (optional) - Autoplay policy to apply to content in the window, can be no-user-gesture-required, user-gesture-required, document-user-activation-required. Defaults to no-user-gesture-required.disableHtmlFullscreenWindowResize Boolean (optional) - Whether to prevent the window from resizing when entering HTML Fullscreen. Default is false.accessibleTitle String (optional) - An alternative title string provided only to accessibility tools such as screen readers. This string is not directly visible to users.spellcheck Boolean (optional) - Whether to enable the builtin spellchecker. Standard ist true.enableWebSQL Boolean (optional) - Whether to enable the WebSQL api. Standard ist true.v8CacheOptions String (optional) - Enforces the v8 code caching policy used by blink. Accepted values arenone - Disables code cachingcode - Heuristic based code cachingbypassHeatCheck - Bypass code caching heuristics but with lazy compilationbypassHeatCheckAndEagerCompile - Same as above except compilation is eager. Default policy is code.enablePreferredSizeMode Boolean (optional) - Whether to enable preferred size mode. The preferred size is the minimum size needed to contain the layout of the document—without requiring scrolling. Enabling this will cause the preferred-size-changed event to be emitted on the WebContents when the preferred size changes. Standard ist false.titleBarOverlay Object | Boolean (optional) - When using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS or using a titleBarStyle so that the standard window controls (\"traffic lights\" on macOS) are visible, this property enables the Window Controls Overlay JavaScript APIs and CSS Environment Variables. Specifying true will result in an overlay with default system colors. Standard ist false.color String (optional) Windows - The CSS color of the Window Controls Overlay when enabled. Default is the system color.symbolColor String (optional) Windows - The CSS color of the symbols on the Window Controls Overlay when enabled. Default is the system color.When setting minimum or maximum window size with minWidth/maxWidth/ minHeight/maxHeight, it only constrains the users. It won't prevent you from passing a size that does not follow size constraints to setBounds/setSize or to the constructor of BrowserWindow.
The possible values and behaviors of the type option are platform dependent. Mögliche Werte sind:
desktop, dock, toolbar, splash, notification.desktop, textured.textured type adds metal gradient appearance (NSTexturedBackgroundWindowMask).desktop type places the window at the desktop background window level (kCGDesktopWindowLevel - 1). Note that desktop window will not receive focus, keyboard or mouse events, but you can use globalShortcut to receive input sparingly.toolbar.Objekte welche mit new BrowserWindow erzeugt wurden emitieren folgende Events:
Hinweis: Manche Methoden sind nur auf spezifischen Betriebssystemen verfügbar und sind dementsprechend gekennzeichnet.
\nKehrt zurück:
\nevent Eventtitle StringexplicitSet BooleanEmitted when the document changed its title, calling event.preventDefault() will prevent the native window's title from changing. explicitSet is false when title is synthesized from file URL.
Kehrt zurück:
\nevent EventEmitted when the window is going to be closed. It's emitted before the beforeunload and unload event of the DOM. Calling event.preventDefault() will cancel the close.
Usually you would want to use the beforeunload handler to decide whether the window should be closed, which will also be called when the window is reloaded. In Electron, returning any value other than undefined would cancel the close. Ein Beispiel:
window.onbeforeunload = (e) => {\n console.log('I do not want to be closed')\n\n // Unlike usual browsers that a message box will be prompted to users, returning\n // a non-void value will silently cancel the close.\n // It is recommended to use the dialog API to let the user confirm closing the\n // application.\n e.returnValue = false // equivalent to `return false` but not recommended\n}\nNote: There is a subtle difference between the behaviors of window.onbeforeunload = handler and window.addEventListener('beforeunload', handler). It is recommended to always set the event.returnValue explicitly, instead of only returning a value, as the former works more consistently within Electron.
Emitted when the window is closed. After you have received this event you should remove the reference to the window and avoid using it any more.
\nAusgegeben wenn die Fenstersitzung aufgrund von erzwungenem Abschalten, einem Neustart oder durch Abmelden enden wird.
\nAusgegeben wenn die Webseite nicht mehr antwortet.
\nAusgegeben wenn eine Webseite, die zuvor nicht mehr antwortete, wieder antwortet.
\nAusgegeben wenn das Fenster den Fokus verliert.
\nAusgegeben wenn das Fenster den Fokus erhält.
\nAusgegeben wenn das Fenster gezeigt wird.
\nAusgegeben wenn das Fenster versteckt wird.
\nEmitted when the web page has been rendered (while not being shown) and window can be displayed without a visual flash.
\nBitte beachten Sie, dass die Verwendung dieses Ereignisses impliziert, dass der Renderer als \"sichtbar\" und bemalt betrachtet wird, obwohl show falsch ist. Dieses Ereignis wird nie abfeuern, wenn paintWhenInitiallyHidden: false gesetzt ist.
Emitted when window is maximized.
\nEmitted when the window exits from a maximized state.
\nEmitted when the window is minimized.
\nEmitted when the window is restored from a minimized state.
\nKehrt zurück:
\nevent EventnewBounds Rectangle - Size the window is being resized to.details Objektedge (String) - The edge of the window being dragged for resizing. Can be bottom, left, right, top-left, top-right, bottom-left or bottom-right.Emitted before the window is resized. Calling event.preventDefault() will prevent the window from being resized.
Note that this is only emitted when the window is being resized manually. Resizing the window with setBounds/setSize will not emit this event.
The possible values and behaviors of the edge option are platform dependent. Mögliche Werte sind:
bottom, top, left, right, top-left, top-right, bottom-left, bottom-right.bottom and right.bottom is used to denote vertical resizing.right is used to denote horizontal resizing.Emitted after the window has been resized.
\nEmitted once when the window has finished being resized.
\nThis 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.
Kehrt zurück:
\nevent EventnewBounds Rectangle - Location the window is being moved to.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 resized manually. Resizing the window with setBounds/setSize will not emit this event.
Emitted when the window is being moved to a new position.
\nEmitted once when the window is moved to a new position.
\nNote: On macOS this event is an alias of move.
Emitted when the window enters a full-screen state.
\nEmitted when the window leaves a full-screen state.
\nEmitted when the window enters a full-screen state triggered by HTML API.
\nEmitted when the window leaves a full-screen state triggered by HTML API.
\nKehrt zurück:
\nevent EventisAlwaysOnTop BooleanEmitted when the window is set or unset to show always on top of other windows.
\nKehrt zurück:
\nevent Eventcommand StringEmitted when an App Command is invoked. These are typically related to keyboard media keys or browser commands, as well as the \"Back\" button built into some mice on Windows.
\nCommands are lowercased, underscores are replaced with hyphens, and the APPCOMMAND_ prefix is stripped off. e.g. APPCOMMAND_BROWSER_BACKWARD is emitted as browser-backward.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.on('app-command', (e, cmd) => {\n // Navigate the window back when the user hits their mouse back button\n if (cmd === 'browser-backward' && win.webContents.canGoBack()) {\n win.webContents.goBack()\n }\n})\nThe following app commands are explicitly supported on Linux:
\nbrowser-backwardbrowser-forwardEmitted when scroll wheel event phase has begun.
\nEmitted when scroll wheel event phase has ended.
\nEmitted when scroll wheel event phase filed upon reaching the edge of element.
\nKehrt zurück:
\nevent Eventdirection StringEmitted on 3-finger swipe. Possible directions are up, right, down, left.
The method underlying this event is built to handle older macOS-style trackpad swiping, where the content on the screen doesn't move with the swipe. Most macOS trackpads are not configured to allow this kind of swiping anymore, so in order for it to emit properly the 'Swipe between pages' preference in System Preferences > Trackpad > More Gestures must be set to 'Swipe with two or three fingers'.
Kehrt zurück:
\nevent Eventrotation FloatEmitted on trackpad rotation gesture. Continually emitted until rotation gesture is ended. The rotation value on each emission is the angle in degrees rotated since the last emission. The last emitted event upon a rotation gesture will always be of value 0. Counter-clockwise rotation values are positive, while clockwise ones are negative.
Emitted when the window opens a sheet.
\nEmitted when the window has closed a sheet.
\nEmitted when the native new tab button is clicked.
\nKehrt zurück:
\nevent Eventpoint Point - The screen coordinates the context menu was triggered atEmitted when the system context menu is triggered on the window, this is normally only triggered when the user right clicks on the non-client area of your window. This is the window titlebar or any area you have declared as -webkit-app-region: drag in a frameless window.
Calling event.preventDefault() will prevent the menu from being displayed.
Die BrowserWindow Klasse hat folgende statische Methoden:
BrowserWindow.getAllWindows()Gibt BrowserWindow[] zurück - Ein Array aller geöffneten Browser Fenster.
BrowserWindow.getFocusedWindow()Returns BrowserWindow | null - The window that is focused in this application, otherwise returns null.
BrowserWindow.fromWebContents(webContents)webContents WebContentsReturns BrowserWindow | null - The window that owns the given webContents or null if the contents are not owned by a window.
BrowserWindow.fromBrowserView(browserView)browserView BrowserViewReturns BrowserWindow | null - The window that owns the given browserView. If the given view is not attached to any window, returns null.
BrowserWindow.fromId(id)id IntegerReturns BrowserWindow | null - The window with the given id.
Objekte, die mit new BrowserWindow erstellt wurden, haben folgende Eigenschaften:
const { BrowserWindow } = require('electron')\n// In this example `win` is our instance\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('https://github.com')\nwin.webContents ReadonlyA WebContents object this window owns. All web page related events and operations will be done via it.
See the webContents documentation for its methods and events.
win.id ReadonlyA Integer property representing the unique ID of the window. Each ID is unique among all BrowserWindow instances of the entire Electron application.
win.autoHideMenuBarA Boolean property that determines whether the window menu bar should hide itself automatically. Once set, the menu bar will only show when users press the single Alt key.
If the menu bar is already visible, setting this property to true won't hide it immediately.
win.simpleFullScreenA Boolean property that determines whether the window is in simple (pre-Lion) fullscreen mode.
win.fullScreenA Boolean property that determines whether the window is in fullscreen mode.
win.focusable Windows macOSA Boolean property that determines whether the window is focusable.
win.visibleOnAllWorkspacesA Boolean property that determines whether the window is visible on all workspaces.
Note: Always returns false on Windows.
\nwin.shadowA Boolean property that determines whether the window has a shadow.
win.menuBarVisible Windows LinuxA 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.kioskA Boolean property that determines whether the window is in kiosk mode.
win.documentEdited macOSA 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 macOSA 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.titleA 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.
\nwin.minimizableA Boolean property that determines whether the window can be manually minimized by user.
On Linux the setter is a no-op, although the getter returns true.
win.maximizableA Boolean property that determines whether the window can be manually maximized by user.
On Linux the setter is a no-op, although the getter returns true.
win.fullScreenableA Boolean property that determines whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
win.resizableA Boolean property that determines whether the window can be manually resized by user.
win.closableA Boolean property that determines whether the window can be manually closed by user.
On Linux the setter is a no-op, although the getter returns true.
win.movableA Boolean property that determines Whether the window can be moved by user.
On Linux the setter is a no-op, although the getter returns true.
win.excludedFromShownWindowsMenu macOSA Boolean property that determines whether the window is excluded from the application’s Windows menu. Automatisch false.
const win = new BrowserWindow({ height: 600, width: 600 })\n\nconst template = [\n {\n role: 'windowmenu'\n }\n]\n\nwin.excludedFromShownWindowsMenu = true\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nwin.accessibleTitleA String property that defines an alternative title provided only to accessibility tools such as screen readers. This string is not directly visible to users.
Objekte, die mit new BrowserWindow erstellt wurden, haben folgende Instanzmethoden:
Hinweis: Manche Methoden sind nur auf spezifischen Betriebssystemen verfügbar und sind dementsprechend gekennzeichnet.
\nwin.destroy()Force closing the window, the unload and beforeunload event won't be emitted for the web page, and close event will also not be emitted for this window, but it guarantees the closed event will be emitted.
win.close()Try to close the window. This has the same effect as a user manually clicking the close button of the window. The web page may cancel the close though. See the close event.
\nwin.focus()Focuses on the window.
\nwin.blur()Removes focus from the window.
\nwin.isFocused()Returns Boolean - Whether the window is focused.
win.isDestroyed()Returns Boolean - Whether the window is destroyed.
win.show()Shows and gives focus to the window.
\nwin.showInactive()Shows the window but doesn't focus on it.
\nwin.hide()Hides the window.
\nwin.isVisible()Returns Boolean - Whether the window is visible to the user.
win.isModal()Returns Boolean - Whether current window is a modal window.
win.maximize()Maximizes the window. This will also show (but not focus) the window if it isn't being displayed already.
\nwin.unmaximize()Unmaximizes the window.
\nwin.isMaximized()Returns Boolean - Whether the window is maximized.
win.minimize()Minimizes the window. On some platforms the minimized window will be shown in the Dock.
\nwin.restore()Restores the window from minimized state to its previous state.
\nwin.isMinimized()Returns Boolean - Whether the window is minimized.
win.setFullScreen(flag)flag BooleanSets whether the window should be in fullscreen mode.
\nwin.isFullScreen()Returns Boolean - Whether the window is in fullscreen mode.
win.setSimpleFullScreen(flag) macOSflag BooleanEnters or leaves simple fullscreen mode.
\nSimple fullscreen mode emulates the native fullscreen behavior found in versions of macOS prior to Lion (10.7).
\nwin.isSimpleFullScreen() macOSReturns Boolean - Whether the window is in simple (pre-Lion) fullscreen mode.
win.isNormal()Returns Boolean - Whether the window is in normal state (not maximized, not minimized, not in fullscreen mode).
win.setAspectRatio(aspectRatio[, extraSize])aspectRatio Float - The aspect ratio to maintain for some portion of the content view.extraSize Size (optional) macOS - The extra size not to be included while maintaining the aspect ratio.This will make a window maintain an aspect ratio. The extra size allows a developer to have space, specified in pixels, not included within the aspect ratio calculations. This API already takes into account the difference between a window's size and its content size.
\nConsider a normal window with an HD video player and associated controls. Perhaps there are 15 pixels of controls on the left edge, 25 pixels of controls on the right edge and 50 pixels of controls below the player. In order to maintain a 16:9 aspect ratio (standard aspect ratio for HD @1920x1080) within the player itself we would call this function with arguments of 16/9 and\n{ width: 40, height: 50 }. The second argument doesn't care where the extra width and height are within the content view--only that they exist. Sum any extra width and height areas you have within the overall content view.
\nThe aspect ratio is not respected when window is resized programmatically with APIs like win.setSize.
win.setBackgroundColor(backgroundColor)backgroundColor String - Window's background color as a hexadecimal value, like #66CD00 or #FFF or #80FFFFFF (alpha is supported if transparent is true). Der Standardwert ist #FFF (weiß).Sets the background color of the window. See Setting backgroundColor.
win.previewFile(path[, displayName]) macOSpath String - The absolute path to the file to preview with QuickLook. This is important as Quick Look uses the file name and file extension on the path to determine the content type of the file to open.displayName String (optional) - The name of the file to display on the Quick Look modal view. This is purely visual and does not affect the content type of the file. Standardwert ist path.Uses Quick Look to preview a file at a given path.
\nwin.closeFilePreview() macOSCloses the currently open Quick Look panel.
\nwin.setBounds(bounds[, animate])bounds Partial<Rectangle>animate Boolean (optional) macOSResizes and moves the window to the supplied bounds. Any properties that are not supplied will default to their current values.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\n// set all bounds properties\nwin.setBounds({ x: 440, y: 225, width: 800, height: 600 })\n\n// set a single bounds property\nwin.setBounds({ width: 100 })\n\n// { x: 440, y: 225, width: 100, height: 600 }\nconsole.log(win.getBounds())\nwin.getBounds()Returns Rectangle - The bounds of the window as Object.
win.getBackgroundColor()Returns String - Gets the background color of the window. See Setting backgroundColor.
win.setContentBounds(bounds[, animate])bounds Rectangle Die Grenzen der Ansicht als Rechteckanimate Boolean (optional) macOSResizes and moves the window's client area (e.g. the web page) to the supplied bounds.
\nwin.getContentBounds()Returns Rectangle - The bounds of the window's client area as Object.
win.getNormalBounds()Returns Rectangle - Contains the window bounds of the normal state
Note: whatever the current state of the window : maximized, minimized or in fullscreen, this function always returns the position and size of the window in normal state. In normal state, getBounds and getNormalBounds returns the same Rectangle.
win.setEnabled(enable)enable BooleanDisable or enable the window.
\nwin.isEnabled()Returns Boolean - whether the window is enabled.
win.setSize(width, height[, animate])width Integerheight Integeranimate Boolean (optional) macOSResizes the window to width and height. If width or height are below any set minimum size constraints the window will snap to its minimum size.
win.getSize()Returns Integer[] - Contains the window's width and height.
win.setContentSize(width, height[, animate])width Integerheight Integeranimate Boolean (optional) macOSResizes the window's client area (e.g. the web page) to width and height.
win.getContentSize()Returns Integer[] - Contains the window's client area's width and height.
win.setMinimumSize(width, height)width Integerheight IntegerSets the minimum size of window to width and height.
win.getMinimumSize()Returns Integer[] - Contains the window's minimum width and height.
win.setMaximumSize(width, height)width Integerheight IntegerSets the maximum size of window to width and height.
win.getMaximumSize()Returns Integer[] - Contains the window's maximum width and height.
win.setResizable(resizable)resizable BooleanSets whether the window can be manually resized by the user.
\nwin.isResizable()Returns Boolean - Whether the window can be manually resized by the user.
win.setMovable(movable) macOS Windowsmovable BooleanSets whether the window can be moved by user. On Linux does nothing.
\nwin.isMovable() macOS WindowsReturns Boolean - Whether the window can be moved by user.
Unter Linux wird immer true zurückgegeben.
win.setMinimizable(minimizable) macOS Windowsminimizable BooleanSets whether the window can be manually minimized by user. On Linux does nothing.
\nwin.isMinimizable() macOS WindowsReturns Boolean - Whether the window can be manually minimized by the user.
Unter Linux wird immer true zurückgegeben.
win.setMaximizable(maximizable) macOS Windowsmaximizable BooleanSets whether the window can be manually maximized by user. On Linux does nothing.
\nwin.isMaximizable() macOS WindowsReturns Boolean - Whether the window can be manually maximized by user.
Unter Linux wird immer true zurückgegeben.
win.setFullScreenable(fullscreenable)fullscreenable BooleanSets whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
\nwin.isFullScreenable()Returns Boolean - Whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
win.setClosable(closable) macOS Windowsclosable BooleanSets whether the window can be manually closed by user. On Linux does nothing.
\nwin.isClosable() macOS WindowsGibt Boolean zurück - Gibt an ob das Fenster durch den Nutzer manuell geschlossen werden kann.
Unter Linux wird immer true zurückgegeben.
win.setAlwaysOnTop(flag[, level][, relativeLevel])flag Booleanlevel String (optional) macOS Windows - Values include normal, floating, torn-off-menu, modal-panel, main-menu, status, pop-up-menu, screen-saver, and dockfloating when flag is true. The level is reset to normal when the flag is false. Note that from floating to status included, the window is placed below the Dock on macOS and below the taskbar on Windows. From pop-up-menu to a higher it is shown above the Dock on macOS and above the taskbar on Windows. See the macOS docs for more details.relativeLevel Integer (optional) macOS - The number of layers higher to set this window relative to the given level. The default is 0. Note that Apple discourages setting levels higher than 1 above screen-saver.Sets whether the window should show always on top of other windows. After setting this, the window is still a normal window, not a toolbox window which can not be focused on.
\nwin.isAlwaysOnTop()Returns Boolean - Whether the window is always on top of other windows.
win.moveAbove(mediaSourceId)mediaSourceId String - Window id in the format of DesktopCapturerSource's id. For example \"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()Moves window to top(z-order) regardless of focus
\nwin.center()Moves window to the center of the screen.
\nwin.setPosition(x, y[, animate])x Integery Integeranimate Boolean (optional) macOSMoves window to x and y.
win.getPosition()Returns Integer[] - Contains the window's current position.
win.setTitle(title)title StringChanges the title of native window to title.
win.getTitle()Returns String - The title of the native window.
Note: The title of the web page can be different from the title of the native window.
\nwin.setSheetOffset(offsetY[, offsetX]) macOSoffsetY FloatoffsetX Float (optional)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. Ein Beispiel:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nconst toolbarRect = document.getElementById('toolbar').getBoundingClientRect()\nwin.setSheetOffset(toolbarRect.height)\nwin.flashFrame(flag)flag BooleanStarts or stops flashing the window to attract user's attention.
\nwin.setSkipTaskbar(skip)skip BooleanMakes the window not show in the taskbar.
\nwin.setKiosk(flag)flag BooleanEnters or leaves kiosk mode.
\nwin.isKiosk()Returns Boolean - Whether the window is in kiosk mode.
win.isTabletMode() WindowsReturns Boolean - Whether the window is in Windows 10 tablet mode.
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.
\nThis API returns whether the window is in tablet mode, and the resize event can be be used to listen to changes to tablet mode.
win.getMediaSourceId()Returns String - Window id in the format of DesktopCapturerSource's id. For example \"window:1324:0\".
More precisely the format is window:id:other_id where id is HWND on Windows, CGWindowID (uint64_t) on macOS and Window (unsigned long) on Linux. other_id is used to identify web contents (tabs) so within the same top level window.
win.getNativeWindowHandle()Returns Buffer - The platform-specific handle of the window.
The native type of the handle is HWND on Windows, NSView* on macOS, and Window (unsigned long) on Linux.
win.hookWindowMessage(message, callback) Windowsmessage Integercallback FunctionwParam any - The wParam provided to the WndProclParam any - The lParam provided to the WndProcHooks a windows message. The callback is called when the message is received in the WndProc.
win.isWindowMessageHooked(message) Windowsmessage IntegerReturns Boolean - true or false depending on whether the message is hooked.
win.unhookWindowMessage(message) Windowsmessage IntegerUnhook the window message.
\nwin.unhookAllWindowMessages() WindowsUnhooks all of the window messages.
\nwin.setRepresentedFilename(filename) macOSfilename StringSets the pathname of the file the window represents, and the icon of the file will show in window's title bar.
\nwin.getRepresentedFilename() macOSReturns String - The pathname of the file the window represents.
win.setDocumentEdited(edited) macOSedited BooleanSpecifies whether the window’s document has been edited, and the icon in title bar will become gray when set to true.
win.isDocumentEdited() macOSReturns Boolean - Whether the window's document has been edited.
win.focusOnWebView()win.blurWebView()win.capturePage([rect])rect Rectangle (optional) - The bounds to captureReturns Promise<NativeImage> - Resolves with a NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page. If the page is not visible, rect may be empty.
win.loadURL(url[, options])url Stringoptions Object (optional)httpReferrer (String | Referrer) (optional) - An HTTP Referrer URL.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base URL (with trailing path separator) for files to be loaded by the data URL. This is needed only if the specified url is a data URL and needs to load other files.Gibt Promise zurück - das Versprechen wird aufgelöst, wenn die Seite das Laden beendet hat (siehe did-finish-load), und lehnt ab, wenn die Seite nicht geladen wird (siehe did-fail-load).
Same as webContents.loadURL(url[, options]).
The url can be a remote address (e.g. http://) or a path to a local HTML file using the file:// protocol.
To ensure that file URLs are properly formatted, it is recommended to use Node's url.format method:
const url = require('url').format({\n protocol: 'file',\n slashes: true,\n pathname: require('path').join(__dirname, 'index.html')\n})\n\nwin.loadURL(url)\nYou can load a URL using a POST request with URL-encoded data by doing the following:
win.loadURL('http://localhost:8000/post', {\n postData: [{\n type: 'rawData',\n bytes: Buffer.from('hello=world')\n }],\n extraHeaders: 'Content-Type: application/x-www-form-urlencoded'\n})\nwin.loadFile(filePath[, options])filePath Stringoptions Object (optional)query Record<String, String> (optional) - Passed to url.format().search String (optional) - Passed to url.format().hash String (optional) - Passed to url.format().Gibt Promise zurück - das Versprechen wird aufgelöst, wenn die Seite das Laden beendet hat (siehe did-finish-load), und lehnt ab, wenn die Seite nicht geladen wird (siehe did-fail-load).
Same as webContents.loadFile, filePath should be a path to an HTML file relative to the root of your application. See the webContents docs for more information.
win.reload()Same as webContents.reload.
win.setMenu(menu) Linux Windowsmenu Menu | nullSets the menu as the window's menu bar.
win.removeMenu() Linux WindowsRemove the window's menu bar.
\nwin.setProgressBar(progress[, options])progress Doubleoptions Object (optional)mode String Windows - Mode for the progress bar. Can be none, normal, indeterminate, error or paused.Sets progress value in progress bar. Valid range is [0, 1.0].
\nRemove progress bar when progress < 0; Change to indeterminate mode when progress > 1.
\nOn Linux platform, only supports Unity desktop environment, you need to specify the *.desktop file name to desktopName field in package.json. By default, it will assume {app.name}.desktop.
On Windows, a mode can be passed. Accepted values are none, normal, indeterminate, error, and paused. If you call setProgressBar without a mode set (but with a value within the valid range), normal will be assumed.
win.setOverlayIcon(overlay, description) Windowsoverlay NativeImage | null - the icon to display on the bottom right corner of the taskbar icon. If this parameter is null, the overlay is cleareddescription String - a description that will be provided to Accessibility screen readersSets a 16 x 16 pixel overlay onto the current taskbar icon, usually used to convey some sort of application status or to passively notify the user.
\nwin.setHasShadow(hasShadow)hasShadow BooleanSets whether the window should have a shadow.
\nwin.hasShadow()Returns Boolean - Whether the window has a shadow.
win.setOpacity(opacity) Windows macOSopacity Number - between 0.0 (fully transparent) and 1.0 (fully opaque)Sets the opacity of the window. On Linux, does nothing. Out of bound number values are clamped to the [0, 1] range.
\nwin.getOpacity()Returns Number - between 0.0 (fully transparent) and 1.0 (fully opaque). On Linux, always returns 1.
win.setShape(rects) Windows Linux Experimentalrects Rectangle[] - Sets a shape on the window. Passing an empty list reverts the window to being rectangular.Setting a window shape determines the area within the window where the system permits drawing and user interaction. Outside of the given region, no pixels will be drawn and no mouse events will be registered. Mouse events outside of the region will not be received by that window, but will fall through to whatever is behind the window.
\nwin.setThumbarButtons(buttons) Windowsbuttons ThumbarButton[]Returns Boolean - Whether the buttons were added successfully
Add a thumbnail toolbar with a specified set of buttons to the thumbnail image of a window in a taskbar button layout. Returns a Boolean object indicates whether the thumbnail has been added successfully.
The number of buttons in thumbnail toolbar should be no greater than 7 due to the limited room. Once you setup the thumbnail toolbar, the toolbar cannot be removed due to the platform's limitation. But you can call the API with an empty array to clean the buttons.
\nbuttons ist ein Array mit Button Objekten:
Button ObjectIcon NativeImage -das Symbol zeigt in Thumbnail Leiste.Klicken Sie auf FunktionTooltip String (optional)-der Text der Tooltip der Schaltfläche.flags String - Kontrollieren Sie bestimmte Zustände und Verhaltensweisen des Buttons. Standardmäßig ist es ['enabled'].Die Flags ist ein Array, das folgende Zeichenfolge s enthalten kann:
Enabled-die Schaltfläche ist aktiv und für den Benutzer verfügbar.disabled - Der Button ist deaktiviert. Er ist vorhanden, zeigt aber visuell, dass er nicht auf Nutzeraktionen reagiert.dismissonclick-wenn auf die Schaltfläche geklickt wird, wird das Thumbnail-Fenster geschlossen sofort.nobackground-zeichnen Sie keinen Schaltflächenrahmen, sondern verwenden Sie nur das Bild.Hidden-die Schaltfläche wird dem Benutzer nicht angezeigt.noninteractive - Der Button ist aktiviert aber nicht interaktiv. Es wird kein gedrückter Button angezeigt. Dieser Wert ist für Instanzen bestimmt, in denen der Button in einer Benachrichtigung verwendet wird.win.setThumbnailClip(region) Windowsregion Rectangle - Region of the windowSets the region of the window to show as the thumbnail image displayed when hovering over the window in the taskbar. You can reset the thumbnail to be the entire window by specifying an empty region: { x: 0, y: 0, width: 0, height: 0 }.
win.setThumbnailToolTip(toolTip) WindowstoolTip StringSets the toolTip that is displayed when hovering over the window thumbnail in the taskbar.
\nwin.setAppDetails(options) Windowsoptions ObjektappId String (optional) - Window's App User Model ID. It has to be set, otherwise the other options will have no effect.appIconPath String (optional) - Window's Relaunch Icon.appIconIndex Integer (optional) - Index of the icon in appIconPath. Ignored when appIconPath is not set. Standard ist 0.relaunchCommand String (optional) - Window's Relaunch Command.relaunchDisplayName String (optional) - Window's Relaunch Display Name.Sets the properties for the window's taskbar button.
\nNote: relaunchCommand and relaunchDisplayName must always be set together. If one of those properties is not set, then neither will be used.
win.showDefinitionForSelection() macOSSame as webContents.showDefinitionForSelection().
win.setIcon(icon) Windows Linuxicon NativeImage | StringChanges window icon.
\nwin.setWindowButtonVisibility(visible) macOSvisible BooleanSets whether the window traffic light buttons should be visible.
\nwin.setAutoHideMenuBar(hide)hide BooleanSets whether the window menu bar should hide itself automatically. 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()Returns Boolean - Whether menu bar automatically hides itself.
win.setMenuBarVisibility(visible) Windows Linuxvisible BooleanSets whether the menu bar should be visible. If the menu bar is auto-hide, users can still bring up the menu bar by pressing the single Alt key.
win.isMenuBarVisible()Returns Boolean - Whether the menu bar is visible.
win.setVisibleOnAllWorkspaces(visible[, options])visible Booleanoptions Object (optional)visibleOnFullScreen Boolean (optional) macOS - Sets whether the window should be visible above fullscreen windows.skipTransformProcessType Boolean (optional) macOS - Calling setVisibleOnAllWorkspaces will by default transform the process type between UIElementApplication and ForegroundApplication to ensure the correct behavior. However, this will hide the window and dock for a short time every time it is called. If your window is already of type UIElementApplication, you can bypass this transformation by passing true to skipTransformProcessType.Sets whether the window should be visible on all workspaces.
\nNote: This API does nothing on Windows.
\nwin.isVisibleOnAllWorkspaces()Returns Boolean - Whether the window is visible on all workspaces.
Note: This API always returns false on Windows.
\nwin.setIgnoreMouseEvents(ignore[, options])ignore Booleanoptions Object (optional)forward Boolean (optional) macOS Windows - If true, forwards mouse move messages to Chromium, enabling mouse related events such as mouseleave. Only used when ignore is true. If ignore is false, forwarding is always disabled regardless of this value.Makes the window ignore all mouse events.
\nAll mouse events happened in this window will be passed to the window below this window, but if this window has focus, it will still receive keyboard events.
\nwin.setContentProtection(enable) macOS Windowsenable BooleanPrevents the window contents from being captured by other apps.
\nOn 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 Windowsfocusable BooleanChanges whether the window can be focused.
\nOn macOS it does not remove the focus from the window.
\nwin.isFocusable() macOS WindowsReturns whether the window can be focused.
\nwin.setParentWindow(parent)parent BrowserWindow | nullSets parent as current window's parent window, passing null will turn current window into a top-level window.
win.getParentWindow()Returns BrowserWindow - The parent window.
win.getChildWindows()Returns BrowserWindow[] - All child windows.
win.setAutoHideCursor(autoHide) macOSautoHide BooleanControls whether to hide cursor when typing.
\nwin.selectPreviousTab() macOSSelects the previous tab when native tabs are enabled and there are other tabs in the window.
\nwin.selectNextTab() macOSSelects the next tab when native tabs are enabled and there are other tabs in the window.
\nwin.mergeAllWindows() macOSMerges all windows into one window with multiple tabs when native tabs are enabled and there is more than one open window.
\nwin.moveTabToNewWindow() macOSMoves the current tab into a new window if native tabs are enabled and there is more than one tab in the current window.
\nwin.toggleTabBar() macOSToggles the visibility of the tab bar if native tabs are enabled and there is only one tab in the current window.
\nwin.addTabbedWindow(browserWindow) macOSbrowserWindow BrowserWindowAdds a window as a tab on this window, after the tab for the window instance.
\nwin.setVibrancy(type) macOStype String | null - Can be appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, or under-page. See the macOS documentation for more details.Adds a vibrancy effect to the browser window. Passing null or an empty string will remove the vibrancy effect on the window.
Note that appearance-based, light, dark, medium-light, and ultra-dark have been deprecated and will be removed in an upcoming version of macOS.
win.setTrafficLightPosition(position) macOSposition PointSet a custom position for the traffic light buttons in frameless window.
\nwin.getTrafficLightPosition() macOSReturns Point - The custom position for the traffic light buttons in frameless window.
win.setTouchBar(touchBar) macOStouchBar TouchBar | nullSets the touchBar layout for the current window. Specifying null or undefined clears the touch bar. This method only has an effect if the machine has a touch bar and is running on macOS 10.12.1+.
Note: The TouchBar API is currently experimental and may change or be removed in future Electron releases.
\nwin.setBrowserView(browserView) ExperimentalbrowserView BrowserView | null - Attach browserView to win. If there are other BrowserViews attached, they will be removed from this window.win.getBrowserView() ExperimentalReturns BrowserView | null - The BrowserView attached to win. Returns null if one is not attached. Throws an error if multiple BrowserViews are attached.
win.addBrowserView(browserView) ExperimentalbrowserView BrowserViewReplacement API for setBrowserView supporting work with multi browser views.
\nwin.removeBrowserView(browserView) ExperimentalbrowserView BrowserViewwin.setTopBrowserView(browserView) ExperimentalbrowserView BrowserViewRaises browserView above other BrowserViews attached to win. Throws an error if browserView is not attached to win.
win.getBrowserViews() ExperimentalReturns BrowserView[] - an array of all BrowserViews that have been attached with addBrowserView or setBrowserView.
Note: The BrowserView API is currently experimental and may change or be removed in future Electron releases.
", "title": "Browserfenster", "description": "Erstellung und Steuerung von Browserfenstern." }, "/docs/api/browser-window-proxy": { "locale": "de-DE", "slug": "browser-window-proxy", "href": "/docs/api/browser-window-proxy", "crowdinFileId": "256285", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/browser-window-proxy.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nManipulate the child browser window
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The BrowserWindowProxy object is returned from window.open and provides limited functionality with the child window.
Das BrowserWindowProxy Objekt hat die folgenden Instanz Methoden:
win.blur()Removes focus from the child window.
\nwin.close()Forcefully closes the child window without calling its unload event.
\nwin.eval(code)code ZeichenketteEvaluates the code in the child window.
\nwin.focus()Focuses the child window (brings the window to front).
\nwin.print()Invokes the print dialog on the child window.
\nwin.postMessage(message, targetOrigin)message anytargetOrigin ZeichenketteSends a message to the child window with the specified origin or * for no origin preference.
In addition to these methods, the child window implements window.opener object with no properties and a single method.
The BrowserWindowProxy object has the following instance properties:
win.closedA Boolean that is set to true after the child window gets closed.
Follow the guidelines below for building Electron itself, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nCheck the build prerequisites for your platform before proceeding
\n\nElectron's Build Tools automate much of the setup for compiling Electron from source with different configurations and build targets. If you wish to set up the environment manually, the instructions are listed below.
\nYou'll need to install depot_tools, the toolset used for fetching Chromium and its dependencies.
Also, on Windows, you'll need to set the environment variable DEPOT_TOOLS_WIN_TOOLCHAIN=0. To do so, open Control Panel → System and Security → System → Advanced system settings and add a system variable DEPOT_TOOLS_WIN_TOOLCHAIN with value 0. This tells depot_tools to use your locally installed version of Visual Studio (by default, depot_tools will try to download a Google-internal version that only Googlers have access to).
If you plan on checking out Electron more than once (for example, to have multiple parallel directories checked out to different branches), using the git cache will speed up subsequent calls to gclient. To do this, set a GIT_CACHE_PATH environment variable:
$ export GIT_CACHE_PATH=\"${HOME}/.git_cache\"\n$ mkdir -p \"${GIT_CACHE_PATH}\"\n# This will use about 16G.\n$ mkdir electron && cd electron\n$ gclient config --name \"src/electron\" --unmanaged https://github.com/electron/electron\n$ gclient sync --with_branch_heads --with_tags\n# This will take a while, go get a coffee.\n\n\nInstead of
\nhttps://github.com/electron/electron, you can use your own fork here (something likehttps://github.com/<username>/electron).
If you intend to git pull or git push from the official electron repository in the future, you now need to update the respective folder's origin URLs.
$ cd src/electron\n$ git remote remove origin\n$ git remote add origin https://github.com/electron/electron\n$ git checkout main\n$ git branch --set-upstream-to=origin/main\n$ cd -\n📝 gclient works by checking a file called DEPS inside the src/electron folder for dependencies (like Chromium or Node.js). Running gclient sync -f ensures that all dependencies required to build Electron match that file.
So, in order to pull, you'd run the following commands:
\n$ cd src/electron\n$ git pull\n$ gclient sync -f\n$ cd src\n$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nOr on Windows (without the optional argument):
\n$ cd src\n$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\\buildtools\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\")\"\nThis will generate a build directory out/Testing under src/ with the testing build configuration. You can replace Testing with another name, but it should be a subdirectory of out. Also you shouldn't have to run gn gen again—if you want to change the build arguments, you can run gn args out/Testing to bring up an editor.
To see the list of available build configuration options, run gn args out/Testing --list.
For generating Testing build config of Electron:
\n$ gn gen out/Testing --args=\"import(\\\"//electron/build/args/testing.gn\\\") $GN_EXTRA_ARGS\"\nFor generating Release (aka \"non-component\" or \"static\") build config of Electron:
\n$ gn gen out/Release --args=\"import(\\\"//electron/build/args/release.gn\\\") $GN_EXTRA_ARGS\"\nTo build, run ninja with the electron target: Nota Bene: This will also take a while and probably heat up your lap.
For the testing configuration:
\n$ ninja -C out/Testing electron\nFor the release configuration:
\n$ ninja -C out/Release electron\nThis will build all of what was previously 'libchromiumcontent' (i.e. the content/ directory of chromium and its dependencies, incl. WebKit and V8), so it will take a while.
The built executable will be under ./out/Testing:
$ ./out/Testing/Electron.app/Contents/MacOS/Electron\n# or, on Windows\n$ ./out/Testing/electron.exe\n# or, on Linux\n$ ./out/Testing/electron\nOn linux, first strip the debugging and symbol information:
\nelectron/script/strip-binaries.py -d out/Release\nTo package the electron build as a distributable zip file:
\nninja -C out/Release electron:electron_dist_zip\nTo compile for a platform that isn't the same as the one you're building on, set the target_cpu and target_os GN arguments. For example, to compile an x86 target from an x64 host, specify target_cpu = \"x86\" in gn args.
$ gn gen out/Testing-x86 --args='... target_cpu = \"x86\"'\nNicht alle Kombinationen von Quell- und Ziel-Prozessor/Betriebssystem werden von Chromium unterstützt.
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Host | Ziel | Status |
|---|---|---|
| Windows x64 | Windows arm64 | Experimental |
| Windows x64 | Windows x86 | Automatisch getestet |
| Linux x64 | Linux x86 | Automatisch getestet |
Wenn Sie andere Kombinationen testen und diese funktionieren aktualisieren Sie bitte dieses Dokument :)
\nSee the GN reference for allowable values of target_os and target_cpu.
Um Windows auf Arm zu kompilieren, folgen Siedem Chromium-Guide um die notwendigen Abhängigkeiten, SDK und Bibliotheken zu erhalten, und bauen Sie dann mit ELECTRON_BUILDING_WOA=1 in Ihrer Umgebung, bevor Sie gclient syncausführen.
set ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nOder (wenn Sie PowerShell benutzen):
\n$env:ELECTRON_BUILDING_WOA=1\ngclient sync -f --with_branch_heads --with_tags\nAls nächstes führe gn gen aus wie oben mit target_cpu=\"arm64\".
Um die Tests durchzuführen, müssen Sie zuerst die Testmodule gegen die gleiche Version von Node.js bauen, die als Teil des Build-Prozesses gebaut wurde. Um Build Header für die Module zu kompilieren, führen Sie folgende Befehle in dem src/ Verzeichnis aus.
$ ninja -C out/Testing third_party/electron_node:headers\nYou can now run the tests.
\nWenn Sie etwas debuggen kann es hilfreich sein einige zusätzlichen Flaggen zu der Electron Binärdatei zu übergeben:
\n$ npm run test -- \\\n --enable-logging -g 'BrowserWindow module'\nIt is possible to share the gclient git cache with other machines by exporting it as SMB share on linux, but only one process/machine can be using the cache at a time. The locks created by git-cache script will try to prevent this, but it may not work perfectly in a network.
\nOn Windows, SMBv2 has a directory cache that will cause problems with the git cache script, so it is necessary to disable it by setting the registry key
\nHKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\\DirectoryCacheLifetime\nto 0. More information: https://stackoverflow.com/a/9935126
\nThis can be set quickly in powershell (ran as administrator):
\nNew-ItemProperty -Path \"HKLM:\\System\\CurrentControlSet\\Services\\Lanmanworkstation\\Parameters\" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force\nIf gclient sync is interrupted the git tree may be left in a bad state, leading to a cryptic message when running gclient sync in the future:
2> Conflict while rebasing this branch.\n2> Fix the conflict and run gclient again.\n2> See man git-rebase for details.\nIf there are no git conflicts or rebases in src/electron, you may need to abort a git am in src:
$ cd ../\n$ git am --abort\n$ cd electron\n$ gclient sync -f\nIf you see a prompt for Username for 'https://chrome-internal.googlesource.com': when running gclient sync on Windows, it's probably because the DEPOT_TOOLS_WIN_TOOLCHAIN environment variable is not set to 0. Open Control Panel → System and Security → System → Advanced system settings and add a system variable DEPOT_TOOLS_WIN_TOOLCHAIN with value 0. This tells depot_tools to use your locally installed version of Visual Studio (by default, depot_tools will try to download a Google-internal version that only Googlers have access to).
Follow the guidelines below for building Electron itself on Linux, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nAt least 25GB disk space and 8GB RAM.
\nPython 2.7.x. Some distributions like CentOS 6.x still use Python 2.6.x so you may need to check your Python version with python -V.
Please also ensure that your system and Python version support at least TLS 1.2. For a quick test, run the following script:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, use your system's package manager to update Python to the latest version in the 2.7.x branch. Alternatively, visit https://www.python.org/downloads/ for detailed instructions.
\nNode.js. There are various ways to install Node. You can download source code from nodejs.org and compile it. Doing so permits installing Node on your own home directory as a standard user. Or try repositories such as NodeSource.
\nclang 3.4 or later.
\nDevelopment headers of GTK 3 and libnotify.
\nOn Ubuntu, install the following libraries:
\n$ sudo apt-get install build-essential clang libdbus-1-dev libgtk-3-dev \\\n libnotify-dev libgnome-keyring-dev \\\n libasound2-dev libcap-dev libcups2-dev libxtst-dev \\\n libxss1 libnss3-dev gcc-multilib g++-multilib curl \\\n gperf bison python-dbusmock openjdk-8-jre\nOn RHEL / CentOS, install the following libraries:
\n$ sudo yum install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Fedora, install the following libraries:
\n$ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \\\n libgnome-keyring-devel xorg-x11-server-utils libcap-devel \\\n cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \\\n nss-devel python-dbusmock openjdk-8-jre\nOn Arch Linux / Manjaro, install the following libraries:
\n$ sudo pacman -Syu base-devel clang libdbus gtk2 libnotify \\\n libgnome-keyring alsa-lib libcap libcups libxtst \\\n libxss nss gcc-multilib curl gperf bison \\\n python2 python-dbusmock jdk8-openjdk\nOther distributions may offer similar packages for installation via package managers such as pacman. Or one can compile from source code.
\nIf you want to build for an arm target you should also install the following dependencies:
$ sudo apt-get install libc6-dev-armhf-cross linux-libc-dev-armhf-cross \\\n g++-arm-linux-gnueabihf\nSimilarly for arm64, install the following:
$ sudo apt-get install libc6-dev-arm64-cross linux-libc-dev-arm64-cross \\\n g++-aarch64-linux-gnu\nAnd to cross-compile for arm or ia32 targets, you should pass the target_cpu parameter to gn gen:
$ gn gen out/Testing --args='import(...) target_cpu=\"arm\"'\nPrebuilt clang will try to link to libtinfo.so.5. Depending on the host architecture, symlink to appropriate libncurses:
$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5\nThe default building configuration is targeted for major desktop Linux distributions. To build for a specific distribution or device, the following information may help you.
\nclang instead of downloaded clang binariesBy default Electron is built with prebuilt clang binaries provided by the Chromium project. If for some reason you want to build with the clang installed in your system, you can specify the clang_base_path argument in the GN args.
For example if you installed clang under /usr/local/bin/clang:
$ gn gen out/Testing --args='import(\"//electron/build/args/testing.gn\") clang_base_path = \"/usr/local/bin\"'\nclangBuilding Electron with compilers other than clang is not supported.
Follow the guidelines below for building Electron itself on macOS, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nPlease also ensure that your system and Python version support at least TLS 1.2. This depends on both your version of macOS and Python. For a quick test, run:
\n$ npx @electron/check-python-tls\nIf the script returns that your configuration is using an outdated security protocol, you can either update macOS to High Sierra or install a new version of Python 2.7.x. To upgrade Python, use Homebrew:
\n$ brew install python@2 && brew link python@2 --force\nIf you are using Python as provided by Homebrew, you also need to install the following Python modules:
\nSie können pip verwenden, um es zu installieren:
$ pip install pyobjc\nWenn Sie Electron entwickeln und nicht vorhaben Ihre Version zu verteilen, können sie diesen Abschnitt überspringen.
\nOfficial Electron builds are built with Xcode 12.2, and the macOS 11.0 SDK. Das Erstellen der Software mit einem neueren SDK funktioniert ebenfalls, aber die veröffentlichten Versionen verwenden derzeit das 11.0 SDK.
\nSiehe Build Instruktionen: GN.
", "title": "Build Anweisungen (macOS)", "description": "" }, "/docs/development/build-instructions-windows": { "locale": "de-DE", "slug": "build-instructions-windows", "href": "/docs/development/build-instructions-windows", "crowdinFileId": "256137", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/build-instructions-windows.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Follow the guidelines below for building Electron itself on Windows, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.
\nvs2019_install = DRIVE:\\path\\to\\Microsoft Visual Studio\\2019\\Community, replacing 2019 and Community with your installed versions and replacing DRIVE: with the drive that Visual Studio is on. Often, this will be C:.WINDOWSSDKDIR = DRIVE:\\path\\to\\Windows Kits\\10, replacing DRIVE: with the drive that Windows Kits is on. Often, this will be C:.symstore.exe is used for creating a symbol store from .pdb files.Modify → Individual Components, scroll down and select the appropriate Windows SDK to install. Another option would be to look at the Windows SDK and emulator archive and download the standalone version of the SDK respectively.Control Panel → Programs → Programs and Features → Select the \"Windows Software Development Kit\" → Change → Change → Check \"Debugging Tools For Windows\" → Change. Or, you can download the standalone SDK installer and use it to install the Debugging Tools.If you don't currently have a Windows installation, dev.microsoftedge.com has timebombed versions of Windows that you can use to build Electron.
\nBuilding Electron is done entirely with command-line scripts and cannot be done with Visual Studio. You can develop Electron with any editor but support for building with Visual Studio will come in the future.
\nNote: Even though Visual Studio is not used for building, it's still required because we need the build toolchains it provides.
\nWindows Security doesn't like one of the files in the Chromium source code (see https://crbug.com/441184), so it will constantly delete it, causing gclient sync issues. You can exclude the source tree from being monitored by Windows Security by following these instructions.
To build for the 32bit target, you need to pass target_cpu = \"x86\" as a GN arg. You can build the 32bit target alongside the 64bit target by using a different output directory for GN, e.g. out/Release-x86, with different arguments.
$ gn gen out/Release-x86 --args=\"import(\\\"//electron/build/args/release.gn\\\") target_cpu=\\\"x86\\\"\"\nThe other building steps are exactly the same.
\nTo generate a Visual Studio project, you can pass the --ide=vs2017 parameter to gn gen:
$ gn gen out/Testing --ide=vs2017\nIf you encountered an error like Command xxxx not found, you may try to use the VS2015 Command Prompt console to execute the build scripts.
Stellen Sie sicher, dass Sie die neueste Visual Studio Version installiert haben.
\nTry reinstalling 32bit Node.js.
\nCreating that directory should fix the problem:
\n$ mkdir ~\\AppData\\Roaming\\npm\nYou may get this error if you are using Git Bash for building, you should use PowerShell or VS2015 Command Prompt instead.
\nnode.js has some extremely long pathnames, and by default git on windows doesn't handle long pathnames correctly (even though windows supports them). This should fix it:
\n$ git config --system core.longpaths true\nThis can happen during build, when Debugging Tools for Windows has been installed with Windows Driver Kit. Uninstall Windows Driver Kit and install Debugging Tools with steps described above.
\nMake sure you have installed pywin32 with pip install pywin32.
This bug is a \"feature\" of Windows' command prompt. It happens when clicking inside the prompt window with QuickEdit enabled and is intended to allow selecting and copying output text easily. Since each accidental click will pause the build process, you might want to disable this feature in the command prompt properties.
Electron uses GN for project generation and ninja for building. Projektkonfigurationen können in Dateien mit .gn und.gni Endung gefunden werden.
The following gn files contain the main rules for building Electron:
BUILD.gn defines how Electron itself is built and includes the default configurations for linking with Chromium.build/args/{debug,release,all}.gn contain the default build arguments for building Electron.Since Chromium is quite a large project, the final linking stage can take quite a few minutes, which makes it hard for development. In order to solve this, Chromium introduced the \"component build\", which builds each component as a separate shared library, making linking very quick but sacrificing file size and performance.
\nElectron inherits this build option from Chromium. In Debug builds, the binary will be linked to a shared library version of Chromium's components to achieve fast linking time; for Release builds, the binary will be linked to the static library versions, so we can have the best possible binary size and performance.
NB this section is out of date and contains information that is no longer relevant to the GN-built electron.
\nTest your changes conform to the project coding style using:
\n$ npm run lint\nTest functionality using:
\n$ npm test\nWhenever you make changes to Electron source code, you'll need to re-run the build before the tests:
\n$ npm run build && npm test\nYou can make the test suite run faster by isolating the specific test or block you're currently working on using Mocha's exclusive tests feature. Append .only to any describe or it function call:
describe.only('some feature', () => {\n // ... only tests in this block will be run\n})\nAlternatively, you can use mocha's grep option to only run tests matching the given regular expression pattern:
$ npm test -- --grep child_process\nTests that include native modules (e.g. runas) can't be executed with the debug build (see #2558 for details), but they will work with the release build.
To run the tests with the release build use:
\n$ npm test -- -R\ndata String - PEM encoded dataissuer CertificatePrincipal - Issuer principalissuerName String - Issuer's Common NameissuerCert Certificate - Issuer certificate (if not self-signed)subject CertificatePrincipal - Subject principalsubjectName String - Subject's Common NameserialNumber String - Hex value represented stringvalidStart Number - Start date of the certificate being valid in secondsvalidExpiry Number - End date of the certificate being valid in secondsfingerprint String - Fingerprint of the certificatecommonName String - Common Name.organizations String[] - Organization names.organizationUnits String[] - Organization Unit names.locality String - Locality.state String - State or province.country String - Country or region.\n\nA collection of resources for learning about Chromium and tracking its development
\n
See also V8 Development
", "title": "Chromium-Entwicklung", "description": "A collection of resources for learning about Chromium and tracking its development" }, "/docs/development/clang-format": { "locale": "de-DE", "slug": "clang-format", "href": "/docs/development/clang-format", "crowdinFileId": "256143", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/clang-format.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "clang-format is a tool to automatically format C/C++/Objective-C code, so that developers don't need to worry about style issues during code reviews.
It is highly recommended to format your changed C++ code before opening pull requests, which will save you and the reviewers' time.
\nYou can install clang-format and git-clang-format via npm install -g clang-format.
To automatically format a file according to Electron C++ code style, run clang-format -i path/to/electron/file.cc. It should work on macOS/Linux/Windows.
The workflow to format your changed code:
\ngit add your_changed_file.cc aus.git-clang-format, and you will probably see modifications in your_changed_file.cc, these modifications are generated from clang-format.git add your_changed_file.cc, and commit your change.If you want to format the changed code on your latest git commit (HEAD), you can run git-clang-format HEAD~1. See git-clang-format -h for more details.
You can also integrate clang-format directly into your favorite editors. For further guidance on setting up editor integration, see these pages:
clang-tidy is a tool to automatically check C/C++/Objective-C code for style violations, programming errors, and best practices.
Electron's clang-tidy integration is provided as a linter script which can be run with npm run lint:clang-tidy. While clang-tidy checks your on-disk files, you need to have built Electron so that it knows which compiler flags were used. There is one required option for the script --output-dir, which tells the script which build directory to pull the compilation information from. A typical usage would be: npm run lint:clang-tidy --out-dir ../out/Testing
With no filenames provided, all C/C++/Objective-C files will be checked. You can provide a list of files to be checked by passing the filenames after the options: npm run lint:clang-tidy --out-dir ../out/Testing shell/browser/api/electron_api_app.cc
While clang-tidy has a long list of possible checks, in Electron only a few are enabled by default. At the moment Electron doesn't have a .clang-tidy config, so clang-tidy will find the one from Chromium at src/.clang-tidy and use the checks which Chromium has enabled. You can change which checks are run by using the --checks= option. This is passed straight through to clang-tidy, so see its documentation for full details. Wildcards can be used, and checks can be disabled by prefixing a -. By default any checks listed are added to those in .clang-tidy, so if you'd like to limit the checks to specific ones you should first exclude all checks then add back what you want, like --checks=-*,performance*.
Running clang-tidy is rather slow - internally it compiles each file and then runs the checks so it will always be some factor slower than compilation. While you can use parallel runs to speed it up using the --jobs|-j option, clang-tidy also uses a lot of memory during its checks, so it can easily run into out-of-memory errors. As such the default number of jobs is one.
\n\nTätigen von HTTP/HTTPS anfragen.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
ClientRequest implementiert die Writable Stream-Schnittstelle und ist somit ein EventEmitter.
new ClientRequest(options)options (Object | String) - If options is a String, it is interpreted as the request URL. If it is an object, it is expected to fully specify an HTTP request via the following properties:method String (optional) - The HTTP request method. Defaults to the GET method.url String (optional) - The request URL. Must be provided in the absolute form with the protocol scheme specified as http or https.session Session (optional) - The Session instance with which the request is associated.partition String (optional) - Der Name der zur Anfrage gehörenden partition. Standard ist ein leerer String. The session option supersedes partition. Somit, falls eine session explizit angegeben wird, wird partition ignoriert.credentials String (optional) - Kann include oder omit sein. Whether to send credentials with this request. If set to include, credentials from the session associated with the request will be used. If set to omit, credentials will not be sent with the request (and the 'login' event will not be triggered in the event of a 401). This matches the behavior of the fetch option of the same name. If this option is not specified, authentication data from the session will be sent, and cookies will not be sent (unless useSessionCookies is set).useSessionCookies Boolean (optional) - Whether to send cookies with this request from the provided session. If credentials is specified, this option has no effect. Standard ist false.protocol String (optional) - Kann http: oder https: sein. The protocol scheme in the form 'scheme:'. Defaults to 'http:'.host String (optional) - Der Server Host angegeben als eine Zusammensetzung aus Hostnamen und der Port Nummer 'hostname:port'.hostname String (optional) - Der Server Host Name.port Integer (optional) - Die Port Nummer des Servers.path String (optional) - Der Pfad Teil der Anfrage URL.redirect String (optional) - Can be follow, error or manual. The redirect mode for this request. When mode is error, any redirection will be aborted. When mode is manual the redirection will be cancelled unless request.followRedirect is invoked synchronously during the redirect event. Standardwert ist follow.origin String (optional) - The origin URL of the request.options Eigenschaften wie zum Beispiel protocol, host, hostname, port und path, folgen strikt dem Node.js Modell, wie im URL Modul beschrieben.
Zum Beispiel hätten wir die gleiche Anfrage an \"github.com\" wie folgt erstellen können:
\nconst request = net.request({\n method: 'GET',\n protocol: 'https:',\n hostname: 'github.com',\n port: 443,\n path: '/'\n})\nKehrt zurück:
\nresponse IncomingMessage - An object representing the HTTP response message.Kehrt zurück:
\nauthInfo ObjektisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (optional)password String (optional)Ausgegeben, wenn ein Authentifizierung Proxy die Benutzeranmeldeinformationen anfragt.
\nDie callback Funktion erwartet mit den Benutzerdaten aufgerufen zu werden:
username Stringpassword Stringrequest.on('login', (authInfo, callback) => {\n callback('username', 'password')\n})\nDas nicht Angeben von Anmeldeinformationen wird die Anfrage abbrechen und dem Response-Objekt einen Authentifizierungsfehler melden:
\nrequest.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`);\n response.on('error', (error) => {\n console.log(`ERROR: ${JSON.stringify(error)}`)\n })\n})\nrequest.on('login', (authInfo, callback) => {\n callback()\n})\nAusgesendet, direkt nachdem der letzte Block der request Daten in das request Objekt geschrieben worden sind.
Emitted when the request is aborted. The abort event will not be fired if the request is already closed.
Kehrt zurück:
\nerror Error - Ein Error Objekt, welches Informationen über den Fehler enthält.Ausgegeben, wenn das net Modul es nicht schaft eine Netzwerkanfrage zu senden. In der Regel wenn das request Objekt ein error Event auslöst, folgt ein close Event und es wird kein response Objekt zur Verfügung gestellt.
Ausgelöst als letztes Event in der HTTP request-response Interaktion. Das close Event gibt an, dass keine weiteren Events mehr auf die request oder response Objekte ausgelöst werden.
Kehrt zurück:
\nstatusCode Integermethod StringredirectUrl StringresponseHeaders Record<String, String[]>Emitted when the server returns a redirect response (e.g. 301 Moved Permanently). Calling request.followRedirect will continue with the redirection. If this event is handled, request.followRedirect must be called synchronously, otherwise the request will be cancelled.
request.chunkedEncodingEin Boolean gibt an, ob die HTTP Anfrage eine segmentierte Übertragungscodierung nutzt oder nicht. Der Standardwert ist false. Die Eigenschaft ist lesbar und beschreibbar, jedoch kann dies nur eingestellt werden, bevor der ersten Schreib-Operation, da die HTTP headers noch nicht abgeschickt worden sind. Der Versuch die chunkedEncoding Eigenschaft nach der ersten Übertragung zu ändern, wird einen Fehler verursachen.
Das Benutzen von segmentierter Codierung wird dringend empfohlen, wenn du einen großen request body senden möchtest, da die Daten in kleinen Stücken gestreamt wird, anstatt das diese intern im Electron Prozess Speicher gebufferd werden.
\nrequest.setHeader(name, value)name String - Ein extra HTTP header Name.value String - An extra HTTP header value.Fügt einen extra HTTP header hinzu. The header name will be issued as-is without lowercasing. Es kann nur vor dem ersten Schreiben aufgerufen werden. Das Aufrufen der Methode nachdem das erste Schreiben erfolgte, wird einen Fehler erzeugen. Falls der übergebene wert kein String ist, wird die toString() Methode aufgerufen, um den Finalen wert zu erhalten.
Certain headers are restricted from being set by apps. These headers are listed below. More information on restricted headers can be found in Chromium's header utils.
\nContent-LengthHostTrailer oder TeUpgradeCookie2Keep-AliveTransfer-EncodingAdditionally, setting the Connection header to the value upgrade is also disallowed.
request.getHeader(name)name String - Spezifiziert einen extra Header Namen.Gibt ein String wieder - Den wert des davor gesetzten extra Header Namen.
request.removeHeader(name)name String - Spezifiziert einen extra Header Namen.Removes a previously set extra header name. This method can be called only before first write. Trying to call it after the first write will throw an error.
\nrequest.write(chunk[, encoding][, callback])chunk (String | Buffer) - A chunk of the request body's data. If it is a string, it is converted into a Buffer using the specified encoding.encoding String (optional) - Used to convert string chunks into Buffer objects. Defaults to 'utf-8'.callback Function (optional) - Wird aufgerufen, nachdem der Schreibvorgang beendet ist.callback ist im Wesentlichen eine dummy-Funktion die dem Zweck dient, Ähnlichkeiten mit der Node.js API beizubehalten. Es wird in den nächsten Tick asynchron aufgerufen, nachdem der chunk Inhalt auf der Chromium Netzwerkebene geliefert worden ist. Im Gegensatz zu der Node.js Implementierung, ist es nicht Garantiert das der chunk Inhalt hochgeladen worden ist, vor dem Aufrufen von callback.
Fügt einen Teil der Daten zum request body. Der erste Schreiboperation könnte das hochladen des request headers einleiten. Nach der ersten Schreiboperation, ist es nicht mehr erlaubt, Benutzerdefinierte Header hinzuzufügen oder zu entfernen.
\nrequest.end([chunk][, encoding][, callback])chunk (String | Buffer) (optional)encoding String (optional)callback Funktion (optional)Sends the last chunk of the request data. Subsequent write or end operations will not be allowed. The finish event is emitted just after the end operation.
request.abort()Bricht die laufende HTTP-Interaktion ab. Falls die Anfrage bereits das close Event ausgegeben hat, hat der Abbruch-Aktion keinen Effekt. Ansonsten wird ein laufendes Event abort und close Events ausgeben. Zusätzlich, falls es ein laufendes response-Objekt gibt, wir dieses ein aborted Event ausgeben.
request.followRedirect()Continues any pending redirection. Can only be called during a 'redirect' event.
request.getUploadProgress()Gibt das Object zurück:
active Boolean - Whether the request is currently active. If this is false no other properties will be setstarted Boolean - Whether the upload has started. If this is false both current and total will be set to 0.current Integer - Die Anzahl der bereits hochgeladenen Bytestotal Integer - Die Anzahl der Bytes, die für diese Anforderung hochgeladen werdenSie können diese Methode in Verbindung mit POST-Anfragen verwenden, um den Fortschritt von einem Datei-Upload oder einer anderen Datenübertragung abzurufen.
\n\n\nAusführung von Kopier- und Einfüge-Operationen von der Zwischenablage des Betriebssystems.
\n
Unter Linux gibt es auch eine selection Zwischenablage. Zum Bearbeiten müssen Sie selection an jede Methode übergeben:
const { clipboard } = require('electron')\n\nclipboard.writeText('Example String', 'selection')\nconsole.log(clipboard.readText('selection'))\nDas clipboard Modul besitzt die folgenden Methoden:
Notiz: Experimentelle Schnittstellen sind mit \"Experimentell\" markiert und könnten in der Zukunft wegfallen.
\nclipboard.readText([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Gibt einen String zurück - Der Inhalt der Zwischenablage liegt in Klartext vor.
const { clipboard } = require('electron')\n\nclipboard.writeText('hello i am a bit of text!')\n\nconst text = clipboard.readText()\nconsole.log(text)\n// hello i am a bit of text!'\nclipboard.writeText(text[, type])text Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Schreibt den text als Klartext in die Zwischenablage.
const { clipboard } = require('electron')\n\nconst text = 'hello i am a bit of text!'\nclipboard.writeText(text)\nclipboard.readHTML([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Gibt einen String zurück - Der Inhalt der Zwischenablage liegt in Auszeichnungssprache (markup language) vor.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b>')\nconst html = clipboard.readHTML()\n\nconsole.log(html)\n// <meta charset='utf-8'><b>Hi</b>\nclipboard.writeHTML(markup[, type])markup Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Schreibt markup in die Zwischenablage.
const { clipboard } = require('electron')\n\nclipboard.writeHTML('<b>Hi</b')\nclipboard.readImage([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Gibt ein NativeImage zurück - Der Inhalt des Bildes liegt in der Zwischenablage vor.
clipboard.writeImage(image[, type])image NativeImagetype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Schreibt das image in die Zwischenablage.
clipboard.readRTF([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Gibt einen String zurück - Der Inhalt der Zwischenablage liegt im Rich Text Format (RTF) vor.
const { clipboard } = require('electron')\n\nclipboard.writeRTF('{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}')\n\nconst rtf = clipboard.readRTF()\nconsole.log(rtf)\n// {\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}\nclipboard.writeRTF(text[, type])text Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Schreibt den text im Rich Text Format (RTF) in die Zwischenablage.
const { clipboard } = require('electron')\n\nconst rtf = '{\\\\rtf1\\\\ansi{\\\\fonttbl\\\\f0\\\\fswiss Helvetica;}\\\\f0\\\\pard\\nThis is some {\\\\b bold} text.\\\\par\\n}'\nclipboard.writeRTF(rtf)\nclipboard.readBookmark() macOS WindowsGibt das Object zurück:
title Stringurl StringGibt ein Objekt, dass die Keys title und url enthält zurück. Diese Keys repräsentieren das Lesezeichen in der Zwischenablage. Wenn das Lesezeichen nicht verfügbar ist, sind die Werte title und url leer.
clipboard.writeBookmark(title, url[, type]) macOS Windowstitle Stringurl Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Schreibt den title und die url als Lesezeichen in die Zwischenablage.
Hinweis: Die meisten Apps unter Windows unterstützen das Einfügen von Lesezeichen nicht in sie, sodass Sie clipboard.write verwenden können, um sowohl ein Lesezeichen als auch einen Fallbacktext in die Zwischenablage zu schreiben.
const { clipboard } = require('electron')\n\nclipboard.writeBookmark({\n text: 'https://electronjs.org',\n bookmark: 'Electron Homepage'\n})\nclipboard.readFindText() macOSReturns String - The text on the find pasteboard, which is the pasteboard that holds information about the current state of the active application’s find panel.
This method uses synchronous IPC when called from the renderer process. The cached value is reread from the find pasteboard whenever the application is activated.
\nclipboard.writeFindText(text) macOStext StringWrites the text into the find pasteboard (the pasteboard that holds information about the current state of the active application’s find panel) as plain text. This method uses synchronous IPC when called from the renderer process.
clipboard.clear([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Löscht den Inhalt aus der Zwischenablage.
\nclipboard.availableFormats([type])type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Gibt ein String[] zurück - Ein Array mit allen von der Zwischenablage unterstützten Formattypen type.
const { clipboard } = require('electron')\n\nconst formats = clipboard.availableFormats()\nconsole.log(formats)\n// [ 'text/plain', 'text/html' ]\nclipboard.has(format[, type]) Experimentellformat Stringtype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Gibt einen Boolean zurück - Prüft, ob die Zwischenablage das angegebene format unterstützt.
const { clipboard } = require('electron')\n\nconst hasFormat = clipboard.has('<p>selection</p>')\nconsole.log(hasFormat)\n// 'true' or 'false'\nclipboard.read(format) Experimentellformat StringGibt den String zurück - Liest den format Typ von der Zwischenablage.
format should contain valid ASCII characters and have / separator. a/c, a/bc are valid formats while /abc, abc/, a/, /a, a are not valid.
clipboard.readBuffer(format) Experimentellformat StringGibt den Buffer zurück - Liest den format Typ von der Zwischenablage.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('this is binary', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\n\nconst ret = clipboard.readBuffer('public/utf8-plain-text')\n\nconsole.log(buffer.equals(out))\n// true\nclipboard.writeBuffer(format, buffer[, type]) Experimentellformat Stringbuffer Puffertype String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Schreibt den buffer mit dem angegebenen format in die Zwischenablage.
const { clipboard } = require('electron')\n\nconst buffer = Buffer.from('writeBuffer', 'utf8')\nclipboard.writeBuffer('public/utf8-plain-text', buffer)\nclipboard.write(data[, type])data Objecttext String (optional)html String (optional)image NativeImage (optional)rtf String (optional)bookmark String (optional) - The title of the URL at text.type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection ist nur unter Linux verfügbar.Schreibt data in die Zwischenablage.
const { clipboard } = require('electron')\n\nclipboard.write({\n text: 'test',\n html: '<b>Hi</b>',\n rtf: '{\\\\rtf1\\\\utf8 text}',\n bookmark: 'a title'\n})\n\nconsole.log(clipboard.readText())\n// 'test'\n\nconsole.log(clipboard.readHTML())\n// <meta charset='utf-8'><b>Hi</b>\n\nconsole.log(clipboard.readRTF())\n// '{\\\\rtf1\\\\utf8 text}'\n\nconsole.log(clipboard.readBookmark())\n// { title: 'a title', url: 'test' }\nCode signing is a security technology that you use to certify that an app was created by you.
\nOn macOS the system can detect any change to the app, whether the change is introduced accidentally or by malicious code.
\nOn Windows, the system assigns a trust level to your code signing certificate which if you don't have, or if your trust level is low, will cause security dialogs to appear when users start using your application. Trust level builds over time so it's better to start code signing as early as possible.
\nWhile it is possible to distribute unsigned apps, it is not recommended. Both Windows and macOS will, by default, prevent either the download or the execution of unsigned applications. Starting with macOS Catalina (version 10.15), users have to go through multiple manual steps to open unsigned applications.
\n
As you can see, users get two options: Move the app straight to the trash or cancel running it. You don't want your users to see that dialog.
\nIf you are building an Electron app that you intend to package and distribute, it should be code-signed.
\nProperly preparing macOS applications for release requires two steps: First, the app needs to be code-signed. Then, the app needs to be uploaded to Apple for a process called \"notarization\", where automated systems will further verify that your app isn't doing anything to endanger its users.
\nTo start the process, ensure that you fulfill the requirements for signing and notarizing your app:
\nElectron's ecosystem favors configuration and freedom, so there are multiple ways to get your application signed and notarized.
\nelectron-forgeIf you're using Electron's favorite build tool, getting your application signed and notarized requires a few additions to your configuration. Forge is a collection of the official Electron tools, using electron-packager, electron-osx-sign, and electron-notarize under the hood.
Let's take a look at an example configuration with all required fields. Not all of them are required: the tools will be clever enough to automatically find a suitable identity, for instance, but we recommend that you are explicit.
{\n \"name\": \"my-app\",\n \"version\": \"0.0.1\",\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"osxSign\": {\n \"identity\": \"Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)\",\n \"hardened-runtime\": true,\n \"entitlements\": \"entitlements.plist\",\n \"entitlements-inherit\": \"entitlements.plist\",\n \"signature-flags\": \"library\"\n },\n \"osxNotarize\": {\n \"appleId\": \"felix@felix.fun\",\n \"appleIdPassword\": \"my-apple-id-password\",\n }\n }\n }\n }\n}\nThe plist file referenced here needs the following macOS-specific entitlements to assure the Apple security mechanisms that your app is doing these things without meaning any harm:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nNote that up until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required as well. However, it should not be used anymore if it can be avoided.
To see all of this in action, check out Electron Fiddle's source code, especially its electron-forge configuration file.
If you plan to access the microphone or camera within your app using Electron's APIs, you'll also need to add the following entitlements:
\n<key>com.apple.security.device.audio-input</key>\n<true/>\n<key>com.apple.security.device.camera</key>\n<true/>\nIf these are not present in your app's entitlements when you invoke, for example:
\nconst { systemPreferences } = require('electron')\n\nconst microphone = systemPreferences.askForMediaAccess('microphone')\nYour app may crash. See the Resource Access section in Hardened Runtime for more information and entitlements you may need.
\nelectron-builderElectron Builder comes with a custom solution for signing your application. You can find its documentation here.
\nelectron-packagerIf you're not using an integrated build pipeline like Forge or Builder, you are likely using electron-packager, which includes electron-osx-sign and electron-notarize.
If you're using Packager's API, you can pass in configuration that both signs and notarizes your application.
\nconst packager = require('electron-packager')\n\npackager({\n dir: '/path/to/my/app',\n osxSign: {\n identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',\n 'hardened-runtime': true,\n entitlements: 'entitlements.plist',\n 'entitlements-inherit': 'entitlements.plist',\n 'signature-flags': 'library'\n },\n osxNotarize: {\n appleId: 'felix@felix.fun',\n appleIdPassword: 'my-apple-id-password'\n }\n})\nThe plist file referenced here needs the following macOS-specific entitlements to assure the Apple security mechanisms that your app is doing these things without meaning any harm:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.cs.allow-jit</key>\n <true/>\n <key>com.apple.security.cs.debugger</key>\n <true/>\n </dict>\n</plist>\nUp until Electron 12, the com.apple.security.cs.allow-unsigned-executable-memory entitlement was required as well. However, it should not be used anymore if it can be avoided.
See the Mac App Store Guide.
\nBefore signing Windows builds, you must do the following:
\nYou can get a code signing certificate from a lot of resellers. Prices vary, so it may be worth your time to shop around. Popular resellers include:
\nThere are a number of tools for signing your packaged app:
\nelectron-winstaller will generate an installer for windows and sign it for youelectron-forge can sign installers it generates through the Squirrel.Windows or MSI targets.electron-builder can sign some of its windows targetsSee the Windows Store Guide.
", "title": "Code Signierung", "description": "" }, "/docs/development/coding-style": { "locale": "de-DE", "slug": "coding-style", "href": "/docs/development/coding-style", "crowdinFileId": "256147", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/coding-style.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "These are the style guidelines for coding in Electron.
\nYou can run npm run lint to show any style issues detected by cpplint and eslint.
path)ipc, app)@)path.join() to concatenate filenames.os.tmpdir() rather than /tmp when you need to reference the temporary directory.return when returning explicitly at the end of a function.return null, return undefined, null or undefinedFor C++ and Python, we follow Chromium's Coding Style. You can use clang-format to format the C++ code automatically. There is also a script script/cpplint.py to check whether all files conform.
The Python version we are using now is Python 2.7.
\nThe C++ code uses a lot of Chromium's abstractions and types, so it's recommended to get acquainted with them. A good place to start is Chromium's Important Abstractions and Data Structures document. The document mentions some special types, scoped types (that automatically release their memory when going out of scope), logging mechanisms etc.
\nYou can run npm run lint-docs to ensure that your documentation changes are formatted correctly.
- instead of _, e.g. file-name.js rather than file_name.js, because in github/atom module names are usually in the module-name form. This rule only applies to .js files.const for requires and other constants. If the value is a primitive, use uppercase naming (eg const NUMBER_OF_RETRIES = 5).let for defining variablesfunction () { }+Electron APIs uses the same capitalization scheme as Node.js:
\nBrowserWindow, use PascalCase.globalShortcut, use camelCase.win.webContents, use mixedCase.<webview> Tag or Process Object.When creating a new API, it is preferred to use getters and setters instead of jQuery's one-function style. For example, .getText() and .setText(text) are preferred to .text([text]). There is a discussion on this.
\n\nManipulate the command line arguments for your app that Chromium reads
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The following example shows how to check if the --disable-gpu flag is set.
const { app } = require('electron')\napp.commandLine.hasSwitch('disable-gpu')\nFor more information on what kinds of flags and switches you can use, check out the Command Line Switches document.
\ncommandLine.appendSwitch(switch[, value])switch String - A command-line switch, without the leading --value String (optional) - A value for the given switchAppend a switch (with optional value) to Chromium's command line.
Note: This will not affect process.argv. The intended usage of this function is to control Chromium's behavior.
commandLine.appendArgument(value)value String - The argument to append to the command lineAppend an argument to Chromium's command line. The argument will be quoted correctly. Switches will precede arguments regardless of appending order.
\nIf you're appending an argument like --switch=value, consider using appendSwitch('switch', 'value') instead.
Note: This will not affect process.argv. The intended usage of this function is to control Chromium's behavior.
commandLine.hasSwitch(switch)switch String - A command-line switchReturns Boolean - Whether the command-line switch is present.
commandLine.getSwitchValue(switch)switch String - A command-line switchReturns String - The command-line switch value.
Note: When the switch is not present or has no value, it returns empty string.
", "title": "CommandLine", "description": "Manipulate the command line arguments for your app that Chromium reads" }, "/docs/api/command-line-switches": { "locale": "de-DE", "slug": "command-line-switches", "href": "/docs/api/command-line-switches", "crowdinFileId": "256293", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/command-line-switches.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nBefehlszeilenoptionen unterstützt von Electron.
\n
app.commandLine.appendSwitch kann benutzt werden um die Befehlszeilenoptionen zu dem Hauptskript der App, bevor das ready-Ereignis des app-Moduls eintritt, hinzuzufügen:
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('remote-debugging-port', '8315')\napp.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')\n\napp.whenReady().then(() => {\n // Your code here\n})\nurlA comma-separated list of servers for which integrated authentication is enabled.
\nEin Beispiel:
\n--auth-server-whitelist='*example.com, *foobar.com, *baz'\nthen any url ending with example.com, foobar.com, baz will be considered for integrated authentication. Without * prefix the URL has to match exactly.
urlA comma-separated list of servers for which delegation of user credentials is required. Without * prefix the URL has to match exactly.
Disables NTLM v2 for posix platforms, no effect elsewhere.
\nDisables the disk cache for HTTP requests.
\nDisable HTTP/2 and SPDY/3.1 protocols.
\nPrevents Chromium from lowering the priority of invisible pages' renderer processes.
\nThis flag is global to all renderer processes, if you only want to disable throttling in one window, you can take the hack of playing silent audio.
\nsizeForces the maximum disk space to be used by the disk cache, in bytes.
\nEnables caller stack logging for the following APIs (filtering events):
\ndesktopCapturer.getSources() / desktop-capturer-get-sourcesPrints Chromium's logging to stderr (or a log file).
\nThe ELECTRON_ENABLE_LOGGING environment variable has the same effect as passing --enable-logging.
Passing --enable-logging will result in logs being printed on stderr. Passing --enable-logging=file will result in logs being saved to the file specified by --log-file=..., or to electron_debug.log in the user-data directory if --log-file is not specified.
\n\nNote: On Windows, logs from child processes cannot be sent to stderr. Logging to a file is the most reliable way to collect logs on Windows.
\n
See also --log-file, --log-level, --v, and --vmodule.
trialsFeldversuche, die zwangsweise aktiviert oder deaktiviert werden können.
\nZum Beispiel: WebRTC-Audio-Red-For-Opus/Enabled/
rulesA comma-separated list of rules that control how hostnames are mapped.
Ein Beispiel:
\nMAP * 127.0.0.1 Forces all hostnames to be mapped to 127.0.0.1MAP *.google.com proxy Forces all google.com subdomains to be resolved to \"proxy\".MAP test.com [::1]:77 Forces \"test.com\" to resolve to IPv6 loopback. Will also force the port of the resulting socket address to be 77.MAP * baz, EXCLUDE www.google.com Remaps everything to \"baz\", except for \"www.google.com\".These mappings apply to the endpoint host in a net request (the TCP connect and host resolver in a direct connection, and the CONNECT in an HTTP proxy connection, and the endpoint host in a SOCKS proxy connection).
rulesLike --host-rules but these rules only apply to the host resolver.
Ignores certificate related errors.
\ndomainsIgnore the connections limit for domains list separated by ,.
flagsSpecifies the flags passed to the Node.js engine. It has to be passed when starting Electron if you want to enable the flags in the main process.
$ electron --js-flags=\"--harmony_proxies --harmony_collections\" your-app\nSee the Node.js documentation or run node --help in your terminal for a list of available flags. Additionally, run node --v8-options to see a list of flags that specifically refer to Node.js's V8 JavaScript engine.
Set a custom locale.
\npathIf --enable-logging is specified, logs will be written to the given path. The parent directory must exist.
Setting the ELECTRON_LOG_FILE environment variable is equivalent to passing this flag. If both are present, the command-line switch takes precedence.
pathEnables net log events to be saved and writes them to path.
NSets the verbosity of logging when used together with --enable-logging. N should be one of Chrome's LogSeverities.
Note that two complimentary logging mechanisms in Chromium -- LOG() and VLOG() -- are controlled by different switches. --log-level controls LOG() messages, while --v and --vmodule control VLOG() messages. So you may want to use a combination of these three switches depending on the granularity you want and what logging calls are made by the code you're trying to watch.
See Chromium Logging source for more information on how LOG() and VLOG() interact. Loosely speaking, VLOG() can be thought of as sub-levels / per-module levels inside LOG(INFO) to control the firehose of LOG(INFO) data.
See also --enable-logging, --log-level, --v, and --vmodule.
Don't use a proxy server and always make direct connections. Overrides any other proxy server flags that are passed.
\nDisables the Chromium sandbox. Forces renderer process and Chromium helper processes to run un-sandboxed. Should only be used for testing.
\nhostsInstructs Electron to bypass the proxy server for the given semi-colon-separated list of hosts. This flag has an effect only if used in tandem with --proxy-server.
Ein Beispiel:
\nconst { app } = require('electron')\napp.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')\nWill use the proxy server for all hosts except for local addresses (localhost, 127.0.0.1 etc.), google.com subdomains, hosts that contain the suffix foo.com and anything at 1.2.3.4:5678.
urlUses the PAC script at the specified url.
address:portUse a specified proxy server, which overrides the system setting. This switch only affects requests with HTTP protocol, including HTTPS and WebSocket requests. It is also noteworthy that not all proxy servers support HTTPS and WebSocket requests. The proxy URL does not support username and password authentication per Chromium issue.
\nportEnables remote debugging over HTTP on the specified port.
log_levelGives the default maximal active V-logging level; 0 is the default. Normally positive values are used for V-logging levels.
\nThis switch only works when --enable-logging is also passed.
See also --enable-logging, --log-level, and --vmodule.
patternGives the per-module maximal V-logging levels to override the value given by --v. z.B. my_module=2,foo*=3 would change the logging level for all code in source files my_module.* and foo*.*.
Any pattern containing a forward or backward slash will be tested against the whole pathname and not only the module. z.B. */foo/bar/*=2 would change the logging level for all code in the source files under a foo/bar directory.
This switch only works when --enable-logging is also passed.
See also --enable-logging, --log-level, and --v.
Force using discrete GPU when there are multiple GPUs available.
\nForce using integrated GPU when there are multiple GPUs available.
\nElectron supports some of the CLI flags supported by Node.js.
\nNote: Passing unsupported command line switches to Electron when it is not running in ELECTRON_RUN_AS_NODE will have no effect.
Activate inspector on host:port and break at start of user script. Default host:port is 127.0.0.1:9229.
\nAliased to --debug-brk=[host:]port.
Set the host:port to be used when the inspector is activated. Useful when activating the inspector by sending the SIGUSR1 signal. Default host is 127.0.0.1.
Aliased to --debug-port=[host:]port.
Activate inspector on host:port. Standard ist 127.0.0.1:9229.
V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug and profile Electron instances. The tools attach to Electron instances via a TCP port and communicate using the Chrome DevTools Protocol.
\nSee the Debugging the Main Process guide for more details.
\nAliased to --debug[=[host:]port.
Specify ways of the inspector web socket url exposure.
\nBy default inspector websocket url is available in stderr and under /json/list endpoint on http://host:port/json/list.
", "title": "Supported Command Line Switches", "description": "Befehlszeilenoptionen unterstützt von Electron." }, "/docs/api/content-tracing": { "locale": "de-DE", "slug": "content-tracing", "href": "/docs/api/content-tracing", "crowdinFileId": "256297", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/content-tracing.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCollect tracing data from Chromium to find performance bottlenecks and slow operations.
\n
Prozess: Haupt
\nThis module does not include a web interface. To view recorded traces, use trace viewer, available at chrome://tracing in Chrome.
Note: You should not use this module until the ready event of the app module is emitted.
const { app, contentTracing } = require('electron')\n\napp.whenReady().then(() => {\n (async () => {\n await contentTracing.startRecording({\n included_categories: ['*']\n })\n console.log('Tracing started')\n await new Promise(resolve => setTimeout(resolve, 5000))\n const path = await contentTracing.stopRecording()\n console.log('Tracing data recorded to ' + path)\n })()\n})\nDas Modul contentTracing verfügt über die folgenden Methoden:
contentTracing.getCategories()Returns Promise<String[]> - resolves with an array of category groups once all child processes have acknowledged the getCategories request
Get a set of category groups. The category groups can change as new code paths are reached. See also the list of built-in tracing categories.
\n\n\nNOTE: Electron adds a non-default tracing category called
\n\"electron\". This category can be used to capture Electron-specific tracing events.
contentTracing.startRecording(options)options (TraceConfig | TraceCategoriesAndOptions)Returns Promise<void> - resolved once all child processes have acknowledged the startRecording request.
Start recording on all processes.
\nRecording begins immediately locally and asynchronously on child processes as soon as they receive the EnableRecording request.
\nIf a recording is already running, the promise will be immediately resolved, as only one trace operation can be in progress at a time.
\ncontentTracing.stopRecording([resultFilePath])resultFilePath String (optional)Returns Promise<String> - resolves with a path to a file that contains the traced data once all child processes have acknowledged the stopRecording request
Stop recording on all processes.
\nChild processes typically cache trace data and only rarely flush and send trace data back to the main process. This helps to minimize the runtime overhead of tracing since sending trace data over IPC can be an expensive operation. So, to end tracing, Chromium asynchronously asks all child processes to flush any pending trace data.
\nTrace data will be written into resultFilePath. If resultFilePath is empty or not provided, trace data will be written to a temporary file, and the path will be returned in the promise.
contentTracing.getTraceBufferUsage()Returns Promise<Object> - Resolves with an object containing the value and percentage of trace buffer maximum usage
value Numberpercentage NumberGet the maximum usage across processes of trace buffer as a percentage of the full state.
", "title": "contentTracing", "description": "Collect tracing data from Chromium to find performance bottlenecks and slow operations." }, "/docs/api/context-bridge": { "locale": "de-DE", "slug": "context-bridge", "href": "/docs/api/context-bridge", "crowdinFileId": "256299", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/context-bridge.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCreate a safe, bi-directional, synchronous bridge across isolated contexts
\n
Prozess: Renderer
\nAn example of exposing an API to a renderer from an isolated preload script is given below:
\n// Preload (Isolated World)\nconst { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing')\n }\n)\n// Renderer (Main World)\n\nwindow.electron.doThing()\nThe \"Main World\" is the JavaScript context that your main renderer code runs in. By default, the page you load in your renderer executes code in this world.
\nWhen contextIsolation is enabled in your webPreferences (this is the default behavior since Electron 12.0.0), your preload scripts run in an \"Isolated World\". You can read more about context isolation and what it affects in the security docs.
Das contextBridge Modul hat folgende Methoden:
contextBridge.exposeInMainWorld(apiKey, api)apiKey String - The key to inject the API onto window with. The API will be accessible on window[apiKey].api any - Your API, more information on what this API can be and how it works is available below.The api provided to exposeInMainWorld must be a Function, String, Number, Array, Boolean, or an object whose keys are strings and values are a Function, String, Number, Array, Boolean, or another nested object that meets the same conditions.
Function values are proxied to the other context and all other values are copied and frozen. Any data / primitives sent in the API become immutable and updates on either side of the bridge do not result in an update on the other side.
An example of a complex API is shown below:
\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld(\n 'electron',\n {\n doThing: () => ipcRenderer.send('do-a-thing'),\n myPromises: [Promise.resolve(), Promise.reject(new Error('whoops'))],\n anAsyncFunction: async () => 123,\n data: {\n myFlags: ['a', 'b', 'c'],\n bootTime: 1234\n },\n nestedAPI: {\n evenDeeper: {\n youCanDoThisAsMuchAsYouWant: {\n fn: () => ({\n returnData: 123\n })\n }\n }\n }\n }\n)\nFunction values that you bind through the contextBridge are proxied through Electron to ensure that contexts remain isolated. This results in some key limitations that we've outlined below.
Because parameters, errors and return values are copied when they are sent over the bridge, there are only certain types that can be used. At a high level, if the type you want to use can be serialized and deserialized into the same object it will work. A table of type support has been included below for completeness:
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Typ | Complexity | Parameter Support | Return Value Support | Einschränkungen |
|---|---|---|---|---|
String | Simple | ✅ | ✅ | N/A |
Number | Simple | ✅ | ✅ | N/A |
Boolean | Simple | ✅ | ✅ | N/A |
Object | Complex | ✅ | ✅ | Keys must be supported using only \"Simple\" types in this table. Values must be supported in this table. Prototype modifications are dropped. Sending custom classes will copy values but not the prototype. |
Array | Complex | ✅ | ✅ | Same limitations as the Object type |
Error | Complex | ✅ | ✅ | Errors that are thrown are also copied, this can result in the message and stack trace of the error changing slightly due to being thrown in a different context |
Promise | Complex | ✅ | ✅ | Promises are only proxied if they are the return value or exact parameter. Promises nested in arrays or objects will be dropped. |
Funktion | Complex | ✅ | ✅ | Prototype modifications are dropped. Sending classes or constructors will not work. |
| Cloneable Types | Simple | ✅ | ✅ | See the linked document on cloneable types |
Element | Complex | ✅ | ✅ | Prototype modifications are dropped. Sending custom elements will not work. |
Blob | Complex | ✅ | ✅ | N/A |
Symbol | N/A | ❌ | ❌ | Symbols cannot be copied across contexts so they are dropped |
If the type you care about is not in the above table, it is probably not supported.
\nThe contextBridge can be used by the preload script to give your renderer access to Node APIs. The table of supported types described above also applies to Node APIs that you expose through contextBridge. Please note that many Node APIs grant access to local system resources. Be very cautious about which globals and APIs you expose to untrusted remote content.
const { contextBridge } = require('electron')\nconst crypto = require('crypto')\ncontextBridge.exposeInMainWorld('nodeCrypto', {\n sha256sum (data) {\n const hash = crypto.createHash('sha256')\n hash.update(data)\n return hash.digest('hex')\n }\n})\nContext Isolation is a feature that ensures that both your preload scripts and Electron's internal logic run in a separate context to the website you load in a webContents. This is important for security purposes as it helps prevent the website from accessing Electron internals or the powerful APIs your preload script has access to.
This means that the window object that your preload script has access to is actually a different object than the website would have access to. For example, if you set window.hello = 'wave' in your preload script and context isolation is enabled, window.hello will be undefined if the website tries to access it.
Context isolation has been enabled by default since Electron 12, and it is a recommended security setting for all applications.
\n\n\nWithout context isolation, I used to provide APIs from my preload script using
\nwindow.X = apiObject. Now what?
Exposing APIs from your preload script to a loaded website in the renderer process is a common use-case. With context isolation disabled, your preload script would share a common global window object with the renderer. You could then attach arbitrary properties to a preload script:
// preload with contextIsolation disabled\nwindow.myAPI = {\n doAThing: () => {}\n}\nThe doAThing() function could then be used directly in the renderer process:
// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nThere is a dedicated module in Electron to help you do this in a painless way. The contextBridge module can be used to safely expose APIs from your preload script's isolated context to the context the website is running in. The API will also be accessible from the website on window.myAPI just like it was before.
// preload with contextIsolation enabled\nconst { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n doAThing: () => {}\n})\n// use the exposed API in the renderer\nwindow.myAPI.doAThing()\nPlease read the contextBridge documentation linked above to fully understand its limitations. For instance, you can't send custom prototypes or symbols over the bridge.
Just enabling contextIsolation and using contextBridge does not automatically mean that everything you do is safe. For instance, this code is unsafe.
// ❌ Bad code\ncontextBridge.exposeInMainWorld('myAPI', {\n send: ipcRenderer.send\n})\nIt directly exposes a powerful API without any kind of argument filtering. This would allow any website to send arbitrary IPC messages, which you do not want to be possible. The correct way to expose IPC-based APIs would instead be to provide one method per IPC message.
\n// ✅ Good code\ncontextBridge.exposeInMainWorld('myAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nIf you're building your Electron app with TypeScript, you'll want to add types to your APIs exposed over the context bridge. The renderer's window object won't have the correct typings unless you extend the types with a declaration file.
For example, given this preload.ts script:
contextBridge.exposeInMainWorld('electronAPI', {\n loadPreferences: () => ipcRenderer.invoke('load-prefs')\n})\nYou can create a renderer.d.ts declaration file and globally augment the Window interface:
export interface IElectronAPI {\n loadPreferences: () => Promise<void>,\n}\n\ndeclare global {\n interface Window {\n electronAPI: IElectronAPI\n }\n}\nDoing so will ensure that the TypeScript compiler will know about the electronAPI property on your global window object when writing scripts in your renderer process:
window.electronAPI.loadPreferences()\nname String - The name of the cookie.value String - The value of the cookie.domain String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains.hostOnly Boolean (optional) - Whether the cookie is a host-only cookie; this will only be true if no domain was passed.path String (optional) - The path of the cookie.secure Boolean (optional) - Whether the cookie is marked as secure.httpOnly Boolean (optional) - Whether the cookie is marked as HTTP only.session Boolean (optional) - Whether the cookie is a session cookie or a persistent cookie with an expiration date.expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.sameSite String - The Same Site policy applied to this cookie. Can be unspecified, no_restriction, lax or strict.\n\nAbfragen und modifizieren von Session Cookies.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Auf Instanzen der Cookies-Klasse wird über die Cookie-Eigenschaft einer Sitzung zugegriffen.
Ein Beispiel:
\nconst { session } = require('electron')\n\n// Durchsuche all Cookies.\nsession.defaultSession.cookies.get({})\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// Query all cookies associated with a specific url.\nsession.defaultSession.cookies.get({ url: 'http://www.github.com' })\n .then((cookies) => {\n console.log(cookies)\n }).catch((error) => {\n console.log(error)\n })\n\n// Set a cookie with the given cookie data;\n// may overwrite equivalent cookies if they exist.\nconst cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }\nsession.defaultSession.cookies.set(cookie)\n .then(() => {\n // success\n }, (error) => {\n console.error(error)\n })\nThe following events are available on instances of Cookies:
Kehrt zurück:
\nevent Eventcookie Cookie - The cookie that was changed.cause String - The cause of the change with one of the following values:explicit - The cookie was changed directly by a consumer's action.overwrite - The cookie was automatically removed due to an insert operation that overwrote it.expired - The cookie was automatically removed as it expired.evicted - The cookie was automatically evicted during garbage collection.expired-overwrite - The cookie was overwritten with an already-expired expiration date.removed Boolean - true if the cookie was removed, false otherwise.Emitted when a cookie is changed because it was added, edited, removed, or expired.
\nDie folgenden Methoden sind verfügbar in Instanzen von Cookies:
cookies.get(filter)filter Objekturl String (optional) - Retrieves cookies which are associated with url. Empty implies retrieving cookies of all URLs.name String (optional) - Filters cookies by name.domain String (optional) - Retrieves cookies whose domains match or are subdomains of domains.path String (optional) - Retrieves cookies whose path matches path.secure Boolean (optional) - Filters cookies by their Secure property.session Boolean (optional) - Filters out session or persistent cookies.Returns Promise<Cookie[]> - A promise which resolves an array of cookie objects.
Sends a request to get all cookies matching filter, and resolves a promise with the response.
cookies.set(details)details Objekturl String - The URL to associate the cookie with. The promise will be rejected if the URL is invalid.name String (optional) - The name of the cookie. Empty by default if omitted.value String (optional) - The value of the cookie. Empty by default if omitted.domain String (optional) - Die Domain des Cookie; dies wird mit einem vorhergehenden Punkt normalisiert, so dass es auch für Subdomains gilt. Empty by default if omitted.path String (optional) - Der Pfad des Cookie. Empty by default if omitted.secure Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to false unless Same Site=None attribute is used.httpOnly Boolean (optional) - Whether the cookie should be marked as HTTP only. Der Standardwert ist false.expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted then the cookie becomes a session cookie and will not be retained between sessions.sameSite String (optional) - The Same Site policy to apply to this cookie. Sein Wert kann nicht gesetzt , no_restriction, lax oder strict sein. Standard ist no_restriction.Returns Promise<void> - A promise which resolves when the cookie has been set
Sets a cookie with details.
cookies.remove(url, name)url String - The URL associated with the cookie.name String - The name of cookie to remove.Returns Promise<void> - A promise which resolves when the cookie has been removed
Removes the cookies matching url and name
cookies.flushStore()Returns Promise<void> - A promise which resolves when the cookie store has been flushed
Writes any unwritten cookies data to disk.
", "title": "Cookies", "description": "Abfragen und modifizieren von Session Cookies." }, "/docs/api/structures/cpu-usage": { "locale": "de-DE", "slug": "cpu-usage", "href": "/docs/api/structures/cpu-usage", "crowdinFileId": "256419", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/cpu-usage.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "percentCPUUsage Number - Percentage of CPU used since the last call to getCPUUsage. First call returns 0.idleWakeupsPerSecond Number - The number of average idle CPU wakeups per second since the last call to getCPUUsage. First call returns 0. Will always return 0 on Windows.date Dateid Zeichenfolge\n\n\nBestätige Crash Reports zu einem Remote Server
\n
The following is an example of setting up Electron to automatically submit crash reports to a remote server:
\nconst { crashReporter } = require('electron')\n\ncrashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })\nZum einrichten eines Servers, zum aktzeptieren und verarbeiten von Crash Reports, können sie folgenden Projekte verwenden:
\n\nOr use a 3rd party hosted solution:
\n\nCrash reports are stored temporarily before being uploaded in a directory underneath the app's user data directory (called 'Crashpad' on Windows and Mac, or 'Crash Reports' on Linux). You can override this directory by calling app.setPath('crashDumps', '/path/to/crashes') before starting the crash reporter.
On Windows and macOS, Electron uses crashpad to monitor and report crashes. On Linux, Electron uses breakpad. This is an implementation detail driven by Chromium, and it may change in future. In particular, crashpad is newer and will likely eventually replace breakpad on all platforms.
\nIf you are using the Node.js child_process module and want to report crashes from those processes on Linux, there is an extra step you will need to take to properly initialize the crash reporter in the child process. This is not necessary on Mac or Windows, as those platforms use Crashpad, which automatically monitors child processes.
Since require('electron') is not available in Node child processes, the following APIs are available on the process object in Node child processes. Note that, on Linux, each Node child process has its own separate instance of the breakpad crash reporter. This is dissimilar to renderer child processes, which have a \"stub\" breakpad reporter which returns information to the main process for reporting.
process.crashReporter.start(options)process.crashReporter.getParameters()See crashReporter.getParameters().
process.crashReporter.addExtraParameter(key, value)See crashReporter.addExtraParameter(key, value).
process.crashReporter.removeExtraParameter(key)See crashReporter.removeExtraParameter(key).
Das Modul crashReporter verfügt über die folgenden Methoden:
crashReporter.start(options)options ObjektsubmitURL String (optional) - URL that crash reports will be sent to as POST. Required unless uploadToServer is false.productName String (optional) - Defaults to app.name.companyName String (optional) Deprecated - Deprecated alias for { globalExtra: { _companyName: ... } }.uploadToServer Boolean (optional) - Whether crash reports should be sent to the server. If false, crash reports will be collected and stored in the crashes directory, but not uploaded. Standard ist true.ignoreSystemCrashHandler Boolean (optional) - If true, crashes generated in the main process will not be forwarded to the system crash handler. Standard ist false.rateLimit Boolean (optional) macOS Windows - If true, limit the number of crashes uploaded to 1/hour. Standard ist false.compress Boolean (optional) - If true, crash reports will be compressed and uploaded with Content-Encoding: gzip. Standard ist true.extra Record<String, String> (optional) - Extra string key/value annotations that will be sent along with crash reports that are generated in the main process. Only string values are supported. Crashes generated in child processes will not contain these extra parameters to crash reports generated from child processes, call addExtraParameter from the child process.globalExtra Record<String, String> (optional) - Extra string key/value annotations that will be sent along with any crash reports generated in any process. These annotations cannot be changed once the crash reporter has been started. If a key is present in both the global extra parameters and the process-specific extra parameters, then the global one will take precedence. By default, productName and the app version are included, as well as the Electron version.This method must be called before using any other crashReporter APIs. Once initialized this way, the crashpad handler collects crashes from all subsequently created processes. The crash reporter cannot be disabled once started.
This method should be called as early as possible in app startup, preferably before app.on('ready'). If the crash reporter is not initialized at the time a renderer process is created, then that renderer process will not be monitored by the crash reporter.
Note: You can test out the crash reporter by generating a crash using process.crash().
Note: If you need to send additional/updated extra parameters after your first call start you can call addExtraParameter.
Note: Parameters passed in extra, globalExtra or set with addExtraParameter have limits on the length of the keys and values. Key names must be at most 39 bytes long, and values must be no longer than 127 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated.
Note: This method is only available in the main process.
\ncrashReporter.getLastCrashReport()Returns CrashReport - The date and ID of the last crash report. Only crash reports that have been uploaded will be returned; even if a crash report is present on disk it will not be returned until it is uploaded. In the case that there are no uploaded reports, null is returned.
Note: This method is only available in the main process.
\ncrashReporter.getUploadedReports()Returns CrashReport[]:
Returns all uploaded crash reports. Each report contains the date and uploaded ID.
\nNote: This method is only available in the main process.
\ncrashReporter.getUploadToServer()Returns Boolean - Whether reports should be submitted to the server. Set through the start method or setUploadToServer.
Note: This method is only available in the main process.
\ncrashReporter.setUploadToServer(uploadToServer)uploadToServer Boolean - Whether reports should be submitted to the server.This would normally be controlled by user preferences. This has no effect if called before start is called.
Note: This method is only available in the main process.
\ncrashReporter.addExtraParameter(key, value)key String - Parameter key, must be no longer than 39 bytes.value String - Parameter value, must be no longer than 127 bytes.Set an extra parameter to be sent with the crash report. The values specified here will be sent in addition to any values set via the extra option when start was called.
Parameters added in this fashion (or via the extra parameter to crashReporter.start) are specific to the calling process. Adding extra parameters in the main process will not cause those parameters to be sent along with crashes from renderer or other child processes. Similarly, adding extra parameters in a renderer process will not result in those parameters being sent with crashes that occur in other renderer processes or in the main process.
Note: Parameters have limits on the length of the keys and values. Key names must be no longer than 39 bytes, and values must be no longer than 20320 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated.
\nNote: On linux values that are longer than 127 bytes will be chunked into multiple keys, each 127 bytes in length. z.B. addExtraParameter('foo', 'a'.repeat(130)) will result in two chunked keys foo__1 and foo__2, the first will contain the first 127 bytes and the second will contain the remaining 3 bytes. On your crash reporting backend you should stitch together keys in this format.
crashReporter.removeExtraParameter(key)key String - Parameter key, must be no longer than 39 bytes.Remove an extra parameter from the current set of parameters. Future crashes will not include this parameter.
\ncrashReporter.getParameters()Returns Record<String, String> - The current 'extra' parameters of the crash reporter.
The crash reporter will send the following data to the submitURL as a multipart/form-data POST:
ver String - The version of Electron.platform String - e.g. 'win32'.process_type String - e.g. 'renderer'.guid String - e.g. '5e1286fc-da97-479e-918b-6bfb0c3d1c72'._version String - The version in package.json._productName String - The product name in the crashReporter options object.prod String - Name of the underlying product. In this case Electron._companyName String - The company name in the crashReporter options object.upload_file_minidump File - The crash report in the format of minidump.extra object in the crashReporter options object.scheme String - Custom schemes to be registered with options.privileges Object (optional)standard Boolean (optional) - Default false.secure Boolean (optional) - Default false.bypassCSP Boolean (optional) - Default false.allowServiceWorkers Boolean (optional) - Default false.supportFetchAPI Boolean (optional) - Default false.corsEnabled Boolean (optional) - Default false.stream Boolean (optional) - Default false.\"Native interfaces\" include the file picker, window border, dialogs, context menus, and more - anything where the UI comes from your operating system and not from your app. The default behavior is to opt into this automatic theming from the OS.
\nIf your app has its own dark mode, you should toggle it on and off in sync with the system's dark mode setting. You can do this by using the [prefer-color-scheme] CSS media query.
\nIf you want to manually switch between light/dark modes, you can do this by setting the desired mode in the themeSource property of the nativeTheme module. This property's value will be propagated to your Renderer process. Any CSS rules related to prefers-color-scheme will be updated accordingly.
In macOS 10.14 Mojave hat Apple einen neuen systemweiten dunklen Modus für alle Mac OS-Computer eingeführt. If your Electron app has a dark mode, you can make it follow the system-wide dark mode setting using the nativeTheme api.
In macOS 10.15 Catalina, Apple introduced a new \"automatic\" dark mode option for all macOS computers. In order for the nativeTheme.shouldUseDarkColors and Tray APIs to work correctly in this mode on Catalina, you need to use Electron >=7.0.0, or set NSRequiresAquaSystemAppearance to false in your Info.plist file for older versions. Both Electron Packager and Electron Forge have a darwinDarkModeSupport option to automate the Info.plist changes during app build time.
If you wish to opt-out while using Electron > 8.0.0, you must set the NSRequiresAquaSystemAppearance key in the Info.plist file to true. Please note that Electron 8.0.0 and above will not let you opt-out of this theming, due to the use of the macOS 10.14 SDK.
This example demonstrates an Electron application that derives its theme colors from the nativeTheme. Additionally, it provides theme toggle and reset controls using IPC channels.
Starting with the index.html file:
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n <link rel=\"stylesheet\" type=\"text/css\" href=\"./styles.css\">\n</head>\n<body>\n <h1>Hello World!</h1>\n <p>Current theme source: <strong id=\"theme-source\">System</strong></p>\n\n <button id=\"toggle-dark-mode\">Toggle Dark Mode</button>\n <button id=\"reset-to-system\">Reset to System Theme</button>\n\n <script src=\"renderer.js\"></script>\n </body>\n</body>\n</html>\nAnd the styles.css file:
@media (prefers-color-scheme: dark) {\n body { background: #333; color: white; }\n}\n\n@media (prefers-color-scheme: light) {\n body { background: #ddd; color: black; }\n}\nThe example renders an HTML page with a couple elements. The <strong id=\"theme-source\"> element shows which theme is currently selected, and the two <button> elements are the controls. The CSS file uses the prefers-color-scheme media query to set the <body> element background and text colors.
The preload.js script adds a new API to the window object called darkMode. This API exposes two IPC channels to the renderer process, 'dark-mode:toggle' and 'dark-mode:system'. It also assigns two methods, toggle and system, which pass messages from the renderer to the main process.
const { contextBridge, ipcRenderer } = require('electron')\n\ncontextBridge.exposeInMainWorld('darkMode', {\n toggle: () => ipcRenderer.invoke('dark-mode:toggle'),\n system: () => ipcRenderer.invoke('dark-mode:system')\n})\nNow the renderer process can communicate with the main process securely and perform the necessary mutations to the nativeTheme object.
The renderer.js file is responsible for controlling the <button> functionality.
document.getElementById('toggle-dark-mode').addEventListener('click', async () => {\n const isDarkMode = await window.darkMode.toggle()\n document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'\n})\n\ndocument.getElementById('reset-to-system').addEventListener('click', async () => {\n await window.darkMode.system()\n document.getElementById('theme-source').innerHTML = 'System'\n})\nUsing addEventListener, the renderer.js file adds 'click' event listeners to each button element. Each event listener handler makes calls to the respective window.darkMode API methods.
Finally, the main.js file represents the main process and contains the actual nativeTheme API.
const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n\n ipcMain.handle('dark-mode:toggle', () => {\n if (nativeTheme.shouldUseDarkColors) {\n nativeTheme.themeSource = 'light'\n } else {\n nativeTheme.themeSource = 'dark'\n }\n return nativeTheme.shouldUseDarkColors\n })\n\n ipcMain.handle('dark-mode:system', () => {\n nativeTheme.themeSource = 'system'\n })\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nThe ipcMain.handle methods are how the main process responds to the click events from the buttons on the HTML page.
The 'dark-mode:toggle' IPC channel handler method checks the shouldUseDarkColors boolean property, sets the corresponding themeSource, and then returns the current shouldUseDarkColors property. Looking back on the renderer process event listener for this IPC channel, the return value from this handler is utilized to assign the correct text to the <strong id='theme-source'> element.
The 'dark-mode:system' IPC channel handler method assigns the string 'system' to the themeSource and returns nothing. This also corresponds with the relative renderer process event listener as the method is awaited with no return value expected.
Run the example using Electron Fiddle and then click the \"Toggle Dark Mode\" button; the app should start alternating between a light and dark background color.
\n
Wenn Sie Abstürze oder Probleme in Electron auftreten, von denen Sie glauben, dass sie nicht JavaScript-Anwendung, sondern von Electron selbst kann das Debuggen ein wenig schwierig sein, vor allem für Entwickler, die nicht an native/C++ gewöhnt sind Debuggen. However, using Visual Studio, Electron's hosted Symbol Server, and the Electron source code, you can enable step-through debugging with breakpoints inside Electron's source code.
\nSee also: There's a wealth of information on debugging Chromium, much of which also applies to Electron, on the Chromium developers site: Debugging Chromium on Windows.
\nA debug build of Electron: The easiest way is usually building it yourself, using the tools and prerequisites listed in the build instructions for Windows. While you can attach to and debug Electron as you can download it directly, you will find that it is heavily optimized, making debugging substantially more difficult: The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations.
\nVisual Studio with C++ Tools: The free community editions of Visual Studio 2013 and Visual Studio 2015 both work. Once installed, configure Visual Studio to use Electron's Symbol server. It will enable Visual Studio to gain a better understanding of what happens inside Electron, making it easier to present variables in a human-readable format.
\nProcMon: The free SysInternals tool allows you to inspect a processes parameters, file handles, and registry operations.
\nTo start a debugging session, open up PowerShell/CMD and execute your debug build of Electron, using the application to open as a parameter.
\n$ ./out/Testing/electron.exe ~/my-electron-app/\nThen, open up Visual Studio. Electron is not built with Visual Studio and hence does not contain a project file - you can however open up the source code files \"As File\", meaning that Visual Studio will open them up by themselves. You can still set breakpoints - Visual Studio will automatically figure out that the source code matches the code running in the attached process and break accordingly.
\nDie wichtigen Code Files findest du in ./shell/.
You can attach the Visual Studio debugger to a running process on a local or remote computer. After the process is running, click Debug / Attach to Process (or press CTRL+ALT+P) to open the \"Attach to Process\" dialog box. You can use this capability to debug apps that are running on a local or remote computer, debug multiple processes simultaneously.
If Electron is running under a different user account, select the Show processes from all users check box. Notice that depending on how many BrowserWindows your app opened, you will see multiple processes. A typical one-window app will result in Visual Studio presenting you with two Electron.exe entries - one for the main process and one for the renderer process. Since the list only gives you names, there's currently no reliable way of figuring out which is which.
Code executed within the main process (that is, code found in or eventually run by your main JavaScript file) will run inside the main process, while other code will execute inside its respective renderer process.
\nYou can be attached to multiple programs when you are debugging, but only one program is active in the debugger at any time. You can set the active program in the Debug Location toolbar or the Processes window.
While Visual Studio is fantastic for inspecting specific code paths, ProcMon's strength is really in observing everything your application is doing with the operating system - it captures File, Registry, Network, Process, and Profiling details of processes. It attempts to log all events occurring and can be quite overwhelming, but if you seek to understand what and how your application is doing to the operating system, it can be a valuable resource.
\nFor an introduction to ProcMon's basic and advanced debugging features, go check out this video tutorial provided by Microsoft.
", "title": "Debugging in Windows", "description": "" }, "/docs/api/debugger": { "locale": "de-DE", "slug": "debugger", "href": "/docs/api/debugger", "crowdinFileId": "256305", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/debugger.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nAn alternate transport for Chrome's remote debugging protocol.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Chrome Developer Tools has a special binding available at JavaScript runtime that allows interacting with pages and instrumenting them.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\ntry {\n win.webContents.debugger.attach('1.1')\n} catch (err) {\n console.log('Debugger attach failed : ', err)\n}\n\nwin.webContents.debugger.on('detach', (event, reason) => {\n console.log('Debugger detached due to : ', reason)\n})\n\nwin.webContents.debugger.on('message', (event, method, params) => {\n if (method === 'Network.requestWillBeSent') {\n if (params.request.url === 'https://www.github.com') {\n win.webContents.debugger.detach()\n }\n }\n})\n\nwin.webContents.debugger.sendCommand('Network.enable')\nKehrt zurück:
\nevent Eventreason String - Reason for detaching debugger.Emitted when the debugging session is terminated. This happens either when webContents is closed or devtools is invoked for the attached webContents.
Kehrt zurück:
\nevent Eventmethod String - Method name.params any - Event parameters defined by the 'parameters' attribute in the remote debugging protocol.sessionId String - Unique identifier of attached debugging session, will match the value sent from debugger.sendCommand.Emitted whenever the debugging target issues an instrumentation event.
\ndebugger.attach([protocolVersion])protocolVersion String (optional) - Requested debugging protocol version.Attaches the debugger to the webContents.
debugger.isAttached()Returns Boolean - Whether a debugger is attached to the webContents.
debugger.detach()Detaches the debugger from the webContents.
debugger.sendCommand(method[, commandParams, sessionId])method String - Method name, should be one of the methods defined by the remote debugging protocol.commandParams any (optional) - JSON object with request parameters.sessionId String (optional) - send command to the target with associated debugging session id. The initial value can be obtained by sending Target.attachToTarget message.Returns Promise<any> - A promise that resolves with the response defined by the 'returns' attribute of the command description in the remote debugging protocol or is rejected indicating the failure of the command.
Send given command to the debugging target.
", "title": "Debugger", "description": "An alternate transport for Chrome's remote debugging protocol." }, "/docs/development/debugging-instructions-macos": { "locale": "de-DE", "slug": "debugging-instructions-macos", "href": "/docs/development/debugging-instructions-macos", "crowdinFileId": "256153", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Wenn Sie Abstürze oder Probleme in Electron auftreten, von denen Sie glauben, dass sie nicht JavaScript-Anwendung, sondern von Electron selbst kann das Debuggen ein wenig schwierig sein, vor allem für Entwickler, die nicht an native/C++ gewöhnt sind Debuggen. However, using lldb, and the Electron source code, you can enable step-through debugging with breakpoints inside Electron's source code. You can also use XCode for debugging if you prefer a graphical interface.
\nA debug build of Electron: The easiest way is usually building it yourself, using the tools and prerequisites listed in the build instructions for macOS. While you can attach to and debug Electron as you can download it directly, you will find that it is heavily optimized, making debugging substantially more difficult: The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations.
\nXcode: In addition to Xcode, also install the Xcode command line tools. They include LLDB, the default debugger in Xcode on macOS. It supports debugging C, Objective-C and C++ on the desktop and iOS devices and simulator.
\n.lldbinit: Create or edit ~/.lldbinit to allow Chromium code to be properly source-mapped.
# e.g: ['~/electron/src/tools/lldb']\nscript sys.path[:0] = ['<...path/to/electron/src/tools/lldb>']\nscript import lldbinit\nTo start a debugging session, open up Terminal and start lldb, passing a non-release build of Electron as a parameter.
$ lldb ./out/Testing/Electron.app\n(lldb) target create \"./out/Testing/Electron.app\"\nCurrent executable set to './out/Testing/Electron.app' (x86_64).\nLLDB is a powerful tool and supports multiple strategies for code inspection. For this basic introduction, let's assume that you're calling a command from JavaScript that isn't behaving correctly - so you'd like to break on that command's C++ counterpart inside the Electron source.
\nDie wichtigen Code Files findest du in ./shell/.
Let's assume that you want to debug app.setName(), which is defined in browser.cc as Browser::SetName(). Set the breakpoint using the breakpoint command, specifying file and line to break on:
(lldb) breakpoint set --file browser.cc --line 117\nBreakpoint 1: where = Electron Framework`atom::Browser::SetName(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) + 20 at browser.cc:118, address = 0x000000000015fdb4\nDann starte Electron:
\n(lldb) run\nThe app will immediately be paused, since Electron sets the app's name on launch:
\n(lldb) run\nProcess 25244 launched: '/Users/fr/Code/electron/out/Testing/Electron.app/Contents/MacOS/Electron' (x86_64)\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1\n frame #0: 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 20 at browser.cc:118\n 115 }\n 116\n 117 void Browser::SetName(const std::string& name) {\n-> 118 name_override_ = name;\n 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n(lldb)\nTo show the arguments and local variables for the current frame, run frame variable (or fr v), which will show you that the app is currently setting the name to \"Electron\".
(lldb) frame variable\n(atom::Browser *) this = 0x0000000108b14f20\n(const string &) name = \"Electron\": {\n [...]\n}\nTo do a source level single step in the currently selected thread, execute step (or s). This would take you into name_override_.empty(). To proceed and do a step over, run next (or n).
(lldb) step\nProcess 25244 stopped\n* thread #1: tid = 0x839a4c, 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119, queue = 'com.apple.main-thread', stop reason = step in\n frame #0: 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name=\"Electron\") + 44 at browser.cc:119\n 116\n 117 void Browser::SetName(const std::string& name) {\n 118 name_override_ = name;\n-> 119 }\n 120\n 121 int Browser::GetBadgeCount() {\n 122 return badge_count_;\nNOTE: If you don't see source code when you think you should, you may not have added the ~/.lldbinit file above.
To finish debugging at this point, run process continue. You can also continue until a certain line is hit in this thread (thread until 100). This command will run the thread in the current frame till it reaches line 100 in this frame or stops if it leaves the current frame.
Jetzt wenn du Electrons DevTools öffnest und setName aufrufst triffst du wieder den Breakpoint.
LLDB is a powerful tool with a great documentation. To learn more about it, consider Apple's debugging documentation, for instance the LLDB Command Structure Reference or the introduction to Using LLDB as a Standalone Debugger.
\nYou can also check out LLDB's fantastic manual and tutorial, which will explain more complex debugging scenarios.
", "title": "Debugging in macOS", "description": "" }, "/docs/development/debugging-instructions-macos-xcode": { "locale": "de-DE", "slug": "debugging-instructions-macos-xcode", "href": "/docs/development/debugging-instructions-macos-xcode", "crowdinFileId": "256151", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/debugging-instructions-macos-xcode.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Run gn gen with the --ide=xcode argument.
$ gn gen out/Testing --ide=xcode\nThis will generate the electron.ninja.xcworkspace. You will have to open this workspace to set breakpoints and inspect.
\nSee gn help gen for more information on generating IDE projects with GN.
Launch Electron app after build. You can now open the xcode workspace created above and attach to the Electron process through the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug the renderer process, you need to attach to the Electron Helper as well.]
\nYou can now set breakpoints in any of the indexed files. However, you will not be able to set breakpoints directly in the Chromium source. To set break points in the Chromium source, you can choose Debug > Breakpoints > Create Symbolic Breakpoint and set any function name as the symbol. This will set the breakpoint for all functions with that name, from all the classes if there are more than one. You can also do this step of setting break points prior to attaching the debugger, however, actual breakpoints for symbolic breakpoint functions may not show up until the debugger is attached to the app.
", "title": "Debugging mit XCode", "description": "" }, "/docs/tutorial/debugging-main-process": { "locale": "de-DE", "slug": "debugging-main-process", "href": "/docs/tutorial/debugging-main-process", "crowdinFileId": "256189", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/debugging-main-process.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Die DevTools in einem Electron Browserfenster können nur JavaScript debuggen, das auch in diesem Fenster ausgeführt wird (z.B. die Websites). Um JavaScript zu debuggen, das im Hauptprozess ausgeführt wird, benötigen Sie einen externen Debugger und müssen Electron mit der --inspect oder --inspect-brk Option starten.
Nutzen Sie eine der folgenden Befehlszeilenoptionen um das Debugging des Hauptprozesses zu aktivieren:
\n--inspect=[port]Electron will listen for V8 inspector protocol messages on the specified port, an external debugger will need to connect on this port. The default port is 5858.
electron --inspect=5858 your/app\n--inspect-brk=[port]Änhlich wie --inspect, pausiert jedoch die Ausführung des JavaScript-Codes auf der ersten Zeile.
Sie müssen einen Debugger verwenden, der das V8-Inspektor-Protokoll unterstützt.
\nchrome://inspect und wählen Sie 'Untersuchen' mit einem Rechtsklick auf die gestartete Electron-App aus.This guide goes over how to set up VSCode debugging for both your own Electron project as well as the native Electron codebase.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json mit der folgenden Konfiguration hinzu:{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"Debug Main Process\",\n \"type\": \"node\",\n \"request\": \"launch\",\n \"cwd\": \"${workspaceFolder}\",\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron\",\n \"windows\": {\n \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/electron.cmd\"\n },\n \"args\" : [\".\"],\n \"outputCapture\": \"std\"\n }\n ]\n}\nSet some breakpoints in main.js, and start debugging in the Debug View. You should be able to hit the breakpoints.
Hier finden Sie ein vorkonfiguriertes Projekt, dass Sie herunterladen und direkt in VSCode debuggen können: https://github.com/octref/vscode-electron-debug/tree/master/electron-quick-start
\nIf you want to build Electron from source and modify the native Electron codebase, this section will help you in testing your modifications.
\nFor those unsure where to acquire this code or how to build it, Electron's Build Tools automates and explains most of this process. If you wish to manually set up the environment, you can instead use these build instructions.
\n$ git clone git@github.com:electron/electron-quick-start.git\n$ code electron-quick-start\n.vscode/launch.json mit der folgenden Konfiguration hinzu:{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"(Windows) Launch\",\n \"type\": \"cppvsdbg\",\n \"request\": \"launch\",\n \"program\": \"${workspaceFolder}\\\\out\\\\your-executable-location\\\\electron.exe\",\n \"args\": [\"your-electron-project-path\"],\n \"stopAtEntry\": false,\n \"cwd\": \"${workspaceFolder}\",\n \"environment\": [\n {\"name\": \"ELECTRON_ENABLE_LOGGING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_ENABLE_STACK_DUMPING\", \"value\": \"true\"},\n {\"name\": \"ELECTRON_RUN_AS_NODE\", \"value\": \"\"},\n ],\n \"externalConsole\": false,\n \"sourceFileMap\": {\n \"o:\\\\\": \"${workspaceFolder}\",\n },\n },\n ]\n}\nConfiguration Notes
\ncppvsdbg requires the built-in C/C++ extension be enabled.${workspaceFolder} is the full path to Chromium's src directory.your-executable-location will be one of the following depending on a few items:Testing: If you are using the default settings of Electron's Build-Tools or the default instructions when building from source.Release: If you built a Release build rather than a Testing build.your-directory-name: If you modified this during your build process from the default, this will be whatever you specified.args array string \"your-electron-project-path\" should be the absolute path to either the directory or main.js file of the Electron project you are using for testing. In this example, it should be your path to electron-quick-start.Set some breakpoints in the .cc files of your choosing in the native Electron C++ code, and start debugging in the Debug View.
", "title": "Debugging in VSCode", "description": "" }, "/docs/api/desktop-capturer": { "locale": "de-DE", "slug": "desktop-capturer", "href": "/docs/api/desktop-capturer", "crowdinFileId": "256307", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/desktop-capturer.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\n\nAccess information about media sources that can be used to capture audio and video from the desktop using the
\nnavigator.mediaDevices.getUserMediaAPI.
Das folgende Beispiel zeigt, wie man Video von einem Desktop Fenster mit dem Titel Electron aufnehmen kann:
// In the renderer process.\nconst { desktopCapturer } = require('electron')\n\ndesktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources => {\n for (const source of sources) {\n if (source.name === 'Electron') {\n try {\n const stream = await navigator.mediaDevices.getUserMedia({\n audio: false,\n video: {\n mandatory: {\n chromeMediaSource: 'desktop',\n chromeMediaSourceId: source.id,\n minWidth: 1280,\n maxWidth: 1280,\n minHeight: 720,\n maxHeight: 720\n }\n }\n })\n handleStream(stream)\n } catch (e) {\n handleError(e)\n }\n return\n }\n }\n})\n\nfunction handleStream (stream) {\n const video = document.querySelector('video')\n video.srcObject = stream\n video.onloadedmetadata = (e) => video.play()\n}\n\nfunction handleError (e) {\n console.log(e)\n}\nTo capture video from a source provided by desktopCapturer the constraints passed to navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop', and audio: false.
To capture both audio and video from the entire desktop the constraints passed to navigator.mediaDevices.getUserMedia must include chromeMediaSource: 'desktop', for both audio and video, but should not include a chromeMediaSourceId constraint.
const constraints = {\n audio: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n },\n video: {\n mandatory: {\n chromeMediaSource: 'desktop'\n }\n }\n}\nDas Modul desktopCapturer verfügt über die folgenden Methoden:
desktopCapturer.getSources(options)options Objekttypes String[] - Ein Array von Strings, das die Typen der Desktop-Quellen auflistet die aufgezeichnet werden sollen, verfügbare Typen sind screen und window.thumbnailSize Size (optional) - Die Größe, auf die die Miniaturansicht der Medienquelle skaliert werden soll. Voreinstellung ist 150 x 150. Setzen Sie die Breite oder Höhe auf 0, wenn Sie kein Miniaturansichten benötigen. Dies reduziert die Verarbeitungszeit, die für die Erfassung des Inhalts der einzelnen Fenster und des Bildschirme benötigt wird.fetchWindowIcons Boolean (optional) - Auf true setzen, um das Abrufen von Fenstersymbolen zu aktivieren. Der Standard Wert ist false. Bei false gibt die appIcon-Eigenschaft der Quellen null zurück. Dasselbe gilt, wenn eine Quelle den Typ \"screen\" hat.Rückgabe Promise<DesktopCapturerSource[]> - Löst mit einem Array von DesktopCapturerSource-Objekte auf, wobei jede DesktopCapturerSource einen Bildschirm oder ein einzelnes Fenster darstellt, das erfasst werden kann.
Note Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher, which can detected by systemPreferences.getMediaAccessStatus.
navigator.mediaDevices.getUserMedia funktioniert unter macOS nicht für Audioaufnahmen aufgrund einer grundsätzlichen Einschränkung, bei der Apps, die auf das Audiosystem zugreifen wollen, eine signierte Kernel-Erweiterung benötigen. Chromium, und damit auch Electron, bieten dies nicht an.
Es ist möglich, diese Einschränkung zu umgehen, indem Sie das Systemaudio mit einer anderen macOS-App wie Soundflower aufnehmen und durch ein virtuelles Audioeingabegerät leiten. Dieses virtuellen Geräte können dann mit navigator.mediaDevices.getUserMedia abgefragt werden.
id String - The identifier of a window or screen that can be used as a chromeMediaSourceId constraint when calling [navigator.webkitGetUserMedia]. The format of the identifier will be window:XX:YY or screen:ZZ:0. XX is the windowID/handle. YY is 1 for the current process, and 0 for all others. ZZ is a sequential number that represents the screen, and it does not equal to the index in the source's name.name String - A screen source will be named either Entire Screen or Screen <index>, while the name of a window source will match the window title.thumbnail NativeImage - A thumbnail image. Note: There is no guarantee that the size of the thumbnail is the same as the thumbnailSize specified in the options passed to desktopCapturer.getSources. The actual size depends on the scale of the screen or window.display_id String - A unique identifier that will correspond to the id of the matching Display returned by the Screen API. On some platforms, this is equivalent to the XX portion of the id field above and on others it will differ. It will be an empty string if not available.appIcon NativeImage - An icon image of the application that owns the window or null if the source has a type screen. The size of the icon is not known in advance and depends on what the application provides.Like Chromium based browsers, Electron provides access to device hardware through web APIs. For the most part these APIs work like they do in a browser, but there are some differences that need to be taken into account. The primary difference between Electron and browsers is what happens when device access is requested. In a browser, users are presented with a popup where they can grant access to an individual device. In Electron APIs are provided which can be used by a developer to either automatically pick a device or prompt users to pick a device via a developer created interface.
\nThe Web Bluetooth API can be used to communicate with bluetooth devices. In order to use this API in Electron, developers will need to handle the select-bluetooth-device event on the webContents associated with the device request.
This example demonstrates an Electron application that automatically selects the first available bluetooth device when the Test Bluetooth button is clicked.
The WebHID API can be used to access HID devices such as keyboards and gamepads. Electron provides several APIs for working with the WebHID API:
\nselect-hid-device event on the Session can be used to select a HID device when a call to navigator.hid.requestDevice is made. Additionally the hid-device-added and hid-device-removed events on the Session can be used to handle devices being plugged in or unplugged during the navigator.hid.requestDevice process.ses.setDevicePermissionHandler(handler) can be used to provide default permissioning to devices without first calling for permission to devices via navigator.hid.requestDevice. Additionally, the default behavior of Electron is to store granted device permision through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.ses.setPermissionCheckHandler(handler) can be used to disable HID access for specific origins.By default Electron employs the same blocklist used by Chromium. If you wish to override this behavior, you can do so by setting the disable-hid-blocklist flag:
app.commandLine.appendSwitch('disable-hid-blocklist')\nThis example demonstrates an Electron application that automatically selects HID devices through ses.setDevicePermissionHandler(handler) and through select-hid-device event on the Session when the Test WebHID button is clicked.
The Web Serial API can be used to access serial devices that are connected via serial port, USB, or Bluetooth. In order to use this API in Electron, developers will need to handle the select-serial-port event on the Session associated with the serial port request.
There are several additional APIs for working with the Web Serial API:
\nserial-port-added and serial-port-removed events on the Session can be used to handle devices being plugged in or unplugged during the navigator.serial.requestPort process.ses.setPermissionCheckHandler(handler) can be used to disable serial access for specific origins.This example demonstrates an Electron application that automatically selects the first available Arduino Uno serial device (if connected) through select-serial-port event on the Session when the Test Web Serial button is clicked.
Electron supports Chrome DevTools extensions, which can be used to extend the ability of Chrome's developer tools for debugging popular web frameworks.
\nThe easiest way to load a DevTools extension is to use third-party tooling to automate the process for you. electron-devtools-installer is a popular NPM package that does just that.
\nIf you don't want to use the tooling approach, you can also do all of the necessary operations by hand. To load an extension in Electron, you need to download it via Chrome, locate its filesystem path, and then load it into your Session by calling the [ses.loadExtension] API.
Using the React Developer Tools as an example:
\nInstall the extension in Google Chrome.
\nNavigate to chrome://extensions, and find its extension ID, which is a hash string like fmkadmapgofadopljbjfkapdkoienihi.
Find out the filesystem location used by Chrome for storing extensions:
\n%LOCALAPPDATA%\\Google\\Chrome\\User Data\\Default\\Extensions;~/.config/google-chrome/Default/Extensions/~/.config/google-chrome-beta/Default/Extensions/~/.config/google-chrome-canary/Default/Extensions/~/.config/chromium/Default/Extensions/~/Library/Application Support/Google/Chrome/Default/Extensions.Pass the location of the extension to the ses.loadExtension API. For React Developer Tools v4.9.0, it looks something like:
const { app, session } = require('electron')\n const path = require('path')\n const os = require('os')\n\n // on macOS\n const reactDevToolsPath = path.join(\n os.homedir(),\n '/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.9.0_0'\n )\n\n app.whenReady().then(async () => {\n await session.defaultSession.loadExtension(reactDevToolsPath)\n })\nHinweise:
\nloadExtension returns a Promise with an Extension object, which contains metadata about the extension that was loaded. This promise needs to resolve (e.g. with an await expression) before loading a page. Otherwise, the extension won't be guaranteed to load.loadExtension cannot be called before the ready event of the app module is emitted, nor can it be called on in-memory (non-persistent) sessions.loadExtension must be called on every boot of your app if you want the extension to be loaded.You can pass the extension's ID to the ses.removeExtension API to remove it from your Session. Loaded extensions are not persisted between app launches.
Electron only supports a limited set of chrome.* APIs, so extensions using unsupported chrome.* APIs under the hood may not work.
The following Devtools extensions have been tested to work in Electron:
\nFirst, please make sure the extension is still being maintained and is compatible with the latest version of Google Chrome. We cannot provide additional support for unsupported extensions.
\nIf the extension works on Chrome but not on Electron, file a bug in Electron's issue tracker and describe which part of the extension is not working as expected.
", "title": "DevTools Erweiterung", "description": "" }, "/docs/api/dialog": { "locale": "de-DE", "slug": "dialog", "href": "/docs/api/dialog", "crowdinFileId": "256309", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/dialog.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nFür das Anzeigen von nativen Systemdialogen beim öffnen und speichern von Dateien, Warnungen, etc.
\n
Prozess: Haupt
\nAn example of showing a dialog to select multiple files:
\nconst { dialog } = require('electron')\nconsole.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))\nDas dialog module hat die folgenden Methoden:
dialog.showOpenDialogSync([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objekttitle String (optional)defaultPath String (optional)buttonLabel String (optional) - Custom label für den Bestätigen-Button. Wenn leer gelassen, dann wird das default label verwendet.filters FileFilter[] (optional)properties String[] (optional) - Contains which features the dialog should use. The following values are supported:openFile - Erlaubt die Auswahl von Dateien.openDirectory - Erlaubt die Auswahl von Verzeichnissen.multiSelections - Erlaubt die Auswahl mehrerer Pfade.showHiddenFiles - Zeige versteckte Dateien im Dialog.createDirectory macOS - Erlaube das Erstellen neuer Verzeichnisse im Dialog.promptToCreate Windows - Prompt for creation if the file path entered in the dialog does not exist. This does not actually create the file at the path but allows non-existent paths to be returned that should be created by the application.noResolveAliases macOS - Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.treatPackageAsDirectory macOS - Treat packages, such as .app folders, as a directory instead of a file.dontAddToRecent Windows - Do not add the item being opened to the recent documents list.message String (optional) macOS - Message to display above input boxes.securityScopedBookmarks Boolean (optional) macOS mas - Create security scoped bookmarks when packaged for the Mac App Store.Returns String[] | undefined, the file paths chosen by the user; if the dialog is cancelled it returns undefined.
The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Ein Beispiel:
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nThe extensions array should contain extensions without wildcards or dots (e.g. 'png' is good but '.png' and '*.png' are bad). To show all files, use the '*' wildcard (no other wildcard is supported).
Note: On Windows and Linux an open dialog can not be both a file selector and a directory selector, so if you set properties to ['openFile', 'openDirectory'] on these platforms, a directory selector will be shown.
dialog.showOpenDialogSync(mainWindow, {\n properties: ['openFile', 'openDirectory']\n})\ndialog.showOpenDialog([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objekttitle String (optional)defaultPath String (optional)buttonLabel String (optional) - Custom label für den Bestätigen-Button. Wenn leer gelassen, dann wird das default label verwendet.filters FileFilter[] (optional)properties String[] (optional) - Contains which features the dialog should use. The following values are supported:openFile - Erlaubt die Auswahl von Dateien.openDirectory - Erlaubt die Auswahl von Verzeichnissen.multiSelections - Erlaubt die Auswahl mehrerer Pfade.showHiddenFiles - Zeige versteckte Dateien im Dialog.createDirectory macOS - Erlaube das Erstellen neuer Verzeichnisse im Dialog.promptToCreate Windows - Prompt for creation if the file path entered in the dialog does not exist. This does not actually create the file at the path but allows non-existent paths to be returned that should be created by the application.noResolveAliases macOS - Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.treatPackageAsDirectory macOS - Treat packages, such as .app folders, as a directory instead of a file.dontAddToRecent Windows - Do not add the item being opened to the recent documents list.message String (optional) macOS - Message to display above input boxes.securityScopedBookmarks Boolean (optional) macOS mas - Create security scoped bookmarks when packaged for the Mac App Store.Returns Promise<Object> - Resolve with an object containing the following:
canceled Boolean - whether or not the dialog was canceled.filePaths String[] - An array of file paths chosen by the user. If the dialog is cancelled this will be an empty array.bookmarks String[] (optional) macOS mas - An array matching the filePaths array of base64 encoded strings which contains security scoped bookmark data. securityScopedBookmarks must be enabled for this to be populated. (For return values, see table here.)The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Ein Beispiel:
{\n filters: [\n { name: 'Images', extensions: ['jpg', 'png', 'gif'] },\n { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },\n { name: 'Custom File Type', extensions: ['as'] },\n { name: 'All Files', extensions: ['*'] }\n ]\n}\nThe extensions array should contain extensions without wildcards or dots (e.g. 'png' is good but '.png' and '*.png' are bad). To show all files, use the '*' wildcard (no other wildcard is supported).
Note: On Windows and Linux an open dialog can not be both a file selector and a directory selector, so if you set properties to ['openFile', 'openDirectory'] on these platforms, a directory selector will be shown.
dialog.showOpenDialog(mainWindow, {\n properties: ['openFile', 'openDirectory']\n}).then(result => {\n console.log(result.canceled)\n console.log(result.filePaths)\n}).catch(err => {\n console.log(err)\n})\ndialog.showSaveDialogSync([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objekttitle String (optional) - The dialog title. Cannot be displayed on some Linux desktop environments.defaultPath String (optional) - Absolute directory path, absolute file path, or file name to use by default.buttonLabel String (optional) - Custom label für den Bestätigen-Button. Wenn leer gelassen, dann wird das default label verwendet.filters FileFilter[] (optional)message String (optional) macOS - Message to display above text fields.nameFieldLabel String (optional) macOS - Custom label for the text displayed in front of the filename text field.showsTagField Boolean (optional) macOS - Show the tags input box, defaults to true.properties String[] (optional)showHiddenFiles - Zeige versteckte Dateien im Dialog.createDirectory macOS - Erlaube das Erstellen neuer Verzeichnisse im Dialog.treatPackageAsDirectory macOS - Treat packages, such as .app folders, as a directory instead of a file.showOverwriteConfirmation Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.dontAddToRecent Windows - Do not add the item being saved to the recent documents list.securityScopedBookmarks Boolean (optional) macOS mas - Create a security scoped bookmark when packaged for the Mac App Store. If this option is enabled and the file doesn't already exist a blank file will be created at the chosen path.Returns String | undefined, the path of the file chosen by the user; if the dialog is cancelled it returns undefined.
The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
The filters specifies an array of file types that can be displayed, see dialog.showOpenDialog for an example.
dialog.showSaveDialog([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objekttitle String (optional) - The dialog title. Cannot be displayed on some Linux desktop environments.defaultPath String (optional) - Absolute directory path, absolute file path, or file name to use by default.buttonLabel String (optional) - Custom label für den Bestätigen-Button. Wenn leer gelassen, dann wird das default label verwendet.filters FileFilter[] (optional)message String (optional) macOS - Message to display above text fields.nameFieldLabel String (optional) macOS - Custom label for the text displayed in front of the filename text field.showsTagField Boolean (optional) macOS - Show the tags input box, defaults to true.properties String[] (optional)showHiddenFiles - Zeige versteckte Dateien im Dialog.createDirectory macOS - Erlaube das Erstellen neuer Verzeichnisse im Dialog.treatPackageAsDirectory macOS - Treat packages, such as .app folders, as a directory instead of a file.showOverwriteConfirmation Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.dontAddToRecent Windows - Do not add the item being saved to the recent documents list.securityScopedBookmarks Boolean (optional) macOS mas - Create a security scoped bookmark when packaged for the Mac App Store. If this option is enabled and the file doesn't already exist a blank file will be created at the chosen path.Returns Promise<Object> - Resolve with an object containing the following:
canceled Boolean - whether or not the dialog was canceled.filePath String (optional) - If the dialog is canceled, this will be undefined.bookmark String (optional) macOS mas - Base64 encoded string which contains the security scoped bookmark data for the saved file. securityScopedBookmarks must be enabled for this to be present. (For return values, see table here.)The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
The filters specifies an array of file types that can be displayed, see dialog.showOpenDialog for an example.
Note: On macOS, using the asynchronous version is recommended to avoid issues when expanding and collapsing the dialog.
\ndialog.showMessageBoxSync([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objektmessage String - Content of the message box.type String (optional) - Can be \"none\", \"info\", \"error\", \"question\" or \"warning\". On Windows, \"question\" displays the same icon as \"info\", unless you set an icon using the \"icon\" option. On macOS, both \"warning\" and \"error\" display the same warning icon.buttons String[] (optional) - Array of texts for buttons. On Windows, an empty array will result in one button labeled \"OK\".defaultId Integer (optional) - Index of the button in the buttons array which will be selected by default when the message box opens.title String (optional) - Title of the message box, some platforms will not show it.detail String (optional) - Extra information of the message.icon (NativeImage | String) (optional)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (optional) - The index of the button to be used to cancel the dialog, via the Esc key. By default this is assigned to the first button with \"cancel\" or \"no\" as the label. If no such labeled buttons exist and this option is not set, 0 will be used as the return value.noLink Boolean (optional) - On Windows Electron will try to figure out which one of the buttons are common buttons (like \"Cancel\" or \"Yes\"), and show the others as command links in the dialog. This can make the dialog appear in the style of modern Windows apps. If you don't like this behavior, you can set noLink to true.normalizeAccessKeys Boolean (optional) - Normalize the keyboard access keys across platforms. Standard ist false. Enabling this assumes & is used in the button labels for the placement of the keyboard shortcut access key and labels will be converted so they work correctly on each platform, & characters are removed on macOS, converted to _ on Linux, and left untouched on Windows. For example, a button label of Vie&w will be converted to Vie_w on Linux and View on macOS and can be selected via Alt-W on Windows and Linux.Returns Integer - the index of the clicked button.
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button.
\nThe browserWindow argument allows the dialog to attach itself to a parent window, making it modal. If browserWindow is not shown dialog will not be attached to it. In such case it will be displayed as an independent window.
dialog.showMessageBox([browserWindow, ]options)browserWindow BrowserWindow (optional)options Objektmessage String - Content of the message box.type String (optional) - Can be \"none\", \"info\", \"error\", \"question\" or \"warning\". On Windows, \"question\" displays the same icon as \"info\", unless you set an icon using the \"icon\" option. On macOS, both \"warning\" and \"error\" display the same warning icon.buttons String[] (optional) - Array of texts for buttons. On Windows, an empty array will result in one button labeled \"OK\".defaultId Integer (optional) - Index of the button in the buttons array which will be selected by default when the message box opens.signal AbortSignal (optional) - Pass an instance of AbortSignal to optionally close the message box, the message box will behave as if it was cancelled by the user. On macOS, signal does not work with message boxes that do not have a parent window, since those message boxes run synchronously due to platform limitations.title String (optional) - Title of the message box, some platforms will not show it.detail String (optional) - Extra information of the message.checkboxLabel String (optional) - If provided, the message box will include a checkbox with the given label.checkboxChecked Boolean (optional) - Initial checked state of the checkbox. Automatisch false.icon NativeImage (optional)textWidth Integer (optional) macOS - Custom width of the text in the message box.cancelId Integer (optional) - The index of the button to be used to cancel the dialog, via the Esc key. By default this is assigned to the first button with \"cancel\" or \"no\" as the label. If no such labeled buttons exist and this option is not set, 0 will be used as the return value.noLink Boolean (optional) - On Windows Electron will try to figure out which one of the buttons are common buttons (like \"Cancel\" or \"Yes\"), and show the others as command links in the dialog. This can make the dialog appear in the style of modern Windows apps. If you don't like this behavior, you can set noLink to true.normalizeAccessKeys Boolean (optional) - Normalize the keyboard access keys across platforms. Standard ist false. Enabling this assumes & is used in the button labels for the placement of the keyboard shortcut access key and labels will be converted so they work correctly on each platform, & characters are removed on macOS, converted to _ on Linux, and left untouched on Windows. For example, a button label of Vie&w will be converted to Vie_w on Linux and View on macOS and can be selected via Alt-W on Windows and Linux.Returns Promise<Object> - resolves with a promise containing the following properties:
response Number - The index of the clicked button.checkboxChecked Boolean - The checked state of the checkbox if checkboxLabel was set. Otherwise false.Shows a message box.
\nThe browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
dialog.showErrorBox(title, content)title String - The title to display in the error box.content String - The text content to display in the error box.Displays a modal dialog that shows an error message.
\nThis API can be called safely before the ready event the app module emits, it is usually used to report errors in early stage of startup. If called before the app readyevent on Linux, the message will be emitted to stderr, and no GUI dialog will appear.
dialog.showCertificateTrustDialog([browserWindow, ]options) macOS WindowsbrowserWindow BrowserWindow (optional)options Objektcertificate Certificate - The certificate to trust/import.message String - The message to display to the user.Returns Promise<void> - resolves when the certificate trust dialog is shown.
On macOS, this displays a modal dialog that shows a message and certificate information, and gives the user the option of trusting/importing the certificate. If you provide a browserWindow argument the dialog will be attached to the parent window, making it modal.
On Windows the options are more limited, due to the Win32 APIs used:
\nmessage argument is not used, as the OS provides its own confirmation dialog.browserWindow argument is ignored since it is not possible to make this confirmation dialog modal.showOpenDialog, showOpenDialogSync, showSaveDialog, and showSaveDialogSync will return a bookmarks array.
| Build Type | securityScopedBookmarks boolean | Return Type | Return Value |
|---|---|---|---|
| macOS mas | True | Success | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | Error | [''] (array of empty string) |
| macOS mas | False | NA | [] (empty array) |
| non mas | any | NA | [] (empty array) |
On macOS, dialogs are presented as sheets attached to a window if you provide a BrowserWindow reference in the browserWindow parameter, or modals if no window is provided.
You can call BrowserWindow.getCurrentWindow().setSheetOffset(offset) to change the offset from the window frame where sheets are attached.
id Number - Unique identifier associated with the display.rotation Number - Can be 0, 90, 180, 270, represents screen rotation in clock-wise degrees.scaleFactor Number - Output device's pixel scale factor.touchSupport String - Can be available, unavailable, unknown.monochrome Boolean - Whether or not the display is a monochrome display.accelerometerSupport String - Can be available, unavailable, unknown.colorSpace String - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversionscolorDepth Number - The number of bits per pixel.depthPerComponent Number - The number of bits per color component.displayFrequency Number - The display refresh rate.bounds Rectangle - the bounds of the display in DIP points.size SizeworkArea Rectangle - the work area of the display in DIP points.workAreaSize Sizeinternal Boolean - true for an internal display and false for an external displayThe Display object represents a physical display connected to the system. A fake Display may exist on a headless system, or a Display may correspond to a remote, virtual display.
\n\nSteuern Sie Ihre App im MacOS-Dock
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Das folgende Beispiel zeigt, wie Sie Ihr Icon auf dem Dock springen lassen.
\nconst { app } = require('electron')\napp.dock.bounce()\ndock.bounce([type]) macOStype String (optional) - Kann critical oder informational sein. Standard ist informationalReturns Integer - Eine ID welche den Request repräsentiert.
When critical is passed, the dock icon will bounce until either the application becomes active or the request is canceled.
When informational is passed, the dock icon will bounce for one second. However, the request remains active until either the application becomes active or the request is canceled.
Nota Bene: This method can only be used while the app is not focused; when the app is focused it will return -1.
\ndock.cancelBounce(id) macOSid IntegerCancel the bounce of id.
dock.downloadFinished(filePath) macOSfilePath StringBounces the Downloads stack if the filePath is inside the Downloads folder.
\ndock.setBadge(text) macOStext StringSets the string to be displayed in the dock’s badging area.
\ndock.getBadge() macOSReturns String - The badge string of the dock.
dock.hide() macOSVersteckt das dock icon.
\ndock.show() macOSReturns Promise<void> - Resolves when the dock icon is shown.
dock.isVisible() macOSReturns Boolean - Whether the dock icon is visible.
dock.setMenu(menu) macOSmenu MenuSets the application's [dock menu][dock-menu].
\ndock.getMenu() macOSReturns Menu | null - The application's [dock menu][dock-menu].
dock.setIcon(image) macOSimage (NativeImage | String)Setzt das image welches als Dock Icon verwendet werden soll.
\n\nControl file downloads from remote sources.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
DownloadItem is an EventEmitter that represents a download item in Electron. It is used in will-download event of Session class, and allows users to control the download item.
// Im Hauptprozess.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.session.on('will-download', (event, item, webContents) => {\n // Set the save path, making Electron not to prompt a save dialog.\n item.setSavePath('/tmp/save.pdf')\n\n item.on('updated', (event, state) => {\n if (state === 'interrupted') {\n console.log('Download is interrupted but can be resumed')\n } else if (state === 'progressing') {\n if (item.isPaused()) {\n console.log('Download is paused')\n } else {\n console.log(`Received bytes: ${item.getReceivedBytes()}`)\n }\n }\n })\n item.once('done', (event, state) => {\n if (state === 'completed') {\n console.log('Download successfully')\n } else {\n console.log(`Download failed: ${state}`)\n }\n })\n})\nKehrt zurück:
\nevent Eventstate String - Can be progressing or interrupted.Ausgelöst, wenn sich der Status des Downloads geändert hat, aber der Download nicht fertig ist.
\nThe state can be one of following:
progressing - The download is in-progress.interrupted - The download has interrupted and can be resumed.Kehrt zurück:
\nevent Eventstate String - Can be completed, cancelled or interrupted.Ausgelöst, wenn der Download beendet wurde. This includes a completed download, a cancelled download (via downloadItem.cancel()), and interrupted download that can't be resumed.
The state can be one of following:
completed - The download completed successfully.cancelled - The download has been cancelled.interrupted - The download has interrupted and can not resume.The downloadItem object has the following methods:
downloadItem.setSavePath(path)path String - Set the save file path of the download item.The API is only available in session's will-download callback function. If path doesn't exist, Electron will try to make the directory recursively. If user doesn't set the save path via the API, Electron will use the original routine to determine the save path; this usually prompts a save dialog.
downloadItem.getSavePath()Returns String - The save path of the download item. This will be either the path set via downloadItem.setSavePath(path) or the path selected from the shown save dialog.
downloadItem.setSaveDialogOptions(options)options SaveDialogOptions - Set the save file dialog options. This object has the same properties as the options parameter of dialog.showSaveDialog().This API allows the user to set custom options for the save dialog that opens for the download item by default. The API is only available in session's will-download callback function.
downloadItem.getSaveDialogOptions()Returns SaveDialogOptions - Returns the object previously set by downloadItem.setSaveDialogOptions(options).
downloadItem.pause()Pauses the download.
\ndownloadItem.isPaused()Returns Boolean - Whether the download is paused.
downloadItem.resume()Resumes the download that has been paused.
\nNote: To enable resumable downloads the server you are downloading from must support range requests and provide both Last-Modified and ETag header values. Otherwise resume() will dismiss previously received bytes and restart the download from the beginning.
downloadItem.canResume()Returns Boolean - Whether the download can resume.
downloadItem.cancel()Cancels the download operation.
\ndownloadItem.getURL()Returns String - The origin URL where the item is downloaded from.
downloadItem.getMimeType()Returns String - The files mime type.
downloadItem.hasUserGesture()Returns Boolean - Whether the download has user gesture.
downloadItem.getFilename()Returns String - The file name of the download item.
Note: The file name is not always the same as the actual one saved in local disk. If user changes the file name in a prompted download saving dialog, the actual name of saved file will be different.
\ndownloadItem.getTotalBytes()Returns Integer - The total size in bytes of the download item.
If the size is unknown, it returns 0.
\ndownloadItem.getReceivedBytes()Returns Integer - The received bytes of the download item.
downloadItem.getContentDisposition()Returns String - The Content-Disposition field from the response header.
downloadItem.getState()Returns String - The current state. Can be progressing, completed, cancelled or interrupted.
Note: The following methods are useful specifically to resume a cancelled item when session is restarted.
downloadItem.getURLChain()Returns String[] - The complete URL chain of the item including any redirects.
downloadItem.getLastModifiedTime()Returns String - Last-Modified header value.
downloadItem.getETag()Returns String - ETag header value.
downloadItem.getStartTime()Returns Double - Number of seconds since the UNIX epoch when the download was started.
downloadItem.savePathA String property that determines the save file path of the download item.
The property is only available in session's will-download callback function. If user doesn't set the save path via the property, Electron will use the original routine to determine the save path; this usually prompts a save dialog.
Special notes:
\n-beta.1 and stable dates are our solid release dates.| Electron | Alpha | Beta | Stabil | Chrome | Node |
|---|---|---|---|---|---|
| 2.0.0 | -- | 2018-Feb-21 | 2018-May-01 | M61 | v8.9 |
| 3.0.0 | -- | 2018-Jun-21 | 2018-Sep-18 | M66 | v10.2 |
| 4.0.0 | -- | 2018-Oct-11 | 2018-Dec-20 | M69 | v10.11 |
| 5.0.0 | -- | 2019-Jan-22 | 2019-Apr-24 | M73 | v12.0 |
| 6.0.0 | -- | 2019-May-01 | 2019-Jul-30 | M76 | v12.4 |
| 7.0.0 | -- | 2019-Aug-01 | 2019-Oct-22 | M78 | v12.8 |
| 8.0.0 | -- | 2019-Oct-24 | 2020-Feb-04 | M80 | v12.13 |
| 9.0.0 | -- | 2020-Feb-06 | 2020-May-19 | M83 | v12.14 |
| 10.0.0 | -- | 2020-May-21 | 2020-Aug-25 | M85 | v12.16 |
| 11.0.0 | -- | 2020-Aug-27 | 2020-Nov-17 | M87 | v12.18 |
| 12.0.0 | -- | 2020-Nov-19 | 2021-Mar-02 | M89 | v14.16 |
| 13.0.0 | -- | 2021-Mar-04 | 2021-May-25 | M91 | v14.16 |
| 14.0.0 | -- | 2021-May-27 | 2021-Aug-31 | M93 | v14.17 |
| 15.0.0 | 2021-Jul-20 | 2021-Sep-01 | 2021-Sep-21 | M94 | v16.5 |
| 16.0.0 | -- | 2021-Sep-23 | 2021-Nov-16 | M96 | TBD |
\n\nA detailed look at our versioning policy and implementation.
\n
As of version 2.0.0, Electron follows SemVer. The following command will install the most recent stable build of Electron:
\nnpm install --save-dev electron\nTo update an existing project to use the latest stable version:
\nnpm install --save-dev electron@latest\nElectron versions < 2.0 did not conform to the SemVer spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. While convenient for developers merging features, it creates problems for developers of client-facing applications. The QA testing cycles of major apps like Slack, Stride, Teams, Skype, VS Code, Atom, and Desktop can be lengthy and stability is a highly desired outcome. There is a high risk in adopting new features while trying to absorb bug fixes.
\nHere is an example of the 1.x strategy:
\n
An app developed with 1.8.1 cannot take the 1.8.3 bug fix without either absorbing the 1.8.2 feature, or by backporting the fix and maintaining a new release line.
There are several major changes from our 1.x strategy outlined below. Each change is intended to satisfy the needs and priorities of developers/maintainers and app developers.
\n-beta tagsmaster branch is versionless; only stabilization branches contain version informationWe will cover in detail how git branching works, how npm tagging works, what developers should expect to see, and how one can backport changes.
\nFrom 2.0 onward, Electron will follow SemVer.
\nBelow is a table explicitly mapping types of changes to their corresponding category of SemVer (e.g. Major, Minor, Patch).
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Major Version Increments | Minor Version Increments | Patch Version Increments |
|---|---|---|
| Electron breaking API changes | Electron non-breaking API changes | Electron bug fixes |
| Node.js major version updates | Node.js minor version updates | Node.js patch version updates |
| Chromium version updates | fix-related chromium patches |
Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
\nStabilization branches are branches that run parallel to master, taking in only cherry-picked commits that are related to security or stability. These branches are never merged back to master.
\n
Since Electron 8, stabilization branches are always major version lines, and named against the following template $MAJOR-x-y e.g. 8-x-y. Prior to that we used minor version lines and named them as $MAJOR-$MINOR-x e.g. 2-0-x
We allow for multiple stabilization branches to exist simultaneously, and intend to support at least two in parallel at all times, backporting security fixes as necessary.
Older lines will not be supported by GitHub, but other groups can take ownership and backport stability and security fixes on their own. We discourage this, but recognize that it makes life easier for many app developers.
\nDevelopers want to know which releases are safe to use. Even seemingly innocent features can introduce regressions in complex applications. At the same time, locking to a fixed version is dangerous because you’re ignoring security patches and bug fixes that may have come out since your version. Our goal is to allow the following standard semver ranges in package.json :
~2.0.0 to admit only stability or security related fixes to your 2.0.0 release.^2.0.0 to admit non-breaking reasonably stable feature work as well as security and bug fixes.What’s important about the second point is that apps using ^ should still be able to expect a reasonable level of stability. To accomplish this, SemVer allows for a pre-release identifier to indicate a particular version is not yet safe or stable.
Whatever you choose, you will periodically have to bump the version in your package.json as breaking changes are a fact of Chromium life.
The process is as follows:
\nbeta.N, e.g. 2.0.0-beta.1. After the first beta, subsequent beta releases must meet all of the following conditions:2.0.0-beta.2.2.0.0. After the first stable, all changes must be backwards-compatible bug or security fixes.2.0.1.Specifically, the above means:
\nFor each major and minor bump, you should expect to see something like the following:
\n2.0.0-beta.1\n2.0.0-beta.2\n2.0.0-beta.3\n2.0.0\n2.0.1\n2.0.2\nAn example lifecycle in pictures:
\n2.0.0-beta.1. 2.0.0-beta.2. 2.0.0. 2-0-x line and release 2.0.1. A few examples of how various SemVer ranges will pick up new releases:
\n
Our strategy has a few tradeoffs, which for now we feel are appropriate. Most importantly that new features in master may take a while before reaching a stable release line. If you want to try a new feature immediately, you will have to build Electron yourself.
\nAs a future consideration, we may introduce one or both of the following:
\nFeature flags are a common practice in Chromium, and are well-established in the web-development ecosystem. In the context of Electron, a feature flag or soft branch must have the following properties:
\nWe seek to increase clarity at all levels of the update and releases process. Starting with 2.0.0 we will require pull requests adhere to the Conventional Commits spec, which can be summarized as follows:
Commits that would result in a SemVer major bump must start their body with BREAKING CHANGE:.
Commits that would result in a SemVer minor bump must start with feat:.
Commits that would result in a SemVer patch bump must start with fix:.
We allow squashing of commits, provided that the squashed message adheres to the above message format.
\nIt is acceptable for some commits in a pull request to not include a semantic prefix, as long as the pull request title contains a meaningful encompassing semantic message.
\nmastermaster branch will always contain the next major version X.0.0-nightly.DATE in its package.jsonpackage.jsonmaster is always versioned as the next theoretical release branchLike NW.js, Electron provides a platform to write desktop applications with web technologies. Both platforms enable developers to utilize HTML, JavaScript, and Node.js. On the surface, they seem very similar.
\nThere are however fundamental differences between the two projects that make Electron a completely separate product from NW.js.
\nIn NW.js, the main entry point of an application can be an HTML web page. In that case, NW.js will open the given entry point in a browser window.
\nIn Electron, the entry point is always a JavaScript script. Instead of providing a URL directly, you manually create a browser window and load an HTML file using the API. You also need to listen to window events to decide when to quit the application.
\nElectron works more like the Node.js runtime. Electron's APIs are lower level so you can use it for browser testing in place of PhantomJS.
\nIn NW.js, the Node integration in web pages requires patching Chromium to work, while in Electron we chose a different way to integrate the libuv loop with each platform's message loop to avoid hacking Chromium. See the node_bindings code for how that was done.
If you are an experienced NW.js user, you should be familiar with the concept of Node context and web context. These concepts were invented because of how NW.js was implemented.
\nBy using the multi-context feature of Node, Electron doesn't introduce a new JavaScript context in web pages.
\nNote: NW.js has optionally supported multi-context since 0.13.
\nNW.js still offers a \"legacy release\" that supports Windows XP. It doesn't receive security updates.
\nGiven that hardware manufacturers, Microsoft, Chromium, and Node.js haven't released even critical security updates for that system, we have to warn you that using Windows XP is wildly insecure and outright irresponsible.
\nHowever, we understand that requirements outside our wildest imagination may exist, so if you're looking for something like Electron that runs on Windows XP, the NW.js legacy release might be the right fit for you.
\nThere are numerous differences in the amount of supported features. Electron has a bigger community, more production apps using it, and a large amount of userland modules available on npm.
\nAs an example, Electron has built-in support for automatic updates and countless tools that make the creation of installers easier. As an example in favor of NW.js, NW.js supports more Chrome.* APIs for the development of Chrome Apps.
Naturally, we believe that Electron is the better platform for polished production applications built with web technologies (like Visual Studio Code, Slack, or Facebook Messenger); however, we want to be fair to our web technology friends. If you have feature needs that Electron does not meet, you might want to try NW.js.
", "title": "Technical Differences Between Electron and NW.js", "description": "" }, "/docs/api/environment-variables": { "locale": "de-DE", "slug": "environment-variables", "href": "/docs/api/environment-variables", "crowdinFileId": "256315", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/environment-variables.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nDie Konfiguration und das Verhalten des Programms kontrollieren ohne das Programm umzuschreiben.
\n
Certain Electron behaviors are controlled by environment variables because they are initialized earlier than the command line flags and the app's code.
\nPOSIX shell example:
\n$ export ELECTRON_ENABLE_LOGGING=true\n$ electron\nWindows console example:
\n> set ELECTRON_ENABLE_LOGGING=true\n> electron\nThe following environment variables are intended primarily for use at runtime in packaged Electron applications.
\nNODE_OPTIONSElectron includes support for a subset of Node's NODE_OPTIONS. The majority are supported with the exception of those which conflict with Chromium's use of BoringSSL.
Beispiel:
\nexport NODE_OPTIONS=\"--no-warnings --max-old-space-size=2048\"\nUnsupported options are:
\n--use-bundled-ca\n--force-fips\n--enable-fips\n--openssl-config\n--use-openssl-ca\nNODE_OPTIONS are explicitly disallowed in packaged apps, except for the following:
--max-http-header-size\n--http-parser\nGOOGLE_API_KEYGeolocation support in Electron requires the use of Google Cloud Platform's geolocation webservice. To enable this feature, acquire a Google API key and place the following code in your main process file, before opening any browser windows that will make geolocation requests:
\nprocess.env.GOOGLE_API_KEY = 'YOUR_KEY_HERE'\nBy default, a newly generated Google API key may not be allowed to make geolocation requests. To enable the geolocation webservice for your project, enable it through the API library.
\nN.B. You will need to add a Billing Account to the project associated to the API key for the geolocation webservice to work.
\nELECTRON_NO_ASARDisables ASAR support. This variable is only supported in forked child processes and spawned child processes that set ELECTRON_RUN_AS_NODE.
ELECTRON_RUN_AS_NODEStarts the process as a normal Node.js process.
\nIn this mode, you will be able to pass cli options to Node.js as you would when running the normal Node.js executable, with the exception of the following flags:
\nThese flags are disabled owing to the fact that Electron uses BoringSSL instead of OpenSSL when building Node.js' crypto module, and so will not work as designed.
ELECTRON_NO_ATTACH_CONSOLE WindowsDon't attach to the current console session.
\nELECTRON_FORCE_WINDOW_MENU_BAR LinuxDon't use the global menu bar on Linux.
\nELECTRON_TRASH LinuxSet the trash implementation on Linux. Standard ist gio.
Options:
\ngvfs-trashtrash-clikioclient5kioclientThe following environment variables are intended primarily for development and debugging purposes.
\nELECTRON_ENABLE_LOGGINGPrints Chromium's internal logging to the console.
\nSetting this variable is the same as passing --enable-logging on the command line. For more info, see --enable-logging in command-line switches.
ELECTRON_LOG_FILESets the file destination for Chromium's internal logging.
\nSetting this variable is the same as passing --log-file on the command line. For more info, see --log-file in command-line switches.
ELECTRON_DEBUG_DRAG_REGIONSAdds coloration to draggable regions on BrowserViews on macOS - draggable regions will be colored green and non-draggable regions will be colored red to aid debugging.
ELECTRON_DEBUG_NOTIFICATIONSAdds extra logs to Notification lifecycles on macOS to aid in debugging. Extra logging will be displayed when new Notifications are created or activated. They will also be displayed when common a tions are taken: a notification is shown, dismissed, its button is clicked, or it is replied to.
Sample output:
\nNotification created (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification displayed (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification activated (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nNotification replied to (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)\nELECTRON_LOG_ASAR_READSWhen Electron reads from an ASAR file, log the read offset and file path to the system tmpdir. The resulting file can be provided to the ASAR module to optimize file ordering.
ELECTRON_ENABLE_STACK_DUMPINGPrints the stack trace to the console when Electron crashes.
\nThis environment variable will not work if the crashReporter is started.
ELECTRON_DEFAULT_ERROR_MODE WindowsShows the Windows's crash dialog when Electron crashes.
\nThis environment variable will not work if the crashReporter is started.
ELECTRON_OVERRIDE_DIST_PATHWhen running from the electron package, this variable tells the electron command to use the specified build of Electron instead of the one downloaded by npm install. Nutzung:
export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing\nElectron sets some variables in your environment at runtime.
\nORIGINAL_XDG_CURRENT_DESKTOPThis variable is set to the value of XDG_CURRENT_DESKTOP that your application originally launched with. Electron sometimes modifies the value of XDG_CURRENT_DESKTOP to affect other logic within Chromium so if you want access to the original value you should look up this environment variable instead.
GlobalEventpreventDefault VoidFunctionSome of Electrons APIs are tagged with _Experimental_ in the documentation. This tag indicates that the API may not be considered stable and the API may be removed or modified more frequently than other APIs with less warning.
Anyone can request an API be tagged as experimental in a feature PR, disagreements on the experimental nature of a feature can be discussed in the API WG if they can't be resolved in the PR.
\nOnce an API has been stable and in at least two major stable release lines it can be nominated to have its experimental tag removed. This discussion should happen at an API WG meeting. Things to consider when discussing / nominating:
\nid Zeichenfolgemanifest any - Copy of the extension's manifest data.name Zeichenfolgepath String - The extension's file path.version Stringurl String - The extension's chrome-extension:// URL.name Zeichenfolgeversion StringElectron supports a subset of the Chrome Extensions API, primarily to support DevTools extensions and Chromium-internal extensions, but it also happens to support some other extension capabilities.
\n\n\nNote: Electron does not support arbitrary Chrome extensions from the store, and it is a non-goal of the Electron project to be perfectly compatible with Chrome's implementation of Extensions.
\n
Electron only supports loading unpacked extensions (i.e., .crx files do not work). Extensions are installed per-session. To load an extension, call ses.loadExtension:
const { session } = require('electron')\n\nsession.loadExtension('path/to/unpacked/extension').then(({ id }) => {\n // ...\n})\nLoaded extensions will not be automatically remembered across exits; if you do not call loadExtension when the app runs, the extension will not be loaded.
Note that loading extensions is only supported in persistent sessions. Attempting to load an extension into an in-memory session will throw an error.
\nSee the session documentation for more information about loading, unloading, and querying active extensions.
We support the following extensions APIs, with some caveats. Other APIs may additionally be supported, but support for any APIs not listed here is provisional and may be removed.
\nchrome.devtools.inspectedWindowAll features of this API are supported.
\nchrome.devtools.networkAll features of this API are supported.
\nchrome.devtools.panelsAll features of this API are supported.
\nchrome.extensionThe following properties of chrome.extension are supported:
chrome.extension.lastErrorThe following methods of chrome.extension are supported:
chrome.extension.getURLchrome.extension.getBackgroundPagechrome.runtimeThe following properties of chrome.runtime are supported:
chrome.runtime.lastErrorchrome.runtime.idThe following methods of chrome.runtime are supported:
chrome.runtime.getBackgroundPagechrome.runtime.getManifestchrome.runtime.getPlatformInfochrome.runtime.getURLchrome.runtime.connectchrome.runtime.sendMessagechrome.runtime.reloadThe following events of chrome.runtime are supported:
chrome.runtime.onStartupchrome.runtime.onInstalledchrome.runtime.onSuspendchrome.runtime.onSuspendCanceledchrome.runtime.onConnectchrome.runtime.onMessagechrome.storageOnly chrome.storage.local is supported; chrome.storage.sync and chrome.storage.managed are not.
chrome.tabsThe following methods of chrome.tabs are supported:
chrome.tabs.sendMessagechrome.tabs.executeScript\n\nNote: In Chrome, passing
\n-1as a tab ID signifies the \"currently active tab\". Since Electron has no such concept, passing-1as a tab ID is not supported and will raise an error.
chrome.managementThe following methods of chrome.management are supported:
chrome.management.getAllchrome.management.getchrome.management.getSelfchrome.management.getPermissionWarningsByIdchrome.management.getPermissionWarningsByManifestchrome.management.onEnabledchrome.management.onDisabledchrome.webRequestAll features of this API are supported.
\n\n", "title": "Chrome Extension Support", "description": "Note: Electron does not support arbitrary Chrome extensions from the store, and it is a non-goal of the Electron project to be perfectly compatible with Chrome's implementation of Extensions." }, "/docs/faq": { "locale": "de-DE", "slug": "faq", "href": "/docs/faq", "crowdinFileId": "256121", "githubUrl": "https://github.com/electron/electron/tree/main/docs/faq.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "NOTE: Electron's
\nwebRequestmodule takes precedence overchrome.webRequestif there are conflicting handlers.
Beim Ausführen von npm install electron können bei einigen Nutzern gelegentlich Installationsfehler auftreten.
In fast allen Fällen sind diese Fehler das Ergebnis von Netzwerkproblemen und nicht von tatsächlichen Problemen mit dem Paket electron npm. Fehler wie ELIFECYCLE, EAI_AGAIN, ECONNRESET, and ETIMEDOUT weisen alle auf ein Problem mit dem Netzwerk hin. Die beste Lösung ist es zu Versuchen die Netzwerkverbindung zu wechseln oder etwas zu warten und die Installation erneut zu versuchen.
Man kann auch versuchen, Electron direkt unter electron/electron/releases herunterzuladen, falls die Installation über npm weiterhin fehlschlägt.
Die Chrome Version von Electron wird in der Regel innerhalb von ein oder zwei Wochen Implementiert nachdem eine neue stabile Version für Chrome veröffentlicht wird. Diese Schätzung kann nicht garantiert werden und hängt vom Arbeitsaufwand während der Aktualisierung ab.
\nNur der stabile Kanal von Chrome wird verwendet. Wenn ein wichtiger Fix im Beta- oder Dev-Kanal ist, werden wir ihn zurückportieren.
\nWeitere Informationen finden Sie in der Einführung zur Sicherheit.
\nWenn eine neue Version von Node.js veröffentlicht wird, warten wir in der Regel etwa einen Monat vor dem Upgrade in Elektron. So können wir vermeiden, die häufigen Bugs in neuen Node.js Versionen mit in Electron einzubinden.
\nNeue Funktionalitäten von Node.js werden in der Regel durch V8 Upgrades ermöglicht. Da Electron das vom Chrome Browser mitgelieferte V8 verwendet, stehen die neuen JavaScript Funktionalitäten der neuen Node.js Version in der Regel bereits in Electron zur Verfügung.
\nUm Daten zwischen Web-Seiten (Renderer-Prozesse) zu teilen, ist der einfachste Weg, HTML5-APIs zu verwenden, die bereits in Browsern zur Verfügung stehen. Good candidates are Storage API, localStorage, sessionStorage, and IndexedDB.
Alternatively, you can use the IPC primitives that are provided by Electron. To share data between the main and renderer processes, you can use the ipcMain and ipcRenderer modules. To communicate directly between web pages, you can send a MessagePort from one to the other, possibly via the main process using ipcRenderer.postMessage(). Subsequent communication over message ports is direct and does not detour through the main process.
Dies geschieht, wenn die Variable die das Fenster speichert abgeräumt wird.
\nWenn dieses Problem auftritt, könnten die folgenden Artikel hilfreich sein:
\n\nWenn Sie eine schnelle Lösung bevorzugen, machen Sie die Variablen global, indem Sie Ihren Code
\nconst { app, Tray } = require('electron')\napp.whenReady().then(() => {\n const tray = new Tray('/path/to/icon.png')\n tray.setTitle('Hallo Welt')\n})\nwie folgt anpassen:
\nconst { app, Tray } = require('electron')\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/icon.png')\n tray.setTitle('Hallo Welt')\n})\nWegen der Node.js Integration in Electron gibt es einige zusätzlich eingefügte Symbole im DOM wie module, exports, require. Das verursacht Probleme für einige Bibliotheken, da diese versuchen, Symbole mit den gleichen Namen einzufügen.
Um dies zu beheben können Sie die Node-Integration in Electron deaktivieren:
\n// Im Hauptprozess.\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n webPreferences: {\n nodeIntegration: false\n }\n})\nwin.show()\nWenn Sie sich jedoch die Möglichkeit, Node.js und Electron APIs zu nutzen, offen halten möchten, müssen Sie die Symbole auf der Seite umbenennen, bevor Sie andere Bibliotheken einbinden:
\n<head>\n<script>\nwindow.nodeRequire = require;\ndelete window.require;\ndelete window.exports;\ndelete window.module;\n</script>\n<script type=\"text/javascript\" src=\"jquery.js\"></script>\n</head>\nrequire('electron').xxx is undefined.Während Sie das in Electron integrierte Modul nutzen, könnten Sie auf einen Fehler wie diesen stoßen:
\n> require('electron').webFrame.setZoomFactor(1.0)\nUncaught TypeError: Cannot read property 'setZoomLevel' of undefined\nEs ist sehr wahrscheinlich, dass das Modul im falschen Prozess verwendet wird. Beispielsweise kann electron.app nur im Hauptprozess verwendet werden, während electron.webFrame nur im Renderer-Prozess verfügbar ist.
If sub-pixel anti-aliasing is deactivated, then fonts on LCD screens can look blurry. Beispiel:
\n
Subpixel Antialiasing benötigt einen nicht-transparenten Hintergrund der Ebene, die die Schrift-Glyphen enthält. (Siehe dieses Problem für weitere Informationen).
\nTo achieve this goal, set the background in the constructor for BrowserWindow:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n backgroundColor: '#fff'\n})\nThe effect is visible only on (some?) LCD screens. Even if you don't see a difference, some of your users may. It is best to always set the background this way, unless you have reasons not to do so.
\nBeachten Sie, dass nur die Einstellung des Hintergrunds in der CSS nicht den gewünschten Effekt hat.
", "title": "Electron FAQ", "description": "" }, "/docs/api/structures/file-filter": { "locale": "de-DE", "slug": "file-filter", "href": "/docs/api/structures/file-filter", "crowdinFileId": "256435", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/file-filter.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "name Zeichenfolgeextensions String[]File Objekt\n\nUse the HTML5
\nFileAPI to work natively with files on the filesystem.
The DOM's File interface provides abstraction around native files in order to let users work on native files directly with the HTML5 file API. Electron has added a path attribute to the File interface which exposes the file's real path on filesystem.
Example of getting a real path from a dragged-onto-the-app file:
\n<div id=\"holder\">\n Drag your file here\n</div>\n\n<script>\n document.addEventListener('drop', (e) => {\n e.preventDefault();\n e.stopPropagation();\n\n for (const f of e.dataTransfer.files) {\n console.log('File(s) you dragged here: ', f.path)\n }\n });\n document.addEventListener('dragover', (e) => {\n e.preventDefault();\n e.stopPropagation();\n });\n</script>\npath String - The path to the file to send.headers Record<string, string> (optional) - Additional headers to be sent.\n\nÖffne ein Fenster ohne Werkzeug/Symbolleiste, Ränder oder anderen grafischen Schnickschnack.
\n
Ein rahmenloses Fenster ist ein Fenster ohne die üblichen Bestandteile, wie Symbolleisten, die nicht Teil der Webseite sind. Die folgenden Optionen stehen in der Klasse BrowserWindow zur Verfügung.
Um ein rahmenloses Fenster zu erstellen musst du frame in den BrowserWindow Optionen auf false setzen:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600, frame: false })\nwin.show()\nThere's an alternative way to specify a chromeless window on macOS and Windows. Instead of setting frame to false which disables both the titlebar and window controls, you may want to have the title bar hidden and your content extend to the full window size, yet still preserve the window controls (\"traffic lights\" on macOS) for standard window actions. Das kannst du erreichen indem du folgende titleBarStyle-Optionen verwendest:
hiddenResults in a hidden title bar and a full size content window. On macOS, the title bar still has the standard window controls (“traffic lights”) in the top left.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hidden' })\nwin.show()\nhiddenInsetResults in a hidden title bar with an alternative look where the traffic light buttons are slightly more inset from the window edge.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })\nwin.show()\ncustomButtonsOnHoverUses custom drawn close, and miniaturize buttons that display when hovering in the top left of the window. The fullscreen button is not available due to restrictions of frameless windows as they interface with Apple's macOS window masks. These custom buttons prevent issues with mouse events that occur with the standard window toolbar buttons. This option is only applicable for frameless windows.
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover', frame: false })\nwin.show()\nWhen using a frameless window in conjuction with win.setWindowButtonVisibility(true) on macOS, using one of the titleBarStyles as described above so that the traffic lights are visible, or using titleBarStyle: hidden on Windows, you can access the Window Controls Overlay JavaScript APIs and CSS Environment Variables by setting the titleBarOverlay option to true. Specifying true will result in an overlay with default system colors.
On Windows, you can also specify the color of the overlay and its symbols by setting titleBarOverlay to an object with the options color and symbolColor. If an option is not specified, the color will default to its system color for the window control buttons:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: true\n})\nwin.show()\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({\n titleBarStyle: 'hidden',\n titleBarOverlay: {\n color: '#2f3241',\n symbolColor: '#74b1be'\n }\n})\nwin.show()\nBy setting the transparent option to true, you can also make the frameless window transparent:
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ transparent: true, frame: false })\nwin.show()\nresizable to true may make a transparent window stop working on some platforms.blur filter only applies to the web page, so there is no way to apply blur effect to the content below the window (i.e. other applications open on the user's system).--enable-transparent-visuals --disable-gpu in the command line to disable GPU and allow ARGB to make transparent window, this is caused by an upstream bug that alpha channel doesn't work on some NVidia drivers on Linux.To create a click-through window, i.e. making the window ignore all mouse events, you can call the win.setIgnoreMouseEvents(ignore) API:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.setIgnoreMouseEvents(true)\nIgnoring mouse messages makes the web page oblivious to mouse movement, meaning that mouse movement events will not be emitted. On Windows operating systems an optional parameter can be used to forward mouse move messages to the web page, allowing events such as mouseleave to be emitted:
const { ipcRenderer } = require('electron')\nconst el = document.getElementById('clickThroughElement')\nel.addEventListener('mouseenter', () => {\n ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })\n})\nel.addEventListener('mouseleave', () => {\n ipcRenderer.send('set-ignore-mouse-events', false)\n})\n\n// Main process\nconst { ipcMain } = require('electron')\nipcMain.on('set-ignore-mouse-events', (event, ...args) => {\n BrowserWindow.fromWebContents(event.sender).setIgnoreMouseEvents(...args)\n})\nThis makes the web page click-through when over el, and returns to normal outside it.
By default, the frameless window is non-draggable. Apps need to specify -webkit-app-region: drag in CSS to tell Electron which regions are draggable (like the OS's standard titlebar), and apps can also use -webkit-app-region: no-drag to exclude the non-draggable area from the draggable region. Note that only rectangular shapes are currently supported.
Note: -webkit-app-region: drag is known to have problems while the developer tools are open. See this GitHub issue for more information including a workaround.
To make the whole window draggable, you can add -webkit-app-region: drag as body's style:
<body style=\"-webkit-app-region: drag\">\n</body>\nAnd note that if you have made the whole window draggable, you must also mark buttons as non-draggable, otherwise it would be impossible for users to click on them:
\nbutton {\n -webkit-app-region: no-drag;\n}\nIf you're only setting a custom titlebar as draggable, you also need to make all buttons in titlebar non-draggable.
\nIn a frameless window the dragging behavior may conflict with selecting text. For example, when you drag the titlebar you may accidentally select the text on the titlebar. To prevent this, you need to disable text selection within a draggable area like this:
\n.titlebar {\n -webkit-user-select: none;\n -webkit-app-region: drag;\n}\nOn some platforms, the draggable area will be treated as a non-client frame, so when you right click on it a system menu will pop up. To make the context menu behave correctly on all platforms you should never use a custom context menu on draggable areas.
", "title": "Rahmenlose Fenster", "description": "Öffne ein Fenster ohne Werkzeug/Symbolleiste, Ränder oder anderen grafischen Schnickschnack." }, "/docs/tutorial/fuses": { "locale": "de-DE", "slug": "fuses", "href": "/docs/tutorial/fuses", "crowdinFileId": "256201", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/fuses.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nPackage time feature toggles
\n
For a subset of Electron functionality it makes sense to disable certain features for an entire application. For example, 99% of apps don't make use of ELECTRON_RUN_AS_NODE, these applications want to be able to ship a binary that is incapable of using that feature. We also don't want Electron consumers building Electron from source as that is both a massive technical challenge and has a high cost of both time and money.
Fuses are the solution to this problem, at a high level they are \"magic bits\" in the Electron binary that can be flipped when packaging your Electron app to enable / disable certain features / restrictions. Because they are flipped at package time before you code sign your app the OS becomes responsible for ensuring those bits aren't flipped back via OS level code signing validation (Gatekeeper / App Locker).
\nWe've made a handy module @electron/fuses to make flipping these fuses easy. Check out the README of that module for more details on usage and potential error cases.
require('@electron/fuses').flipFuses(\n // Path to electron\n require('electron'),\n // Fuses to flip\n {\n runAsNode: false\n }\n)\nManually flipping fuses requires editing the Electron binary and modifying the fuse wire to be the sequence of bytes that represent the state of the fuses you want.
\nSomewhere in the Electron binary there will be a sequence of bytes that look like this:
\n| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |\nsentinel_bytes is always this exact string dL7pKGdnNz796PbbjQWNKmHXBZaB9tsXfuse_version is a single byte whose unsigned integer value represents the version of the fuse schemafuse_wire_length is a single byte whose unsigned integer value represents the number of fuses in the following fuse wirefuse_wire is a sequence of N bytes, each byte represents a single fuse and its state.To flip a fuse you find its position in the fuse wire and change it to \"0\" or \"1\" depending on the state you'd like.
\nYou can view the current schema here.
", "title": "Electron Fuses", "description": "Package time feature toggles" }, "/docs/api/global-shortcut": { "locale": "de-DE", "slug": "global-shortcut", "href": "/docs/api/global-shortcut", "crowdinFileId": "256323", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/global-shortcut.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nDetect keyboard events when the application does not have keyboard focus.
\n
Prozess: Haupt
\nThe globalShortcut module can register/unregister a global keyboard shortcut with the operating system so that you can customize the operations for various shortcuts.
Note: The shortcut is global; it will work even if the app does not have the keyboard focus. This module cannot be used before the ready event of the app module is emitted.
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n // Register a 'CommandOrControl+X' shortcut listener.\n const ret = globalShortcut.register('CommandOrControl+X', () => {\n console.log('CommandOrControl+X is pressed')\n })\n\n if (!ret) {\n console.log('registration failed')\n }\n\n // Check whether a shortcut is registered.\n console.log(globalShortcut.isRegistered('CommandOrControl+X'))\n})\n\napp.on('will-quit', () => {\n // Unregister a shortcut.\n globalShortcut.unregister('CommandOrControl+X')\n\n // Unregister all shortcuts.\n globalShortcut.unregisterAll()\n})\nDas globalShortcut Modul hat folgende Methoden:
globalShortcut.register(accelerator, callback)accelerator Acceleratorcallback FunctionReturns Boolean - Whether or not the shortcut was registered successfully.
Registers a global shortcut of accelerator. The callback is called when the registered shortcut is pressed by the user.
When the accelerator is already taken by other applications, this call will silently fail. This behavior is intended by operating systems, since they don't want applications to fight for global shortcuts.
\nThe following accelerators will not be registered successfully on macOS 10.14 Mojave unless the app has been authorized as a trusted accessibility client:
\nglobalShortcut.registerAll(accelerators, callback)accelerators String[] - an array of Accelerators.callback FunctionRegisters a global shortcut of all accelerator items in accelerators. The callback is called when any of the registered shortcuts are pressed by the user.
When a given accelerator is already taken by other applications, this call will silently fail. This behavior is intended by operating systems, since they don't want applications to fight for global shortcuts.
\nThe following accelerators will not be registered successfully on macOS 10.14 Mojave unless the app has been authorized as a trusted accessibility client:
\nglobalShortcut.isRegistered(accelerator)accelerator AcceleratorReturns Boolean - Whether this application has registered accelerator.
When the accelerator is already taken by other applications, this call will still return false. This behavior is intended by operating systems, since they don't want applications to fight for global shortcuts.
globalShortcut.unregister(accelerator)accelerator AcceleratorUnregisters the global shortcut of accelerator.
globalShortcut.unregisterAll()Unregisters all of the global shortcuts.
", "title": "globalShortcut", "description": "Detect keyboard events when the application does not have keyboard focus." }, "/docs/glossary": { "locale": "de-DE", "slug": "glossary", "href": "/docs/glossary", "crowdinFileId": "256123", "githubUrl": "https://github.com/electron/electron/tree/main/docs/glossary.md", "category": "", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Diese Seite enthält Begriffe, die während der Entwicklung von Electron häufig verwendet werden.
\nASAR steht für Atom-Shell-Archiv-Format. Ein asar-Archiv ist ein simples, tar-ähnliches Format, das die Dateien in einer einzelnen Datei zusammenführt. Electron kann willkürliche Dateien aus dem Archiv lesen ohne diese zu entpacken.
The ASAR format was created primarily to improve performance on Windows when reading large quantities of small files (e.g. when loading your app's JavaScript dependency tree from node_modules).
Code signing is a process where an app developer digitally signs their code to ensure that it hasn't been tampered with after packaging. Both Windows and macOS implement their own version of code signing. As a desktop app developer, it's important that you sign your code if you plan on distributing it to the general public.
\nFor more information, read the Code Signing tutorial.
\nContext isolation is a security measure in Electron that ensures that your preload script cannot leak privileged Electron or Node.js APIs to the web contents in your renderer process. With context isolation enabled, the only way to expose APIs from your preload script is through the contextBridge API.
For more information, read the Context Isolation tutorial.
\nSee also: preload script, renderer process
\nThe C Runtime Library (CRT) is the part of the C++ Standard Library that incorporates the ISO C99 standard library. Die Visual C++ Bibliotheken, welche die CRT implementieren, unterstützen native Codeentwicklung sowie gemischt nativen und verwalteten Code als auch reiner verwalteter Code für .NET-Entwicklung.
\n\"Apple Disk Image\" ist ein Paket-Format von macOS. DMG-Dateien werden oft zur Distribution von Installern verwendet.
\nInput Method Editor. Ein Programm, dass dem Benutzer die Eingabe von Buchstaben und Zeichen, welche nicht auf der Tastatur vertreten sind, erlaubt. Zum Beispiel können Benutzer einer lateinischen Tastatur chinesische, japanische, koreanische und indische Zeichen einzugeben.
\nInterface description language. Write function signatures and data types in a format that can be used to generate interfaces in Java, C++, JavaScript, etc.
\nIPC stands for inter-process communication. Electron uses IPC to send serialized JSON messages between the main and renderer processes.
\nsiehe auch: main process, renderer process
\nThe main process, commonly a file named main.js, is the entry point to every Electron app. It controls the life of the app, from open to close. Er steurert auch Native Elemente wie Menu, Menu Bar, Dock, Tray, usw. The main process is responsible for creating each new renderer process in the app. The full Node API is built in.
Die Datei für den Hauptprozess jeder App ist in der main Eigenschaft in package.json angegeben. This is how electron . knows what file to execute at startup.
In Chromium wird dieser Prozess als \"Browser-Prozess\" bezeichnet. In Electron wird er umbenannt, um Verwechslung mit Renderer-Prozessen zu vermeiden.
\nSiehe auch: process, renderer process
\nAbkürzung für Apple's Mac App Store. Für Infromationen zum Einreichen deiner App zum MAS siehe Anleitung: Mac App Store Veröffentlichung.
\nAn IPC system for communicating intra- or inter-process, and that's important because Chrome is keen on being able to split its work into separate processes or not, depending on memory pressures etc.
\nSiehe https://chromium.googlesource.com/chromium/src/+/master/mojo/README.md
\nSee also: IPC
\nOn Windows, MSI packages are used by the Windows Installer (also known as Microsoft Installer) service to install and configure applications.
\nMore information can be found in Microsoft's documentation.
\nNative Module, in Node.js auch addons genannt, sind Module, welche in C oder C++ geschrieben werden und genau wie normale mithilfe der require() Funktion geladen werden können. Sie werden in erster Linie dazu eingesetzt, um eine Schnittstelle zwischen JavaScript in Node.js und C/C++-Bibliotheken zur Verfügung zu stellen.
\nNative Node-Module werden von Electron unterstützt, aber da Electron sehr es wahrscheinlich eine andere V8-Version als die von der auf ihrem System verwendete Node.js Version verwendet, musst du den Ort der Electron-Header beim Bauen von nativen Modulen manuell angeben.
\nFor more information, read the [Native Node Modules] tutorial.
\nNotarization is a macOS-specific process where a developer can send a code-signed app to Apple servers to get verified for malicious components through an automated service.
\nSee also: code signing
\nOSR (offscreen rendering) can be used for loading heavy page in background and then displaying it after (it will be much faster). It allows you to render page without showing it on screen.
\nFor more information, read the Offscreen Rendering[osr] tutorial.
\nPreload scripts contain code that executes in a renderer process before its web contents begin loading. These scripts run within the renderer context, but are granted more privileges by having access to Node.js APIs.
\nSee also: renderer process, context isolation
\nEin Prozess ist eine Instanz eines Computerprogramms, welches ausgeführt wird. Electron Anwendungen, welche einen main- und einen oder mehrere renderer-Prozesse verwenden, bestehen eigentlich aus mehreren parallel laufenden Programmen.
\nIn Node.js und Electron hat jeder laufende Prozess ein process-Objekt. Dieses globale Objekt stellt Informationen und Steuerungsmöglichkeiten über den aktuellen Prozess bereit. Als globales Objekt ist es immer verfügbar für Anwendungen, welche nicht require() benutzen.
Siehe auch: main process, renderer process
\nThe renderer process is a browser window in your app. Unlike the main process, there can be multiple of these and each is run in a separate process. They can also be hidden.
\nSiehe auch: process, main process
\nThe sandbox is a security feature inherited from Chromium that restricts your renderer processes to a limited set of permissions.
\nFor more information, read the Process Sandboxing tutorial.
\nSee also: process
\nSquirrel ist ein Open-Source Framework, welches Electron Apps ermöglicht sich automatisch zu aktualisieren, wenn neue Versionen veröffentlicht werden. Siehe dir die autoUpdater API an für mehr Informationen wie du mit Squirrel startest.
\nDer Begriff hat seinen Ursprung in der Unix Community, wo \"userland\" oder \"userspace\" für Programme steht, die außerhalb des Kernels des Betriebssystems agieren. Seit einiger Zeit wird der Begriff auch in der Node und npm Community verwendet, um zwischen Features, die im \"Node core\" verfügbar sind, und Paketen, die in der npm registry veröffentlicht wurden, zu unterscheiden.
\nWie Node fokussiert sich auch Electron darauf, eine relativ einfache API mit allen nötigen primitiven Werkzeugen, die es braucht, um Multi-Plattform Desktop-Anwendungen zu entwickeln, bereitzustellen. Diese Design-Philosophie ermöglicht es Electron, ein flexibles Werkzeug zu sein, ohne zu stark in der Art, wie es benutzt werden kann, einzuschränken. Userland erlaubt Nutzern das Erstellen und Teilen von Tools, die weitere, komplexere Funktionalität bereitstellt, zusätzlich zu denen, die im \"Core\" existieren.
\nV8 is Google's open source JavaScript engine. It is written in C++ and is used in Google Chrome. V8 can run standalone, or can be embedded into any C++ application.
\nElectron baut V8 als Teil von Chromium und weist dann Node beim Bauen darauf hin.
\nV8's version numbers always correspond to those of Google Chrome. Chrome 59 includes V8 5.9, Chrome 58 includes V8 5.8, etc.
\n\nwebview tags are used to embed 'guest' content (such as external web pages) in your Electron app. They are similar to iframes, but differ in that each webview runs in a separate process. 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.
\n\nGoma is a distributed compiler service for open-source projects such as Chromium and Android.
\n
Electron hat ein eigenes Goma-Backend, das wir allen Electron-Betreuern zur Verfügung stellen. See the Access section below for details on authentication. There is also a cache-only Goma endpoint that will be used by default if you do not have credentials. Requests to the cache-only Goma will not hit our cluster, but will read from our cache and should result in significantly faster build times.
Currently the only supported way to use Goma is to use our Build Tools. Goma configuration is automatically included when you set up build-tools.
If you are a maintainer and have access to our cluster, please ensure that you run e init with --goma=cluster in order to configure build-tools to use the Goma cluster. If you have an existing config, you can just set \"goma\": \"cluster\" in your config file.
When you are using Goma you can run ninja with a substantially higher j value than would normally be supported by your machine.
Please do not set a value higher than 200 on Windows or Linux and 50 on macOS. We monitor Goma system usage, and users found to be abusing it with unreasonable concurrency will be de-activated.
\nninja -C out/Testing electron -j 200\nIf you're using build-tools, appropriate -j values will automatically be used for you.
If you access http://localhost:8088 on your local machine you can monitor compile jobs as they flow through the goma system.
\nFor security and cost reasons, access to Electron's Goma cluster is currently restricted to Electron Maintainers. If you want access please head to #access-requests in Slack and ping @goma-squad to ask for access. Please be aware that being a maintainer does not automatically grant access and access is determined on a case by case basis.
We have automated monitoring of our Goma cluster and cache at https://status.notgoma.com
\nWe do not provide support for usage of Goma and any issues raised asking for help / having issues will probably be closed without much reason, we do not have the capacity to handle that kind of support.
", "title": "Goma", "description": "Goma is a distributed compiler service for open-source projects such as Chromium and Android." }, "/docs/api/structures/gpu-feature-status": { "locale": "de-DE", "slug": "gpu-feature-status", "href": "/docs/api/structures/gpu-feature-status", "crowdinFileId": "256439", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/gpu-feature-status.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "2d_canvas String - Canvas.flash_3d String - Flash.flash_stage3d String - Flash Stage3D.flash_stage3d_baseline String - Flash Stage3D Baseline profile.gpu_compositing String - Compositing.multiple_raster_threads String - Multiple Raster Threads.native_gpu_memory_buffers String - Native GpuMemoryBuffers.rasterization String - Rasterization.video_decode String - Video Decode.video_encode String - Video Encode.vpx_decode String - VPx Video Decode.webgl String - WebGL.webgl2 String - WebGL2.Mögliche werte:
\ndisabled_software - Software only. Hardware acceleration disabled (yellow)disabled_off - Disabled (red)disabled_off_ok - Disabled (yellow)unavailable_software - Software only, hardware acceleration unavailable (yellow)unavailable_off - Unavailable (red)unavailable_off_ok - Unavailable (yellow)enabled_readback - Hardware accelerated but at reduced performance (yellow)enabled_force - Hardware accelerated on all pages (green)enabled - Hardware accelerated (green)enabled_on - Enabled (green)enabled_force_on - Force enabled (green)deviceId String - Unique identifier for the device.name String - Name of the device.vendorId Integer - The USB vendor ID.productId Integer - The USB product ID.serialNumber String (optional) - The USB device serial number.guid String (optional) - Unique identifier for the HID interface. A device may have multiple HID interfaces.\n\nIn-app purchases on Mac App Store.
\n
Prozess: Haupt
\nDas inAppPurchase Modul sendet folgende Ereignisse aus:
Emitted when one or more transactions have been updated.
\nKehrt zurück:
\nevent Eventtransactions Transaction[] - Array of Transaction objects.Das Modul inAppPurchase verfügt über die folgenden Methoden:
inAppPurchase.purchaseProduct(productID[, quantity])productID String - The identifiers of the product to purchase. (The identifier of com.example.app.product1 is product1).quantity Integer (optional) - The number of items the user wants to purchase.Returns Promise<Boolean> - Returns true if the product is valid and added to the payment queue.
You should listen for the transactions-updated event as soon as possible and certainly before you call purchaseProduct.
inAppPurchase.getProducts(productIDs)productIDs String[] - The identifiers of the products to get.Returns Promise<Product[]> - Resolves with an array of Product objects.
Retrieves the product descriptions.
\ninAppPurchase.canMakePayments()Returns Boolean - whether a user can make a payment.
inAppPurchase.restoreCompletedTransactions()Restores finished transactions. This method can be called either to install purchases on additional devices, or to restore purchases for an application that the user deleted and reinstalled.
\nThe payment queue delivers a new transaction for each previously completed transaction that can be restored. Each transaction includes a copy of the original transaction.
\ninAppPurchase.getReceiptURL()Returns String - the path to the receipt.
inAppPurchase.finishAllTransactions()Completes all pending transactions.
\ninAppPurchase.finishTransactionByDate(date)date String - The ISO formatted date of the transaction to finish.Completes the pending transactions corresponding to the date.
", "title": "inAppPurchase", "description": "In-app purchases on Mac App Store." }, "/docs/tutorial/in-app-purchases": { "locale": "de-DE", "slug": "in-app-purchases", "href": "/docs/tutorial/in-app-purchases", "crowdinFileId": "256203", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/in-app-purchases.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "If you haven't already, you’ll need to sign the Paid Applications Agreement and set up your banking and tax information in iTunes Connect.
\niTunes Connect Developer Help: Agreements, tax, and banking overview
\nThen, you'll need to configure your in-app purchases in iTunes Connect, and include details such as name, pricing, and description that highlights the features and functionality of your in-app purchase.
\niTunes Connect Developer Help: Create an in-app purchase
\nTo test In-App Purchase in development with Electron you'll have to change the CFBundleIdentifier in node_modules/electron/dist/Electron.app/Contents/Info.plist. You have to replace com.github.electron by the bundle identifier of the application you created with iTunes Connect.
<key>CFBundleIdentifier</key>\n<string>com.example.app</string>\nHere is an example that shows how to use In-App Purchases in Electron. You'll have to replace the product ids by the identifiers of the products created with iTunes Connect (the identifier of com.example.app.product1 is product1). Note that you have to listen to the transactions-updated event as soon as possible in your app.
// Main process\nconst { inAppPurchase } = require('electron')\nconst PRODUCT_IDS = ['id1', 'id2']\n\n// Listen for transactions as soon as possible.\ninAppPurchase.on('transactions-updated', (event, transactions) => {\n if (!Array.isArray(transactions)) {\n return\n }\n\n // Check each transaction.\n transactions.forEach(function (transaction) {\n const payment = transaction.payment\n\n switch (transaction.transactionState) {\n case 'purchasing':\n console.log(`Purchasing ${payment.productIdentifier}...`)\n break\n\n case 'purchased': {\n console.log(`${payment.productIdentifier} purchased.`)\n\n // Get the receipt url.\n const receiptURL = inAppPurchase.getReceiptURL()\n\n console.log(`Receipt URL: ${receiptURL}`)\n\n // Submit the receipt file to the server and check if it is valid.\n // @see https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html\n // ...\n // If the receipt is valid, the product is purchased\n // ...\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n }\n\n case 'failed':\n\n console.log(`Failed to purchase ${payment.productIdentifier}.`)\n\n // Finish the transaction.\n inAppPurchase.finishTransactionByDate(transaction.transactionDate)\n\n break\n case 'restored':\n\n console.log(`The purchase of ${payment.productIdentifier} has been restored.`)\n\n break\n case 'deferred':\n\n console.log(`The purchase of ${payment.productIdentifier} has been deferred.`)\n\n break\n default:\n break\n }\n })\n})\n\n// Check if the user is allowed to make in-app purchase.\nif (!inAppPurchase.canMakePayments()) {\n console.log('The user is not allowed to make in-app purchase.')\n}\n\n// Retrieve and display the product descriptions.\ninAppPurchase.getProducts(PRODUCT_IDS).then(products => {\n // Check the parameters.\n if (!Array.isArray(products) || products.length <= 0) {\n console.log('Unable to retrieve the product informations.')\n return\n }\n\n // Display the name and price of each product.\n products.forEach(product => {\n console.log(`The price of ${product.localizedTitle} is ${product.formattedPrice}.`)\n })\n\n // Ask the user which product he/she wants to purchase.\n const selectedProduct = products[0]\n const selectedQuantity = 1\n\n // Purchase the selected product.\n inAppPurchase.purchaseProduct(selectedProduct.productIdentifier, selectedQuantity).then(isProductValid => {\n if (!isProductValid) {\n console.log('The product is not valid.')\n return\n }\n\n console.log('The payment has been added to the payment queue.')\n })\n})\n\n\nBehandelt Antworten zu HTTP/HTTPS Anfragen.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
IncomingMessage implementiert das Readable Stream interface und ist somit ein EventEmitter.
Kehrt zurück:
\nchunk Buffer - Ein Stück der Antwortdaten.Das data Event ist die gewöhnliche Methode um Antwortdaten in Anwendungscode zu transferieren.
Gibt an dass der Body der Antwort endet. Must be placed before 'data' event.
\nAusgegeben wenn eine Anfrage während einer laufenden HTTP Transaktion abgebrochen wurde.
\nKehrt zurück:
\nerror Error - Typically holds an error string identifying failure root cause.
Emitted when an error was encountered while streaming response data events. For instance, if the server closes the underlying while the response is still streaming, an error event will be emitted on the response object and a close event will subsequently follow on the request object.
An IncomingMessage instance has the following readable properties:
response.statusCodeAn Integer indicating the HTTP response status code.
response.statusMessageA String representing the HTTP status message.
response.headersA Record<string, string | string[]> representing the HTTP response headers. The headers object is formatted as follows:
age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, server, or user-agent are discarded.set-cookie is always an array. Duplicates are added to the array.cookie headers, the values are joined together with '; '.response.httpVersionA String indicating the HTTP protocol version number. Typical values are '1.0' or '1.1'. Additionally httpVersionMajor and httpVersionMinor are two Integer-valued readable properties that return respectively the HTTP major and minor version numbers.
response.httpVersionMajorAn Integer indicating the HTTP protocol major version number.
response.httpVersionMinorAn Integer indicating the HTTP protocol minor version number.
modifiers String - An array of modifiers of the event, can be shift, control, ctrl, alt, meta, command, cmd, isKeypad, isAutoRepeat, leftButtonDown, middleButtonDown, rightButtonDown, capsLock, numLock, left, right.To install prebuilt Electron binaries, use npm. The preferred method is to install Electron as a development dependency in your app:
npm install electron --save-dev\nSee the Electron versioning doc for info on how to manage Electron versions in your apps.
\nIf you're in a pinch and would prefer to not use npm install in your local project, you can also run Electron ad-hoc using the npx command runner bundled with npm:
npx electron .\nThe above command will run the current working directory with Electron. Note that any dependencies in your app will not be installed.
\nFalls Sie die herunterzuladende Architektur ändern möchten (z.B. ia32 auf einem x64-Rechner), dann können Sie den --arch-Flag verwenden oder die Umgebungsvariable npm_config_arch setzen:
npm install --arch=ia32 electron\nZusätzlich zur Änderung der Architektur können Sie auch die Plattform (z.B. win32, linux, usw.) mittels des --platform-Flags spezifizieren:
npm install --platform=win32 electron\nIf you need to use an HTTP proxy, you need to set the ELECTRON_GET_USE_PROXY variable to any value, plus additional environment variables depending on your host system's Node version:
During installation, the electron module will call out to @electron/get to download prebuilt binaries of Electron for your platform. It will do so by contacting GitHub's release download page (https://github.com/electron/electron/releases/tag/v$VERSION, where $VERSION is the exact version of Electron).
If you are unable to access GitHub or you need to provide a custom build, you can do so by either providing a mirror or an existing cache directory.
\nYou can use environment variables to override the base URL, the path at which to look for Electron binaries, and the binary filename. The URL used by @electron/get is composed as follows:
url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME\nFor instance, to use the China CDN mirror:
\nELECTRON_MIRROR=\"https://cdn.npm.taobao.org/dist/electron/\"\nBy default, ELECTRON_CUSTOM_DIR is set to v$VERSION. To change the format, use the {{ version }} placeholder. For example, version-{{ version }} resolves to version-5.0.0, {{ version }} resolves to 5.0.0, and v{{ version }} is equivalent to the default. As a more concrete example, to use the China non-CDN mirror:
ELECTRON_MIRROR=\"https://npm.taobao.org/mirrors/electron/\"\nELECTRON_CUSTOM_DIR=\"{{ version }}\"\nThe above configuration will download from URLs such as https://npm.taobao.org/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip.
If your mirror serves artifacts with different checksums to the official Electron release you may have to set ELECTRON_USE_REMOTE_CHECKSUMS=1 to force Electron to use the remote SHASUMS256.txt file to verify the checksum instead of the embedded checksums.
Alternatively, you can override the local cache. @electron/get will cache downloaded binaries in a local directory to not stress your network. You can use that cache folder to provide custom builds of Electron or to avoid making contact with the network at all.
$XDG_CACHE_HOME or ~/.cache/electron/~/Library/Caches/electron/$LOCALAPPDATA/electron/Cache or ~/AppData/Local/electron/Cache/On environments that have been using older versions of Electron, you might find the cache also in ~/.electron.
You can also override the local cache location by providing a electron_config_cache environment variable.
The cache contains the version's official zip file as well as a checksum, stored as a text file. A typical cache might look like this:
\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9electron-v1.7.9-darwin-x64.zip\n│ └── electron-v1.7.9-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.7.9SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1electron-v1.8.1-darwin-x64.zip\n│ └── electron-v1.8.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1electron-v1.8.2-beta.1-darwin-x64.zip\n│ └── electron-v1.8.2-beta.1-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.1SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2electron-v1.8.2-beta.2-darwin-x64.zip\n│ └── electron-v1.8.2-beta.2-darwin-x64.zip\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.2SHASUMS256.txt\n│ └── SHASUMS256.txt\n├── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3electron-v1.8.2-beta.3-darwin-x64.zip\n│ └── electron-v1.8.2-beta.3-darwin-x64.zip\n└── httpsgithub.comelectronelectronreleasesdownloadv1.8.2-beta.3SHASUMS256.txt\n └── SHASUMS256.txt\nUnder the hood, Electron's JavaScript API binds to a binary that contains its implementations. Because this binary is crucial to the function of any Electron app, it is downloaded by default in the postinstall step every time you install electron from the npm registry.
However, if you want to install your project's dependencies but don't need to use Electron functionality, you can set the ELECTRON_SKIP_BINARY_DOWNLOAD environment variable to prevent the binary from being downloaded. For instance, this feature can be useful in continuous integration environments when running unit tests that mock out the electron module.
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install\nBeim Ausführen von npm install electron können bei einigen Nutzern gelegentlich Installationsfehler auftreten.
In fast allen Fällen sind diese Fehler das Ergebnis von Netzwerkproblemen und nicht von tatsächlichen Problemen mit dem Paket electron npm. Fehler wie ELIFECYCLE, EAI_AGAIN, ECONNRESET, and ETIMEDOUT weisen alle auf ein Problem mit dem Netzwerk hin. Die beste Lösung ist es zu Versuchen die Netzwerkverbindung zu wechseln oder etwas zu warten und die Installation erneut zu versuchen.
You can also attempt to download Electron directly from electron/electron/releases if installing via npm is failing.
If installation fails with an EACCESS error you may need to fix your npm permissions.
If the above error persists, the unsafe-perm flag may need to be set to true:
\nsudo npm install electron --unsafe-perm=true\nOn slower networks, it may be advisable to use the --verbose flag in order to show download progress:
npm install --verbose electron\nIf you need to force a re-download of the asset and the SHASUM file set the force_no_cache environment variable to true.
Willkommen bei der Electron-Dokumentation! Wenn Sie zum ersten Mal eine Electron-App entwickeln, lesen Sie diesen Abschnitt \"Erste Schritte\" durch, um sich mit den Grundlagen vertraut zu machen. Andernfalls können Sie gerne unsere Anleitungen und die Api-Dokumentation erkunden! If this is your first time developing an Electron app, read through this Getting Started section to get familiar with the basics. Otherwise, feel free to explore our guides and API documentation!
\nElectron is a framework for building desktop applications using JavaScript, HTML, and CSS. By embedding Chromium and Node.js into its binary, Electron allows you to maintain one JavaScript codebase and create cross-platform apps that work on Windows, macOS, and Linux — no native development experience required.
\nThese docs operate under the assumption that the reader is familiar with both Node.js and general web development. If you need to get more comfortable with either of these areas, we recommend the following resources:
\n\nMoreover, you'll have a better time understanding how Electron works if you get acquainted with Chromium's process model. You can get a brief overview of Chrome architecture with the Chrome comic, which was released alongside Chrome's launch back in 2008. Although it's been over a decade since then, the core principles introduced in the comic remain helpful to understand Electron.
\nElectron Fiddle is a sandbox app written with Electron and supported by Electron's maintainers. We highly recommend installing it as a learning tool to experiment with Electron's APIs or to prototype features during development.
\nFiddle also integrates nicely with our documentation. When browsing through examples in our tutorials, you'll frequently see an \"Open in Electron Fiddle\" button underneath a code block. If you have Fiddle installed, this button will open a fiddle.electronjs.org link that will automatically load the example into Fiddle, no copy-pasting required.
Are you getting stuck anywhere? Here are a few links to places to look:
\nelectron package, please check the GitHub issue tracker to see if any existing issues match your problem. If not, feel free to fill out our bug report template and submit a new issue.readOperationCount Number - The number of I/O read operations.writeOperationCount Number - The number of I/O write operations.otherOperationCount Number - Then number of I/O other operations.readTransferCount Number - The number of I/O read transfers.writeTransferCount Number - The number of I/O write transfers.otherTransferCount Number - Then number of I/O other transfers.\n\nCommunicate asynchronously from the main process to renderer processes.
\n
Prozess: Haupt
\nThe ipcMain module is an Event Emitter. When used in the main process, it handles asynchronous and synchronous messages sent from a renderer process (web page). Messages sent from a renderer will be emitted to this module.
It is also possible to send messages from the main process to the renderer process, see webContents.send for more information.
\nchannel.event.returnValue.event.reply(...). This helper method will automatically handle messages coming from frames that aren't the main frame (e.g. iframes) whereas event.sender.send(...) will always send to the main frame.An example of sending and handling messages between the render and main processes:
\n// In main process.\nconst { ipcMain } = require('electron')\nipcMain.on('asynchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.reply('asynchronous-reply', 'pong')\n})\n\nipcMain.on('synchronous-message', (event, arg) => {\n console.log(arg) // prints \"ping\"\n event.returnValue = 'pong'\n})\n// In renderer process (web page).\n// NB. Electron APIs are only accessible from preload, unless contextIsolation is disabled.\n// See https://www.electronjs.org/docs/tutorial/process-model#preload-scripts for more details.\nconst { ipcRenderer } = require('electron')\nconsole.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // prints \"pong\"\n\nipcRenderer.on('asynchronous-reply', (event, arg) => {\n console.log(arg) // prints \"pong\"\n})\nipcRenderer.send('asynchronous-message', 'ping')\nThe ipcMain module has the following method to listen for events:
ipcMain.on(channel, listener)channel Stringlistener Funktionevent IpcMainEvent...args any[]Listens to channel, when a new message arrives listener would be called with listener(event, args...).
ipcMain.once(channel, listener)channel Stringlistener Funktionevent IpcMainEvent...args any[]Adds a one time listener function for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed.
ipcMain.removeListener(channel, listener)channel Stringlistener Funktion...args any[]Removes the specified listener from the listener array for the specified channel.
ipcMain.removeAllListeners([channel])channel String (optional)Removes listeners of the specified channel.
ipcMain.handle(channel, listener)channel Stringlistener Function<Promise\\event IpcMainInvokeEvent...args any[]Adds a handler for an invokeable IPC. This handler will be called whenever a renderer calls ipcRenderer.invoke(channel, ...args).
If listener returns a Promise, the eventual result of the promise will be returned as a reply to the remote caller. Otherwise, the return value of the listener will be used as the value of the reply.
// Main process\nipcMain.handle('my-invokable-ipc', async (event, ...args) => {\n const result = await somePromise(...args)\n return result\n})\n\n// Renderer process\nasync () => {\n const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)\n // ...\n}\nThe event that is passed as the first argument to the handler is the same as that passed to a regular event listener. It includes information about which WebContents is the source of the invoke request.
Errors thrown through handle in the main process are not transparent as they are serialized and only the message property from the original error is provided to the renderer process. Please refer to #24427 for details.
ipcMain.handleOnce(channel, listener)channel Stringlistener Function<Promise\\event IpcMainInvokeEvent...args any[]Handles a single invokeable IPC message, then removes the listener. See ipcMain.handle(channel, listener).
ipcMain.removeHandler(channel)channel StringRemoves any handler for channel, if present.
The documentation for the event object passed to the callback can be found in the ipc-main-event structure docs.
The documentation for the event object passed to handle callbacks can be found in the ipc-main-invoke-event structure docs.
EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagereturnValue any - Set this to the value to be returned in a synchronous messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this messageports MessagePortMain[] - A list of MessagePorts that were transferred with this messagereply Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to \"reply\" to the sent message in order to guarantee the reply will go to the correct process and frame.channel String...args any[]EventprocessId Integer - The internal ID of the renderer process that sent this messageframeId Integer - The ID of the renderer frame that sent this messagesender WebContents - Returns the webContents that sent the messagesenderFrame WebFrameMain Readonly - The frame that sent this message\n\nCommunicate asynchronously from a renderer process to the main process.
\n
Prozess: Renderer
\nThe ipcRenderer module is an EventEmitter. It provides a few methods so you can send synchronous and asynchronous messages from the render process (web page) to the main process. You can also receive replies from the main process.
See ipcMain for code examples.
\nThe ipcRenderer module has the following method to listen for events and send messages:
ipcRenderer.on(channel, listener)channel Stringlistener Funktionevent IpcRendererEvent...args any[]Listens to channel, when a new message arrives listener would be called with listener(event, args...).
ipcRenderer.once(channel, listener)channel Stringlistener Funktionevent IpcRendererEvent...args any[]Adds a one time listener function for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed.
ipcRenderer.removeListener(channel, listener)channel Stringlistener Funktion...args any[]Removes the specified listener from the listener array for the specified channel.
ipcRenderer.removeAllListeners(channel)channel StringRemoves all listeners, or those of the specified channel.
ipcRenderer.send(channel, ...args)channel String...args any[]Send an asynchronous message to the main process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
The main process handles it by listening for channel with the ipcMain module.
If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you want to receive a single response from the main process, like the result of a method call, consider using ipcRenderer.invoke.
ipcRenderer.invoke(channel, ...args)channel String...args any[]Returns Promise<any> - Resolves with the response from the main process.
Send a message to the main process via channel and expect a result asynchronously. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
The main process should listen for channel with ipcMain.handle().
Ein Beispiel:
\n// Renderer process\nipcRenderer.invoke('some-name', someArgument).then((result) => {\n // ...\n})\n\n// Main process\nipcMain.handle('some-name', async (event, someArgument) => {\n const result = await doSomeWork(someArgument)\n return result\n})\nIf you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.
If you do not need a response to the message, consider using ipcRenderer.send.
ipcRenderer.sendSync(channel, ...args)channel String...args any[]Returns any - The value sent back by the ipcMain handler.
Send a message to the main process via channel and expect a result synchronously. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\nSince the main process does not have support for DOM objects such as
\nImageBitmap,File,DOMMatrixand so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. Attempting to send such objects over IPC will result in an error.
The main process handles it by listening for channel with ipcMain module, and replies by setting event.returnValue.
\n\n⚠️ WARNING: Sending a synchronous message will block the whole renderer process until the reply is received, so use this method only as a last resort. It's much better to use the asynchronous version,
\ninvoke().
ipcRenderer.postMessage(channel, message, [transfer])Send a message to the main process, optionally transferring ownership of zero or more MessagePort objects.
The transferred MessagePort objects will be available in the main process as MessagePortMain objects by accessing the ports property of the emitted event.
Ein Beispiel:
\n// Renderer process\nconst { port1, port2 } = new MessageChannel()\nipcRenderer.postMessage('port', { message: 'hello' }, [port1])\n\n// Main process\nipcMain.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nFor more information on using MessagePort and MessageChannel, see the MDN documentation.
ipcRenderer.sendTo(webContentsId, channel, ...args)webContentsId Numberchannel String...args any[]Sends a message to a window with webContentsId via channel.
ipcRenderer.sendToHost(channel, ...args)channel String...args any[]Like ipcRenderer.send but the event will be sent to the <webview> element in the host page instead of the main process.
The documentation for the event object passed to the callback can be found in the ipc-renderer-event structure docs.
Eventsender IpcRenderer - The IpcRenderer instance that emitted the event originallysenderId Integer - The webContents.id that sent the message, you can call event.sender.sendTo(event.senderId, ...) to reply to the message, see ipcRenderer.sendTo for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set event.senderId to 0.ports MessagePort[] - A list of MessagePorts that were transferred with this messageFor any issue, there are fundamentally three ways an individual can contribute:
\nelectron/electron issue tracker.electron/electron in a concrete and reviewable manner.\"Finding Support\" has a list of resources for getting programming help, reporting security issues, contributing, and more. Please use the issue tracker for bugs only!
\nTo submit a bug report:
\nWhen opening a new issue in the electron/electron issue tracker, users will be presented with a template that should be filled in.
If you believe that you have found a bug in Electron, please fill out the template to the best of your ability.
\nThe two most important pieces of information needed to evaluate the report are a description of the bug and a simple test case to recreate it. It is easier to fix a bug if it can be reproduced.
\nSee How to create a Minimal, Complete, and Verifiable example.
\nIt's common for open issues to involve discussion. Some contributors may have differing opinions, including whether the behavior is a bug or feature. This discussion is part of the process and should be kept focused, helpful, and professional.
\nTerse responses that provide neither additional context nor supporting detail are not helpful or professional. To many, such responses are annoying and unfriendly.
\nContributors are encouraged to solve issues collaboratively and help one another make progress. If you encounter an issue that you feel is invalid, or which contains incorrect information, explain why you feel that way with additional supporting context, and be willing to be convinced that you may be wrong. By doing so, we can often reach the correct outcome faster.
\nMost issues are resolved by opening a pull request. The process for opening and reviewing a pull request is similar to that of opening and triaging issues, but carries with it a necessary review and approval workflow that ensures that the proposed changes meet the minimal quality and functional guidelines of the Electron project.
", "title": "Issues In Electron", "description": "" }, "/docs/api/structures/jump-list-category": { "locale": "de-DE", "slug": "jump-list-category", "href": "/docs/api/structures/jump-list-category", "crowdinFileId": "256451", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/jump-list-category.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "type String (optional) - One of the following:tasks - Items in this category will be placed into the standard Tasks category. There can be only one such category, and it will always be displayed at the bottom of the Jump List.frequent - Displays a list of files frequently opened by the app, the name of the category and its items are set by Windows.recent - Displays a list of files recently opened by the app, the name of the category and its items are set by Windows. Items may be added to this category indirectly using app.addRecentDocument(path).custom - Displays tasks or file links, name must be set by the app.name String (optional) - Must be set if type is custom, otherwise it should be omitted.items JumpListItem - Array of JumpListItem objects if type is tasks or custom, otherwise it should be omitted.Note: If a JumpListCategory object has neither the type nor the name property set then its type is assumed to be tasks. If the name property is set but the type property is omitted then the type is assumed to be custom.
Note: The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.
type String (optional) - One of the following:task - A task will launch an app with specific arguments.separator - Can be used to separate items in the standard Tasks category.file - A file link will open a file using the app that created the Jump List, for this to work the app must be registered as a handler for the file type (though it doesn't have to be the default handler).path String (optional) - Path of the file to open, should only be set if type is file.program String (optional) - Path of the program to execute, usually you should specify process.execPath which opens the current program. Should only be set if type is task.args String (optional) - The command line arguments when program is executed. Should only be set if type is task.title String (optional) - The text to be displayed for the item in the Jump List. Should only be set if type is task.description String (optional) - Description of the task (displayed in a tooltip). Should only be set if type is task. Maximum length 260 characters.iconPath String (optional) - The absolute path to an icon to be displayed in a Jump List, which can be an arbitrary resource file that contains an icon (e.g. .ico, .exe, .dll). You can usually specify process.execPath to show the program icon.iconIndex Number (optional) - The index of the icon in the resource file. If a resource file contains multiple icons this value can be used to specify the zero-based index of the icon that should be displayed for this task. If a resource file contains only one icon, this property should be set to zero.workingDirectory String (optional) - The working directory. Default is empty.ctrlKey Boolean (optional) - whether the Control key was used in an accelerator to trigger the EventmetaKey Boolean (optional) - whether a meta key was used in an accelerator to trigger the EventshiftKey Boolean (optional) - whether a Shift key was used in an accelerator to trigger the EventaltKey Boolean (optional) - whether an Alt key was used in an accelerator to trigger the EventtriggeredByAccelerator Boolean (optional) - whether an accelerator was used to trigger the event as opposed to another user gesture like mouse clickInputEventtype String - The type of the event, can be keyDown, keyUp or char.keyCode String - The character that will be sent as the keyboard event. Should only use the valid key codes in Accelerator.This feature allows you to configure local and global keyboard shortcuts for your Electron application.
\nLocal keyboard shortcuts are triggered only when the application is focused. To configure a local keyboard shortcut, you need to specify an accelerator property when creating a MenuItem within the Menu module.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { Menu, MenuItem } = require('electron')\n\nconst menu = new Menu()\nmenu.append(new MenuItem({\n label: 'Electron',\n submenu: [{\n role: 'help',\n accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Alt+Shift+I',\n click: () => { console.log('Electron rocks!') }\n }]\n}))\n\nMenu.setApplicationMenu(menu)\n\n\nNOTE: In the code above, you can see that the accelerator differs based on the user's operating system. For MacOS, it is
\nAlt+Cmd+I, whereas for Linux and Windows, it isAlt+Shift+I.
After launching the Electron application, you should see the application menu along with the local shortcut you just defined:
\n
If you click Help or press the defined accelerator and then open the terminal that you ran your Electron application from, you will see the message that was generated after triggering the click event: \"Electron rocks!\".
To configure a global keyboard shortcut, you need to use the globalShortcut module to detect keyboard events even when the application does not have keyboard focus.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, globalShortcut } = require('electron')\n\napp.whenReady().then(() => {\n globalShortcut.register('Alt+CommandOrControl+I', () => {\n console.log('Electron loves global shortcuts!')\n })\n}).then(createWindow)\n\n\nNOTE: In the code above, the
\nCommandOrControlcombination usesCommandon macOS andControlon Windows/Linux.
After launching the Electron application, if you press the defined key combination then open the terminal that you ran your Electron application from, you will see that Electron loves global shortcuts!
\nIf you want to handle keyboard shortcuts within a BrowserWindow, you can listen for the keyup and keydown DOM events inside the renderer process using the addEventListener() API.
function handleKeyPress(event) {\n // You can put code here to handle the keypress.\n document.getElementById(\"last-keypress\").innerText = event.key;\n console.log(`You pressed ${event.key}`);\n}\n\nwindow.addEventListener('keyup', handleKeyPress, true);\n\n\nNote: the third parameter
\ntrueindicates that the listener will always receive key presses before other listeners so they can't havestopPropagation()called on them.
The before-input-event event is emitted before dispatching keydown and keyup events in the page. It can be used to catch and handle custom shortcuts that are not visible in the menu.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, BrowserWindow } = require('electron')\n\napp.whenReady().then(() => {\n const win = new BrowserWindow({ width: 800, height: 600 })\n\n win.loadFile('index.html')\n win.webContents.on('before-input-event', (event, input) => {\n if (input.control && input.key.toLowerCase() === 'i') {\n console.log('Pressed Control+I')\n event.preventDefault()\n }\n })\n})\nAfter launching the Electron application, if you open the terminal that you ran your Electron application from and press Ctrl+I key combination, you will see that this key combination was successfully intercepted.
If you don't want to do manual shortcut parsing, there are libraries that do advanced key detection, such as mousetrap. Below are examples of usage of the mousetrap running in the Renderer process:
Mousetrap.bind('4', () => { console.log('4') })\nMousetrap.bind('?', () => { console.log('show shortcuts!') })\nMousetrap.bind('esc', () => { console.log('escape') }, 'keyup')\n\n// combinations\nMousetrap.bind('command+shift+k', () => { console.log('command shift k') })\n\n// map multiple combinations to the same callback\nMousetrap.bind(['command+k', 'ctrl+k'], () => {\n console.log('command k or control k')\n\n // return false to prevent default behavior and stop event from bubbling\n return false\n})\n\n// gmail style sequences\nMousetrap.bind('g i', () => { console.log('go to inbox') })\nMousetrap.bind('* a', () => { console.log('select all') })\n\n// konami code!\nMousetrap.bind('up up down down left right left right b a enter', () => {\n console.log('konami code')\n})\ntitle: Launching Your Electron App From a URL In Another App\ndescription: This guide will take you through the process of setting your electron app as the default handler for a specific protocol.\nslug: launch-app-from-url-in-another-app
\nThis guide will take you through the process of setting your Electron app as the default handler for a specific protocol.
\nBy the end of this tutorial, we will have set our app to intercept and handle any clicked URLs that start with a specific protocol. In this guide, the protocol we will use will be \"electron-fiddle://\".
First, we will import the required modules from electron. These modules help control our application lifecycle and create a native browser window.
const { app, BrowserWindow, shell } = require('electron')\nconst path = require('path')\nNext, we will proceed to register our application to handle all \"electron-fiddle://\" protocols.
if (process.defaultApp) {\n if (process.argv.length >= 2) {\n app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])\n }\n} else {\n app.setAsDefaultProtocolClient('electron-fiddle')\n}\nWe will now define the function in charge of creating our browser window and load our application's index.html file.
const createWindow = () => {\n // Create the browser window.\n mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n mainWindow.loadFile('index.html')\n}\nIn this next step, we will create our BrowserWindow and tell our application how to handle an event in which an external protocol is clicked.
This code will be different in Windows compared to MacOS and Linux. This is due to Windows requiring additional code in order to open the contents of the protocol link within the same Electron instance. Read more about this here.
\nconst gotTheLock = app.requestSingleInstanceLock()\n\nif (!gotTheLock) {\n app.quit()\n} else {\n app.on('second-instance', (event, commandLine, workingDirectory) => {\n // Someone tried to run a second instance, we should focus our window.\n if (mainWindow) {\n if (mainWindow.isMinimized()) mainWindow.restore()\n mainWindow.focus()\n }\n })\n\n // Create mainWindow, load the rest of the app, etc...\n app.whenReady().then(() => {\n createWindow()\n })\n\n // Handle the protocol. In this case, we choose to show an Error Box.\n app.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n })\n}\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// Einige APIs können nur nach dem Auftreten dieses Events genutzt werden.\napp.whenReady().then(() => {\n createWindow()\n})\n\n// Handle the protocol. In this case, we choose to show an Error Box.\napp.on('open-url', (event, url) => {\n dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)\n})\nFinally, we will add some additional code to handle when someone closes our application.
\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') app.quit()\n})\nOn macOS and Linux, this feature will only work when your app is packaged. It will not work when you're launching it in development from the command-line. When you package your app you'll need to make sure the macOS Info.plist and the Linux .desktop files for the app are updated to include the new protocol handler. Some of the Electron tools for bundling and distributing apps handle this for you.
If you're using Electron Forge, adjust packagerConfig for macOS support, and the configuration for the appropriate Linux makers for Linux support, in your Forge configuration (please note the following example only shows the bare minimum needed to add the configuration changes):
{\n \"config\": {\n \"forge\": {\n \"packagerConfig\": {\n \"protocols\": [\n {\n \"name\": \"Electron Fiddle\",\n \"schemes\": [\"electron-fiddle\"]\n }\n ]\n },\n \"makers\": [\n {\n \"name\": \"@electron-forge/maker-deb\",\n \"config\": {\n \"mimeType\": [\"x-scheme-handler/electron-fiddle\"]\n }\n }\n ]\n }\n }\n}\nFor macOS support:
\nIf you're using Electron Packager's API, adding support for protocol handlers is similar to how Electron Forge is handled, except protocols is part of the Packager options passed to the packager function.
const packager = require('electron-packager')\n\npackager({\n // ...other options...\n protocols: [\n {\n name: 'Electron Fiddle',\n schemes: ['electron-fiddle']\n }\n ]\n\n}).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))\n .catch(err => console.error(`ERROR: ${err.message}`))\nIf you're using Electron Packager's CLI, use the --protocol and --protocol-name flags. For example:
npx electron-packager . --protocol=electron-fiddle --protocol-name=\"Electron Fiddle\"\nAfter you start your Electron app, you can enter in a URL in your browser that contains the custom protocol, for example \"electron-fiddle://open\" and observe that the application will respond and show an error dialog box.
On many Linux environments, you can add custom entries to the system launcher by modifying the .desktop file. For Canonical's Unity documentation, see Adding Shortcuts to a Launcher. For details on a more generic implementation, see the freedesktop.org Specification.
\n\nNOTE: The screenshot above is an example of launcher shortcuts in Audacious audio player
\n
To create a shortcut, you need to provide Name and Exec properties for the entry you want to add to the shortcut menu. Unity will execute the command defined in the Exec field after the user clicked the shortcut menu item. An example of the .desktop file may look as follows:
Actions=PlayPause;Next;Previous\n\n[Desktop Action PlayPause]\nName=Play-Pause\nExec=audacious -t\nOnlyShowIn=Unity;\n\n[Desktop Action Next]\nName=Next\nExec=audacious -f\nOnlyShowIn=Unity;\n\n[Desktop Action Previous]\nName=Previous\nExec=audacious -r\nOnlyShowIn=Unity;\nThe preferred way for Unity to instruct your application on what to do is using parameters. You can find them in your application in the global variable process.argv.
This guide provides information on:
\nTo sign Electron apps, the following tools must be installed first:
\nYou also have to register an Apple Developer account and join the Apple Developer Program.
\nElectron apps can be distributed through Mac App Store or outside it. Each way requires different ways of signing and testing. This guide focuses on distribution via Mac App Store, but will also mention other methods.
\nThe following steps describe how to get the certificates from Apple, how to sign Electron apps, and how to test them.
\nThe simplest way to get signing certificates is to use Xcode:
\nThe \"Apple Development\" certificate is used to sign apps for development and testing, on machines that have been registered on Apple Developer website. The method of registration will be described in Prepare provisioning profile.
\nApps signed with the \"Apple Development\" certificate cannot be submitted to Mac App Store. For that purpose, apps must be signed with the \"Apple Distribution\" certificate instead. But note that apps signed with the \"Apple Distribution\" certificate cannot run directly, they must be re-signed by Apple to be able to run, which will only be possible after being downloaded from the Mac App Store.
\nYou may notice that there are also other kinds of certificates.
\nThe \"Developer ID Application\" certificate is used to sign apps before distributing them outside the Mac App Store.
\nThe \"Developer ID Installer\" and \"Mac Installer Distribution\" certificates are used to sign the Mac Installer Package instead of the app itself. Most Electron apps do not use Mac Installer Package so they are generally not needed.
\nThe full list of certificate types can be found here.
\nApps signed with \"Apple Development\" and \"Apple Distribution\" certificates can only run under App Sandbox, so they must use the MAS build of Electron. However, the \"Developer ID Application\" certificate does not have this restrictions, so apps signed with it can use either the normal build or the MAS build of Electron.
\nApple has been changing the names of certificates during past years, you might encounter them when reading old documentations, and some utilities are still using one of the old names.
\nIf you want to test your app on your local machine before submitting your app to the Mac App Store, you have to sign the app with the \"Apple Development\" certificate with the provisioning profile embedded in the app bundle.
\nTo create a provisioning profile, you can follow the below steps:
\n/path/to/yourapp.provisionprofile.Apps submitted to the Mac App Store must run under Apple's App Sandbox, and only the MAS build of Electron can run with the App Sandbox. The standard darwin build of Electron will fail to launch when run under App Sandbox.
\nWhen signing the app with electron-osx-sign, it will automatically add the necessary entitlements to your app's entitlements, but if you are using custom entitlements, you must ensure App Sandbox capacity is added:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n </dict>\n</plist>\nelectron-osx-signIf you are signing your app without using electron-osx-sign, you must ensure the app bundle's entitlements have at least following keys:
\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.application-groups</key>\n <array>\n <string>TEAM_ID.your.bundle.id</string>\n </array>\n </dict>\n</plist>\nThe TEAM_ID should be replaced with your Apple Developer account's Team ID, and the your.bundle.id should be replaced with the App ID of the app.
And the following entitlements must be added to the binaries and helpers in the app's bundle:
\n\n\n<plist version=\"1.0\">\n <dict>\n <key>com.apple.security.app-sandbox</key>\n <true/>\n <key>com.apple.security.inherit</key>\n <true/>\n </dict>\n</plist>\nAnd the app bundle's Info.plist must include ElectronTeamID key, which has your Apple Developer account's Team ID as its value:
<plist version=\"1.0\">\n<dict>\n ...\n <key>ElectronTeamID</key>\n <string>TEAM_ID</string>\n</dict>\n</plist>\nWhen using electron-osx-sign the ElectronTeamID key will be added automatically by extracting the Team ID from the certificate's name. You may need to manually add this key if electron-osx-sign could not find the correct Team ID.
To sign an app that can run on your development machine, you must sign it with the \"Apple Development\" certificate and pass the provisioning profile to electron-osx-sign.
electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile\nIf you are signing without electron-osx-sign, you must place the provisioning profile to YourApp.app/Contents/embedded.provisionprofile.
The signed app can only run on the machines that registered by the provisioning profile, and this is the only way to test the signed app before submitting to Mac App Store.
\nTo sign an app that will be submitted to Mac App Store, you must sign it with the \"Apple Distribution\" certificate. Note that apps signed with this certificate will not run anywhere, unless it is downloaded from Mac App Store.
\nelectron-osx-sign YourApp.app --identity='Apple Distribution'\nIf you don't plan to submit the app to Mac App Store, you can sign it the \"Developer ID Application\" certificate. In this way there is no requirement on App Sandbox, and you should use the normal darwin build of Electron if you don't use App Sandbox.
\nelectron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess\nBy passing --no-gatekeeper-assess, the electron-osx-sign will skip the macOS GateKeeper check as your app usually has not been notarized yet by this step.
This guide does not cover App Notarization, but you might want to do it otherwise Apple may prevent users from using your app outside Mac App Store.
\nAfter signing the app with the \"Apple Distribution\" certificate, you can continue to submit it to Mac App Store.
\nHowever, this guide do not ensure your app will be approved by Apple; you still need to read Apple's Submitting Your App guide on how to meet the Mac App Store requirements.
\nThe Application Loader should be used to upload the signed app to iTunes Connect for processing, making sure you have created a record before uploading.
\nIf you are seeing errors like private APIs uses, you should check if the app is using the MAS build of Electron.
\nAfter uploading, you should submit your app for review.
\nIn order to satisfy all requirements for app sandboxing, the following modules have been disabled in the MAS build:
\ncrashReporterautoUpdaterand the following behaviors have been changed:
\nAlso, due to the usage of app sandboxing, the resources which can be accessed by the app are strictly limited; you can read App Sandboxing for more information.
\nDepending on which Electron APIs your app uses, you may need to add additional entitlements to your app's entitlements file. Otherwise, the App Sandbox may prevent you from using them.
\nEnable outgoing network connections to allow your app to connect to a server:
\n<key>com.apple.security.network.client</key>\n<true/>\nEnable incoming network connections to allow your app to open a network listening socket:
\n<key>com.apple.security.network.server</key>\n<true/>\nSee the Enabling Network Access documentation for more details.
\n<key>com.apple.security.files.user-selected.read-only</key>\n<true/>\nSee the Enabling User-Selected File Access documentation for more details.
\n<key>com.apple.security.files.user-selected.read-write</key>\n<true/>\nSee the Enabling User-Selected File Access documentation for more details.
\nDepending on the countries in which you are releasing your app, you may be required to provide information on the cryptographic algorithms used in your software. See the encryption export compliance docs for more information.
\nElectron uses following cryptographic algorithms:
\nElectron has APIs to configure the app's icon in the macOS Dock. A macOS-only API exists to create a custom dock menu, but Electron also uses the app dock icon as the entry point for cross-platform features like recent documents and application progress.
\nThe custom dock is commonly used to add shortcuts to tasks the user wouldn't want to open the whole app window for.
\nDock Menu der Terminal.app:
\n
To set your custom dock menu, you need to use the app.dock.setMenu API, which is only available on macOS.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app, BrowserWindow, Menu } = require('electron')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n })\n\n win.loadFile('index.html')\n}\n\nconst dockMenu = Menu.buildFromTemplate([\n {\n label: 'New Window',\n click () { console.log('New Window') }\n }, {\n label: 'New Window with Settings',\n submenu: [\n { label: 'Basic' },\n { label: 'Pro' }\n ]\n },\n { label: 'New Command...' }\n])\n\napp.whenReady().then(() => {\n if (process.platform === 'darwin') {\n app.dock.setMenu(dockMenu)\n }\n}).then(createWindow)\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\n\nAfter launching the Electron application, right click the application icon. You should see the custom menu you just defined:
\n
workingSetSize Integer - The amount of memory currently pinned to actual physical RAM.peakWorkingSetSize Integer - The maximum amount of memory that has ever been pinned to actual physical RAM.privateBytes Integer (optional) Windows - The amount of memory not shared by other processes, such as JS heap or HTML content.Note that all statistics are reported in Kilobytes.
", "title": "MemoryInfo Object", "description": "" }, "/docs/api/structures/memory-usage-details": { "locale": "de-DE", "slug": "memory-usage-details", "href": "/docs/api/structures/memory-usage-details", "crowdinFileId": "256461", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/memory-usage-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "count Numbersize NumberliveSize Number\n\nCreate native application menus and context menus.
\n
Prozess: Haupt
\nnew Menu()Neues Menü anlegen.
\nDie Menu Klasse hat folgende statische Methoden:
Menu.setApplicationMenu(menu)menu Menu | nullSets menu as the application menu on macOS. On Windows and Linux, the menu will be set as each window's top menu.
Also on Windows and Linux, you can use a & in the top-level item name to indicate which letter should get a generated accelerator. For example, using &File for the file menu would result in a generated Alt-F accelerator that opens the associated menu. The indicated character in the button label then gets an underline, and the & character is not displayed on the button label.
In order to escape the & character in an item name, add a proceeding &. For example, &&File would result in &File displayed on the button label.
Passing null will suppress the default menu. On Windows and Linux, this has the additional effect of removing the menu bar from the window.
Note: The default menu will be created automatically if the app does not set one. It contains standard items such as File, Edit, View, Window and Help.
Menu.getApplicationMenu()Returns Menu | null - The application menu, if set, or null, if not set.
Note: The returned Menu instance doesn't support dynamic addition or removal of menu items. Instance properties can still be dynamically modified.
Menu.sendActionToFirstResponder(action) macOSaction StringSends the action to the first responder of application. This is used for emulating default macOS menu behaviors. Usually you would use the role property of a MenuItem.
See the macOS Cocoa Event Handling Guide for more information on macOS' native actions.
\nMenu.buildFromTemplate(template)template (MenuItemConstructorOptions | MenuItem)[]Returns Menu
Generally, the template is an array of options for constructing a MenuItem. The usage can be referenced above.
You can also attach other fields to the element of the template and they will become properties of the constructed menu items.
Das menu Objekt hat die folgenden Instanz Methoden:
menu.popup([options])options Object (optional)window BrowserWindow (optional) - Default ist das fokussierte Fenster.x Number (optional) - Default is the current mouse cursor position. Must be declared if y is declared.y Number (optional) - Default is the current mouse cursor position. Must be declared if x is declared.positioningItem Number (optional) macOS - The index of the menu item to be positioned under the mouse cursor at the specified coordinates. Default is -1.callback Funktion (optional) - Wird aufgerufen wenn das Menü geschlossen wird.Pops up this menu as a context menu in the BrowserWindow.
menu.closePopup([browserWindow])browserWindow BrowserWindow (optional) - Default ist das fokussierte Fenster.Schließt das Kontext-Menü im browserWindow.
menu.append(menuItem)menuItem MenuItemFügt dem Menü das menuItem hinzu.
menu.getMenuItemById(id)id ZeichenfolgeReturns MenuItem | null the item with the specified id
menu.insert(pos, menuItem)pos IntegermenuItem MenuItemFüre das menuItem an der pos Position im Menü ein.
Objects created with new Menu or returned by Menu.buildFromTemplate emit the following events:
Hinweis: Manche Methoden sind nur auf spezifischen Betriebssystemen verfügbar und sind dementsprechend gekennzeichnet.
\nKehrt zurück:
\nevent EventEmitted when menu.popup() is called.
Kehrt zurück:
\nevent EventEmitiert wenn ein Popup manuell oder mit menu.closePopup() geschlossen wird.
menu objects also have the following properties:
menu.itemsA MenuItem[] array containing the menu's items.
Each Menu consists of multiple MenuItems and each MenuItem can have a submenu.
An example of creating the application menu with the simple template API:
\nconst { app, Menu } = require('electron')\n\nconst isMac = process.platform === 'darwin'\n\nconst template = [\n // { role: 'appMenu' }\n ...(isMac ? [{\n label: app.name,\n submenu: [\n { role: 'about' },\n { type: 'separator' },\n { role: 'services' },\n { type: 'separator' },\n { role: 'hide' },\n { role: 'hideOthers' },\n { role: 'unhide' },\n { type: 'separator' },\n { role: 'quit' }\n ]\n }] : []),\n // { role: 'fileMenu' }\n {\n label: 'File',\n submenu: [\n isMac ? { role: 'close' } : { role: 'quit' }\n ]\n },\n // { role: 'editMenu' }\n {\n label: 'Edit',\n submenu: [\n { role: 'undo' },\n { role: 'redo' },\n { type: 'separator' },\n { role: 'cut' },\n { role: 'copy' },\n { role: 'paste' },\n ...(isMac ? [\n { role: 'pasteAndMatchStyle' },\n { role: 'delete' },\n { role: 'selectAll' },\n { type: 'separator' },\n {\n label: 'Speech',\n submenu: [\n { role: 'startSpeaking' },\n { role: 'stopSpeaking' }\n ]\n }\n ] : [\n { role: 'delete' },\n { type: 'separator' },\n { role: 'selectAll' }\n ])\n ]\n },\n // { role: 'viewMenu' }\n {\n label: 'View',\n submenu: [\n { role: 'reload' },\n { role: 'forceReload' },\n { role: 'toggleDevTools' },\n { type: 'separator' },\n { role: 'resetZoom' },\n { role: 'zoomIn' },\n { role: 'zoomOut' },\n { type: 'separator' },\n { role: 'togglefullscreen' }\n ]\n },\n // { role: 'windowMenu' }\n {\n label: 'Window',\n submenu: [\n { role: 'minimize' },\n { role: 'zoom' },\n ...(isMac ? [\n { type: 'separator' },\n { role: 'front' },\n { type: 'separator' },\n { role: 'window' }\n ] : [\n { role: 'close' }\n ])\n ]\n },\n {\n role: 'help',\n submenu: [\n {\n label: 'Learn More',\n click: async () => {\n const { shell } = require('electron')\n await shell.openExternal('https://electronjs.org')\n }\n }\n ]\n }\n]\n\nconst menu = Menu.buildFromTemplate(template)\nMenu.setApplicationMenu(menu)\nTo create menus initiated by the renderer process, send the required information to the main process using IPC and have the main process display the menu on behalf of the renderer.
\nBelow is an example of showing a menu when the user right clicks the page:
\n// renderer\nwindow.addEventListener('contextmenu', (e) => {\n e.preventDefault()\n ipcRenderer.send('show-context-menu')\n})\n\nipcRenderer.on('context-menu-command', (e, command) => {\n // ...\n})\n\n// main\nipcMain.on('show-context-menu', (event) => {\n const template = [\n {\n label: 'Menu Item 1',\n click: () => { event.sender.send('context-menu-command', 'menu-item-1') }\n },\n { type: 'separator' },\n { label: 'Menu Item 2', type: 'checkbox', checked: true }\n ]\n const menu = Menu.buildFromTemplate(template)\n menu.popup(BrowserWindow.fromWebContents(event.sender))\n})\nmacOS has a completely different style of application menu from Windows and Linux. Here are some notes on making your app's menu more native-like.
\nOn macOS there are many system-defined standard menus, like the Services and Windows menus. To make your menu a standard menu, you should set your menu's role to one of the following and Electron will recognize them and make them become standard menus:
windowhelpservicesmacOS has provided standard actions for some menu items, like About xxx, Hide xxx, and Hide Others. To set the action of a menu item to a standard action, you should set the role attribute of the menu item.
On macOS the label of the application menu's first item is always your app's name, no matter what label you set. To change it, modify your app bundle's Info.plist file. See About Information Property List Files for more information.
The setMenu method of browser windows can set the menu of certain browser windows.
You can make use of before, after, beforeGroupContaining, afterGroupContaining and id to control how the item will be placed when building a menu with Menu.buildFromTemplate.
before - Inserts this item before the item with the specified label. If the referenced item doesn't exist the item will be inserted at the end of the menu. Also implies that the menu item in question should be placed in the same “group” as the item.after - Inserts this item after the item with the specified label. If the referenced item doesn't exist the item will be inserted at the end of the menu. Also implies that the menu item in question should be placed in the same “group” as the item.beforeGroupContaining - Provides a means for a single context menu to declare the placement of their containing group before the containing group of the item with the specified label.afterGroupContaining - Provides a means for a single context menu to declare the placement of their containing group after the containing group of the item with the specified label.By default, items will be inserted in the order they exist in the template unless one of the specified positioning keywords is used.
\nTemplate:
\n[\n { id: '1', label: 'one' },\n { id: '2', label: 'two' },\n { id: '3', label: 'three' },\n { id: '4', label: 'four' }\n]\nMenü:
\n- 1\n- 2\n- 3\n- 4\nTemplate:
\n[\n { id: '1', label: 'Eins' },\n { type: 'separator' },\n { id: '3', label: 'Drei', beforeGroupContaining: ['1'] },\n { id: '4', label: 'Vier', afterGroupContaining: ['2'] },\n { type: 'separator' },\n { id: '2', label: 'Zwei' }\n]\nMenü:
\n- 3\n- 4\n- ---\n- 1\n- ---\n- 2\nTemplate:
\n[\n { id: '1', label: 'Eins', after: ['3'] },\n { id: '2', label: 'Zwei', before: ['1'] },\n { id: '3', label: 'Drei' }\n]\nMenü:
\n- ---\n- 3\n- 2\n- 1\n\n\nAdd items to native application menus and context menus.
\n
Prozess: Haupt
\nSee Menu for examples.
new MenuItem(options)options Objektclick Function (optional) - Will be called with click(menuItem, browserWindow, event) when the menu item is clicked.menuItem MenuItembrowserWindow BrowserWindow | undefined - This will not be defined if no window is open.event KeyboardEventrole String (optional) - Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu - Define the action of the menu item, when specified the click property will be ignored. See roles.type String (optional) - Can be normal, separator, submenu, checkbox or radio.label String (optional)sublabel String (optional)toolTip String (optional) macOS - Hover-Text für diesen Nenüpunkt.accelerator Accelerator (optional)icon (NativeImage | String) (optional)enabled Boolean (optional) - If false, the menu item will be greyed out and unclickable.acceleratorWorksWhenHidden Boolean (optional) macOS - Standard ist true, und wennfalse wird es den Accelerator vom Ausführen hindern, sofern der Menüpunkt nicht sichtbar ist.visible Boolean (optional) - If false, the menu item will be entirely hidden.checked Boolean (optional) - Should only be specified for checkbox or radio type menu items.registerAccelerator Boolean (optional) Linux Windows - Sofern false wird der Accelerator nicht im System registriert, aber weiterhin angezeigt. Standard ist true.sharingItem SharingItem (optional) macOS - The item to share when the role is shareMenu.submenu (MenuItemConstructorOptions[] | Menu) (optional) - Should be specified for submenu type menu items. If submenu is specified, the type: 'submenu' can be omitted. If the value is not a Menu then it will be automatically converted to one using Menu.buildFromTemplate.id String (optional) - Unique within a single menu. If defined then it can be used as a reference to this item by the position attribute.before String - Inserts this item before the item with the specified label. If the referenced item doesn't exist the item will be inserted at the end of the menu. Also implies that the menu item in question should be placed in the same “group” as the item.after String - Inserts this item after the item with the specified label. If the referenced item doesn't exist the item will be inserted at the end of the menu.beforeGroupContaining String - Provides a means for a single context menu to declare the placement of their containing group before the containing group of the item with the specified label.afterGroupContaining String - Provides a means for a single context menu to declare the placement of their containing group after the containing group of the item with the specified label.Notiz: acceleratorWorksWhenHidden ist als nur-macOS spezifiziert, day Acceleratoren auf Windows und Linux immer arbeiten wenn Einträge versteckt sind. The option is exposed to users to give them the option to turn it off, as this is possible in native macOS development. This property is only usable on macOS High Sierra 10.13 or newer.
Roles allow menu items to have predefined behaviors.
\nIt is best to specify role for any menu item that matches a standard role, rather than trying to manually implement the behavior in a click function. The built-in role behavior will give the best native experience.
The label and accelerator values are optional when using a role and will default to appropriate values for each platform.
Every menu item must have either a role, label, or in the case of a separator a type.
The role property can have following values:
undoabout - Trigger a native about panel (custom message box on Window, which does not provide its own).redocutcopypastepasteAndMatchStyleselectAlldeleteminimize - Minimize current window.close - Close current window.quit - Quit the application.reload - Reload the current window.forceReload - Reload the current window ignoring the cache.toggleDevTools - Toggle developer tools in the current window.togglefullscreen - Toggle full screen mode on the current window.resetZoom - Reset the focused page's zoom level to the original size.zoomIn - Zoom in the focused page by 10%.zoomOut - Zoom out the focused page by 10%.toggleSpellChecker - Enable/disable builtin spell checker.fileMenu - Whole default \"File\" menu (Close / Quit)editMenu - Whole default \"Edit\" menu (Undo, Copy, etc.).viewMenu - Whole default \"View\" menu (Reload, Toggle Developer Tools, etc.)windowMenu - Whole default \"Window\" menu (Minimize, Zoom, etc.).The following additional roles are available on macOS:
\nappMenu - Whole default \"App\" menu (About, Services, etc.)hide - Map to the hide action.hideOthers - Map to the hideOtherApplications action.unhide - Map to the unhideAllApplications action.startSpeaking - Map to the startSpeaking action.stopSpeaking - Map to the stopSpeaking action.front - Map to the arrangeInFront action.zoom - Map to the performZoom action.toggleTabBar - Map to the toggleTabBar action.selectNextTab - Map to the selectNextTab action.selectPreviousTab - Map to the selectPreviousTab action.mergeAllWindows - Map to the mergeAllWindows action.moveTabToNewWindow - Map to the moveTabToNewWindow action.window - The submenu is a \"Window\" menu.help - The submenu is a \"Help\" menu.services - The submenu is a \"Services\" menu. This is only intended for use in the Application Menu and is not the same as the \"Services\" submenu used in context menus in macOS apps, which is not implemented in Electron.recentDocuments - The submenu is an \"Open Recent\" menu.clearRecentDocuments - Map to the clearRecentDocuments action.shareMenu - The submenu is share menu. The sharingItem property must also be set to indicate the item to share.When specifying a role on macOS, label and accelerator are the only options that will affect the menu item. All other options will be ignored. Lowercase role, e.g. toggledevtools, is still supported.
Nota Bene: The enabled and visibility properties are not available for top-level menu items in the tray on macOS.
The following properties are available on instances of MenuItem:
menuItem.idEin String welcher die eindeutige Id anzeigt, diese Eigenschaft kann dynamisch geändert werden.
menuItem.labelA String indicating the item's visible label.
menuItem.clickA Function that is fired when the MenuItem receives a click event. It can be called with menuItem.click(event, focusedWindow, focusedWebContents).
event KeyboardEventfocusedWindow BrowserWindowfocusedWebContents WebContentsmenuItem.submenuA Menu (optional) containing the menu item's submenu, if present.
menuItem.typeA String indicating the type of the item. Can be normal, separator, submenu, checkbox or radio.
menuItem.roleA String (optional) indicating the item's role, if set. Can be undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu
menuItem.acceleratorAn Accelerator (optional) indicating the item's accelerator, if set.
menuItem.userAccelerator Readonly macOSAn Accelerator | null indicating the item's user-assigned accelerator for the menu item.
Note: This property is only initialized after the MenuItem has been added to a Menu. Either via Menu.buildFromTemplate or via Menu.append()/insert(). Accessing before initialization will just return null.
menuItem.iconA NativeImage | String (optional) indicating the item's icon, if set.
menuItem.sublabelA String indicating the item's sublabel.
menuItem.toolTip macOSA String indicating the item's hover text.
menuItem.enabledA Boolean indicating whether the item is enabled, this property can be dynamically changed.
menuItem.visibleA Boolean indicating whether the item is visible, this property can be dynamically changed.
menuItem.checkedA Boolean indicating whether the item is checked, this property can be dynamically changed.
A checkbox menu item will toggle the checked property on and off when selected.
A radio menu item will turn on its checked property when clicked, and will turn off that property for all adjacent items in the same menu.
You can add a click function for additional behavior.
menuItem.registerAcceleratorA Boolean indicating if the accelerator should be registered with the system or just displayed.
This property can be dynamically changed.
\nmenuItem.sharingItem macOSA SharingItem indicating the item to share when the role is shareMenu.
This property can be dynamically changed.
\nmenuItem.commandIdA Number indicating an item's sequential unique id.
menuItem.menuA Menu that the item is a part of.
MessageChannelMain is the main-process-side equivalent of the DOM MessageChannel object. Its singular function is to create a pair of connected MessagePortMain objects.
See the Channel Messaging API documentation for more information on using channel messaging.
\n\n\nChannel interface for channel messaging in the main process.
\n
Prozess: Haupt
\nBeispiel:
\n// Main process\nconst { MessageChannelMain } = require('electron')\nconst { port1, port2 } = new MessageChannelMain()\nw.webContents.postMessage('port', null, [port2])\nport1.postMessage({ some: 'message' })\n\n// Renderer process\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('port', (e) => {\n // e.ports is a list of ports sent along with this message\n e.ports[0].on('message', (messageEvent) => {\n console.log(messageEvent.data)\n })\n})\nchannel.port1A MessagePortMain property.
channel.port2A MessagePortMain property.
MessagePortMain is the main-process-side equivalent of the DOM MessagePort object. It behaves similarly to the DOM version, with the exception that it uses the Node.js EventEmitter event system, instead of the DOM EventTarget system. This means you should use port.on('message', ...) to listen for events, instead of port.onmessage = ... or port.addEventListener('message', ...)
See the Channel Messaging API documentation for more information on using channel messaging.
\nMessagePortMain is an [EventEmitter][event-emitter].
\n\nPort interface for channel messaging in the main process.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
port.postMessage(message, [transfer])Sends a message from the port, and optionally, transfers ownership of objects to other browsing contexts.
\nport.start()Starts the sending of messages queued on the port. Messages will be queued until this method is called.
\nport.close()Disconnects the port, so it is no longer active.
\nKehrt zurück:
\nmessageEvent Objectdata anyports MessagePortMain[]Emitted when a MessagePortMain object receives a message.
\nEmitted when the remote end of a MessagePortMain object becomes disconnected.
", "title": "MessagePortMain", "description": "Port interface for channel messaging in the main process." }, "/docs/tutorial/message-ports": { "locale": "de-DE", "slug": "message-ports", "href": "/docs/tutorial/message-ports", "crowdinFileId": "256219", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/message-ports.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Nachrichtschlussist ein Kennzeichen von Internet, das die Nachrichte erlaubt durch verschiedene Texte einzugehen. Es ist wie Fenster. Nachricht Post, aber auf verschiedene Kanaelen. Das Ziel dieses Dokumentes ist zu beschreiben, wie Electron die Nachrichten einem Kanal uebertraegt, und Beispiele geben, wie Nachrichtschluesse in einem App verwenden.
Hier ist ein kurzes Beispiel, was ein Nachrichtschluss genau ist und seine Funktion:
\n// Geraet.js ///////////////////////////////////////////////////////////////\n//Nachrichtschluesse sind in Kuppeln geschaffen. Ein Kuppel von Nachrichtschluessen in Verbindung heisst\n//Kanal.\ndauernder. Kanal=neuer Nachrichtkanal()\n//Der eigene Unterschied zwischen Schluss 1 und Schluss2 ist wie Sie sie verwenden. Nachrichte\n//die dem Schluss1 gesendet sind, werden vom Schluss2 bekommen werden und umgekehrt.\nconst port1 = channel.port1\nconst port2 = channel.port2\n\n// It's OK to send a message on the channel before the other end has registered\n// a listener. Messages will be queued until a listener is registered.\nport2.postMessage({ answer: 42 })\n\n// Here we send the other end of the channel, port1, to the main process. It's\n// also possible to send MessagePorts to other frames, or to Web Workers, etc.\nipcRenderer.postMessage('port', null, [port1])\n// main.js ///////////////////////////////////////////////////////////////////\n// In the main process, we receive the port.\nipcMain.on('port', (event) => {\n // When we receive a MessagePort in the main process, it becomes a\n // MessagePortMain.\n const port = event.ports[0]\n\n // MessagePortMain uses the Node.js-style events API, rather than the\n // web-style events API. So .on('message', ...) instead of .onmessage = ...\n port.on('message', (event) => {\n // data is { answer: 42 }\n const data = event.data\n })\n\n // MessagePortMain queues messages until the .start() method has been called.\n port.start()\n})\nThe Channel Messaging API documentation is a great way to learn more about how MessagePorts work.
\nIn the renderer, the MessagePort class behaves exactly as it does on the web. The main process is not a web page, though—it has no Blink integration—and so it does not have the MessagePort or MessageChannel classes. In order to handle and interact with MessagePorts in the main process, Electron adds two new classes: MessagePortMain and MessageChannelMain. These behave similarly to the analogous classes in the renderer.
MessagePort objects can be created in either the renderer or the main process, and passed back and forth using the ipcRenderer.postMessage and WebContents.postMessage methods. Note that the usual IPC methods like send and invoke cannot be used to transfer MessagePorts, only the postMessage methods can transfer MessagePorts.
By passing MessagePorts via the main process, you can connect two pages that might not otherwise be able to communicate (e.g. due to same-origin restrictions).
close eventElectron adds one feature to MessagePort that isn't present on the web, in order to make MessagePorts more useful. That is the close event, which is emitted when the other end of the channel is closed. Ports can also be implicitly closed by being garbage-collected.
In the renderer, you can listen for the close event either by assigning to port.onclose or by calling port.addEventListener('close', ...). In the main process, you can listen for the close event by calling port.on('close', ...).
In this example, your app has a worker process implemented as a hidden window. You want the app page to be able to communicate directly with the worker process, without the performance overhead of relaying via the main process.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, ipcMain, MessageChannelMain } = require('electron')\n\napp.whenReady().then(async () => {\n // The worker process is a hidden BrowserWindow, so that it will have access\n // to a full Blink context (including e.g. <canvas>, audio, fetch(), etc.)\n const worker = new BrowserWindow({\n show: false,\n webPreferences: { nodeIntegration: true }\n })\n await worker.loadFile('worker.html')\n\n // The main window will send work to the worker process and receive results\n // over a MessagePort.\n const mainWindow = new BrowserWindow({\n webPreferences: { nodeIntegration: true }\n })\n mainWindow.loadFile('app.html')\n\n // We can't use ipcMain.handle() here, because the reply needs to transfer a\n // MessagePort.\n ipcMain.on('request-worker-channel', (event) => {\n // For security reasons, let's make sure only the frames we expect can\n // access the worker.\n if (event.senderFrame === mainWindow.webContents.mainFrame) {\n // Create a new channel ...\n const { port1, port2 } = new MessageChannelMain()\n // ... send one end to the worker ...\n worker.webContents.postMessage('new-client', null, [port1])\n // ... and the other end to the main window.\n event.senderFrame.postMessage('provide-worker-channel', null, [port2])\n // Now the main window and the worker can communicate with each other\n // without going through the main process!\n }\n })\n})\n<!-- worker.html ------------------------------------------------------------>\n<script>\nconst { ipcRenderer } = require('electron')\n\nfunction doWork(input) {\n // Something cpu-intensive.\n return input * 2\n}\n\n// We might get multiple clients, for instance if there are multiple windows,\n// or if the main window reloads.\nipcRenderer.on('new-client', (event) => {\n const [ port ] = event.ports\n port.onmessage = (event) => {\n // The event data can be any serializable object (and the event could even\n // carry other MessagePorts with it!)\n const result = doWork(event.data)\n port.postMessage(result)\n }\n})\n</script>\n<!-- app.html --------------------------------------------------------------->\n<script>\nconst { ipcRenderer } = require('electron')\n\n// We request that the main process sends us a channel we can use to\n// communicate with the worker.\nipcRenderer.send('request-worker-channel')\n\nipcRenderer.once('provide-worker-channel', (event) => {\n // Once we receive the reply, we can take the port...\n const [ port ] = event.ports\n // ... register a handler to receive results ...\n port.onmessage = (event) => {\n console.log('received result:', event.data)\n }\n // ... and start sending it work!\n port.postMessage(21)\n})\n</script>\nElectron's built-in IPC methods only support two modes: fire-and-forget (e.g. send), or request-response (e.g. invoke). Using MessageChannels, you can implement a \"response stream\", where a single request responds with a stream of data.
// renderer.js ///////////////////////////////////////////////////////////////\n\nfunction makeStreamingRequest (element, callback) {\n // MessageChannels are lightweight--it's cheap to create a new one for each\n // request.\n const { port1, port2 } = new MessageChannel()\n\n // We send one end of the port to the main process ...\n ipcRenderer.postMessage(\n 'give-me-a-stream',\n { element, count: 10 },\n [port2]\n )\n\n // ... and we hang on to the other end. The main process will send messages\n // to its end of the port, and close it when it's finished.\n port1.onmessage = (event) => {\n callback(event.data)\n }\n port1.onclose = () => {\n console.log('stream ended')\n }\n}\n\nmakeStreamingRequest(42, (data) => {\n console.log('got response data:', event.data)\n})\n// We will see \"got response data: 42\" 10 times.\n// main.js ///////////////////////////////////////////////////////////////////\n\nipcMain.on('give-me-a-stream', (event, msg) => {\n // The renderer has sent us a MessagePort that it wants us to send our\n // response over.\n const [replyPort] = event.ports\n\n // Here we send the messages synchronously, but we could just as easily store\n // the port somewhere and send messages asynchronously.\n for (let i = 0; i < msg.count; i++) {\n replyPort.postMessage(msg.element)\n }\n\n // We close the port when we're done to indicate to the other end that we\n // won't be sending any more messages. This isn't strictly necessary--if we\n // didn't explicitly close the port, it would eventually be garbage\n // collected, which would also trigger the 'close' event in the renderer.\n replyPort.close()\n})\nWhen context isolation is enabled, IPC messages from the main process to the renderer are delivered to the isolated world, rather than to the main world. Sometimes you want to deliver messages to the main world directly, without having to step through the isolated world.
\n// main.js ///////////////////////////////////////////////////////////////////\nconst { BrowserWindow, app, MessageChannelMain } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(async () => {\n // Create a BrowserWindow with contextIsolation enabled.\n const bw = new BrowserWindow({\n webPreferences: {\n contextIsolation: true,\n preload: path.join(__dirname, 'preload.js')\n }\n })\n bw.loadURL('index.html')\n\n // We'll be sending one end of this channel to the main world of the\n // context-isolated page.\n const { port1, port2 } = new MessageChannelMain()\n\n // It's OK to send a message on the channel before the other end has\n // registered a listener. Messages will be queued until a listener is\n // registered.\n port2.postMessage({ test: 21 })\n\n // We can also receive messages from the main world of the renderer.\n port2.on('message', (event) => {\n console.log('from renderer main world:', event.data)\n })\n port2.start()\n\n // The preload script will receive this IPC message and transfer the port\n // over to the main world.\n bw.webContents.postMessage('main-world-port', null, [port1])\n})\n// preload.js ////////////////////////////////////////////////////////////////\nconst { ipcRenderer } = require('electron')\n\n// We need to wait until the main world is ready to receive the message before\n// sending the port. We create this promise in the preload so it's guaranteed\n// to register the onload listener before the load event is fired.\nconst windowLoaded = new Promise(resolve => {\n window.onload = resolve\n})\n\nipcRenderer.on('main-world-port', async (event) => {\n await windowLoaded\n // We use regular window.postMessage to transfer the port from the isolated\n // world to the main world.\n window.postMessage('main-world-port', '*', event.ports)\n})\n<!-- index.html ------------------------------------------------------------->\n<script>\nwindow.onmessage = (event) => {\n // event.source === window means the message is coming from the preload\n // script, as opposed to from an <iframe> or other source.\n if (event.source === window && event.data === 'main-world-port') {\n const [ port ] = event.ports\n // Once we have the port, we can communicate directly with the main\n // process.\n port.onmessage = (event) => {\n console.log('from main process:', event.data)\n port.postMessage(event.data * 2)\n }\n }\n}\n</script>\nmimeType String (optional) - MIME type of the buffer.charset String (optional) - Charset of the buffer.data Buffer - The actual Buffer content.InputEventtype String - The type of the event, can be mouseDown, mouseUp, mouseEnter, mouseLeave, contextMenu, mouseWheel or mouseMove.x Integery Integerbutton String (optional) - The button pressed, can be left, middle, right.globalX Integer (optional)globalY Integer (optional)movementX Integer (optional)movementY Integer (optional)clickCount Integer (optional)MouseInputEventtype String - The type of the event, can be mouseWheel.deltaX Integer (optional)deltaY Integer (optional)wheelTicksX Integer (optional)wheelTicksY Integer (optional)accelerationRatioX Integer (optional)accelerationRatioY Integer (optional)hasPreciseScrollingDeltas Boolean (optional)canScroll Boolean (optional)Mit Web Workers ist es möglich, JavaScript in OS-Level Threads auszuführen.
\nEs ist möglich Node.js features in Electrons Webworkers zu verwenden. Dazu muss die Option nodeIntegrationInWorker in den <0>WebPreferences</0> auf <0>true</0> gesetzt werden.
const win = new BrowserWindow({\n webPreferences: {\n nodeIntegrationInWorker: true\n }\n})\nThe nodeIntegrationInWorker can be used independent of nodeIntegration, but sandbox must not be set to true.
All built-in modules of Node.js are supported in Web Workers, and asar archives can still be read with Node.js APIs. However none of Electron's built-in modules can be used in a multi-threaded environment.
Any native Node.js module can be loaded directly in Web Workers, but it is strongly recommended not to do so. Most existing native modules have been written assuming single-threaded environment, using them in Web Workers will lead to crashes and memory corruptions.
\nNote that even if a native Node.js module is thread-safe it's still not safe to load it in a Web Worker because the process.dlopen function is not thread safe.
The only way to load a native module safely for now, is to make sure the app loads no native modules after the Web Workers get started.
\nprocess.dlopen = () => {\n throw new Error('Load native module is not safe')\n}\nconst worker = new Worker('script.js')\nCertain kinds of applications that manipulate files might want to support the operating system's native file drag & drop feature. Dragging files into web content is common and supported by many websites. Electron additionally supports dragging files and content out from web content into the operating system's world.
\nTo implement this feature in your app, you need to call the webContents.startDrag(item) API in response to the ondragstart event.
An example demonstrating how you can create a file on the fly to be dragged out of the window.
\nIn preload.js use the contextBridge to inject a method window.electron.startDrag(...) that will send an IPC message to the main process.
const { contextBridge, ipcRenderer } = require('electron')\nconst path = require('path')\n\ncontextBridge.exposeInMainWorld('electron', {\n startDrag: (fileName) => {\n ipcRenderer.send('ondragstart', path.join(process.cwd(), fileName))\n }\n})\nAdd a draggable element to index.html, and reference your renderer script:
<div style=\"border:2px solid black;border-radius:3px;padding:5px;display:inline-block\" draggable=\"true\" id=\"drag\">Drag me</div>\n<script src=\"renderer.js\"></script>\nIn renderer.js set up the renderer process to handle drag events by calling the method you added via the contextBridge above.
document.getElementById('drag').ondragstart = (event) => {\n event.preventDefault()\n window.electron.startDrag('drag-and-drop.md')\n}\nIn the Main process (main.js file), expand the received event with a path to the file that is being dragged and an icon:
const { ipcMain } = require('electron')\n\nipcMain.on('ondragstart', (event, filePath) => {\n event.sender.startDrag({\n file: filePath,\n icon: '/path/to/icon.png'\n })\n})\nAfter launching the Electron application, try dragging and dropping the item from the BrowserWindow onto your desktop. In this guide, the item is a Markdown file located in the root of the project:
\n
\n\n\nCreate tray, dock, and application icons using PNG or JPG files.
\n
In Electron, for the APIs that take images, you can pass either file paths or NativeImage instances. An empty image will be used when null is passed.
For example, when creating a tray or setting a window's icon, you can pass an image file path as a String:
const { BrowserWindow, Tray } = require('electron')\n\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconst win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })\nconsole.log(appIcon, win)\nOr read the image from the clipboard, which returns a NativeImage:
const { clipboard, Tray } = require('electron')\nconst image = clipboard.readImage()\nconst appIcon = new Tray(image)\nconsole.log(appIcon)\nCurrently PNG and JPEG image formats are supported. PNG is recommended because of its support for transparency and lossless compression.
On Windows, you can also load ICO icons from file paths. For best visual quality, it is recommended to include at least the following sizes in the:
Check the Size requirements section in this article.
\nOn platforms that have high-DPI support such as Apple Retina displays, you can append @2x after image's base filename to mark it as a high resolution image.
For example, if icon.png is a normal image that has standard resolution, then icon@2x.png will be treated as a high resolution image that has double DPI density.
If you want to support displays with different DPI densities at the same time, you can put images with different sizes in the same folder and use the filename without DPI suffixes. Ein Beispiel:
\nimages/\n├── icon.png\n├── icon@2x.png\n└── icon@3x.png\nconst { Tray } = require('electron')\nconst appIcon = new Tray('/Users/somebody/images/icon.png')\nconsole.log(appIcon)\nThe following suffixes for DPI are also supported:
\n@1x@1.25x@1.33x@1.4x@1.5x@1.8x@2x@2.5x@3x@4x@5xTemplate images consist of black and an alpha channel. Template images are not intended to be used as standalone images and are usually mixed with other content to create the desired final appearance.
\nThe most common case is to use template images for a menu bar icon, so it can adapt to both light and dark menu bars.
\nNote: Template image is only supported on macOS.
\nTo mark an image as a template image, its filename should end with the word Template. Ein Beispiel:
xxxTemplate.pngxxxTemplate@2x.pngThe nativeImage module has the following methods, all of which return an instance of the NativeImage class:
nativeImage.createEmpty()Gibt das NativeImage zurück
Creates an empty NativeImage instance.
nativeImage.createThumbnailFromPath(path, maxSize) macOS Windowspath String - path to a file that we intend to construct a thumbnail out of.maxSize Size - the maximum width and height (positive numbers) the thumbnail returned can be. The Windows implementation will ignore maxSize.height and scale the height according to maxSize.width.Returns Promise<NativeImage> - fulfilled with the file's thumbnail preview image, which is a NativeImage.
nativeImage.createFromPath(path)path StringGibt das NativeImage zurück
Creates a new NativeImage instance from a file located at path. This method returns an empty image if the path does not exist, cannot be read, or is not a valid image.
const nativeImage = require('electron').nativeImage\n\nconst image = nativeImage.createFromPath('/Users/somebody/images/icon.png')\nconsole.log(image)\nnativeImage.createFromBitmap(buffer, options)buffer Bufferoptions Objektwidth Integerheight IntegerscaleFactor Double (optional) - Defaults to 1.0.Gibt das NativeImage zurück
Creates a new NativeImage instance from buffer that contains the raw bitmap pixel data returned by toBitmap(). The specific format is platform-dependent.
nativeImage.createFromBuffer(buffer[, options])buffer Bufferoptions Object (optional)width Integer (optional) - Required for bitmap buffers.height Integer (optional) - Required for bitmap buffers.scaleFactor Double (optional) - Defaults to 1.0.Gibt das NativeImage zurück
Creates a new NativeImage instance from buffer. Tries to decode as PNG or JPEG first.
nativeImage.createFromDataURL(dataURL)dataURL StringGibt das NativeImage zurück
Creates a new NativeImage instance from dataURL.
nativeImage.createFromNamedImage(imageName[, hslShift]) macOSGibt das NativeImage zurück
Creates a new NativeImage instance from the NSImage that maps to the given image name. See System Icons for a list of possible values.
The hslShift is applied to the image with the following rules:
hsl_shift[0] (hue): The absolute hue value for the image - 0 and 1 map to 0 and 360 on the hue color wheel (red).hsl_shift[1] (saturation): A saturation shift for the image, with the following key values: 0 = remove all color. 0.5 = leave unchanged. 1 = fully saturate the image.hsl_shift[2] (lightness): A lightness shift for the image, with the following key values: 0 = remove all lightness (make all pixels black). 0.5 = leave unchanged. 1 = full lightness (make all pixels white).This means that [-1, 0, 1] will make the image completely white and [-1, 1, 0] will make the image completely black.
In some cases, the NSImageName doesn't match its string representation; one example of this is NSFolderImageName, whose string representation would actually be NSFolder. Therefore, you'll need to determine the correct string representation for your image before passing it in. This can be done with the following:
echo -e '#import <Cocoa/Cocoa.h>\\nint main() { NSLog(@\"%@\", SYSTEM_IMAGE_NAME); }' | clang -otest -x objective-c -framework Cocoa - && ./test
where SYSTEM_IMAGE_NAME should be replaced with any value from this list.
\n\nNatively wrap images such as tray, dock, and application icons.
\n
Process: Main, Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
The following methods are available on instances of the NativeImage class:
image.toPNG([options])options Object (optional)scaleFactor Double (optional) - Defaults to 1.0.Returns Buffer - A Buffer that contains the image's PNG encoded data.
image.toJPEG(quality)quality Integer - Between 0 - 100.Returns Buffer - A Buffer that contains the image's JPEG encoded data.
image.toBitmap([options])options Object (optional)scaleFactor Double (optional) - Defaults to 1.0.Returns Buffer - A Buffer that contains a copy of the image's raw bitmap pixel data.
image.toDataURL([options])options Object (optional)scaleFactor Double (optional) - Defaults to 1.0.Returns String - The data URL of the image.
image.getBitmap([options])options Object (optional)scaleFactor Double (optional) - Defaults to 1.0.Returns Buffer - A Buffer that contains the image's raw bitmap pixel data.
The difference between getBitmap() and toBitmap() is that getBitmap() does not copy the bitmap data, so you have to use the returned Buffer immediately in current event loop tick; otherwise the data might be changed or destroyed.
image.getNativeHandle() macOSReturns Buffer - A Buffer that stores C pointer to underlying native handle of the image. On macOS, a pointer to NSImage instance would be returned.
Notice that the returned pointer is a weak pointer to the underlying native image instead of a copy, so you must ensure that the associated nativeImage instance is kept around.
image.isEmpty()Returns Boolean - Whether the image is empty.
image.getSize([scaleFactor])scaleFactor Double (optional) - Defaults to 1.0.Returns Size.
If scaleFactor is passed, this will return the size corresponding to the image representation most closely matching the passed value.
image.setTemplateImage(option)option BooleanMarks the image as a template image.
\nimage.isTemplateImage()Returns Boolean - Whether the image is a template image.
image.crop(rect)rect Rectangle - The area of the image to crop.Returns NativeImage - The cropped image.
image.resize(options)options Objektwidth Integer (optional) - Defaults to the image's width.height Integer (optional) - Defaults to the image's height.quality String (optional) - The desired quality of the resize image. Mögliche Werte sind good, better oder best. The default is best. These values express a desired quality/speed tradeoff. They are translated into an algorithm-specific method that depends on the capabilities (CPU, GPU) of the underlying platform. It is possible for all three methods to be mapped to the same algorithm on a given platform.Returns NativeImage - The resized image.
If only the height or the width are specified then the current aspect ratio will be preserved in the resized image.
image.getAspectRatio([scaleFactor])scaleFactor Double (optional) - Defaults to 1.0.Returns Float - The image's aspect ratio.
If scaleFactor is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value.
image.getScaleFactors()Returns Float[] - An array of all scale factors corresponding to representations for a given nativeImage.
image.addRepresentation(options)options ObjektscaleFactor Double - The scale factor to add the image representation for.width Integer (optional) - Defaults to 0. Required if a bitmap buffer is specified as buffer.height Integer (optional) - Defaults to 0. Required if a bitmap buffer is specified as buffer.buffer Buffer (optional) - The buffer containing the raw image data.dataURL String (optional) - The data URL containing either a base 64 encoded PNG or JPEG image.Add an image representation for a specific scale factor. This can be used to explicitly add different scale factor representations to an image. This can be called on empty images.
\nnativeImage.isMacTemplateImage macOSA Boolean property that determines whether the image is considered a template image.
Please note that this property only has an effect on macOS.
", "title": "nativeImage", "description": "Create tray, dock, and application icons using PNG or JPG files." }, "/docs/api/native-theme": { "locale": "de-DE", "slug": "native-theme", "href": "/docs/api/native-theme", "crowdinFileId": "256343", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/native-theme.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRead and respond to changes in Chromium's native color theme.
\n
Prozess: Haupt
\nDas nativeTheme Modul sendet folgende Ereignisse aus:
Emitted when something in the underlying NativeTheme has changed. This normally means that either the value of shouldUseDarkColors, shouldUseHighContrastColors or shouldUseInvertedColorScheme has changed. You will have to check them to determine which one has changed.
The nativeTheme module has the following properties:
nativeTheme.shouldUseDarkColors ReadonlyA Boolean for if the OS / Chromium currently has a dark mode enabled or is being instructed to show a dark-style UI. If you want to modify this value you should use themeSource below.
nativeTheme.themeSourceA String property that can be system, light or dark. It is used to override and supersede the value that Chromium has chosen to use internally.
Setting this property to system will remove the override and everything will be reset to the OS default. By default themeSource is system.
Settings this property to dark will have the following effects:
nativeTheme.shouldUseDarkColors will be true when accessedprefers-color-scheme CSS query will match dark mode.updated event will be emittedSettings this property to light will have the following effects:
nativeTheme.shouldUseDarkColors will be false when accessedprefers-color-scheme CSS query will match light mode.updated event will be emittedThe usage of this property should align with a classic \"dark mode\" state machine in your application where the user has three options.
\nFollow OS --> themeSource = 'system'Dark Mode --> themeSource = 'dark'Light Mode --> themeSource = 'light'Your application should then always use shouldUseDarkColors to determine what CSS to apply.
nativeTheme.shouldUseHighContrastColors macOS Windows ReadonlyA Boolean for if the OS / Chromium currently has high-contrast mode enabled or is being instructed to show a high-contrast UI.
nativeTheme.shouldUseInvertedColorScheme macOS Windows ReadonlyA Boolean for if the OS / Chromium currently has an inverted color scheme or is being instructed to use an inverted color scheme.
\n\nIssue HTTP/HTTPS requests using Chromium's native networking library
\n
Prozess: Haupt
\nThe net module is a client-side API for issuing HTTP(S) requests. It is similar to the HTTP and HTTPS modules of Node.js but uses Chromium's native networking library instead of the Node.js implementation, offering better support for web proxies. It also supports checking network status.
The following is a non-exhaustive list of why you may consider using the net module instead of the native Node.js modules:
The API components (including classes, methods, properties and event names) are similar to those used in Node.js.
\nExample usage:
\nconst { app } = require('electron')\napp.whenReady().then(() => {\n const { net } = require('electron')\n const request = net.request('https://github.com')\n request.on('response', (response) => {\n console.log(`STATUS: ${response.statusCode}`)\n console.log(`HEADERS: ${JSON.stringify(response.headers)}`)\n response.on('data', (chunk) => {\n console.log(`BODY: ${chunk}`)\n })\n response.on('end', () => {\n console.log('No more data in response.')\n })\n })\n request.end()\n})\nThe net API can be used only after the application emits the ready event. Trying to use the module before the ready event will throw an error.
Das Modul net besitzt folgende Methoden:
net.request(options)options (ClientRequestConstructorOptions | String) - The ClientRequest constructor options.Returns ClientRequest
Creates a ClientRequest instance using the provided options which are directly forwarded to the ClientRequest constructor. The net.request method would be used to issue both secure and insecure HTTP requests according to the specified protocol scheme in the options object.
net.isOnline()Returns Boolean - Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
net.online ReadonlyA Boolean property. Whether there is currently internet connection.
A return value of false is a pretty strong indicator that the user won't be able to connect to remote sites. However, a return value of true is inconclusive; even if some link is up, it is uncertain whether a particular connection attempt to a particular remote site will be successful.
\n\nLogging network events for a session.
\n
Prozess: Haupt
\nconst { netLog } = require('electron')\n\napp.whenReady().then(async () => {\n await netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nSee --log-net-log to log network events throughout the app's lifecycle.
Note: All methods unless specified can only be used after the ready event of the app module gets emitted.
netLog.startLogging(path[, options])path String - Dateipfad zu den Netzwerk Logfiles.options Object (optional)captureMode String (optional) - What kinds of data should be captured. By default, only metadata about requests will be captured. Setting this to includeSensitive will include cookies and authentication data. Setting it to everything will include all bytes transferred on sockets. Can be default, includeSensitive or everything.maxFileSize Number (optional) - When the log grows beyond this size, logging will automatically stop. Defaults to unlimited.Returns Promise<void> - resolves when the net log has begun recording.
Beginnt die Aufzeichnung von Netzwerk Events in path.
netLog.stopLogging()Returns Promise<void> - resolves when the net log has been flushed to disk.
Beendet die Aufzeichnung der Netzwerk Events. Wenn nicht aufgerufen, dann beendet net die Aufzeichnung automatisch wenn die App beendet wird.
\nnetLog.currentlyLogging ReadonlyA Boolean property that indicates whether network logs are currently being recorded.
EventnewGuest BrowserWindow (optional)\n\nCreate OS desktop notifications
\n
Prozess: Haupt
\nIf you want to show Notifications from a renderer process you should use the HTML5 Notification API
\n\n\nCreate OS desktop notifications
\n
Prozess: Haupt
\nNotification ist ein EventEmitter.
Es erzeugt ein neues Notification mit nativen Eigenschaften die durch options gesetzt wurden.
Die Notification Klasse hat folgende statische Methoden:
Notification.isSupported()Returns Boolean - Whether or not desktop notifications are supported on the current system
new Notification([options])options Object (optional)title String (optional) - A title for the notification, which will be shown at the top of the notification window when it is shown.subtitle String (optional) macOS - A subtitle for the notification, which will be displayed below the title.body String (optional) - The body text of the notification, which will be displayed below the title or subtitle.silent Boolean (optional) - Whether or not to emit an OS notification noise when showing the notification.icon (String | NativeImage) (optional) - An icon to use in the notification.hasReply Boolean (optional) macOS - Whether or not to add an inline reply option to the notification.timeoutType String (optional) Linux Windows - The timeout duration of the notification. Can be 'default' or 'never'.replyPlaceholder String (optional) macOS - The placeholder to write in the inline reply input field.sound String (optional) macOS - The name of the sound file to play when the notification is shown.urgency String (optional) Linux - The urgency level of the notification. Can be 'normal', 'critical', or 'low'.actions NotificationAction[] (optional) macOS - Actions to add to the notification. Please read the available actions and limitations in the NotificationAction documentation.closeButtonText String (optional) macOS - A custom title for the close button of an alert. An empty string will cause the default localized text to be used.toastXml String (optional) Windows - A custom description of the Notification on Windows superseding all properties above. Provides full customization of design and behavior of the notification.Objekte welche mit new Notification erzeugt wurden emitieren folgende Events:
Hinweis: Manche Methoden sind nur auf spezifischen Betriebssystemen verfügbar und sind dementsprechend gekennzeichnet.
\nKehrt zurück:
\nevent EventEmitted when the notification is shown to the user, note this could be fired multiple times as a notification can be shown multiple times through the show() method.
Kehrt zurück:
\nevent EventEmitted when the notification is clicked by the user.
\nKehrt zurück:
\nevent EventEmitted when the notification is closed by manual intervention from the user.
\nThis event is not guaranteed to be emitted in all cases where the notification is closed.
\nKehrt zurück:
\nevent Eventreply String - The string the user entered into the inline reply field.Emitted when the user clicks the \"Reply\" button on a notification with hasReply: true.
Kehrt zurück:
\nevent Eventindex Number - The index of the action that was activated.Kehrt zurück:
\nevent Eventerror String - The error encountered during execution of the show() method.Emitted when an error is encountered while creating and showing the native notification.
\nObjekte, die mit new Notification erstellt wurden, haben folgende Instanzmethoden:
notification.show()Immediately shows the notification to the user, please note this means unlike the HTML5 Notification implementation, instantiating a new Notification does not immediately show it to the user, you need to call this method before the OS will display it.
If the notification has been shown before, this method will dismiss the previously shown notification and create a new one with identical properties.
\nnotification.close()Dismisses the notification.
\nnotification.titleA String property representing the title of the notification.
notification.subtitleA String property representing the subtitle of the notification.
notification.bodyA String property representing the body of the notification.
notification.replyPlaceholderA String property representing the reply placeholder of the notification.
notification.soundA String property representing the sound of the notification.
notification.closeButtonTextA String property representing the close button text of the notification.
notification.silentA Boolean property representing whether the notification is silent.
notification.hasReplyA Boolean property representing whether the notification has a reply action.
notification.urgency LinuxA String property representing the urgency level of the notification. Can be 'normal', 'critical', or 'low'.
Default is 'low' - see NotifyUrgency for more information.
\nnotification.timeoutType Linux WindowsA String property representing the type of timeout duration for the notification. Can be 'default' or 'never'.
If timeoutType is set to 'never', the notification never expires. It stays open until closed by the calling API or the user.
notification.actionsA NotificationAction[] property representing the actions of the notification.
notification.toastXml WindowsA String property representing the custom Toast XML of the notification.
On macOS, you can specify the name of the sound you'd like to play when the notification is shown. Any of the default sounds (under System Preferences > Sound) can be used, in addition to custom sound files. Be sure that the sound file is copied under the app bundle (e.g., YourApp.app/Contents/Resources), or one of the following locations:
~/Library/Sounds/Library/Sounds/Network/Library/Sounds/System/Library/SoundsSee the NSSound docs for more information.
type String - The type of action, can be button.text String (optional) - The label for the given action.| Action Type | Platform Support | Usage of text | Default text | Limitations |
|---|---|---|---|---|
button | macOS | Used as the label for the button | \"Show\" (or a localized string by system default if first of such button, otherwise empty) | Only the first one is used. If multiple are provided, those beyond the first will be listed as additional actions (displayed when mouse active over the action button). Any such action also is incompatible with hasReply and will be ignored if hasReply is true. |
In order for extra notification buttons to work on macOS your app must meet the following criteria.
\nNSUserNotificationAlertStyle set to alert in the Info.plist.If either of these requirements are not met the button won't appear.
", "title": "NotificationAction Object", "description": "" }, "/docs/api/structures/notification-response": { "locale": "de-DE", "slug": "notification-response", "href": "/docs/api/structures/notification-response", "crowdinFileId": "256473", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/notification-response.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "actionIdentifier String - The identifier string of the action that the user selected.date Number - The delivery date of the notification.identifier String - The unique identifier for this notification request.userInfo Record<String, any> - A dictionary of custom information associated with the notification.userText String (optional) - The text entered or chosen by the user.All three operating systems provide means for applications to send notifications to the user. The technique of showing notifications is different for the Main and Renderer processes.
\nFor the Renderer process, Electron conveniently allows developers to send notifications with the HTML5 Notification API, using the currently running operating system's native notification APIs to display it.
\nTo show notifications in the Main process, you need to use the Notification module.
\nStarting with a working application from the Quick Start Guide, add the following line to the index.html file before the closing </body> tag:
<script src=\"renderer.js\"></script>\n...and add the renderer.js file:
const NOTIFICATION_TITLE = 'Title'\nconst NOTIFICATION_BODY = 'Notification from the Renderer process. Click to log to console.'\nconst CLICK_MESSAGE = 'Notification clicked'\n\nnew Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY })\n .onclick = () => console.log(CLICK_MESSAGE)\nAfter launching the Electron application, you should see the notification:
\n
Additionally, if you click on the notification, the DOM will update to show \"Notification clicked!\".
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { Notification } = require('electron')\n\nconst NOTIFICATION_TITLE = 'Basic Notification'\nconst NOTIFICATION_BODY = 'Notification from the Main process'\n\nfunction showNotification () {\n new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()\n}\n\napp.whenReady().then(createWindow).then(showNotification)\nAfter launching the Electron application, you should see the system notification:
\n
Während Code und Benutzererfahrung innerhalb der Betriebssysteme ähnlich sind, gibt es leichte Unterschiede.
\nnode_modules\\electron\\dist\\electron.exe to your Start Menu also does the trick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'. You will then need to add the line app.setAppUserModelId(process.execPath) to your main process to see notifications.Electron attempts to automate the work around the Application User Model ID. When Electron is used together with the installation and update framework Squirrel, shortcuts will automatically be set correctly. Furthermore, Electron will detect that Squirrel was used and will automatically call app.setAppUserModelId() with the correct value. During development, you may have to call app.setAppUserModelId() yourself.
Furthermore, in Windows 8, the maximum length for the notification body is 250 characters, with the Windows team recommending that notifications should be kept to 200 characters. That said, that limitation has been removed in Windows 10, with the Windows team asking developers to be reasonable. Attempting to send gigantic amounts of text to the API (thousands of characters) might result in instability.
\nLater versions of Windows allow for advanced notifications, with custom templates, images, and other flexible elements. To send those notifications (from either the main process or the renderer process), use the userland module electron-windows-notifications, which uses native Node addons to send ToastNotification and TileNotification objects.
While notifications including buttons work with electron-windows-notifications, handling replies requires the use of electron-windows-interactive-notifications, which helps with registering the required COM components and calling your Electron app with the entered user data.
To detect whether or not you're allowed to send a notification, use the userland module electron-notification-state.
\nThis allows you to determine ahead of time whether or not Windows will silently throw the notification away.
\nNotifications are straight-forward on macOS, but you should be aware of Apple's Human Interface guidelines regarding notifications.
\nNote that notifications are limited to 256 bytes in size and will be truncated if you exceed that limit.
\nTo detect whether or not you're allowed to send a notification, use the userland module electron-notification-state.
\nThis will allow you to detect ahead of time whether or not the notification will be displayed.
\nNotifications are sent using libnotify which can show notifications on any desktop environment that follows Desktop Notifications Specification, including Cinnamon, Enlightenment, Unity, GNOME, KDE.
Offscreen rendering lets you obtain the content of a BrowserWindow in a bitmap, so it can be rendered anywhere, for example, on texture in a 3D scene. The offscreen rendering in Electron uses a similar approach to that of the Chromium Embedded Framework project.
Notes:
\npaint event to be more efficient.GPU beschleunigtes Rendering bedeutet, dass der Grafikprozessor für die Bildgenerierung verwendet wird. Because of that, the frame has to be copied from the GPU which requires more resources, thus this mode is slower than the Software output device. The benefit of this mode is that WebGL and 3D CSS animations are supported.
\nThis mode uses a software output device for rendering in the CPU, so the frame generation is much faster. As a result, this mode is preferred over the GPU accelerated one.
\nTo enable this mode, GPU acceleration has to be disabled by calling the app.disableHardwareAcceleration() API.
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\n\napp.disableHardwareAcceleration()\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ webPreferences: { offscreen: true } })\n\n win.loadURL('https://github.com')\n win.webContents.on('paint', (event, dirty, image) => {\n fs.writeFileSync('ex.png', image.toPNG())\n })\n win.webContents.setFrameRate(60)\n})\nAfter launching the Electron application, navigate to your application's working folder, where you'll find the rendered image.
", "title": "Offscreen Rendering", "description": "" }, "/docs/tutorial/online-offline-events": { "locale": "de-DE", "slug": "online-offline-events", "href": "/docs/tutorial/online-offline-events", "crowdinFileId": "256229", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/online-offline-events.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Online and offline event detection can be implemented in the Renderer process using the navigator.onLine attribute, part of standard HTML5 API.
The navigator.onLine attribute returns:
false if all network requests are guaranteed to fail (e.g. when disconnected from the network).true in all other cases.Since many cases return true, you should treat with care situations of getting false positives, as we cannot always assume that true value means that Electron can access the Internet. For example, in cases when the computer is running a virtualization software that has virtual Ethernet adapters in \"always connected\" state. Therefore, if you want to determine the Internet access status of Electron, you should develop additional means for this check.
Starting with an HTML file index.html, this example will demonstrate how the navigator.onLine API can be used to build a connection status indicator.
\n<html>\n<head>\n <meta charset=\"UTF-8\">\n <title>Hello World!</title>\n <meta http-equiv=\"Content-Security-Policy\" content=\"script-src 'self' 'unsafe-inline';\" />\n</head>\n<body>\n <h1>Connection status: <strong id='status'></strong></h1>\n <script src=\"renderer.js\"></script>\n</body>\n</html>\nIn order to mutate the DOM, create a renderer.js file that adds event listeners to the 'online' and 'offline' window events. The event handler sets the content of the <strong id='status'> element depending on the result of navigator.onLine.
function updateOnlineStatus () {\n document.getElementById('status').innerHTML = navigator.onLine ? 'online' : 'offline'\n}\n\nwindow.addEventListener('online', updateOnlineStatus)\nwindow.addEventListener('offline', updateOnlineStatus)\n\nupdateOnlineStatus()\nFinally, create a main.js file for main process that creates the window.
const { app, BrowserWindow } = require('electron')\n\nfunction createWindow () {\n const onlineStatusWindow = new BrowserWindow({\n width: 400,\n height: 100\n })\n\n onlineStatusWindow.loadFile('index.html')\n}\n\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n })\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\nAfter launching the Electron application, you should see the notification:
\n
\n", "title": "Online/Offline Ereigniserkennung", "description": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API." }, "/docs/development/patches": { "locale": "de-DE", "slug": "patches", "href": "/docs/development/patches", "crowdinFileId": "256161", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/patches.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Note: If you need to communicate the connection status to the main process, use the IPC renderer API.
\n
Electron is built on two major upstream projects: Chromium and Node.js. Each of these projects has several of their own dependencies, too. We try our best to use these dependencies exactly as they are but sometimes we can't achieve our goals without patching those upstream dependencies to fit our use cases.
\nEvery patch in Electron is a maintenance burden. When upstream code changes, patches can break—sometimes without even a patch conflict or a compilation error. It's an ongoing effort to keep our patch set up-to-date and effective. So we strive to keep our patch count at a minimum. To that end, every patch must describe its reason for existence in its commit message. That reason must be one of the following:
\nProfile). Include reasoning about why the change cannot be implemented without a patch (e.g. by subclassing or copying the code).In general, all the upstream projects we work with are friendly folks and are often happy to accept refactorings that allow the code in question to be compatible with both Electron and the upstream project. (See e.g. this change in Chromium, which allowed us to remove a patch that did the same thing, or this change in Node, which was a no-op for Node but fixed a bug in Electron.) We should aim to upstream changes whenever we can, and avoid indefinite-lifetime patches.
\nIf you find yourself in the unfortunate position of having to make a change which can only be made through patching an upstream project, you'll need to know how to manage patches in Electron.
\nAll patches to upstream projects in Electron are contained in the patches/ directory. Each subdirectory of patches/ contains several patch files, along with a .patches file which lists the order in which the patches should be applied. Think of these files as making up a series of git commits that are applied on top of the upstream project after we check it out.
patches\n├── config.json <-- this describes which patchset directory is applied to what project\n├── chromium\n│ ├── .patches\n│ ├── accelerator.patch\n│ ├── add_contentgpuclient_precreatemessageloop_callback.patch\n│ ⋮\n├── node\n│ ├── .patches\n│ ├── add_openssl_is_boringssl_guard_to_oaep_hash_check.patch\n│ ├── build_add_gn_build_files.patch\n│ ⋮\n⋮\nTo help manage these patch sets, we provide two tools: git-import-patches and git-export-patches. git-import-patches imports a set of patch files into a git repository by applying each patch in the correct order and creating a commit for each one. git-export-patches does the reverse; it exports a series of git commits in a repository into a set of files in a directory and an accompanying .patches file.
\n\nSide note: the reason we use a
\n.patchesfile to maintain the order of applied patches, rather than prepending a number like001-to each file, is because it reduces conflicts related to patch ordering. It prevents the situation where two PRs both add a patch at the end of the series with the same numbering and end up both getting merged resulting in a duplicate identifier, and it also reduces churn when a patch is added or deleted in the middle of the series.
$ cd src/third_party/electron_node\n$ vim some/code/file.cc\n$ git commit\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\n\n\nNOTE:
\ngit-export-patchesignores any uncommitted files, so you must create a commit if you want your changes to be exported. The subject line of the commit message will be used to derive the patch file name, and the body of the commit message should include the reason for the patch's existence.
Re-exporting patches will sometimes cause shasums in unrelated patches to change. This is generally harmless and can be ignored (but go ahead and add those changes to your PR, it'll stop them from showing up for other people).
\n$ cd src/v8\n$ vim some/code/file.cc\n$ git log\n# Find the commit sha of the patch you want to edit.\n$ git commit --fixup [COMMIT_SHA]\n$ git rebase --autosquash -i [COMMIT_SHA]^\n$ ../electron/script/git-export-patches -o ../electron/patches/v8\n$ vim src/electron/patches/node/.patches\n# Delete the line with the name of the patch you want to remove\n$ cd src/third_party/electron_node\n$ git reset --hard refs/patches/upstream-head\n$ ../../electron/script/git-import-patches ../../electron/patches/node\n$ ../../electron/script/git-export-patches -o ../../electron/patches/node\nNote that git-import-patches will mark the commit that was HEAD when it was run as refs/patches/upstream-head. This lets you keep track of which commits are from Electron patches (those that come after refs/patches/upstream-head) and which commits are in upstream (those before refs/patches/upstream-head).
When updating an upstream dependency, patches may fail to apply cleanly. Often, the conflict can be resolved automatically by git with a 3-way merge. You can instruct git-import-patches to use the 3-way merge algorithm by passing the -3 argument:
$ cd src/third_party/electron_node\n# If the patch application failed midway through, you can reset it with:\n$ git am --abort\n# And then retry with 3-way merge:\n$ ../../electron/script/git-import-patches -3 ../../electron/patches/node\nIf git-import-patches -3 encounters a merge conflict that it can't resolve automatically, it will pause and allow you to resolve the conflict manually. Once you have resolved the conflict, git add the resolved files and continue to apply the rest of the patches by running git am --continue.
Developers frequently ask about strategies to optimize the performance of Electron applications. Software engineers, consumers, and framework developers do not always agree on one single definition of what \"performance\" means. This document outlines some of the Electron maintainers' favorite ways to reduce the amount of memory, CPU, and disk resources being used while ensuring that your app is responsive to user input and completes operations as quickly as possible. Furthermore, we want all performance strategies to maintain a high standard for your app's security.
\nWisdom and information about how to build performant websites with JavaScript generally applies to Electron apps, too. To a certain extent, resources discussing how to build performant Node.js applications also apply, but be careful to understand that the term \"performance\" means different things for a Node.js backend than it does for an application running on a client.
\nThis list is provided for your convenience – and is, much like our security checklist – not meant to exhaustive. It is probably possible to build a slow Electron app that follows all the steps outlined below. Electron is a powerful development platform that enables you, the developer, to do more or less whatever you want. All that freedom means that performance is largely your responsibility.
\nThe list below contains a number of steps that are fairly straightforward and easy to implement. However, building the most performant version of your app will require you to go beyond a number of steps. Instead, you will have to closely examine all the code running in your app by carefully profiling and measuring. Where are the bottlenecks? When the user clicks a button, what operations take up the brunt of the time? While the app is simply idling, which objects take up the most memory?
\nTime and time again, we have seen that the most successful strategy for building a performant Electron app is to profile the running code, find the most resource-hungry piece of it, and to optimize it. Repeating this seemingly laborious process over and over again will dramatically increase your app's performance. Experience from working with major apps like Visual Studio Code or Slack has shown that this practice is by far the most reliable strategy to improve performance.
\nTo learn more about how to profile your app's code, familiarize yourself with the Chrome Developer Tools. For advanced analysis looking at multiple processes at once, consider the Chrome Tracing tool.
\nChances are that your app could be a little leaner, faster, and generally less resource-hungry if you attempt these steps.
\nBefore adding a Node.js module to your application, examine said module. How many dependencies does that module include? What kind of resources does it need to simply be called in a require() statement? You might find that the module with the most downloads on the NPM package registry or the most stars on GitHub is not in fact the leanest or smallest one available.
The reasoning behind this recommendation is best illustrated with a real-world example. During the early days of Electron, reliable detection of network connectivity was a problem, resulting many apps to use a module that exposed a simple isOnline() method.
That module detected your network connectivity by attempting to reach out to a number of well-known endpoints. For the list of those endpoints, it depended on a different module, which also contained a list of well-known ports. This dependency itself relied on a module containing information about ports, which came in the form of a JSON file with more than 100,000 lines of content. Whenever the module was loaded (usually in a require('module') statement), it would load all its dependencies and eventually read and parse this JSON file. Parsing many thousands lines of JSON is a very expensive operation. On a slow machine it can take up whole seconds of time.
In many server contexts, startup time is virtually irrelevant. A Node.js server that requires information about all ports is likely actually \"more performant\" if it loads all required information into memory whenever the server boots at the benefit of serving requests faster. The module discussed in this example is not a \"bad\" module. Electron apps, however, should not be loading, parsing, and storing in memory information that it does not actually need.
\nIn short, a seemingly excellent module written primarily for Node.js servers running Linux might be bad news for your app's performance. In this particular example, the correct solution was to use no module at all, and to instead use connectivity checks included in later versions of Chromium.
\nWhen considering a module, we recommend that you check:
\nrequire()) itGenerating a CPU profile and a heap memory profile for loading a module can be done with a single command on the command line. In the example below, we're looking at the popular module request.
node --cpu-prof --heap-prof -e \"require('request')\"\nExecuting this command results in a .cpuprofile file and a .heapprofile file in the directory you executed it in. Both files can be analyzed using the Chrome Developer Tools, using the Performance and Memory tabs respectively.
In this example, on the author's machine, we saw that loading request took almost half a second, whereas node-fetch took dramatically less memory and less than 50ms.
If you have expensive setup operations, consider deferring those. Inspect all the work being executed right after the application starts. Instead of firing off all operations right away, consider staggering them in a sequence more closely aligned with the user's journey.
\nIn traditional Node.js development, we're used to putting all our require() statements at the top. If you're currently writing your Electron application using the same strategy and are using sizable modules that you do not immediately need, apply the same strategy and defer loading to a more opportune time.
Loading modules is a surprisingly expensive operation, especially on Windows. When your app starts, it should not make users wait for operations that are currently not necessary.
\nThis might seem obvious, but many applications tend to do a large amount of work immediately after the app has launched - like checking for updates, downloading content used in a later flow, or performing heavy disk I/O operations.
\nLet's consider Visual Studio Code as an example. When you open a file, it will immediately display the file to you without any code highlighting, prioritizing your ability to interact with the text. Once it has done that work, it will move on to code highlighting.
\nLet's consider an example and assume that your application is parsing files in the fictitious .foo format. In order to do that, it relies on the equally fictitious foo-parser module. In traditional Node.js development, you might write code that eagerly loads dependencies:
const fs = require('fs')\nconst fooParser = require('foo-parser')\n\nclass Parser {\n constructor () {\n this.files = fs.readdirSync('.')\n }\n\n getParsedFiles () {\n return fooParser.parse(this.files)\n }\n}\n\nconst parser = new Parser()\n\nmodule.exports = { parser }\nIn the above example, we're doing a lot of work that's being executed as soon as the file is loaded. Do we need to get parsed files right away? Could we do this work a little later, when getParsedFiles() is actually called?
// \"fs\" is likely already being loaded, so the `require()` call is cheap\nconst fs = require('fs')\n\nclass Parser {\n async getFiles () {\n // Touch the disk as soon as `getFiles` is called, not sooner.\n // Also, ensure that we're not blocking other operations by using\n // the asynchronous version.\n this.files = this.files || await fs.readdir('.')\n\n return this.files\n }\n\n async getParsedFiles () {\n // Our fictitious foo-parser is a big and expensive module to load, so\n // defer that work until we actually need to parse files.\n // Since `require()` comes with a module cache, the `require()` call\n // will only be expensive once - subsequent calls of `getParsedFiles()`\n // will be faster.\n const fooParser = require('foo-parser')\n const files = await this.getFiles()\n\n return fooParser.parse(files)\n }\n}\n\n// This operation is now a lot cheaper than in our previous example\nconst parser = new Parser()\n\nmodule.exports = { parser }\nIn short, allocate resources \"just in time\" rather than allocating them all when your app starts.
\nElectron's main process (sometimes called \"browser process\") is special: It is the parent process to all your app's other processes and the primary process the operating system interacts with. It handles windows, interactions, and the communication between various components inside your app. It also houses the UI thread.
\nUnder no circumstances should you block this process and the UI thread with long-running operations. Blocking the UI thread means that your entire app will freeze until the main process is ready to continue processing.
\nThe main process and its UI thread are essentially the control tower for major operations inside your app. When the operating system tells your app about a mouse click, it'll go through the main process before it reaches your window. If your window is rendering a buttery-smooth animation, it'll need to talk to the GPU process about that – once again going through the main process.
\nElectron and Chromium are careful to put heavy disk I/O and CPU-bound operations onto new threads to avoid blocking the UI thread. You should do the same.
\nElectron's powerful multi-process architecture stands ready to assist you with your long-running tasks, but also includes a small number of performance traps.
\n1) For long running CPU-heavy tasks, make use of worker threads, consider moving them to the BrowserWindow, or (as a last resort) spawn a dedicated process.
\n2) Avoid using the synchronous IPC and the remote module as much as possible. While there are legitimate use cases, it is far too easy to unknowingly block the UI thread using the remote module.
3) Avoid using blocking I/O operations in the main process. In short, whenever core Node.js modules (like fs or child_process) offer a synchronous or an asynchronous version, you should prefer the asynchronous and non-blocking variant.
Since Electron ships with a current version of Chrome, you can make use of the latest and greatest features the Web Platform offers to defer or offload heavy operations in a way that keeps your app smooth and responsive.
\nYour app probably has a lot of JavaScript to run in the renderer process. The trick is to execute operations as quickly as possible without taking away resources needed to keep scrolling smooth, respond to user input, or animations at 60fps.
\nOrchestrating the flow of operations in your renderer's code is particularly useful if users complain about your app sometimes \"stuttering\".
\nGenerally speaking, all advice for building performant web apps for modern browsers apply to Electron's renderers, too. The two primary tools at your disposal are currently requestIdleCallback() for small operations and Web Workers for long-running operations.
requestIdleCallback() allows developers to queue up a function to be executed as soon as the process is entering an idle period. It enables you to perform low-priority or background work without impacting the user experience. For more information about how to use it, check out its documentation on MDN.
Web Workers are a powerful tool to run code on a separate thread. There are some caveats to consider – consult Electron's multithreading documentation and the MDN documentation for Web Workers. They're an ideal solution for any operation that requires a lot of CPU power for an extended period of time.
\nOne of Electron's great benefits is that you know exactly which engine will parse your JavaScript, HTML, and CSS. If you're re-purposing code that was written for the web at large, make sure to not polyfill features included in Electron.
\nWhen building a web application for today's Internet, the oldest environments dictate what features you can and cannot use. Even though Electron supports well-performing CSS filters and animations, an older browser might not. Where you could use WebGL, your developers may have chosen a more resource-hungry solution to support older phones.
\nWhen it comes to JavaScript, you may have included toolkit libraries like jQuery for DOM selectors or polyfills like the regenerator-runtime to support async/await.
It is rare for a JavaScript-based polyfill to be faster than the equivalent native feature in Electron. Do not slow down your Electron app by shipping your own version of standard web platform features.
\nOperate under the assumption that polyfills in current versions of Electron are unnecessary. If you have doubts, check caniuse.com and check if the version of Chromium used in your Electron version supports the feature you desire.
\nIn addition, carefully examine the libraries you use. Are they really necessary? jQuery, for example, was such a success that many of its features are now part of the standard JavaScript feature set available.
If you're using a transpiler/compiler like TypeScript, examine its configuration and ensure that you're targeting the latest ECMAScript version supported by Electron.
\nAvoid fetching rarely changing resources from the internet if they could easily be bundled with your application.
\nMany users of Electron start with an entirely web-based app that they're turning into a desktop application. As web developers, we are used to loading resources from a variety of content delivery networks. Now that you are shipping a proper desktop application, attempt to \"cut the cord\" where possible and avoid letting your users wait for resources that never change and could easily be included in your app.
\nA typical example is Google Fonts. Many developers make use of Google's impressive collection of free fonts, which comes with a content delivery network. The pitch is straightforward: Include a few lines of CSS and Google will take care of the rest.
\nWhen building an Electron app, your users are better served if you download the fonts and include them in your app's bundle.
\nIn an ideal world, your application wouldn't need the network to operate at all. To get there, you must understand what resources your app is downloading - and how large those resources are.
\nTo do so, open up the developer tools. Navigate to the Network tab and check the Disable cache option. Then, reload your renderer. Unless your app prohibits such reloads, you can usually trigger a reload by hitting Cmd + R or Ctrl + R with the developer tools in focus.
The tools will now meticulously record all network requests. In a first pass, take stock of all the resources being downloaded, focusing on the larger files first. Are any of them images, fonts, or media files that don't change and could be included with your bundle? If so, include them.
\nAs a next step, enable Network Throttling. Find the drop-down that currently reads Online and select a slower speed such as Fast 3G. Reload your renderer and see if there are any resources that your app is unnecessarily waiting for. In many cases, an app will wait for a network request to complete despite not actually needing the involved resource.
As a tip, loading resources from the Internet that you might want to change without shipping an application update is a powerful strategy. For advanced control over how resources are being loaded, consider investing in Service Workers.
\nAs already pointed out in \"Loading and running code too soon\", calling require() is an expensive operation. If you are able to do so, bundle your application's code into a single file.
Modern JavaScript development usually involves many files and modules. While that's perfectly fine for developing with Electron, we heavily recommend that you bundle all your code into one single file to ensure that the overhead included in calling require() is only paid once when your application loads.
There are numerous JavaScript bundlers out there and we know better than to anger the community by recommending one tool over another. We do however recommend that you use a bundler that is able to handle Electron's unique environment that needs to handle both Node.js and browser environments.
\nAs of writing this article, the popular choices include Webpack, Parcel, and rollup.js.
", "title": "Performance", "description": "" }, "/docs/api/structures/point": { "locale": "de-DE", "slug": "point", "href": "/docs/api/structures/point", "crowdinFileId": "256475", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/point.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "x Numbery NumberNote: Both x and y must be whole integers, when providing a point object as input to an Electron API we will automatically round your x and y values to the nearest whole integer.
data (UploadRawData | UploadFile)[] - The post data to be sent to the new window.contentType String - The content-type header used for the data. One of application/x-www-form-urlencoded or multipart/form-data. Corresponds to the enctype attribute of the submitted HTML form.boundary String (optional) - The boundary used to separate multiple parts of the message. Only valid when contentType is multipart/form-data.Note that keys starting with -- are not currently supported. For example, this will errantly submit as multipart/form-data when nativeWindowOpen is set to false in webPreferences:
<form\n target=\"_blank\"\n method=\"POST\"\n enctype=\"application/x-www-form-urlencoded\"\n action=\"https://postman-echo.com/post\"\n>\n <input type=\"text\" name=\"--theKey\">\n <input type=\"submit\">\n</form>\n\n\nMonitor power state changes.
\n
Prozess: Haupt
\nDas powerMonitor Modul sendet folgende Ereignisse aus:
Emitted when the system is suspending.
\nEmitted when system is resuming.
\nEmitted when the system changes to AC power.
\nEmitted when system changes to battery power.
\nEmitted when the system is about to reboot or shut down. If the event handler invokes e.preventDefault(), Electron will attempt to delay system shutdown in order for the app to exit cleanly. If e.preventDefault() is called, the app should exit as soon as possible by calling something like app.quit().
Emitted when the system is about to lock the screen.
\nEmitted as soon as the systems screen is unlocked.
\nEmitted when a login session is activated. See documentation for more information.
\nEmitted when a login session is deactivated. See documentation for more information.
\nDas Modul powerMonitor verfügt über die folgenden Methoden:
powerMonitor.getSystemIdleState(idleThreshold)idleThreshold IntegerReturns String - The system's current state. Can be active, idle, locked or unknown.
Calculate the system idle state. idleThreshold is the amount of time (in seconds) before considered idle. locked is available on supported systems only.
powerMonitor.getSystemIdleTime()Returns Integer - Idle time in seconds
Calculate system idle time in seconds.
\npowerMonitor.isOnBatteryPower()Returns Boolean - Whether the system is on battery power.
To monitor for changes in this property, use the on-battery and on-ac events.
powerMonitor.onBatteryPowerA Boolean property. True if the system is on battery power.
See powerMonitor.isOnBatteryPower().
\n\nVerhindere, dass das System in den Stromspar-/Schlafmodus geht.
\n
Prozess: Haupt
\nEin Beispiel:
\nconst { powerSaveBlocker } = require('electron')\n\nconst id = powerSaveBlocker.start('prevent-display-sleep')\nconsole.log(powerSaveBlocker.isStarted(id))\n\npowerSaveBlocker.stop(id)\nDas powerSaveBlocker-Modul hat folgende Methoden:
powerSaveBlocker.start(type)type String - Power save blocker type.prevent-app-suspension - Prevent the application from being suspended. Keeps system active but allows screen to be turned off. Example use cases: downloading a file or playing audio.prevent-display-sleep - Prevent the display from going to sleep. Keeps system and screen active. Example use case: playing video.Gibt Integer zurück - Die Blocker-ID, die diesem Power-Blocker zugeordnet ist.
Starts preventing the system from entering lower-power mode. Returns an integer identifying the power save blocker.
\nNote: prevent-display-sleep has higher precedence over prevent-app-suspension. Only the highest precedence type takes effect. In other words, prevent-display-sleep always takes precedence over prevent-app-suspension.
For example, an API calling A requests for prevent-app-suspension, and another calling B requests for prevent-display-sleep. prevent-display-sleep will be used until B stops its request. After that, prevent-app-suspension is used.
powerSaveBlocker.stop(id)id Integer - The power save blocker id returned by powerSaveBlocker.start.Stops the specified power save blocker.
\npowerSaveBlocker.isStarted(id)id Integer - The power save blocker id returned by powerSaveBlocker.start.Returns Boolean - Whether the corresponding powerSaveBlocker has started.
name String - the name of the printer as understood by the OS.displayName String - the name of the printer as shown in Print Preview.description String - a longer description of the printer's type.status Number - the current status of the printer.isDefault Boolean - whether or not a given printer is set as the default printer on the OS.options Object - an object containing a variable number of platform-specific printer information.The number represented by status means different things on different platforms: on Windows its potential values can be found here, and on Linux and macOS they can be found here.
Below is an example of some of the additional options that may be set which may be different on each platform.
\n{\n name: 'Austin_4th_Floor_Printer___C02XK13BJHD4',\n displayName: 'Austin 4th Floor Printer @ C02XK13BJHD4',\n description: 'TOSHIBA ColorMFP',\n status: 3,\n isDefault: false,\n options: {\n copies: '1',\n 'device-uri': 'dnssd://Austin%204th%20Floor%20Printer%20%40%20C02XK13BJHD4._ipps._tcp.local./?uuid=71687f1e-1147-3274-6674-22de61b110bd',\n finishings: '3',\n 'job-cancel-after': '10800',\n 'job-hold-until': 'no-hold',\n 'job-priority': '50',\n 'job-sheets': 'none,none',\n 'marker-change-time': '0',\n 'number-up': '1',\n 'printer-commands': 'ReportLevels,PrintSelfTestPage,com.toshiba.ColourProfiles.update,com.toshiba.EFiling.update,com.toshiba.EFiling.checkPassword',\n 'printer-info': 'Austin 4th Floor Printer @ C02XK13BJHD4',\n 'printer-is-accepting-jobs': 'true',\n 'printer-is-shared': 'false',\n 'printer-is-temporary': 'false',\n 'printer-location': '',\n 'printer-make-and-model': 'TOSHIBA ColorMFP',\n 'printer-state': '3',\n 'printer-state-change-time': '1573472937',\n 'printer-state-reasons': 'offline-report,com.toshiba.snmp.failed',\n 'printer-type': '10531038',\n 'printer-uri-supported': 'ipp://localhost/printers/Austin_4th_Floor_Printer___C02XK13BJHD4',\n system_driverinfo: 'T'\n }\n}\n\n\n\nExtensions to process object.
\n
Electron's process object is extended from the Node.js process object. It adds the following events, properties, and methods:
In sandboxed renderers the process object contains only a subset of the APIs:
crash()hang()getCreationTime()getHeapStatistics()getBlinkMemoryInfo()getProcessMemoryInfo()getSystemMemoryInfo()getSystemVersion()getCPUUsage()getIOCounters()uptime()argvexecPathenvpidarchplattformsandboxedcontextIsolatedtypeversionversionsmaswindowsStorecontextIdEmitted when Electron has loaded its internal initialization script and is beginning to load the web page or the main script.
\nprocess.defaultApp ReadonlyA Boolean. When app is started by being passed as parameter to the default app, this property is true in the main process, otherwise it is undefined.
process.isMainFrame ReadonlyA Boolean, true when the current renderer context is the \"main\" renderer frame. If you want the ID of the current frame you should use webFrame.routingId.
process.mas ReadonlyA Boolean. For Mac App Store build, this property is true, for other builds it is undefined.
process.noAsarA Boolean that controls ASAR support inside your application. Setting this to true will disable the support for asar archives in Node's built-in modules.
process.noDeprecationA Boolean that controls whether or not deprecation warnings are printed to stderr. Setting this to true will silence deprecation warnings. This property is used instead of the --no-deprecation command line flag.
process.resourcesPath ReadonlyA String representing the path to the resources directory.
process.sandboxed ReadonlyA Boolean. When the renderer process is sandboxed, this property is true, otherwise it is undefined.
process.contextIsolated ReadonlyA Boolean that indicates whether the current renderer context has contextIsolation enabled. It is undefined in the main process.
process.throwDeprecationA Boolean that controls whether or not deprecation warnings will be thrown as exceptions. Setting this to true will throw errors for deprecations. This property is used instead of the --throw-deprecation command line flag.
process.traceDeprecationA Boolean that controls whether or not deprecations printed to stderr include their stack trace. Setting this to true will print stack traces for deprecations. This property is instead of the --trace-deprecation command line flag.
process.traceProcessWarningsA Boolean that controls whether or not process warnings printed to stderr include their stack trace. Setting this to true will print stack traces for process warnings (including deprecations). This property is instead of the --trace-warnings command line flag.
process.type ReadonlyA String representing the current process's type, can be:
browser - The main processrenderer - A renderer processworker - In a web workerprocess.versions.chrome ReadonlyA String representing Chrome's version string.
process.versions.electron ReadonlyA String representing Electron's version string.
process.windowsStore ReadonlyA Boolean. If the app is running as a Windows Store app (appx), this property is true, for otherwise it is undefined.
process.contextId ReadonlyA String (optional) representing a globally unique ID of the current JavaScript context. Each frame has its own JavaScript context. When contextIsolation is enabled, the isolated world also has a separate JavaScript context. This property is only available in the renderer process.
Das process Objekt enthält die folgenden Methoden:
process.crash()Causes the main thread of the current process crash.
\nprocess.getCreationTime()Returns Number | null - The number of milliseconds since epoch, or null if the information is unavailable
Indicates the creation time of the application. Die Zeit wird seit der Epoche als Anzahl von Millisekunden dargestellt. It returns null if it is unable to get the process creation time.
\nprocess.getCPUUsage()Returns CPUUsage
process.getIOCounters() Windows LinuxReturns IOCounters
process.getHeapStatistics()Gibt das Object zurück:
totalHeapSize IntegertotalHeapSizeExecutable IntegertotalPhysicalSize IntegertotalAvailableSize IntegerusedHeapSize IntegerheapSizeLimit IntegermallocedMemory IntegerpeakMallocedMemory IntegerdoesZapGarbage BooleanReturns an object with V8 heap statistics. Beachten Sie, dass alle Statistiken in Kilobyte angegeben werden.
\nprocess.getBlinkMemoryInfo()Gibt das Object zurück:
allocated Integer - Size of all allocated objects in Kilobytes.marked Integer - Size of all marked objects in Kilobytes.total Integer - Total allocated space in Kilobytes.Returns an object with Blink memory information. It can be useful for debugging rendering / DOM related memory issues. Note that all values are reported in Kilobytes.
\nprocess.getProcessMemoryInfo()Returns Promise<ProcessMemoryInfo> - Resolves with a ProcessMemoryInfo
Returns an object giving memory usage statistics about the current process. Note that all statistics are reported in Kilobytes. This api should be called after app ready.
\nChromium does not provide residentSet value for macOS. This is because macOS performs in-memory compression of pages that haven't been recently used. As a result the resident set size value is not what one would expect. private memory is more representative of the actual pre-compression memory usage of the process on macOS.
process.getSystemMemoryInfo()Gibt das Object zurück:
total Integer - The total amount of physical memory in Kilobytes available to the system.free Integer - The total amount of memory not being used by applications or disk cache.swapTotal Integer Windows Linux - The total amount of swap memory in Kilobytes available to the system.swapFree Integer Windows Linux - The free amount of swap memory in Kilobytes available to the system.Returns an object giving memory usage statistics about the entire system. Note that all statistics are reported in Kilobytes.
\nprocess.getSystemVersion()Returns String - The version of the host operating system.
Beispiel:
\nconst version = process.getSystemVersion()\nconsole.log(version)\n// On macOS -> '10.13.6'\n// On Windows -> '10.0.17763'\n// On Linux -> '4.15.0-45-generic'\nNote: It returns the actual operating system version instead of kernel version on macOS unlike os.release().
process.takeHeapSnapshot(filePath)filePath String - Path to the output file.Returns Boolean - Indicates whether the snapshot has been created successfully.
Takes a V8 heap snapshot and saves it to filePath.
process.hang()Causes the main thread of the current process hang.
\nprocess.setFdLimit(maxDescriptors) macOS LinuxmaxDescriptors IntegerSets the file descriptor soft limit to maxDescriptors or the OS hard limit, whichever is lower for the current process.
residentSet Integer Linux Windows - The amount of memory currently pinned to actual physical RAM in Kilobytes.private Integer - The amount of memory not shared by other processes, such as JS heap or HTML content in Kilobytes.shared Integer - The amount of memory shared between processes, typically memory consumed by the Electron code itself in Kilobytes.pid Integer - Process id of the process.Typ String - Prozess-Typ. Einer der folgenden Werte:BrowserTabUtilityZygoteSandbox helperGPUPepper PluginPepper Plugin BrokerUnknownserviceName String (optional) - The non-localized name of the process.name String (optional) - The name of the process. Examples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.cpu CPUUsage - CPU usage of the process.creationTime Number - Creation time for this process. The time is represented as number of milliseconds since epoch. Since the pid can be reused after a process dies, it is useful to use both the pid and the creationTime to uniquely identify a process.memory MemoryInfo - Memory information for the process.sandboxed Boolean (optional) macOS Windows - Whether the process is sandboxed on OS level.integrityLevel String (optional) Windows - One of the following values:untrustedlowmediumhighunknownElectron inherits its multi-process architecture from Chromium, which makes the framework architecturally very similar to a modern web browser. In this guide, we'll expound on the conceptual knowledge of Electron that we applied in the minimal quick start app.
\nWeb browsers are incredibly complicated applications. Aside from their primary ability to display web content, they have many secondary responsibilities, such as managing multiple windows (or tabs) and loading third-party extensions.
\nIn the earlier days, browsers usually used a single process for all of this functionality. Although this pattern meant less overhead for each tab you had open, it also meant that one website crashing or hanging would affect the entire browser.
\nTo solve this problem, the Chrome team decided that each tab would render in its own process, limiting the harm that buggy or malicious code on a web page could cause to the app as a whole. A single browser process then controls these processes, as well as the application lifecycle as a whole. This diagram below from the Chrome Comic visualizes this model:
\n
Electron applications are structured very similarly. As an app developer, you control two types of processes: main and renderer. These are analogous to Chrome's own browser and renderer processes outlined above.
\nEach Electron app has a single main process, which acts as the application's entry point. The main process runs in a Node.js environment, meaning it has the ability to require modules and use all of Node.js APIs.
The main process' primary purpose is to create and manage application windows with the BrowserWindow module.
Each instance of the BrowserWindow class creates an application window that loads a web page in a separate renderer process. You can interact with this web content from the main process using the window's webContents object.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\n\n\nNote: A renderer process is also created for web embeds such as the
\nBrowserViewmodule. ThewebContentsobject is also accessible for embedded web content.
Because the BrowserWindow module is an EventEmitter, you can also add handlers for various user events (for example, minimizing or maximizing your window).
When a BrowserWindow instance is destroyed, its corresponding renderer process gets terminated as well.
The main process also controls your application's lifecycle through Electron's app module. This module provides a large set of events and methods that you can use to add custom application behaviour (for instance, programatically quitting your application, modifying the application dock, or showing an About panel).
As a practical example, the app shown in the quick start guide uses app APIs to create a more native application window experience.
// quitting the app when no windows are open on non-macOS platforms\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nTo extend Electron's features beyond being a Chromium wrapper for web contents, the main process also adds custom APIs to interact with the user's operating system. Electron exposes various modules that control native desktop functionality, such as menus, dialogs, and tray icons.
\nFor a full list of Electron's main process modules, check out our API documentation.
\nEach Electron app spawns a separate renderer process for each open BrowserWindow (and each web embed). As its name implies, a renderer is responsible for rendering web content. For all intents and purposes, code ran in renderer processes should behave according to web standards (insofar as Chromium does, at least).
Therefore, all user interfaces and app functionality within a single browser window should be written with the same tools and paradigms that you use on the web.
\nAlthough explaining every web spec is out of scope for this guide, the bare minimum to understand is:
\n<script> elements.Moreover, this also means that the renderer has no direct access to require or other Node.js APIs. In order to directly include NPM modules in the renderer, you must use the same bundler toolchains (for example, webpack or parcel) that you use on the web.
\n\nNote: Renderer processes can be spawned with a full Node.js environment for ease of development. Historically, this used to be the default, but this feature was disabled for security reasons.
\n
At this point, you might be wondering how your renderer process user interfaces can interact with Node.js and Electron's native desktop functionality if these features are only accessible from the main process. In fact, there is no direct way to import Electron's content scripts.
\nA preload script can be attached to the main process in the BrowserWindow constructor's webPreferences option.
const { BrowserWindow } = require('electron')\n//...\nconst win = new BrowserWindow({\n webPreferences: {\n preload: 'path/to/preload.js'\n }\n})\n//...\nBecause the preload script shares a global Window interface with the renderers and can access Node.js APIs, it serves to enhance your renderer by exposing arbitrary APIs in the window global that your web contents can then consume.
Although preload scripts share a window global with the renderer they're attached to, you cannot directly attach any variables from the preload script to window because of the contextIsolation default.
window.myAPI = {\n desktop: true\n}\nconsole.log(window.myAPI)\n// => undefined\nContext Isolation means that preload scripts are isolated from the renderer's main world to avoid leaking any privileged APIs into your web content's code.
\nInstead, use the contextBridge module to accomplish this securely:
const { contextBridge } = require('electron')\n\ncontextBridge.exposeInMainWorld('myAPI', {\n desktop: true\n})\nconsole.log(window.myAPI)\n// => { desktop: true }\nThis feature is incredibly useful for two main purposes:
\nipcRenderer helpers to the renderer, you can use inter-process communication (IPC) to trigger main process tasks from the renderer (and vice-versa).window global that can be used for desktop-only logic on the web client's side.productIdentifier String - The string that identifies the product to the Apple App Store.localizedDescription String - A description of the product.localizedTitle String - The name of the product.contentVersion String - A string that identifies the version of the content.contentLengths Number[] - The total size of the content, in bytes.price Number - The cost of the product in the local currency.formattedPrice String - The locale formatted price of the product.currencyCode String - 3 character code presenting a product's currency based on the ISO 4217 standard.isDownloadable Boolean - A Boolean value that indicates whether the App Store has downloadable content for this product. true if at least one file has been associated with the product.A progress bar enables a window to provide progress information to the user without the need of switching to the window itself.
\nOn Windows, you can use a taskbar button to display a progress bar.
\n![Windows Progress Bar][https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png\\]
\nOn macOS, the progress bar will be displayed as a part of the dock icon.
\n
On Linux, the Unity graphical interface also has a similar feature that allows you to specify the progress bar in the launcher.
\n
\n\nNOTE: on Windows, each window can have its own progress bar, whereas on macOS and Linux (Unity) there can be only one progress bar for the application.
\n
All three cases are covered by the same API - the setProgressBar() method available on an instance of BrowserWindow. To indicate your progress, call this method with a number between 0 and 1. For example, if you have a long-running task that is currently at 63% towards completion, you would call it as setProgressBar(0.63).
Setting the parameter to negative values (e.g. -1) will remove the progress bar. Setting it to a value greater than 1 will indicate an indeterminate progress bar in Windows or clamp to 100% in other operating systems. An indeterminate progress bar remains active but does not show an actual percentage, and is used for situations when you do not know how long an operation will take to complete.
Weitere Informationen können in der API-Dokumentation für mehr Optionen und Modulen gefunden werden.
\nIn this example, we add a progress bar to the main window that increments over time using Node.js timers.
\nconst { app, BrowserWindow } = require('electron')\n\nlet progressInterval\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n\n const INCREMENT = 0.03\n const INTERVAL_DELAY = 100 // ms\n\n let c = 0\n progressInterval = setInterval(() => {\n // update progress bar to next value\n // values between 0 and 1 will show progress, >1 will show indeterminate or stick at 100%\n win.setProgressBar(c)\n\n // increment or reset progress bar\n if (c < 2) c += INCREMENT\n else c = 0\n }, INTERVAL_DELAY)\n}\n\napp.whenReady().then(createWindow)\n\n// before the app is terminated, clear both timers\napp.on('before-quit', () => {\n clearInterval(progressInterval)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nAfter launching the Electron application, the dock (macOS) or taskbar (Windows, Unity) should show a progress bar that starts at zero and progresses through 100% to completion. It should then show indeterminate (Windows) or pin to 100% (other operating systems) briefly and then loop.
\n
For macOS, the progress bar will also be indicated for your application when using Mission Control:
\n
\n\nRegister a custom protocol and intercept existing protocol requests.
\n
Prozess: Haupt
\nAn example of implementing a protocol that has the same effect as the file:// protocol:
const { app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n})\nNote: All methods unless specified can only be used after the ready event of the app module gets emitted.
protocol with a custom partition or sessionA protocol is registered to a specific Electron session object. If you don't specify a session, then your protocol will be applied to the default session that Electron uses. However, if you define a partition or session on your browserWindow's webPreferences, then that window will use a different session and your custom protocol will not work if you just use electron.protocol.XXX.
To have your custom protocol work in combination with a custom session, you need to register it to that session explicitly.
\nconst { session, app, protocol } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const partition = 'persist:example'\n const ses = session.fromPartition(partition)\n\n ses.protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })\n\n mainWindow = new BrowserWindow({ webPreferences: { partition } })\n})\nDas Modul protocol verfügt über die folgenden Methoden:
protocol.registerSchemesAsPrivileged(customSchemes)customSchemes CustomScheme[]Note: This method can only be used before the ready event of the app module gets emitted and can be called only once.
Registers the scheme as standard, secure, bypasses content security policy for resources, allows registering ServiceWorker, supports fetch API, and streaming video/audio. Specify a privilege with the value of true to enable the capability.
An example of registering a privileged scheme, that bypasses Content Security Policy:
\nconst { protocol } = require('electron')\nprotocol.registerSchemesAsPrivileged([\n { scheme: 'foo', privileges: { bypassCSP: true } }\n])\nA standard scheme adheres to what RFC 3986 calls generic URI syntax. For example http and https are standard schemes, while file is not.
Registering a scheme as standard allows relative and absolute resources to be resolved correctly when served. Otherwise the scheme will behave like the file protocol, but without the ability to resolve relative URLs.
For example when you load following page with custom protocol without registering it as standard scheme, the image will not be loaded because non-standard schemes can not recognize relative URLs:
\n<body>\n <img src='test.png'>\n</body>\nRegistering a scheme as standard will allow access to files through the FileSystem API. Otherwise the renderer will throw a security error for the scheme.
\nBy default web storage apis (localStorage, sessionStorage, webSQL, indexedDB, cookies) are disabled for non standard schemes. So in general if you want to register a custom protocol to replace the http protocol, you have to register it as a standard scheme.
Protocols that use streams (http and stream protocols) should set stream: true. The <video> and <audio> HTML elements expect protocols to buffer their responses by default. The stream flag configures those elements to correctly expect streaming responses.
protocol.registerFileProtocol(scheme, handler)scheme Stringhandler Funktionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a file as the response. The handler will be called with request and callback where request is an incoming request for the scheme.
To handle the request, the callback should be called with either the file's path or an object that has a path property, e.g. callback(filePath) or callback({ path: filePath }). The filePath must be an absolute path.
By default the scheme is treated like http:, which is parsed differently from protocols that follow the \"generic URI syntax\" like file:.
protocol.registerBufferProtocol(scheme, handler)scheme Stringhandler Funktionrequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a Buffer as a response.
The usage is the same with registerFileProtocol, except that the callback should be called with either a Buffer object or an object that has the data property.
Beispiel:
\nprotocol.registerBufferProtocol('atom', (request, callback) => {\n callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })\n})\nprotocol.registerStringProtocol(scheme, handler)scheme Stringhandler Funktionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a String as a response.
The usage is the same with registerFileProtocol, except that the callback should be called with either a String or an object that has the data property.
protocol.registerHttpProtocol(scheme, handler)scheme Stringhandler Funktionrequest ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send an HTTP request as a response.
The usage is the same with registerFileProtocol, except that the callback should be called with an object that has the url property.
protocol.registerStreamProtocol(scheme, handler)scheme Stringhandler Funktionrequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully registered
Registers a protocol of scheme that will send a stream as a response.
The usage is the same with registerFileProtocol, except that the callback should be called with either a ReadableStream object or an object that has the data property.
Beispiel:
\nconst { protocol } = require('electron')\nconst { PassThrough } = require('stream')\n\nfunction createStream (text) {\n const rv = new PassThrough() // PassThrough is also a Readable stream\n rv.push(text)\n rv.push(null)\n return rv\n}\n\nprotocol.registerStreamProtocol('atom', (request, callback) => {\n callback({\n statusCode: 200,\n headers: {\n 'content-type': 'text/html'\n },\n data: createStream('<h5>Response</h5>')\n })\n})\nIt is possible to pass any object that implements the readable stream API (emits data/end/error events). For example, here's how a file could be returned:
protocol.registerStreamProtocol('atom', (request, callback) => {\n callback(fs.createReadStream('index.html'))\n})\nprotocol.unregisterProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unregistered
Unregisters the custom protocol of scheme.
protocol.isProtocolRegistered(scheme)scheme StringReturns Boolean - Whether scheme is already registered.
protocol.interceptFileProtocol(scheme, handler)scheme Stringhandler Funktionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler which sends a file as a response.
protocol.interceptStringProtocol(scheme, handler)scheme Stringhandler Funktionrequest ProtocolRequestcallback Functionresponse (String | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler which sends a String as a response.
protocol.interceptBufferProtocol(scheme, handler)scheme Stringhandler Funktionrequest ProtocolRequestcallback Functionresponse (Buffer | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler which sends a Buffer as a response.
protocol.interceptHttpProtocol(scheme, handler)scheme Stringhandler Funktionrequest ProtocolRequestcallback Functionresponse ProtocolResponseReturns Boolean - Whether the protocol was successfully intercepted
Intercepts scheme protocol and uses handler as the protocol's new handler which sends a new HTTP request as a response.
protocol.interceptStreamProtocol(scheme, handler)scheme Stringhandler Funktionrequest ProtocolRequestcallback Functionresponse (ReadableStream | ProtocolResponse)Returns Boolean - Whether the protocol was successfully intercepted
Same as protocol.registerStreamProtocol, except that it replaces an existing protocol handler.
protocol.uninterceptProtocol(scheme)scheme StringReturns Boolean - Whether the protocol was successfully unintercepted
Remove the interceptor installed for scheme and restore its original handler.
protocol.isProtocolIntercepted(scheme)scheme StringReturns Boolean - Whether scheme is already intercepted.
referrer` String\nmethod StringuploadData UploadData[] (optional)headers Record<String, String>error Integer (optional) - When assigned, the request will fail with the error number . For the available error numbers you can use, please see the net error list.statusCode Number (optional) - The HTTP response code, default is 200.charset String (optional) - The charset of response body, default is \"utf-8\".mimeType String (optional) - The MIME type of response body, default is \"text/html\". Setting mimeType would implicitly set the content-type header in response, but if content-type is already set in headers, the mimeType would be ignored.headers Record<string, string | string[]> (optional) - An object containing the response headers. The keys must be String, and values must be either String or Array of String.data (Buffer | String | ReadableStream) (optional) - The response body. When returning stream as response, this is a Node.js readable stream representing the response body. When returning Buffer as response, this is a Buffer. When returning String as response, this is a String. This is ignored for other types of responses.path String (optional) - Path to the file which would be sent as response body. This is only used for file responses.url String (optional) - Download the url and pipe the result as response body. This is only used for URL responses.referrer String (optional) - The referrer URL. This is only used for file and URL responses.method String (optional) - The HTTP method. This is only used for file and URL responses.session Session (optional) - The session used for requesting URL, by default the HTTP request will reuse the current session. Setting session to null would use a random independent session. This is only used for URL responses.uploadData ProtocolResponseUploadData (optional) - The data used as upload data. This is only used for URL responses when method is \"POST\".contentType String - MIME type of the content.data String | Buffer - Content to be sent.Forke das Projekt auf GitHub und clone deinen fork lokal.
\n$ git clone git@github.com:username/electron.git\n$ cd electron\n$ git remote add upstream https://github.com/electron/electron.git\n$ git fetch upstream\nBuild Schritte und Abhängigkeiten unterscheiden sich leicht, abhängig von Deinem Betriebssystem. Lies hier für eine detaillierte Anleitung zum lokalen bauen von Electron Apps:
\n\nNach dem lokalen bauen des Projekts bist du startklar zum machen von Änderungen!
\nTo keep your development environment organized, create local branches to hold your work. These should be branched directly off of the main branch.
$ git checkout -b my-branch -t upstream/main\nMost pull requests opened against the electron/electron repository include changes to either the C/C++ code in the shell/ folder, the JavaScript code in the lib/ folder, the documentation in docs/api/ or tests in the spec/ folder.
Please be sure to run npm run lint from time to time on any code changes to ensure that they follow the project's code style.
See coding style for more information about best practice when modifying code in different parts of the project.
\nIt is recommended to keep your changes grouped logically within individual commits. Many contributors find it easier to review changes that are split across multiple commits. There is no limit to the number of commits in a pull request.
\n$ git add my/changed/files\n$ git commit\nNote that multiple commits often get squashed when they are landed.
\nA good commit message should describe what changed and why. The Electron project uses semantic commit messages to streamline the release process.
\nBefore a pull request can be merged, it must have a pull request title with a semantic prefix.
\nExamples of commit messages with semantic prefixes:
\nfix: don't overwrite prevent_default if default wasn't preventedfeat: add app.isPackaged() methoddocs: app.isDefaultProtocolClient is now available on LinuxCommon prefixes:
\nOther things to keep in mind when writing a commit message:
\nA commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with Major in semantic versioning). A breaking change can be part of commits of any type. e.g., a fix:, feat: & chore: types would all be valid, in addition to any other type.
See conventionalcommits.org for more details.
\nOnce you have committed your changes, it is a good idea to use git rebase (not git merge) to synchronize your work with the main repository.
$ git fetch upstream\n$ git rebase upstream/main\nThis ensures that your working branch has the latest changes from electron/electron main.
Bug fixes and features should always come with tests. A testing guide has been provided to make the process easier. Looking at other tests to see how they should be structured can also help.
\nBefore submitting your changes in a pull request, always run the full test suite. To run the tests:
\n$ npm run test\nMake sure the linter does not report any issues and that all tests pass. Please do not submit patches that fail either check.
\nIf you are updating tests and want to run a single spec to check it:
\n$ npm run test -match=menu\nThe above would only run spec modules matching menu, which is useful for anyone who's working on tests that would otherwise be at the very end of the testing cycle.
Once your commits are ready to go -- with passing tests and linting -- begin the process of opening a pull request by pushing your working branch to your fork on GitHub.
\n$ git push origin my-branch\nFrom within GitHub, opening a new pull request will present you with a template that should be filled out:
\n<!--\nThank you for your pull request. Please provide a description above and review\nthe requirements below.\n\nBug fixes and new features should include tests and possibly benchmarks.\n\nContributors guide: https://github.com/electron/electron/blob/main/CONTRIBUTING.md\n-->\nYou will probably get feedback or requests for changes to your pull request. This is a big part of the submission process so don't be discouraged! Some contributors may sign off on the pull request right away. Others may have detailed comments or feedback. This is a necessary part of the process in order to evaluate whether the changes are correct and necessary.
\nTo make changes to an existing pull request, make the changes to your local branch, add a new commit with those changes, and push those to your fork. GitHub will automatically update the pull request.
\n$ git add my/changed/files\n$ git commit\n$ git push origin my-branch\nThere are a number of more advanced mechanisms for managing commits using git rebase that can be used, but are beyond the scope of this guide.
Feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer on something. If you encounter words or acronyms that seem unfamiliar, refer to this glossary.
\nAll pull requests require approval from a Code Owner of the area you modified in order to land. Whenever a maintainer reviews a pull request they may request changes. These may be small, such as fixing a typo, or may involve substantive changes. Such requests are intended to be helpful, but at times may come across as abrupt or unhelpful, especially if they do not include concrete suggestions on how to change them.
\nTry not to be discouraged. If you feel that a review is unfair, say so or seek the input of another project contributor. Often such comments are the result of a reviewer having taken insufficient time to review and are not ill-intended. Such difficulties can often be resolved with a bit of patience. That said, reviewers should be expected to provide helpful feedback.
\nIn order to land, a pull request needs to be reviewed and approved by at least one Electron Code Owner and pass CI. After that, if there are no objections from other contributors, the pull request can be merged.
\nCongratulations and thanks for your contribution!
\nEvery pull request is tested on the Continuous Integration (CI) system to confirm that it works on Electron's supported platforms.
\nIdeally, the pull request will pass (\"be green\") on all of CI's platforms. This means that all tests pass and there are no linting errors. However, it is not uncommon for the CI infrastructure itself to fail on specific platforms or for so-called \"flaky\" tests to fail (\"be red\"). Each CI failure must be manually inspected to determine the cause.
\nCI starts automatically when you open a pull request, but only core maintainers can restart a CI run. If you believe CI is giving a false negative, ask a maintainer to restart the tests.
", "title": "Pull Requests", "description": "" }, "/docs/tutorial/quick-start": { "locale": "de-DE", "slug": "quick-start", "href": "/docs/tutorial/quick-start", "crowdinFileId": "256237", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/quick-start.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "This guide will step you through the process of creating a barebones Hello World app in Electron, similar to electron/electron-quick-start.
By the end of this tutorial, your app will open a browser window that displays a web page with information about which Chromium, Node.js, and Electron versions are running.
\nTo use Electron, you need to install Node.js. We recommend that you use the latest LTS version available.
\n\nPlease install Node.js using pre-built installers for your platform. You may encounter incompatibility issues with different development tools otherwise.
\n
To check that Node.js was installed correctly, type the following commands in your terminal client:
\nnode -v\nnpm -v\nDie Befehle sollten die entsprechenden Versionen von Node.js und npm ausgeben.
\nNote: Since Electron embeds Node.js into its binary, the version of Node.js running your code is unrelated to the version running on your system.
\nElectron apps follow the same general structure as other Node.js projects. Start by creating a folder and initializing an npm package.
\nmkdir my-electron-app && cd my-electron-app\nnpm init\nThe interactive init command will prompt you to set some fields in your config. There are a few rules to follow for the purposes of this tutorial:
entry point should be main.js.author and description can be any value, but are necessary for app packaging.Your package.json file should look something like this:
{\n \"name\": \"my-electron-app\",\n \"version\": \"1.0.0\",\n \"description\": \"Hello World!\",\n \"main\": \"main.js\",\n \"author\": \"Jane Doe\",\n \"license\": \"MIT\"\n}\nThen, install the electron package into your app's devDependencies.
$ npm install --save-dev electron\n\n\nNote: If you're encountering any issues with installing Electron, please refer to the Advanced Installation guide.
\n
Finally, you want to be able to execute Electron. In the scripts field of your package.json config, add a start command like so:
{\n \"scripts\": {\n \"start\": \"electron .\"\n }\n}\nThis start command will let you open your app in development mode.
npm start\n\n\nNote: This script tells Electron to run on your project's root folder. At this stage, your app will immediately throw an error telling you that it cannot find an app to run.
\n
The entry point of any Electron application is its main script. This script controls the main process, which runs in a full Node.js environment and is responsible for controlling your app's lifecycle, displaying native interfaces, performing privileged operations, and managing renderer processes (more on that later).
During execution, Electron will look for this script in the main field of the app's package.json config, which you should have configured during the app scaffolding step.
To initialize the main script, create an empty file named main.js in the root folder of your project.
\n\nNote: If you run the
\nstartscript again at this point, your app will no longer throw any errors! However, it won't do anything yet because we haven't added any code intomain.js.
Before we can create a window for our application, we need to create the content that will be loaded into it. In Electron, each window displays web contents that can be loaded from either from a local HTML file or a remote URL.
\nFor this tutorial, you will be doing the former. Create an index.html file in the root folder of your project:
\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n </body>\n</html>\n\n\nNote: Looking at this HTML document, you can observe that the version numbers are missing from the body text. We'll manually insert them later using JavaScript.
\n
Now that you have a web page, load it into an application window. To do so, you'll need two Electron modules:
\napp module, which controls your application's event lifecycle.BrowserWindow module, which creates and manages application windows.Because the main process runs Node.js, you can import these as CommonJS modules at the top of your file:
\nconst { app, BrowserWindow } = require('electron')\nThen, add a createWindow() function that loads index.html into a new BrowserWindow instance.
function createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\nNext, call this createWindow() function to open your window.
In Electron, browser windows can only be created after the app module's ready event is fired. You can wait for this event by using the app.whenReady() API. Call createWindow() after whenReady() resolves its Promise.
app.whenReady().then(() => {\n createWindow()\n})\n\n\nNote: At this point, your Electron application should successfully open a window that displays your web page!
\n
Although you can now open a browser window, you'll need some additional boilerplate code to make it feel more native to each platform. Application windows behave differently on each OS, and Electron puts the responsibility on developers to implement these conventions in their app.
\nIn general, you can use the process global's platform attribute to run code specifically for certain operating systems.
On Windows and Linux, exiting all windows generally quits an application entirely.
\nTo implement this, listen for the app module's 'window-all-closed' event, and call app.quit() if the user is not on macOS (darwin).
app.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\nWhereas Linux and Windows apps quit when they have no windows open, macOS apps generally continue running even without any windows open, and activating the app when no windows are available should open a new one.
\nTo implement this feature, listen for the app module's activate event, and call your existing createWindow() method if no browser windows are open.
Because windows cannot be created before the ready event, you should only listen for activate events after your app is initialized. Do this by attaching your event listener from within your existing whenReady() callback.
app.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n\nNote: At this point, your window controls should be fully functional!
\n
Now, the last thing to do is print out the version numbers for Electron and its dependencies onto your web page.
\nAccessing this information is trivial to do in the main process through Node's global process object. However, you can't just edit the DOM from the main process because it has no access to the renderer's document context. They're in entirely different processes!
\n\nNote: If you need a more in-depth look at Electron processes, see the Process Model document.
\n
This is where attaching a preload script to your renderer comes in handy. A preload script runs before the renderer process is loaded, and has access to both renderer globals (e.g. window and document) and a Node.js environment.
Create a new script named preload.js as such:
window.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\nThe above code accesses the Node.js process.versions object and runs a basic replaceText helper function to insert the version numbers into the HTML document.
To attach this script to your renderer process, pass in the path to your preload script to the webPreferences.preload option in your existing BrowserWindow constructor.
// include the Node.js 'path' module at the top of your file\nconst path = require('path')\n\n// modify your existing createWindow() function\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n win.loadFile('index.html')\n}\n// ...\nThere are two Node.js concepts that are used here:
\n__dirname string points to the path of the currently executing script (in this case, your project's root folder).path.join API joins multiple path segments together, creating a combined path string that works across all platforms.We use a path relative to the currently executing JavaScript file so that your relative path will work in both development and packaged mode.
\nAt this point, you might be wondering how to add more functionality to your application.
\nFor any interactions with your web contents, you want to add scripts to your renderer process. Because the renderer runs in a normal web environment, you can add a <script> tag right before your index.html file's closing </body> tag to include any arbitrary scripts you want:
<script src=\"./renderer.js\"></script>\nThe code contained in renderer.js can then use the same JavaScript APIs and tooling you use for typical front-end development, such as using webpack to bundle and minify your code or React to manage your user interfaces.
After following the above steps, you should have a fully functional Electron application that looks like this:
\n
The full code is available below:
\n// main.js\n\n// Modules to control application life and create native browser window\nconst { app, BrowserWindow } = require('electron')\nconst path = require('path')\n\nfunction createWindow () {\n // Create the browser window.\n const mainWindow = new BrowserWindow({\n width: 800,\n height: 600,\n webPreferences: {\n preload: path.join(__dirname, 'preload.js')\n }\n })\n\n // and load the index.html of the app.\n mainWindow.loadFile('index.html')\n\n // Open the DevTools.\n // mainWindow.webContents.openDevTools()\n}\n\n// This method will be called when Electron has finished\n// initialization and is ready to create browser windows.\n// Einige APIs können nur nach dem Auftreten dieses Events genutzt werden.\napp.whenReady().then(() => {\n createWindow()\n\n app.on('activate', function () {\n // On macOS it's common to re-create a window in the app when the\n // dock icon is clicked and there are no other windows open.\n if (BrowserWindow.getAllWindows().length === 0) createWindow()\n })\n})\n\n// Quit when all windows are closed, except on macOS. There, it's common\n// for applications and their menu bar to stay active until the user quits\n// explicitly with Cmd + Q.\napp.on('window-all-closed', function () {\n if (process.platform !== 'darwin') app.quit()\n})\n\n// In this file you can include the rest of your app's specific main process\n// code. Sie können den Code auch \n// auf mehrere Dateien aufteilen und diese hier einbinden.\n// preload.js\n\n// All of the Node.js APIs are available in the preload process.\n// It has the same sandbox as a Chrome extension.\nwindow.addEventListener('DOMContentLoaded', () => {\n const replaceText = (selector, text) => {\n const element = document.getElementById(selector)\n if (element) element.innerText = text\n }\n\n for (const dependency of ['chrome', 'node', 'electron']) {\n replaceText(`${dependency}-version`, process.versions[dependency])\n }\n})\n<!--index.html-->\n\n\n<html>\n <head>\n <meta charset=\"UTF-8\">\n <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->\n <meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <meta http-equiv=\"X-Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'\">\n <title>Hello World!</title>\n </head>\n <body>\n <h1>Hello World!</h1>\n We are using Node.js <span id=\"node-version\"></span>,\n Chromium <span id=\"chrome-version\"></span>,\n and Electron <span id=\"electron-version\"></span>.\n\n <!-- You can also require other files to run in this process -->\n <script src=\"./renderer.js\"></script>\n </body>\n</html>\nTo summarize all the steps we've done:
\nWe bootstrapped a Node.js application and added Electron as a dependency.
\nWe created a main.js script that runs our main process, which controls our app\nand runs in a Node.js environment. In this script, we used Electron's app and\nBrowserWindow modules to create a browser window that displays web content\nin a separate process (the renderer).
In order to access certain Node.js functionality in the renderer, we attached\na preload script to our BrowserWindow constructor.
The fastest way to distribute your newly created app is using\nElectron Forge.
\nAdd Electron Forge as a development dependency of your app, and use its import command to set up\nForge's scaffolding:
```sh npm2yarn\nnpm install --save-dev @electron-forge/cli\nnpx electron-forge import\n\n✔ Checking your system\n✔ Initializing Git Repository\n✔ Writing modified package.json file\n✔ Installing dependencies\n✔ Writing modified package.json file\n✔ Fixing .gitignore\n\nWe have ATTEMPTED to convert your app to be in a format that electron-forge understands.\n\nThanks for using \"electron-forge\"!!!\n```\nCreate a distributable using Forge's make command:
npm run make\n\n> my-electron-app@1.0.0 make /my-electron-app\n> electron-forge make\n\n✔ Checking your system\n✔ Resolving Forge Config\nWe need to package your application before we can make it\n✔ Preparing to Package Application for arch: x64\n✔ Preparing native dependencies\n✔ Packaging Application\nMaking for the following targets: zip\n✔ Making for target: zip - On platform: darwin - For arch: x64\nElectron Forge creates the out folder where your package will be located:
// Example for macOS\nout/\n├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip\n├── ...\n└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app\nBitte nutze die Dokumentation, die mit der Version von Electron übereinstimmt. Die Versionsnummer sollte ein Bestandteil der Seiten-URL sein. Falls nicht, verwenden Sie möglicherweise die Dokumentation einer Development Variante, welche eventuell API Änderungen enthält, die nicht mit Ihrer Electron Version kompatibel sind. Um sich ältere Versionen der Dokumentation anzuschauen, können Sie auf GitHub nach Tag filtern indem Sie das Dropdownmenü \"Switch branches/tags\" öffnen und den Tag auswählen, der mit Ihrer Version übereinstimmt.
\nEs gibt sehr häufig gestellte Fragen. Prüfe das bitte vor dem Erstellen eines Issue:
\nDiese individuellen Tutorials bauen auf den Themen auf, die in dem Handbuch weiter oben diskutiert wurden.
\nSiehe development/README.md
", "title": "Offizielle Anleitungen", "description": "" }, "/docs/development/README": { "locale": "de-DE", "slug": "README", "href": "/docs/development/README", "crowdinFileId": "256127", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/README.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "Dieses Handbuch wendet sich an Entwickler des Electron Projekts. Guides zur App-Entwicklung für Electron finden sie auf /docs/README.md.
\nWindos und macOS bieten die Möglichkeit für Apps, die zuletzt geöffneten Dateien in der Taskbar per JumpList oder dock menu anzuzeigen.
\nJumpList:
\n
Dock Menu einer Anwendung:
\n
const { app, BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n\n win.loadFile('index.html')\n}\n\nconst fileName = 'recently-used.md'\nfs.writeFile(fileName, 'Lorem Ipsum', () => {\n app.addRecentDocument(path.join(__dirname, fileName))\n})\n\napp.whenReady().then(createWindow)\n\napp.on('window-all-closed', () => {\n app.clearRecentDocuments()\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nTo add a file to recent documents, use the app.addRecentDocument API.
\nAfter launching the Electron application, right click the application icon. In this guide, the item is a Markdown file located in the root of the project. You should see recently-used.md added to the list of recent files:
To clear the list of recent documents, use the app.clearRecentDocuments API. In this guide, the list of documents is cleared once all windows have been closed.
\nTo use this feature on Windows, your application has to be registered as a handler of the file type of the document, otherwise the file won't appear in JumpList even after you have added it. You can find everything on registering your application in Application Registration.
\nSobald ein Nutzer auf eine Datei in der JumpList klickt, wird eine neue Instanz Ihrer Anwendung gestartet mit dem Pfad der Datei als Befehlszeilenargument.
\nYou can add menu items to access and clear recent documents by adding the following code snippet to your menu template:
\n{\n \"submenu\":[\n {\n \"label\":\"Open Recent\",\n \"role\":\"recentdocuments\",\n \"submenu\":[\n {\n \"label\":\"Clear Recent\",\n \"role\":\"clearrecentdocuments\"\n }\n ]\n }\n ]\n}\nMake sure the application menu is added after the 'ready' event and not before, or the menu item will be disabled:
const { app, Menu } = require('electron')\n\nconst template = [\n // Menu template here\n]\nconst menu = Menu.buildFromTemplate(template)\n\napp.whenReady().then(() => {\n Menu.setApplicationMenu(menu)\n})\n
Sobald eine Datei vom Menu der zuletzt hinzugefügten Dateien angefordert wird, so wird dafür das open-file-Event des app-Moduls ausgeworfen.
x Number - The x coordinate of the origin of the rectangle (must be an integer).y Number - The y coordinate of the origin of the rectangle (must be an integer).width Number - The width of the rectangle (must be an integer).height Number - The height of the rectangle (must be an integer).url String - HTTP Referrer URL.policy String - Can be default, unsafe-url, no-referrer-when-downgrade, no-referrer, origin, strict-origin-when-cross-origin, same-origin or strict-origin. See the Referrer-Policy spec for more details on the meaning of these values.Read-Eval-Print-Loop (REPL) is a simple, interactive computer programming environment that takes single user inputs (i.e. single expressions), evaluates them, and returns the result to the user.
\nElectron exposes the Node.js repl module through the --interactive CLI flag. Assuming you have electron installed as a local project dependency, you should be able to access the REPL with the following command:
./node_modules/.bin/electron --interactive\nNote: electron --interactive is not available on Windows (see electron/electron#5776 for more details).
You can use the DevTools Console tab to get a REPL for any renderer process. To learn more, read the Chrome documentation.
", "title": "REPL", "description": "" }, "/docs/tutorial/represented-file": { "locale": "de-DE", "slug": "represented-file", "href": "/docs/tutorial/represented-file", "crowdinFileId": "256243", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/represented-file.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "On macOS, you can set a represented file for any window in your application. The represented file's icon will be shown in the title bar, and when users Command-Click or Control-Click, a popup with a path to the file will be shown.
\n\nNOTE: The screenshot above is an example where this feature is used to indicate the currently opened file in the Atom text editor.
\n
You can also set the edited state for a window so that the file icon can indicate whether the document in this window has been modified.
\nTo set the represented file of window, you can use the BrowserWindow.setRepresentedFilename and BrowserWindow.setDocumentEdited APIs.
\nconst { app, BrowserWindow } = require('electron')\nconst os = require('os');\n\nfunction createWindow () {\n const win = new BrowserWindow({\n width: 800,\n height: 600\n })\n}\n\napp.whenReady().then(() => {\n const win = new BrowserWindow()\n\n win.setRepresentedFilename(os.homedir())\n win.setDocumentEdited(true)\n})\n\napp.on('window-all-closed', () => {\n if (process.platform !== 'darwin') {\n app.quit()\n }\n})\n\napp.on('activate', () => {\n if (BrowserWindow.getAllWindows().length === 0) {\n createWindow()\n }\n})\nAfter launching the Electron application, click on the title with Command or Control key pressed. You should see a popup with the represented file at the top. In this guide, this is the current user's home directory:
\n\nAllows access to simple encryption and decryption of strings for storage on the local machine.
\n
Prozess: Haupt
\nThis module protects data stored on disk from being accessed by other applications or users with full disk access.
\nNote that on Mac, access to the system Keychain is required and these calls can block the current thread to collect user input. The same is true for Linux, if a password management tool is available.
\nDas Modul safeStorage verfügt über die folgenden Methoden:
safeStorage.isEncryptionAvailable()Returns Boolean - Whether encryption is available.
On Linux, returns true if the secret key is available. On MacOS, returns true if Keychain is available. On Windows, returns true with no other preconditions.
\nsafeStorage.encryptString(plainText)plainText ZeichenketteReturns Buffer - An array of bytes representing the encrypted string.
This function will throw an error if encryption fails.
\nsafeStorage.decryptString(encrypted)encrypted PufferReturns String - the decrypted string. Decrypts the encrypted buffer obtained with safeStorage.encryptString back into a string.
This function will throw an error if decryption fails.
", "title": "safeStorage", "description": "Allows access to simple encryption and decryption of strings for storage on the local machine." }, "/docs/tutorial/sandbox": { "locale": "de-DE", "slug": "sandbox", "href": "/docs/tutorial/sandbox", "crowdinFileId": "256245", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/sandbox.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "One key security feature in Chromium is that processes can be executed within a sandbox. The sandbox limits the harm that malicious code can cause by limiting access to most system resources — sandboxed processes can only freely use CPU cycles and memory. In order to perform operations requiring additional privilege, sandboxed processes use dedicated communication channels to delegate tasks to more privileged processes.
\nIn Chromium, sandboxing is applied to most processes other than the main process. This includes renderer processes, as well as utility processes such as the audio service, the GPU service and the network service.
\nSee Chromium's Sandbox design document for more information.
\nElectron comes with a mixed sandbox environment, meaning sandboxed processes can run alongside privileged ones. By default, renderer processes are not sandboxed, but utility processes are. Note that as in Chromium, the main (browser) process is privileged and cannot be sandboxed.
\nHistorically, this mixed sandbox approach was established because having Node.js available in the renderer is an extremely powerful tool for app developers. Unfortunately, this feature is also an equally massive security vulnerability.
\nTheoretically, unsandboxed renderers are not a problem for desktop applications that only display trusted code, but they make Electron less secure than Chromium for displaying untrusted web content. However, even purportedly trusted code may be dangerous — there are countless attack vectors that malicious actors can use, from cross-site scripting to content injection to man-in-the-middle attacks on remotely loaded websites, just to name a few. For this reason, we recommend enabling renderer sandboxing for the vast majority of cases under an abundance of caution.
\n\nNote that there is an active discussion in the issue tracker to enable renderer sandboxing by default. See #28466) for details.
\nSandboxed processes in Electron behave mostly in the same way as Chromium's do, but Electron has a few additional concepts to consider because it interfaces with Node.js.
\nWhen renderer processes in Electron are sandboxed, they behave in the same way as a regular Chrome renderer would. A sandboxed renderer won't have a Node.js environment initialized.
\n\nTherefore, when the sandbox is enabled, renderer processes can only perform privileged tasks (such as interacting with the filesystem, making changes to the system, or spawning subprocesses) by delegating these tasks to the main process via inter-process communication (IPC).
\nIn order to allow renderer processes to communicate with the main process, preload scripts attached to sandboxed renderers will still have a polyfilled subset of Node.js APIs available. A require function similar to Node's require module is exposed, but can only import a subset of Electron and Node's built-in modules:
electron (only renderer process modules)ereignissetimersurlIn addition, the preload script also polyfills certain Node.js primitives as globals:
\nBufferprocessclearImmediatesetImmediateBecause the require function is a polyfill with limited functionality, you will not be able to use CommonJS modules to separate your preload script into multiple files. If you need to split your preload code, use a bundler such as webpack or Parcel.
Note that because the environment presented to the preload script is substantially more privileged than that of a sandboxed renderer, it is still possible to leak privileged APIs to untrusted code running in the renderer process unless contextIsolation is enabled.
In Electron, renderer sandboxing can be enabled on a per-process basis with the sandbox: true preference in the BrowserWindow constructor.
// main.js\napp.whenReady().then(() => {\n const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n })\n win.loadURL('https://google.com')\n})\nIf you want to force sandboxing for all renderers, you can also use the app.enableSandbox API. Note that this API has to be called before the app's ready event.
// main.js\napp.enableSandbox()\napp.whenReady().then(() => {\n // no need to pass `sandbox: true` since `app.enableSandbox()` was called.\n const win = new BrowserWindow()\n win.loadURL('https://google.com')\n})\nYou can also disable Chromium's sandbox entirely with the --no-sandbox CLI flag, which will disable the sandbox for all processes (including utility processes). We highly recommend that you only use this flag for testing purposes, and never in production.
Note that the sandbox: true option will still disable the renderer's Node.js environment.
Rendering untrusted content in Electron is still somewhat uncharted territory, though some apps are finding success (e.g. Beaker Browser). Our goal is to get as close to Chrome as we can in terms of the security of sandboxed content, but ultimately we will always be behind due to a few fundamental issues:
\nWhile we make our best effort to backport Chromium security fixes to older versions of Electron, we do not make a guarantee that every fix will be backported. Your best chance at staying secure is to be on the latest stable version of Electron.
", "title": "Process-Sandboxing", "description": "" }, "/docs/api/screen": { "locale": "de-DE", "slug": "screen", "href": "/docs/api/screen", "crowdinFileId": "256361", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/screen.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRetrieve information about screen size, displays, cursor position, etc.
\n
Prozess: Haupt
\nThis module cannot be used until the ready event of the app module is emitted.
screen ist ein EventEmitter.
Note: In the renderer / DevTools, window.screen is a reserved DOM property, so writing let { screen } = require('electron') will not work.
An example of creating a window that fills the whole screen:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\napp.whenReady().then(() => {\n const { width, height } = screen.getPrimaryDisplay().workAreaSize\n win = new BrowserWindow({ width, height })\n win.loadURL('https://github.com')\n})\nAnother example of creating a window in the external display:
\nconst { app, BrowserWindow, screen } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n const displays = screen.getAllDisplays()\n const externalDisplay = displays.find((display) => {\n return display.bounds.x !== 0 || display.bounds.y !== 0\n })\n\n if (externalDisplay) {\n win = new BrowserWindow({\n x: externalDisplay.bounds.x + 50,\n y: externalDisplay.bounds.y + 50\n })\n win.loadURL('https://github.com')\n }\n})\nDas screen Modul sendet folgende Ereignisse aus:
Kehrt zurück:
\nevent EventnewDisplay DisplayEmitted when newDisplay has been added.
Kehrt zurück:
\nevent EventoldDisplay DisplayEmitted when oldDisplay has been removed.
Kehrt zurück:
\nevent Eventdisplay DisplaychangedMetrics String[]Emitted when one or more metrics change in a display. The changedMetrics is an array of strings that describe the changes. Possible changes are bounds, workArea, scaleFactor and rotation.
Das Modul screen verfügt über die folgenden Methoden:
screen.getCursorScreenPoint()Returns Point
The current absolute position of the mouse pointer.
\nNote: The return value is a DIP point, not a screen physical point.
\nscreen.getPrimaryDisplay()Returns Display - The primary display.
screen.getAllDisplays()Returns Display[] - An array of displays that are currently available.
screen.getDisplayNearestPoint(point)point PointReturns Display - The display nearest the specified point.
screen.getDisplayMatching(rect)rect RectangleReturns Display - The display that most closely intersects the provided bounds.
screen.screenToDipPoint(point) Windowspoint PointReturns Point
Converts a screen physical point to a screen DIP point. The DPI scale is performed relative to the display containing the physical point.
\nscreen.dipToScreenPoint(point) Windowspoint PointReturns Point
Converts a screen DIP point to a screen physical point. The DPI scale is performed relative to the display containing the DIP point.
\nscreen.screenToDipRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleGibt Rectangle zurück
Converts a screen physical rect to a screen DIP rect. The DPI scale is performed relative to the display nearest to window. If window is null, scaling will be performed to the display nearest to rect.
screen.dipToScreenRect(window, rect) Windowswindow BrowserWindow | nullrect RectangleGibt Rectangle zurück
Converts a screen DIP rect to a screen physical rect. The DPI scale is performed relative to the display nearest to window. If window is null, scaling will be performed to the display nearest to rect.
label String (optional) - The text to appear in this item.icon NativeImage (optional) - The image to appear in this item.Als Webentwickler genießen wir normalerweise das starke Sicherheitsnetz des Browsers - Die Risiken, die mit dem von uns geschriebenen Code verbunden sind, sind relativ gering. Unseren Websites werden in einer Sandbox mit begrenzten Befugnissen ausgeführt und wir vertrauen darauf, dass unsere Benutzer einen Browser verwenden, der von einem großen Team von Ingenieuren entwickelt wurde und der in der Lage ist, schnell auf neu entdeckte Sicherheitsbedrohungen zu reagieren.
\nBei der Arbeit mit Electron ist es wichtig zu verstehen, dass Electron kein Webbrowser ist. Es erlaubt Ihnen, funktionstüchtige Desktop-Anwendungen mit vertrauten Web-Technologien zu erstellen, aber Ihr Code hat viel mehr Kraft. JavaScript kann auf das Dateisystem, die Benutzer-Shell und einiges mehr zugreifen. Dies erlaubt Ihnen, hochqualitative native Anwendungen zu erstellen, aber die inhärenten Sicherheitsrisiken skalieren mit den zusätzlichen Befugnissen, die Ihrem Code gewährt werden.
\nVor diesem Hintergrund sollten Sie sich bewusst sein, dass die Anzeige willkürlicher Inhalte aus nicht vertrauenswürdigen Quellen ein ernstes Sicherheitsrisiko darstellt, dass Electron nicht vollständig verhindern kann. Tatsächlich werden die beliebtesten Electron-Apps (Atom, Slack, Visual Studio Code, etc) in erster Linie lokale Inhalte anzeigen (oder vertrauenswürdige und sichere Remote-Inhalte ohne Node-Integration) – wenn Ihre Anwendung jedoch Code aus einer Online-Quelle ausführt, liegt es in Ihrer Verantwortung sicherzustellen, dass der Code nicht bösartig ist.
\nInformationen dazu, wie sie eine Electron-Sicherheitslücke richtig melden können, finden Sie unter SECURITY.md
\nElectron keeps up to date with alternating Chromium releases. For more information, see the Electron Release Cadence blog post.
\nIt is important to remember that the security of your Electron application is the result of the overall security of the framework foundation (Chromium, Node.js), Electron itself, all NPM dependencies and your code. As such, it is your responsibility to follow a few important best practices:
\nKeep your application up-to-date with the latest Electron framework release. When releasing your product, you’re also shipping a bundle composed of Electron, Chromium shared library and Node.js. Vulnerabilities affecting these components may impact the security of your application. By updating Electron to the latest version, you ensure that critical vulnerabilities (such as nodeIntegration bypasses) are already patched and cannot be exploited in your application. For more information, see \"Use a current version of Electron\".
\nEvaluate your dependencies. While NPM provides half a million reusable packages, it is your responsibility to choose trusted 3rd-party libraries. If you use outdated libraries affected by known vulnerabilities or rely on poorly maintained code, your application security could be in jeopardy.
\nAdopt secure coding practices. The first line of defense for your application is your own code. Common web vulnerabilities, such as Cross-Site Scripting (XSS), have a higher security impact on Electron applications hence it is highly recommended to adopt secure software development best practices and perform security testing.
\nA security issue exists whenever you receive code from an untrusted source (e.g. a remote server) and execute it locally. As an example, consider a remote website being displayed inside a default BrowserWindow. If an attacker somehow manages to change said content (either by attacking the source directly, or by sitting between your app and the actual destination), they will be able to execute native code on the user's machine.
\n\n⚠️ Under no circumstances should you load and execute remote code with Node.js integration enabled. Instead, use only local files (packaged together with your application) to execute Node.js code. To display remote content, use the
\n<webview>tag orBrowserView, make sure to disable thenodeIntegrationand enablecontextIsolation.
From Electron 2.0 on, developers will see warnings and recommendations printed to the developer console. They only show up when the binary's name is Electron, indicating that a developer is currently looking at the console.
\nYou can force-enable or force-disable these warnings by setting ELECTRON_ENABLE_SECURITY_WARNINGS or ELECTRON_DISABLE_SECURITY_WARNINGS on either process.env or the window object.
You should at least follow these steps to improve the security of your application:
\nses.setPermissionRequestHandler() in all sessions that load remote contentwebSecurityContent-Security-Policy and use restrictive rules (i.e. script-src 'self')allowRunningInsecureContent to trueenableBlinkFeatures<webview>: Do not use allowpopups<webview>: Verify options and paramsopenExternal with untrusted contentTo automate the detection of misconfigurations and insecure patterns, it is possible to use electronegativity. For additional details on potential weaknesses and implementation bugs when developing applications using Electron, please refer to this guide for developers and auditors
\nAny resources not included with your application should be loaded using a secure protocol like HTTPS. In other words, do not use insecure protocols like HTTP. Similarly, we recommend the use of WSS over WS, FTPS over FTP, and so on.
HTTPS has three main benefits:
1) It authenticates the remote server, ensuring your app connects to the correct host instead of an impersonator. 2) It ensures data integrity, asserting that the data was not modified while in transit between your application and the host. 3) It encrypts the traffic between your user and the destination host, making it more difficult to eavesdrop on the information sent between your app and the host.
\n// Schlecht\nbrowserWindow.loadURL('http://example.com')\n\n// Gut\nbrowserWindow.loadURL('https://example.com')\n<!-- Schlecht -->\n<script crossorigin src=\"http://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"http://example.com/style.css\">\n\n<!-- Gut -->\n<script crossorigin src=\"https://example.com/react.js\"></script>\n<link rel=\"stylesheet\" href=\"https://example.com/style.css\">\nThis recommendation is the default behavior in Electron since 5.0.0.
\nIt is paramount that you do not enable Node.js integration in any renderer (BrowserWindow, BrowserView, or <webview>) that loads remote content. The goal is to limit the powers you grant to remote content, thus making it dramatically more difficult for an attacker to harm your users should they gain the ability to execute JavaScript on your website.
After this, you can grant additional permissions for specific hosts. For example, if you are opening a BrowserWindow pointed at https://example.com/, you can give that website exactly the abilities it needs, but no more.
A cross-site-scripting (XSS) attack is more dangerous if an attacker can jump out of the renderer process and execute code on the user's computer. Cross-site-scripting attacks are fairly common - and while an issue, their power is usually limited to messing with the website that they are executed on. Disabling Node.js integration helps prevent an XSS from being escalated into a so-called \"Remote Code Execution\" (RCE) attack.
\n// Bad\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n nodeIntegration: true,\n nodeIntegrationInWorker: true\n }\n})\n\nmainWindow.loadURL('https://example.com')\n// Good\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n preload: path.join(app.getAppPath(), 'preload.js')\n }\n})\n\nmainWindow.loadURL('https://example.com')\n<!-- Schlecht -->\n<webview nodeIntegration src=\"page.html\"></webview>\n\n<!-- Gut -->\n<webview src=\"page.html\"></webview>\nWhen disabling Node.js integration, you can still expose APIs to your website that do consume Node.js modules or features. Preload scripts continue to have access to require and other Node.js features, allowing developers to expose a custom API to remotely loaded content.
In the following example preload script, the later loaded website will have access to a window.readConfig() method, but no Node.js features.
const { readFileSync } = require('fs')\n\nwindow.readConfig = function () {\n const data = readFileSync('./config.json')\n return data\n}\nContext isolation is an Electron feature that allows developers to run code in preload scripts and in Electron APIs in a dedicated JavaScript context. In practice, that means that global objects like Array.prototype.push or JSON.parse cannot be modified by scripts running in the renderer process.
Electron uses the same technology as Chromium's Content Scripts to enable this behavior.
\nEven when nodeIntegration: false is used, to truly enforce strong isolation and prevent the use of Node primitives contextIsolation must also be used.
For more information on what contextIsolation is and how to enable it please see our dedicated Context Isolation document.
Sandboxing is a Chromium feature that uses the operating system to significantly limit what renderer processes have access to. You should enable the sandbox in all renderers. Loading, reading or processing any untrusted content in an unsandboxed process, including the main process, is not advised.
\nWhen creating a window, pass the sandbox: true option in webPreferences:
const win = new BrowserWindow({\n webPreferences: {\n sandbox: true\n }\n})\nYou may have seen permission requests while using Chrome: They pop up whenever the website attempts to use a feature that the user has to manually approve ( like notifications).
\nThe API is based on the Chromium permissions API and implements the same types of permissions.
\nBy default, Electron will automatically approve all permission requests unless the developer has manually configured a custom handler. While a solid default, security-conscious developers might want to assume the very opposite.
\nconst { session } = require('electron')\n\nsession\n .fromPartition('some-partition')\n .setPermissionRequestHandler((webContents, permission, callback) => {\n const url = webContents.getURL()\n\n if (permission === 'notifications') {\n // Approves the permissions request\n callback(true)\n }\n\n // Verify URL\n if (!url.startsWith('https://example.com/')) {\n // Denies the permissions request\n return callback(false)\n }\n })\nRecommendation is Electron's default
\nYou may have already guessed that disabling the webSecurity property on a renderer process (BrowserWindow, BrowserView, or <webview>) disables crucial security features.
Do not disable webSecurity in production applications.
Disabling webSecurity will disable the same-origin policy and set allowRunningInsecureContent property to true. In other words, it allows the execution of insecure code from different domains.
// Schlecht\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n webSecurity: false\n }\n})\n// Gut\nconst mainWindow = new BrowserWindow()\n<!-- Schlecht -->\n<webview disablewebsecurity src=\"page.html\"></webview>\n\n<!-- Gut -->\n<webview src=\"page.html\"></webview>\nA Content Security Policy (CSP) is an additional layer of protection against cross-site-scripting attacks and data injection attacks. We recommend that they be enabled by any website you load inside Electron.
\nCSP allows the server serving content to restrict and control the resources Electron can load for that given web page. https://example.com should be allowed to load scripts from the origins you defined while scripts from https://evil.attacker.com should not be allowed to run. Defining a CSP is an easy way to improve your application's security.
The following CSP will allow Electron to execute scripts from the current website and from apis.example.com.
// Schlecht\nContent-Security-Policy: '*'\n\n// Gut\nContent-Security-Policy: script-src 'self' https://apis.example.com\nElectron respects the Content-Security-Policy HTTP header which can be set using Electron's webRequest.onHeadersReceived handler:
const { session } = require('electron')\n\nsession.defaultSession.webRequest.onHeadersReceived((details, callback) => {\n callback({\n responseHeaders: {\n ...details.responseHeaders,\n 'Content-Security-Policy': ['default-src \\'none\\'']\n }\n })\n})\nCSP's preferred delivery mechanism is an HTTP header, however it is not possible to use this method when loading a resource using the file:// protocol. It can be useful in some cases, such as using the file:// protocol, to set a policy on a page directly in the markup using a <meta> tag:
<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'\">\nallowRunningInsecureContent nicht auf trueRecommendation is Electron's default
\nBy default, Electron will not allow websites loaded over HTTPS to load and execute scripts, CSS, or plugins from insecure sources (HTTP). Setting the property allowRunningInsecureContent to true disables that protection.
Loading the initial HTML of a website over HTTPS and attempting to load subsequent resources via HTTP is also known as \"mixed content\".
Loading content over HTTPS assures the authenticity and integrity of the loaded resources while encrypting the traffic itself. See the section on only displaying secure content for more details.
// Schlecht\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n allowRunningInsecureContent: true\n }\n})\n// Gut\nconst mainWindow = new BrowserWindow({})\nRecommendation is Electron's default
\nAdvanced users of Electron can enable experimental Chromium features using the experimentalFeatures property.
Experimental features are, as the name suggests, experimental and have not been enabled for all Chromium users. Furthermore, their impact on Electron as a whole has likely not been tested.
\nLegitimate use cases exist, but unless you know what you are doing, you should not enable this property.
\n// Schlecht\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n experimentalFeatures: true\n }\n})\n// Gut\nconst mainWindow = new BrowserWindow({})\nenableBlinkFeaturesRecommendation is Electron's default
\nBlink is the name of the rendering engine behind Chromium. As with experimentalFeatures, the enableBlinkFeatures property allows developers to enable features that have been disabled by default.
Generally speaking, there are likely good reasons if a feature was not enabled by default. Legitimate use cases for enabling specific features exist. As a developer, you should know exactly why you need to enable a feature, what the ramifications are, and how it impacts the security of your application. Under no circumstances should you enable features speculatively.
\n// Schlecht\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n enableBlinkFeatures: 'ExecCommandInJavaScript'\n }\n})\n// Gut\nconst mainWindow = new BrowserWindow()\nallowpopupsRecommendation is Electron's default
\nIf you are using <webview>, you might need the pages and scripts loaded in your <webview> tag to open new windows. The allowpopups attribute enables them to create new BrowserWindows using the window.open() method. <webview> tags are otherwise not allowed to create new windows.
If you do not need popups, you are better off not allowing the creation of new BrowserWindows by default. This follows the principle of minimally required access: Don't let a website create new popups unless you know it needs that feature.
<!-- Schlecht -->\n<webview allowpopups src=\"page.html\"></webview>\n\n<!-- Gut -->\n<webview src=\"page.html\"></webview>\nA WebView created in a renderer process that does not have Node.js integration enabled will not be able to enable integration itself. However, a WebView will always create an independent renderer process with its own webPreferences.
It is a good idea to control the creation of new <webview> tags from the main process and to verify that their webPreferences do not disable security features.
Since <webview> live in the DOM, they can be created by a script running on your website even if Node.js integration is otherwise disabled.
Electron enables developers to disable various security features that control a renderer process. In most cases, developers do not need to disable any of those features - and you should therefore not allow different configurations for newly created <webview> tags.
Before a <webview> tag is attached, Electron will fire the will-attach-webview event on the hosting webContents. Use the event to prevent the creation of webViews with possibly insecure options.
app.on('web-contents-created', (event, contents) => {\n contents.on('will-attach-webview', (event, webPreferences, params) => {\n // Strip away preload scripts if unused or verify their location is legitimate\n delete webPreferences.preload\n delete webPreferences.preloadURL\n\n // Disable Node.js integration\n webPreferences.nodeIntegration = false\n\n // Verify URL being loaded\n if (!params.src.startsWith('https://example.com/')) {\n event.preventDefault()\n }\n })\n})\nAgain, this list merely minimizes the risk, it does not remove it. If your goal is to display a website, a browser will be a more secure option.
\nIf your app has no need to navigate or only needs to navigate to known pages, it is a good idea to limit navigation outright to that known scope, disallowing any other kinds of navigation.
\nNavigation is a common attack vector. If an attacker can convince your app to navigate away from its current page, they can possibly force your app to open web sites on the Internet. Even if your webContents are configured to be more secure (like having nodeIntegration disabled or contextIsolation enabled), getting your app to open a random web site will make the work of exploiting your app a lot easier.
A common attack pattern is that the attacker convinces your app's users to interact with the app in such a way that it navigates to one of the attacker's pages. This is usually done via links, plugins, or other user-generated content.
\nIf your app has no need for navigation, you can call event.preventDefault() in a will-navigate handler. If you know which pages your app might navigate to, check the URL in the event handler and only let navigation occur if it matches the URLs you're expecting.
We recommend that you use Node's parser for URLs. Simple string comparisons can sometimes be fooled - a startsWith('https://example.com') test would let https://example.com.attacker.com through.
const URL = require('url').URL\n\napp.on('web-contents-created', (event, contents) => {\n contents.on('will-navigate', (event, navigationUrl) => {\n const parsedUrl = new URL(navigationUrl)\n\n if (parsedUrl.origin !== 'https://example.com') {\n event.preventDefault()\n }\n })\n})\nIf you have a known set of windows, it's a good idea to limit the creation of additional windows in your app.
\nMuch like navigation, the creation of new webContents is a common attack vector. Attackers attempt to convince your app to create new windows, frames, or other renderer processes with more privileges than they had before; or with pages opened that they couldn't open before.
If you have no need to create windows in addition to the ones you know you'll need to create, disabling the creation buys you a little bit of extra security at no cost. This is commonly the case for apps that open one BrowserWindow and do not need to open an arbitrary number of additional windows at runtime.
webContents will delegate to its window open handler before creating new windows. The handler will receive, amongst other parameters, the url the window was requested to open and the options used to create it. We recommend that you register a handler to monitor the creation of windows, and deny any unexpected window creation.
const { shell } = require('electron')\n\napp.on('web-contents-created', (event, contents) => {\n contents.setWindowOpenHandler(({ url }) => {\n // In this example, we'll ask the operating system\n // to open this event's url in the default browser.\n //\n // See the following item for considerations regarding what\n // URLs should be allowed through to shell.openExternal.\n if (isSafeForExternalOpen(url)) {\n setImmediate(() => {\n shell.openExternal(url)\n })\n }\n\n return { action: 'deny' }\n })\n})\nopenExternal with untrusted contentShell's openExternal allows opening a given protocol URI with the desktop's native utilities. On macOS, for instance, this function is similar to the open terminal command utility and will open the specific application based on the URI and filetype association.
Improper use of openExternal can be leveraged to compromise the user's host. When openExternal is used with untrusted content, it can be leveraged to execute arbitrary commands.
// Bad\nconst { shell } = require('electron')\nshell.openExternal(USER_CONTROLLED_DATA_HERE)\n// Good\nconst { shell } = require('electron')\nshell.openExternal('https://example.com/index.html')\nYou should strive for always using the latest available version of Electron. Whenever a new major version is released, you should attempt to update your app as quickly as possible.
\nAn application built with an older version of Electron, Chromium, and Node.js is an easier target than an application that is using more recent versions of those components. Generally speaking, security issues and exploits for older versions of Chromium and Node.js are more widely available.
\nBoth Chromium and Node.js are impressive feats of engineering built by thousands of talented developers. Given their popularity, their security is carefully tested and analyzed by equally skilled security researchers. Many of those researchers disclose vulnerabilities responsibly, which generally means that researchers will give Chromium and Node.js some time to fix issues before publishing them. Your application will be more secure if it is running a recent version of Electron (and thus, Chromium and Node.js) for which potential security issues are not as widely known.
", "title": "Sicherheit, native Fähigkeiten und Ihre eigene Verantwortung", "description": "⚠️ Under no circumstances should you load and execute remote code with Node.js integration enabled. Instead, use only local files (packaged together with your application) to execute Node.js code. To display remote content, use thelabel String (optional) - The text to appear in this segment.icon NativeImage (optional) - The image to appear in this segment.enabled Boolean (optional) - Whether this segment is selectable. Default: true.portId String - Unique identifier for the port.portName String - Name of the port.displayName String - A string suitable for display to the user for describing this device.vendorId String - Optional USB vendor ID.productId String - Optional USB product ID.serialNumber String - The USB device serial number.usbDriverName String (optional) - Represents a single serial port on macOS can be enumerated by multiple drivers.deviceInstanceId String (optional) - A stable identifier on Windows that can be used for device permissions.scriptUrl String - The full URL to the script that this service worker runsscope String - The base URL that this service worker is active for.renderProcessId Number - The virtual ID of the process that this service worker is running in. This is not an OS level PID. This aligns with the ID set used for webContents.getProcessId().\n\nQuery and receive events from a sessions active service workers.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Instances of the ServiceWorkers class are accessed by using serviceWorkers property of a Session.
Ein Beispiel:
\nconst { session } = require('electron')\n\n// Get all service workers.\nconsole.log(session.defaultSession.serviceWorkers.getAllRunning())\n\n// Handle logs and get service worker info\nsession.defaultSession.serviceWorkers.on('console-message', (event, messageDetails) => {\n console.log(\n 'Got service worker message',\n messageDetails,\n 'from',\n session.defaultSession.serviceWorkers.getFromVersionID(messageDetails.versionId)\n )\n})\nThe following events are available on instances of ServiceWorkers:
Kehrt zurück:
\nevent EventmessageDetails Object - Information about the console messagemessage String - The actual console messageversionId Number - The version ID of the service worker that sent the log messagesource String - The type of source for this message. Can be javascript, xml, network, console-api, storage, app-cache, rendering, security, deprecation, worker, violation, intervention, recommendation or other.level Number - The log level, from 0 to 3. In order it matches verbose, info, warning and error.sourceUrl String - The URL the message came fromlineNumber Number - The line number of the source that triggered this console messageEmitted when a service worker logs something to the console.
\nKehrt zurück:
\nevent Eventdetails Object - Information about the registered service workerscope String - The base URL that a service worker is registered forEmitted when a service worker has been registered. Can occur after a call to navigator.serviceWorker.register('/sw.js') successfully resolves or when a Chrome extension is loaded.
Die folgenden Methoden sind verfügbar in Instanzen von ServiceWorkers:
serviceWorkers.getAllRunning()Returns Record<Number, ServiceWorkerInfo> - A ServiceWorkerInfo object where the keys are the service worker version ID and the values are the information about that service worker.
serviceWorkers.getFromVersionID(versionId)versionId NumberReturns ServiceWorkerInfo - Information about this service worker
If the service worker does not exist or is not running this method will throw an exception.
", "title": "ServiceWorkers", "description": "Query and receive events from a sessions active service workers." }, "/docs/api/session": { "locale": "de-DE", "slug": "session", "href": "/docs/api/session", "crowdinFileId": "256365", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/session.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nManage browser sessions, cookies, cache, proxy settings, etc.
\n
Prozess: Haupt
\nThe session module can be used to create new Session objects.
You can also access the session of existing pages by using the session property of WebContents, or from the session module.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nconst ses = win.webContents.session\nconsole.log(ses.getUserAgent())\nDas Modul session verfügt über die folgenden Methoden:
session.fromPartition(partition[, options])partition Zeichenketteoptions Object (optional)cache Boolean - Whether to enable cache.Returns Session - A session instance from partition string. When there is an existing Session with the same partition, it will be returned; otherwise a new Session instance will be created with options.
If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. if there is no persist: prefix, the page will use an in-memory session. If the partition is empty then default session of the app will be returned.
To create a Session with options, you have to ensure the Session with the partition has never been used before. There is no way to change the options of an existing Session object.
The session module has the following properties:
session.defaultSessionA Session object, the default session object of the app.
\n\nGet and set properties of a session.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
You can create a Session object in the session module:
const { session } = require('electron')\nconst ses = session.fromPartition('persist:name')\nconsole.log(ses.getUserAgent())\nThe following events are available on instances of Session:
Kehrt zurück:
\nevent Eventitem DownloadItemwebContents WebContentsEmitted when Electron is about to download item in webContents.
Calling event.preventDefault() will cancel the download and item will not be available from next tick of the process.
const { session } = require('electron')\nsession.defaultSession.on('will-download', (event, item, webContents) => {\n event.preventDefault()\n require('got')(item.getURL()).then((response) => {\n require('fs').writeFileSync('/somewhere', response.body)\n })\n})\nKehrt zurück:
\nevent Eventextension ExtensionEmitted after an extension is loaded. This occurs whenever an extension is added to the \"enabled\" set of extensions. This includes:
\nSession.loadExtension.chrome.runtime.reload()).Kehrt zurück:
\nevent Eventextension ExtensionEmitted after an extension is unloaded. This occurs when Session.removeExtension is called.
Kehrt zurück:
\nevent Eventextension ExtensionEmitted after an extension is loaded and all necessary browser state is initialized to support the start of the extension's background page.
\nKehrt zurück:
\nevent EventpreconnectUrl String - The URL being requested for preconnection by the renderer.allowCredentials Boolean - True if the renderer is requesting that the connection include credentials (see the spec for more details.)Emitted when a render process requests preconnection to a URL, generally due to a resource hint.
\nKehrt zurück:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file has been successfully initialized. This occurs after the file has been downloaded.
\nKehrt zurück:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file starts downloading
\nKehrt zurück:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file has been successfully downloaded
\nKehrt zurück:
\nevent EventlanguageCode String - The language code of the dictionary fileEmitted when a hunspell dictionary file download fails. For details on the failure you should collect a netlog and inspect the download request.
\nKehrt zurück:
\nevent Eventdetails ObjektdeviceList HIDDevice[]frame WebFrameMaincallback FunctiondeviceId String | null (optional)Emitted when a HID device needs to be selected when a call to navigator.hid.requestDevice is made. callback should be called with deviceId to be selected; passing no arguments to callback will cancel the request. Additionally, permissioning on navigator.hid can be further managed by using ses.setPermissionCheckHandler(handler) and ses.setDevicePermissionHandler(handler)`.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nKehrt zurück:
\nevent Eventdetails Objektdevice HIDDevice[]frame WebFrameMainEmitted when a new HID device becomes available. For example, when a new USB device is plugged in.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
Kehrt zurück:
\nevent Eventdetails Objektdevice HIDDevice[]frame WebFrameMainEmitted when a HID device has been removed. For example, this event will fire when a USB device is unplugged.
\nThis event will only be emitted after navigator.hid.requestDevice has been called and select-hid-device has fired.
Kehrt zurück:
\nevent EventportList SerialPort[]webContents WebContentscallback FunctionportId ZeichenketteEmitted when a serial port needs to be selected when a call to navigator.serial.requestPort is made. callback should be called with portId to be selected, passing an empty string to callback will cancel the request. Additionally, permissioning on navigator.serial can be managed by using ses.setPermissionCheckHandler(handler) with the serial permission.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({\n width: 800,\n height: 600\n })\n win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {\n event.preventDefault()\n const selectedPort = portList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n if (!selectedPort) {\n callback('')\n } else {\n callback(selectedPort.portId)\n }\n })\n})\nKehrt zurück:
\nevent Eventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a new serial port becomes available. For example, this event will fire when a new USB device is plugged in.
Kehrt zurück:
\nevent Eventport SerialPortwebContents WebContentsEmitted after navigator.serial.requestPort has been called and select-serial-port has fired if a serial port has been removed. For example, this event will fire when a USB device is unplugged.
The following methods are available on instances of Session:
ses.getCacheSize()Returns Promise<Integer> - the session's current cache size, in bytes.
ses.clearCache()Returns Promise<void> - resolves when the cache clear operation is complete.
Clears the session’s HTTP cache.
\nses.clearStorageData([options])options Object (optional)origin String (optional) - Should follow window.location.origin’s representation scheme://host:port.storages String - The types of storages to clear, can contain: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage. If not specified, clear all storage types.quotas String - The types of quotas to clear, can contain: temporary, persistent, syncable. If not specified, clear all quotas.Returns Promise<void> - resolves when the storage data has been cleared.
ses.flushStorageData()Writes any unwritten DOMStorage data to disk.
\nses.setProxy(config)config Objectmode String (optional) - The proxy mode. Should be one of direct, auto_detect, pac_script, fixed_servers or system. If it's unspecified, it will be automatically determined based on other specified options.direct In direct mode all connections are created directly, without any proxy involved.auto_detect In auto_detect mode the proxy configuration is determined by a PAC script that can be downloaded at http://wpad/wpad.dat.pac_script In pac_script mode the proxy configuration is determined by a PAC script that is retrieved from the URL specified in the pacScript. This is the default mode if pacScript is specified.fixed_servers In fixed_servers mode the proxy configuration is specified in proxyRules. This is the default mode if proxyRules is specified.system In system mode the proxy configuration is taken from the operating system. Note that the system mode is different from setting no proxy configuration. In the latter case, Electron falls back to the system settings only if no command-line options influence the proxy configuration.pacScript String (optional) - The URL associated with the PAC file.proxyRules String (optional) - Rules indicating which proxies to use.proxyBypassRules String (optional) - Rules indicating which URLs should bypass the proxy settings.Returns Promise<void> - Resolves when the proxy setting process is complete.
Sets the proxy settings.
\nWhen mode is unspecified, pacScript and proxyRules are provided together, the proxyRules option is ignored and pacScript configuration is applied.
You may need ses.closeAllConnections to close currently in flight connections to prevent pooled sockets using previous proxy from being reused by future requests.
The proxyRules has to follow the rules below:
proxyRules = schemeProxies[\";\"<schemeProxies>]\nschemeProxies = [<urlScheme>\"=\"]<proxyURIList>\nurlScheme = \"http\" | \"https\" | \"ftp\" | \"socks\"\nproxyURIList = <proxyURL>[\",\"<proxyURIList>]\nproxyURL = [<proxyScheme>\"://\"]<proxyHost>[\":\"<proxyPort>]\nEin Beispiel:
\nhttp=foopy:80;ftp=foopy2 - Use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.foopy:80 - Use HTTP proxy foopy:80 for all URLs.foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing over to bar if foopy:80 is unavailable, and after that using no proxy.socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail over to the SOCKS5 proxy bar.com if foopy is unavailable.http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no proxy if foopy is unavailable.http=foopy;socks=foopy2 - Use HTTP proxy foopy for http URLs, and use socks4://foopy2 for all other URLs.The proxyBypassRules is a comma separated list of rules described below:
[ URL_SCHEME \"://\" ] HOSTNAME_PATTERN [ \":\" <port> ]
Match all hostnames that match the pattern HOSTNAME_PATTERN.
\nExamples: \"foobar.com\", \"foobar.com\", \".foobar.com\", \"foobar.com:99\", \"https://x..y.com:99\"
\n\".\" HOSTNAME_SUFFIX_PATTERN [ \":\" PORT ]
Match a particular domain suffix.
\nExamples: \".google.com\", \".com\", \"http://.google.com\"
\n[ SCHEME \"://\" ] IP_LITERAL [ \":\" PORT ]
Match URLs which are IP address literals.
\nExamples: \"127.0.1\", \"[0:0::1]\", \"[::1]\", \"http://[::1]:99\"
\nIP_LITERAL \"/\" PREFIX_LENGTH_IN_BITS
Match any URL that is to an IP literal that falls between the given range. IP range is specified using CIDR notation.
\nExamples: \"192.168.1.1/16\", \"fefe:13::abc/33\".
\n<local>
Match local addresses. The meaning of <local> is whether the host matches one of: \"127.0.0.1\", \"::1\", \"localhost\".
ses.resolveProxy(url)url URLReturns Promise<String> - Resolves with the proxy information for url.
ses.forceReloadProxyConfig()Returns Promise<void> - Resolves when the all internal states of proxy service is reset and the latest proxy configuration is reapplied if it's already available. The pac script will be fetched from pacScript again if the proxy mode is pac_script.
ses.setDownloadPath(path)path String - The download location.Sets download saving directory. By default, the download directory will be the Downloads under the respective app folder.
ses.enableNetworkEmulation(options)options Objektoffline Boolean (optional) - Whether to emulate network outage. Defaults to false.latency Double (optional) - RTT in ms. Defaults to 0 which will disable latency throttling.downloadThroughput Double (optional) - Download rate in Bps. Defaults to 0 which will disable download throttling.uploadThroughput Double (optional) - Upload rate in Bps. Defaults to 0 which will disable upload throttling.Emulates network with the given configuration for the session.
// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.\nwindow.webContents.session.enableNetworkEmulation({\n latency: 500,\n downloadThroughput: 6400,\n uploadThroughput: 6400\n})\n\n// To emulate a network outage.\nwindow.webContents.session.enableNetworkEmulation({ offline: true })\nses.preconnect(options)options Objekturl String - URL for preconnect. Only the origin is relevant for opening the socket.numSockets Number (optional) - number of sockets to preconnect. Must be between 1 and 6. Defaults to 1.Preconnects the given number of sockets to an origin.
\nses.closeAllConnections()Returns Promise<void> - Resolves when all connections are closed.
Note: It will terminate / fail all requests currently in flight.
\nses.disableNetworkEmulation()Disables any network emulation already active for the session. Resets to the original network configuration.
ses.setCertificateVerifyProc(proc)proc Function | nullrequest Objecthostname Stringcertificate CertificatevalidatedCertificate CertificateverificationResult String - Verification result from chromium.errorCode Integer - Error code.callback FunctionverificationResult Integer - Value can be one of certificate error codes from here. Apart from the certificate error codes, the following special codes can be used.0 - Indicates success and disables Certificate Transparency verification.-2 - Indicates failure.-3 - Uses the verification result from chromium.Sets the certificate verify proc for session, the proc will be called with proc(request, callback) whenever a server certificate verification is requested. Calling callback(0) accepts the certificate, calling callback(-2) rejects it.
Calling setCertificateVerifyProc(null) will revert back to default certificate verify proc.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.webContents.session.setCertificateVerifyProc((request, callback) => {\n const { hostname } = request\n if (hostname === 'github.com') {\n callback(0)\n } else {\n callback(-2)\n }\n})\n\n\nNOTE: The result of this procedure is cached by the network service.
\n
ses.setPermissionRequestHandler(handler)handler Function | nullwebContents WebContents - WebContents requesting the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.permission String - The type of requested permission.clipboard-read - Request access to read from the clipboard.media - Request access to media devices such as camera, microphone and speakers.aufstellen-Eingreif-Zugang dem Bildschirm antragen.mediaKeySystem - Request access to DRM protected content.geolocation - Request access to user's current location.notifications - Request notification creation and the ability to display them in the user's system tray.midi - Request MIDI access in the webmidi API.midiSysex - Request the use of system exclusive messages in the webmidi API.pointerLock - Request to directly interpret mouse movements as an input method. Click here to know more.fullscreen - Request for the app to enter fullscreen mode.openExternal - Request to open links in external applications.unknown - An unrecognized permission requestcallback FunctionpermissionGranted Boolean - Allow or deny the permission.details Object - Some properties are only available on certain permission types.externalURL String (optional) - The url of the openExternal request.mediaTypes String - The types of media access being requested, elements can be video or audiorequestingUrl String - The last URL the requesting frame loadedisMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission requests for the session. Calling callback(true) will allow the permission and callback(false) will reject it. To clear the handler, call setPermissionRequestHandler(null). Please note that you must also implement setPermissionCheckHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied.
const { session } = require('electron')\nsession.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {\n if (webContents.getURL() === 'some-host' && permission === 'notifications') {\n return callback(false) // denied.\n }\n\n callback(true)\n})\nses.setPermissionCheckHandler(handler)handler Funktion\\webContents (WebContents | null) - WebContents checking the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin. All cross origin sub frames making permission checks will pass a null webContents to this handler, while certain other permission checks such as notifications checks will always pass null. You should use embeddingOrigin and requestingOrigin to determine what origin the owning frame and the requesting frame are on respectively.permission String - Type of permission check. Valid values are midiSysex, notifications, geolocation, media,mediaKeySystem,midi, pointerLock, fullscreen, openExternal, hid, or serial.requestingOrigin String - The origin URL of the permission checkdetails Object - Some properties are only available on certain permission types.embeddingOrigin String (optional) - The origin of the frame embedding the frame that made the permission check. Only set for cross-origin sub frames making permission checks.securityOrigin String (optional) - The security origin of the media check.mediaType String (optional) - The type of media access being requested, can be video, audio or unknownrequestingUrl String (optional) - The last URL the requesting frame loaded. This is not provided for cross-origin sub frames making permission checks.isMainFrame Boolean - Whether the frame making the request is the main frameSets the handler which can be used to respond to permission checks for the session. Returning true will allow the permission and false will reject it. Please note that you must also implement setPermissionRequestHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied. To clear the handler, call setPermissionCheckHandler(null).
const { session } = require('electron')\nconst url = require('url')\nsession.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {\n if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {\n return true // granted\n }\n\n return false // denied\n})\nses.setDevicePermissionHandler(handler)handler Funktion\\details ObjektdeviceType String - The type of device that permission is being requested on, can be hid.origin String - The origin URL of the device permission check.device HIDDevice - the device that permission is being requested for.frame WebFrameMain - WebFrameMain checking the device permission.Sets the handler which can be used to respond to device permission checks for the session. Returning true will allow the device to be permitted and false will reject it. To clear the handler, call setDevicePermissionHandler(null). This handler can be used to provide default permissioning to devices without first calling for permission to devices (eg via navigator.hid.requestDevice). If this handler is not defined, the default device permissions as granted through device selection (eg via navigator.hid.requestDevice) will be used. Additionally, the default behavior of Electron is to store granted device permision through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n\n win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {\n if (permission === 'hid') {\n // Add logic here to determine if permission should be given to allow HID selection\n return true\n }\n return false\n })\n\n // Optionally, retrieve previously persisted devices from a persistent store\n const grantedDevices = fetchGrantedDevices()\n\n win.webContents.session.setDevicePermissionHandler((details) => {\n if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {\n if (details.device.vendorId === 123 && details.device.productId === 345) {\n // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)\n return true\n }\n\n // Search through the list of devices that have previously been granted permission\n return grantedDevices.some((grantedDevice) => {\n return grantedDevice.vendorId === details.device.vendorId &&\n grantedDevice.productId === details.device.productId &&\n grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber\n })\n }\n return false\n })\n\n win.webContents.session.on('select-hid-device', (event, details, callback) => {\n event.preventDefault()\n const selectedDevice = details.deviceList.find((device) => {\n return device.vendorId === '9025' && device.productId === '67'\n })\n callback(selectedPort?.deviceId)\n })\n})\nses.clearHostResolverCache()Returns Promise<void> - Resolves when the operation is complete.
Clears the host resolver cache.
\nses.allowNTLMCredentialsForDomains(domains)domains String - A comma-separated list of servers for which integrated authentication is enabled.Dynamically sets whether to always send credentials for HTTP NTLM or Negotiate authentication.
\nconst { session } = require('electron')\n// consider any url ending with `example.com`, `foobar.com`, `baz`\n// for integrated authentication.\nsession.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')\n\n// consider all urls for integrated authentication.\nsession.defaultSession.allowNTLMCredentialsForDomains('*')\nses.setUserAgent(userAgent[, acceptLanguages])userAgent StringacceptLanguages String (optional)Overrides the userAgent and acceptLanguages for this session.
The acceptLanguages must a comma separated ordered list of language codes, for example \"en-US,fr,de,ko,zh-CN,ja\".
This doesn't affect existing WebContents, and each WebContents can use webContents.setUserAgent to override the session-wide user agent.
ses.isPersistent()Returns Boolean - Whether or not this session is a persistent one. The default webContents session of a BrowserWindow is persistent. When creating a session from a partition, session prefixed with persist: will be persistent, while others will be temporary.
ses.getUserAgent()Returns String - The user agent for this session.
ses.setSSLConfig(config)config ObjectminVersion String (optional) - Can be tls1, tls1.1, tls1.2 or tls1.3. The minimum SSL version to allow when connecting to remote servers. Defaults to tls1.maxVersion String (optional) - Kann tls1.2 oder tls1.3 sein. The maximum SSL version to allow when connecting to remote servers. Standardwert ist tls1.3.disabledCipherSuites Integer - List of cipher suites which should be explicitly prevented from being used in addition to those disabled by the net built-in policy. Supported literal forms: 0xAABB, where AA is cipher_suite[0] and BB is cipher_suite[1], as defined in RFC 2246, Section 7.4.1.2. Unrecognized but parsable cipher suites in this form will not return an error. Ex: To disable TLS_RSA_WITH_RC4_128_MD5, specify 0x0004, while to disable TLS_ECDH_ECDSA_WITH_RC4_128_SHA, specify 0xC002. Note that TLSv1.3 ciphers cannot be disabled using this mechanism.Sets the SSL configuration for the session. All subsequent network requests will use the new configuration. Existing network connections (such as WebSocket connections) will not be terminated, but old sockets in the pool will not be reused for new connections.
\nses.getBlobData(identifier)identifier String - Valid UUID.Returns Promise<Buffer> - resolves with blob data.
ses.downloadURL(url)url StringInitiates a download of the resource at url. The API will generate a DownloadItem that can be accessed with the will-download event.
Note: This does not perform any security checks that relate to a page's origin, unlike webContents.downloadURL.
ses.createInterruptedDownload(options)options Objektpath String - Absolute path of the download.urlChain String[] - Complete URL chain for the download.mimeType String (optional)offset Integer - Start range for the download.length Integer - Total length of the download.lastModified String (optional) - Last-Modified header value.eTag String (optional) - ETag header value.startTime Double (optional) - Time when download was started in number of seconds since UNIX epoch.Allows resuming cancelled or interrupted downloads from previous Session. The API will generate a DownloadItem that can be accessed with the will-download event. The DownloadItem will not have any WebContents associated with it and the initial state will be interrupted. The download will start only when the resume API is called on the DownloadItem.
ses.clearAuthCache()Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.
ses.setPreloads(preloads)preloads String[] - An array of absolute path to preload scriptsAdds scripts that will be executed on ALL web contents that are associated with this session just before normal preload scripts run.
ses.getPreloads()Returns String[] an array of paths to preload scripts that have been registered.
ses.setSpellCheckerEnabled(enable)enable BooleanSets whether to enable the builtin spell checker.
\nses.isSpellCheckerEnabled()Returns Boolean - Whether the builtin spell checker is enabled.
ses.setSpellCheckerLanguages(languages)languages String[] - An array of language codes to enable the spellchecker for.The built in spellchecker does not automatically detect what language a user is typing in. In order for the spell checker to correctly check their words you must call this API with an array of language codes. You can get the list of supported language codes with the ses.availableSpellCheckerLanguages property.
Note: On macOS the OS spellchecker is used and will detect your language automatically. This API is a no-op on macOS.
\nses.getSpellCheckerLanguages()Returns String[] - An array of language codes the spellchecker is enabled for. If this list is empty the spellchecker will fallback to using en-US. By default on launch if this setting is an empty list Electron will try to populate this setting with the current OS locale. This setting is persisted across restarts.
Note: On macOS the OS spellchecker is used and has its own list of languages. This API is a no-op on macOS.
\nses.setSpellCheckerDictionaryDownloadURL(url)url String - A base URL for Electron to download hunspell dictionaries from.By default Electron will download hunspell dictionaries from the Chromium CDN. If you want to override this behavior you can use this API to point the dictionary downloader at your own hosted version of the hunspell dictionaries. We publish a hunspell_dictionaries.zip file with each release which contains the files you need to host here, the file server must be case insensitive you must upload each file twice, once with the case it has in the ZIP file and once with the filename as all lower case.
If the files present in hunspell_dictionaries.zip are available at https://example.com/dictionaries/language-code.bdic then you should call this api with ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Please note the trailing slash. The URL to the dictionaries is formed as ${url}${filename}.
Note: On macOS the OS spellchecker is used and therefore we do not download any dictionary files. This API is a no-op on macOS.
\nses.listWordsInSpellCheckerDictionary()Returns Promise<String[]> - An array of all words in app's custom dictionary. Resolves when the full dictionary is loaded from disk.
ses.addWordToSpellCheckerDictionary(word)word String - The word you want to add to the dictionaryReturns Boolean - Whether the word was successfully written to the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be written to the OS custom dictionary as well
\nses.removeWordFromSpellCheckerDictionary(word)word String - The word you want to remove from the dictionaryReturns Boolean - Whether the word was successfully removed from the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be removed from the OS custom dictionary as well
\nses.loadExtension(path[, options])path String - Path to a directory containing an unpacked Chrome extensionoptions Object (optional)allowFileAccess Boolean - Whether to allow the extension to read local files over file:// protocol and inject content scripts into file:// pages. This is required e.g. for loading devtools extensions on file:// URLs. Der Standardwert ist false.Returns Promise<Extension> - resolves when the extension is loaded.
This method will raise an exception if the extension could not be loaded. If there are warnings when installing the extension (e.g. if the extension requests an API that Electron does not support) then they will be logged to the console.
\nNote that Electron does not support the full range of Chrome extensions APIs. See Supported Extensions APIs for more details on what is supported.
\nNote that in previous versions of Electron, extensions that were loaded would be remembered for future runs of the application. This is no longer the case: loadExtension must be called on every boot of your app if you want the extension to be loaded.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.on('ready', async () => {\n await session.defaultSession.loadExtension(\n path.join(__dirname, 'react-devtools'),\n // allowFileAccess is required to load the devtools extension on file:// URLs.\n { allowFileAccess: true }\n )\n // Note that in order to use the React DevTools extension, you'll need to\n // download and unzip a copy of the extension.\n})\nThis API does not support loading packed (.crx) extensions.
\nNote: This API cannot be called before the ready event of the app module is emitted.
Note: Loading extensions into in-memory (non-persistent) sessions is not supported and will throw an error.
\nses.removeExtension(extensionId)extensionId String - ID of extension to removeUnloads an extension.
\nNote: This API cannot be called before the ready event of the app module is emitted.
ses.getExtension(extensionId)extensionId String - ID of extension to queryReturns Extension | null - The loaded extension with the given ID.
Note: This API cannot be called before the ready event of the app module is emitted.
ses.getAllExtensions()Returns Extension[] - A list of all loaded extensions.
Note: This API cannot be called before the ready event of the app module is emitted.
ses.getStoragePath()A String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
The following properties are available on instances of Session:
ses.availableSpellCheckerLanguages ReadonlyA String[] array which consists of all the known available spell checker languages. Providing a language code to the setSpellCheckerLanguages API that isn't in this array will result in an error.
ses.spellCheckerEnabledA Boolean indicating whether builtin spell checker is enabled.
ses.storagePath ReadonlyA String | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.
ses.cookies ReadonlyA Cookies object for this session.
ses.serviceWorkers ReadonlyA ServiceWorkers object for this session.
ses.webRequest ReadonlyA WebRequest object for this session.
ses.protocol ReadonlyA Protocol object for this session.
const { app, session } = require('electron')\nconst path = require('path')\n\napp.whenReady().then(() => {\n const protocol = session.fromPartition('some-partition').protocol\n if (!protocol.registerFileProtocol('atom', (request, callback) => {\n const url = request.url.substr(7)\n callback({ path: path.normalize(`${__dirname}/${url}`) })\n })) {\n console.error('Failed to register protocol')\n }\n})\nses.netLog ReadonlyA NetLog object for this session.
const { app, session } = require('electron')\n\napp.whenReady().then(async () => {\n const netLog = session.fromPartition('some-partition').netLog\n netLog.startLogging('/path/to/net-log')\n // After some network events\n const path = await netLog.stopLogging()\n console.log('Net-logs written to', path)\n})\nDebug-Symbole ermöglichen es Ihnen, bessere Debugging-Sitzungen zu haben. Sie enthalten Informationen über die Funktionen in Anwendungen und Bibliotheken und ermöglichen es ihnen saubere Call-Stacks zu erhalten. Ein Symbolserver erlaubt es dem Debugger die richtigen Symbole, Binärdateien und Quellcode automatisch zu laden, ohne den Nutzer zum Herunterladen großer Debuggingdateien zu zwingen. The server functions like Microsoft's symbol server so the documentation there can be useful.
\nNote that because released Electron builds are heavily optimized, debugging is not always easy. The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations. The only workaround is to build an unoptimized local build.
\nThe official symbol server URL for Electron is https://symbols.electronjs.org. You cannot visit this URL directly, you must add it to the symbol path of your debugging tool. In the examples below, a local cache directory is used to avoid repeatedly fetching the PDB from the server. Replace c:\\code\\symbols with an appropriate cache directory on your machine.
The Windbg symbol path is configured with a string value delimited with asterisk characters. To use only the Electron symbol server, add the following entry to your symbol path (Note: you can replace c:\\code\\symbols with any writable directory on your computer, if you'd prefer a different location for downloaded symbols):
SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\nSet this string as _NT_SYMBOL_PATH in the environment, using the Windbg menus, or by typing the .sympath command. If you would like to get symbols from Microsoft's symbol server as well, you should list that first:
SRV*c:\\code\\symbols\\*https://msdl.microsoft.com/download/symbols;SRV*c:\\code\\symbols\\*https://symbols.electronjs.org\n Options\">
Type the following commands in Windbg to print why symbols are not loading:
\n> !sym noisy\n> .reload /f electron.exe\nThe ShareMenu class creates Share Menu on macOS, which can be used to share information from the current context to apps, social media accounts, and other services.
For including the share menu as a submenu of other menus, please use the shareMenu role of MenuItem.
\n\nCreate share menu on macOS.
\n
Prozess: Haupt
\nnew ShareMenu(sharingItem)sharingItem SharingItem - The item to share.Creates a new share menu.
\nDas shareMenu Objekt hat die folgenden Instanz Methoden:
shareMenu.popup([options])options PopupOptions (optional)browserWindow BrowserWindow (optional) - Default ist das fokussierte Fenster.x Number (optional) - Default is the current mouse cursor position. Must be declared if y is declared.y Number (optional) - Default is the current mouse cursor position. Must be declared if x is declared.positioningItem Number (optional) macOS - The index of the menu item to be positioned under the mouse cursor at the specified coordinates. Default is -1.callback Funktion (optional) - Wird aufgerufen wenn das Menü geschlossen wird.Pops up this menu as a context menu in the BrowserWindow.
shareMenu.closePopup([browserWindow])browserWindow BrowserWindow (optional) - Default ist das fokussierte Fenster.Schließt das Kontext-Menü im browserWindow.
id String - The unique id of the shared worker.url String - The url of the shared worker.texts String - An array of text to share.filePaths String - An array of files to share.urls String - An array of URLs to share.\n\nVerwalten von Dateien und URLs durch ihre Standardprogramme.
\n
Process: Main, Renderer (non-sandboxed only)
\nThe shell module provides functions related to desktop integration.
An example of opening a URL in the user's default browser:
\nconst { shell } = require('electron')\n\nshell.openExternal('https://github.com')\nNote: While the shell module can be used in the renderer process, it will not function in a sandboxed renderer.
Das Modul shell verfügt über die folgenden Methoden:
shell.showItemInFolder(fullPath)fullPath ZeichenketteShow the given file in a file manager. If possible, select the file.
\nshell.openPath(path)path StringReturns Promise<String> - Resolves with a string containing the error message corresponding to the failure if a failure occurred, otherwise \"\".
Open the given file in the desktop's default manner.
\nshell.openExternal(url[, options])url String - Max 2081 characters on windows.options Object (optional)activate Boolean (optional) macOS - true to bring the opened application to the foreground. The default is true.workingDirectory String (optional) Windows - The working directory.Gibt das Promise<void> zurück
Open the given external protocol URL in the desktop's default manner. (For example, mailto: URLs in the user's default mail agent).
\nshell.trashItem(path)path String - path to the item to be moved to the trash.Returns Promise<void> - Resolves when the operation has been completed. Rejects if there was an error while deleting the requested item.
This moves a path to the OS-specific trash location (Trash on macOS, Recycle Bin on Windows, and a desktop-environment-specific location on Linux).
\nshell.beep()Play the beep sound.
\nshell.writeShortcutLink(shortcutPath[, operation], options) WindowsshortcutPath Zeichenketteoperation String (optional) - Default is create, can be one of following:create - Creates a new shortcut, overwriting if necessary.update - Updates specified properties only on an existing shortcut.replace - Overwrites an existing shortcut, fails if the shortcut doesn't exist.options ShortcutDetailsReturns Boolean - Whether the shortcut was created successfully.
Creates or updates a shortcut link at shortcutPath.
shell.readShortcutLink(shortcutPath) WindowsshortcutPath ZeichenketteReturns ShortcutDetails
Resolves the shortcut link at shortcutPath.
An exception will be thrown when any error happens.
", "title": "shell", "description": "Verwalten von Dateien und URLs durch ihre Standardprogramme." }, "/docs/api/structures/shortcut-details": { "locale": "de-DE", "slug": "shortcut-details", "href": "/docs/api/structures/shortcut-details", "crowdinFileId": "256509", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/shortcut-details.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "target String - The target to launch from this shortcut.cwd String (optional) - The working directory. Default is empty.args String (optional) - The arguments to be applied to target when launching from this shortcut. Default is empty.description String (optional) - The description of the shortcut. Default is empty.icon String (optional) - The path to the icon, can be a DLL or EXE. icon and iconIndex have to be set together. Default is empty, which uses the target's icon.iconIndex Number (optional) - The resource ID of icon when icon is a DLL or EXE. Default is 0.appUserModelId String (optional) - The Application User Model ID. Default is empty.toastActivatorClsid String (optional) - The Application Toast Activator CLSID. Needed for participating in Action Center.width Numberheight NumberThis guide provides information on how to package your Electron application for any Snapcraft environment, including the Ubuntu Software Center.
\nTogether with the broader Linux community, Canonical aims to fix many of the common software installation problems with the snapcraft project. Snaps are containerized software packages that include required dependencies, auto-update, and work on all major Linux distributions without system modification.
There are three ways to create a .snap file:
1) Using electron-forge or electron-builder, both tools that come with snap support out of the box. This is the easiest option. 2) Using electron-installer-snap, which takes electron-packager's output. 3) Using an already created .deb package.
In some cases, you will need to have the snapcraft tool installed. Instructions to install snapcraft for your particular distribution are available here.
electron-installer-snapThe module works like electron-winstaller and similar modules in that its scope is limited to building snap packages. You can install it with:
npm install --save-dev electron-installer-snap\nPackage the application using electron-packager (or a similar tool). Make sure to remove node_modules that you don't need in your final application, since any module you don't actually need will increase your application's size.
Die Ausgabe sollte etwa wie folgt aussehen:
\n.\n└── dist\n └── app-linux-x64\n ├── LICENSE\n ├── LICENSES.chromium.html\n ├── content_shell.pak\n ├── app\n ├── icudtl.dat\n ├── libgcrypt.so.11\n ├── libnode.so\n ├── locales\n ├── resources\n ├── v8_context_snapshot.bin\n └── version\nelectron-installer-snapFrom a terminal that has snapcraft in its PATH, run electron-installer-snap with the only required parameter --src, which is the location of your packaged Electron application created in the first step.
npx electron-installer-snap --src=out/myappname-linux-x64\nIf you have an existing build pipeline, you can use electron-installer-snap programmatically. For more information, see the Snapcraft API docs.
const snap = require('electron-installer-snap')\n\nsnap(options)\n .then(snapPath => console.log(`Created snap at ${snapPath}!`))\nsnapcraft with electron-packagerCreate your project directory and add the following to snap/snapcraft.yaml:
name: electron-packager-hello-world\nversion: '0.1'\nsummary: Hello World Electron app\ndescription: |\n Simple Hello World Electron app as an example\nbase: core18\nconfinement: strict\ngrade: stable\n\napps:\n electron-packager-hello-world:\n command: electron-quick-start/electron-quick-start --no-sandbox\n extensions: [gnome-3-34]\n plugs:\n - browser-support\n - network\n - network-bind\n environment:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n TMPDIR: $XDG_RUNTIME_DIR\n\nparts:\n electron-quick-start:\n plugin: nil\n source: https://github.com/electron/electron-quick-start.git\n override-build: |\n npm install electron electron-packager\n npx electron-packager . --overwrite --platform=linux --output=release-build --prune=true\n cp -rv ./electron-quick-start-linux-* $SNAPCRAFT_PART_INSTALL/electron-quick-start\n build-snaps:\n - node/14/stable\n build-packages:\n - unzip\n stage-packages:\n - libnss3\n - libnspr4\nIf you want to apply this example to an existing project:
\nsource: https://github.com/electron/electron-quick-start.git with source: ..electron-quick-start with your project's name.$ snapcraft\n\n<output snipped>\nSnapped electron-packager-hello-world_0.1_amd64.snap\nsudo snap install electron-packager-hello-world_0.1_amd64.snap --dangerous\nelectron-packager-hello-world\nSnapcraft is capable of taking an existing .deb file and turning it into a .snap file. The creation of a snap is configured using a snapcraft.yaml file that describes the sources, dependencies, description, and other core building blocks.
If you do not already have a .deb package, using electron-installer-snap might be an easier path to create snap packages. However, multiple solutions for creating Debian packages exist, including electron-forge, electron-builder or electron-installer-debian.
For more information on the available configuration options, see the documentation on the snapcraft syntax. Let's look at an example:
\nname: myApp\nversion: '2.0.0'\nsummary: Eine kurze Beschreibung der App.\nweist du was? Diese App ist unglaublich! Sie tut all diese Dinge für dich. Manch einer behauptet, sie hält dich jung oder macht dich sogar glücklich.\n\ngrade: stable\nconfinement: classic\n\nparts:\n slack:\n plugin: dump\n source: my-deb.deb\n source-type: deb\n after:\n - desktop-gtk3\n stage-packages:\n - libasound2\n - libnotify4\n - libnspr4\n - libnss3\n - libpcre3\n - libpulse0\n - libxss1\n - libxtst6\n electron-launch:\n plugin: dump\n source: files/\n prepare: |\n chmod +x bin/electron-launch\n\napps:\n myApp:\n command: bin/electron-launch $SNAP/usr/lib/myApp/myApp\n desktop: usr/share/applications/myApp.desktop\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n environment:\n TMPDIR: $XDG_RUNTIME_DIR\nAs you can see, the snapcraft.yaml instructs the system to launch a file called electron-launch. In this example, it passes information on to the app's binary:
\nexec \"$@\" --executed-from=\"$(pwd)\" --pid=$$ > /dev/null 2>&1 &\nAlternatively, if you're building your snap with strict confinement, you can use the desktop-launch command:
apps:\n myApp:\n # Correct the TMPDIR path for Chromium Framework/Electron to ensure\n # libappindicator has readable resources.\n command: env TMPDIR=$XDG_RUNTIME_DIR PATH=/usr/local/bin:${PATH} ${SNAP}/bin/desktop-launch $SNAP/myApp/desktop\n desktop: usr/share/applications/desktop.desktop\nElectrons Source Code ist aufgeteilt in einige Bereiche und folgt weitestgehend den Chromium separation conventions.
\nEs wäre hilfreich sich in Chromium's Multi-Prozess Architekture einzulesen um den Source Code besser zu verstehen.
\nElectron\n├── build/ - Build configuration files needed to build with GN.\n├── buildflags/ - Determines the set of features that can be conditionally built.\n├── chromium_src/ - Source code copied from Chromium that isn't part of the content layer.\n├── default_app/ - A default app run when Electron is started without\n| providing a consumer app.\n├── docs/ - Electron's documentation.\n| ├── api/ - Documentation for Electron's externally-facing modules and APIs.\n| ├── development/ - Documentation to aid in developing for and with Electron.\n| ├── fiddles/ - A set of code snippets one can run in Electron Fiddle.\n| ├── images/ - Images used in documentation.\n| └── tutorial/ - Tutorial documents for various aspects of Electron.\n├── lib/ - JavaScript/TypeScript source code.\n| ├── browser/ - Main process initialization code.\n| | ├── api/ - API implementation for main process modules.\n| | └── remote/ - Code related to the remote module as it is\n| | used in the main process.\n| ├── common/ - Relating to logic needed by both main and renderer processes.\n| | └── api/ - API implementation for modules that can be used in\n| | both the main and renderer processes\n| ├── isolated_renderer/ - Handles creation of isolated renderer processes when\n| | contextIsolation is enabled.\n| ├── renderer/ - Renderer process initialization code.\n| | ├── api/ - API implementation for renderer process modules.\n| | ├── extension/ - Code related to use of Chrome Extensions\n| | | in Electron's renderer process.\n| | ├── remote/ - Logic that handles use of the remote module in\n| | | the main process.\n| | └── web-view/ - Logic that handles the use of webviews in the\n| | renderer process.\n| ├── sandboxed_renderer/ - Logic that handles creation of sandboxed renderer\n| | | processes.\n| | └── api/ - API implementation for sandboxed renderer processes.\n| └── worker/ - Logic that handles proper functionality of Node.js\n| environments in Web Workers.\n├── patches/ - Patches applied on top of Electron's core dependencies\n| | in order to handle differences between our use cases and\n| | default functionality.\n| ├── boringssl/ - Patches applied to Google's fork of OpenSSL, BoringSSL.\n| ├── chromium/ - Patches applied to Chromium.\n| ├── node/ - Patches applied on top of Node.js.\n| └── v8/ - Patches applied on top of Google's V8 engine.\n├── shell/ - C++ source code.\n| ├── app/ - System entry code.\n| ├── browser/ - The frontend including the main window, UI, and all of the\n| | | main process things. This talks to the renderer to manage web\n| | | pages.\n| | ├── ui/ - Implementation of UI stuff for different platforms.\n| | | ├── cocoa/ - Cocoa specific source code.\n| | | ├── win/ - Windows GUI specific source code.\n| | | └── x/ - X11 specific source code.\n| | ├── api/ - The implementation of the main process APIs.\n| | ├── net/ - Network related code.\n| | ├── mac/ - Mac specific Objective-C source code.\n| | └── resources/ - Icons, platform-dependent files, etc.\n| ├── renderer/ - Code that runs in renderer process.\n| | └── api/ - The implementation of renderer process APIs.\n| └── common/ - Code that used by both the main and renderer processes,\n| | including some utility functions and code to integrate node's\n| | message loop into Chromium's message loop.\n| └── api/ - The implementation of common APIs, and foundations of\n| Electron's built-in modules.\n├── spec/ - Components of Electron's test suite run in the renderer process.\n├── spec-main/ - Components of Electron's test suite run in the main process.\n└── BUILD.gn - Building rules of Electron.\nscript/create-dist.py script when creating a distribution.ninja.script/ - The set of all scripts Electron runs for a variety of purposes.\n├── codesign/ - Fakes codesigning for Electron apps; used for testing.\n├── lib/ - Miscellaneous python utility scripts.\n└── release/ - Scripts run during Electron's release process.\n ├── notes/ - Generates release notes for new Electron versions.\n └── uploaders/ - Uploads various release-related files during release.\nElectron has built-in support for Chromium's spellchecker since Electron 8. On Windows and Linux this is powered by Hunspell dictionaries, and on macOS it makes use of the native spellchecker APIs.
\nFor Electron 9 and higher the spellchecker is enabled by default. For Electron 8 you need to enable it in webPreferences.
const myWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: true\n }\n})\nOn macOS as we use the native APIs there is no way to set the language that the spellchecker uses. By default on macOS the native spellchecker will automatically detect the language being used for you.
\nFor Windows and Linux there are a few Electron APIs you should use to set the languages for the spellchecker.
\n// Sets the spellchecker to check English US and French\nmyWindow.session.setSpellCheckerLanguages(['en-US', 'fr'])\n\n// An array of all available language codes\nconst possibleLanguages = myWindow.session.availableSpellCheckerLanguages\nBy default the spellchecker will enable the language matching the current OS locale.
\nAll the required information to generate a context menu is provided in the context-menu event on each webContents instance. A small example of how to make a context menu with this information is provided below.
const { Menu, MenuItem } = require('electron')\n\nmyWindow.webContents.on('context-menu', (event, params) => {\n const menu = new Menu()\n\n // Add each spelling suggestion\n for (const suggestion of params.dictionarySuggestions) {\n menu.append(new MenuItem({\n label: suggestion,\n click: () => mainWindow.webContents.replaceMisspelling(suggestion)\n }))\n }\n\n // Allow users to add the misspelled word to the dictionary\n if (params.misspelledWord) {\n menu.append(\n new MenuItem({\n label: 'Add to dictionary',\n click: () => mainWindow.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord)\n })\n )\n }\n\n menu.popup()\n})\nAlthough the spellchecker itself does not send any typings, words or user input to Google services the hunspell dictionary files are downloaded from a Google CDN by default. If you want to avoid this you can provide an alternative URL to download the dictionaries from.
\nmyWindow.session.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/')\nCheck out the docs for session.setSpellCheckerDictionaryDownloadURL for more information on where to get the dictionary files from and how you need to host them.
Dies sind die Richtlinien für das Schreiben von Dokumentation zu Elektron.
\n# am Anfang.##-level headings.# in the heading according to their nesting depth.Am Beispiel von Schnellstart:
# Schnellstart\n\n...\n\n## Main-Prozess\n\n...\n\n## Renderer-Prozess\n\n...\n\n## Ihre App ausführen\n\n...\n\n### Als Distribution ausführen\n\n...\n\n### Electron-Binärdatei manuell herunterladen\n\n...\nFür API-Referenzen gibt es Ausnahmen von dieser Regel.
\nThis repository uses the markdownlint package to enforce consistent Markdown styling. For the exact rules, see the .markdownlint.json file in the root folder.
There are a few style guidelines that aren't covered by the linter rules:
\n\nsh instead of cmd in code blocks (due to the syntax highlighter).js i javascript są sprawdzane pod względem zgodności ze stylem standard-markdown.Die folgenden Regeln gelten nur für Dokumentationen der APIs.
\nEach module's API doc must use the actual object name returned by require('electron') as its title (such as BrowserWindow, autoUpdater, and session).
Directly under the page title, add a one-line description of the module as a markdown quote (beginning with >).
Using the session module as an example:
# session\n\n> Verwalte Browser-Sitzungen, Cookies, Cache, Proxy-Einstellungen, etc.\nFür Module, die keine Klassen sind, müssen deren Methoden und Events unter ## Methods und ## Events aufgelistet werden.
Verwende AutoUpdater als Beispiel:
# autoUpdater\n\n## Events\n\n### Event: 'error'\n\n## Methoden\n\n### `autoUpdater.setFeedURL(url[, requestHeaders])`\n## Klassen: Klassenname aufgeführt werden.###-level headings.### Static Methods chapter.### Instance Methods chapter.[TYPE] - [Return description]\"Object, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.### Instance Events chapter.### Instance Properties chapter.Using the Session and Cookies classes as an example:
# session\n\n## Methods\n\n### session.fromPartition(partition)\n\n## Static Properties\n\n### session.defaultSession\n\n## Class: Session\n\n### Instance Events\n\n#### Event: 'will-download'\n\n### Instance Methods\n\n#### `ses.getCacheSize()`\n\n### Instance Properties\n\n#### `ses.cookies`\n\n## Class: Cookies\n\n### Instance Methods\n\n#### `cookies.get(filter, callback)`\nThe methods chapter must be in the following form:
\n### `objectName.methodName(required[, optional]))`\n\n* `required` String - A parameter description.\n* `optional` Integer (optional) - Another parameter description.\n\n...\nThe heading can be ### or ####-levels depending on whether the method belongs to a module or a class.
For modules, the objectName is the module's name. For classes, it must be the name of the instance of the class, and must not be the same as the module's name.
For example, the methods of the Session class under the session module must use ses as the objectName.
Optional arguments are notated by square brackets [] surrounding the optional argument as well as the comma required if this optional argument follows another argument:
erforderlich[, optional]\nMore detailed information on each of the arguments is noted in an unordered list below the method. The type of argument is notated by either JavaScript primitives (e.g. String, Promise, or Object), a custom API structure like Electron's Cookie, or the wildcard any.
If the argument is of type Array, use [] shorthand with the type of value inside the array (for example,any[] or String[]).
If the argument is of type Promise, parametrize the type with what the promise resolves to (for example, Promise<void> or Promise<String>).
If an argument can be of multiple types, separate the types with |.
The description for Function type arguments should make it clear how it may be called and list the types of the parameters that will be passed to it.
If an argument or a method is unique to certain platforms, those platforms are denoted using a space-delimited italicized list following the datatype. Werte können macOS, Windows oder Linux sein.
* `animate` Boolean (optional) _macOS_ _Windows_ - Animate the thing.\nThe events chapter must be in following form:
\n### Ereignis: 'aufwachen'\n\nGibt zurück:\n\n* `time` String\n\n...\nThe heading can be ### or ####-levels depending on whether the event belongs to a module or a class.
The arguments of an event follow the same rules as methods.
\nThe properties chapter must be in following form:
\n### session.defaultSession\n\n...\nThe heading can be ### or ####-levels depending on whether the property belongs to a module or a class.
Siehe Elektron/i18n
", "title": "Electron Documentation Style Guide", "description": "" }, "/docs/tutorial/support": { "locale": "de-DE", "slug": "support", "href": "/docs/tutorial/support", "crowdinFileId": "256253", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/support.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "If you have a security concern, please see the security document.
\nIf you're looking for programming help, for answers to questions, or to join in discussion with other developers who use Electron, you can interact with the community in these locations:
\nElectron's Discord has channels for:electron category on the Atom forums#electron Kanal auf Atom's Slackelectron-ru (Russian)electron-br (Brazilian Portuguese)electron-kr (Korean)electron-jp (Japanese)electron-tr (Turkish)electron-id (Indonesia)electron-pl (Poland)If you'd like to contribute to Electron, see the contributing document.
\nIf you've found a bug in a supported version of Electron, please report it with the issue tracker.
\nawesome-electron is a community-maintained list of useful example apps, tools and resources.
\nNote: Beginning in September 2021 with Electron 15, the Electron team will temporarily support the latest four stable major versions. This extended support is intended to help Electron developers transition to the new eight week release cadence, and will continue until May 2022, with the release of Electron 19. At that time, the Electron team will drop support back to the latest three stable major versions.
\nThe latest three stable major versions are supported by the Electron team. For example, if the latest release is 6.1.x, then the 5.0.x as well as the 4.2.x series are supported. We only support the latest minor release for each stable release series. This means that in the case of a security fix 6.1.x will receive the fix, but we will not release a new version of 6.0.x.
\nThe latest stable release unilaterally receives all fixes from main, and the version prior to that receives the vast majority of those fixes as time and bandwidth warrants. The oldest supported release line will receive only security fixes directly.
All supported release lines will accept external pull requests to backport fixes previously merged to main, though this may be on a case-by-case basis for some older supported lines. All contested decisions around release line backports will be resolved by the Releases Working Group as an agenda item at their weekly meeting the week the backport PR is raised.
When an API is changed or removed in a way that breaks existing functionality, the previous functionality will be supported for a minimum of two major versions when possible before being removed. For example, if a function takes three arguments, and that number is reduced to two in major version 10, the three-argument version would continue to work until, at minimum, major version 12. Past the minimum two-version threshold, we will attempt to support backwards compatibility beyond two versions until the maintainers feel the maintenance burden is too high to continue doing so.
\nWhen a release branch reaches the end of its support cycle, the series will be deprecated in NPM and a final end-of-support release will be made. This release will add a warning to inform that an unsupported version of Electron is in use.
\nThese steps are to help app developers learn when a branch they're using becomes unsupported, but without being excessively intrusive to end users.
\nIf an application has exceptional circumstances and needs to stay on an unsupported series of Electron, developers can silence the end-of-support warning by omitting the final release from the app's package.json devDependencies. For example, since the 1-6-x series ended with an end-of-support 1.6.18 release, developers could choose to stay in the 1-6-x series without warnings with devDependency of \"electron\": 1.6.0 - 1.6.17.
Die folgenden Plattformen werden durch Electron unterstützt:
\nOnly 64bit binaries are provided for macOS, and the minimum macOS version supported is macOS 10.11 (El Capitan).
\nNative support for Apple Silicon (arm64) devices was added in Electron 11.0.0.
Windows 7 und neuere Versionen werden unterstützt. Ältere Betriebssysteme werden nicht unterstützt (und funktionieren nicht zusammen mit Electron).
\nBoth ia32 (x86) and x64 (amd64) binaries are provided for Windows. Native support for Windows on Arm (arm64) devices was added in Electron 6.0.8.. Running apps packaged with previous versions is possible using the ia32 binary.
The prebuilt binaries of Electron are built on Ubuntu 18.04.
\nOb die vorkompilierten Dateien auf einer Distribution laufen, hängt davon ab, ob die Distribution die Bibliotheken enthält, die auf der Build-Plattform verwendet wurden. Deshalb ist nur für Ubuntu 18.04 garantiert, dass es funktioniert, aber die folgenden Plattformen wurden ebenfalls bestätigt, kompatibel mit den vorkompilierten Dateien zu sein:
\n\n\nHow to use Node.js and Electron APIs.
\n
All of Node.js's built-in modules are available in Electron and third-party node modules also fully supported as well (including the native modules).
\nElectron also provides some extra built-in modules for developing native desktop applications. Some modules are only available in the main process, some are only available in the renderer process (web page), and some can be used in either process type.
\nThe basic rule is: if a module is GUI or low-level system related, then it should be only available in the main process. You need to be familiar with the concept of main process vs. renderer process scripts to be able to use those modules.
\nDas Main-Prozess Script ist wie ein normales Node.js Script:
\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL('https://github.com')\n})\nThe renderer process is no different than a normal web page, except for the extra ability to use node modules if nodeIntegration is enabled:
\n<html>\n<body>\n<script>\n const fs = require('fs')\n console.log(fs.readFileSync(__filename, 'utf8'))\n</script>\n</body>\n</html>\nAs of 0.37, you can use destructuring assignment to make it easier to use built-in modules.
\nconst { app, BrowserWindow } = require('electron')\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nWenn du das gesamte electron Module brauchst, dann kannst du dieses per require einbinden und auf einzelne electron Module per destructuring zugreifen.
const electron = require('electron')\nconst { app, BrowserWindow } = electron\n\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\nDies ist equivalent zum folgenden Code:
\nconst electron = require('electron')\nconst app = electron.app\nconst BrowserWindow = electron.BrowserWindow\nlet win\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.loadURL('https://github.com')\n})\n\n\nSystemeinstellungen anschauen.
\n
Prozess: Haupt
\nconst { systemPreferences } = require('electron')\nconsole.log(systemPreferences.isDarkMode())\nDas systemPreferences Objekt stellt folgende Event zur Verfügung:
Kehrt zurück:
\nevent EventnewColor String - The new RGBA color the user assigned to be their system accent color.Kehrt zurück:
\nevent EventKehrt zurück:
\nevent EventinvertedColorScheme Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is being used, false otherwise.Deprecated: Should use the new updated event on the nativeTheme module.
Kehrt zurück:
\nevent EventhighContrastColorScheme Boolean - true if a high contrast theme is being used, false otherwise.Deprecated: Should use the new updated event on the nativeTheme module.
systemPreferences.isDarkMode() macOS Windows DeprecatedReturns Boolean - Whether the system is in Dark Mode.
Deprecated: Should use the new nativeTheme.shouldUseDarkColors API.
systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOSReturns Boolean - Whether the Swipe between pages setting is on.
systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOSevent StringuserInfo Record<String, any>deliverImmediately Boolean (optional) - true to post notifications immediately even when the subscribing app is inactive.Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postLocalNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.postWorkspaceNotification(event, userInfo) macOSevent StringuserInfo Record<String, any>Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.
systemPreferences.subscribeNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object ZeichenketteReturns Number - The ID of this subscription
Subscribes to native notifications of macOS, callback will be called with callback(event, userInfo) when the corresponding event happens. The userInfo is an Object that contains the user information dictionary sent along with the notification. The object is the sender of the notification, and only supports NSString values for now.
The id of the subscriber is returned, which can be used to unsubscribe the event.
Under the hood this API subscribes to NSDistributedNotificationCenter, example values of event are:
AppleInterfaceThemeChangedNotificationAppleAquaColorVariantChangedAppleColorPreferencesChangedNotificationAppleShowScrollBarsSettingChangedsystemPreferences.subscribeLocalNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object ZeichenketteReturns Number - The ID of this subscription
Same as subscribeNotification, but uses NSNotificationCenter for local defaults. This is necessary for events such as NSUserDefaultsDidChangeNotification.
systemPreferences.subscribeWorkspaceNotification(event, callback) macOSevent Stringcallback Functionevent StringuserInfo Record<String, unknown>object ZeichenketteReturns Number - The ID of this subscription
Same as subscribeNotification, but uses NSWorkspace.sharedWorkspace.notificationCenter. This is necessary for events such as NSWorkspaceDidActivateApplicationNotification.
systemPreferences.unsubscribeNotification(id) macOSid IntegerRemoves the subscriber with id.
systemPreferences.unsubscribeLocalNotification(id) macOSid IntegerSame as unsubscribeNotification, but removes the subscriber from NSNotificationCenter.
systemPreferences.unsubscribeWorkspaceNotification(id) macOSid IntegerSame as unsubscribeNotification, but removes the subscriber from NSWorkspace.sharedWorkspace.notificationCenter.
systemPreferences.registerDefaults(defaults) macOSdefaults Record<String, String | Boolean | Number> - a dictionary of (key: value) user defaultsAdd the specified defaults to your application's NSUserDefaults.
systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOSkey Stringtype Type - Can be string, boolean, integer, float, double, url, array or dictionary.Returns UserDefaultTypes[Type] - The value of key in NSUserDefaults.
Some popular key and types are:
AppleInterfaceStyle: stringAppleAquaColorVariant: integerAppleHighlightColor: stringAppleShowScrollBars: stringNSNavRecentPlaces: arrayNSPreferredWebServices: dictionaryNSUserDictionaryReplacementItems: arraysystemPreferences.setUserDefault(key, type, value) macOSkey Stringtype String - Can be string, boolean, integer, float, double, url, array or dictionary.value StringSet the value of key in NSUserDefaults.
Note that type should match actual type of value. An exception is thrown if they don't.
Some popular key and types are:
ApplePressAndHoldEnabled: booleansystemPreferences.removeUserDefault(key) macOSkey StringRemoves the key in NSUserDefaults. This can be used to restore the default or global value of a key previously set with setUserDefault.
systemPreferences.isAeroGlassEnabled() WindowsReturns Boolean - true if DWM composition (Aero Glass) is enabled, and false otherwise.
An example of using it to determine if you should create a transparent window or not (transparent windows won't work correctly when DWM composition is disabled):
\nconst { BrowserWindow, systemPreferences } = require('electron')\nconst browserOptions = { width: 1000, height: 800 }\n\n// Make the window transparent only if the platform supports it.\nif (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {\n browserOptions.transparent = true\n browserOptions.frame = false\n}\n\n// Create the window.\nconst win = new BrowserWindow(browserOptions)\n\n// Navigate.\nif (browserOptions.transparent) {\n win.loadURL(`file://${__dirname}/index.html`)\n} else {\n // No transparency, so we load a fallback that uses basic styles.\n win.loadURL(`file://${__dirname}/fallback.html`)\n}\nsystemPreferences.getAccentColor() Windows macOSReturns String - The users current system wide accent color preference in RGBA hexadecimal form.
const color = systemPreferences.getAccentColor() // `\"aabbccdd\"`\nconst red = color.substr(0, 2) // \"aa\"\nconst green = color.substr(2, 2) // \"bb\"\nconst blue = color.substr(4, 2) // \"cc\"\nconst alpha = color.substr(6, 2) // \"dd\"\nThis API is only available on macOS 10.14 Mojave or newer.
\nsystemPreferences.getColor(color) Windows macOScolor String - One of the following values:3d-dark-shadow - Dark shadow for three-dimensional display elements.3d-face - Face color for three-dimensional display elements and for dialog box backgrounds.3d-highlight - Highlight color for three-dimensional display elements.3d-light - Light color for three-dimensional display elements.3d-shadow - Shadow color for three-dimensional display elements.active-border - Active window border.active-caption - Active window title bar. Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.active-caption-gradient - Right side color in the color gradient of an active window's title bar.app-workspace - Background color of multiple document interface (MDI) applications.button-text - Text on push buttons.caption-text - Text in caption, size box, and scroll bar arrow box.desktop - Desktop background color.disabled-text - Grayed (disabled) text.highlight - Item(s) selected in a control.highlight-text - Text of item(s) selected in a control.hotlight - Color for a hyperlink or hot-tracked item.inactive-border - Inactive window border.inactive-caption - Inactive window caption. Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.inactive-caption-gradient - Right side color in the color gradient of an inactive window's title bar.inactive-caption-text - Color of text in an inactive caption.info-background - Background color for tooltip controls.info-text - Text color for tooltip controls.menu - Menu background.menu-highlight - The color used to highlight menu items when the menu appears as a flat menu.menubar - The background color for the menu bar when menus appear as flat menus.menu-text - Text in menus.scrollbar - Scroll bar gray area.window - Window background.window-frame - Window frame.window-text - Text in windows.alternate-selected-control-text - The text on a selected surface in a list or table. deprecatedcontrol-background - The background of a large interface element, such as a browser or table.control - The surface of a control.control-text -The text of a control that isn’t disabled.disabled-control-text - The text of a control that’s disabled.find-highlight - The color of a find indicator.grid - The gridlines of an interface element such as a table.header-text - The text of a header cell in a table.highlight - The virtual light source onscreen.keyboard-focus-indicator - The ring that appears around the currently focused control when using the keyboard for interface navigation.label - The text of a label containing primary content.link - A link to other content.placeholder-text - A placeholder string in a control or text view.quaternary-label - The text of a label of lesser importance than a tertiary label such as watermark text.scrubber-textured-background - The background of a scrubber in the Touch Bar.secondary-label - The text of a label of lesser importance than a normal label such as a label used to represent a subheading or additional information.selected-content-background - The background for selected content in a key window or view.selected-control - The surface of a selected control.selected-control-text - The text of a selected control.selected-menu-item-text - The text of a selected menu.selected-text-background - The background of selected text.selected-text - Selected text.separator - A separator between different sections of content.shadow - The virtual shadow cast by a raised object onscreen.tertiary-label - The text of a label of lesser importance than a secondary label such as a label used to represent disabled text.text-background - Text background.text - The text in a document.under-page-background - The background behind a document's content.unemphasized-selected-content-background - The selected content in a non-key window or view.unemphasized-selected-text-background - A background for selected text in a non-key window or view.unemphasized-selected-text - Selected text in a non-key window or view.window-background - The background of a window.window-frame-text - The text in the window's titlebar area.Returns String - The system color setting in RGB hexadecimal form (#ABCDEF). See the Windows docs and the macOS docs for more details.
The following colors are only available on macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, and unemphasized-selected-text.
systemPreferences.getSystemColor(color) macOScolor String - One of the following values:bluebrowngraygreenorangepinkpurpleredyellowReturns String - The standard system color formatted as #RRGGBBAA.
Returns one of several standard system colors that automatically adapt to vibrancy and changes in accessibility settings like 'Increase contrast' and 'Reduce transparency'. See Apple Documentation for more details.
\nsystemPreferences.isInvertedColorScheme() Windows DeprecatedReturns Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is active, false otherwise.
Deprecated: Should use the new nativeTheme.shouldUseInvertedColorScheme API.
systemPreferences.isHighContrastColorScheme() macOS Windows DeprecatedReturns Boolean - true if a high contrast theme is active, false otherwise.
Deprecated: Should use the new nativeTheme.shouldUseHighContrastColors API.
systemPreferences.getEffectiveAppearance() macOSReturns String - Can be dark, light or unknown.
Gets the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance
\nsystemPreferences.getAppLevelAppearance() macOS DeprecatedReturns String | null - Can be dark, light or unknown.
Gets the macOS appearance setting that you have declared you want for your application, maps to NSApplication.appearance. You can use the setAppLevelAppearance API to set this value.
systemPreferences.setAppLevelAppearance(appearance) macOS Deprecatedappearance String | null - Can be dark or lightSets the appearance setting for your application, this should override the system default and override the value of getEffectiveAppearance.
systemPreferences.canPromptTouchID() macOSReturns Boolean - whether or not this device has the ability to use Touch ID.
NOTE: This API will return false on macOS systems older than Sierra 10.12.2.
systemPreferences.promptTouchID(reason) macOSreason String - The reason you are asking for Touch ID authenticationReturns Promise<void> - resolves if the user has successfully authenticated with Touch ID.
const { systemPreferences } = require('electron')\n\nsystemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {\n console.log('You have successfully authenticated with Touch ID!')\n}).catch(err => {\n console.log(err)\n})\nThis API itself will not protect your user data; rather, it is a mechanism to allow you to do so. Native apps will need to set Access Control Constants like kSecAccessControlUserPresence on their keychain entry so that reading it would auto-prompt for Touch ID biometric consent. This could be done with node-keytar, such that one would store an encryption key with node-keytar and only fetch it if promptTouchID() resolves.
NOTE: This API will return a rejected Promise on macOS systems older than Sierra 10.12.2.
\nsystemPreferences.isTrustedAccessibilityClient(prompt) macOSprompt Boolean - whether or not the user will be informed via prompt if the current process is untrusted.Returns Boolean - true if the current process is a trusted accessibility client and false if it is not.
systemPreferences.getMediaAccessStatus(mediaType) Windows macOSmediaType String - Can be microphone, camera or screen.Returns String - Can be not-determined, granted, denied, restricted or unknown.
This user consent was not required on macOS 10.13 High Sierra or lower so this method will always return granted. macOS 10.14 Mojave or higher requires consent for microphone and camera access. macOS 10.15 Catalina or higher requires consent for screen access.
Windows 10 has a global setting controlling microphone and camera access for all win32 applications. It will always return granted for screen and for all media types on older versions of Windows.
systemPreferences.askForMediaAccess(mediaType) macOSmediaType String - the type of media being requested; can be microphone, camera.Returns Promise<Boolean> - A promise that resolves with true if consent was granted and false if it was denied. If an invalid mediaType is passed, the promise will be rejected. If an access request was denied and later is changed through the System Preferences pane, a restart of the app will be required for the new permissions to take effect. If access has already been requested and denied, it must be changed through the preference pane; an alert will not pop up and the promise will resolve with the existing access status.
Important: In order to properly leverage this API, you must set the NSMicrophoneUsageDescription and NSCameraUsageDescription strings in your app's Info.plist file. The values for these keys will be used to populate the permission dialogs so that the user will be properly informed as to the purpose of the permission request. See Electron Application Distribution for more information about how to set these in the context of Electron.
This user consent was not required until macOS 10.14 Mojave, so this method will always return true if your system is running 10.13 High Sierra or lower.
systemPreferences.getAnimationSettings()Gibt das Object zurück:
shouldRenderRichAnimation Boolean - Returns true if rich animations should be rendered. Looks at session type (e.g. remote desktop) and accessibility settings to give guidance for heavy animations.scrollAnimationsEnabledBySystem Boolean - Determines on a per-platform basis whether scroll animations (e.g. produced by home/end key) should be enabled.prefersReducedMotion Boolean - Determines whether the user desires reduced motion based on platform APIs.Returns an object with system animation settings.
\nsystemPreferences.appLevelAppearance macOSA String property that can be dark, light or unknown. It determines the macOS appearance setting for your application. This maps to values in: NSApplication.appearance. Setting this will override the system default as well as the value of getEffectiveAppearance.
Possible values that can be set are dark and light, and possible return values are dark, light, and unknown.
This property is only available on macOS 10.14 Mojave or newer.
\nsystemPreferences.effectiveAppearance macOS ReadonlyA String property that can be dark, light or unknown.
Returns the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance
", "title": "systemPreferences", "description": "Systemeinstellungen anschauen." }, "/docs/api/structures/task": { "locale": "de-DE", "slug": "task", "href": "/docs/api/structures/task", "crowdinFileId": "256513", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/structures/task.md", "category": "api/structures", "categoryFancy": "API Structures", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": true, "isDevTutorial": false, "html": "program String - Path of the program to execute, usually you should specify process.execPath which opens the current program.arguments String - The command line arguments when program is executed.title String - The string to be displayed in a JumpList.description String - Description of this task.iconPath String - The absolute path to an icon to be displayed in a JumpList, which can be an arbitrary resource file that contains an icon. You can usually specify process.execPath to show the icon of the program.iconIndex Number - The icon index in the icon file. If an icon file consists of two or more icons, set this value to identify the icon. If an icon file consists of one icon, this value is 0.workingDirectory String (optional) - The working directory. Default is empty.We aim to keep the code coverage of Electron high. We ask that all pull request not only pass all existing tests, but ideally also add new tests to cover changed code and new scenarios. Ensuring that we capture as many code paths and use cases of Electron as possible ensures that we all ship apps with fewer bugs.
\nThis repository comes with linting rules for both JavaScript and C++ – as well as unit and integration tests. To learn more about Electron's coding style, please see the coding-style document.
\nTo ensure that your JavaScript is in compliance with the Electron coding style, run npm run lint-js, which will run standard against both Electron itself as well as the unit tests. If you are using an editor with a plugin/addon system, you might want to use one of the many StandardJS addons to be informed of coding style violations before you ever commit them.
To run standard with parameters, run npm run lint-js -- followed by arguments you want passed to standard.
To ensure that your C++ is in compliance with the Electron coding style, run npm run lint-cpp, which runs a cpplint script. We recommend that you use clang-format and prepared a short tutorial.
There is not a lot of Python in this repository, but it too is governed by coding style rules. npm run lint-py will check all Python, using pylint to do so.
If you are not using build-tools, ensure that that name you have configured for your local build of Electron is one of Testing, Release, Default, Debug, or you have set process.env.ELECTRON_OUT_DIR. Without these set, Electron will fail to perform some pre-testing steps.
To run all unit tests, run npm run test. The unit tests are an Electron app (surprise!) that can be found in the spec folder. Note that it has its own package.json and that its dependencies are therefore not defined in the top-level package.json.
To run only specific tests matching a pattern, run npm run test -- -g=PATTERN, replacing the PATTERN with a regex that matches the tests you would like to run. As an example: If you want to run only IPC tests, you would run npm run test -- -g ipc.
Visual Studio 2019 muss installiert sein.
\nNode-Header müssen für Ihre Konfiguration kompiliert werden.
\nninja -C out\\Testing third_party\\electron_node:headers\nDie electron.lib muss als node.lib kopiert werden.
\ncd out\\Testing\nmkdir gen\\node_headers\\Release\ncopy electron.lib gen\\node_headers\\Release\\node.lib\nSome Windows 10 devices do not ship with the Meiryo font installed, which may cause a font fallback test to fail. To install Meiryo:
\nSome tests which rely on precise pixel measurements may not work correctly on devices with Hi-DPI screen settings due to floating point precision errors. To run these tests correctly, make sure the device is set to 100% scaling.
\nTo configure display scaling:
\nBeing based on Chromium, Electron requires a display driver to function. If Chromium can't find a display driver, Electron will fail to launch - and therefore not executing any of your tests, regardless of how you are running them. Testing Electron-based apps on Travis, Circle, Jenkins or similar Systems requires therefore a little bit of configuration. In essence, we need to use a virtual display driver.
\nFirst, install Xvfb. It's a virtual framebuffer, implementing the X11 display server protocol - it performs all graphical operations in memory without showing any screen output, which is exactly what we need.
\nThen, create a virtual Xvfb screen and export an environment variable called DISPLAY that points to it. Chromium in Electron will automatically look for $DISPLAY, so no further configuration of your app is required. This step can be automated with Anaïs Betts' xvfb-maybe: Prepend your test commands with xvfb-maybe and the little tool will automatically configure Xvfb, if required by the current system. On Windows or macOS, it will do nothing.
## On Windows or macOS, this invokes electron-mocha\n## On Linux, if we are in a headless environment, this will be equivalent\n## to xvfb-run electron-mocha ./test/*.js\nxvfb-maybe electron-mocha ./test/*.js\nOn Travis, your .travis.yml should look roughly like this:
addons:\n apt:\n packages:\n - xvfb\n\ninstall:\n - export DISPLAY=':99.0'\n - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &\nFor Jenkins, a Xvfb plugin is available.
\nCircle CI is awesome and has Xvfb and $DISPLAY already set up, so no further configuration is required.
AppVeyor runs on Windows, supporting Selenium, Chromium, Electron and similar tools out of the box - no configuration is required.
", "title": "Testing on Headless CI Systems (Travis CI, Jenkins)", "description": "" }, "/docs/tutorial/testing-widevine-cdm": { "locale": "de-DE", "slug": "testing-widevine-cdm", "href": "/docs/tutorial/testing-widevine-cdm", "crowdinFileId": "256257", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/testing-widevine-cdm.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "In Electron you can use the Widevine CDM library shipped with Chrome browser.
\nWidevine Content Decryption Modules (CDMs) are how streaming services protect content using HTML5 video to web browsers without relying on an NPAPI plugin like Flash or Silverlight. Widevine support is an alternative solution for streaming services that currently rely on Silverlight for playback of DRM-protected video content. It will allow websites to show DRM-protected video content in Firefox without the use of NPAPI plugins. The Widevine CDM runs in an open-source CDM sandbox providing better user security than NPAPI plugins.
\nAs of Electron v1.8.0 (Chrome v59), the below steps are may only be some of the necessary steps to enable Widevine; any app on or after that version intending to use the Widevine CDM may need to be signed using a license obtained from Widevine itself.
Per Widevine:
\n\n\nChrome 59 (and later) includes support for Verified Media Path (VMP). VMP provides a method to verify the authenticity of a device platform. For browser deployments, this will provide an additional signal to determine if a browser-based implementation is reliable and secure.
\nThe proxy integration guide has been updated with information about VMP and how to issue licenses.
\nWidevine recommends our browser-based integrations (vendors and browser-based applications) add support for VMP.
\n
To enable video playback with this new restriction, castLabs has created a fork that has implemented the necessary changes to enable Widevine to be played in an Electron application if one has obtained the necessary licenses from widevine.
\nOpen chrome://components/ in Chrome browser, find Widevine Content Decryption Module and make sure it is up to date, then you can find the library files from the application directory.
The library file widevinecdm.dll will be under Program Files(x86)/Google/Chrome/Application/CHROME_VERSION/WidevineCdm/_platform_specific/win_(x86|x64)/ directory.
The library file libwidevinecdm.dylib will be under /Applications/Google Chrome.app/Contents/Versions/CHROME_VERSION/Google Chrome Framework.framework/Versions/A/Libraries/WidevineCdm/_platform_specific/mac_(x86|x64)/ directory.
Note: Make sure that chrome version used by Electron is greater than or equal to the min_chrome_version value of Chrome's widevine cdm component. The value can be found in manifest.json under WidevineCdm directory.
After getting the library files, you should pass the path to the file with --widevine-cdm-path command line switch, and the library's version with --widevine-cdm-version switch. The command line switches have to be passed before the ready event of app module gets emitted.
Example code:
\nconst { app, BrowserWindow } = require('electron')\n\n// You have to pass the directory that contains widevine library here, it is\n// * `libwidevinecdm.dylib` on macOS,\n// * `widevinecdm.dll` on Windows.\napp.commandLine.appendSwitch('widevine-cdm-path', '/path/to/widevine_library')\n// Die Version des Plugins kann von der Seite `chrome://components` in Chrome erhalten werden.\napp.commandLine.appendSwitch('widevine-cdm-version', '1.4.8.866')\n\nlet win = null\napp.whenReady().then(() => {\n win = new BrowserWindow()\n win.show()\n})\nTo verify whether widevine works, you can use following ways:
\nWidevine.bitdash uses Widevine in your browser, then play the video.icon NativeImage - The icon showing in thumbnail toolbar.click Functiontooltip String (optional) - The text of the button's tooltip.flags String - Control specific states and behaviors of the button. By default, it is ['enabled'].The flags is an array that can include following Strings:
enabled - The button is active and available to the user.disabled - The button is disabled. It is present, but has a visual state indicating it will not respond to user action.dismissonclick - When the button is clicked, the thumbnail window closes immediately.nobackground - Do not draw a button border, use only the image.hidden - The button is not shown to the user.noninteractive - The button is enabled but not interactive; no pressed button state is drawn. This value is intended for instances where the button is used in a notification.\n\nCreate TouchBar layouts for native macOS applications
\n
Prozess: Haupt
\nnew TouchBar(options)options Objektitems (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer)escapeItem (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer | null) (optional)Creates a new touch bar with the specified items. Use BrowserWindow.setTouchBar to add the TouchBar to a window.
Note: The TouchBar API is currently experimental and may change or be removed in future Electron releases.
\nTip: If you don't have a MacBook with Touch Bar, you can use Touch Bar Simulator to test Touch Bar usage in your app.
\nTouchBarButtonA typeof TouchBarButton reference to the TouchBarButton class.
TouchBarColorPickerA typeof TouchBarColorPicker reference to the TouchBarColorPicker class.
TouchBarGroupA typeof TouchBarGroup reference to the TouchBarGroup class.
TouchBarLabelA typeof TouchBarLabel reference to the TouchBarLabel class.
TouchBarPopoverA typeof TouchBarPopover reference to the TouchBarPopover class.
TouchBarScrubberA typeof TouchBarScrubber reference to the TouchBarScrubber class.
TouchBarSegmentedControlA typeof TouchBarSegmentedControl reference to the TouchBarSegmentedControl class.
TouchBarSliderA typeof TouchBarSlider reference to the TouchBarSlider class.
TouchBarSpacerA typeof TouchBarSpacer reference to the TouchBarSpacer class.
TouchBarOtherItemsProxyA typeof TouchBarOtherItemsProxy reference to the TouchBarOtherItemsProxy class.
The following properties are available on instances of TouchBar:
touchBar.escapeItemA TouchBarItem that will replace the \"esc\" button on the touch bar when set. Setting to null restores the default \"esc\" button. Changing this value immediately updates the escape item in the touch bar.
Below is an example of a simple slot machine touch bar game with a button and some labels.
\nconst { app, BrowserWindow, TouchBar } = require('electron')\n\nconst { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar\n\nlet spinning = false\n\n// Reel labels\nconst reel1 = new TouchBarLabel()\nconst reel2 = new TouchBarLabel()\nconst reel3 = new TouchBarLabel()\n\n// Spin result label\nconst result = new TouchBarLabel()\n\n// Spin button\nconst spin = new TouchBarButton({\n label: '🎰 Spin',\n backgroundColor: '#7851A9',\n click: () => {\n // Ignore clicks if already spinning\n if (spinning) {\n return\n }\n\n spinning = true\n result.label = ''\n\n let timeout = 10\n const spinLength = 4 * 1000 // 4 seconds\n const startTime = Date.now()\n\n const spinReels = () => {\n updateReels()\n\n if ((Date.now() - startTime) >= spinLength) {\n finishSpin()\n } else {\n // Slow down a bit on each spin\n timeout *= 1.1\n setTimeout(spinReels, timeout)\n }\n }\n\n spinReels()\n }\n})\n\nconst getRandomValue = () => {\n const values = ['🍒', '💎', '7️⃣', '🍊', '🔔', '⭐', '🍇', '🍀']\n return values[Math.floor(Math.random() * values.length)]\n}\n\nconst updateReels = () => {\n reel1.label = getRandomValue()\n reel2.label = getRandomValue()\n reel3.label = getRandomValue()\n}\n\nconst finishSpin = () => {\n const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size\n if (uniqueValues === 1) {\n // All 3 values are the same\n result.label = '💰 Jackpot!'\n result.textColor = '#FDFF00'\n } else if (uniqueValues === 2) {\n // 2 values are the same\n result.label = '😍 Winner!'\n result.textColor = '#FDFF00'\n } else {\n // No values are the same\n result.label = '🙁 Spin Again'\n result.textColor = null\n }\n spinning = false\n}\n\nconst touchBar = new TouchBar({\n items: [\n spin,\n new TouchBarSpacer({ size: 'large' }),\n reel1,\n new TouchBarSpacer({ size: 'small' }),\n reel2,\n new TouchBarSpacer({ size: 'small' }),\n reel3,\n new TouchBarSpacer({ size: 'large' }),\n result\n ]\n})\n\nlet window\n\napp.whenReady().then(() => {\n window = new BrowserWindow({\n frame: false,\n titleBarStyle: 'hiddenInset',\n width: 200,\n height: 200,\n backgroundColor: '#000'\n })\n window.loadURL('about:blank')\n window.setTouchBar(touchBar)\n})\nTo run the example above, you'll need to (assuming you've got a terminal open in the directory you want to run the example):
\ntouchbar.jsnpm install electron./node_modules/.bin/electron touchbar.jsYou should then see a new Electron window and the app running in your touch bar (or touch bar emulator).
", "title": "TouchBar", "description": "Create TouchBar layouts for native macOS applications" }, "/docs/api/touch-bar-button": { "locale": "de-DE", "slug": "touch-bar-button", "href": "/docs/api/touch-bar-button", "crowdinFileId": "256375", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/touch-bar-button.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nCreate a button in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarButton(options)options Objektlabel String (optional) - Button text.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.backgroundColor String (optional) - Button background color in hex format, i.e #ABCDEF.icon NativeImage | String (optional) - Button icon.iconPosition String (optional) - Can be left, right or overlay. Standardwert ist overlay.click Function (optional) - Function to call when the button is clicked.enabled Boolean (optional) - Whether the button is in an enabled state. Standard ist true.When defining accessibilityLabel, ensure you have considered macOS best practices.
The following properties are available on instances of TouchBarButton:
touchBarButton.accessibilityLabelA String representing the description of the button to be read by a screen reader. Will only be read by screen readers if no label is set.
touchBarButton.labelA String representing the button's current text. Changing this value immediately updates the button in the touch bar.
touchBarButton.backgroundColorA String hex code representing the button's current background color. Changing this value immediately updates the button in the touch bar.
touchBarButton.iconA NativeImage representing the button's current icon. Changing this value immediately updates the button in the touch bar.
touchBarButton.iconPositionA String - Can be left, right or overlay. Standardwert ist overlay.
touchBarButton.enabledA Boolean representing whether the button is in an enabled state.
\n\nCreate a color picker in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarColorPicker(options)options ObjektavailableColors String - Array of hex color strings to appear as possible colors to select.selectedColor String (optional) - The selected hex color in the picker, i.e #ABCDEF.change Function (optional) - Function to call when a color is selected.color String - The color that the user selected from the picker.The following properties are available on instances of TouchBarColorPicker:
touchBarColorPicker.availableColorsA String[] array representing the color picker's available colors to select. Changing this value immediately updates the color picker in the touch bar.
touchBarColorPicker.selectedColorA String hex code representing the color picker's currently selected color. Changing this value immediately updates the color picker in the touch bar.
\n\nCreate a group in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarGroup(options)options Objektitems TouchBar - Items to display as a group.\n\nCreate a label in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarLabel(options)options Objektlabel String (optional) - Text to display.accessibilityLabel String (optional) - A short description of the button for use by screenreaders like VoiceOver.textColor String (optional) - Hex color of text, i.e #ABCDEF.When defining accessibilityLabel, ensure you have considered macOS best practices.
The following properties are available on instances of TouchBarLabel:
touchBarLabel.labelA String representing the label's current text. Changing this value immediately updates the label in the touch bar.
touchBarLabel.accessibilityLabelA String representing the description of the label to be read by a screen reader.
touchBarLabel.textColorA String hex code representing the label's current text color. Changing this value immediately updates the label in the touch bar.
\n\nInstantiates a special \"other items proxy\", which nests TouchBar elements inherited from Chromium at the space indicated by the proxy. By default, this proxy is added to each TouchBar at the end of the input. For more information, see the AppKit docs on NSTouchBarItemIdentifierOtherItemsProxy
\nNote: Only one instance of this class can be added per TouchBar.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarOtherItemsProxy()\n\nCreate a popover in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarPopover(options)options Objektlabel String (optional) - Popover button text.icon NativeImage (optional) - Popover button icon.items TouchBar - Items to display in the popover.showCloseButton Boolean (optional) - true to display a close button on the left of the popover, false to not show it. Standard ist true.The following properties are available on instances of TouchBarPopover:
touchBarPopover.labelA String representing the popover's current button text. Changing this value immediately updates the popover in the touch bar.
touchBarPopover.iconA NativeImage representing the popover's current button icon. Changing this value immediately updates the popover in the touch bar.
\n\nCreate a scrubber (a scrollable selector)
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarScrubber(options)options Objektitems ScrubberItem[] - An array of items to place in this scrubber.select Function (optional) - Called when the user taps an item that was not the last tapped item.selectedIndex Integer - The index of the item the user selected.highlight Function (optional) - Called when the user taps any item.highlightedIndex Integer - The index of the item the user touched.selectedStyle String (optional) - Selected item style. Can be background, outline or none. Standardwert ist none.overlayStyle String (optional) - Selected overlay item style. Can be background, outline or none. Standardwert ist none.showArrowButtons Boolean (optional) - Whether to show arrow buttons. Defaults to false and is only shown if items is non-empty.mode String (optional) - Kann fixed oder free sein. The default is free.continuous Boolean (optional) - Defaults to true.The following properties are available on instances of TouchBarScrubber:
touchBarScrubber.itemsA ScrubberItem[] array representing the items in this scrubber. Updating this value immediately updates the control in the touch bar. Updating deep properties inside this array does not update the touch bar.
touchBarScrubber.selectedStyleA String representing the style that selected items in the scrubber should have. Updating this value immediately updates the control in the touch bar. Mögliche werte:
background - Maps to [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Maps to [NSScrubberSelectionStyle outlineOverlayStyle].none - Removes all styles.touchBarScrubber.overlayStyleA String representing the style that selected items in the scrubber should have. This style is overlayed on top of the scrubber item instead of being placed behind it. Updating this value immediately updates the control in the touch bar. Mögliche werte:
background - Maps to [NSScrubberSelectionStyle roundedBackgroundStyle].outline - Maps to [NSScrubberSelectionStyle outlineOverlayStyle].none - Removes all styles.touchBarScrubber.showArrowButtonsA Boolean representing whether to show the left / right selection arrows in this scrubber. Updating this value immediately updates the control in the touch bar.
touchBarScrubber.modeA String representing the mode of this scrubber. Updating this value immediately updates the control in the touch bar. Mögliche werte:
fixed - Maps to NSScrubberModeFixed.free - Maps to NSScrubberModeFree.touchBarScrubber.continuousA Boolean representing whether this scrubber is continuous or not. Updating this value immediately updates the control in the touch bar.
\n\nCreate a segmented control (a button group) where one button has a selected state
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSegmentedControl(options)options ObjektsegmentStyle String (optional) - Style of the segments:automatic - Default. The appearance of the segmented control is automatically determined based on the type of window in which the control is displayed and the position within the window. Maps to NSSegmentStyleAutomatic.rounded - The control is displayed using the rounded style. Maps to NSSegmentStyleRounded.textured-rounded - The control is displayed using the textured rounded style. Maps to NSSegmentStyleTexturedRounded.round-rect - The control is displayed using the round rect style. Maps to NSSegmentStyleRoundRect.textured-square - The control is displayed using the textured square style. Maps to NSSegmentStyleTexturedSquare.capsule - The control is displayed using the capsule style. Maps to NSSegmentStyleCapsule.small-square - The control is displayed using the small square style. Maps to NSSegmentStyleSmallSquare.separated - The segments in the control are displayed very close to each other but not touching. Maps to NSSegmentStyleSeparated.mode String (optional) - The selection mode of the control:single - Default. One item selected at a time, selecting one deselects the previously selected item. Maps to NSSegmentSwitchTrackingSelectOne.multiple - Multiple items can be selected at a time. Maps to NSSegmentSwitchTrackingSelectAny.buttons - Make the segments act as buttons, each segment can be pressed and released but never marked as active. Maps to NSSegmentSwitchTrackingMomentary.segments SegmentedControlSegment[] - An array of segments to place in this control.selectedIndex Integer (optional) - The index of the currently selected segment, will update automatically with user interaction. When the mode is multiple it will be the last selected item.change Function (optional) - Called when the user selects a new segment.selectedIndex Integer - The index of the segment the user selected.isSelected Boolean - Whether as a result of user selection the segment is selected or not.The following properties are available on instances of TouchBarSegmentedControl:
touchBarSegmentedControl.segmentStyleA String representing the controls current segment style. Updating this value immediately updates the control in the touch bar.
touchBarSegmentedControl.segmentsA SegmentedControlSegment[] array representing the segments in this control. Updating this value immediately updates the control in the touch bar. Updating deep properties inside this array does not update the touch bar.
touchBarSegmentedControl.selectedIndexAn Integer representing the currently selected segment. Changing this value immediately updates the control in the touch bar. User interaction with the touch bar will update this value automatically.
touchBarSegmentedControl.modeA String representing the current selection mode of the control. Can be single, multiple or buttons.
\n\nCreate a slider in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSlider(options)options Objektlabel String (optional) - Label text.value Integer (optional) - Selected value.minValue Integer (optional) - Minimum value.maxValue Integer (optional) - Maximum value.change Function (optional) - Function to call when the slider is changed.newValue Number - The value that the user selected on the Slider.The following properties are available on instances of TouchBarSlider:
touchBarSlider.labelA String representing the slider's current text. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.valueA Number representing the slider's current value. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.minValueA Number representing the slider's current minimum value. Changing this value immediately updates the slider in the touch bar.
touchBarSlider.maxValueA Number representing the slider's current maximum value. Changing this value immediately updates the slider in the touch bar.
\n\nCreate a spacer between two items in the touch bar for native macOS applications
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
new TouchBarSpacer(options)options Objektsize String (optional) - Size of spacer, possible values are:small - Small space between items. Maps to NSTouchBarItemIdentifierFixedSpaceSmall. This is the default.large - Large space between items. Maps to NSTouchBarItemIdentifierFixedSpaceLarge.flexible - Take up all available space. Maps to NSTouchBarItemIdentifierFlexibleSpace.The following properties are available on instances of TouchBarSpacer:
touchBarSpacer.sizeA String representing the size of the spacer. Can be small, large or flexible.
categoryFilter String - A filter to control what category groups should be traced. A filter can have an optional '-' prefix to exclude category groups that contain a matching category. Having both included and excluded category patterns in the same list is not supported. Examples: test_MyTest*, test_MyTest*,test_OtherStuff, -excluded_category1,-excluded_category2.traceOptions String - Controls what kind of tracing is enabled, it is a comma-delimited sequence of the following strings: record-until-full, record-continuously, trace-to-console, enable-sampling, enable-systrace, e.g. 'record-until-full,enable-sampling'. The first 3 options are trace recording modes and hence mutually exclusive. If more than one trace recording modes appear in the traceOptions string, the last one takes precedence. If none of the trace recording modes are specified, recording mode is record-until-full. The trace option will first be reset to the default option (record_mode set to record-until-full, enable_sampling and enable_systrace set to false) before options parsed from traceOptions are applied on it.recording_mode String (optional) - Can be record-until-full, record-continuously, record-as-much-as-possible or trace-to-console. Defaults to record-until-full.trace_buffer_size_in_kb number (optional) - maximum size of the trace recording buffer in kilobytes. Defaults to 100MB.trace_buffer_size_in_events number (optional) - maximum size of the trace recording buffer in events.enable_argument_filter boolean (optional) - if true, filter event data according to a specific list of events that have been manually vetted to not include any PII. See the implementation in Chromium for specifics.included_categories String - a list of tracing categories to include. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.excluded_categories String - a list of tracing categories to exclude. Can include glob-like patterns using * at the end of the category name. See tracing categories for the list of categories.included_process_ids number - a list of process IDs to include in the trace. If not specified, trace all processes.histogram_names String - a list of histogram names to report with the trace.memory_dump_config Record<String, any> (optional) - if the disabled-by-default-memory-infra category is enabled, this contains optional additional configuration for data collection. See the Chromium memory-infra docs for more information.An example TraceConfig that roughly matches what Chrome DevTools records:
\n{\n recording_mode: 'record-until-full',\n included_categories: [\n 'devtools.timeline',\n 'disabled-by-default-devtools.timeline',\n 'disabled-by-default-devtools.timeline.frame',\n 'disabled-by-default-devtools.timeline.stack',\n 'v8.execute',\n 'blink.console',\n 'blink.user_timing',\n 'latencyInfo',\n 'disabled-by-default-v8.cpu_profiler',\n 'disabled-by-default-v8.cpu_profiler.hires'\n ],\n excluded_categories: ['*']\n}\ntransactionIdentifier String - A string that uniquely identifies a successful payment transaction.transactionDate String - The date the transaction was added to the App Store’s payment queue.originalTransactionIdentifier String - The identifier of the restored transaction by the App Store.transactionState String - The transaction state, can be purchasing, purchased, failed, restored or deferred.errorCode Integer - The error code if an error occurred while processing the transaction.errorMessage String - The error message if an error occurred while processing the transaction.payment ObjectproductIdentifier String - The identifier of the purchased product.quantity Integer - The quantity purchased.\n\nFügen Sie Symbole und Kontextmenüs in den Benachrichtigungsbereich des Systems hinzu.
\n
Prozess: Haupt
\nTray ist ein EventEmitter.
const { app, Menu, Tray } = require('electron')\n\nlet tray = null\napp.whenReady().then(() => {\n tray = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n ])\n tray.setToolTip('This is my application.')\n tray.setContextMenu(contextMenu)\n})\nPlattform-Einschränkungen:
\nGtkStatusIcon verwendet.libappindicator1 to make the tray icon work.click Ereignis ignoriert.MenuItems to take effect, you have to call setContextMenu again. Ein Beispiel:const { app, Menu, Tray } = require('electron')\n\nlet appIcon = null\napp.whenReady().then(() => {\n appIcon = new Tray('/path/to/my/icon')\n const contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' }\n ])\n\n // Make a change to the context menu\n contextMenu.items[1].checked = false\n\n // Call this again for Linux because we modified the context menu\n appIcon.setContextMenu(contextMenu)\n})\nICO Icons zu verwenden, um beste visuelle Effekte zu erhalten.If you want to keep exact same behaviors on all platforms, you should not rely on the click event and always attach a context menu to the tray icon.
new Tray(image, [guid])image (NativeImage | String)guid String (optional) Windows - Assigns a GUID to the tray icon. If the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. OS level settings like the position of the tray icon in the system tray will persist even if the path to the executable changes. If the executable is not code-signed then the GUID is permanently associated with the path to the executable. Changing the path to the executable will break the creation of the tray icon and a new GUID must be used. However, it is highly recommended to use the GUID parameter only in conjunction with code-signed executable. If an App defines multiple tray icons then each icon must use a separate GUID.Creates a new tray icon associated with the image.
Das Tray Modul sendet folgende Ereignisse aus:
Kehrt zurück:
\nevent KeyboardEventbounds Rechteck - Die Grenzen des Tray-Symbols.position Punkt - Die Position des Events.Wird beim Klicken des Tray Icons gesendet.
\nKehrt zurück:
\nevent KeyboardEventbounds Rechteck - Die Grenzen des Tray-Symbols.Wird durch einen Rechts Klick auf das Tray Icon gesendet.
\nKehrt zurück:
\nevent KeyboardEventbounds Rechteck - Die Grenzen des Tray-Symbols.Emitted when the tray icon is double clicked.
\nEmitted when the tray balloon shows.
\nEmitted when the tray balloon is clicked.
\nEmitted when the tray balloon is closed because of timeout or user manually closes it.
\nEmitted when any dragged items are dropped on the tray icon.
\nKehrt zurück:
\nevent Eventfiles String[] - The paths of the dropped files.Emitted when dragged files are dropped in the tray icon.
\nKehrt zurück:
\nevent Eventtext String - the dropped text string.Emitted when dragged text is dropped in the tray icon.
\nEmitted when a drag operation enters the tray icon.
\nEmitted when a drag operation exits the tray icon.
\nEmitted when a drag operation ends on the tray or ends at another location.
\nKehrt zurück:
\nevent KeyboardEventposition Punkt - Die Position des Events.Emitted when the mouse is released from clicking the tray icon.
\nNote: This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.
Kehrt zurück:
\nevent KeyboardEventposition Punkt - Die Position des Events.Emitted when the mouse clicks the tray icon.
\nKehrt zurück:
\nevent KeyboardEventposition Punkt - Die Position des Events.Emitted when the mouse enters the tray icon.
\nKehrt zurück:
\nevent KeyboardEventposition Punkt - Die Position des Events.Emitted when the mouse exits the tray icon.
\nKehrt zurück:
\nevent KeyboardEventposition Punkt - Die Position des Events.Emitted when the mouse moves in the tray icon.
\nThe Tray class has the following methods:
tray.destroy()Destroys the tray icon immediately.
\ntray.setImage(image)image (NativeImage | String)Sets the image associated with this tray icon.
tray.setPressedImage(image) macOSimage (NativeImage | String)Sets the image associated with this tray icon when pressed on macOS.
tray.setToolTip(toolTip)toolTip StringLegt den Hover-Text für dieses Tray-Symbol fest.
\ntray.setTitle(title[, options]) macOStitle Stringoptions Object (optional)fontType String (optional) - The font family variant to display, can be monospaced or monospacedDigit. monospaced is available in macOS 10.15+ and monospacedDigit is available in macOS 10.11+. When left blank, the title uses the default system font.Legt den Titel fest, der neben dem Tray Icon in der Statusleiste angezeigt wird (Unterstütz ANSI-Farben).
\ntray.getTitle() macOSReturns String - the title displayed next to the tray icon in the status bar
tray.setIgnoreDoubleClickEvents(ignore) macOSignore BooleanSets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.
\nThis value is set to false by default.
\ntray.getIgnoreDoubleClickEvents() macOSReturns Boolean - Whether double click events will be ignored.
tray.displayBalloon(options) Windowsoptions Objekticon (NativeImage | String) (optional) - Icon to use when iconType is custom.iconType String (optional) - Can be none, info, warning, error or custom. Standard ist custom.title Stringcontent StringlargeIcon Boolean (optional) - The large version of the icon should be used. Standard ist true. Maps to NIIF_LARGE_ICON.noSound Boolean (optional) - Do not play the associated sound. Standard ist false. Maps to NIIF_NOSOUND.respectQuietTime Boolean (optional) - Do not display the balloon notification if the current user is in \"quiet time\". Standard ist false. Maps to NIIF_RESPECT_QUIET_TIME.Displays a tray balloon.
\ntray.removeBalloon() WindowsRemoves a tray balloon.
\ntray.focus() WindowsReturns focus to the taskbar notification area. Notification area icons should use this message when they have completed their UI operation. For example, if the icon displays a shortcut menu, but the user presses ESC to cancel it, use tray.focus() to return focus to the notification area.
tray.popUpContextMenu([menu, position]) macOS Windowsmenu Menü (optional)position Punkt (optional) - Die Pop-up-Position.Pops up the context menu of the tray icon. When menu is passed, the menu will be shown instead of the tray icon's context menu.
Die position ist nur unter Windows verfügbar und ist standardmäßig (0, 0).
tray.closeContextMenu() macOS WindowsCloses an open context menu, as set by tray.setContextMenu().
tray.setContextMenu(menu)menu Menu | nullLegt das Kontextmenü für dieses Symbol fest.
\ntray.getBounds() macOS WindowsGibt Rectangle zurück
The bounds of this tray icon as Object.
tray.isDestroyed()Returns Boolean - Whether the tray icon is destroyed.
title: Fach\ndescription: This guide will take you through the process of creating a Tray icon with its own context menu to the system's notification area.\nslug: fach
\nThis guide will take you through the process of creating a Tray icon with its own context menu to the system's notification area.
\nOn MacOS and Ubuntu, the Tray will be located on the top right corner of your screen, adjacent to your battery and wifi icons. On Windows, the Tray will usually be located in the bottom right corner.
\nFirst we must import app, Tray, Menu, nativeImage from electron.
const { app, Tray, Menu, nativeImage } = require('electron')\nNext we will create our Tray. To do this, we will use a NativeImage icon, which can be created through any one of these methods. Note that we wrap our Tray creation code within an app.whenReady as we will need to wait for our electron app to finish initializing.
let tray\n\napp.whenReady().then(() => {\n const icon = nativeImage.createFromPath('path/to/asset.png')\n tray = new Tray(icon)\n\n // note: your contextMenu, Tooltip and Title code will go here!\n})\nGreat! Now we can start attaching a context menu to our Tray, like so:
\nconst contextMenu = Menu.buildFromTemplate([\n { label: 'Item1', type: 'radio' },\n { label: 'Item2', type: 'radio' },\n { label: 'Item3', type: 'radio', checked: true },\n { label: 'Item4', type: 'radio' }\n])\n\ntray.setContextMenu(contextMenu)\nThe code above will create 4 separate radio-type items in the context menu. To read more about constructing native menus, click here.
\nFinally, let's give our tray a tooltip and a title.
\ntray.setToolTip('This is my application')\ntray.setTitle('This is my title')\nAfter you start your electron app, you should see the Tray residing in either the top or bottom right of your screen, depending on your operating system.\nfiddle docs/fiddles/native-ui/tray
Electron-Apps können auf verschiedenste Weise aktualisiert werden. Die einfachste und offiziell unterstützte ist, die Vorteile des eingebauten Squirrel-Frameworks und Electrons autoUpdater-Moduls zu nutzen.
\nupdate.electronjs.orgThe Electron team maintains update.electronjs.org, a free and open-source webservice that Electron apps can use to self-update. Der Service ist für Electron-Apps, die die folgenden Kriterien erfüllen ausgelegt:
\nAm einfachsten können Sie diesen Service nutzen, indem Sie update-electron-app installieren, ein Node.js-Modul, das für die Verwendung mit update.electronjs.org vorkonfiguriert ist.
\nInstalliere das Modul:
\nnpm install update-electron-app\nRufen Sie den Updater über die Hauptprozessdatei Ihrer App auf:
\nrequire('update-electron-app')()\nBy default, this module will check for updates at app startup, then every ten minutes. When an update is found, it will automatically be downloaded in the background. When the download completes, a dialog is displayed allowing the user to restart the app.
\nWenn Sie Ihre Konfiguration anpassen müssen, übergeben Sie Optionen an update-electron-app oder nutzen Sie den Update-Dienst direkt.
Wenn Sie eine private Electron-Anwendung entwickeln oder wenn Sie sie nicht auf GitHub Releases veröffentlichen, könnte notwendig sein, Ihren eigenen Update-Server bereitzustellen.
\nAbhängig von Ihren Ansprüchen können Sie einen der folgenden Server nutzen:
\nWenn Sie Ihren Update-Server aufgesetzt haben, fahren Sie mit dem Importieren der erforderlichen Module in Ihrem Code fort. Der folgende Code kann etwas abweichen für die verschiedenen Server, aber er funktioniert wie beschrieben bei der Verwendung von Hazel.
\nWichtig: Bitte stellen Sie sicher, das der Code nur in Ihrer gepackten App ausgeführt wird und nicht in der Entwicklungsumgebung. Sie können electron-is-dev nutzen, um Ihre Entwicklungsumgebung zu überprüfen.
\nconst { app, autoUpdater, dialog } = require('electron')\nAls nächstes, stellen Sie die URL des Update-Servers bereit und stellen Sie diese dem autoUpdater zur Verfügung:
\nconst server = 'https://your-deployment-url.com'\nconst url = `${server}/update/${process.platform}/${app.getVersion()}`\n\nautoUpdater.setFeedURL({ url })\nAs the final step, check for updates. The example below will check every minute:
\nsetInterval(() => {\n autoUpdater.checkForUpdates()\n}, 60000)\nOnce your application is packaged, it will receive an update for each new GitHub Release that you publish.
\nNun, da Sie den grundlegenden Update-Mechanismus konfiguriert haben, müssen Sie sicherstellen, dass die Nutzer benachrichtigt werden, wenn es ein Update gibt. Das kann erreicht werden, indem man die API events des autoUpdater nutzt:
\nautoUpdater.on('update-downloaded', (event, releaseNotes, releaseName) => {\n const dialogOpts = {\n type: 'info',\n buttons: ['Restart', 'Later'],\n title: 'Application Update',\n message: process.platform === 'win32' ? releaseNotes : releaseName,\n detail: 'A new version has been downloaded. Restart the application to apply the updates.'\n }\n\n dialog.showMessageBox(dialogOpts).then((returnValue) => {\n if (returnValue.response === 0) autoUpdater.quitAndInstall()\n })\n})\nAlso make sure that errors are being handled. Here's an example for logging them to stderr:
autoUpdater.on('error', message => {\n console.error('There was a problem updating the application')\n console.error(message)\n})\nBecause the requests made by Auto Update aren't under your direct control, you may find situations that are difficult to handle (such as if the update server is behind authentication). The url field does support files, which means that with some effort, you can sidestep the server-communication aspect of the process. Here's an example of how this could work.
bytes Buffer - Content being sent.file String (optional) - Path of file being uploaded.blobUUID String (optional) - UUID of blob data. Use ses.getBlobData method to retrieve the data.type 'file' - file.filePath String - Path of file to be uploaded.offset Integer - Defaults to 0.length Integer - Number of bytes to read from offset. Defaults to 0.modificationTime Double - Last Modification time in number of seconds since the UNIX epoch.type 'rawData' - rawData.bytes Buffer - Data to be uploaded.string Zeichenketteboolean Booleaninteger Numberfloat Numberdouble Numberurl Stringarray Array\\dictionary Record\\<string, unknown>This type is a helper alias, no object will never exist of this type.
", "title": "UserDefaultTypes Object", "description": "" }, "/docs/tutorial/using-native-node-modules": { "locale": "de-DE", "slug": "using-native-node-modules", "href": "/docs/tutorial/using-native-node-modules", "crowdinFileId": "256263", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-native-node-modules.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Native Node.js modules are supported by Electron, but since Electron has a different application binary interface (ABI) from a given Node.js binary (due to differences such as using Chromium's BoringSSL instead of OpenSSL), the native modules you use will need to be recompiled for Electron. Otherwise, you will get the following class of error when you try to run your app:
\nError: The module '/path/to/native/module.node'\nwas compiled against a different Node.js version using\nNODE_MODULE_VERSION $XYZ. This version of Node.js requires\nNODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing\nthe module (for instance, using `npm rebuild` or `npm install`).\nThere are several different ways to install native modules:
\nYou can install modules like other Node projects, and then rebuild the modules for Electron with the electron-rebuild package. This module can automatically determine the version of Electron and handle the manual steps of downloading headers and rebuilding native modules for your app. If you are using Electron Forge, this tool is used automatically in both development mode and when making distributables.
For example, to install the standalone electron-rebuild tool and then rebuild modules with it via the command line:
npm install --save-dev electron-rebuild\n\n# Every time you run \"npm install\", run this:\n./node_modules/.bin/electron-rebuild\n\n# If you have trouble on Windows, try:\n.\\node_modules\\.bin\\electron-rebuild.cmd\nFor more information on usage and integration with other tools such as Electron Packager, consult the project's README.
\nnpmBy setting a few environment variables, you can use npm to install modules directly.
For example, to install all dependencies for Electron:
\n# Electron's version.\nexport npm_config_target=1.2.3\n# The architecture of Electron, see https://electronjs.org/docs/tutorial/support#supported-platforms\n# for supported architectures.\nexport npm_config_arch=x64\nexport npm_config_target_arch=x64\n# Download headers for Electron.\nexport npm_config_disturl=https://electronjs.org/headers\n# Sage node-pre-gyp das wir fur Electron bauen.\nexport npm_config_runtime=electron\n# Tell node-pre-gyp to build module from source code.\nexport npm_config_build_from_source=true\n# Install all dependencies, and store cache to ~/.electron-gyp.\nHOME=~/.electron-gyp npm install\nIf you are a developer developing a native module and want to test it against Electron, you might want to rebuild the module for Electron manually. You can use node-gyp directly to build for Electron:
cd /path-to-module/\nHOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://electronjs.org/headers\nHOME=~/.electron-gyp changes where to find development headers.--target=1.2.3 is the version of Electron.--dist-url=... specifies where to download the headers.--arch=x64 says the module is built for a 64-bit system.To compile native Node modules against a custom build of Electron that doesn't match a public release, instruct npm to use the version of Node you have bundled with your custom build.
npm rebuild --nodedir=/path/to/src/out/Default/gen/node_headers\nIf you installed a native module and found it was not working, you need to check the following things:
\nelectron-rebuild first.win_delay_load_hook is not set to false in the module's binding.gyp.win_delay_load_hookOn Windows, by default, node-gyp links native modules against node.dll. However, in Electron 4.x and higher, the symbols needed by native modules are exported by electron.exe, and there is no node.dll. In order to load native modules on Windows, node-gyp installs a delay-load hook that triggers when the native module is loaded, and redirects the node.dll reference to use the loading executable instead of looking for node.dll in the library search path (which would turn up nothing). As such, on Electron 4.x and higher, 'win_delay_load_hook': 'true' is required to load native modules.
If you get an error like Module did not self-register, or The specified procedure could not be found, it may mean that the module you're trying to use did not correctly include the delay-load hook. If the module is built with node-gyp, ensure that the win_delay_load_hook variable is set to true in the binding.gyp file, and isn't getting overridden anywhere. If the module is built with another system, you'll need to ensure that you build with a delay-load hook installed in the main .node file. Your link.exe invocation should look like this:
link.exe /OUT:\"foo.node\" \"...\\node.lib\" delayimp.lib /DELAYLOAD:node.exe /DLL\n \"my_addon.obj\" \"win_delay_load_hook.obj\"\nIn particular, it's important that:
\nnode.lib from Electron and not Node. If you link against the wrong node.lib you will get load-time errors when you require the module in Electron./DELAYLOAD:node.exe. If the node.exe link is not delayed, then the delay-load hook won't get a chance to fire and the node symbols won't be correctly resolved.win_delay_load_hook.obj is linked directly into the final DLL. If the hook is set up in a dependent DLL, it won't fire at the right time.See node-gyp for an example delay-load hook if you're implementing your own.
prebuildprebuild provides a way to publish native Node modules with prebuilt binaries for multiple versions of Node and Electron.
If the prebuild-powered module provide binaries for the usage in Electron, make sure to omit --build-from-source and the npm_config_build_from_source environment variable in order to take full advantage of the prebuilt binaries.
node-pre-gypThe node-pre-gyp tool provides a way to deploy native Node modules with prebuilt binaries, and many popular modules are using it.
Sometimes those modules work fine under Electron, but when there are no Electron-specific binaries available, you'll need to build from source. Because of this, it is recommended to use electron-rebuild for these modules.
If you are following the npm way of installing modules, you'll need to pass --build-from-source to npm, or set the npm_config_build_from_source environment variable.
Electron no longer supports the Pepper Flash plugin, as Chrome has removed support.
\nSee Chromium's Flash Roadmap for more details.
", "title": "Pepper Flash Plugin", "description": "" }, "/docs/tutorial/using-selenium-and-webdriver": { "locale": "de-DE", "slug": "using-selenium-and-webdriver", "href": "/docs/tutorial/using-selenium-and-webdriver", "crowdinFileId": "256267", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/using-selenium-and-webdriver.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Aus ChromeDriver - WebDriver for Chrome:
\n\n\nWebDriver ist ein Open-Source-Tool zum automatisierten Testen von Webanwendungen in vielen Browsern. Es bietet Funktionen für die Navigation zu Webseiten, Benutzereingaben, JavaScript-Ausführung und mehr. ChromeDriver ist ein eigenständiger Server, der das Wire-Protokoll vom WebDriver für Chromium implementiert. Es wird von Mitgliedern des Chromium- und WebDriver-Teams entwickelt.
\n
Spectron ist das offiziell unterstützte ChromeDriver Test Framework für Electron. Es basiert auf WebdriverIO und hat Helfer, um auf die Electron APIs in Ihren Tests zuzugreifen und ChromeDriver zu bündeln.
\n$ npm install --save-dev spectron\n// A simple test to verify a visible window is opened with a title\nconst Application = require('spectron').Application\nconst assert = require('assert')\n\nconst myApp = new Application({\n path: '/Applications/MyApp.app/Contents/MacOS/MyApp'\n})\n\nconst verifyWindowIsVisibleWithTitle = async (app) => {\n await app.start()\n try {\n // Check if the window is visible\n const isVisible = await app.browserWindow.isVisible()\n // Verify the window is visible\n assert.strictEqual(isVisible, true)\n // Get the window's title\n const title = await app.client.getTitle()\n // Verify the window's title\n assert.strictEqual(title, 'My App')\n } catch (error) {\n // Log any failures\n console.error('Test failed', error.message)\n }\n // Stop the application\n await app.stop()\n}\n\nverifyWindowIsVisibleWithTitle(myApp)\nWebDriverJs provides a Node package for testing with web driver, we will use it as an example.
\nZuerst müssen Sie das chromedriver-Binary herunterladen und ausführen:
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\nMerken Sie sich die Portnummer 9515, die später verwendet wird.
$ npm install selenium-webdriver\nDie Verwendung von selenium-webdriver mit Electron ist die gleiche wie bei Upstream, nur dass Sie manuell angeben müssen, wie Sie den Chromtreiber anschließen und wo Sie die Binärdatei von Electron finden:
const webdriver = require('selenium-webdriver')\n\nconst driver = new webdriver.Builder()\n // The \"9515\" is the port opened by chrome driver.\n .usingServer('http://localhost:9515')\n .withCapabilities({\n 'goog:chromeOptions': {\n // Here is the path to your Electron binary.\n binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'\n }\n })\n .forBrowser('chrome') // note: use .forBrowser('electron') for selenium-webdriver <= 3.6.0\n .build()\n\ndriver.get('http://www.google.com')\ndriver.findElement(webdriver.By.name('q')).sendKeys('webdriver')\ndriver.findElement(webdriver.By.name('btnG')).click()\ndriver.wait(() => {\n return driver.getTitle().then((title) => {\n return title === 'webdriver - Google Search'\n })\n}, 1000)\n\ndriver.quit()\nWebdriverIO provides a Node package for testing with web driver.
\nZuerst müssen Sie das chromedriver-Binary herunterladen und ausführen:
$ npm install electron-chromedriver\n$ ./node_modules/.bin/chromedriver --url-base=wd/hub --port=9515\nStarting ChromeDriver (v2.10.291558) on port 9515\nOnly local connections are allowed.\nMerken Sie sich die Portnummer 9515, die später verwendet wird.
$ npm install webdriverio\nconst webdriverio = require('webdriverio')\nconst options = {\n host: 'localhost', // Use localhost as chrome driver server\n port: 9515, // \"9515\" is the port opened by chrome driver.\n desiredCapabilities: {\n browserName: 'chrome',\n 'goog:chromeOptions': {\n binary: '/Path-to-Your-App/electron', // Path to your Electron binary.\n args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/\n }\n }\n}\n\nconst client = webdriverio.remote(options)\n\nclient\n .init()\n .url('http://google.com')\n .setValue('#q', 'webdriverio')\n .click('#btnG')\n .getTitle().then((title) => {\n console.log('Title was: ' + title)\n })\n .end()\nUm Ihre Anwendung ohne Neuaufbau von Electron zu testen, platzieren Sie Ihre App-Quelle in das Ressourcenverzeichnis von Electron.
\nAlternatively, 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.
", "title": "Selenium and WebDriver", "description": "WebDriver ist ein Open-Source-Tool zum automatisierten Testen von Webanwendungen in vielen Browsern. Es bietet Funktionen für die Navigation zu Webseiten, Benutzereingaben, JavaScript-Ausführung und mehr. ChromeDriver ist ein eigenständiger Server, der das Wire-Protokoll vom WebDriver für Chromium implementiert. Es wird von Mitgliedern des Chromium- und WebDriver-Teams entwickelt." }, "/docs/development/v8-development": { "locale": "de-DE", "slug": "v8-development", "href": "/docs/development/v8-development", "crowdinFileId": "256171", "githubUrl": "https://github.com/electron/electron/tree/main/docs/development/v8-development.md", "category": "development", "categoryFancy": "Development", "isTutorial": false, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": true, "html": "\n\nA collection of resources for learning and using V8
\n
--prof, --trace-ic, --trace-opt, --trace-deopt, --print-bytecode, --print-opt-codeSee also Chromium Development
", "title": "V8 Entwicklung", "description": "A collection of resources for learning and using V8" }, "/docs/api/web-contents": { "locale": "de-DE", "slug": "web-contents", "href": "/docs/api/web-contents", "crowdinFileId": "256399", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-contents.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nRendert und steuert web pages.
\n
Prozess: Haupt
\nwebContents ist ein EventEmitter. Ist zuständig für das rendering und die Steuerung einer web page und ist eine Property des BrowserWindow Objekts. Ein Beispiel für die Verwendung des webContents Objekts:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('http://github.com')\n\nconst contents = win.webContents\nconsole.log(contents)\nDiese diese Methoden des webContents Modul hast du zugriff:
const { webContents } = require('electron')\nconsole.log(webContents)\nwebContents.getAllWebContents()Gibt WebContents[] zurück - Ein array aller WebContents Instanzen. This will contain web contents for all windows, webviews, opened devtools, and devtools extension background pages.
webContents.getFocusedWebContents()Returns WebContents - The web contents that is focused in this application, otherwise returns null.
webContents.fromId(id)id IntegerReturns WebContents | undefined - A WebContents instance with the given ID, or undefined if there is no WebContents associated with the given ID.
webContents.fromDevToolsTargetId(targetId)targetId String - The Chrome DevTools Protocol TargetID associated with the WebContents instance.Returns WebContents | undefined - A WebContents instance with the given TargetID, or undefined if there is no WebContents associated with the given TargetID.
When communicating with the Chrome DevTools Protocol, it can be useful to lookup a WebContents instance based on its assigned TargetID.
\nasync function lookupTargetId (browserWindow) {\n const wc = browserWindow.webContents\n await wc.debugger.attach('1.3')\n const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')\n const { targetId } = targetInfo\n const targetWebContents = await webContents.fromDevToolsTargetId(targetId)\n}\n\n\nRendert und steuert den Inhalt einer BrowserWindow Instanze.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emittiert wenn die Navigation abgeschlossen ist, daher, wenn der Spinner des Tab fertig ist und das onload Event gesendet wurde.
Kehrt zurück:
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerThis event is like did-finish-load but emitted when the load failed. The full list of error codes and their meaning is available here.
Kehrt zurück:
\nevent EventerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerThis event is like did-fail-load but emitted when the load was cancelled (e.g. window.stop() was invoked).
Kehrt zurück:
\nevent EventisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when a frame has done navigation.
\nCorresponds to the points in time when the spinner of the tab started spinning.
\nCorresponds to the points in time when the spinner of the tab stopped spinning.
\nKehrt zurück:
\nevent EventEmitted when the document in the top-level frame is loaded.
\nKehrt zurück:
\nevent Eventtitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when title is synthesized from file url.
Kehrt zurück:
\nevent Eventfavicons String[] - Array mit URLs.Emitted when page receives favicon urls.
\nKehrt zurück:
\nevent NewWindowWebContentsEventurl StringframeName Stringdisposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.options BrowserWindowConstructorOptions - The options which will be used for creating the new BrowserWindow.additionalFeatures String[] - The non-standard features (features not handled by Chromium or Electron) given to window.open(). Deprecated, and will now always be the empty array [].referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.Deprecated in favor of webContents.setWindowOpenHandler.
Emitted when the page requests to open a new window for a url. It could be requested by window.open or an external link like <a target='_blank'>.
By default a new BrowserWindow will be created for the url.
Calling event.preventDefault() will prevent Electron from automatically creating a new BrowserWindow. If you call event.preventDefault() and manually create a new BrowserWindow then you must set event.newGuest to reference the new BrowserWindow instance, failing to do so may result in unexpected behavior. Ein Beispiel:
myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {\n event.preventDefault()\n const win = new BrowserWindow({\n webContents: options.webContents, // use existing webContents if provided\n show: false\n })\n win.once('ready-to-show', () => win.show())\n if (!options.webContents) {\n const loadOptions = {\n httpReferrer: referrer\n }\n if (postBody != null) {\n const { data, contentType, boundary } = postBody\n loadOptions.postData = postBody.data\n loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`\n }\n\n win.loadURL(url, loadOptions) // existing webContents will be navigated automatically\n }\n event.newGuest = win\n})\nKehrt zurück:
\nwindow BrowserWindowdetails Objekturl String - URL for the created window.frameName String - Name given to the created window in the window.open() call.options BrowserWindowConstructorOptions - The options used to create the BrowserWindow. They are merged in increasing precedence: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Unrecognized options are not filtered out.referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.Emitted after successful creation of a window via window.open in the renderer. Not emitted if the creation of the window is canceled from webContents.setWindowOpenHandler.
See window.open() for more details and how to use this in conjunction with webContents.setWindowOpenHandler.
Kehrt zurück:
\nevent Eventurl StringEmitted when a user or the page wants to start navigation. It can happen when the window.location object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with APIs like webContents.loadURL and webContents.back.
It is also not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Calling event.preventDefault() will prevent the navigation.
Kehrt zurück:
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be true for in-page navigations.
Kehrt zurück:
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted as a server side redirect occurs during navigation. For example a 302 redirect.
\nThis event will be emitted after did-start-navigation and always before the did-redirect-navigation event for the same navigation.
Calling event.preventDefault() will prevent the navigation (not just the redirect).
Kehrt zurück:
\nevent Eventurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nThis event cannot be prevented, if you want to prevent redirects you should checkout out the will-redirect event above.
Kehrt zurück:
\nevent Eventurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigationsEmitted when a main frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Kehrt zurück:
\nevent Eventurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigations,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Kehrt zurück:
\nevent Eventurl StringisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when an in-page navigation happened in any frame.
\nWhen in-page navigation happens, the page URL changes but does not cause navigation outside of the page. Examples of this occurring are when anchor links are clicked or when the DOM hashchange event is triggered.
Kehrt zurück:
\nevent EventEmitted when a beforeunload event handler is attempting to cancel a page unload.
Calling event.preventDefault() will ignore the beforeunload event handler and allow the page to be unloaded.
const { BrowserWindow, dialog } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.webContents.on('will-prevent-unload', (event) => {\n const choice = dialog.showMessageBoxSync(win, {\n type: 'question',\n buttons: ['Leave', 'Stay'],\n title: 'Do you want to leave this site?',\n message: 'Changes you made may not be saved.',\n defaultId: 0,\n cancelId: 1\n })\n const leave = (choice === 0)\n if (leave) {\n event.preventDefault()\n }\n})\nNote: This will be emitted for BrowserViews but will not be respected - this is because we have chosen not to tie the BrowserView lifecycle to its owning BrowserWindow should one exist per the specification.
Kehrt zurück:
\nevent Eventkilled BooleanEmitted when the renderer process crashes or is killed.
\nDeprecated: This event is superceded by the render-process-gone event which contains more information about why the render process disappeared. Ist es nicht immer, wenn es abgestürzt ist. Der Boolesche Wert killed kann ersetzt werden durch Überprüfung von reason === 'killed', wenn Sie zu diesem Ereignis wechseln.
Kehrt zurück:
\nevent Eventdetails Objektreason String - The reason the render process is gone. Mögliche werte:clean-exit - Process exited with an exit code of zeroabnormal-exit - Process exited with a non-zero exit codekilled - Process was sent a SIGTERM or otherwise killed externallycrashed - Process crashedoom - Process ran out of memorylaunch-failed - Process never successfully launchedintegrity-failure - Windows code integrity checks failedexitCode Integer - The exit code of the process, unless reason is launch-failed, in which case exitCode will be a platform-specific launch failure error code.Emitted when the renderer process unexpectedly disappears. This is normally because it was crashed or killed.
\nAusgegeben wenn die Webseite nicht mehr antwortet.
\nAusgegeben wenn eine Webseite, die zuvor nicht mehr antwortete, wieder antwortet.
\nKehrt zurück:
\nevent Eventname Zeichenfolgeversion StringEmitted when a plugin process has crashed.
\nEmitted when webContents is destroyed.
Kehrt zurück:
\nevent Eventinput Object - Input properties.type String - Entweder keyUp oder keyDown.key String - Equivalent zu KeyboardEvent.key.code String - Equivalent zu KeyboardEvent.code.isAutoRepeat Boolean - Equivalent zu KeyboardEvent.repeat.isComposing Boolean - Equivalent to KeyboardEvent.isComposing.shift Boolean - Equivalent zu KeyboardEvent.shiftKey.control Boolean - Equivalent zu KeyboardEvent.controlKey.alt Boolean - Equivalent zu KeyboardEvent.altKey.meta Boolean - Equivalent zu KeyboardEvent.metaKey.location Number - Equivalent to KeyboardEvent.location.modifiers String[] - See InputEvent.modifiers.Emitted before dispatching the keydown and keyup events in the page. Calling event.preventDefault will prevent the page keydown/keyup events and the menu shortcuts.
To only prevent the menu shortcuts, use setIgnoreMenuShortcuts:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\n\nwin.webContents.on('before-input-event', (event, input) => {\n // For example, only enable application menu keyboard shortcuts when\n // Ctrl/Cmd are down.\n win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)\n})\nEmitted when the window enters a full-screen state triggered by HTML API.
\nEmitted when the window leaves a full-screen state triggered by HTML API.
\nKehrt zurück:
\nevent EventzoomDirection String - Can be in or out.Emitted when the user is requesting to change the zoom level using the mouse wheel.
\nEmittiert wenn die DevTools geöffnet wurden.
\nEmittiert wenn die DevTools geschlossen wurden.
\nEmitted when DevTools is focused / opened.
\nKehrt zurück:
\nevent Eventurl Stringerror String - Der error code.certificate Certificatecallback FunctionisTrusted Boolean - Indicates whether the certificate can be considered trusted.isMainFrame BooleanEmitted when failed to verify the certificate for url.
The usage is the same with the certificate-error event of app.
Kehrt zurück:
\nevent Eventurl URLcertificateList Certificate[]callback Functioncertificate Certificate - Must be a certificate from the given list.Emittiert wenn ein Client Zertifikat angefordert wird.
\nThe usage is the same with the select-client-certificate event of app.
Kehrt zurück:
\nevent EventauthenticationResponseDetails Objekturl URLauthInfo ObjektisProxy Booleanscheme Stringhost Stringport Integerrealm Stringcallback Functionusername String (optional)password String (optional)Wird ausgelöst wenn webContents grundlegende Authentifizierung durchführen will.
The usage is the same with the login event of app.
Kehrt zurück:
\nevent Eventresult ObjectrequestId IntegeractiveMatchOrdinal Integer - Position of the active match.matches Integer - Number of Matches.selectionArea Rectangle - Coordinates of first match region.finalUpdate BooleanEmitted when a result is available for [webContents.findInPage] request.
Emittiert wenn ein Media Element anfängt zu spielen.
\nEmitted when media is paused or done playing.
\nKehrt zurück:
\nevent Eventcolor (String | null) - Theme color is in format of '#rrggbb'. It is null when no theme color is set.Emitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nKehrt zurück:
\nevent Eventurl StringEmitted when mouse moves over a link or the keyboard moves the focus to a link.
\nKehrt zurück:
\nevent Eventtype Stringimage NativeImage (optional)scale Float (optional) - scaling factor for the custom cursor.size Size (optional) - Die Größe desBildes.hotspot Point (optional) - coordinates of the custom cursor's hotspot.Emittiert wenn der Cursor Typ sich ändert. Der type Parameter kann folgenden Werte haben default, crosshair, pointer, text, wait, help, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ns-resize, ew-resize, nesw-resize, nwse-resize, col-resize, row-resize, m-panning, e-panning, n-panning, ne-panning, nw-panning, s-panning, se-panning, sw-panning, w-panning, move, vertical-text, cell, context-menu, alias, progress, nodrop, copy, none, not-allowed, zoom-in, zoom-out, grab, grabbing or custom.
If the type parameter is custom, the image parameter will hold the custom cursor image in a NativeImage, and scale, size and hotspot will hold additional information about the custom cursor.
Kehrt zurück:
\nevent Eventparams Objectx Integer - x Koordinate.y Integer - y Koordinate.frame WebFrameMain - Frame from which the context menu was invoked.linkURL String - URL of the link that encloses the node the context menu was invoked on.linkText String - Text associated with the link. May be an empty string if the contents of the link are an image.pageURL String - URL of the top level page that the context menu was invoked on.frameURL String - URL of the subframe that the context menu was invoked on.srcURL String - Source URL for the element that the context menu was invoked on. Elements with source URLs are images, audio and video.mediaType String - Type of the node the context menu was invoked on. Can be none, image, audio, video, canvas, file or plugin.hasImageContents Boolean - Whether the context menu was invoked on an image which has non-empty contents.isEditable Boolean - Whether the context is editable.selectionText String - Text of the selection that the context menu was invoked on.titleText String - Title text of the selection that the context menu was invoked on.altText String - Alt text of the selection that the context menu was invoked on.suggestedFilename String - Suggested filename to be used when saving file through 'Save Link As' option of context menu.selectionRect Rectangle - Rect representing the coordinates in the document space of the selection.selectionStartOffset Number - Start position of the selection text.referrerPolicy Referrer - The referrer policy of the frame on which the menu is invoked.misspelledWord String - The misspelled word under the cursor, if any.dictionarySuggestions String[] - An array of suggested words to show the user to replace the misspelledWord. Only available if there is a misspelled word and spellchecker is enabled.frameCharset String - The character encoding of the frame on which the menu was invoked.inputFieldType String - If the context menu was invoked on an input field, the type of that field. Possible values are none, plainText, password, other.spellcheckEnabled Boolean - If the context is editable, whether or not spellchecking is enabled.menuSourceType String - Input source that invoked the context menu. Can be none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, or adjustSelectionReset.mediaFlags Object - The flags for the media element the context menu was invoked on.inError Boolean - Whether the media element has crashed.isPaused Boolean - Whether the media element is paused.isMuted Boolean - Whether the media element is muted.hasAudio Boolean - Whether the media element has audio.isLooping Boolean - Whether the media element is looping.isControlsVisible Boolean - Whether the media element's controls are visible.canToggleControls Boolean - Whether the media element's controls are toggleable.canPrint Boolean - Whether the media element can be printed.canSave Boolean - Whether or not the media element can be downloaded.canShowPictureInPicture Boolean - Whether the media element can show picture-in-picture.isShowingPictureInPicture Boolean - Whether the media element is currently showing picture-in-picture.canRotate Boolean - Whether the media element can be rotated.canLoop Boolean - Whether the media element can be looped.editFlags Object - These flags indicate whether the renderer believes it is able to perform the corresponding action.canUndo Boolean - Whether the renderer believes it can undo.canRedo Boolean - Whether the renderer believes it can redo.canCut Boolean - Whether the renderer believes it can cut.canCopy Boolean - Whether the renderer believes it can copy.canPaste Boolean - Whether the renderer believes it can paste.canDelete Boolean - Whether the renderer believes it can delete.canSelectAll Boolean - Whether the renderer believes it can select all.canEditRichly Boolean - Whether the renderer believes it can edit text richly.Emitted when there is a new context menu that needs to be handled.
\nKehrt zurück:
\nevent Eventdevices BluetoothDevice[]callback FunctiondeviceId StringEmitted when bluetooth device needs to be selected on call to navigator.bluetooth.requestDevice. To use navigator.bluetooth api webBluetooth should be enabled. If event.preventDefault is not called, first available device will be selected. callback should be called with deviceId to be selected, passing empty string to callback will cancel the request.
const { app, BrowserWindow } = require('electron')\n\nlet win = null\napp.commandLine.appendSwitch('enable-experimental-web-platform-features')\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {\n event.preventDefault()\n const result = deviceList.find((device) => {\n return device.deviceName === 'test'\n })\n if (!result) {\n callback('')\n } else {\n callback(result.deviceId)\n }\n })\n})\nKehrt zurück:
\nevent EventdirtyRect Rectangleimage NativeImage - The image data of the whole frame.Emitted when a new frame is generated. Only the dirty area is passed in the buffer.
\nconst { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow({ webPreferences: { offscreen: true } })\nwin.webContents.on('paint', (event, dirty, image) => {\n // updateBitmap(dirty, image.getBitmap())\n})\nwin.loadURL('http://github.com')\nEmitted when the devtools window instructs the webContents to reload
\nKehrt zurück:
\nevent EventwebPreferences WebPreferences - The web preferences that will be used by the guest page. This object can be modified to adjust the preferences for the guest page.params Record<string, string> - The other <webview> parameters such as the src URL. This object can be modified to adjust the parameters of the guest page.Emitted when a <webview>'s web contents is being attached to this web contents. Calling event.preventDefault() will destroy the guest page.
This event can be used to configure webPreferences for the webContents of a <webview> before it's loaded, and provides the ability to set settings that can't be set via <webview> attributes.
Note: The specified preload script option will appear as preloadURL (not preload) in the webPreferences object emitted with this event.
Kehrt zurück:
\nevent EventwebContents WebContents - The guest web contents that is used by the <webview>.Emitted when a <webview> has been attached to this web contents.
Kehrt zurück:
\nevent Eventlevel Integer - The log level, from 0 to 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Integer - The line number of the source that triggered this console messagesourceId StringEmitted when the associated window logs a console message.
\nKehrt zurück:
\nevent EventpreloadPath Stringerror FehlerEmitted when the preload script preloadPath throws an unhandled exception error.
Kehrt zurück:
\nevent Eventchannel String...args any[]Emitted when the renderer process sends an asynchronous message via ipcRenderer.send().
Kehrt zurück:
\nevent Eventchannel String...args any[]Emitted when the renderer process sends a synchronous message via ipcRenderer.sendSync().
Kehrt zurück:
\nevent EventEmitted when desktopCapturer.getSources() is called in the renderer process. Calling event.preventDefault() will make it return empty sources.
Kehrt zurück:
\nevent EventpreferredSize Size - The minimum size needed to contain the layout of the document—without requiring scrolling.Emitted when the WebContents preferred size has changed.
This event will only be emitted when enablePreferredSizeMode is set to true in webPreferences.
Kehrt zurück:
\nevent Eventdetails Objektframe WebFrameMainEmitted when the mainFrame, an <iframe>, or a nested <iframe> is loaded within the page.
contents.loadURL(url[, options])url Stringoptions Object (optional)httpReferrer (String | Referrer) (optional) - An HTTP Referrer url.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\".postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url is a data url and needs to load other files.Returns Promise<void> - the promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load). A noop rejection handler is already attached, which avoids unhandled rejection errors.
Loads the url in the window. The url must contain the protocol prefix, e.g. the http:// or file://. If the load should bypass http cache then use the pragma header to achieve it.
const { webContents } = require('electron')\nconst options = { extraHeaders: 'pragma: no-cache\\n' }\nwebContents.loadURL('https://github.com', options)\ncontents.loadFile(filePath[, options])filePath Stringoptions Object (optional)query Record<String, String> (optional) - Passed to url.format().search String (optional) - Passed to url.format().hash String (optional) - Passed to url.format().Gibt Promise zurück - das Versprechen wird aufgelöst, wenn die Seite das Laden beendet hat (siehe did-finish-load), und lehnt ab, wenn die Seite nicht geladen wird (siehe did-fail-load).
Loads the given file in the window, filePath should be a path to an HTML file relative to the root of your application. For instance an app structure like this:
| root\n| - package.json\n| - src\n| - main.js\n| - index.html\nWürde Code wie diesen benötigen
\nwin.loadFile('src/index.html')\ncontents.downloadURL(url)url StringInitiates a download of the resource at url without navigating. The will-download event of session will be triggered.
contents.getURL()Gibt einen String zurück - Die URL der aktuellen web page.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com').then(() => {\n const currentURL = win.webContents.getURL()\n console.log(currentURL)\n})\ncontents.getTitle()Returns String - The title of the current web page.
contents.isDestroyed()Returns Boolean - Whether the web page is destroyed.
contents.focus()Focuses the web page.
\ncontents.isFocused()Returns Boolean - Whether the web page is focused.
contents.isLoading()Returns Boolean - Whether web page is still loading resources.
contents.isLoadingMainFrame()Returns Boolean - Whether the main frame (and not just iframes or frames within it) is still loading.
contents.isWaitingForResponse()Returns Boolean - Whether the web page is waiting for a first-response from the main resource of the page.
contents.stop()Stops any pending navigation.
\ncontents.reload()Lädt die aktuelle web page neu.
\ncontents.reloadIgnoringCache()Lädt die aktuelle web page neu und ignoriert dabei die Caches.
\ncontents.canGoBack()Returns Boolean - Whether the browser can go back to previous web page.
contents.canGoForward()Returns Boolean - Whether the browser can go forward to next web page.
contents.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the web page can go to offset.
contents.clearHistory()Clears the navigation history.
\ncontents.goBack()Makes the browser go back a web page.
\ncontents.goForward()Makes the browser go forward a web page.
\ncontents.goToIndex(index)index IntegerNavigates browser to the specified absolute web page index.
\ncontents.goToOffset(offset)offset IntegerNavigates to the specified offset from the \"current entry\".
\ncontents.isCrashed()Returns Boolean - Whether the renderer process has crashed.
contents.forcefullyCrashRenderer()Forcefully terminates the renderer process that is currently hosting this webContents. This will cause the render-process-gone event to be emitted with the reason=killed || reason=crashed. Please note that some webContents share renderer processes and therefore calling this method may also crash the host process for other webContents as well.
Calling reload() immediately after calling this method will force the reload to occur in a new process. This should be used when this process is unstable or unusable, for instance in order to recover from the unresponsive event.
contents.on('unresponsive', async () => {\n const { response } = await dialog.showMessageBox({\n message: 'App X has become unresponsive',\n title: 'Do you want to try forcefully reloading the app?',\n buttons: ['OK', 'Cancel'],\n cancelId: 1\n })\n if (response === 0) {\n contents.forcefullyCrashRenderer()\n contents.reload()\n }\n})\ncontents.setUserAgent(userAgent)userAgent StringOverrides the user agent for this web page.
\ncontents.getUserAgent()Returns String - The user agent for this web page.
contents.insertCSS(css[, options])css Stringoptions Object (optional)cssOrigin String (optional) - Can be either 'user' or 'author'; Specifying 'user' enables you to prevent websites from overriding the CSS you insert. Default is 'author'.Returns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via contents.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\ncontents.on('did-finish-load', () => {\n contents.insertCSS('html, body { background-color: #f00; }')\n})\ncontents.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from contents.insertCSS(css).
contents.on('did-finish-load', async () => {\n const key = await contents.insertCSS('html, body { background-color: #f00; }')\n contents.removeInsertedCSS(key)\n})\ncontents.executeJavaScript(code[, userGesture])code ZeichenketteuserGesture Boolean (optional) - Default is false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Evaluates code in page.
In the browser window some HTML APIs like requestFullScreen can only be invoked by a gesture from the user. Setting userGesture to true will remove this limitation.
Code execution will be suspended until web page stop loading.
\ncontents.executeJavaScript('fetch(\"https://jsonplaceholder.typicode.com/users/1\").then(resp => resp.json())', true)\n .then((result) => {\n console.log(result) // Will be the JSON object from the fetch call\n })\ncontents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])worldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electron's contextIsolation feature. You can provide any integer here.scripts WebSource[]userGesture Boolean (optional) - Default is false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Works like executeJavaScript but evaluates scripts in an isolated context.
contents.setIgnoreMenuShortcuts(ignore)ignore BooleanIgnore application menu shortcuts while this web contents is focused.
\ncontents.setWindowOpenHandler(handler)handler Funktion<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>
details Objekturl String - The resolved version of the URL passed to window.open(). e.g. opening a window with window.open('foo') will yield something like https://the-origin/the/current/path/foo.frameName String - Name of the window provided in window.open()features String - Comma separated list of window features provided to window.open().disposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk or other.referrer Referrer - The referrer that will be passed to the new window. May or may not result in the Referer header being sent, depending on the referrer policy.postBody PostBody (optional) - The post data that will be sent to the new window, along with the appropriate headers that will be set. If no post data is to be sent, the value will be null. Only defined when the window is being created by a form that set target=_blank.Returns {action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny cancels the creation of the new window. allow will allow the new window to be created. Specifying overrideBrowserWindowOptions allows customization of the created window. Returning an unrecognized value such as a null, undefined, or an object without a recognized 'action' value will result in a console error and have the same effect as returning {action: 'deny'}.
Called before creating a window a new window is requested by the renderer, e.g. by window.open(), a link with target=\"_blank\", shift+clicking on a link, or submitting a form with <form target=\"_blank\">. See window.open() for more details and how to use this in conjunction with did-create-window.
contents.setAudioMuted(muted)muted BooleanMute the audio on the current web page.
\ncontents.isAudioMuted()Returns Boolean - Whether this page has been muted.
contents.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
contents.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\nThe factor must be greater than 0.0.
\ncontents.getZoomFactor()Returns Number - the current zoom factor.
contents.setZoomLevel(level)level Number - Zoom level.Changes the zoom level to the specified level. The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
contents.getZoomLevel()Returns Number - the current zoom level.
contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberGibt das Promise<void> zurück
Setzt das Maximum und Minimum pinch-to-zoom Level.
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\ncontents.setVisualZoomLevelLimits(1, 3)\n
contents.undo()Executes the editing command undo in web page.
contents.redo()Executes the editing command redo in web page.
contents.cut()Executes the editing command cut in web page.
contents.copy()Executes the editing command copy in web page.
contents.copyImageAt(x, y)x Integery IntegerCopy the image at the given position to the clipboard.
\ncontents.paste()Executes the editing command paste in web page.
contents.pasteAndMatchStyle()Executes the editing command pasteAndMatchStyle in web page.
contents.delete()Executes the editing command delete in web page.
contents.selectAll()Executes the editing command selectAll in web page.
contents.unselect()Executes the editing command unselect in web page.
contents.replace(text)text StringExecutes the editing command replace in web page.
contents.replaceMisspelling(text)text StringExecutes the editing command replaceMisspelling in web page.
contents.insertText(text)text StringGibt das Promise<void> zurück
Füge text in das fokusierte Element ein.
contents.findInPage(text[, options])text String - Content to be searched, must not be empty.options Object (optional)forward Boolean (optional) - Whether to search forward or backward, defaults to true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Defaults to false.matchCase Boolean (optional) - Whether search should be case-sensitive, defaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. The result of the request can be obtained by subscribing to found-in-page event.
contents.stopFindInPage(action)action String - Specifies the action to take place when ending [webContents.findInPage] request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webContents with the provided action.
const { webContents } = require('electron')\nwebContents.on('found-in-page', (event, result) => {\n if (result.finalUpdate) webContents.stopFindInPage('clearSelection')\n})\n\nconst requestId = webContents.findInPage('api')\nconsole.log(requestId)\ncontents.capturePage([rect])rect Rectangle (optional) - The area of the page to be captured.Returns Promise<NativeImage> - Resolves with a NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page.
contents.isBeingCaptured()Returns Boolean - Whether this page is being captured. It returns true when the capturer count is large then 0.
contents.incrementCapturerCount([size, stayHidden, stayAwake])size Size (optional) - The preferred size for the capturer.stayHidden Boolean (optional) - Keep the page hidden instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Increase the capturer count by one. The page is considered visible when its browser window is hidden and the capturer count is non-zero. If you would like the page to stay hidden, you should ensure that stayHidden is set to true.
This also affects the Page Visibility API.
\ncontents.decrementCapturerCount([stayHidden, stayAwake])stayHidden Boolean (optional) - Keep the page in hidden state instead of visible.stayAwake Boolean (optional) - Keep the system awake instead of allowing it to sleep.Decrease the capturer count by one. The page will be set to hidden or occluded state when its browser window is hidden or occluded and the capturer count reaches zero. If you want to decrease the hidden capturer count instead you should set stayHidden to true.
contents.getPrinters()Get the system printer list.
\nReturns PrinterInfo[]
contents.print([options], [callback])options Object (optional)silent Boolean (optional) - Don't ask user for print settings. Standard ist false.printBackground Boolean (optional) - Prints the background color and image of the web page. Standard ist false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. Standard ist true.margins Object (optional)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. Standard ist false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print. On macOS, only one range is honored.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Can be simplex, shortEdge, or longEdge.dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.callback Funktion (optional)success Boolean - Indicates success of the print call.failureReason String - Error description called back if the print fails.When a custom pageSize is passed, Chromium attempts to validate platform specific minimum values for width_microns and height_microns. Width and height must both be minimum 353 microns but may be higher on some operating systems.
Prints window's web page. When silent is set to true, Electron will pick the system's default printer if deviceName is empty and the default settings for printing.
Use page-break-before: always; CSS style to force to print to a new page.
Example usage:
\nconst options = {\n silent: true,\n deviceName: 'My-Printer',\n pageRanges: [{\n from: 0,\n to: 1\n }]\n}\nwin.webContents.print(options, (success, errorType) => {\n if (!success) console.log(errorType)\n})\ncontents.printToPDF(options)options ObjektheaderFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height and width in microns.printBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Buffer> - Resolves with the generated PDF data.
Prints window's web page as PDF with Chromium's preview printing custom settings.
\nThe landscape will be ignored if @page CSS at-rule is used in the web page.
By default, an empty options will be regarded as:
{\n marginsType: 0,\n printBackground: false,\n printSelectionOnly: false,\n landscape: false,\n pageSize: 'A4',\n scaleFactor: 100\n}\nUse page-break-before: always; CSS style to force to print to a new page.
Ein Beispiel für webContents.printToPDF:
const { BrowserWindow } = require('electron')\nconst fs = require('fs')\nconst path = require('path')\nconst os = require('os')\n\nconst win = new BrowserWindow({ width: 800, height: 600 })\nwin.loadURL('http://github.com')\n\nwin.webContents.on('did-finish-load', () => {\n // Use default printing options\n win.webContents.printToPDF({}).then(data => {\n const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')\n fs.writeFile(pdfPath, data, (error) => {\n if (error) throw error\n console.log(`Wrote PDF successfully to ${pdfPath}`)\n })\n }).catch(error => {\n console.log(`Failed to write PDF to ${pdfPath}: `, error)\n })\n})\ncontents.addWorkSpace(path)path StringAdds the specified path to DevTools workspace. Must be used after DevTools creation:
\nconst { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\nwin.webContents.on('devtools-opened', () => {\n win.webContents.addWorkSpace(__dirname)\n})\ncontents.removeWorkSpace(path)path StringRemoves the specified path from DevTools workspace.
\ncontents.setDevToolsWebContents(devToolsWebContents)devToolsWebContents WebContentsUses the devToolsWebContents as the target WebContents to show devtools.
The devToolsWebContents must not have done any navigation, and it should not be used for other purposes after the call.
By default Electron manages the devtools by creating an internal WebContents with native view, which developers have very limited control of. With the setDevToolsWebContents method, developers can use any WebContents to show the devtools in it, including BrowserWindow, BrowserView and <webview> tag.
Note that closing the devtools does not destroy the devToolsWebContents, it is caller's responsibility to destroy devToolsWebContents.
An example of showing devtools in a <webview> tag:
<html>\n<head>\n <style type=\"text/css\">\n * { margin: 0; }\n #browser { height: 70%; }\n #devtools { height: 30%; }\n </style>\n</head>\n<body>\n <webview id=\"browser\" src=\"https://github.com\"></webview>\n <webview id=\"devtools\" src=\"about:blank\"></webview>\n <script>\n const { ipcRenderer } = require('electron')\n const emittedOnce = (element, eventName) => new Promise(resolve => {\n element.addEventListener(eventName, event => resolve(event), { once: true })\n })\n const browserView = document.getElementById('browser')\n const devtoolsView = document.getElementById('devtools')\n const browserReady = emittedOnce(browserView, 'dom-ready')\n const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')\n Promise.all([browserReady, devtoolsReady]).then(() => {\n const targetId = browserView.getWebContentsId()\n const devtoolsId = devtoolsView.getWebContentsId()\n ipcRenderer.send('open-devtools', targetId, devtoolsId)\n })\n </script>\n</body>\n</html>\n// Main process\nconst { ipcMain, webContents } = require('electron')\nipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {\n const target = webContents.fromId(targetContentsId)\n const devtools = webContents.fromId(devtoolsContentsId)\n target.setDevToolsWebContents(devtools)\n target.openDevTools()\n})\nEin Beispiel zum zeigen der DevTools in einem BrowserWindow:
const { app, BrowserWindow } = require('electron')\n\nlet win = null\nlet devtools = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow()\n devtools = new BrowserWindow()\n win.loadURL('https://github.com')\n win.webContents.setDevToolsWebContents(devtools.webContents)\n win.webContents.openDevTools({ mode: 'detach' })\n})\ncontents.openDevTools([options])options Object (optional)mode String - Opens the devtools with specified dock state, can be right, bottom, undocked, detach. Defaults to last used dock state. In undocked mode it's possible to dock back. In detach mode it's not.activate Boolean (optional) - Whether to bring the opened devtools window to the foreground. The default is true.Opens the devtools.
\nWhen contents is a <webview> tag, the mode would be detach by default, explicitly passing an empty mode can force using last used dock state.
contents.closeDevTools()Schließt die DevTools.
\ncontents.isDevToolsOpened()Returns Boolean - Whether the devtools is opened.
contents.isDevToolsFocused()Returns Boolean - Whether the devtools view is focused .
contents.toggleDevTools()Toggles the developer tools.
\ncontents.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y).
contents.inspectSharedWorker()Opens the developer tools for the shared worker context.
\ncontents.inspectSharedWorkerById(workerId)workerId StringInspects the shared worker based on its ID.
\ncontents.getAllSharedWorkers()Returns SharedWorkerInfo[] - Information about all Shared Workers.
contents.inspectServiceWorker()Opens the developer tools for the service worker context.
\ncontents.send(channel, ...args)channel String...args any[]Send an asynchronous message to the renderer process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the ipcRenderer module.
An example of sending messages from the main process to the renderer process:
\n// Im Hauptprozess.\nconst { app, BrowserWindow } = require('electron')\nlet win = null\n\napp.whenReady().then(() => {\n win = new BrowserWindow({ width: 800, height: 600 })\n win.loadURL(`file://${__dirname}/index.html`)\n win.webContents.on('did-finish-load', () => {\n win.webContents.send('ping', 'whoooooooh!')\n })\n})\n<!-- index.html -->\n<html>\n<body>\n <script>\n require('electron').ipcRenderer.on('ping', (event, message) => {\n console.log(message) // Prints 'whoooooooh!'\n })\n </script>\n</body>\n</html>\ncontents.sendToFrame(frameId, channel, ...args)frameId Integer | [number, number] - the ID of the frame to send to, or a pair of [processId, frameId] if the frame is in a different process to the main frame.channel String...args any[]Send an asynchronous message to a specific frame in a renderer process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
\n\nNOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
\n
The renderer process can handle the message by listening to channel with the ipcRenderer module.
If you want to get the frameId of a given renderer context you should use the webFrame.routingId value. z.B.
// In a renderer process\nconsole.log('My frameId is:', require('electron').webFrame.routingId)\nYou can also read frameId from all incoming IPC messages in the main process.
// In the main process\nipcMain.on('ping', (event) => {\n console.info('Message came from frameId:', event.frameId)\n})\ncontents.postMessage(channel, message, [transfer])Send a message to the renderer process, optionally transferring ownership of zero or more [MessagePortMain][] objects.
The transferred MessagePortMain objects will be available in the renderer process by accessing the ports property of the emitted event. When they arrive in the renderer, they will be native DOM MessagePort objects.
Ein Beispiel:
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\ncontents.enableDeviceEmulation(parameters)parameters ObjektscreenPosition String - Specify the screen type to emulate (default: desktop):desktop - Desktop screen type.mobile - Mobile screen type.screenSize Size - Set the emulated screen size (screenPosition == mobile).viewPosition Point - Position the view on the screen (screenPosition == mobile) (default: { x: 0, y: 0 }).deviceScaleFactor Integer - Set the device scale factor (if zero defaults to original device scale factor) (default: 0).viewSize Size - Set the emulated view size (empty means no override)scale Float - Scale of emulated view inside available space (not in fit to view mode) (default: 1).Enable device emulation with the given parameters.
\ncontents.disableDeviceEmulation()Disable device emulation enabled by webContents.enableDeviceEmulation.
contents.sendInputEvent(inputEvent)inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventSends an input event to the page. Note: The BrowserWindow containing the contents needs to be focused for sendInputEvent() to work.
contents.beginFrameSubscription([onlyDirty ,]callback)onlyDirty Boolean (optional) - Defaults to false.callback Functionimage NativeImagedirtyRect RectangleBegin subscribing for presentation events and captured frames, the callback will be called with callback(image, dirtyRect) when there is a presentation event.
The image is an instance of NativeImage that stores the captured frame.
The dirtyRect is an object with x, y, width, height properties that describes which part of the page was repainted. If onlyDirty is set to true, image will only contain the repainted area. onlyDirty defaults to false.
contents.endFrameSubscription()End subscribing for frame presentation events.
\ncontents.startDrag(item)item Objektfile String - The path to the file being dragged.files String - The paths to the files being dragged. (files will override file field)icon NativeImage | String - The image must be non-empty on macOS.Sets the item as dragging item for current drag-drop operation, file is the absolute path of the file to be dragged, and icon is the image showing under the cursor when dragging.
contents.savePage(fullPath, saveType)fullPath String - Der volle Dateipfad.saveType String - Specify the save type.HTMLOnly - Save only the HTML of the page.HTMLComplete - Save complete-html page.MHTML - Save complete-html page as MHTML.Returns Promise<void> - resolves if the page is saved.
const { BrowserWindow } = require('electron')\nconst win = new BrowserWindow()\n\nwin.loadURL('https://github.com')\n\nwin.webContents.on('did-finish-load', async () => {\n win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {\n console.log('Page was saved successfully.')\n }).catch(err => {\n console.log(err)\n })\n})\ncontents.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\ncontents.isOffscreen()Returns Boolean - Indicates whether offscreen rendering is enabled.
contents.startPainting()If offscreen rendering is enabled and not painting, start painting.
\ncontents.stopPainting()If offscreen rendering is enabled and painting, stop painting.
\ncontents.isPainting()Returns Boolean - If offscreen rendering is enabled returns whether it is currently painting.
contents.setFrameRate(fps)fps IntegerIf offscreen rendering is enabled sets the frame rate to the specified number. Only values between 1 and 240 are accepted.
\ncontents.getFrameRate()Returns Integer - If offscreen rendering is enabled returns the current frame rate.
contents.invalidate()Schedules a full repaint of the window this web contents is in.
\nIf offscreen rendering is enabled invalidates the frame and generates a new one through the 'paint' event.
contents.getWebRTCIPHandlingPolicy()Returns String - Returns the WebRTC IP Handling Policy.
contents.setWebRTCIPHandlingPolicy(policy)policy String - Specify the WebRTC IP Handling Policy.default - Exposes user's public and local IPs. This is the default behavior. When this policy is used, WebRTC has the right to enumerate all interfaces and bind them to discover public interfaces.default_public_interface_only - Exposes user's public IP, but does not expose user's local IP. When this policy is used, WebRTC should only use the default route used by http. This doesn't expose any local addresses.default_public_and_private_interfaces - Exposes user's public and local IPs. When this policy is used, WebRTC should only use the default route used by http. This also exposes the associated default private address. Default route is the route chosen by the OS on a multi-homed endpoint.disable_non_proxied_udp - Does not expose public or local IPs. When this policy is used, WebRTC should only use TCP to contact peers or servers unless the proxy server supports UDP.Setting the WebRTC IP handling policy allows you to control which IPs are exposed via WebRTC. See BrowserLeaks for more details.
\ncontents.getOSProcessId()Returns Integer - The operating system pid of the associated renderer process.
contents.getProcessId()Returns Integer - The Chromium internal pid of the associated renderer. Can be compared to the frameProcessId passed by frame specific navigation events (e.g. did-frame-navigate)
contents.takeHeapSnapshot(filePath)filePath String - Path to the output file.Returns Promise<void> - Indicates whether the snapshot has been created successfully.
Takes a V8 heap snapshot and saves it to filePath.
contents.getBackgroundThrottling()Returns Boolean - whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
contents.setBackgroundThrottling(allowed)allowed BooleanControls whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
\ncontents.getType()Returns String - the type of the webContent. Can be backgroundPage, window, browserView, remote, webview or offscreen.
contents.setImageAnimationPolicy(policy)policy String - Can be animate, animateOnce or noAnimation.Sets the image animation policy for this webContents. The policy only affects new images, existing images that are currently being animated are unaffected. This is a known limitation in Chromium, you can force image animation to be recalculated with img.src = img.src which will result in no network traffic but will update the animation policy.
This corresponds to the animationPolicy accessibility feature in Chromium.
\ncontents.audioMutedA Boolean property that determines whether this page is muted.
contents.userAgentA String property that determines the user agent for this web page.
contents.zoomLevelA Number property that determines the zoom level for this web contents.
The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
contents.zoomFactorA Number property that determines the zoom factor for this web contents.
The zoom factor is the zoom percent divided by 100, so 300% = 3.0.
\ncontents.frameRateAn Integer property that sets the frame rate of the web contents to the specified number. Only values between 1 and 240 are accepted.
Only applicable if offscreen rendering is enabled.
\ncontents.id ReadonlyA Integer representing the unique ID of this WebContents. Each ID is unique among all WebContents instances of the entire Electron application.
contents.session ReadonlyA Session used by this webContents.
contents.hostWebContents ReadonlyA WebContents instance that might own this WebContents.
contents.devToolsWebContents ReadonlyA WebContents | null property that represents the of DevTools WebContents associated with a given WebContents.
Note: Users should never store this object because it may become null when the DevTools has been closed.
contents.debugger ReadonlyA Debugger instance for this webContents.
contents.backgroundThrottlingA Boolean property that determines whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
contents.mainFrame ReadonlyA WebFrameMain property that represents the top frame of the page's frame hierarchy.
If you want to embed (third-party) web content in an Electron BrowserWindow, there are three options available to you: <iframe> tags, <webview> tags, and BrowserViews. Each one offers slightly different functionality and is useful in different situations. To help you choose between these, this guide explains the differences and capabilities of each option.
Iframes haben die selben Eigenschaften in Electron wie in normalen Browsern. An <iframe> element in your page can show external web pages, provided that their Content Security Policy allows it. To limit the number of capabilities of a site in an <iframe> tag, it is recommended to use the sandbox attribute and only allow the capabilities you want to support.
\n\nImportant Note: we do not recommend you to use WebViews, as this tag undergoes dramatic architectural changes that may affect stability of your application. Consider switching to alternatives, like
\niframeand Electron'sBrowserView, or an architecture that avoids embedded content by design.
WebViews are based on Chromium's WebViews and are not explicitly supported by Electron. We do not guarantee that the WebView API will remain available in future versions of Electron. To use <webview> tags, you will need to set webviewTag to true in the webPreferences of your BrowserWindow.
WebView is a custom element (<webview>) that will only work inside Electron. Sie sind als ein \"außerhalb-des-Prozesses iframe\" implementiert. This means that all communication with the <webview> is done asynchronously using IPC. The <webview> element has many custom methods and events, similar to webContents, that provide you with greater control over the content.
Compared to an <iframe>, <webview> tends to be slightly slower but offers much greater control in loading and communicating with the third-party content and handling various events.
BrowserViews are not a part of the DOM - instead, they are created in and controlled by your Main process. They are simply another layer of web content on top of your existing window. This means that they are completely separate from your own BrowserWindow content and their position is not controlled by the DOM or CSS. Instead, it is controlled by setting the bounds in the Main process.
BrowserViews offer the greatest control over their contents, since they implement the webContents similarly to how the BrowserWindow does it. However, as BrowserViews are not a part of your DOM, but are rather overlaid on top of them, you will have to manage their position manually.
\n\nCustomize the rendering of the current web page.
\n
Prozess: Renderer
\nwebFrame export of the Electron module is an instance of the WebFrame class representing the top frame of the current BrowserWindow. Sub-frames can be retrieved by certain properties and methods (e.g. webFrame.firstChild).
Ein Beispiel zum zoomen der aktuellen Page auf 200%.
\nconst { webFrame } = require('electron')\n\nwebFrame.setZoomFactor(2)\nDie WebFrame class hat die folgenden Methoden:
webFrame.setZoomFactor(factor)factor Double - Zoom factor; default is 1.0.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\nThe factor must be greater than 0.0.
\nwebFrame.getZoomFactor()Gibt eine Number zurück - Der aktuelle Zoom Faktor.
webFrame.setZoomLevel(level)level Number - Zoom level.Changes the zoom level to the specified level. The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively.
\n\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
webFrame.getZoomLevel()Returns Number - Das aktuelle Zoom Level.
webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberSetzt das Maximum und Minimum pinch-to-zoom Level.
\n\n\nNOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
\n\nwebFrame.setVisualZoomLevelLimits(1, 3)\n
\n\nNOTE: Visual zoom only applies to pinch-to-zoom behavior. Cmd+/-/0 zoom shortcuts are controlled by the 'zoomIn', 'zoomOut', and 'resetZoom' MenuItem roles in the application Menu. To disable shortcuts, manually define the Menu and omit zoom roles from the definition.
\n
webFrame.setSpellCheckProvider(language, provider)language Stringprovider ObjektspellCheck Funktionwords Zeichenkette[]callback FunctionmisspeltWords Zeichenkette[]Sets a provider for spell checking in input fields and text areas.
\nIf you want to use this method you must disable the builtin spellchecker when you construct the window.
\nconst mainWindow = new BrowserWindow({\n webPreferences: {\n spellcheck: false\n }\n})\nThe provider must be an object that has a spellCheck method that accepts an array of individual words for spellchecking. The spellCheck function runs asynchronously and calls the callback function with an array of misspelt words when complete.
An example of using node-spellchecker as provider:
\nconst { webFrame } = require('electron')\nconst spellChecker = require('spellchecker')\nwebFrame.setSpellCheckProvider('en-US', {\n spellCheck (words, callback) {\n setTimeout(() => {\n const spellchecker = require('spellchecker')\n const misspelled = words.filter(x => spellchecker.isMisspelled(x))\n callback(misspelled)\n }, 0)\n }\n})\nwebFrame.insertCSS(css)css String - CSS source code.Returns String - A key for the inserted CSS that can later be used to remove the CSS via webFrame.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\nwebFrame.removeInsertedCSS(key)key StringRemoves the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from webFrame.insertCSS(css).
webFrame.insertText(text)text StringFüge text in das fokusierte Element ein.
webFrame.executeJavaScript(code[, userGesture, callback])code ZeichenketteuserGesture Boolean (optional) - Default is false.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.result AnyReturns Promise
\nEvaluates code in page.
\nIn the browser window some HTML APIs like requestFullScreen can only be invoked by a gesture from the user. Setting userGesture to true will remove this limitation.
\nwebFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])
\n\nworldId Integer - The ID of the world to run the javascript in, 0 is the default main world (where content runs), 999 is the world used by Electron's contextIsolation feature. Accepts values in the range 1..536870911.scripts WebSource[]userGesture Boolean (optional) - Default is false.callback Function (optional) - Called after script has been executed. Unless the frame is suspended (e.g. showing a modal alert), execution will be synchronous and the callback will be invoked before the method returns. For compatibility with an older version of this method, the error parameter is second.\nresult Any- ` Fehler </ 0> Fehler
\n\n\nReturns Promise` - A promise that resolves with the result of the executed code or is rejected if execution could not start.
\nWorks like executeJavaScript but evaluates scripts in an isolated context.
\nNote that when the execution of script fails, the returned promise will not reject and the result would be undefined. This is because Chromium does not dispatch errors of isolated worlds to foreign worlds.
\nwebFrame.setIsolatedWorldInfo(worldId, info)
\n\nworldId Integer - The ID of the world to run the javascript in, 0 is the default world, 999 is the world used by Electrons contextIsolation feature. Chrome extensions reserve the range of IDs in [1 << 20, 1 << 29). You can provide any integer here.info Objekt\nsecurityOrigin String (optional) - Security origin for the isolated world.csp String (optional) - Content Security Policy for the isolated world.name String (optional) - Name for isolated world. Useful in devtools.
\nSet the security origin, content security policy and name of the isolated world. Note: If the csp is specified, then the securityOrigin also has to be specified.
\nwebFrame.getResourceUsage()
\nGibt das Object zurück:
\n\nimages MemoryUsageDetailsscripts MemoryUsageDetailscssStyleSheets MemoryUsageDetailsxslStyleSheets MemoryUsageDetailsfonts MemoryUsageDetailsother MemoryUsageDetails
\nReturns an object describing usage information of Blink's internal memory caches.
\nconst { webFrame } = require('electron')\nconsole.log(webFrame.getResourceUsage())\n
\nDies generiert:
\n{\n images: {\n count: 22,\n size: 2549,\n liveSize: 2542\n },\n cssStyleSheets: { /* same with \"images\" */ },\n xslStyleSheets: { /* same with \"images\" */ },\n fonts: { /* same with \"images\" */ },\n other: { /* same with \"images\" */ }\n}\n
\nwebFrame.clearCache()
\nAttempts to free memory that is no longer being used (like images from a previous navigation).
\nNote that blindly calling this method probably makes Electron slower since it will have to refill these emptied caches, you should only call it if an event in your app has occurred that makes you think your page is actually using less memory (i.e. you have navigated from a super heavy page to a mostly empty one, and intend to stay there).
\nwebFrame.getFrameForSelector(selector)
\n\nselector String - CSS selector für ein frame Element.
\nReturns WebFrame - The frame element in webFrame's document selected by selector, null would be returned if selector does not select a frame or if the frame is not in the current renderer process.
\nwebFrame.findFrameByName(name)
\n\nname Zeichenfolge
\nReturns WebFrame - A child of webFrame with the supplied name, null would be returned if there's no such frame or if the frame is not in the current renderer process.
\nwebFrame.findFrameByRoutingId(routingId)
\n\nroutingId Integer - An Integer representing the unique frame id in the current renderer process. Routing IDs can be retrieved from WebFrame instances (webFrame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate)
\nReturns WebFrame - that has the supplied routingId, null if not found.
\nwebFrame.isWordMisspelled(word)
\n\nword String - The word to be spellchecked.
\nReturns Boolean - True if the word is misspelled according to the built in spellchecker, false otherwise. If no dictionary is loaded, always return false.
\nwebFrame.getWordSuggestions(word)
\n\nword String - The misspelled word.
\nReturns String[] - A list of suggested words for a given word. If the word is spelled correctly, the result will be empty.
\nEigenschaften
\nwebFrame.top Readonly
\nA WebFrame | null representing top frame in frame hierarchy to which webFrame belongs, the property would be null if top frame is not in the current renderer process.
\nwebFrame.opener Readonly
\nA WebFrame | null representing the frame which opened webFrame, the property would be null if there's no opener or opener is not in the current renderer process.
\nwebFrame.parent Readonly
\nA WebFrame | null representing parent frame of webFrame, the property would be null if webFrame is top or parent is not in the current renderer process.
\nwebFrame.firstChild Readonly
\nA WebFrame | null representing the first child frame of webFrame, the property would be null if webFrame has no children or if first child is not in the current renderer process.
\nwebFrame.nextSibling Readonly
\nA WebFrame | null representing next sibling frame, the property would be null if webFrame is the last frame in its parent or if the next sibling is not in the current renderer process.
\nwebFrame.routingId Readonly
\nAn Integer representing the unique frame id in the current renderer process. Distinct WebFrame instances that refer to the same underlying frame will have the same routingId.
",
"title": "webFrame",
"description": "Customize the rendering of the current web page."
},
"/docs/api/web-frame-main": {
"locale": "de-DE",
"slug": "web-frame-main",
"href": "/docs/api/web-frame-main",
"crowdinFileId": "256401",
"githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-frame-main.md",
"category": "api",
"categoryFancy": "API",
"isTutorial": false,
"isApiDoc": true,
"isApiStructureDoc": false,
"isDevTutorial": false,
"html": "\n\nControl web pages and iframes.
\n
Prozess: Haupt
\nThe webFrameMain module can be used to lookup frames across existing WebContents instances. Navigation events are the common use case.
const { BrowserWindow, webFrameMain } = require('electron')\n\nconst win = new BrowserWindow({ width: 800, height: 1500 })\nwin.loadURL('https://twitter.com')\n\nwin.webContents.on(\n 'did-frame-navigate',\n (event, url, isMainFrame, frameProcessId, frameRoutingId) => {\n const frame = webFrameMain.fromId(frameProcessId, frameRoutingId)\n if (frame) {\n const code = 'document.body.innerHTML = document.body.innerHTML.replaceAll(\"heck\", \"h*ck\")'\n frame.executeJavaScript(code)\n }\n }\n)\nYou can also access frames of existing pages by using the mainFrame property of WebContents.
const { BrowserWindow } = require('electron')\n\nasync function main () {\n const win = new BrowserWindow({ width: 800, height: 600 })\n await win.loadURL('https://reddit.com')\n\n const youtubeEmbeds = win.webContents.mainFrame.frames.filter((frame) => {\n try {\n const url = new URL(frame.url)\n return url.host === 'www.youtube.com'\n } catch {\n return false\n }\n })\n\n console.log(youtubeEmbeds)\n}\n\nmain()\nThese methods can be accessed from the webFrameMain module:
webFrameMain.fromId(processId, routingId)processId Integer - An Integer representing the internal ID of the process which owns the frame.routingId Integer - An Integer representing the unique frame ID in the current renderer process. Routing IDs can be retrieved from WebFrameMain instances (frame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate).Returns WebFrameMain | undefined - A frame with the given process and routing IDs, or undefined if there is no WebFrameMain associated with the given IDs.
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Emitted when the document is loaded.
\nframe.executeJavaScript(code[, userGesture])code ZeichenketteuserGesture Boolean (optional) - Default is false.Returns Promise<unknown> - A promise that resolves with the result of the executed code or is rejected if execution throws or results in a rejected promise.
Evaluates code in page.
In the browser window some HTML APIs like requestFullScreen can only be invoked by a gesture from the user. Setting userGesture to true will remove this limitation.
frame.reload()Returns boolean - Whether the reload was initiated successfully. Only results in false when the frame has no history.
frame.send(channel, ...args)channel String...args any[]Send an asynchronous message to the renderer process via channel, along with arguments. Arguments will be serialized with the [Structured Clone Algorithm][SCA], just like [postMessage][], so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
The renderer process can handle the message by listening to channel with the ipcRenderer module.
frame.postMessage(channel, message, [transfer])Send a message to the renderer process, optionally transferring ownership of zero or more [MessagePortMain][] objects.
The transferred MessagePortMain objects will be available in the renderer process by accessing the ports property of the emitted event. When they arrive in the renderer, they will be native DOM MessagePort objects.
Ein Beispiel:
\n// Main process\nconst { port1, port2 } = new MessageChannelMain()\nwebContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])\n\n// Renderer process\nipcRenderer.on('port', (e, msg) => {\n const [port] = e.ports\n // ...\n})\nframe.url ReadonlyA string representing the current URL of the frame.
frame.top ReadonlyA WebFrameMain | null representing top frame in the frame hierarchy to which frame belongs.
frame.parent ReadonlyA WebFrameMain | null representing parent frame of frame, the property would be null if frame is the top frame in the frame hierarchy.
frame.frames ReadonlyA WebFrameMain[] collection containing the direct descendents of frame.
frame.framesInSubtree ReadonlyA WebFrameMain[] collection containing every frame in the subtree of frame, including itself. This can be useful when traversing through all frames.
frame.frameTreeNodeId ReadonlyAn Integer representing the id of the frame's internal FrameTreeNode instance. This id is browser-global and uniquely identifies a frame that hosts content. The identifier is fixed at the creation of the frame and stays constant for the lifetime of the frame. When the frame is removed, the id is not used again.
frame.name ReadonlyA String representing the frame name.
frame.osProcessId ReadonlyAn Integer representing the operating system pid of the process which owns this frame.
frame.processId ReadonlyAn Integer representing the Chromium internal pid of the process which owns this frame. This is not the same as the OS process ID; to read that use frame.osProcessId.
frame.routingId ReadonlyAn Integer representing the unique frame id in the current renderer process. Distinct WebFrameMain instances that refer to the same underlying frame will have the same routingId.
frame.visibilityState ReadonlyA string representing the visibility state of the frame.
See also how the Page Visibility API is affected by other Electron APIs.
", "title": "webFrameMain", "description": "Control web pages and iframes." }, "/docs/api/web-request": { "locale": "de-DE", "slug": "web-request", "href": "/docs/api/web-request", "crowdinFileId": "256405", "githubUrl": "https://github.com/electron/electron/tree/main/docs/api/web-request.md", "category": "api", "categoryFancy": "API", "isTutorial": false, "isApiDoc": true, "isApiStructureDoc": false, "isDevTutorial": false, "html": "\n\nIntercept and modify the contents of a request at various stages of its lifetime.
\n
Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Instances of the WebRequest class are accessed by using the webRequest property of a Session.
The methods of WebRequest accept an optional filter and a listener. The listener will be called with listener(details) when the API's event has happened. The details object describes the request.
⚠️ Only the last attached listener will be used. Passing null as listener will unsubscribe from the event.
The filter object has a urls property which is an Array of URL patterns that will be used to filter out the requests that do not match the URL patterns. If the filter is omitted then all requests will be matched.
For certain events the listener is passed with a callback, which should be called with a response object when listener has done its work.
Ein Beispiel zum hinzufügen von User-Agent Headern für Requests:
const { session } = require('electron')\n\n// Modifiziert den user agent für alle requests zu den folgenden Urls.\nconst filter = {\n urls: ['https://*.github.com/*', '*://electron.github.io']\n}\n\nsession.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {\n details.requestHeaders['User-Agent'] = 'MyAgent'\n callback({ requestHeaders: details.requestHeaders })\n}){ requestHeaders: details.requestHeaders }\nDie folgenden Methoden sind verfügbar in Instanzen von WebRequest:
webRequest.onBeforeRequest([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objektid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleuploadData UploadData[]callback Functionresponse Objectcancel Boolean (optional)redirectURL String (optional) - The original request is prevented from being sent or completed and is instead redirected to the given URL.The listener will be called with listener(details, callback) when a request is about to occur.
uploadData ist ein Array mit UploadData Objekten.
Der callback muss aufgerufen werden mit einem response Objekt.
Some examples of valid urls:
'http://foo:1234/'\n'http://foo.com/'\n'http://foo:1234/bar'\n'*://*/*'\n'*://example.com/*'\n'*://example.com/foo/*'\n'http://*.foo:1234/'\n'file://foo:1234/bar'\n'http://foo:*/'\n'*://www.foo.com/'\nwebRequest.onBeforeSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objektid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders Record<string, string>callback FunctionbeforeSendResponse Objectcancel Boolean (optional)requestHeaders Record<string, string | string[]> (optional) - When provided, request will be made with these headers.The listener will be called with listener(details, callback) before sending an HTTP request, once the request headers are available. This may occur after a TCP connection is made to the server, but before any http data is sent.
The callback has to be called with a response object.
webRequest.onSendHeaders([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objektid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublerequestHeaders Record<string, string>The listener will be called with listener(details) just before a request is going to be sent to the server, modifications of previous onBeforeSendHeaders response are visible by the time this listener is fired.
webRequest.onHeadersReceived([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objektid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublestatusLine StringstatusCode IntegerresponseHeaders Record<string, string[]> (optional)callback FunctionheadersReceivedResponse Objectcancel Boolean (optional)responseHeaders Record<string, string | string[]> (optional) - When provided, the server is assumed to have responded with these headers.statusLine String (optional) - Should be provided when overriding responseHeaders to change header status otherwise original response header's status will be used.The listener will be called with listener(details, callback) when HTTP response headers of a request have been received.
The callback has to be called with a response object.
webRequest.onResponseStarted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objektid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache Boolean - Indicates whether the response was fetched from disk cache.statusCode IntegerstatusLine StringThe listener will be called with listener(details) when first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.
webRequest.onBeforeRedirect([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objektid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleredirectURL StringstatusCode IntegerstatusLine Stringip String (optional) - Die Server IP Adresse an den der Request ursprünglich gesendet wurde.fromCache BooleanresponseHeaders Record<string, string[]> (optional)The listener will be called with listener(details) when a server initiated redirect is about to occur.
webRequest.onCompleted([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objektid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoubleresponseHeaders Record<string, string[]> (optional)fromCache BooleanstatusCode IntegerstatusLine Stringerror StringThe listener will be called with listener(details) when a request is completed.
webRequest.onErrorOccurred([filter, ]listener)filter WebRequestFilter (optional)listener Function | nulldetails Objektid Integerurl Stringmethod StringwebContentsId Integer (optional)webContents WebContents (optional)frame WebFrameMain (optional)resourceType String - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.referrer Stringtimestamp DoublefromCache Booleanerror String - The error description.The listener will be called with listener(details) when an error occurs.
urls String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.code Zeichenketteurl String (optional)startLine Integer (optional) - Default is 1.<webview> TagElectron's webview tag is based on Chromium's webview, which is undergoing dramatic architectural changes. This impacts the stability of webviews, including rendering, navigation, and event routing. We currently recommend to not use the webview tag and to consider alternatives, like iframe, Electron's BrowserView, or an architecture that avoids embedded content altogether.
By default the webview tag is disabled in Electron >= 5. You need to enable the tag by setting the webviewTag webPreferences option when constructing your BrowserWindow. For more information see the BrowserWindow constructor docs.
\n\nDisplay external web content in an isolated frame and process.
\n
Process: Renderer
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.
Use the webview tag to embed 'guest' content (such as web pages) in your Electron app. The guest content is contained within the webview container. An embedded page within your app controls how the guest content is laid out and rendered.
Unlike an 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. Note: Most methods called on the webview from the host page require a synchronous call to the main process.
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:
<webview id=\"foo\" src=\"https://www.github.com/\" style=\"display:inline-flex; width:640px; height:480px\"></webview>\nIf 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:
<script>\n onload = () => {\n const webview = document.querySelector('webview')\n const indicator = document.querySelector('.indicator')\n\n const loadstart = () => {\n indicator.innerText = 'loading...'\n }\n\n const loadstop = () => {\n indicator.innerText = ''\n }\n\n webview.addEventListener('did-start-loading', loadstart)\n webview.addEventListener('did-stop-loading', loadstop)\n }\n</script>\nUnder the hood webview is implemented with Out-of-Process iframes (OOPIFs). The webview tag is essentially a custom element using shadow DOM to wrap an iframe element inside it.
So the behavior of webview is very similar to a cross-domain iframe, as examples:
webview, the page focus will move from the embedder frame to webview.webview.webview are asynchronous.Please note that the webview tag's style uses display:flex; internally to ensure the child iframe element fills the full height and width of its webview container when used with traditional and flexbox layouts. Please do not overwrite the default display:flex; CSS property, unless specifying display:inline-flex; for inline layout.
The webview tag has the following attributes:
src<webview src=\"https://www.github.com/\"></webview>\nA String representing 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!.
nodeintegration<webview src=\"http://www.google.com/\" nodeintegration></webview>\nA Boolean. When this attribute is present the guest page in webview will have node integration and can use node APIs like require and process to access low level system resources. Node integration is disabled by default in the guest page.
nodeintegrationinsubframes<webview src=\"http://www.google.com/\" nodeintegrationinsubframes></webview>\nA Boolean for the experimental option for enabling NodeJS support in sub-frames such as iframes inside the webview. All your preloads will load for every iframe, you can use process.isMainFrame to determine if you are in the main frame or not. This option is disabled by default in the guest page.
plugins<webview src=\"https://www.github.com/\" plugins></webview>\nA Boolean. When this attribute is present the guest page in webview will be able to use browser plugins. Plugins are disabled by default.
preload<!-- from a file -->\n<webview src=\"https://www.github.com/\" preload=\"./test.js\"></webview>\n<!-- or if you want to load from an asar archive -->\n<webview src=\"https://www.github.com/\" preload=\"./app.asar/test.js\"></webview>\nA String that specifies a script that will be loaded before other scripts run in the guest page. The protocol of script's URL must be file: (even when using asar: archives) because it will be loaded by Node's require under the hood, which treats asar: archives as virtual directories.
When the guest page doesn't have node integration this script will still have access to all Node APIs, but global objects injected by Node will be deleted after this script has finished executing.
\nNote: This option will appear as preloadURL (not preload) in the webPreferences specified to the will-attach-webview event.
httpreferrer<webview src=\"https://www.github.com/\" httpreferrer=\"http://cheng.guru\"></webview>\nA String that sets the referrer URL for the guest page.
useragent<webview src=\"https://www.github.com/\" useragent=\"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko\"></webview>\nA String that sets the user agent for the guest page before the page is navigated to. Once the page is loaded, use the setUserAgent method to change the user agent.
disablewebsecurity<webview src=\"https://www.github.com/\" disablewebsecurity></webview>\nA Boolean. When this attribute is present the guest page will have web security disabled. Web security is enabled by default.
partition<webview src=\"https://github.com\" partition=\"persist:github\"></webview>\n<webview src=\"https://electronjs.org\" partition=\"electron\"></webview>\nA String that sets the session used by the page. If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. if there is no persist: prefix, the page will use an in-memory session. By assigning the same partition, multiple pages can share the same session. If the partition is unset then default session of the app will be used.
This value can only be modified before the first navigation, since the session of an active renderer process cannot change. Subsequent attempts to modify the value will fail with a DOM exception.
\nallowpopups<webview src=\"https://www.github.com/\" allowpopups></webview>\nA Boolean. When this attribute is present the guest page will be allowed to open new windows. Popups are disabled by default.
webpreferences<webview src=\"https://github.com\" webpreferences=\"allowRunningInsecureContent, javascript=no\"></webview>\nA String which is a comma separated list of strings which specifies the web preferences to be set on the webview. The full list of supported preference strings can be found in BrowserWindow.
The string follows the same format as the features string in window.open. A name by itself is given a true boolean value. A preference can be set to another value by including an =, followed by the value. Special values yes and 1 are interpreted as true, while no and 0 are interpreted as false.
enableblinkfeatures<webview src=\"https://www.github.com/\" enableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be enabled separated by ,. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
disableblinkfeatures<webview src=\"https://www.github.com/\" disableblinkfeatures=\"PreciseMemoryInfo, CSSVariables\"></webview>\nA String which is a list of strings which specifies the blink features to be disabled separated by ,. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
The webview tag has the following methods:
Note: The webview element must be loaded before using the methods.
\nBeispiel
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('dom-ready', () => {\n webview.openDevTools()\n})\n<webview>.loadURL(url[, options])url URLoptions Object (optional)httpReferrer (String | Referrer) (optional) - An HTTP Referrer url.userAgent String (optional) - A user agent originating the request.extraHeaders String (optional) - Extra headers separated by \"\\n\"postData (UploadRawData | UploadFile)baseURLForDataURL String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url is a data url and needs to load other files.Returns Promise<void> - The promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load).
Loads the url in the webview, the url must contain the protocol prefix, e.g. the http:// or file://.
<webview>.downloadURL(url)url StringInitiates a download of the resource at url without navigating.
<webview>.getURL()Returns String - The URL of guest page.
<webview>.getTitle()Returns String - The title of guest page.
<webview>.isLoading()Returns Boolean - Whether guest page is still loading resources.
<webview>.isLoadingMainFrame()Returns Boolean - Whether the main frame (and not just iframes or frames within it) is still loading.
<webview>.isWaitingForResponse()Returns Boolean - Whether the guest page is waiting for a first-response for the main resource of the page.
<webview>.stop()Stops any pending navigation.
\n<webview>.reload()Reloads the guest page.
\n<webview>.reloadIgnoringCache()Reloads the guest page and ignores cache.
\n<webview>.canGoBack()Returns Boolean - Whether the guest page can go back.
<webview>.canGoForward()Returns Boolean - Whether the guest page can go forward.
<webview>.canGoToOffset(offset)offset IntegerReturns Boolean - Whether the guest page can go to offset.
<webview>.clearHistory()Clears the navigation history.
\n<webview>.goBack()Makes the guest page go back.
\n<webview>.goForward()Makes the guest page go forward.
\n<webview>.goToIndex(index)index IntegerNavigates to the specified absolute index.
\n<webview>.goToOffset(offset)offset IntegerNavigates to the specified offset from the \"current entry\".
\n<webview>.isCrashed()Returns Boolean - Whether the renderer process has crashed.
<webview>.setUserAgent(userAgent)userAgent StringOverrides the user agent for the guest page.
\n<webview>.getUserAgent()Returns String - The user agent for guest page.
<webview>.insertCSS(css)css StringReturns Promise<String> - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via <webview>.removeInsertedCSS(key).
Injects CSS into the current web page and returns a unique key for the inserted stylesheet.
\n<webview>.removeInsertedCSS(key)key StringReturns Promise<void> - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified by its key, which is returned from <webview>.insertCSS(css).
<webview>.executeJavaScript(code[, userGesture])code ZeichenketteuserGesture Boolean (optional) - Default false.Returns Promise<any> - A promise that resolves with the result of the executed code or is rejected if the result of the code is a rejected promise.
Evaluates code in page. If userGesture is set, it will create the user gesture context in the page. HTML APIs like requestFullScreen, which require user action, can take advantage of this option for automation.
<webview>.openDevTools()Opens a DevTools window for guest page.
\n<webview>.closeDevTools()Closes the DevTools window of guest page.
\n<webview>.isDevToolsOpened()Returns Boolean - Whether guest page has a DevTools window attached.
<webview>.isDevToolsFocused()Returns Boolean - Whether DevTools window of guest page is focused.
<webview>.inspectElement(x, y)x Integery IntegerStarts inspecting element at position (x, y) of guest page.
<webview>.inspectSharedWorker()Opens the DevTools for the shared worker context present in the guest page.
\n<webview>.inspectServiceWorker()Opens the DevTools for the service worker context present in the guest page.
\n<webview>.setAudioMuted(muted)muted BooleanSet guest page muted.
\n<webview>.isAudioMuted()Returns Boolean - Whether guest page has been muted.
<webview>.isCurrentlyAudible()Returns Boolean - Whether audio is currently playing.
<webview>.undo()Executes editing command undo in page.
<webview>.redo()Executes editing command redo in page.
<webview>.cut()Executes editing command cut in page.
<webview>.copy()Executes editing command copy in page.
<webview>.paste()Executes editing command paste in page.
<webview>.pasteAndMatchStyle()Executes editing command pasteAndMatchStyle in page.
<webview>.delete()Executes editing command delete in page.
<webview>.selectAll()Executes editing command selectAll in page.
<webview>.unselect()Executes editing command unselect in page.
<webview>.replace(text)text StringExecutes editing command replace in page.
<webview>.replaceMisspelling(text)text StringExecutes editing command replaceMisspelling in page.
<webview>.insertText(text)text StringGibt das Promise<void> zurück
Füge text in das fokusierte Element ein.
<webview>.findInPage(text[, options])text String - Content to be searched, must not be empty.options Object (optional)forward Boolean (optional) - Whether to search forward or backward, defaults to true.findNext Boolean (optional) - Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Defaults to false.matchCase Boolean (optional) - Whether search should be case-sensitive, defaults to false.Returns Integer - The request id used for the request.
Starts a request to find all matches for the text in the web page. The result of the request can be obtained by subscribing to found-in-page event.
<webview>.stopFindInPage(action)action String - Specifies the action to take place when ending <webview>.findInPage request.clearSelection - Clear the selection.keepSelection - Translate the selection into a normal selection.activateSelection - Focus and click the selection node.Stops any findInPage request for the webview with the provided action.
<webview>.print([options])options Object (optional)silent Boolean (optional) - Don't ask user for print settings. Standard ist false.printBackground Boolean (optional) - Prints the background color and image of the web page. Standard ist false.deviceName String (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color Boolean (optional) - Set whether the printed web page will be in color or grayscale. Standard ist true.margins Object (optional)marginType String (optional) - Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.top Number (optional) - The top margin of the printed web page, in pixels.bottom Number (optional) - The bottom margin of the printed web page, in pixels.left Number (optional) - The left margin of the printed web page, in pixels.right Number (optional) - The right margin of the printed web page, in pixels.landscape Boolean (optional) - Whether the web page should be printed in landscape mode. Standard ist false.scaleFactor Number (optional) - The scale factor of the web page.pagesPerSheet Number (optional) - The number of pages to print per page sheet.collate Boolean (optional) - Whether the web page should be collated.copies Number (optional) - The number of copies of the web page to print.pageRanges Object - The page range to print.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).duplexMode String (optional) - Set the duplex mode of the printed web page. Can be simplex, shortEdge, or longEdge.dpi Record<string, number> (optional)horizontal Number (optional) - The horizontal dpi.vertical Number (optional) - The vertical dpi.header String (optional) - String to be printed as page header.footer String (optional) - String to be printed as page footer.pageSize String | Size (optional) - Specify page size of the printed document. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height.Gibt das Promise<void> zurück
Prints webview's web page. Same as webContents.print([options]).
<webview>.printToPDF(options)options ObjektheaderFooter Record<string, string> (optional) - the header and footer for the PDF.title String - The title for the PDF header.url String - the url for the PDF footer.landscape Boolean (optional) - true for landscape, false for portrait.marginsType Integer (optional) - Specifies the type of margins to use. Uses 0 for default margin, 1 for no margin, and 2 for minimum margin. and width in microns.scaleFactor Number (optional) - The scale factor of the web page. Can range from 0 to 100.pageRanges Record<string, number> (optional) - The page range to print. On macOS, only the first range is honored.from Number - Index of the first page to print (0-based).to Number - Index of the last page to print (inclusive) (0-based).pageSize String | Size (optional) - Specify page size of the generated PDF. Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing heightprintBackground Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly Boolean (optional) - Whether to print selection only.Returns Promise<Uint8Array> - Resolves with the generated PDF data.
Prints webview's web page as PDF, Same as webContents.printToPDF(options).
<webview>.capturePage([rect])rect Rectangle (optional) - The area of the page to be captured.Returns Promise<NativeImage> - Resolves with a NativeImage
Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page.
<webview>.send(channel, ...args)channel String...args any[]Gibt das Promise<void> zurück
Send an asynchronous message to renderer process via channel, you can also send arbitrary arguments. The renderer process can handle the message by listening to the channel event with the ipcRenderer module.
See webContents.send for examples.
\n<webview>.sendToFrame(frameId, channel, ...args)frameId [number, number] - [processId, frameId]channel String...args any[]Gibt das Promise<void> zurück
Send an asynchronous message to renderer process via channel, you can also send arbitrary arguments. The renderer process can handle the message by listening to the channel event with the ipcRenderer module.
See webContents.sendToFrame for examples.
\n<webview>.sendInputEvent(event)event MouseInputEvent | MouseWheelInputEvent | KeyboardInputEventGibt das Promise<void> zurück
Sends an input event to the page.
See webContents.sendInputEvent for detailed description of event object.
<webview>.setZoomFactor(factor)factor Number - Zoom Faktor.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
\n<webview>.setZoomLevel(level)level Number - Zoom level.Changes the zoom level to the specified level. The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level.
\n\nNOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
\n
<webview>.getZoomFactor()Returns Number - the current zoom factor.
<webview>.getZoomLevel()Returns Number - the current zoom level.
<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)minimumLevel NumbermaximumLevel NumberGibt das Promise<void> zurück
Setzt das Maximum und Minimum pinch-to-zoom Level.
\n<webview>.showDefinitionForSelection() macOSShows pop-up dictionary that searches the selected word on the page.
\n<webview>.getWebContentsId()Returns Number - The WebContents ID of this webview.
The following DOM events are available to the webview tag:
Kehrt zurück:
\nurl StringisMainFrame BooleanFired when a load has committed. This includes navigation within the current document as well as subframe document-level loads, but does not include asynchronous resource loads.
\nFired when the navigation is done, i.e. the spinner of the tab will stop spinning, and the onload event is dispatched.
Kehrt zurück:
\nerrorCode IntegererrorDescription StringvalidatedURL StringisMainFrame BooleanThis event is like did-finish-load, but fired when the load failed or was cancelled, e.g. window.stop() is invoked.
Kehrt zurück:
\nisMainFrame BooleanFired when a frame has done navigation.
\nCorresponds to the points in time when the spinner of the tab starts spinning.
\nCorresponds to the points in time when the spinner of the tab stops spinning.
\nFired when attached to the embedder web contents.
\nFired when document in the given frame is loaded.
\nKehrt zurück:
\ntitle StringexplicitSet BooleanFired when page title is set during navigation. explicitSet is false when title is synthesized from file url.
Kehrt zurück:
\nfavicons String[] - Array mit URLs.Fired when page receives favicon urls.
\nFired when page enters fullscreen triggered by HTML API.
\nFired when page leaves fullscreen triggered by HTML API.
\nKehrt zurück:
\nlevel Integer - The log level, from 0 to 3. In order it matches verbose, info, warning and error.message String - The actual console messageline Integer - The line number of the source that triggered this console messagesourceId StringFired when the guest window logs a console message.
\nThe following example code forwards all log messages to the embedder's console without regard for log level or other properties.
\nconst webview = document.querySelector('webview')\nwebview.addEventListener('console-message', (e) => {\n console.log('Guest page logged a message:', e.message)\n})\nKehrt zurück:
\nresult ObjectrequestId IntegeractiveMatchOrdinal Integer - Position of the active match.matches Integer - Number of Matches.selectionArea Rectangle - Coordinates of first match region.finalUpdate BooleanFired when a result is available for webview.findInPage request.
const webview = document.querySelector('webview')\nwebview.addEventListener('found-in-page', (e) => {\n webview.stopFindInPage('keepSelection')\n})\n\nconst requestId = webview.findInPage('test')\nconsole.log(requestId)\nKehrt zurück:
\nurl StringframeName Stringdisposition String - Can be default, foreground-tab, background-tab, new-window, save-to-disk and other.options BrowserWindowConstructorOptions - The options which should be used for creating the new BrowserWindow.Fired when the guest page attempts to open a new browser window.
\nThe following example code opens the new url in system's default browser.
\nconst { shell } = require('electron')\nconst webview = document.querySelector('webview')\n\nwebview.addEventListener('new-window', async (e) => {\n const protocol = (new URL(e.url)).protocol\n if (protocol === 'http:' || protocol === 'https:') {\n await shell.openExternal(e.url)\n }\n})\nKehrt zurück:
\nurl StringEmitted when a user or the page wants to start navigation. It can happen when the window.location object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with APIs like <webview>.loadURL and <webview>.back.
It is also not emitted during in-page navigation, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Calling event.preventDefault() does NOT have any effect.
Kehrt zurück:
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame (including main) starts navigating. isInPlace will be true for in-page navigations.
Kehrt zurück:
\nurl StringisInPlace BooleanisMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted after a server side redirect occurs during navigation. For example a 302 redirect.
\nKehrt zurück:
\nurl StringEmitted when a navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Kehrt zurück:
\nurl StringhttpResponseCode Integer - -1 for non HTTP navigationshttpStatusText String - empty for non HTTP navigations,isMainFrame BooleanframeProcessId IntegerframeRoutingId IntegerEmitted when any frame navigation is done.
\nThis event is not emitted for in-page navigations, such as clicking anchor links or updating the window.location.hash. Use did-navigate-in-page event for this purpose.
Kehrt zurück:
\nisMainFrame Booleanurl StringEmitted when an in-page navigation happened.
\nWhen in-page navigation happens, the page URL changes but does not cause navigation outside of the page. Examples of this occurring are when anchor links are clicked or when the DOM hashchange event is triggered.
Fired when the guest page attempts to close itself.
\nThe following example code navigates the webview to about:blank when the guest attempts to close itself.
const webview = document.querySelector('webview')\nwebview.addEventListener('close', () => {\n webview.src = 'about:blank'\n})\nKehrt zurück:
\nframeId [number, number] - pair of [processId, frameId].channel Stringargs any[]Fired when the guest page has sent an asynchronous message to embedder page.
\nWith sendToHost method and ipc-message event you can communicate between guest page and embedder page:
// In embedder page.\nconst webview = document.querySelector('webview')\nwebview.addEventListener('ipc-message', (event) => {\n console.log(event.channel)\n // Prints \"pong\"\n})\nwebview.send('ping')\n// In guest page.\nconst { ipcRenderer } = require('electron')\nipcRenderer.on('ping', () => {\n ipcRenderer.sendToHost('pong')\n})\nFired when the renderer process is crashed.
\nKehrt zurück:
\nname Zeichenfolgeversion StringFired when a plugin process is crashed.
\nFired when the WebContents is destroyed.
\nEmittiert wenn ein Media Element anfängt zu spielen.
\nEmitted when media is paused or done playing.
\nKehrt zurück:
\nthemeColor StringEmitted when a page's theme color changes. This is usually due to encountering a meta tag:
\n<meta name='theme-color' content='#ff0000'>\nKehrt zurück:
\nurl StringEmitted when mouse moves over a link or the keyboard moves the focus to a link.
\nEmittiert wenn die DevTools geöffnet wurden.
\nEmittiert wenn die DevTools geschlossen wurden.
\nEmitted when DevTools is focused / opened.
", "title": "There are several ways to control how windows are created from trusted or untrusted content within a renderer. Windows can be created from the renderer in two ways:
\ntarget=_blankwindow.open()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.
When nativeWindowOpen is set to false, window.open instead results in the creation of a BrowserWindowProxy, 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 BrowserWindow in the main process by using webContents.setWindowOpenHandler() for renderer-created windows.
BrowserWindow constructor options are set by, in increasing precedence order: parsed options from the features string from window.open(), security-related webPreferences inherited from the parent, and options given by webContents.setWindowOpenHandler. Note that webContents.setWindowOpenHandler has final say and full privilege because it is invoked in the main process.
window.open(url[, frameName][, features])url StringframeName String (optional)features String (optional)Returns BrowserWindowProxy | Window
features is a comma-separated key-value list, following the standard format of the browser. Electron will parse BrowserWindowConstructorOptions out of this list where possible, for convenience. For full control and better ergonomics, consider using webContents.setWindowOpenHandler to customize the BrowserWindow creation.
A subset of WebPreferences can be set directly, unnested, from the features string: zoomFactor, nodeIntegration, preload, javascript, contextIsolation, and webviewTag.
Ein Beispiel:
\nwindow.open('https://github.com', '_blank', 'top=500,left=200,frame=false,nodeIntegration=no')\nHinweise:
\nwindow if it is disabled on the parent window.window if it is enabled on the parent window.window if it is disabled on the parent window.features will be passed to any registered webContents's did-create-window event handler in the options argument.frameName follows the specification of windowName located in the native documentation.To customize or cancel the creation of the window, you can optionally set an override handler with webContents.setWindowOpenHandler() from the main 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.
Window example// main.js\nconst mainWindow = new BrowserWindow()\n\n// In this example, only windows with the `about:blank` url will be created.\n// All other urls will be blocked.\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url === 'about:blank') {\n return {\n action: 'allow',\n overrideBrowserWindowOptions: {\n frame: false,\n fullscreenable: false,\n backgroundColor: 'black',\n webPreferences: {\n preload: 'my-child-window-preload-script.js'\n }\n }\n }\n }\n return { action: 'deny' }\n})\n// renderer process (mainWindow)\nconst childWindow = window.open('', 'modal')\nchildWindow.document.write('<h1>Hello</h1>')\nBrowserWindowProxy example\n// main.js\nconst mainWindow = new BrowserWindow({\n webPreferences: { nativeWindowOpen: false }\n})\n\nmainWindow.webContents.setWindowOpenHandler(({ url }) => {\n if (url.startsWith('https://github.com/')) {\n return { action: 'allow' }\n }\n return { action: 'deny' }\n})\n\nmainWindow.webContents.on('did-create-window', (childWindow) => {\n // For example...\n childWindow.webContents.on('will-navigate', (e) => {\n e.preventDefault()\n })\n})\n// renderer.js\nconst windowProxy = window.open('https://github.com/', null, 'minimizable=false')\nwindowProxy.postMessage('hi', '*')\nWenn Ihre App mit Electron 6.0.8 oder höher läuft, können Sie sie nun unter Arm für Windows 10 bauen. This considerably improves performance, but requires recompilation of any native modules used in your app. It may also require small fixups to your build and packaging scripts.
\nWenn Ihre App keine nativen Module verwendet, ist es wirklich einfach, eine Arm-Version Ihrer App zu erstellen.
\nnode_modules Verzeichnis deiner App leer ist.set npm_config_arch=arm64 before running npm install/yarn install as usual.Lots of Windows-specific code contains if... else logic that selects between either the x64 or x86 architectures.
\nif (process.arch === 'x64') {\n // Do 64-bit thing...\n} else {\n // Do 32-bit thing...\n}\nIf you want to target arm64, logic like this will typically select the wrong architecture, so carefully check your application and build scripts for conditions like this. In custom build and packaging scripts, you should always check the value of npm_config_arch in the environment, rather than relying on the current process arch.
If you use native modules, you must make sure that they compile against v142 of the MSVC compiler (provided in Visual Studio 2017). You must also check that any pre-built .dll or .lib files provided or referenced by the native module are available for Windows on Arm.
To test your app, use a Windows on Arm device running Windows 10 (version 1903 or later). Make sure that you copy your application over to the target device - Chromium's sandbox will not work correctly when loading your application assets from a network location.
\nNode.js v12.9.0 or later is recommended. If updating to a new version of Node is undesirable, you can instead update npm's copy of node-gyp manually to version 5.0.2 or later, which contains the required changes to compile native modules for Arm.
\nVisual Studio 2017 (any edition) is required for cross-compiling native modules. You can download Visual Studio Community 2017 via Microsoft's Visual Studio Dev Essentials program. After installation, you can add the Arm-specific components by running the following from a Command Prompt:
\nvs_installer.exe ^\n--add Microsoft.VisualStudio.Workload.NativeDesktop ^\n--add Microsoft.VisualStudio.Component.VC.ATLMFC ^\n--add Microsoft.VisualStudio.Component.VC.Tools.ARM64 ^\n--add Microsoft.VisualStudio.Component.VC.MFC.ARM64 ^\n--includeRecommended\nSetting npm_config_arch=arm64 in the environment creates the correct arm64 .obj files, but the standard Developer Command Prompt for VS 2017 will use the x64 linker. To fix this:
vcvarsamd64_arm64.bat at the end instead of vcvarsamd64_x86.bat.If done successfully, the command prompt should print something similar to this on startup:
\n**********************************************************************\n** Visual Studio 2017 Developer Command Prompt v15.9.15\n** Copyright (c) 2017 Microsoft Corporation\n**********************************************************************\n[vcvarsall.bat] Environment initialized for: 'x64_arm64'\nIf you want to develop your application directly on a Windows on Arm device, substitute vcvarsx86_arm64.bat in Target so that cross-compilation can happen with the device's x86 emulation.
node.libBy default, node-gyp unpacks Electron's node headers and downloads the x86 and x64 versions of node.lib into %APPDATA%\\..\\Local\\node-gyp\\Cache, but it does not download the arm64 version (a fix for this is in development.) To fix this:
node.lib from https://electronjs.org/headers/v6.0.9/win-arm64/node.lib%APPDATA%\\..\\Local\\node-gyp\\Cache\\6.0.9\\arm64\\node.libSubstitute 6.0.9 for the version you're using.
After completing all of the above, open your cross-compilation command prompt and run set npm_config_arch=arm64. Then use npm install to build your project as normal. As with cross-compiling x86 modules, you may need to remove node_modules to force recompilation of native modules if they were previously compiled for another architecture.
Debugging native modules can be done with Visual Studio 2017 (running on your development machine) and corresponding Visual Studio Remote Debugger running on the target device. To debug:
\n.exe on the target device via the Command Prompt (passing --inspect-brk to pause it before any native modules are loaded)..pdb symbols under Debugging > Symbols.If you encounter a problem with this documentation, or if your app works when compiled for x86 but not for arm64, please file an issue with \"Windows on Arm\" in the title.
", "title": "Windows on ARM", "description": "" }, "/docs/tutorial/windows-store-guide": { "locale": "de-DE", "slug": "windows-store-guide", "href": "/docs/tutorial/windows-store-guide", "crowdinFileId": "256273", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-store-guide.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Mit Windows 10, die bewährten win32-Programmdateien bekamen einen neuen Verwandten: die Universelle Windows-Plattform. Das neue .appx-Format ermöglicht nicht nur neue APIs wie 'Cortana' oder 'Push Notifications', sondern, durch den Windows Store, wird das Aktualisieren und die Installation vereinfacht.
Microsoft entwickelte ein Werkzeug, dass Electron-Apps in .appx-Pakete kompiliert. Somit wird Entwicklern ermöglicht, einige der Annehmlichkeiten, welche sich im neuen Enticklungs-Modul finden, zu nutzen. Diese Anleitung erklärt Ihnen, wie man es benutzt - und was die Möglichkeiten und Begrenzungen von Electron-AppX-Paketen sind.
Windows 10 \"Anniversary Update\" kann win32-.exe-Dateien ausführen, indem man sie zusammen mit einem virtualisiertem Dateisystem und einer Registry startet. Beides wird während der Kompilierung erstellt durch das Ausführen der App und des Installer in einem Windows-Container. Dies erlaubt Windows genau zu identifizieren, welche Änderungen am Betriebssystem gemacht werden während der Installation. Das Zusammenbringen der Programmdatei mit einem virtuellem Dateisystem und einer virtuellen Registry erlaubt Windows, dass Ein-Klick Installationen und Deinstallationen möglich sind.
Zusätzlich wird die exe innerhalb eines appx-Modells ausgeführt. Somit können viele der APIs genutzt werden, welche in der Universellen Windows-Plattform verfügbar sind. Um noch mehr Möglichkeiten zu bekommen, kann sich eine Electron-App im Hintergrund mit einem unsichtbaren UWP-Hintergrund-Task verbinden, welcher zusammen mit der exe startet. Sie wird als eine Art \"Handlanger\" gestartet, um Tasks im Hintergrund zu starten, damit Push Notifications empfangen werden können oder um mit anderen UWP-Anwendungen kommunizieren zu können.
Um eine existierende Ectron-App zu kompilieren, stellen Sie sicher, dass die folgenden Bedingungen erfüllt sind:
\nnode -v ausführen)Als nächstes: Installieren der electron-windows-store CLI:
npm install -g electron-windows-store\nPacken Sie die Anwendung mittels des Electron-Packagers (oder einer vergleichbaren Anwendung). Make sure to remove node_modules that you don't need in your final application, since any module you don't actually need will increase your application's size.
Die Ausgabe sollte etwa wie folgt aussehen:
\n├── Ghost.exe\n├── LICENSE\n├── content_resources_200_percent.pak\n├── content_shell.pak\n├── d3dcompiler_47.dll\n├── ffmpeg.dll\n├── icudtl.dat\n├── libEGL.dll\n├── libGLESv2.dll\n├── locales\n│ ├── am.pak\n│ ├── ar.pak\n│ ├── [...]\n├── node.dll\n├── resources\n│ └── app.asar\n├── v8_context_snapshot.bin\n├── squirrel.exe\n└── ui_resources_200_percent.pak\nFrom an elevated PowerShell (run it \"as Administrator\"), run electron-windows-store with the required parameters, passing both the input and output directories, the app's name and version, and confirmation that node_modules should be flattened.
electron-windows-store `\n --input-directory C:\\myelectronapp `\n --output-directory C:\\output\\myelectronapp `\n --package-version 1.0.0.0 `\n --package-name myelectronapp\nOnce executed, the tool goes to work: It accepts your Electron app as an input, flattening the node_modules. Then, it archives your application as app.zip. Using an installer and a Windows Container, the tool creates an \"expanded\" AppX package - including the Windows Application Manifest (AppXManifest.xml) as well as the virtual file system and the virtual registry inside your output folder.
Once the expanded AppX files are created, the tool uses the Windows App Packager (MakeAppx.exe) to create a single-file AppX package from those files on disk. Finally, the tool can be used to create a trusted certificate on your computer to sign the new AppX package. With the signed AppX package, the CLI can also automatically install the package on your machine.
Um Ihr Paket ausführen zu können, wird Windows 10 mit dem sogenannten \"Anniversary Update\" benötigt. Details, wie man Windows aktualisieren kann, können hier gefunden werden.
\nIm Gegensatz zu traditionellen UWP-Apps, müssen sich gepackte Apps einem manuellen Prüfprozess unterziehen. Dieser kann hier beantragt werden. In the meantime, all users will be able to install your package by double-clicking it, so a submission to the store might not be necessary if you're looking for an easier installation method. In einer verwalteten Umgebung (normalerweise Unternehmen), das Add-AppxPackage Powershell Cmdlet kann benutzt werden, um es auf automatischem Wege zu installieren.
Eine weitere wichtige Beschränkung ist, dass das kompilierte AppX-Paket noch eine win32 Programmdatei beinhaltet. Somit wird es nicht auf der Xbox, HoloLens oder Mobiltelefonen ausführbar sein.
\nYou can pair your Electron app up with an invisible UWP background task that gets to make full use of Windows 10 features - like push notifications, Cortana integration, or live tiles.
\nTo check out how an Electron app that uses a background task to send toast notifications and live tiles, check out the Microsoft-provided sample.
\nTo generate the AppX package, the electron-windows-store CLI uses a template that should work for most Electron apps. However, if you are using a custom installer, or should you experience any trouble with the generated package, you can attempt to create a package using compilation with a Windows Container - in that mode, the CLI will install and run your application in blank Windows Container to determine what modifications your application is exactly doing to the operating system.
Before running the CLI for the first time, you will have to setup the \"Windows Desktop App Converter\". This will take a few minutes, but don't worry - you only have to do this once. Download and Desktop App Converter from here. You will receive two files: DesktopAppConverter.zip and BaseImage-14316.wim.
DesktopAppConverter.zip. From an elevated PowerShell (opened with \"run as Administrator\", ensure that your systems execution policy allows us to run everything we intend to run by calling Set-ExecutionPolicy bypass.BaseImage-14316.wim), by calling .\\DesktopAppConverter.ps1 -Setup -BaseImage .\\BaseImage-14316.wim.Once installation succeeded, you can move on to compiling your Electron app.
", "title": "Windows Store Guide", "description": "" }, "/docs/tutorial/windows-taskbar": { "locale": "de-DE", "slug": "windows-taskbar", "href": "/docs/tutorial/windows-taskbar", "crowdinFileId": "256275", "githubUrl": "https://github.com/electron/electron/tree/main/docs/tutorial/windows-taskbar.md", "category": "tutorial", "categoryFancy": "Guides", "isTutorial": true, "isApiDoc": false, "isApiStructureDoc": false, "isDevTutorial": false, "html": "Electron has APIs to configure the app's icon in the Windows taskbar. This API supports both Windows-only features like creation of a JumpList, custom thumbnails and toolbars, icon overlays, and the so-called \"Flash Frame\" effect, and cross-platform features like recent documents and application progress.
Windows allows apps to define a custom context menu that shows up when users right-click the app's icon in the taskbar. That context menu is called JumpList. You specify custom actions in the Tasks category of JumpList, as quoted from MSDN:
\n\nApplications define tasks based on both the program's features and the key things a user is expected to do with them. Tasks should be context-free, in that the application does not need to be running for them to work. They should also be the statistically most common actions that a normal user would perform in an application, such as compose an email message or open the calendar in a mail program, create a new document in a word processor, launch an application in a certain mode, or launch one of its subcommands. An application should not clutter the menu with advanced features that standard users won't need or one-time actions such as registration. Do not use tasks for promotional items such as upgrades or special offers.
\nIt is strongly recommended that the task list be static. It should remain the same regardless of the state or status of the application. While it is possible to vary the list dynamically, you should consider that this could confuse the user who does not expect that portion of the destination list to change.
\n
\n\nNOTE: The screenshot above is an example of general tasks of Internet Explorer
\n
Unlike the dock menu in macOS which is a real menu, user tasks in Windows work like application shortcuts. For example, when a user clicks a task, the program will be executed with specified arguments.
\nTo set user tasks for your application, you can use app.setUserTasks API.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { app } = require('electron')\n\napp.setUserTasks([\n {\n program: process.execPath,\n arguments: '--new-window',\n iconPath: process.execPath,\n iconIndex: 0,\n title: 'New Window',\n description: 'Create a new window'\n }\n])\nTo clear your tasks list, you need to call app.setUserTasks with an empty array in the main.js file.
const { app } = require('electron')\n\napp.setUserTasks([])\n\n\nNOTE: The user tasks will still be displayed even after closing your application, so the icon and program path specified for a task should exist until your application is uninstalled.
\n
On Windows, you can add a thumbnail toolbar with specified buttons to a taskbar layout of an application window. It provides users with a way to access a particular window's command without restoring or activating the window.
\nAs quoted from MSDN:
\n\n\nThis toolbar is the familiar standard toolbar common control. It has a maximum of seven buttons. Each button's ID, image, tooltip, and state are defined in a structure, which is then passed to the taskbar. The application can show, enable, disable, or hide buttons from the thumbnail toolbar as required by its current state.
\nFor example, Windows Media Player might offer standard media transport controls such as play, pause, mute, and stop.
\n
\n\nNOTE: The screenshot above is an example of thumbnail toolbar of Windows Media Player
\n
To set thumbnail toolbar in your application, you need to use BrowserWindow.setThumbarButtons
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { BrowserWindow } = require('electron')\nconst path = require('path')\n\nconst win = new BrowserWindow()\n\nwin.setThumbarButtons([\n {\n tooltip: 'button1',\n icon: path.join(__dirname, 'button1.png'),\n click () { console.log('button1 clicked') }\n }, {\n tooltip: 'button2',\n icon: path.join(__dirname, 'button2.png'),\n flags: ['enabled', 'dismissonclick'],\n click () { console.log('button2 clicked.') }\n }\n])\nTo clear thumbnail toolbar buttons, you need to call BrowserWindow.setThumbarButtons with an empty array in the main.js file.
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\nwin.setThumbarButtons([])\nOn Windows, a taskbar button can use a small overlay to display application status.
\nAs quoted from MSDN:
\n\n\nIcon overlays serve as a contextual notification of status, and are intended to negate the need for a separate notification area status icon to communicate that information to the user. For instance, the new mail status in Microsoft Outlook, currently shown in the notification area, can now be indicated through an overlay on the taskbar button. Again, you must decide during your development cycle which method is best for your application. Overlay icons are intended to supply important, long-standing status or notifications such as network status, messenger status, or new mail. The user should not be presented with constantly changing overlays or animations.
\n
\n\nNOTE: The screenshot above is an example of overlay on a taskbar button
\n
To set the overlay icon for a window, you need to use the BrowserWindow.setOverlayIcon API.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.setOverlayIcon('path/to/overlay.png', 'Description for overlay')\nOn Windows, you can highlight the taskbar button to get the user's attention. This is similar to bouncing the dock icon in macOS.
\nAs quoted from MSDN:
\n\n\nTypically, a window is flashed to inform the user that the window requires attention but that it does not currently have the keyboard focus.
\n
To flash the BrowserWindow taskbar button, you need to use the BrowserWindow.flashFrame API.
\nStarting with a working application from the Quick Start Guide, update the main.js file with the following lines:
const { BrowserWindow } = require('electron')\n\nconst win = new BrowserWindow()\n\nwin.once('focus', () => win.flashFrame(false))\nwin.flashFrame(true)\n\n", "title": "Taskbar Customization (Windows)", "description": "Applications define tasks based on both the program's features and the key things a user is expected to do with them. Tasks should be context-free, in that the application does not need to be running for them to work. They should also be the statistically most common actions that a normal user would perform in an application, such as compose an email message or open the calendar in a mail program, create a new document in a word processor, launch an application in a certain mode, or launch one of its subcommands. An application should not clutter the menu with advanced features that standard users won't need or one-time actions such as registration. Do not use tasks for promotional items such as upgrades or special offers.\nIt is strongly recommended that the task list be static. It should remain the same regardless of the state or status of the application. While it is possible to vary the list dynamically, you should consider that this could confuse the user who does not expect that portion of the destination list to change." } } }NOTE: Don't forget to call
\nwin.flashFrame(false)to turn off the flash. In the above example, it is called when the window comes into focus, but you might use a timeout or some other event to disable it.