* refactor: use std::erase() in WebContentsPreferences::~WebContentsPreferences()
* refactor: use std::erase() in WindowList::RemoveWindow()
* refactor: use std::erase() in ElectronBindings::EnvironmentDestroyed()
* refactor: use std::erase() in CleanedUpAtExit::~CleanedUpAtExit()
* refactor: use std::erase_if() in ElectronBrowserContext::RevokeDevicePermission()
* refactor: use std::erase_if() in UsbChooserController::GotUsbDeviceList()
* refactor: move DoesDeviceMatch() out of class into anonymous namespace
* perf: remove unnecessary c_str() call when invoking promise.RejectWithErrorMessage()
RejectWithErrorMessage() takes a std::string_view
* perf: remove unnecessary c_str() call when invoking Environment::SetVar()
the val arg to Environment::SetVar() takes a const std::string&
* refactor: use string_view variant of base::UTF8ToWide()
* perf: remove unnecessary c_str() call when instantiating a ScopedHString
ScopedHString has always taken a StringPiece
* refactor: use simpler invocation of base::make_span()
* perf: remove unnecessary c_str() call when calling base::CommandLine::HasSwitch()
HasSwitch() already takes a string_piece
* perf: remove unnecessary c_str() call when calling net::HttpResponseHeaders::AddHeader()
AddHeader() already takes a StringPiece arg
* perf: omit unnecessary str -> wstr -> str conversion in DesktopCapturer::UpdateSourcesList()
this conversion was made redundant by c670e38
* docs: document windows asar integrity
* docs: update ASAR integrity tutorial
* fix lint
---------
Co-authored-by: Samuel Attard <marshallofsound@electronjs.org>
* feat: support NODE_EXTRA_CA_CERTS
* chore: allow disabling NODE_EXTRA_CA_CERTS
* chore: call base::Environment::UnSetVar
* docs: link to fuses from env vars
* chore: update patch to match upstream
* docs: note enabled by default
* Update environment-variables.md
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
---------
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
IWYU: add missing header for `content::SyntheticGestureTarget`
GNU libstdc++ does not allow using std::unique_ptr on incomplete types,
leading to a compile error.
* feat: Options parameter for `Session.clearData` API
* Consolidate & curate data type categories
* Update docs for better typing
* off-by-one typo
* refactor to use `std::shared_ptr` instead of `base::RefCounted`
* fix compile errors
* std::enable_shared_from_this didn't work 🤷
* Refine docs with defaults
Callers of Notification::Dismiss() assume that the notification
instance is not deleted after the call, but this was not the case
for LibnotifyNotification:
- Destroy() would get `this` deleted.
- notify_notification_close() in portal environment triggers
LibnotifyNotification::OnNotificationClosed(), and finally calls
Destroy()
This patch removes all Destroy() in Dismiss(), and adds a boolean
to tell whether notify_notification_close() is running, to avoid crash
under portal environment.
Fixes#40461.
* Disable flaky test
* Add helper for storing test artifacts
* Refactor screen capture tests
We have a pattern for inspecting a screen capture, so this refactor codifies that pattern into a helper. This gives us shorter test code, consistency (previously, the display in test code and the display captured could theoretically be different), and better debugging/observability on failure.
* WIP: Session.clearBrowsingData API
* impl API method
* clean up
* tidy types and comments
* add docs
* add barebones test
* forgot a `#` :(
* tidy: address review comments
* use format macro for cross-platform build
* add another test
* amend docs to disambiguate
* Rename to `clearData`
This fixes a nasty warning / permission dialog that pops up to end-users
when consuming legacy APIs. Chrome has flipped these flags via field trials
as have other Electron apps. It should just be the default.
perf: omit unnecessary work from ElectronRenderFrameObserver::ShouldNotifyClient()
- (perf) GetBlinkPreferences() returns a const&, so we can use that
reference instead of making a temporary copy
- (perf) Don't create url object unless it's needed.
- (refactor) Move is_main_world() and is_isolated_world() from the
header into an anonymous namespace in the .cc file so they can
be inlined and made constexpr
* refactor(protocol): extract file stream factory
Increase readability by moving the file stream creation logic out of the
`uploadData` to request body conversion function.
* fix: properly flatten streams in `protocol.handle()`
Refs: electron/electron#39658
* fix: `protocol.handle()` filter null origin header
Refs: electron/electron#40754
* fix: remove obsolete TODO comment
Refs: electron/electron#38929
* fix: forward `Blob` parts in `protocol.handle()`
Refs: electron/electron#40826
* fix: explicitly error out on unknown chunk parts
This aligns us with Chromiums flags / capabilities in regards to using SCK for
everything. Currently on 14.4 Electron apps will pop warnings for usage of
deprecated APIs. With this change and a few "enable-features" toggles.
`--enable-features="ScreenCaptureKitMac,ScreenCaptureKitStreamPickerSonoma,ThumbnailCapturerMac:capture_mode/sc_screenshot_manager"`
As Chromium enables these by default Electron will inherit those changes, apps wishing to skip ahead can apply these flags early.
* build: make patches/config.json an array of objects
This file was previously an object of patch_dir keys to repo values;
Now is an array of objects containing `patch_dir` and `repo` properties.
This makes other per-target properties (e.g. `grep`) possible.
* build: include Note metadata when exporting patches
* build: support keyword filtering in export_patches()
* build: add optional `--grep` arg to git-export-patches script
* build: update export_all_patches to understand new config file
* fixup! build: update export_all_patches to understand new config file
chore: make lint happy
* fixup! build: make patches/config.json an array of objects
chore: fix oops
* refactor: remove support for the old file format
There is more code using config.json than I thought, so the
effort-to-reward of supporting the old format is not worth it.
* build: update apply_all_patches to understand new config file
* build: update lint.js to understand new config file
* build: update patches-mtime-cache.py to understand new config file
* fixup! build: update apply_all_patches to understand new config file
fix: oops
* fixup! build: update apply_all_patches to understand new config file
fix minor syntax wart
* fixup! build: support keyword filtering in export_patches()
refactor: use idiomatic python
* refactor: warn if config.json has an invalid repo
* docs: note EXIF data unsupported in nativeImage
* Update docs/api/native-image.md
Co-authored-by: David Sanders <dsanders11@ucsbalum.com>
---------
Co-authored-by: David Sanders <dsanders11@ucsbalum.com>
* refactor: make KeyWeakMap::KeyObject private
* perf: avoid redundant map lookup
* refactor: remove unused KeyWeakMap::Has()
* refactor: make KeyWeakMap dtor nonvirtual
no inheritance used, so no need for virtual dtor?
* chore: fix KeyWeakMap code comment
* refactor: use if statement in KeyWeakMap::Get()
* refactor: use better variable names in KeyWeakMap::Values()
When worker_thread shutdown, it will destory context and close
message_port. In this case, it should not dispatch close event.
Because it forbid script running during NotifyContextDestroyed in
ContextLifecycleNotifier.
Now chromium has implemented close_event and will not crash,
so we remove the patch with #22532 and add one test.
* Add note about fuses to our security documentation
Additionally, add the missing #18 to the ToC.
* lint issues for security.md
* Update docs/tutorial/security.md
Co-authored-by: Felix Rieseberg <fr@makenotion.com>
* move reference links to bottom of security.md
---------
Co-authored-by: Felix Rieseberg <fr@makenotion.com>
* refactor: use base::WriteJson() in ListValueToNSArray()
refactor: use base::WriteJson() in DictionaryValueToNSDictionary()
* refactor: use base::WriteJson() in Debugger::SendCommand()
* refactor: use base::WriteJson() in ScriptingExecuteScriptFunction::Run()
* refactor: use base::WriteJson() in HandleAccessibilityRequestCallback()
This is a follow up to https://github.com/electron/electron/pull/35921
that, it fixes more corner cases that on-screen-keyboard does not hide
for webviews.
This change has been applied in Teams for quite a while and should be
reliable enough to introduce to Electron.
`delegated_frame_host_` holds a pointer to `delegated_frame_host_client_`.
Since `delegated_frame_host_client_` was being destroyed first, that
pointer was dangling in the OSRWHV destructor.
Also, make these two unique_ptr fields `const` since they point to the
same objects for the lifespan of the OSRWHV.
* refactor: do not use banned std::to_string() in ServiceWorkerContext::GetAllRunningWorkerInfo()
* refactor: do not use banned std::to_string() in REPORT_AND_RETURN_IF_FAILED()
* refactor: do not use banned std::to_string() in JSChunkedDataPipeGetter::OnWriteChunkComplete()
* refactor: do not use banned std::to_string() in SetCrashKey()
* chore: remove unused #include
* fix: ElectronBrowserContext::PartitionKey comparisons
Use c++20 default comparisons to simplify + fix PartitionKey sorting:
- The equality operator is broken. `PartitionKey{"foo", false}` is both
equal, to and less than, `PartitionKey{"foo", true}`
- For some keys, the same session can be retrieved via both `fromPath()`
and `fromPartition()`. This use case was discussed and removed from
the original PR after code review said "always returning different
sessions feels lower maintenance." The current behavior is a bug that
comes from the comparison operators not checking the keys' types.
Xref: 3f1aea9af9 (r1099745359)
Xref: https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++-features.md#Default-comparisons-allowed
* fixup! fix: ElectronBrowserContext::PartitionKey comparisons
* Add Windows integrity check feature into Electron
Co-authored-by: Weiyun Dai <weiyun.chn@gmail.com>
* Add integrity checker header file to sources
Co-authored-by: Weiyun Dai <weiyun.chn@gmail.com>
* Moved integrity checker after checking command line args
Co-authored-by: Weiyun Dai <weiyun.chn@gmail.com>
* Revert previous Windows integrity check commits (2379a60, 331cf3c, a3c47ec)
Co-authored-by: guohaolay <guohaolay@gmail.com>
* Implement asar header integrity for Windows platform.
Co-authored-by: guohaolay <guohaolay@gmail.com>
* Fix Archive::RelativePath() on Windows platform.
Co-authored-by: guohaolay <guohaolay@gmail.com>
* Address comments.
* Address Windows integrity check PR comments.
* Update absl::optional to std::optional.
* Fix spelling.
---------
Co-authored-by: Weiyun Dai <weiyun.chn@gmail.com>
Co-authored-by: Weiyun Dai <weiyund@amazon.com>
Co-authored-by: Weiyun Dai <35878488+WeiyunD@users.noreply.github.com>
* refactor: do not use deprecated ToInternalValue() in ElectronExtensionLoader::FinishExtensionLoad()
* refactor: do not use deprecated ToInternalValue() in NotificationPresenterWin::SaveIconToFilesystem()
* chore: rename temp variable to now_usec for clarity
* refactor: use NoDestructor for g_io_thread_application_locale
* refactor: use NoDestructor for ExtensionActionAPI::GetFactoryInstance()
* refactor: use NoDestructor for ElectronExtensionsClient::GetPermissionMessageProvider()
* refactor: use NoDestructor for feat_add_support_for_overriding_the_base_spellchecker_download_url.patch
* chore: remove unused #include
* fixup! refactor: use NoDestructor for ElectronExtensionsClient::GetPermissionMessageProvider()
make sure instance is static
* chore: remove unused #include "base/lazy_instance.h"
* chore: migrate from base::StringPiece to std::string_view in keyboard_util.cc
* chore: migrate from base::StringPiece to std::string_view in error_thrower.cc
* chore: migrate from base::StringPiece to std::string_view in electron_api_web_contents.cc
* chore: migrate from base::StringPiece to std::string_view in gin_helper/dictionary.h
* chore: migrate from base::StringPiece to std::string_view in electron_api_url_loader.cc
* chore: phase out internal use of base:::StringPiece
`base::StringPiece` is being phased out upstream. Its code has been
removed upstream and it's just a typedef for `std::string_view`.
They haven't removed the typedef yet, so this PR tries to get ahead
of future breakage by migrating "internal" use (i.e. leaving alone the
places where the `base::StringPiece` name is coming from an upstream
method that we override).
Xref: https://bugs.chromium.org/p/chromium/issues/detail?id=691162
Xref: https://chromium-review.googlesource.com/c/chromium/src/+/4294483
Xref: https://docs.google.com/document/d/1d4RnD1uAE2t4iANR0nXy82ASIPGsPuw2mpO6v6T7JKs
* build: use aks arm64 test runners
* build: better image
* build: even more stuff
* build: arm par
* build: use aks arm32
* build: arm32 par
* build: get test timings from abs paths
* build: avoid realpath, use echo
* chore: add patch to always set macos platform for x-build
* build: add infra for reclient support
* build: override reclient version
* build: use RBE in CI
* chore: hardcode reclient fix version
* build: lower process count on macOS
* build: use large macOS instance for testing-arm64
* Revert "build: use large macOS instance for testing-arm64"
This reverts commit 6844adfd00a5230e68234112dfd84caa50d3f621.
* build: login in via helper not writing file
* chore: update patches
* build: use recelint from DEPS
* build: fix windows reproxy cfg
* build: use reclient in appveyor
* build: update WOA job too
* build: force another build
* build: do not checkout reclient
refactor: use fixed-size arrays for the font cache
Since we know at compile time which [family x script] combos we want to
cache, we can hold the cache in fixed std::arrays instead of in nested
std::unordered_maps.
* fix: macOS maximize button shouldn't be disabled just because the window is non-fullscreenable
* add test
* fix test by enabling maximize button if `resizable && (maximizable || fullscreenable)` instead of `(resizable && maximizable) && fullscreenable`
* refactor: use base::flat_map in ElectronMenuModel
* refactor: use base::flat_map in BuildSubmenuFromModel()
* refactor: use base::flat_map in GetDialogsMap()
* refactor: use base::flat_map in DesktopCapturer
* refactor: use base::flat_map, flat_set in ElectronBrowserClient
* refactor: use base::flat_map in ProxyingURLLoaderFactory
* refactor: use base::flat_map in MapToCommonId()
* refactor: use base::flat_map for g_map_id
* refactor: use base::flat_map for ViewsDelegate::AppbarAutohideEdgeMap
* refactor: use base::flat_map for App::app_metrics_
* refactor: use base::flat_map for PowerSaveBlocker::wake_lock_types_
* refactor: use base::flat_map for NativeImage::hicons_
* refactor: use base::flat_map for MenuViews::menu_runners_
* refactor: use base::flat_map for WebViewManager::web_contents_embedder_map_
* refactor: use base::flat_map for InspectableWebContents::extensions_api_
* refactor: use base::flat_set for libnotify GetServerCapabilities()
* refactor: use base::flat_set for InspectableWebContents::loaders_
* refactor: use base::flat_set for ElectronRendererClient::environments_
refactor: use base::flat_set for ElectronRendererClient::injected_frames_
* refactor: use base::flat_set for WebWorkerObserver::environments_
* feat: add transparent option to WebContents
* feat: add transparent attribute to webview
* test: add tests for webview transparent attribute
* docs: add transparent attribute to webview docs
* fix: run tests on macOS only
* refactor: remove unneeded html tag
* fix: only apply transparent option to guests
* refactor: correct comment
* refactor: use opaque instead
Retains current webview behaviour by default.
* fix: correct variable name to guest_opaque_
* refactor: use transparent webpreference
* docs: remove unused web preference
* fix: uncomment condition for transparency test
* docs: converted to list format and linked to MDN
* fix: make webviews transparent by default again
* fix: rebase error
---------
Co-authored-by: Cheng Zhao <zcbenz@gmail.com>
* chore: initial prototype of net api from utility process
* chore: update url loader to work on both browser and utility processes
* chore: add net files to utility process bundle
* chore: re-add app ready check but only on main process
* chore: replace browser thread dcheck's with sequence checker
* refactor: move url loader from browser to common
* refactor: move net-client-request.ts from browser to common
* docs: add utility process to net api docs
* refactor: move net module app ready check to browser only
* refactor: switch import from main to common after moving to common
* test: add basic net module test for utility process
* refactor: switch browser pid with utility pid
* refactor: move electron_api_net from browser to common
* chore: add fetch to utility net module
* chore: add isOnline and online to utility net module
* refactor: move net spec helpers into helper file
* refactor: break apart net module tests
Adds two additional net module test files: `api-net-session-spec.ts` for
tests that depend on a session being available (aka depend on running on
the main process) and `api-net-custom-protocols-spec.ts` for custom
protocol tests. This enables running `api-net-spec.ts` in the utility
process.
* test: add utility process mocha runner to run net module tests
* docs: add utility process to net module classes
* refactor: update imports in lib/utility to use electron/utility
* chore: check browser context before using in main process
Since the browser context supplied to the SimpleURLLoaderWrapper can now
be null for use in the UtilityProcess, adding a null check for the main
process before use to get a more sensible error if something goes wrong.
Co-authored-by: Cheng Zhao <github@zcbenz.com>
* chore: remove test debugging
* chore: remove unnecessary header include
* docs: add utility process net module limitations
* test: run net module tests in utility process individually
* refactor: clean up prior utility process net tests
* chore: add resolveHost to utility process net module
* chore: replace resolve host dcheck with sequence checker
* test: add net module tests for net.resolveHost
* docs: remove utility process limitation for resolveHost
---------
Co-authored-by: deepak1556 <hop2deep@gmail.com>
Co-authored-by: Cheng Zhao <github@zcbenz.com>
* Fix PR#38673
As requested in PR#38673 , a line has been added that explicitly states that accelerators are case sensitive
* Update docs/api/accelerator.md
Co-authored-by: Erick Zhao <erick@hotmail.ca>
* Update accelerator.md
---------
Co-authored-by: Erick Zhao <erick@hotmail.ca>
* chore: bump chromium in DEPS to 121.0.6154.0
* chore: bump chromium in DEPS to 121.0.6155.0
* fix patches
* chore: update patches
* patch out reference to GetOcclusionTracker
* un-flag PIPOcclusionTracker
* chore: bump chromium in DEPS to 121.0.6157.0
* fix conflicts
https://chromium-review.googlesource.com/c/chromium/src/+/5038807
* add PIP occlusion tracker sources to chromium_src
* 5037591: Replace feature_list's Initialize* methods with Init*.
https://chromium-review.googlesource.com/c/chromium/src/+/5037591
* 4811903: Move //content/browser/renderer_host/input/synthetic_gesture_controller to //content/common/input
https://chromium-review.googlesource.com/c/chromium/src/+/4811903
* 4917953: usb: Add usb-unrestricted to permission policy
https://chromium-review.googlesource.com/c/chromium/src/+/4917953
* 5072395: Remove unused `creation_context` parameter from blink/public APIs
https://chromium-review.googlesource.com/c/chromium/src/+/5072395
* 5052035: [X11] Change AtomCache from a singleton to owned by Connection
https://chromium-review.googlesource.com/c/chromium/src/+/5052035
* fix v8/.patches
* node script/gen-libc++-filenames.js
* 5035771: Remove the SetImage method of ImageButton
https://chromium-review.googlesource.com/c/chromium/src/+/5035771
* fixup! 5052035: [X11] Change AtomCache from a singleton to owned by Connection
* fixup! 5035771: Remove the SetImage method of ImageButton
* chore: bump chromium in DEPS to 121.0.6159.0
* 4505903: [Extensions] Add lastAccessed property to chrome.tabs.Tab
https://chromium-review.googlesource.com/c/chromium/src/+/4505903
* update patches
* don't duplicate tabs API types
this causes weird memory bugs if the two get out of sync
* fix UAF in TrayIconCocoa
not sure why this is popping up just now ... this has been broken for ages afaict
* Revert "don't duplicate tabs API types"
This reverts commit 80dff2efaa.
This is failing tests with extensions API schema check failures, so
revert for now. we'll fix it later.
* revert v8 change causing node crashes
* chore: reduce diffs in revert_api_dcheck-fail_when_we_reenter_v8_while_terminating.patch
---------
Co-authored-by: electron-roller[bot] <84116207+electron-roller[bot]@users.noreply.github.com>
Co-authored-by: Jeremy Rose <jeremya@chromium.org>
Co-authored-by: PatchUp <73610968+patchup[bot]@users.noreply.github.com>
Co-authored-by: clavin <clavin@electronjs.org>
Co-authored-by: Charles Kerr <charles@charleskerr.com>
* fix: clean up devtools frontend_host on destroy
* chore: use IsInPrimaryMainFrame instead of IsInMainFrame
* test: add a test for re-opening devtools
* build: fix release notes script bug that omitted edited release-clerk comments
add a warning when neither notes nor no-notes are found
* fixup! build: fix release notes script bug that omitted edited release-clerk comments
use console.warn() instead of console.log()
* chore: make use of the v8_expose_public_symbols flag
Use the newly added v8_expose_public_symbols flag to expose V8 symbols,
instead of relying on custom patches.
* chore: update patches
---------
Co-authored-by: PatchUp <73610968+patchup[bot]@users.noreply.github.com>
* feat: add blinkUtils module with getPathForFile method
This is designed to replace the File.path augmentation
we currently have in place to allow apps to get the filesystem
path for a file that blink has a representation of.
File.path is non-standard and messes with certain websites, using
a method like this is effectively 0-cost and removes one of the final
deviations we have with web standards.
* add error
* refactor: update per PR feedback
* chore: update patches
* oops
* chore: update patches
* chore: update patches
* feat: add blinkUtils module with getPathForFile method
This is designed to replace the File.path augmentation
we currently have in place to allow apps to get the filesystem
path for a file that blink has a representation of.
File.path is non-standard and messes with certain websites, using
a method like this is effectively 0-cost and removes one of the final
deviations we have with web standards.
* add error
* refactor: update per PR feedback
* chore: update patches
* oops
* chore: update patches
* chore: update patches
* chore: update patches
* fix: provide isolate to WebBlob::FromV8Value
* chore: add tests
* build: fix depshash mismatch on arm64 macOS
---------
Co-authored-by: PatchUp <73610968+patchup[bot]@users.noreply.github.com>
* refactor: use new extensions Messaging API IPC
Refs CRBUG:993189
Incorporates changes from:
* Bind ServiceWorker associated interfaces on Worker Thread (CL:4929154)
* [extensions] Move WakeEventPage to mojom::RendererHost (CL:4902564)
* [extensions] Convert Extension Messaging APIs over to mojo (CL:4947890)
* [extensions] Port GetMessageBundle over to mojom (CL:4956841)
* 5008635: [extensions] Bind the mojo interfaces to the frame instance
https://chromium-review.googlesource.com/c/chromium/src/+/5008635
* build: update appveyor image to latest version
* chore: update version to e-120.0.6099.0
* chore: rename base image for bakes
---------
Co-authored-by: jkleinsc <jkleinsc@users.noreply.github.com>
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
* feat: support for configuring use_remote_checksums via .npmrc
* docs: support for configuring use_remote_checksums via .npmrc
---------
Co-authored-by: jiujianian <jiujianian@bytedance.com>
* chore: Show FIDO devices in the chooser if allowed
* chore: tweak HidChooserContext::IsFidoAllowedForOrigin
* chore: feedback from review
---------
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
* replace the example app using electron
* Update README.md
Remove the trailing space to pass linter. Suggested by @jkleinsc. Thank you @jkleinsc for the suggestion.
---------
Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>
* fix: correctly track receiver for methods called via ctx bridge
* spec: test for correct contextBridge passage
---------
Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com>
XDG Desktop Portal provides restore tokens to restore a previously
selected PipeWire stream instead of prompting the user again. This
restore token is single use only and it has to be replaced when the
stream is completed/stopped.
BaseCapturerPipewire maintains two source IDs: one is initialized by
the constructor for new sources (source_id_) and another is for
capturing previously selected sources (selected_source_id_). The
restore token was always being stored under `source_id_`, even if the
capture was ongoing for `selected_source_id_`. This prevents a stream
from being restored more than once. Fix that by storing the restore
token under the selected source ID if it exists.
if [ "`uname`" != "Darwin" ] && ([ "$TARGET_ARCH" == "arm" ] || [ "$TARGET_ARCH" == "arm64" ]); then
gn gen out/chromedriver --args="import(\"$GN_CONFIG\") import(\"$GN_GOMA_FILE\") is_component_ffmpeg=false proprietary_codecs=false $GN_EXTRA_ARGS $GN_BUILDFLAG_ARGS"
gn gen out/chromedriver --args="import(\"$GN_CONFIG\") use_remoteexec=true is_component_ffmpeg=false proprietary_codecs=false $GN_EXTRA_ARGS $GN_BUILDFLAG_ARGS"
This issue has been automatically marked as stale. **If this issue is still affecting you, please leave any comment** (for example, "bump"), and we'll keep it open. If you have any new additional information—in particular, if this is still reproducible in the [latest version of Electron](https://www.electronjs.org/releases/stable) or in the [beta](https://www.electronjs.org/releases/beta)—please include it with your comment!
close-issue-message:>
This issue has been closed due to inactivity, and will not be monitored. If this is a bug and you can reproduce this issue on a [supported version of Electron](https://www.electronjs.org/docs/latest/tutorial/electron-timelines#timeline) please open a new issue and include instructions for reproducing the issue.
@@ -9,8 +9,8 @@ View these docs in other languages on our [Crowdin](https://crowdin.com/project/
The Electron framework lets you write cross-platform desktop applications
using JavaScript, HTML and CSS. It is based on [Node.js](https://nodejs.org/) and
[Chromium](https://www.chromium.org) and is used by the [Atom
editor](https://github.com/atom/atom) and many other [apps](https://electronjs.org/apps).
[Chromium](https://www.chromium.org) and is used by the [Visual Studio
Code](https://github.com/Microsoft/vscode/) and many other [apps](https://electronjs.org/apps).
Follow [@electronjs](https://twitter.com/electronjs) on Twitter for important
announcements.
@@ -41,9 +41,9 @@ Each Electron release provides binaries for macOS, Windows, and Linux.
* macOS (Catalina and up): Electron provides 64-bit Intel and ARM binaries for macOS. Apple Silicon support was added in Electron 11.
* Windows (Windows 10 and up): Electron provides `ia32` (`x86`), `x64` (`amd64`), and `arm64` binaries for Windows. Windows on ARM support was added in Electron 5.0.8. Support for Windows 7, 8 and 8.1 was [removed in Electron 23, in line with Chromium's Windows deprecation policy](https://www.electronjs.org/blog/windows-7-to-8-1-deprecation-notice).
* Linux: The prebuilt binaries of Electron are built on Ubuntu 20.04. They have also been verified to work on:
*`path` string (optional) _Windows_ - The executable path to compare against.
Defaults to `process.execPath`.
*`args` string[] (optional) _Windows_ - The command-line arguments to compare
against. Defaults to an empty array.
*`type` string (optional) _macOS_ - Can be one of `mainAppService`, `agentService`, `daemonService`, or `loginItemService`. Defaults to `mainAppService`. Only available on macOS 13 and up. See [app.setLoginItemSettings](app.md#appsetloginitemsettingssettings-macos-windows) for more information about each type.
*`serviceName` string (optional) _macOS_ - The name of the service. Required if `type` is non-default. Only available on macOS 13 and up.
*`path` string (optional) _Windows_ - The executable path to compare against. Defaults to `process.execPath`.
*`args` string[] (optional) _Windows_ - The command-line arguments to compare against. Defaults to an empty array.
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.
@@ -1289,17 +1264,11 @@ need 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.
This setting is not available on [MAS builds][mas-builds].
*`wasOpenedAtLogin` boolean _macOS_ - `true` if the app was opened at login
automatically. This setting is not available on [MAS builds][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][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][mas-builds].
*`openAsHidden` boolean _macOS__Deprecated_ - `true` if the app is set to open as hidden at login. This does not work on macOS 13 and up.
*`wasOpenedAtLogin` boolean _macOS__Deprecated_ - `true` if the app was opened at login automatically. This setting is not available on [MAS builds][mas-builds] or on macOS 13 and up.
*`wasOpenedAsHidden` boolean _macOS__Deprecated_ - `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][mas-builds] or on macOS 13 and up.
*`restoreState` boolean _macOS__Deprecated_ - `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][mas-builds] or on macOS 13 and up.
*`status` string _macOS_ - can be one of `not-registered`, `enabled`, `requires-approval`, or `not-found`.
*`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[] _Windows_
*`name` string _Windows_ - name value of a registry entry.
@@ -1313,10 +1282,14 @@ Returns `Object`:
*`settings` Object
*`openAtLogin` 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][mas-builds].
*`openAsHidden` boolean (optional) _macOS__Deprecated_ - `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 build
s][mas-builds] or on macOS 13 and up.
*`type` string (optional) _macOS_ - The type of service to add as a login item. Defaults to `mainAppService`. Only available on macOS 13 and up.
*`mainAppService` - The primary application.
*`agentService` - The property list name for a launch agent. The property list name must correspond to a property list in the app’s `Contents/Library/LaunchAgents` directory.
*`daemonService` string (optional) _macOS_ - The property list name for a launch agent. The property list name must correspond to a property list in the app’s `Contents/Library/LaunchDaemons` directory.
*`loginItemService` string (optional) _macOS_ - The property list name for a login item service. The property list name must correspond to a property list in the app’s `Contents/Library/LoginItems` directory.
*`serviceName` string (optional) _macOS_ - The name of the service. Required if `type` is non-default. Only available on macOS 13 and up.
*`path` string (optional) _Windows_ - The executable to launch at login.
Defaults to `process.execPath`.
*`args` string[] (optional) _Windows_ - The command-line arguments to pass to
@@ -1325,6 +1298,7 @@ Returns `Object`:
*`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][Squirrel-Windows],
@@ -1349,6 +1323,8 @@ app.setLoginItemSettings({
})
```
For more information about setting different services as login items on macOS 13 and up, see [`SMAppService`](https://developer.apple.com/documentation/servicemanagement/smappservice?language=objc).
* Options are listed in [SkParseColor.cpp](https://source.chromium.org/chromium/chromium/src/+/main:third_party/skia/src/utils/SkParseColor.cpp;l=11-152;drc=eea4bf52cb0d55e2a39c828b017c80a5ee054148)
* Similar to CSS Color Module Level 3 keywords, but case-sensitive.
* e.g. `blueviolet` or `red`
**Note:** Hex format with alpha takes `AARRGGBB` or `ARGB`, _not_`RRGGBBA` or `RGA`.
**Note:** Hex format with alpha takes `AARRGGBB` or `ARGB`, _not_`RRGGBBAA` or `RGB`.
* Options are listed in [SkParseColor.cpp](https://source.chromium.org/chromium/chromium/src/+/main:third_party/skia/src/utils/SkParseColor.cpp;l=11-152;drc=eea4bf52cb0d55e2a39c828b017c80a5ee054148)
@@ -775,7 +779,7 @@ Closes the currently open [Quick Look][quick-look] panel.
* `dontAddToRecent` _Windows_ - Do not add the item being saved to the recent documents list.
* `securityScopedBookmarks` boolean (optional) _macOS_ _mas_ - Create a [security scoped bookmark](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) 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`.
Returns `string`, the path of the file chosen by the user; if the dialog is cancelled it returns an empty string.
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
@@ -207,7 +207,7 @@ The `filters` specifies an array of file types that can be displayed, see
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`.
* `filePath` string - If the dialog is canceled, this will be an empty string.
* `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](#bookmarks-array).)
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
Adds coloration to draggable regions on [`BrowserView`](./browser-view.md)s on macOS - draggable regions will be colored
green and non-draggable regions will be colored red to aid debugging.
### `ELECTRON_DEBUG_NOTIFICATIONS`
Adds extra logs to [`Notification`](./notification.md) 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 actions are taken: a notification is shown, dismissed, its button is clicked, or it is replied to.
@@ -38,18 +38,18 @@ See [`Menu`](menu.md) for examples.
`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[] (optional) - Inserts this item before the item with the specified label. If
*`before` string[] (optional) - Inserts this item before the item with the specified id. 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[] (optional) - Inserts this item after the item with the specified label. If the
*`after` string[] (optional) - Inserts this item after the item with the specified id. If the
referenced item doesn't exist the item will be inserted at the end of
the menu.
*`beforeGroupContaining` string[] (optional) - 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.
with the specified id.
*`afterGroupContaining` string[] (optional) - 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.
with the specified id.
**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.
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
* `before` - Inserts this item before the item with the specified id. 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
* `after` - Inserts this item after the item with the specified id. 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.
the placement of their containing group before the containing group of the item with the specified id.
* `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.
the placement of their containing group after the containing group of the item with the specified id.
By default, items will be inserted in the order they exist in the template unless one of the specified positioning keywords is used.
@@ -192,14 +193,14 @@ Creates a new `NativeImage` instance from `dataURL`.
Returns `NativeImage`
Creates a new `NativeImage` instance from the NSImage that maps to the
given image name. See [`System Icons`](https://developer.apple.com/design/human-interface-guidelines/macos/icons-and-images/system-icons/)
for a list of possible values.
Creates a new `NativeImage` instance from the `NSImage` that maps to the
given image name. See Apple's [`NSImageName`](https://developer.apple.com/documentation/appkit/nsimagename#2901388)
documentation 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).
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.
@@ -216,7 +217,9 @@ This means that `[-1, 0, 1]` will make the image completely white and
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:
where `SYSTEM_IMAGE_NAME` should be replaced with any value from [this list](https://developer.apple.com/documentation/appkit/nsimagename?language=objc).
@@ -257,7 +260,7 @@ data.
* `options` Object (optional)
* `scaleFactor` Number (optional) - Defaults to 1.0.
Returns `string` - The data URL of the image.
Returns `string` - The [Data URL][data-url] of the image.
#### `image.getBitmap([options])`
@@ -273,7 +276,7 @@ current event loop tick; otherwise the data might be changed or destroyed.
#### `image.getNativeHandle()` _macOS_
Returns `Buffer` - A [Buffer][buffer] that stores C pointer to underlying native handle of
the image. On macOS, a pointer to `NSImage` instance would be returned.
the image. On macOS, a pointer to `NSImage` instance is 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
@@ -295,11 +298,11 @@ If `scaleFactor` is passed, this will return the size corresponding to the image
* `option` boolean
Marks the image as a template image.
Marks the image as a macOS [template image][template-image].
#### `image.isTemplateImage()`
Returns `boolean` - Whether the image is a template image.
Returns `boolean` - Whether the image is a macOS [template image][template-image].
#### `image.crop(rect)`
@@ -328,13 +331,13 @@ will be preserved in the resized image.
* `scaleFactor` Number (optional) - Defaults to 1.0.
Returns `Number` - The image's aspect ratio.
Returns `Number` - The image's aspect ratio (width divided by height).
If `scaleFactor` is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value.
#### `image.getScaleFactors()`
Returns `Number[]` - An array of all scale factors corresponding to representations for a given nativeImage.
Returns `Number[]` - An array of all scale factors corresponding to representations for a given `NativeImage`.
#### `image.addRepresentation(options)`
@@ -349,15 +352,17 @@ Returns `Number[]` - An array of all scale factors corresponding to representati
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
to programmatically add different scale factor representations to an image. This
A `boolean` property that determines whether the image is considered a [template image](https://developer.apple.com/documentation/appkit/nsimage/1520017-template).
A `boolean` property that determines whether the image is considered a [template image][template-image].
Please note that this property only has an effect on macOS.
_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
Each navigation entry corresponds to a specific page. The indexing system follows a sequential order, where the first available navigation entry is at index 0, representing the earliest visited page, and the latest navigation entry is at index N, representing the most recent page. Maintaining this ordered list of navigation entries enables seamless navigation both backward and forward through the user's browsing history.
### Instance Methods
#### `navigationHistory.getActiveIndex()`
Returns `Integer` - The index of the current page, from which we would go back/forward or reload.
#### `navigationHistory.getEntryAtIndex(index)`
*`index` Integer
Returns `Object`:
*`url` string - The URL of the navigation entry at the given index.
*`title` string - The page title of the navigation entry at the given index.
If index is out of bounds (greater than history length or less than 0), null will be returned.
* `pointerLock` - Request to directly interpret mouse movements as an input method via the [Pointer Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API). These requests always appear to originate from the main frame.
* `keyboardLock` - Request capture of keypresses for any or all of the keys on the physical keyboard via the [Keyboard Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard/lock). These requests always appear to originate from the main frame.
* `openExternal` - Request to open links in external applications.
* `speaker-selection` - Request to enumerate and select audio output devices via the [speaker-selection permissions policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection).
* `storage-access` - Allows content loaded in a third-party context to request access to third-party cookies using the [Storage Access API](https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API).
* `top-level-storage-access` - Allow top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same related website set using the [Storage Access API](https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API).
* `window-management` - Request access to enumerate screens using the [`getScreenDetails`](https://developer.chrome.com/en/articles/multi-screen-window-placement/) API.
* `unknown` - An unrecognized permission request.
* `fileSystem` - Request access to read, write, and file management capabilities using the [File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API).
* `callback` Function
* `permissionGranted` 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.
* `securityOrigin` string (optional) - The security origin of the `media` request.
* `mediaTypes` string[] (optional) - The types of media access being requested, elements can be `video`
or `audio`
* `requestingUrl` string - The last URL the requesting frame loaded
* `isMainFrame` boolean - Whether the frame making the request is the main frame
* `details` [PermissionRequest](structures/permission-request.md) | [FilesystemPermissionRequest](structures/filesystem-permission-request.md) | [MediaAccessPermissionRequest](structures/media-access-permission-request.md) | [OpenExternalPermissionRequest](structures/open-external-permission-request.md) - Additional information about the permission being requested.
Sets 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.
The API will generate a [DownloadItem](download-item.md) that can be accessed
@@ -1427,6 +1423,37 @@ is emitted.
Returns `string | null` - The absolute file system path where data for this
session is persisted on disk. For in memory sessions this returns `null`.
#### `ses.clearData([options])`
* `options` Object (optional)
* `dataTypes` String[] (optional) - The types of data to clear. By default, this will clear all types of data.
* `backgroundFetch` - Background Fetch
* `cache` - Cache
* `cookies` - Cookies
* `downloads` - Downloads
* `fileSystems` - File Systems
* `indexedDB` - IndexedDB
* `localStorage` - Local Storage
* `serviceWorkers` - Service Workers
* `webSQL` - WebSQL
* `origins` String[] (optional) - Clear data for only these origins. Cannot be used with `excludeOrigins`.
* `excludeOrigins` String[] (optional) - Clear data for all origins except these ones. Cannot be used with `origins`.
* `avoidClosingConnections` boolean (optional) - Skips deleting cookies that would close current network connections. (Default: `false`)
* `originMatchingMode` String (optional) - The behavior for matching data to origins.
* `third-parties-included` (default) - Storage is matched on origin in first-party contexts and top-level-site in third-party contexts.
* `origin-in-all-contexts` - Storage is matched on origin only in all contexts.
Returns `Promise<void>` - resolves when all data has been cleared.
Clears various different types of data.
This method clears more types of data and is more thourough than the
`clearStorageData` method.
**Note:** Cookies are stored at a broader scope than origins. When removing cookies and filtering by `origins` (or `excludeOrigins`), the cookies will be removed at the [registrable domain](https://url.spec.whatwg.org/#host-registrable-domain) level. For example, clearing cookies for the origin `https://really.specific.origin.example.com/` will end up clearing all cookies for `example.com`. Clearing cookies for the origin `https://my.website.example.co.uk/` will end up clearing all cookies for `example.co.uk`.
For more information, refer to Chromium's [`BrowsingDataRemover` interface](https://source.chromium.org/chromium/chromium/src/+/main:content/public/browser/browsing_data_remover.h).
### Instance Properties
The following properties are available on instances of `Session`:
*`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.
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. Default is `false`.
*`center` boolean (optional) - Show window in the center of the screen. Default is `false`.
*`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) _macOS__Windows_ - Whether window is
movable. This is not implemented on Linux. Default is `true`.
*`minimizable` boolean (optional) _macOS__Windows_ - Whether window is
minimizable. This is not implemented on Linux. Default is `true`.
*`maximizable` boolean (optional) _macOS__Windows_ - Whether window is
maximizable. This is not implemented on Linux. Default is `true`.
*`closable` boolean (optional) _macOS__Windows_ - Whether window is
closable. This is not implemented on Linux. Default is `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. Default is `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. Default is `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. Default is `true`.
*`simpleFullscreen` boolean (optional) _macOS_ - Use pre-Lion fullscreen on
macOS. Default is `false`.
*`skipTaskbar` boolean (optional) _macOS__Windows_ - Whether to show the window in taskbar.
Default is `false`.
*`hiddenInMissionControl` boolean (optional) _macOS_ - Whether window should be hidden when the user toggles into mission control.
*`restoreOnRelaunch` boolean (optional) _macOS_ - Whether the window should launch with full fidelity across app restarts.
*`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](../native-image.md) | 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`.
*`frame` boolean (optional) - Specify `false` to create a
[frameless window](../../tutorial/window-customization.md#create-frameless-windows). Default is `true`.
*`parent` BaseWindow (optional) - Specify parent window. Default is `null`.
*`modal` boolean (optional) - Whether this is a modal window. This only works when the
window is a child window. Default is `false`.
*`acceptFirstMouse` boolean (optional) _macOS_ - 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.
Default is `false`.
*`autoHideMenuBar` boolean (optional) - Auto hide the menu bar unless the `Alt`
key is pressed. Default is `false`.
*`enableLargerThanScreen` boolean (optional) _macOS_ - Enable the window to
be resized larger than screen. Only relevant for macOS, as other OSes
allow larger-than-screen windows by default. Default is `false`.
*`backgroundColor` string (optional) - The window's background color in Hex, RGB, RGBA, HSL, HSLA or named CSS color format. Alpha in #AARRGGBB format is supported if `transparent` is set to `true`. Default is `#FFF` (white). See [win.setBackgroundColor](../browser-window.md#winsetbackgroundcolorbackgroundcolor) for more information.
*`hasShadow` boolean (optional) - Whether window should have a shadow. Default is `true`.
*`opacity` number (optional) _macOS__Windows_ - 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. Default is `false`.
*`transparent` boolean (optional) - Makes the window [transparent](../../tutorial/window-customization.md#create-transparent-windows).
Default 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
this below.
*`visualEffectState` string (optional) _macOS_ - 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.
Default 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`_macOS_ - 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`_macOS_ - 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.
`tooltip`, `content`, `under-window`, or `under-page`.
*`backgroundMaterial` string (optional) _Windows_ - Set the window's
system-drawn background material, including behind the non-client area.
Can be `auto`, `none`, `mica`, `acrylic` or `tabbed`. See [win.setBackgroundMaterial](../browser-window.md#winsetbackgroundmaterialmaterial-windows) for more information.
*`zoomToPageWidth` boolean (optional) _macOS_ - 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. Default is `false`.
*`tabbingIdentifier` string (optional) _macOS_ - Tab group name, allows
opening the window as a native tab. 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.
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:
* On Linux, possible types are `desktop`, `dock`, `toolbar`, `splash`,
`notification`.
* The `desktop` type places the window at the desktop background window level
(kCGDesktopWindowLevel - 1). However, note that a desktop window will not
receive focus, keyboard, or mouse events. You can still use globalShortcut to
receive input sparingly.
* The `dock` type creates a dock-like window behavior.
* The `toolbar` type creates a window with a toolbar appearance.
* The `splash` type behaves in a specific way. It is not
draggable, even if the CSS styling of the window's body contains
-webkit-app-region: drag. This type is commonly used for splash screens.
* The `notification` type creates a window that behaves like a system notification.
* On macOS, possible types are `desktop`, `textured`, `panel`.
* The `textured` type adds metal gradient appearance
(`NSWindowStyleMaskTexturedBackground`).
* The `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.
* The `panel` type enables the window to float on top of full-screened apps
by adding the `NSWindowStyleMaskNonactivatingPanel` style mask,normally
reserved for NSPanel, at runtime. Also, the window will appear on all
*`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.
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. Default is `false`.
*`center` boolean (optional) - Show window in the center of the screen. Default is `false`.
*`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) _macOS__Windows_ - Whether window is
movable. This is not implemented on Linux. Default is `true`.
*`minimizable` boolean (optional) _macOS__Windows_ - Whether window is
minimizable. This is not implemented on Linux. Default is `true`.
*`maximizable` boolean (optional) _macOS__Windows_ - Whether window is
maximizable. This is not implemented on Linux. Default is `true`.
*`closable` boolean (optional) _macOS__Windows_ - Whether window is
closable. This is not implemented on Linux. Default is `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. Default is `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. Default is `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. Default is `true`.
*`simpleFullscreen` boolean (optional) _macOS_ - Use pre-Lion fullscreen on
macOS. Default is `false`.
*`skipTaskbar` boolean (optional) _macOS__Windows_ - Whether to show the window in taskbar.
Default is `false`.
*`hiddenInMissionControl` boolean (optional) _macOS_ - Whether window should be hidden when the user toggles into mission control.
*`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](../native-image.md) | 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. Default is `true`.
*`frame` boolean (optional) - Specify `false` to create a
[frameless window](../../tutorial/window-customization.md#create-frameless-windows). 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
window is a child window. Default is `false`.
*`acceptFirstMouse` boolean (optional) _macOS_ - 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.
Default is `false`.
*`autoHideMenuBar` boolean (optional) - Auto hide the menu bar unless the `Alt`
key is pressed. Default is `false`.
*`enableLargerThanScreen` boolean (optional) _macOS_ - Enable the window to
be resized larger than screen. Only relevant for macOS, as other OSes
allow larger-than-screen windows by default. Default is `false`.
*`backgroundColor` string (optional) - The window's background color in Hex, RGB, RGBA, HSL, HSLA or named CSS color format. Alpha in #AARRGGBB format is supported if `transparent` is set to `true`. Default is `#FFF` (white). See [win.setBackgroundColor](../browser-window.md#winsetbackgroundcolorbackgroundcolor) for more information.
*`hasShadow` boolean (optional) - Whether window should have a shadow. Default is `true`.
*`opacity` number (optional) _macOS__Windows_ - 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. Default is `false`.
*`transparent` boolean (optional) - Makes the window [transparent](../../tutorial/window-customization.md#create-transparent-windows).
Default 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
this below.
*`visualEffectState` string (optional) _macOS_ - 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.
Default 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`_macOS_ - 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`_macOS_ - 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.
`tooltip`, `content`, `under-window`, or `under-page`.
*`backgroundMaterial` string (optional) _Windows_ - Set the window's
system-drawn background material, including behind the non-client area.
Can be `auto`, `none`, `mica`, `acrylic` or `tabbed`. See [win.setBackgroundMaterial](../browser-window.md#winsetbackgroundmaterialmaterial-windows) for more information.
*`zoomToPageWidth` boolean (optional) _macOS_ - 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. Default is `false`.
*`tabbingIdentifier` string (optional) _macOS_ - Tab group name, allows
opening the window as a native tab. 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` [WebPreferences](web-preferences.md?inline) (optional) - Settings of web page's features.
*`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`.
*`titleBarOverlay` Object | Boolean (optional) - When using a frameless window in conjunction 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][overlay-javascript-apis] and [CSS Environment Variables][overlay-css-env-vars]. 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.
*`height` Integer (optional) _macOS__Windows_ - The height of the title bar and Window Controls Overlay in pixels. Default is system height.
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:
* On Linux, possible types are `desktop`, `dock`, `toolbar`, `splash`,
`notification`.
* The `desktop` type places the window at the desktop background window level
(kCGDesktopWindowLevel - 1). However, note that a desktop window will not
receive focus, keyboard, or mouse events. You can still use globalShortcut to
receive input sparingly.
* The `dock` type creates a dock-like window behavior.
* The `toolbar` type creates a window with a toolbar appearance.
* The `splash` type behaves in a specific way. It is not
draggable, even if the CSS styling of the window's body contains
-webkit-app-region: drag. This type is commonly used for splash screens.
* The `notification` type creates a window that behaves like a system notification.
* On macOS, possible types are `desktop`, `textured`, `panel`.
* The `textured` type adds metal gradient appearance
(`NSWindowStyleMaskTexturedBackground`).
* The `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.
* The `panel` type enables the window to float on top of full-screened apps
by adding the `NSWindowStyleMaskNonactivatingPanel` style mask,normally
reserved for NSPanel, at runtime. Also, the window will appear on all
*`action` string - Can be `allow` or `deny`. Controls whether new window should be created.
*`overrideBrowserWindowOptions` BrowserWindowConstructorOptions (optional) - Allows customization of the created window.
*`outlivesOpener` boolean (optional) - By default, child windows are closed when their opener is closed. This can be
changed by specifying `outlivesOpener: true`, in which case the opened window will not be closed when its opener is closed.
*`createWindow` (options: BrowserWindowConstructorOptions) => WebContents (optional) - If specified, will be called instead of `new BrowserWindow` to create the new child window and event [`did-create-window`](../web-contents.md#event-did-create-window) will not be emitted. Constructed child window should use passed `options` object. This can be used for example to have the new window open as a BrowserView instead of in a separate window.
* Icons passed to the Tray constructor should be [Template Images](native-image.md#template-image).
* Icons passed to the Tray constructor should be [Template Images](native-image.md#template-image-macos).
* To make sure your icon isn't grainy on retina monitors, be sure your `@2x` image is 144dpi.
* If you are bundling your application (e.g., with webpack for development), be sure that the file names are not being mangled or hashed. The filename needs to end in Template, and the `@2x` image needs to have the same filename as the standard image, or MacOS will not magically invert your image's colors or use the high density image.
* 16x16 (72dpi) and 32x32@2x (144dpi) work well for most icons.
* Options are listed in [SkParseColor.cpp](https://source.chromium.org/chromium/chromium/src/+/main:third_party/skia/src/utils/SkParseColor.cpp;l=11-152;drc=eea4bf52cb0d55e2a39c828b017c80a5ee054148)
* Similar to CSS Color Module Level 3 keywords, but case-sensitive.
* e.g. `blueviolet` or `red`
**Note:** Hex format with alpha takes `AARRGGBB` or `ARGB`, _not_`RRGGBBAA` or `RGB`.
#### `view.setVisible(visible)`
*`visible` boolean - If false, the view will be hidden from display.
### Instance Properties
Objects created with `new View` have the following properties:
#### `view.children` _Readonly_
A `View[]` property representing the child views of this view.
**Note:** 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event).
#### Event: 'crashed' _Deprecated_
Returns:
*`event` Event
*`killed` boolean
Emitted when the renderer process 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. It
isn't always because it crashed. The `killed` boolean can be replaced by
checking `reason === 'killed'` when you switch to that event.
#### Event: 'render-process-gone'
Returns:
@@ -596,6 +582,15 @@ Returns:
Emitted when a link is clicked in DevTools or 'Open in new tab' is selected for a link in its context menu.
#### Event: 'devtools-search-query'
Returns:
*`event` Event
*`query` string - text to query for.
Emitted when 'Search' is selected for text in its context menu.
#### Event: 'devtools-opened'
Emitted when DevTools is opened.
@@ -688,7 +683,7 @@ Emitted when media is paused or done playing.
Returns:
*`event` Event<>
*`event` Event\<\>
*`audible` boolean - True if one or more frames or child `webContents` are emitting audio.
*`inputFieldType` string _Deprecated_ - If the context menu was invoked on an
input field, the type of that field. Possible values include `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`.
@@ -908,7 +900,7 @@ Returns:
* `webPreferences` [WebPreferences](structures/web-preferences.md) - 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.
* `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
* `url` 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()`
@@ -1311,11 +1303,8 @@ Ignore application menu shortcuts while this web contents is focused.
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', outlivesOpener?: boolean, 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.
By default, child windows are closed when their opener is closed. This can be
changed by specifying `outlivesOpener: true`, in which case the opened window
will not be closed when its opener is closed.
Returns `WindowOpenHandlerResponse` - When set to `{ action: 'deny' }` cancels the creation of the new
window. `{ action: 'allow' }` will allow the new window to be created.
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'}`.
@@ -1326,6 +1315,26 @@ submitting a form with `<form target="_blank">`. See
[`window.open()`](window-open.md) for more details and how to use this in
conjunction with `did-create-window`.
An example showing how to customize the process of new `BrowserWindow` creation to be `BrowserView` attached to main window instead:
* `footerTemplate` string (optional) - HTML template for the print footer. Should use the same format as the `headerTemplate`.
* `preferCSSPageSize` boolean (optional) - Whether or not to prefer page size as defined by css. Defaults to false, in which case the content will be scaled to fit the paper size.
* `generateTaggedPDF` boolean (optional) _Experimental_ - Whether or not to generate a tagged (accessible) PDF. Defaults to false. As this property is experimental, the generated PDF may not adhere fully to PDF/UA and WCAG standards.
* `generateDocumentOutline` boolean (optional) _Experimental_ - Whether or not to generate a PDF document outline from content headers. Defaults to false.
Returns `Promise<Buffer>` - Resolves with the generated PDF data.
@@ -1638,24 +1648,26 @@ The `landscape` will be ignored if `@page` CSS at-rule is used in the web page.
*`file` File - A web [File](https://developer.mozilla.org/en-US/docs/Web/API/File) object.
Returns `string` - The file system path that this `File` object points to. In the case where the object passed in is not a `File` object an exception is thrown. In the case where the File object passed in was constructed in JS and is not backed by a file on disk an empty string is returned.
This method superceded the previous augmentation to the `File` object with the `path` property. An example is included below.
Electron's `webview` tag is based on [Chromium's `webview`][chrome-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`](browser-view.md),
or an architecture that avoids embedded content altogether.
including rendering, navigation, and event routing. We currently recommend to
not use the `webview` tag and to consider alternatives, like `iframe`, a
[`WebContentsView`](web-contents-view.md), or an architecture that avoids
embedded content altogether.
## Enabling
@@ -220,7 +221,9 @@ windows. Popups are disabled by default.
```
A `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](browser-window.md#new-browserwindowoptions).
The full list of supported preference strings can be found in [BrowserWindow](browser-window.md#new-browserwindowoptions). In addition, webview supports the following preferences:
*`transparent` boolean (optional) - Whether to enable background transparency for the guest page. Default is `true`. **Note:** The guest page's text and background colors are derived from the [color scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme) of its root element. When transparency is enabled, the text color will still change accordingly but the background will remain transparent.
The string follows the same format as the features string in `window.open`.
A name by itself is given a `true` boolean value.
@@ -284,7 +287,7 @@ e.g. the `http://` or `file://`.
Initiates a download of the resource at `url` without navigating.
@@ -577,7 +580,7 @@ Stops any `findInPage` request for the `webview` with the provided `action`.
* `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)
* `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.
@@ -608,6 +611,7 @@ Prints `webview`'s web page. Same as `webContents.print([options])`.
* `footerTemplate` string (optional) - HTML template for the print footer. Should use the same format as the `headerTemplate`.
* `preferCSSPageSize` boolean (optional) - Whether or not to prefer page size as defined by css. Defaults to false, in which case the content will be scaled to fit the paper size.
* `generateTaggedPDF` boolean (optional) _Experimental_ - Whether or not to generate a tagged (accessible) PDF. Defaults to false. As this property is experimental, the generated PDF may not adhere fully to PDF/UA and WCAG standards.
* `generateDocumentOutline` boolean (optional) _Experimental_ - Whether or not to generate a PDF document outline from content headers. Defaults to false.
Returns `Promise<Uint8Array>` - Resolves with the generated PDF data.
* `inputFieldType` string _Deprecated_ - If the context menu was invoked on an
input field, the type of that field. Possible values include `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`.
@@ -12,6 +12,111 @@ This document uses the following convention to categorize breaking changes:
* **Deprecated:** An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release.
* **Removed:** An API or feature was removed, and is no longer supported by Electron.
## Planned Breaking API Changes (31.0)
### Behavior Changed: `nativeImage.toDataURL` will preseve PNG colorspace
PNG decoder implementation has been changed to preserve colorspace data, the
encoded data returned from this function now matches it.
See [crbug.com/332584706](https://issues.chromium.org/issues/332584706) for more information.
### Behavior Changed: `window.flashFrame(bool)` will flash dock icon continuously on macOS
This brings the behavior to parity with Windows and Linux. Prior behavior: The first `flashFrame(true)` bounces the dock icon only once (using the [NSInformationalRequest](https://developer.apple.com/documentation/appkit/nsrequestuserattentiontype/nsinformationalrequest) level) and `flashFrame(false)` does nothing. New behavior: Flash continuously until `flashFrame(false)` is called. This uses the [NSCriticalRequest](https://developer.apple.com/documentation/appkit/nsrequestuserattentiontype/nscriticalrequest) level instead. To explicitly use `NSInformationalRequest` to cause a single dock icon bounce, it is still possible to use [`dock.bounce('informational')`](https://www.electronjs.org/docs/latest/api/dock#dockbouncetype-macos).
## Planned Breaking API Changes (30.0)
### Behavior Changed: cross-origin iframes now use Permission Policy to access features
Cross-origin iframes must now specify features available to a given `iframe` via the `allow`
attribute in order to access them.
See [documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#allow) for
more information.
### Removed: The `--disable-color-correct-rendering` switch
This switch was never formally documented but it's removal is being noted here regardless. Chromium itself now has better support for color spaces so this flag should not be needed.
### Behavior Changed: `BrowserView.setAutoResize` behavior on macOS
In Electron 30, BrowserView is now a wrapper around the new [WebContentsView](api/web-contents-view.md) API.
Previously, the `setAutoResize` function of the `BrowserView` API was backed by [autoresizing](https://developer.apple.com/documentation/appkit/nsview/1483281-autoresizingmask?language=objc) on macOS, and by a custom algorithm on Windows and Linux.
For simple use cases such as making a BrowserView fill the entire window, the behavior of these two approaches was identical.
However, in more advanced cases, BrowserViews would be autoresized differently on macOS than they would be on other platforms, as the custom resizing algorithm for Windows and Linux did not perfectly match the behavior of macOS's autoresizing API.
The autoresizing behavior is now standardized across all platforms.
If your app uses `BrowserView.setAutoResize` to do anything more complex than making a BrowserView fill the entire window, it's likely you already had custom logic in place to handle this difference in behavior on macOS.
If so, that logic will no longer be needed in Electron 30 as autoresizing behavior is consistent.
### Removed: `params.inputFormType` property on `context-menu` on `WebContents`
The `inputFormType` property of the params object in the `context-menu`
event from `WebContents` has been removed. Use the new `formControlType`
property instead.
### Removed: `process.getIOCounters()`
Chromium has removed access to this information.
## Planned Breaking API Changes (29.0)
### Behavior Changed: `ipcRenderer` can no longer be sent over the `contextBridge`
Attempting to send the entire `ipcRenderer` module as an object over the `contextBridge` will now result in
an empty object on the receiving side of the bridge. This change was made to remove / mitigate
a security footgun. You should not directly expose ipcRenderer or its methods over the bridge.
$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")"
```
On Windows:
```sh
# cmd
$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")"
# PowerShell
gn gen out/Testing --args="import(\`"//electron/build/args/testing.gn\`")"
```
**To generate Release build config of Electron:**
On Linux & MacOS
```sh
$ gn gen out/Release --args="import(\"//electron/build/args/release.gn\")"
```
On Windows:
```sh
# cmd
$ gn gen out/Release --args="import(\"//electron/build/args/release.gn\")"
# PowerShell
$ gn gen out/Release --args="import(\`"//electron/build/args/release.gn\`")"
```
**Note:** This will generate a `out/Testing` or `out/Release` build directory under `src/` with the testing or release build depending upon the configuration passed above. You can replace `Testing|Release` with another names, 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`.
> Goma is a distributed compiler service for open-source projects such as
> Chromium and Android.
Electron has a deployment of a custom Goma Backend that we make available to
all Electron Maintainers. See the [Access](#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.
## Enabling Goma
Currently the only supported way to use Goma is to use our [Build Tools](https://github.com/electron/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.
## Building with Goma
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**. We monitor Goma system usage, and users
found to be abusing it with unreasonable concurrency will be de-activated.
```bash
ninja -C out/Testing electron -j 200
```
If you're using `build-tools`, appropriate `-j` values will automatically be used for you.
## Monitoring Goma
If you access [http://localhost:8088](http://localhost:8088) on your local
machine you can monitor compile jobs as they flow through the goma system.
## Access
For 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.
## Uptime / Support
We have automated monitoring of our Goma cluster and cache at https://status.notgoma.com
We 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.
Electron's deployment of Goma is deprecated and we are gradually shifting all usage to the [reclient](reclient.md) system. At some point in 2024 the Goma backend will be shutdown.
ASAR integrity is an experimental feature that validates the contents of your app's
[ASAR archives](./asar-archives.md) at runtime.
Currently ASAR integrity checking is only supported on macOS.
## Version support
## Requirements
Currently, ASAR integrity checking is supported on:
### Electron Forge / Electron Packager
* macOS as of `electron>=16.0.0`
* Windows as of `electron>=30.0.0`
If you are using `>= @electron/packager`, `>= electron-packager@15.4.0` or `>= @electron-forge/core@6.0.0-beta.61` then all these requirements are met for you automatically and you can skip to [Toggling the Fuse](#toggling-the-fuse).
In order to enable ASAR integrity checking, you also need to ensure that your `app.asar` file
was generated by a version of the `@electron/asar` npm package that supports ASAR integrity.
### Other build systems
Support was introduced in `asar@3.1.0`. Note that this package has since migrated over to `@electron/asar`.
All versions of `@electron/asar` support ASAR integrity.
In order to enable ASAR integrity checking you need to ensure that your `app.asar` file was generated by a version of the `asar` npm package that supports asar integrity. Support was introduced in version `3.1.0`.
## How it works
Your must then populate a valid `ElectronAsarIntegrity` dictionary block in your packaged apps `Info.plist`. An example is included below.
Each ASAR archive contains a JSON string header. The header format includes an `integrity` object
that contain a hex encoded hash of the entire archive as well as an array of hex encoded hashes for each
Valid `algorithm` values are currently `SHA256` only. The `hash` is a hash of the ASAR header using the given algorithm. The `asar` package exposes a `getRawHeader` method whose result can then be hashed to generate this value.
Separately, you need to define a hex encoded hash of the entire ASAR header when packaging your Electron app.
## Toggling the Fuse
When ASAR integrity is enabled, your Electron app will verify the header hash of the ASAR archive on runtime.
If no hash is present or if there is a mismatch in the hashes, the app will forcefully terminate.
ASAR integrity checking is currently disabled by default and can be enabled by toggling a fuse. See [Electron Fuses](fuses.md) for more information on what Electron Fuses are and how they work. When enabling this fuse you typically also want to enable the `onlyLoadAppFromAsar` fuse otherwise the validity checking can be bypassed via the Electron app code search path.
## Enabling ASAR integrity in the binary
ASAR integrity checking is currently disabled by default in Electron and can
be enabled on build time by toggling the `EnableEmbeddedAsarIntegrityValidation`
[Electron fuse](fuses.md).
When enabling this fuse, you typically also want to enable the `onlyLoadAppFromAsar` fuse.
Otherwise, the validity checking can be bypassed via the Electron app code search path.
- Amongst others, please shop around to find one that suits your needs! 😄
The new EV certificates are required to be stored on a hardware storage module
compliant with FIPS 140 Level 2, Common Criteria EAL 4+ or equivalent. In other words,
the certificate cannot be simply downloaded onto a CI infrastructure. In practice,
those storage modules look like fancy USB thumb drives.
:::caution Keep your certificate password private
Your certificate password should be a **secret**. Do not share it publicly or
commit it to your source code.
:::
Many certificate providers now offer "cloud-based signing" - the entire signing hardware
is in their data center and you can use it to remotely sign code. This approach is
popular with Electron maintainers since it makes signing your applications in CI (like
GitHub Actions, CircleCI, etc) relatively easy.
At the time of writing, Electron's own apps use [DigiCert KeyLocker](https://docs.digicert.com/en/digicert-keylocker.html), but any provider that provides a command line tool for
signing files will be compatible with Electron's tooling.
All tools in the Electron ecosystem use [`@electron/windows-sign`][] and typically
expose configuration options through a `windowsSign` property. You can either use it
to sign files directly - or use the same `windowsSign` configuration across Electron
Forge, [`@electron/packager`][], [`electron-winstaller`][], and [`electron-wix-msi`][].
### Using Electron Forge
Electron Forge is the recommended way to sign your `Squirrel.Windows` and `WiX MSI` installers. Detailed instructions on how to configure your application can be found in the [Electron Forge Code Signing Tutorial](https://www.electronforge.io/guides/code-signing/code-signing-macos).
Electron Forge is the recommended way to sign your app as well as your `Squirrel.Windows`
and `WiX MSI` installers. Detailed instructions on how to configure your application can
be found in the [Electron Forge Code Signing Tutorial](https://www.electronforge.io/guides/code-signing/code-signing-windows).
### Using Electron Packager
If you're not using an integrated build pipeline like Forge, you
are likely using [`@electron/packager`][], which includes [`@electron/windows-sign`][].
If you're using Packager's API, you can pass [in configuration that signs
your application](https://electron.github.io/packager/main/modules.html). If the
example below does not meet your needs, please see [`@electron/windows-sign`][]
for the many possible configuration options.
```js @ts-nocheck
const packager = require('@electron/packager')
packager({
dir: '/path/to/my/app',
windowsSign: {
signWithParams: '--my=custom --parameters',
// If signtool.exe does not work for you, customize!
signToolPath: 'C:\\Path\\To\\my-custom-tool.exe'
}
})
```
### Using electron-winstaller (Squirrel.Windows)
[`electron-winstaller`][] is a package that can generate Squirrel.Windows installers for your
Electron app. This is the tool used under the hood by Electron Forge's
[Squirrel.Windows Maker][maker-squirrel]. If you're not using Electron Forge and want to use
`electron-winstaller` directly, use the `certificateFile` and `certificatePassword` configuration
options when creating your installer.
[Squirrel.Windows Maker][maker-squirrel]. Just like `@electron/packager`, it uses
[`@electron/windows-sign`][] under the hood and supports the same `windowsSign`
@@ -15,7 +15,7 @@ Fuses are the solution to this problem, at a high level they are "magic bits" in
**Default:** Enabled
**@electron/fuses:** `FuseV1Options.RunAsNode`
The runAsNode fuse toggles whether the `ELECTRON_RUN_AS_NODE` environment variable is respected or not. Please note that if this fuse is disabled then `process.fork` in the main process will not function as expected as it depends on this environment variable to function.
The runAsNode fuse toggles whether the `ELECTRON_RUN_AS_NODE` environment variable is respected or not. Please note that if this fuse is disabled then `process.fork` in the main process will not function as expected as it depends on this environment variable to function. Instead, we recommend that you use [Utility Processes](../api/utility-process.md), which work for many use cases where you need a standalone Node.js process (like a Sqlite server process or similar scenarios).
### `cookieEncryption`
@@ -29,7 +29,7 @@ The cookieEncryption fuse toggles whether the cookie store on disk is encrypted
The nodeOptions fuse toggles whether the [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#node_optionsoptions) environment variable is respected or not. This environment variable can be used to pass all kinds of custom options to the Node.js runtime and isn't typically used by apps in production. Most apps can safely disable this fuse.
The nodeOptions fuse toggles whether the [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#node_optionsoptions) and [`NODE_EXTRA_CA_CERTS`](https://github.com/nodejs/node/blob/main/doc/api/cli.md#node_extra_ca_certsfile) environment variables are respected. The `NODE_OPTIONS` environment variable can be used to pass all kinds of custom options to the Node.js runtime and isn't typically used by apps in production. Most apps can safely disable this fuse.
### `nodeCliInspect`
@@ -61,6 +61,19 @@ The onlyLoadAppFromAsar fuse changes the search system that Electron uses to loc
The loadBrowserProcessSpecificV8Snapshot fuse changes which V8 snapshot file is used for the browser process. By default Electron's processes will all use the same V8 snapshot file. When this fuse is enabled the browser process uses the file called `browser_v8_context_snapshot.bin` for its V8 snapshot. The other processes will use the V8 snapshot file that they normally do.
The grantFileProtocolExtraPrivileges fuse changes whether pages loaded from the `file://` protocol are given privileges beyond what they would receive in a traditional web browser. This behavior was core to Electron apps in original versions of Electron but is no longer required as apps should be [serving local files from custom protocols](./security.md#18-avoid-usage-of-the-file-protocol-and-prefer-usage-of-custom-protocols) now instead. If you aren't serving pages from `file://` you should disable this fuse.
The extra privileges granted to the `file://` protocol by this fuse are incompletely documented below:
*`file://` protocol pages can use `fetch` to load other assets over `file://`
*`file://` protocol pages can use service workers
*`file://` protocol pages have universal access granted to child frames also running on `file://` protocols regardless of sandbox settings
The main process also controls your application's lifecycle through Electron's
[`app`][app] module. This module provides a large set of events and methods
that you can use to add custom application behaviour (for instance, programmatically
that you can use to add custom application behavior (for instance, programmatically
quitting your application, modifying the application dock, or showing an About panel).
As a practical example, the app shown in the [quick start guide][quick-start-lifecycle]
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
