Compare commits

..

1 Commits

Author SHA1 Message Date
Shelley Vohr
a843792e12 chore: try removing debugger timeout patch 2023-09-06 14:27:42 +02:00
554 changed files with 3699 additions and 16958 deletions

View File

@@ -65,9 +65,6 @@ jobs:
curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh | DESTDIR=$CIRCLECI_BINARY bash
node build.js
name: Pack config.yml
- run:
name: Set params
command: node .circleci/config/params.js
- continuation/continue:
configuration_path: .circleci/config-staging/built.yml
parameters: /tmp/pipeline-parameters.json

View File

@@ -35,16 +35,6 @@ parameters:
default: all
enum: ["all", "osx-x64", "osx-arm64", "mas-x64", "mas-arm64"]
medium-linux-executor:
type: enum
default: electronjs/aks-linux-medium
enum: ["electronjs/aks-linux-medium", "medium"]
large-linux-executor:
type: enum
default: electronjs/aks-linux-large
enum: ["electronjs/aks-linux-large", "2xlarge"]
# Executors
executors:
linux-docker:
@@ -52,9 +42,9 @@ executors:
size:
description: "Docker executor size"
type: enum
# aks-linux-medium === 8 core (32 core host, shared with other builds)
# aks-linux-large === 32 core
# 2xlarge should not be used directly, use the pipeline param instead
enum: ["medium", "electronjs/aks-linux-medium", "xlarge", "electronjs/aks-linux-large", "2xlarge"]
enum: ["medium", "xlarge", "electronjs/aks-linux-medium", "electronjs/aks-linux-large"]
docker:
- image: ghcr.io/electron/build:e6bebd08a51a0d78ec23e5b3fd7e7c0846412328
resource_class: << parameters.size >>
@@ -68,8 +58,8 @@ executors:
version:
description: "xcode version"
type: enum
enum: ["15.0.0", "14.0.0"]
default: 15.0.0
enum: ["14.3.0", "14.0.0"]
default: 14.3.0
macos:
xcode: << parameters.version >>
resource_class: << parameters.size >>
@@ -359,7 +349,7 @@ step-setup-goma-for-build: &step-setup-goma-for-build
exit 1
fi
echo 'export GN_GOMA_FILE='`node -e "console.log(require('./src/utils/goma.js').gnFilePath)"` >> $BASH_ENV
echo 'export GOMA_DIR='`node -e "console.log(require('./src/utils/goma.js').dir)"` >> $BASH_ENV
echo 'export LOCAL_GOMA_DIR='`node -e "console.log(require('./src/utils/goma.js').dir)"` >> $BASH_ENV
echo 'export GOMA_FALLBACK_ON_AUTH_FAILURE=true' >> $BASH_ENV
cd ..
touch "${TMPDIR:=/tmp}"/.goma-ready
@@ -660,7 +650,6 @@ step-nodejs-headers-build: &step-nodejs-headers-build
step-electron-publish: &step-electron-publish
run:
name: Publish Electron Dist
no_output_timeout: 30m
command: |
if [ "`uname`" == "Darwin" ]; then
rm -rf src/out/Default/obj
@@ -755,8 +744,8 @@ step-show-goma-stats: &step-show-goma-stats
command: |
set +e
set +o pipefail
python3 $GOMA_DIR/goma_ctl.py stat
python3 $GOMA_DIR/diagnose_goma_log.py
$LOCAL_GOMA_DIR/goma_ctl.py stat
$LOCAL_GOMA_DIR/diagnose_goma_log.py
true
when: always
background: true
@@ -776,7 +765,6 @@ step-mksnapshot-build: &step-mksnapshot-build
fi
sed $SEDOPTION '/.*builtins-pgo/d' out/Default/mksnapshot_args
sed $SEDOPTION '/--turbo-profiling-input/d' out/Default/mksnapshot_args
sed $SEDOPTION '/The gn arg use_goma=true .*/d' out/Default/mksnapshot_args
if [ "`uname`" != "Darwin" ]; then
if [ "$TARGET_ARCH" == "arm" ]; then
electron/script/strip-binaries.py --file $PWD/out/Default/clang_x86_v8_arm/mksnapshot
@@ -907,26 +895,14 @@ step-touch-sync-done: &step-touch-sync-done
step-maybe-restore-src-cache: &step-maybe-restore-src-cache
restore_cache:
keys:
- v17-src-cache-{{ checksum "src/electron/.depshash" }}
- v16-src-cache-{{ checksum "src/electron/.depshash" }}
name: Restoring src cache
step-maybe-restore-src-cache-marker: &step-maybe-restore-src-cache-marker
restore_cache:
keys:
- v17-src-cache-marker-{{ checksum "src/electron/.depshash" }}
- v16-src-cache-marker-{{ checksum "src/electron/.depshash" }}
name: Restoring src cache marker
step-maybe-restore-src-cache-aks: &step-maybe-restore-src-cache-aks
restore_cache_aks:
step-name: Restoring src cache
cache_key: v17-src-cache-$(shasum src/electron/.depshash | cut -f1 -d' ')
cache_path: /var/portal
step-maybe-restore-src-cache-marker-aks: &step-maybe-restore-src-cache-marker-aks
restore_cache_aks:
step-name: Restoring src cache marker
cache_key: v17-src-cache-marker-$(shasum src/electron/.depshash | cut -f1 -d' ')
cache_path: "."
# Restore exact or closest git cache based on the hash of DEPS and .circle-sync-done
# If the src cache was restored above then this will match an empty cache
# If the src cache was not restored above then this will match a close git cache
@@ -939,12 +915,6 @@ step-maybe-restore-git-cache: &step-maybe-restore-git-cache
- v1-git-cache-{{ checksum "src/electron/.circle-sync-done" }}
name: Conditionally restoring git cache
step-maybe-restore-git-cache-aks: &step-maybe-restore-git-cache-aks
restore_cache_aks:
step-name: Conditionally restoring git cache (aks)
cache_key: v1-git-cache-$(shasum src/electron/.circle-sync-done | cut -f1 -d' ')-$(shasum src/electron/DEPS | cut -f1 -d' ') v1-git-cache-$(shasum src/electron/.circle-sync-done | cut -f1 -d' ')
cache_path: git-cache
step-set-git-cache-path: &step-set-git-cache-path
run:
name: Set GIT_CACHE_PATH to make gclient to use the cache
@@ -962,12 +932,6 @@ step-save-git-cache: &step-save-git-cache
key: v1-git-cache-{{ checksum "src/electron/.circle-sync-done" }}-{{ checksum "src/electron/DEPS" }}
name: Persisting git cache
step-save-git-cache-aks: &step-save-git-cache-aks
save_cache_aks:
step-name: Persisting git cache (AKS)
cache_key: v1-git-cache-$(shasum src/electron/.circle-sync-done | cut -f1 -d' ')-$(shasum src/electron/DEPS | cut -f1 -d' ')
cache_path: git-cache
step-run-electron-only-hooks: &step-run-electron-only-hooks
run:
name: Run Electron Only Hooks
@@ -1005,7 +969,7 @@ step-save-src-cache: &step-save-src-cache
save_cache:
paths:
- /var/portal
key: v17-src-cache-{{ checksum "/var/portal/src/electron/.depshash" }}
key: v16-src-cache-{{ checksum "/var/portal/src/electron/.depshash" }}
name: Persisting src cache
step-make-src-cache-marker: &step-make-src-cache-marker
run:
@@ -1015,17 +979,7 @@ step-save-src-cache-marker: &step-save-src-cache-marker
save_cache:
paths:
- .src-cache-marker
key: v17-src-cache-marker-{{ checksum "/var/portal/src/electron/.depshash" }}
step-save-src-cache-aks: &step-save-src-cache-aks
save_cache_aks:
step-name: Persisting src cache (aks)
cache_key: v17-src-cache-$(shasum /var/portal/src/electron/.depshash | cut -f1 -d' ')
cache_path: /var/portal
step-save-src-cache-marker-aks: &step-save-src-cache-marker-aks
save_cache_aks:
step-name: Persisting src cache marker (aks)
cache_key: v17-src-cache-marker-$(shasum /var/portal/src/electron/.depshash | cut -f1 -d' ')
cache_path: .src-cache-marker
key: v16-src-cache-marker-{{ checksum "/var/portal/src/electron/.depshash" }}
step-maybe-early-exit-no-doc-change: &step-maybe-early-exit-no-doc-change
run:
@@ -1051,6 +1005,15 @@ step-ts-compile: &step-ts-compile
done
# List of all steps.
steps-electron-gn-check: &steps-electron-gn-check
steps:
- *step-setup-goma-for-build
- checkout-from-cache
- *step-setup-env-for-build
- *step-wait-for-goma
- *step-gn-gen-default
- *step-gn-check
steps-electron-ts-compile-for-doc-change: &steps-electron-ts-compile-for-doc-change
steps:
# Checkout - Copied from steps-checkout
@@ -1062,92 +1025,11 @@ steps-electron-ts-compile-for-doc-change: &steps-electron-ts-compile-for-doc-cha
# Command Aliases
commands:
aks-specific-step:
parameters:
circle:
type: steps
aks:
type: steps
could-be-aks:
type: boolean
description: Only set this to true on linux hosts
steps:
- when:
condition:
or:
- equal: [<< parameters.could-be-aks >>, false]
- equal: [<< pipeline.parameters.large-linux-executor >>, 2xlarge]
steps: << parameters.circle >>
- when:
condition:
and:
- equal: [<< parameters.could-be-aks >>, true]
- equal: [<< pipeline.parameters.large-linux-executor >>, electronjs/aks-linux-large]
steps: << parameters.aks >>
save_cache_aks:
parameters:
step-name:
type: string
cache_key:
type: string
cache_path:
type: string
steps:
- run:
name: << parameters.step-name >>
command: |
cache_key="<< parameters.cache_key >>"
final_cache_path=/mnt/cross-instance-cache/${cache_key}.tar
echo "Using cache key: $cache_key"
echo "Checking path: $final_cache_path"
if [ ! -f "$final_cache_path" ]; then
echo "Cache key not founding, storing tarball"
tmp_container=/mnt/cross-instance-cache/tmp/$CIRCLE_WORKFLOW_JOB_ID
tmp_cache_path=$tmp_container/${cache_key}.tar
mkdir -p $tmp_container
if [ -f "<< parameters.cache_path >>" ]; then
tar -cf $tmp_cache_path -C $(dirname << parameters.cache_path >>) ./$(basename << parameters.cache_path >>)
else
tar -cf $tmp_cache_path -C << parameters.cache_path >>/ ./
fi
mv -vn $tmp_cache_path $final_cache_path
rm -rf $tmp_container
else
echo "Cache key already exists, skipping.."
fi
restore_cache_aks:
parameters:
step-name:
type: string
cache_key:
type: string
cache_path:
type: string
steps:
- run:
name: << parameters.step-name >>
command: |
df -h
for cache_key in << parameters.cache_key >>; do
cache_path=/mnt/cross-instance-cache/${cache_key}.tar
echo "Using cache key: $cache_key"
echo "Checking path: $cache_path"
if [ ! -f "$cache_path" ]; then
echo "Cache key not found, nothing to restore..."
else
echo "Cache key found, restoring to path..."
mkdir -p << parameters.cache_path >>/
tar -xf /mnt/cross-instance-cache/${cache_key}.tar -C << parameters.cache_path >>/
exit 0
fi
done
maybe-restore-portaled-src-cache:
parameters:
halt-if-successful:
type: boolean
default: false
could-be-aks:
type: boolean
steps:
- run:
name: Prepare for cross-OS sync restore
@@ -1157,44 +1039,23 @@ commands:
- when:
condition: << parameters.halt-if-successful >>
steps:
- aks-specific-step:
circle:
- *step-maybe-restore-src-cache-marker
aks:
- *step-maybe-restore-src-cache-marker-aks
could-be-aks: << parameters.could-be-aks >>
- *step-maybe-restore-src-cache-marker
- run:
name: Halt the job early if the src cache exists
command: |
if [ -f ".src-cache-marker" ]; then
circleci-agent step halt
fi
- aks-specific-step:
circle:
- *step-maybe-restore-src-cache
aks:
- *step-maybe-restore-src-cache-aks
could-be-aks: << parameters.could-be-aks >>
- *step-maybe-restore-src-cache
- run:
name: Fix the src cache restore point
name: Fix the src cache restore point on macOS
command: |
if [ -d "/var/portal/src" ]; then
echo Relocating Cache
rm -rf src
mv /var/portal/src ./
fi
run-gn-check:
parameters:
could-be-aks:
type: boolean
steps:
- *step-setup-goma-for-build
- checkout-from-cache:
could-be-aks: << parameters.could-be-aks >>
- *step-setup-env-for-build
- *step-wait-for-goma
- *step-gn-gen-default
- *step-gn-check
build_and_save_artifacts:
parameters:
artifact-key:
@@ -1308,16 +1169,12 @@ commands:
mv_if_exist cross-arch-snapshots src
checkout-from-cache:
parameters:
could-be-aks:
type: boolean
steps:
- *step-checkout-electron
- *step-depot-tools-get
- *step-depot-tools-add-to-path
- *step-generate-deps-hash
- maybe-restore-portaled-src-cache:
could-be-aks: << parameters.could-be-aks >>
- maybe-restore-portaled-src-cache
- run:
name: Ensure src checkout worked
command: |
@@ -1429,8 +1286,6 @@ commands:
after-persist:
type: steps
default: []
could-be-aks:
type: boolean
steps:
- when:
condition: << parameters.attach >>
@@ -1448,8 +1303,7 @@ commands:
- when:
condition: << parameters.checkout-and-assume-cache >>
steps:
- checkout-from-cache:
could-be-aks: << parameters.could-be-aks >>
- checkout-from-cache
- when:
condition: << parameters.checkout >>
steps:
@@ -1465,15 +1319,8 @@ commands:
steps:
- maybe-restore-portaled-src-cache:
halt-if-successful: << parameters.checkout-to-create-src-cache >>
could-be-aks: << parameters.could-be-aks >>
- aks-specific-step:
circle:
- *step-maybe-restore-git-cache
aks:
- *step-maybe-restore-git-cache-aks
could-be-aks: << parameters.could-be-aks >>
- *step-maybe-restore-git-cache
- *step-set-git-cache-path
- *step-fix-known-hosts-linux
# This sync call only runs if .circle-sync-done is an EMPTY file
- *step-gclient-sync
- store_artifacts:
@@ -1489,12 +1336,7 @@ commands:
- when:
condition: << parameters.save-git-cache >>
steps:
- aks-specific-step:
circle:
- *step-save-git-cache
aks:
- *step-save-git-cache-aks
could-be-aks: << parameters.could-be-aks >>
- *step-save-git-cache
# Mark sync as done _after_ saving the git cache so that it is uploaded
# only when the src cache was not present
# Their are theoretically two cases for this cache key
@@ -1544,19 +1386,9 @@ commands:
sudo mkdir -p /var/portal
sudo chown -R $(id -u):$(id -g) /var/portal
mv ./src /var/portal
- aks-specific-step:
circle:
- *step-save-src-cache
aks:
- *step-save-src-cache-aks
could-be-aks: << parameters.could-be-aks >>
- *step-save-src-cache
- *step-make-src-cache-marker
- aks-specific-step:
circle:
- *step-save-src-cache-marker
aks:
- *step-save-src-cache-marker-aks
could-be-aks: << parameters.could-be-aks >>
- *step-save-src-cache-marker
- when:
condition: << parameters.build >>
@@ -1610,18 +1442,6 @@ commands:
condition: << parameters.build >>
steps:
- *step-maybe-notify-slack-failure
- when:
condition: << parameters.could-be-aks >>
steps:
- run:
name: Wait for active debug sessions
command: |
while [ -f /var/.ssh-lock ]
do
sleep 60
done
no_output_timeout: 2h
when: always
electron-tests:
parameters:
@@ -1808,7 +1628,7 @@ jobs:
linux-make-src-cache:
executor:
name: linux-docker
size: << pipeline.parameters.large-linux-executor >>
size: xlarge
environment:
<<: *env-linux-2xlarge
GCLIENT_EXTRA_ARGS: '--custom-var=checkout_arm=True --custom-var=checkout_arm64=True'
@@ -1821,7 +1641,6 @@ jobs:
checkout-to-create-src-cache: true
artifact-key: 'nil'
build-type: 'nil'
could-be-aks: true
mac-checkout:
executor:
@@ -1841,7 +1660,6 @@ jobs:
restore-src-cache: false
artifact-key: 'nil'
build-type: 'nil'
could-be-aks: false
mac-make-src-cache-x64:
executor:
@@ -1861,7 +1679,6 @@ jobs:
checkout-to-create-src-cache: true
artifact-key: 'nil'
build-type: 'nil'
could-be-aks: false
mac-make-src-cache-arm64:
executor:
@@ -1881,13 +1698,12 @@ jobs:
checkout-to-create-src-cache: true
artifact-key: 'nil'
build-type: 'nil'
could-be-aks: false
# Layer 2: Builds.
linux-x64-testing:
executor:
name: linux-docker
size: << pipeline.parameters.large-linux-executor >>
size: electronjs/aks-linux-large
environment:
<<: *env-global
<<: *env-testing-build
@@ -1900,12 +1716,11 @@ jobs:
checkout-and-assume-cache: true
artifact-key: 'linux-x64'
build-type: 'Linux'
could-be-aks: true
linux-x64-testing-asan:
executor:
name: linux-docker
size: << pipeline.parameters.large-linux-executor >>
size: electronjs/aks-linux-large
environment:
<<: *env-global
<<: *env-testing-build
@@ -1916,29 +1731,25 @@ jobs:
steps:
- electron-build:
persist: true
checkout: false
checkout-and-assume-cache: true
checkout: true
build-nonproprietary-ffmpeg: false
artifact-key: 'linux-x64-asan'
build-type: 'Linux'
could-be-aks: true
linux-x64-testing-gn-check:
executor:
name: linux-docker
size: << pipeline.parameters.medium-linux-executor >>
size: medium
environment:
<<: *env-linux-medium
<<: *env-testing-build
GCLIENT_EXTRA_ARGS: '--custom-var=checkout_arm=True --custom-var=checkout_arm64=True'
steps:
- run-gn-check:
could-be-aks: true
<<: *steps-electron-gn-check
linux-x64-publish:
executor:
name: linux-docker
size: << pipeline.parameters.large-linux-executor >>
size: electronjs/aks-linux-large
environment:
<<: *env-linux-2xlarge-release
<<: *env-release-build
@@ -1961,7 +1772,7 @@ jobs:
linux-arm-testing:
executor:
name: linux-docker
size: << pipeline.parameters.large-linux-executor >>
size: electronjs/aks-linux-large
environment:
<<: *env-global
<<: *env-arm
@@ -1977,12 +1788,11 @@ jobs:
checkout-and-assume-cache: true
artifact-key: 'linux-arm'
build-type: 'Linux ARM'
could-be-aks: true
linux-arm-publish:
executor:
name: linux-docker
size: << pipeline.parameters.large-linux-executor >>
size: electronjs/aks-linux-large
environment:
<<: *env-linux-2xlarge-release
<<: *env-arm
@@ -2007,7 +1817,7 @@ jobs:
linux-arm64-testing:
executor:
name: linux-docker
size: << pipeline.parameters.large-linux-executor >>
size: electronjs/aks-linux-large
environment:
<<: *env-global
<<: *env-arm64
@@ -2023,25 +1833,22 @@ jobs:
checkout-and-assume-cache: true
artifact-key: 'linux-arm64'
build-type: 'Linux ARM64'
could-be-aks: true
linux-arm64-testing-gn-check:
executor:
name: linux-docker
size: << pipeline.parameters.medium-linux-executor >>
size: medium
environment:
<<: *env-linux-medium
<<: *env-arm64
<<: *env-testing-build
GCLIENT_EXTRA_ARGS: '--custom-var=checkout_arm=True --custom-var=checkout_arm64=True'
steps:
- run-gn-check:
could-be-aks: true
<<: *steps-electron-gn-check
linux-arm64-publish:
executor:
name: linux-docker
size: << pipeline.parameters.large-linux-executor >>
size: electronjs/aks-linux-large
environment:
<<: *env-linux-2xlarge-release
<<: *env-arm64
@@ -2096,7 +1903,6 @@ jobs:
root: .
paths:
- generated_artifacts_mas-x64
could-be-aks: false
osx-testing-x64-gn-check:
executor:
@@ -2106,9 +1912,7 @@ jobs:
<<: *env-machine-mac
<<: *env-testing-build
GCLIENT_EXTRA_ARGS: '--custom-var=checkout_mac=True --custom-var=host_os=mac'
steps:
- run-gn-check:
could-be-aks: false
<<: *steps-electron-gn-check
osx-publish-x64:
executor:
@@ -2190,7 +1994,6 @@ jobs:
root: .
paths:
- generated_artifacts_mas-arm64
could-be-aks: false
mas-publish-x64:
executor:

View File

@@ -1,12 +0,0 @@
const fs = require('fs');
const PARAMS_PATH = '/tmp/pipeline-parameters.json';
const content = JSON.parse(fs.readFileSync(PARAMS_PATH, 'utf-8'));
// Choose resource class for linux hosts
const currentBranch = process.env.CIRCLE_BRANCH || '';
content['large-linux-executor'] = /^pull\/[0-9-]+$/.test(currentBranch) ? '2xlarge' : 'electronjs/aks-linux-large';
content['medium-linux-executor'] = /^pull\/[0-9-]+$/.test(currentBranch) ? 'medium' : 'electronjs/aks-linux-medium';
fs.writeFileSync(PARAMS_PATH, JSON.stringify(content));

View File

@@ -2,6 +2,7 @@ name: Bug Report
description: Report an Electron bug
title: "[Bug]: "
labels: "bug :beetle:"
projects: ["electron/90"]
body:
- type: checkboxes
attributes:

View File

@@ -60,33 +60,106 @@ jobs:
done
- name: Generate GitHub App token
if: ${{ steps.check-major-version.outputs.MAJOR }}
uses: electron/github-app-auth-action@384fd19694fe7b6dcc9a684746c6976ad78228ae # v1.1.1
uses: electron/github-app-auth-action@cc6751b3b5e4edc5b9a4ad0a021ac455653b6dc8 # v1.0.0
id: generate-token
with:
creds: ${{ secrets.RELEASE_BOARD_GH_APP_CREDS }}
org: electron
- name: Generate Release Project Board Metadata
if: ${{ steps.check-major-version.outputs.MAJOR }}
uses: actions/github-script@d7906e4ad0b1822421a7e6a35d5ca353c962f410 # v6.4.1
id: generate-project-metadata
with:
script: |
const major = ${{ steps.check-major-version.outputs.MAJOR }}
core.setOutput("template-view", JSON.stringify({
major,
"next-major": major + 1,
"prev-major": major - 1,
}))
core.setOutput("title", `${major}-x-y`)
- name: Create Release Project Board
if: ${{ steps.check-major-version.outputs.MAJOR }}
uses: dsanders11/project-actions/copy-project@a24415515fa60a22f71f9d9d00e36ca82660cde9 # v1.0.1
with:
drafts: true
project-number: 64
# TODO - Set to public once GitHub fixes their GraphQL bug
# public: true
template-view: ${{ steps.generate-project-metadata.outputs.template-view }}
title: ${{ steps.generate-project-metadata.outputs.title}}
token: ${{ steps.generate-token.outputs.token }}
env:
GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
MAJOR: ${{ steps.check-major-version.outputs.MAJOR }}
ELECTRON_ORG_ID: "O_kgDOAMybxg"
ELECTRON_REPO_ID: "R_kgDOAI8xSw"
TEMPLATE_PROJECT_ID: "PVT_kwDOAMybxs4AQvib"
run: |
# Copy template to create new project board
PROJECT_ID=$(gh api graphql -f query='mutation ($ownerId: ID!, $projectId: ID!, $title: String!) {
copyProjectV2(input: {
includeDraftIssues: true,
ownerId: $ownerId,
projectId: $projectId,
title: $title
}) {
projectV2 {
id
}
}
}' -f ownerId=$ELECTRON_ORG_ID -f projectId=$TEMPLATE_PROJECT_ID -f title="${MAJOR}-x-y" | jq -r '.data.copyProjectV2.projectV2.id')
# Make the new project public
gh api graphql -f query='mutation ($projectId: ID!) {
updateProjectV2(input: {
projectId: $projectId,
public: true,
}) {
projectV2 {
id
}
}
}' -f projectId=$PROJECT_ID
# Link the new project to the Electron repository
gh api graphql -f query='mutation ($projectId: ID!, $repositoryId: ID!) {
linkProjectV2ToRepository(input: {
projectId: $projectId,
repositoryId: $repositoryId
}) {
clientMutationId
}
}' -f projectId=$PROJECT_ID -f repositoryId=$ELECTRON_REPO_ID
# Get all draft issues on the new project board
gh api graphql -f query='query ($id: ID!) {
node(id: $id) {
... on ProjectV2 {
items(first: 100) {
nodes {
... on ProjectV2Item {
id
content {
... on DraftIssue { id title
body
}
}
}
}
}
}
}
}' -f id=$PROJECT_ID > issues.json
PROJECT_ITEMS=$(jq '.data.node.items.nodes[] | select(.content.id != null) | .id' issues.json)
#
# Do template replacement for draft issues
#
echo "{\"major\": $MAJOR, \"next-major\": $((MAJOR + 1)), \"prev-major\": $((MAJOR - 1))}" > variables.json
# npx mustache is annoyingly slow, so install mustache directly
yarn add -D mustache
for PROJECT_ITEM_ID in $PROJECT_ITEMS; do
# These are done with the raw output flag and sent to file to better retain formatting
jq -r ".data.node.items.nodes[] | select(.id == $PROJECT_ITEM_ID) | .content.title" issues.json > title.txt
jq -r ".data.node.items.nodes[] | select(.id == $PROJECT_ITEM_ID) | .content.body" issues.json > body.txt
./node_modules/.bin/mustache variables.json title.txt new_title.txt
./node_modules/.bin/mustache variables.json body.txt new_body.txt
# Only update draft issues which had content change when interpolated
if ! cmp --silent -- new_title.txt title.txt || ! cmp --silent -- new_body.txt body.txt; then
DRAFT_ISSUE_ID=$(jq ".data.node.items.nodes[] | select(.id == $PROJECT_ITEM_ID) | .content.id" issues.json)
gh api graphql -f query='mutation ($draftIssueId: ID!, $title: String!, $body: String!) {
updateProjectV2DraftIssue(input: {
draftIssueId: $draftIssueId,
title: $title,
body: $body
}) {
draftIssue {
id
}
}
}' -f draftIssueId=$DRAFT_ISSUE_ID -f title="$(cat new_title.txt)" -f body="$(cat new_body.txt)"
fi
done

View File

@@ -10,7 +10,7 @@ permissions: {}
jobs:
issue-commented:
name: Remove blocked/need-repro on comment
if: ${{ contains(github.event.issue.labels.*.name, 'blocked/need-repro') && !contains(fromJSON('["MEMBER", "OWNER"]'), github.event.comment.author_association) && github.event.comment.user.type != 'Bot' }}
if: ${{ contains(github.event.issue.labels.*.name, 'blocked/need-repro') && !contains(fromJSON('["MEMBER", "OWNER"]'), github.event.comment.author_association) }}
runs-on: ubuntu-latest
steps:
- name: Generate GitHub App token

View File

@@ -20,12 +20,14 @@ jobs:
creds: ${{ secrets.ISSUE_TRIAGE_GH_APP_CREDS }}
org: electron
- name: Set status
uses: dsanders11/project-actions/edit-item@a24415515fa60a22f71f9d9d00e36ca82660cde9 # v1.0.1
uses: github/update-project-action@2d475e08804f11f4022df7e21f5816531e97cb64 # v2
with:
token: ${{ steps.generate-token.outputs.token }}
project-number: 90
github_token: ${{ steps.generate-token.outputs.token }}
organization: electron
project_number: 90
content_id: ${{ github.event.issue.node_id }}
field: Status
field-value: 🛑 Blocked
value: 🛑 Blocked
issue-labeled-blocked-need-repro:
name: blocked/need-repro label added
if: github.event.label.name == 'blocked/need-repro'
@@ -40,7 +42,7 @@ jobs:
GH_REPO: electron/electron
run: |
set -eo pipefail
COMMENT_COUNT=$(gh issue view ${{ github.event.issue.number }} --comments --json comments | jq '[ .comments[] | select(.author.login == "electron-issue-triage" or .authorAssociation == "OWNER" or .authorAssociation == "MEMBER") | select(.body | startswith("<!-- blocked/need-repro -->")) ] | length')
COMMENT_COUNT=$(gh issue view ${{ github.event.issue.number }} --comments --json comments | jq '[ .comments[] | select(.author.login == "github-actions" or .authorAssociation == "OWNER" or .authorAssociation == "MEMBER") | select(.body | startswith("<!-- blocked/need-repro -->")) ] | length')
if [[ $COMMENT_COUNT -eq 0 ]]; then
echo "SHOULD_COMMENT=1" >> "$GITHUB_OUTPUT"
fi

View File

@@ -1,27 +0,0 @@
name: Issue Opened
on:
issues:
types:
- opened
permissions: {}
jobs:
add-to-issue-triage:
if: ${{ contains(github.event.issue.labels.*.name, 'bug :beetle:') }}
runs-on: ubuntu-latest
steps:
- name: Generate GitHub App token
uses: electron/github-app-auth-action@384fd19694fe7b6dcc9a684746c6976ad78228ae # v1.1.1
id: generate-token
with:
creds: ${{ secrets.ISSUE_TRIAGE_GH_APP_CREDS }}
org: electron
- name: Add to Issue Triage
uses: dsanders11/project-actions/add-item@a24415515fa60a22f71f9d9d00e36ca82660cde9 # v1.0.1
with:
field: Reporter
field-value: ${{ github.event.issue.user.login }}
project-number: 90
token: ${{ steps.generate-token.outputs.token }}

View File

@@ -10,7 +10,7 @@ permissions:
jobs:
issue-unlabeled-blocked:
name: All blocked/* labels removed
if: startsWith(github.event.label.name, 'blocked/') && github.event.issue.state == 'open'
if: startsWith(github.event.label.name, 'blocked/')
runs-on: ubuntu-latest
steps:
- name: Check for any blocked labels
@@ -30,9 +30,11 @@ jobs:
org: electron
- name: Set status
if: ${{ steps.check-for-blocked-labels.outputs.NOT_BLOCKED }}
uses: dsanders11/project-actions/edit-item@a24415515fa60a22f71f9d9d00e36ca82660cde9 # v1.0.1
uses: github/update-project-action@2d475e08804f11f4022df7e21f5816531e97cb64 # v2
with:
token: ${{ steps.generate-token.outputs.token }}
project-number: 90
github_token: ${{ steps.generate-token.outputs.token }}
organization: electron
project_number: 90
content_id: ${{ github.event.issue.node_id }}
field: Status
field-value: 📥 Was Blocked
value: 📥 Was Blocked

View File

@@ -20,9 +20,11 @@ jobs:
creds: ${{ secrets.RELEASE_BOARD_GH_APP_CREDS }}
org: electron
- name: Set status
uses: dsanders11/project-actions/edit-item@a24415515fa60a22f71f9d9d00e36ca82660cde9 # v1.0.1
uses: dsanders11/update-project-action@7ade91760df70df76770a238abee7a4869e01cf8
with:
token: ${{ steps.generate-token.outputs.token }}
project-number: 94
github_token: ${{ steps.generate-token.outputs.token }}
organization: electron
project_number: 94
content_id: ${{ github.event.pull_request.node_id }}
field: Status
field-value: ✅ Reviewed
value: ✅ Reviewed

View File

@@ -1,35 +0,0 @@
name: Check Stable Prep Items
on:
schedule:
- cron: '0 */12 * * *'
workflow_dispatch:
permissions: {}
jobs:
check-stable-prep-items:
name: Check Stable Prep Items
runs-on: ubuntu-latest
steps:
- name: Generate GitHub App token
uses: electron/github-app-auth-action@384fd19694fe7b6dcc9a684746c6976ad78228ae # v1.1.1
id: generate-token
with:
creds: ${{ secrets.RELEASE_BOARD_GH_APP_CREDS }}
org: electron
- name: Find Newest Release Project Board
id: find-project-number
env:
GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
run: |
set -eo pipefail
PROJECT_NUMBER=$(gh project list --owner electron --format json | jq -r '.projects | map(select(.title | test("^[0-9]+-x-y$"))) | max_by(.number) | .number')
echo "PROJECT_NUMBER=$PROJECT_NUMBER" >> "$GITHUB_OUTPUT"
- name: Update Completed Stable Prep Items
uses: dsanders11/project-actions/completed-by@a24415515fa60a22f71f9d9d00e36ca82660cde9 # v1.0.1
with:
field: Prep Status
field-value: ✅ Complete
project-number: ${{ steps.find-project-number.outputs.PROJECT_NUMBER }}
token: ${{ steps.generate-token.outputs.token }}

View File

@@ -104,26 +104,14 @@ branding = read_file("shell/app/BRANDING.json", "json")
electron_project_name = branding.project_name
electron_product_name = branding.product_name
electron_mac_bundle_id = branding.mac_bundle_id
if (override_electron_version != "") {
electron_version = override_electron_version
} else {
# When building from source code tarball there is no git tag available and
# builders must explicitly pass override_electron_version in gn args.
# This read_file call will assert if there is no git information, without it
# gn will generate a malformed build configuration and ninja will get into
# infinite loop.
read_file(".git/packed-refs", "string")
# Set electron version from git tag.
electron_version = exec_script("script/get-git-version.py",
[],
"trim string",
[
".git/packed-refs",
".git/HEAD",
])
}
electron_version = exec_script("script/print-version.py",
[],
"trim string",
[
".git/packed-refs",
".git/HEAD",
"script/lib/get-version.js",
])
if (is_mas_build) {
assert(is_mac,
@@ -434,7 +422,6 @@ source_set("electron_lib") {
"//chrome/app/resources:platform_locale_settings",
"//components/autofill/core/common:features",
"//components/certificate_transparency",
"//components/compose:buildflags",
"//components/embedder_support:browser_util",
"//components/language/core/browser",
"//components/net_log",
@@ -443,8 +430,6 @@ source_set("electron_lib") {
"//components/network_hints/renderer",
"//components/network_session_configurator/common",
"//components/omnibox/browser:buildflags",
"//components/os_crypt/async/browser",
"//components/os_crypt/async/browser:key_provider_interface",
"//components/os_crypt/sync",
"//components/pref_registry",
"//components/prefs",
@@ -919,7 +904,10 @@ if (is_mac) {
assert(defined(invoker.helper_name_suffix))
output_name = electron_helper_name + invoker.helper_name_suffix
deps = [ ":electron_framework+link" ]
deps = [
":electron_framework+link",
"//base/allocator:early_zone_registration_apple",
]
if (!is_mas_build) {
deps += [ "//sandbox/mac:seatbelt" ]
}
@@ -1080,6 +1068,7 @@ if (is_mac) {
":electron_app_plist",
":electron_app_resources",
":electron_fuses",
"//base/allocator:early_zone_registration_apple",
"//electron/buildflags",
]
if (is_mas_build) {

6
DEPS
View File

@@ -2,11 +2,11 @@ gclient_gn_args_from = 'src'
vars = {
'chromium_version':
'120.0.6099.109',
'118.0.5991.0',
'node_version':
'v18.18.2',
'v18.17.1',
'nan_version':
'e14bdcd1f72d62bca1d541b66da43130384ec213',
'16fa32231e2ccd89d2804b3f765319128b20c4ac',
'squirrel.mac_version':
'0e5d146ba13101a1302d59ea6e6e0b3cace4ae38',
'reactiveobjc_version':

View File

@@ -6,7 +6,7 @@
version: 1.0.{build}
build_cloud: electronhq-16-core
image: base-bake-image
image: e-112.0.5607.0-vs2022
environment:
GIT_CACHE_PATH: C:\Users\appveyor\libcc_cache
ELECTRON_OUT_DIR: Default

View File

@@ -29,7 +29,7 @@
version: 1.0.{build}
build_cloud: electronhq-16-core
image: e-120.0.6099.0
image: e-118.0.5949.0
environment:
GIT_CACHE_PATH: C:\Users\appveyor\libcc_cache
ELECTRON_OUT_DIR: Default
@@ -160,7 +160,7 @@ for:
- gn desc out/Default v8:run_mksnapshot_default args > out/Default/default_mksnapshot_args
# Remove unused args from mksnapshot_args
- ps: >-
Get-Content out/Default/default_mksnapshot_args | Where-Object { -not $_.Contains('--turbo-profiling-input') -And -not $_.Contains('builtins-pgo') -And -not $_.Contains('The gn arg use_goma=true') } | Set-Content out/Default/mksnapshot_args
Get-Content out/Default/default_mksnapshot_args | Where-Object { -not $_.Contains('--turbo-profiling-input') -And -not $_.Contains('builtins-pgo') } | Set-Content out/Default/mksnapshot_args
- ninja -C out/Default electron:electron_mksnapshot_zip
- cd out\Default
- 7z a mksnapshot.zip mksnapshot_args gen\v8\embedded.S

View File

@@ -29,7 +29,7 @@
version: 1.0.{build}
build_cloud: electronhq-16-core
image: e-120.0.6099.0
image: e-118.0.5949.0
environment:
GIT_CACHE_PATH: C:\Users\appveyor\libcc_cache
ELECTRON_OUT_DIR: Default
@@ -158,7 +158,7 @@ for:
- gn desc out/Default v8:run_mksnapshot_default args > out/Default/default_mksnapshot_args
# Remove unused args from mksnapshot_args
- ps: >-
Get-Content out/Default/default_mksnapshot_args | Where-Object { -not $_.Contains('--turbo-profiling-input') -And -not $_.Contains('builtins-pgo') -And -not $_.Contains('The gn arg use_goma=true') } | Set-Content out/Default/mksnapshot_args
Get-Content out/Default/default_mksnapshot_args | Where-Object { -not $_.Contains('--turbo-profiling-input') -And -not $_.Contains('builtins-pgo') } | Set-Content out/Default/mksnapshot_args
- ninja -C out/Default electron:electron_mksnapshot_zip
- cd out\Default
- 7z a mksnapshot.zip mksnapshot_args gen\v8\embedded.S

View File

@@ -2,7 +2,7 @@ is_electron_build = true
root_extra_deps = [ "//electron" ]
# Registry of NMVs --> https://github.com/nodejs/node/blob/main/doc/abi_version_registry.json
node_module_version = 119
node_module_version = 118
v8_promise_internal_field_count = 1
v8_embedder_string = "-electron.0"

View File

@@ -18,9 +18,4 @@ declare_args() {
# Enable Spellchecker support
enable_builtin_spellchecker = true
# The version of Electron.
# Packagers and vendor builders should set this in gn args to avoid running
# the script that reads git tag.
override_electron_version = ""
}

View File

@@ -55,8 +55,6 @@ static_library("chrome") {
"//chrome/browser/net/proxy_config_monitor.h",
"//chrome/browser/net/proxy_service_factory.cc",
"//chrome/browser/net/proxy_service_factory.h",
"//chrome/browser/picture_in_picture/picture_in_picture_bounds_cache.cc",
"//chrome/browser/picture_in_picture/picture_in_picture_bounds_cache.h",
"//chrome/browser/picture_in_picture/picture_in_picture_window_manager.cc",
"//chrome/browser/picture_in_picture/picture_in_picture_window_manager.h",
"//chrome/browser/platform_util.cc",
@@ -100,6 +98,8 @@ static_library("chrome") {
"//chrome/browser/ui/ui_features.h",
"//chrome/browser/ui/views/eye_dropper/eye_dropper.cc",
"//chrome/browser/ui/views/eye_dropper/eye_dropper.h",
"//chrome/browser/ui/views/eye_dropper/eye_dropper_view.cc",
"//chrome/browser/ui/views/eye_dropper/eye_dropper_view.h",
"//chrome/browser/ui/views/overlay/back_to_tab_label_button.cc",
"//chrome/browser/ui/views/overlay/close_image_button.cc",
"//chrome/browser/ui/views/overlay/close_image_button.h",
@@ -154,6 +154,15 @@ static_library("chrome") {
sources += [ "//chrome/browser/media/webrtc/window_icon_util_ozone.cc" ]
}
if (use_aura) {
sources += [
"//chrome/browser/platform_util_aura.cc",
"//chrome/browser/ui/views/eye_dropper/eye_dropper_view_aura.cc",
"//ui/views/native_window_tracker_aura.cc",
"//ui/views/native_window_tracker_aura.h",
]
}
public_deps = [
"//chrome/browser:dev_ui_browser_resources",
"//chrome/browser/resources/accessibility:resources",
@@ -178,16 +187,6 @@ static_library("chrome") {
"//ui/views/controls/webview",
]
if (use_aura) {
sources += [
"//chrome/browser/platform_util_aura.cc",
"//chrome/browser/ui/views/eye_dropper/eye_dropper_aura.cc",
"//ui/views/native_window_tracker_aura.cc",
"//ui/views/native_window_tracker_aura.h",
]
deps += [ "//components/eye_dropper" ]
}
if (is_linux) {
sources += [ "//chrome/browser/icon_loader_auralinux.cc" ]
if (use_ozone) {
@@ -203,10 +202,6 @@ static_library("chrome") {
"//chrome/browser/ui/views/status_icons/status_icon_linux_dbus.cc",
"//chrome/browser/ui/views/status_icons/status_icon_linux_dbus.h",
]
sources += [
"//chrome/browser/ui/views/dark_mode_manager_linux.cc",
"//chrome/browser/ui/views/dark_mode_manager_linux.h",
]
public_deps += [
"//components/dbus/menu",
"//components/dbus/thread_linux",
@@ -218,11 +213,7 @@ static_library("chrome") {
"//chrome/browser/win/icon_reader_service.cc",
"//chrome/browser/win/icon_reader_service.h",
]
public_deps += [
"//chrome/browser/web_applications/proto",
"//chrome/services/util_win:lib",
"//components/webapps/common:mojo_bindings",
]
public_deps += [ "//chrome/services/util_win:lib" ]
}
if (is_mac) {
@@ -256,8 +247,6 @@ static_library("chrome") {
sources += [
"//chrome/browser/bad_message.cc",
"//chrome/browser/bad_message.h",
"//chrome/browser/printing/prefs_util.cc",
"//chrome/browser/printing/prefs_util.h",
"//chrome/browser/printing/print_job.cc",
"//chrome/browser/printing/print_job.h",
"//chrome/browser/printing/print_job_manager.cc",
@@ -343,34 +332,6 @@ static_library("chrome") {
"//components/pdf/renderer",
]
}
} else {
# These are required by the webRequest module.
sources += [
"//extensions/browser/api/declarative_net_request/request_action.cc",
"//extensions/browser/api/declarative_net_request/request_action.h",
"//extensions/browser/api/web_request/form_data_parser.cc",
"//extensions/browser/api/web_request/form_data_parser.h",
"//extensions/browser/api/web_request/upload_data_presenter.cc",
"//extensions/browser/api/web_request/upload_data_presenter.h",
"//extensions/browser/api/web_request/web_request_api_constants.cc",
"//extensions/browser/api/web_request/web_request_api_constants.h",
"//extensions/browser/api/web_request/web_request_info.cc",
"//extensions/browser/api/web_request/web_request_info.h",
"//extensions/browser/api/web_request/web_request_resource_type.cc",
"//extensions/browser/api/web_request/web_request_resource_type.h",
"//extensions/browser/extension_api_frame_id_map.cc",
"//extensions/browser/extension_api_frame_id_map.h",
"//extensions/browser/extension_navigation_ui_data.cc",
"//extensions/browser/extension_navigation_ui_data.h",
"//extensions/browser/extensions_browser_client.cc",
"//extensions/browser/extensions_browser_client.h",
"//extensions/browser/guest_view/web_view/web_view_renderer_state.cc",
"//extensions/browser/guest_view/web_view/web_view_renderer_state.h",
]
public_deps += [
"//extensions/browser/api/declarative_net_request/flat:extension_ruleset",
]
}
if (!is_mas_build) {

View File

@@ -15,7 +15,7 @@ Shortcuts are registered with the [`globalShortcut`](global-shortcut.md) module
using the [`register`](global-shortcut.md#globalshortcutregisteraccelerator-callback)
method, i.e.
```js
```javascript
const { app, globalShortcut } = require('electron')
app.whenReady().then(() => {

View File

@@ -1134,11 +1134,11 @@ indicates success while any other value indicates failure according to Chromium
resolver will attempt to use the system's DNS settings to do DNS lookups
itself. Enabled by default on macOS, disabled by default on Windows and
Linux.
* `secureDnsMode` string (optional) - Can be 'off', 'automatic' or 'secure'.
Configures the DNS-over-HTTP mode. When 'off', no DoH lookups will be
performed. When 'automatic', DoH lookups will be performed first if DoH is
* `secureDnsMode` string (optional) - Can be "off", "automatic" or "secure".
Configures the DNS-over-HTTP mode. When "off", no DoH lookups will be
performed. When "automatic", DoH lookups will be performed first if DoH is
available, and insecure DNS lookups will be performed as a fallback. When
'secure', only DoH lookups will be performed. Defaults to 'automatic'.
"secure", only DoH lookups will be performed. Defaults to "automatic".
* `secureDnsServers` string[]&#32;(optional) - A list of DNS-over-HTTP
server templates. See [RFC8484 § 3][] for details on the template format.
Most servers support the POST method; the template for such servers is
@@ -1542,7 +1542,7 @@ A `boolean` property that returns `true` if the app is packaged, `false` otherw
[tasks]:https://learn.microsoft.com/en-us/windows/win32/shell/taskbar-extensions#tasks
[app-user-model-id]: https://learn.microsoft.com/en-us/windows/win32/shell/appids
[electron-forge]: https://www.electronforge.io/
[electron-packager]: https://github.com/electron/packager
[electron-packager]: https://github.com/electron/electron-packager
[CFBundleURLTypes]: https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/TP40009249-102207-TPXREF115
[LSCopyDefaultHandlerForURLScheme]: https://developer.apple.com/documentation/coreservices/1441725-lscopydefaulthandlerforurlscheme?language=objc
[handoff]: https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/Handoff/HandoffFundamentals/HandoffFundamentals.html
@@ -1571,6 +1571,19 @@ This is the user agent that will be used when no user agent is set at the
app has the same user agent. Set to a custom value as early as possible
in your app's initialization to ensure that your overridden value is used.
### `app.runningUnderRosettaTranslation` _macOS_ _Readonly_ _Deprecated_
A `boolean` which when `true` indicates that the app is currently running
under the [Rosetta Translator Environment](https://en.wikipedia.org/wiki/Rosetta_(software)).
You can use this property to prompt users to download the arm64 version of
your application when they are running the x64 version under Rosetta
incorrectly.
**Deprecated:** This property is superceded by the `runningUnderARM64Translation`
property which detects when the app is being translated to ARM64 in both macOS
and Windows.
### `app.runningUnderARM64Translation` _Readonly_ _macOS_ _Windows_
A `boolean` which when `true` indicates that the app is currently running under

View File

@@ -16,7 +16,7 @@ module is emitted.
### Example
```js
```javascript
// In the main process.
const { app, BrowserView, BrowserWindow } = require('electron')

View File

@@ -7,7 +7,7 @@ Process: [Main](../glossary.md#main-process)
This module cannot be used until the `ready` event of the `app`
module is emitted.
```js
```javascript
// In the main process.
const { BrowserWindow } = require('electron')
@@ -38,7 +38,7 @@ While loading the page, the `ready-to-show` event will be emitted when the rende
process has rendered the page for the first time if the window has not been shown yet. Showing
the window after this event will have no visual flash:
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ show: false })
win.once('ready-to-show', () => {
@@ -59,7 +59,7 @@ For a complex app, the `ready-to-show` event could be emitted too late, making
the app feel slow. In this case, it is recommended to show the window
immediately, and use a `backgroundColor` close to your app's background:
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ backgroundColor: '#2e2c29' })
@@ -85,7 +85,7 @@ For more information about these color types see valid options in [win.setBackgr
By using `parent` option, you can create child windows:
```js
```javascript
const { BrowserWindow } = require('electron')
const top = new BrowserWindow()
@@ -101,7 +101,7 @@ The `child` window will always show on top of the `top` window.
A modal window is a child window that disables parent window, to create a modal
window, you have to set both `parent` and `modal` options:
```js
```javascript
const { BrowserWindow } = require('electron')
const top = new BrowserWindow()
@@ -188,7 +188,7 @@ window should be closed, which will also be called when the window is
reloaded. In Electron, returning any value other than `undefined` would cancel the
close. For example:
```js
```javascript
window.onbeforeunload = (e) => {
console.log('I do not want to be closed')
@@ -351,7 +351,7 @@ Commands are lowercased, underscores are replaced with hyphens, and the
`APPCOMMAND_` prefix is stripped off.
e.g. `APPCOMMAND_BROWSER_BACKWARD` is emitted as `browser-backward`.
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.on('app-command', (e, cmd) => {
@@ -367,6 +367,36 @@ The following app commands are explicitly supported on Linux:
* `browser-backward`
* `browser-forward`
#### Event: 'scroll-touch-begin' _macOS_ _Deprecated_
Emitted when scroll wheel event phase has begun.
> **Note**
> This event is deprecated beginning in Electron 22.0.0. See [Breaking
> Changes](../breaking-changes.md#deprecated-browserwindow-scroll-touch--events)
> for details of how to migrate to using the [WebContents
> `input-event`](./web-contents.md#event-input-event) event.
#### Event: 'scroll-touch-end' _macOS_ _Deprecated_
Emitted when scroll wheel event phase has ended.
> **Note**
> This event is deprecated beginning in Electron 22.0.0. See [Breaking
> Changes](../breaking-changes.md#deprecated-browserwindow-scroll-touch--events)
> for details of how to migrate to using the [WebContents
> `input-event`](./web-contents.md#event-input-event) event.
#### Event: 'scroll-touch-edge' _macOS_ _Deprecated_
Emitted when scroll wheel event phase filed upon reaching the edge of element.
> **Note**
> This event is deprecated beginning in Electron 22.0.0. See [Breaking
> Changes](../breaking-changes.md#deprecated-browserwindow-scroll-touch--events)
> for details of how to migrate to using the [WebContents
> `input-event`](./web-contents.md#event-input-event) event.
#### Event: 'swipe' _macOS_
Returns:
@@ -456,7 +486,7 @@ Returns `BrowserWindow | null` - The window with the given `id`.
Objects created with `new BrowserWindow` have the following properties:
```js
```javascript
const { BrowserWindow } = require('electron')
// In this example `win` is our instance
const win = new BrowserWindow({ width: 800, height: 600 })
@@ -475,10 +505,6 @@ events.
A `Integer` property representing the unique ID of the window. Each ID is unique among all `BrowserWindow` instances of the entire Electron application.
#### `win.tabbingIdentifier` _macOS_ _Readonly_
A `string` (optional) property that is equal to the `tabbingIdentifier` passed to the `BrowserWindow` constructor or `undefined` if none was set.
#### `win.autoHideMenuBar`
A `boolean` property that determines whether the window menu bar should hide itself automatically. Once set, the menu bar will only show when users press the single `Alt` key.
@@ -780,7 +806,7 @@ Closes the currently open [Quick Look][quick-look] panel.
Resizes and moves the window to the supplied bounds. Any properties that are not supplied will default to their current values.
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
@@ -1035,7 +1061,7 @@ Changes the attachment point for sheets on macOS. By default, sheets are
attached just below the window frame, but you may want to display them beneath
a HTML-rendered toolbar. For example:
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
@@ -1178,7 +1204,7 @@ To ensure that file URLs are properly formatted, it is recommended to use
Node's [`url.format`](https://nodejs.org/api/url.html#url_url_format_urlobject)
method:
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
@@ -1194,7 +1220,7 @@ win.loadURL(url)
You can load a URL using a `POST` request with URL-encoded data by doing
the following:
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
@@ -1621,7 +1647,7 @@ removed in future Electron releases.
* `options` Object
* `color` String (optional) _Windows_ - The CSS color of the Window Controls Overlay when enabled.
* `symbolColor` String (optional) _Windows_ - The CSS color of the symbols on the Window Controls Overlay when enabled.
* `height` Integer (optional) _macOS_ _Windows_ - The height of the title bar and Window Controls Overlay in pixels.
* `height` Integer (optional) _Windows_ - The height of the title bar and Window Controls Overlay in pixels.
On a Window with Window Controls Overlay already enabled, this method updates
the style of the title bar overlay.

View File

@@ -65,7 +65,7 @@ strictly follow the Node.js model as described in the
For instance, we could have created the same request to 'github.com' as follows:
```js
```javascript
const request = net.request({
method: 'GET',
protocol: 'https:',
@@ -104,7 +104,7 @@ The `callback` function is expected to be called back with user credentials:
* `username` string
* `password` string
```js @ts-type={request:Electron.ClientRequest}
```javascript @ts-type={request:Electron.ClientRequest}
request.on('login', (authInfo, callback) => {
callback('username', 'password')
})
@@ -113,7 +113,7 @@ request.on('login', (authInfo, callback) => {
Providing empty credentials will cancel the request and report an authentication
error on the response object:
```js @ts-type={request:Electron.ClientRequest}
```javascript @ts-type={request:Electron.ClientRequest}
request.on('response', (response) => {
console.log(`STATUS: ${response.statusCode}`)
response.on('error', (error) => {

View File

@@ -7,7 +7,7 @@ Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer
On Linux, there is also a `selection` clipboard. To manipulate it
you need to pass `selection` to each method:
```js
```javascript
const { clipboard } = require('electron')
clipboard.writeText('Example string', 'selection')

View File

@@ -6,7 +6,7 @@ You can use [app.commandLine.appendSwitch][append-switch] to append them in
your app's main script before the [ready][ready] event of the [app][app] module
is emitted:
```js
```javascript
const { app } = require('electron')
app.commandLine.appendSwitch('remote-debugging-port', '8315')
app.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')
@@ -185,7 +185,7 @@ list of hosts. This flag has an effect only if used in tandem with
For example:
```js
```javascript
const { app } = require('electron')
app.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')
```

View File

@@ -7,7 +7,7 @@ _This class is not exported from the `'electron'` module. It is only available a
The following example shows how to check if the `--disable-gpu` flag is set.
```js
```javascript
const { app } = require('electron')
app.commandLine.hasSwitch('disable-gpu')
```

View File

@@ -10,7 +10,7 @@ This module does not include a web interface. To view recorded traces, use
**Note:** You should not use this module until the `ready` event of the app
module is emitted.
```js
```javascript
const { app, contentTracing } = require('electron')
app.whenReady().then(() => {

View File

@@ -6,7 +6,7 @@ Process: [Renderer](../glossary.md#renderer-process)
An example of exposing an API to a renderer from an isolated preload script is given below:
```js
```javascript
// Preload (Isolated World)
const { contextBridge, ipcRenderer } = require('electron')
@@ -18,7 +18,7 @@ contextBridge.exposeInMainWorld(
)
```
```js @ts-nocheck
```javascript @ts-nocheck
// Renderer (Main World)
window.electron.doThing()
@@ -64,7 +64,7 @@ the API become immutable and updates on either side of the bridge do not result
An example of a complex API is shown below:
```js
```javascript
const { contextBridge, ipcRenderer } = require('electron')
contextBridge.exposeInMainWorld(
@@ -92,7 +92,7 @@ contextBridge.exposeInMainWorld(
An example of `exposeInIsolatedWorld` is shown below:
```js
```javascript
const { contextBridge, ipcRenderer } = require('electron')
contextBridge.exposeInIsolatedWorld(
@@ -104,7 +104,7 @@ contextBridge.exposeInIsolatedWorld(
)
```
```js @ts-nocheck
```javascript @ts-nocheck
// Renderer (In isolated world id1004)
window.electron.doThing()
@@ -145,7 +145,7 @@ The table of supported types described above also applies to Node APIs that you
Please note that many Node APIs grant access to local system resources.
Be very cautious about which globals and APIs you expose to untrusted remote content.
```js
```javascript
const { contextBridge } = require('electron')
const crypto = require('node:crypto')
contextBridge.exposeInMainWorld('nodeCrypto', {

View File

@@ -10,7 +10,7 @@ a `Session`.
For example:
```js
```javascript
const { session } = require('electron')
// Query all cookies.
@@ -119,8 +119,4 @@ Removes the cookies matching `url` and `name`
Returns `Promise<void>` - A promise which resolves when the cookie store has been flushed
Writes any unwritten cookies data to disk
Cookies written by any method will not be written to disk immediately, but will be written every 30 seconds or 512 operations
Calling this method can cause the cookie to be written to disk immediately.
Writes any unwritten cookies data to disk.

View File

@@ -7,7 +7,7 @@ Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer
The following is an example of setting up Electron to automatically submit
crash reports to a remote server:
```js
```javascript
const { crashReporter } = require('electron')
crashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })

View File

@@ -8,7 +8,7 @@ _This class is not exported from the `'electron'` module. It is only available a
Chrome Developer Tools has a [special binding][rdp] available at JavaScript
runtime that allows interacting with pages and instrumenting them.
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

View File

@@ -8,7 +8,7 @@ Process: [Main](../glossary.md#main-process)
The following example shows how to capture video from a desktop window whose
title is `Electron`:
```js
```javascript
// In the main process.
const { BrowserWindow, desktopCapturer } = require('electron')
@@ -24,7 +24,7 @@ desktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources =
})
```
```js @ts-nocheck
```javascript @ts-nocheck
// In the preload script.
const { ipcRenderer } = require('electron')
@@ -68,7 +68,7 @@ To capture both audio and video from the entire desktop the constraints passed
to [`navigator.mediaDevices.getUserMedia`][] must include `chromeMediaSource: 'desktop'`,
for both `audio` and `video`, but should not include a `chromeMediaSourceId` constraint.
```js
```javascript
const constraints = {
audio: {
mandatory: {

View File

@@ -6,7 +6,7 @@ Process: [Main](../glossary.md#main-process)
An example of showing a dialog to select multiple files:
```js
```javascript
const { dialog } = require('electron')
console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))
```
@@ -52,7 +52,7 @@ The `browserWindow` argument allows the dialog to attach itself to a parent wind
The `filters` specifies an array of file types that can be displayed or
selected when you want to limit the user to a specific type. For example:
```js
```javascript
{
filters: [
{ name: 'Images', extensions: ['jpg', 'png', 'gif'] },
@@ -119,7 +119,7 @@ The `browserWindow` argument allows the dialog to attach itself to a parent wind
The `filters` specifies an array of file types that can be displayed or
selected when you want to limit the user to a specific type. For example:
```js
```javascript
{
filters: [
{ name: 'Images', extensions: ['jpg', 'png', 'gif'] },

View File

@@ -7,7 +7,7 @@ _This class is not exported from the `'electron'` module. It is only available a
The following example shows how to bounce your icon on the dock.
```js
```javascript
const { app } = require('electron')
app.dock.bounce()
```

View File

@@ -9,7 +9,7 @@ _This class is not exported from the `'electron'` module. It is only available a
It is used in `will-download` event of `Session` class, and allows users to
control the download item.
```js
```javascript
// In the main process.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

View File

@@ -59,7 +59,7 @@ geolocation webservice. To enable this feature, acquire a
and place the following code in your main process file, before opening any
browser windows that will make geolocation requests:
```js
```javascript
process.env.GOOGLE_API_KEY = 'YOUR_KEY_HERE'
```
@@ -111,16 +111,6 @@ Options:
* `kioclient5`
* `kioclient`
### `ELECTRON_OZONE_PLATFORM_HINT` _Linux_
Selects the preferred platform backend used on Linux. The default one is `x11`. `auto` selects Wayland if possible, X11 otherwise.
Options:
* `auto`
* `wayland`
* `x11`
## Development Variables
The following environment variables are intended primarily for development and

View File

@@ -12,7 +12,7 @@ shortcuts.
not have the keyboard focus. This module cannot be used before the `ready`
event of the app module is emitted.
```js
```javascript
const { app, globalShortcut } = require('electron')
app.whenReady().then(() => {

View File

@@ -89,7 +89,7 @@ tuples. So, the even-numbered offsets are key values, and the odd-numbered
offsets are the associated values. Header names are not lowercased, and
duplicates are not merged.
```js @ts-type={response:Electron.IncomingMessage}
```javascript @ts-type={response:Electron.IncomingMessage}
// Prints something like:
//
// [ 'user-agent',

View File

@@ -32,15 +32,6 @@ The `ipcRenderer` module has the following method to listen for events and send
Listens to `channel`, when a new message arrives `listener` would be called with
`listener(event, args...)`.
### `ipcRenderer.off(channel, listener)`
* `channel` string
* `listener` Function
* `event` [IpcRendererEvent][ipc-renderer-event]
* `...args` any[]
Alias for [`ipcRenderer.removeListener`](#ipcrendererremovelistenerchannel-listener).
### `ipcRenderer.once(channel, listener)`
* `channel` string
@@ -51,20 +42,10 @@ Alias for [`ipcRenderer.removeListener`](#ipcrendererremovelistenerchannel-liste
Adds a one time `listener` function for the event. This `listener` is invoked
only the next time a message is sent to `channel`, after which it is removed.
### `ipcRenderer.addListener(channel, listener)`
* `channel` string
* `listener` Function
* `event` [IpcRendererEvent][ipc-renderer-event]
* `...args` any[]
Alias for [`ipcRenderer.on`](#ipcrendereronchannel-listener).
### `ipcRenderer.removeListener(channel, listener)`
* `channel` string
* `listener` Function
* `event` [IpcRendererEvent][ipc-renderer-event]
* `...args` any[]
Removes the specified `listener` from the listener array for the specified
@@ -120,7 +101,7 @@ The main process should listen for `channel` with
For example:
```js @ts-type={someArgument:unknown} @ts-type={doSomeWork:(arg:unknown)=>Promise<unknown>}
```javascript @ts-type={someArgument:unknown} @ts-type={doSomeWork:(arg:unknown)=>Promise<unknown>}
// Renderer process
ipcRenderer.invoke('some-name', someArgument).then((result) => {
// ...

View File

@@ -151,7 +151,7 @@ can have a submenu.
An example of creating the application menu with the simple template API:
```js @ts-expect-error=[107]
```javascript @ts-expect-error=[107]
const { app, Menu } = require('electron')
const isMac = process.platform === 'darwin'
@@ -353,7 +353,7 @@ By default, items will be inserted in the order they exist in the template unles
Template:
```js
```javascript
[
{ id: '1', label: 'one' },
{ id: '2', label: 'two' },
@@ -373,7 +373,7 @@ Menu:
Template:
```js
```javascript
[
{ id: '1', label: 'one' },
{ type: 'separator' },
@@ -397,7 +397,7 @@ Menu:
Template:
```js
```javascript
[
{ id: '1', label: 'one', after: ['3'] },
{ id: '2', label: 'two', before: ['1'] },

View File

@@ -10,7 +10,7 @@ In Electron, for the APIs that take images, you can pass either file paths or
For example, when creating a tray or setting a window's icon, you can pass an
image file path as a `string`:
```js
```javascript
const { BrowserWindow, Tray } = require('electron')
const appIcon = new Tray('/Users/somebody/images/icon.png')
@@ -20,7 +20,7 @@ console.log(appIcon, win)
Or read the image from the clipboard, which returns a `NativeImage`:
```js
```javascript
const { clipboard, Tray } = require('electron')
const image = clipboard.readImage()
const appIcon = new Tray(image)
@@ -71,7 +71,7 @@ images/
└── icon@3x.png
```
```js
```javascript
const { Tray } = require('electron')
const appIcon = new Tray('/Users/somebody/images/icon.png')
console.log(appIcon)
@@ -138,7 +138,7 @@ Creates a new `NativeImage` instance from a file located at `path`. This method
returns an empty image if the `path` does not exist, cannot be read, or is not
a valid image.
```js
```javascript
const nativeImage = require('electron').nativeImage
const image = nativeImage.createFromPath('/Users/somebody/images/icon.png')

View File

@@ -4,7 +4,7 @@
Process: [Main](../glossary.md#main-process)
```js
```javascript
const { app, netLog } = require('electron')
app.whenReady().then(async () => {

View File

@@ -26,7 +26,7 @@ Node.js.
Example usage:
```js
```javascript
const { app } = require('electron')
app.whenReady().then(() => {
const { net } = require('electron')

View File

@@ -85,8 +85,6 @@ Emitted when the notification is closed by manual intervention from the user.
This event is not guaranteed to be emitted in all cases where the notification
is closed.
On Windows, the `close` event can be emitted in one of three ways: programmatic dismissal with `notification.close()`, by the user closing the notification, or via system timeout. If a notification is in the Action Center after the initial `close` event is emitted, a call to `notification.close()` will remove the notification from the action center but the `close` event will not be emitted again.
#### Event: 'reply' _macOS_
Returns:
@@ -129,8 +127,6 @@ shown notification and create a new one with identical properties.
Dismisses the notification.
On Windows, calling `notification.close()` while the notification is visible on screen will dismiss the notification and remove it from the Action Center. If `notification.close()` is called after the notification is no longer visible on screen, calling `notification.close()` will try remove it from the Action Center.
### Instance Properties
#### `notification.title`

View File

@@ -6,7 +6,7 @@ Process: [Main](../glossary.md#main-process)
For example:
```js
```javascript
const { powerSaveBlocker } = require('electron')
const id = powerSaveBlocker.start('prevent-display-sleep')

View File

@@ -7,7 +7,7 @@ Process: [Main](../glossary.md#main-process)
An example of implementing a protocol that has the same effect as the
`file://` protocol:
```js
```javascript
const { app, protocol, net } = require('electron')
app.whenReady().then(() => {
@@ -31,7 +31,7 @@ a different session and your custom protocol will not work if you just use
To have your custom protocol work in combination with a custom session, you need
to register it to that session explicitly.
```js
```javascript
const { app, BrowserWindow, net, protocol, session } = require('electron')
const path = require('node:path')
const url = require('url')
@@ -61,14 +61,13 @@ The `protocol` module has the following methods:
module gets emitted and can be called only once.
Registers the `scheme` as standard, secure, bypasses content security policy for
resources, allows registering ServiceWorker, supports fetch API, streaming
video/audio, and V8 code cache. Specify a privilege with the value of `true` to
enable the capability.
resources, allows registering ServiceWorker, supports fetch API, and streaming
video/audio. Specify a privilege with the value of `true` to enable the capability.
An example of registering a privileged scheme, that bypasses Content Security
Policy:
```js
```javascript
const { protocol } = require('electron')
protocol.registerSchemesAsPrivileged([
{ scheme: 'foo', privileges: { bypassCSP: true } }
@@ -213,7 +212,7 @@ property.
Example:
```js
```javascript
protocol.registerBufferProtocol('atom', (request, callback) => {
callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })
})
@@ -268,7 +267,7 @@ has the `data` property.
Example:
```js
```javascript
const { protocol } = require('electron')
const { PassThrough } = require('stream')
@@ -293,7 +292,7 @@ protocol.registerStreamProtocol('atom', (request, callback) => {
It is possible to pass any object that implements the readable stream API (emits
`data`/`end`/`error` events). For example, here's how a file could be returned:
```js
```javascript
protocol.registerStreamProtocol('atom', (request, callback) => {
callback(fs.createReadStream('index.html'))
})

View File

@@ -6,7 +6,7 @@ Process: [Main](../glossary.md#main-process)
For example, when registering for push notifications via Apple push notification services (APNS):
```js
```javascript
const { pushNotifications, Notification } = require('electron')
pushNotifications.registerForAPNSNotifications().then((token) => {

View File

@@ -14,29 +14,20 @@ property, so writing `let { screen } = require('electron')` will not work.
An example of creating a window that fills the whole screen:
```fiddle docs/fiddles/screen/fit-screen
// Retrieve information about screen size, displays, cursor position, etc.
//
// For more info, see:
// https://www.electronjs.org/docs/latest/api/screen
const { app, BrowserWindow, screen } = require('electron/main')
let mainWindow = null
```javascript fiddle='docs/fiddles/screen/fit-screen'
const { app, BrowserWindow, screen } = require('electron')
let win
app.whenReady().then(() => {
// Create a window that fills the screen's available work area.
const primaryDisplay = screen.getPrimaryDisplay()
const { width, height } = primaryDisplay.workAreaSize
mainWindow = new BrowserWindow({ width, height })
mainWindow.loadURL('https://electronjs.org')
const { width, height } = screen.getPrimaryDisplay().workAreaSize
win = new BrowserWindow({ width, height })
win.loadURL('https://github.com')
})
```
Another example of creating a window in the external display:
```js
```javascript
const { app, BrowserWindow, screen } = require('electron')
let win

View File

@@ -10,7 +10,7 @@ a `Session`.
For example:
```js
```javascript
const { session } = require('electron')
// Get all service workers.

View File

@@ -9,7 +9,7 @@ The `session` module can be used to create new `Session` objects.
You can also access the `session` of existing pages by using the `session`
property of [`WebContents`](web-contents.md), or from the `session` module.
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
@@ -75,7 +75,7 @@ _This class is not exported from the `'electron'` module. It is only available a
You can create a `Session` object in the `session` module:
```js
```javascript
const { session } = require('electron')
const ses = session.fromPartition('persist:name')
console.log(ses.getUserAgent())
@@ -98,7 +98,7 @@ Emitted when Electron is about to download `item` in `webContents`.
Calling `event.preventDefault()` will cancel the download and `item` will not be
available from next tick of the process.
```js @ts-expect-error=[4]
```javascript @ts-expect-error=[4]
const { session } = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
event.preventDefault()
@@ -214,7 +214,7 @@ cancel the request. Additionally, permissioning on `navigator.hid` can
be further managed by using [`ses.setPermissionCheckHandler(handler)`](#sessetpermissioncheckhandlerhandler)
and [`ses.setDevicePermissionHandler(handler)`](#sessetdevicepermissionhandlerhandler).
```js @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)}
```javascript @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)}
const { app, BrowserWindow } = require('electron')
let win = null
@@ -266,7 +266,7 @@ Returns:
* `event` Event
* `details` Object
* `device` [HIDDevice](structures/hid-device.md)
* `device` [HIDDevice[]](structures/hid-device.md)
* `frame` [WebFrameMain](web-frame-main.md)
Emitted after `navigator.hid.requestDevice` has been called and
@@ -281,7 +281,7 @@ Returns:
* `event` Event
* `details` Object
* `device` [HIDDevice](structures/hid-device.md)
* `device` [HIDDevice[]](structures/hid-device.md)
* `frame` [WebFrameMain](web-frame-main.md)
Emitted after `navigator.hid.requestDevice` has been called and
@@ -296,7 +296,7 @@ Returns:
* `event` Event
* `details` Object
* `device` [HIDDevice](structures/hid-device.md)
* `device` [HIDDevice[]](structures/hid-device.md)
* `origin` string (optional) - The origin that the device has been revoked from.
Emitted after `HIDDevice.forget()` has been called. This event can be used
@@ -320,7 +320,7 @@ cancel the request. Additionally, permissioning on `navigator.serial` can
be managed by using [ses.setPermissionCheckHandler(handler)](#sessetpermissioncheckhandlerhandler)
with the `serial` permission.
```js @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)}
```javascript @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)}
const { app, BrowserWindow } = require('electron')
let win = null
@@ -463,7 +463,7 @@ cancel the request. Additionally, permissioning on `navigator.usb` can
be further managed by using [`ses.setPermissionCheckHandler(handler)`](#sessetpermissioncheckhandlerhandler)
and [`ses.setDevicePermissionHandler(handler)`](#sessetdevicepermissionhandlerhandler).
```js @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)} @ts-type={updateGrantedDevices:(devices:Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)=>void}
```javascript @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)} @ts-type={updateGrantedDevices:(devices:Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)=>void}
const { app, BrowserWindow } = require('electron')
let win = null
@@ -754,7 +754,7 @@ Sets download saving directory. By default, the download directory will be the
Emulates network with the given configuration for the `session`.
```js
```javascript
const win = new BrowserWindow()
// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
@@ -785,7 +785,7 @@ Returns `Promise<void>` - Resolves when all connections are closed.
#### `ses.fetch(input[, init])`
* `input` string | [GlobalRequest](https://nodejs.org/api/globals.html#request)
* `init` [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options) & { bypassCustomProtocolHandlers?: boolean } (optional)
* `init` [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options) (optional)
Returns `Promise<GlobalResponse>` - see [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response).
@@ -868,7 +868,7 @@ calling `callback(-2)` rejects it.
Calling `setCertificateVerifyProc(null)` will revert back to default certificate
verify proc.
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
@@ -901,7 +901,6 @@ win.webContents.session.setCertificateVerifyProc((request, callback) => {
* `midiSysex` - Request the use of system exclusive messages in the [Web MIDI API](https://developer.mozilla.org/en-US/docs/Web/API/Web_MIDI_API).
* `notifications` - Request notification creation and the ability to display them in the user's system tray using the [Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/notification)
* `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.
* `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.
@@ -921,7 +920,7 @@ To clear the handler, call `setPermissionRequestHandler(null)`. Please note tha
you must also implement `setPermissionCheckHandler` to get complete permission handling.
Most web APIs do a permission check and then make a permission request if the check is denied.
```js
```javascript
const { session } = require('electron')
session.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {
if (webContents.getURL() === 'some-host' && permission === 'notifications') {
@@ -967,7 +966,7 @@ you must also implement `setPermissionRequestHandler` to get complete permission
Most web APIs do a permission check and then make a permission request if the check is denied.
To clear the handler, call `setPermissionCheckHandler(null)`.
```js
```javascript
const { session } = require('electron')
const url = require('url')
session.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
@@ -1012,7 +1011,7 @@ via the `navigator.mediaDevices.getDisplayMedia` API. Use the
[desktopCapturer](desktop-capturer.md) API to choose which stream(s) to grant
access to.
```js
```javascript
const { session, desktopCapturer } = require('electron')
session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
@@ -1026,7 +1025,7 @@ session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
Passing a [WebFrameMain](web-frame-main.md) object as a video or audio stream
will capture the video or audio stream from that frame.
```js
```javascript
const { session } = require('electron')
session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
@@ -1051,11 +1050,11 @@ To clear the handler, call `setDevicePermissionHandler(null)`.
This handler can be used to provide default permissioning to devices without first calling for permission
to devices (eg via `navigator.hid.requestDevice`). If this handler is not defined, the default device
permissions as granted through device selection (eg via `navigator.hid.requestDevice`) will be used.
Additionally, the default behavior of Electron is to store granted device permission in memory.
Additionally, the default behavior of Electron is to store granted device permision in memory.
If longer term storage is needed, a developer can store granted device
permissions (eg when handling the `select-hid-device` event) and then read from that storage with `setDevicePermissionHandler`.
```js @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)}
```javascript @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)}
const { app, BrowserWindow } = require('electron')
let win = null
@@ -1137,7 +1136,7 @@ The return value for the handler is a string array of USB classes which should b
Returning an empty string array from the handler will allow all USB classes; returning the passed in array will maintain the default list of protected USB classes (this is also the default behavior if a handler is not defined).
To clear the handler, call `setUSBProtectedClassesHandler(null)`.
```js
```javascript
const { app, BrowserWindow } = require('electron')
let win = null
@@ -1192,7 +1191,7 @@ that requires additional validation will be automatically cancelled.
macOS does not require a handler because macOS handles the pairing
automatically. To clear the handler, call `setBluetoothPairingHandler(null)`.
```js
```javascript
const { app, BrowserWindow, session } = require('electron')
const path = require('node:path')
@@ -1238,7 +1237,7 @@ Clears the host resolver cache.
Dynamically sets whether to always send credentials for HTTP NTLM or Negotiate
authentication.
```js
```javascript
const { session } = require('electron')
// consider any url ending with `example.com`, `foobar.com`, `baz`
// for integrated authentication.
@@ -1356,10 +1355,6 @@ registered.
Sets the directory to store the generated JS [code cache](https://v8.dev/blog/code-caching-for-devs) for this session. The directory is not required to be created by the user before this call, the runtime will create if it does not exist otherwise will use the existing directory. If directory cannot be created, then code cache will not be used and all operations related to code cache will fail silently inside the runtime. By default, the directory will be `Code Cache` under the
respective user data folder.
Note that by default code cache is only enabled for http(s) URLs, to enable code
cache for custom protocols, `codeCache: true` and `standard: true` must be
specified when registering the protocol.
#### `ses.clearCodeCaches(options)`
* `options` Object
@@ -1547,7 +1542,7 @@ A [`WebRequest`](web-request.md) object for this session.
A [`Protocol`](protocol.md) object for this session.
```js
```javascript
const { app, session } = require('electron')
const path = require('node:path')
@@ -1566,7 +1561,7 @@ app.whenReady().then(() => {
A [`NetLog`](net-log.md) object for this session.
```js
```javascript
const { app, session } = require('electron')
app.whenReady().then(async () => {

View File

@@ -8,7 +8,7 @@ The `shell` module provides functions related to desktop integration.
An example of opening a URL in the user's default browser:
```js
```javascript
const { shell } = require('electron')
shell.openExternal('https://github.com')

View File

@@ -97,6 +97,9 @@
* `roundedCorners` boolean (optional) _macOS_ - Whether frameless window
should have rounded corners on macOS. Default is `true`. Setting this property
to `false` will prevent the window from being fullscreenable.
* `fullscreenWindowTitle` boolean (optional) _macOS_ _Deprecated_ - Shows
the title in the title bar in full screen mode on macOS for `hiddenInset`
titleBarStyle. Default is `false`.
* `thickFrame` boolean (optional) - Use `WS_THICKFRAME` style for frameless windows on
Windows, which adds standard window frame. Setting it to `false` will remove
window shadow and window animations. Default is `true`.

View File

@@ -9,5 +9,3 @@
* `supportFetchAPI` boolean (optional) - Default false.
* `corsEnabled` boolean (optional) - Default false.
* `stream` boolean (optional) - Default false.
* `codeCache` boolean (optional) - Enable V8 code cache for the scheme, only
works when `standard` is also set to true. Default false.

View File

@@ -1,25 +1,22 @@
# Display Object
* `accelerometerSupport` string - Can be `available`, `unavailable`, `unknown`.
* `bounds` [Rectangle](rectangle.md) - the bounds of the display in DIP points.
* `colorDepth` number - The number of bits per pixel.
* `colorSpace` string - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversions.
* `depthPerComponent` number - The number of bits per color component.
* `detected` boolean - `true`` if the display is detected by the system.
* `displayFrequency` number - The display refresh rate.
* `id` number - Unique identifier associated with the display. A value of of -1 means the display is invalid or the correct `id` is not yet known, and a value of -10 means the display is a virtual display assigned to a unified desktop.
* `internal` boolean - `true` for an internal display and `false` for an external display.
* `id` number - Unique identifier associated with the display.
* `label` string - User-friendly label, determined by the platform.
* `maximumCursorSize` [Size](size.md) - Maximum cursor size in native pixels.
* `nativeOrigin` [Point](point.md) - Returns the display's origin in pixel coordinates. Only available on windowing systems like X11 that position displays in pixel coordinates.
* `rotation` number - Can be 0, 90, 180, 270, represents screen rotation in
clock-wise degrees.
* `scaleFactor` number - Output device's pixel scale factor.
* `touchSupport` string - Can be `available`, `unavailable`, `unknown`.
* `monochrome` boolean - Whether or not the display is a monochrome display.
* `accelerometerSupport` string - Can be `available`, `unavailable`, `unknown`.
* `colorSpace` string - represent a color space (three-dimensional object which contains all realizable color combinations) for the purpose of color conversions
* `colorDepth` number - The number of bits per pixel.
* `depthPerComponent` number - The number of bits per color component.
* `displayFrequency` number - The display refresh rate.
* `bounds` [Rectangle](rectangle.md) - the bounds of the display in DIP points.
* `size` [Size](size.md)
* `workArea` [Rectangle](rectangle.md) - the work area of the display in DIP points.
* `workAreaSize` [Size](size.md) - The size of the work area.
* `workAreaSize` [Size](size.md)
* `internal` boolean - `true` for an internal display and `false` for an external display
The `Display` object represents a physical display connected to the system. A
fake `Display` may exist on a headless system, or a `Display` may correspond to

View File

@@ -14,7 +14,7 @@ The number represented by `status` means different things on different platforms
Below is an example of some of the additional options that may be set which
may be different on each platform.
```js
```javascript
{
name: 'Austin_4th_Floor_Printer___C02XK13BJHD4',
displayName: 'Austin 4th Floor Printer @ C02XK13BJHD4',

View File

@@ -74,11 +74,7 @@
* `defaultEncoding` string (optional) - Defaults to `ISO-8859-1`.
* `backgroundThrottling` boolean (optional) - Whether to throttle animations and timers
when the page becomes background. This also affects the
[Page Visibility API](../browser-window.md#page-visibility). When at least one
[webContents](../web-contents.md) displayed in a single
[browserWindow](../browser-window.md) has disabled `backgroundThrottling` then
frames will be drawn and swapped for the whole window and other
[webContents](../web-contents.md) displayed by it. Defaults to `true`.
[Page Visibility API](../browser-window.md#page-visibility). Defaults to `true`.
* `offscreen` boolean (optional) - Whether to enable offscreen rendering for the browser
window. Defaults to `false`. See the
[offscreen rendering tutorial](../../tutorial/offscreen-rendering.md) for

View File

@@ -4,7 +4,7 @@
Process: [Main](../glossary.md#main-process)
```js
```javascript
const { systemPreferences } = require('electron')
console.log(systemPreferences.isAeroGlassEnabled())
```
@@ -189,7 +189,7 @@ enabled, and `false` otherwise.
An example of using it to determine if you should create a transparent window or
not (transparent windows won't work correctly when DWM composition is disabled):
```js
```javascript
const { BrowserWindow, systemPreferences } = require('electron')
const browserOptions = { width: 1000, height: 800 }
@@ -273,6 +273,7 @@ This API is only available on macOS 10.14 Mojave or newer.
* `window-frame` - Window frame.
* `window-text` - Text in windows.
* On **macOS**
* `alternate-selected-control-text` - The text on a selected surface in a list or table. _Deprecated_
* `control-background` - The background of a large interface element, such as a browser or table.
* `control` - The surface of a control.
* `control-text` -The text of a control that isnt disabled.
@@ -306,7 +307,7 @@ This API is only available on macOS 10.14 Mojave or newer.
* `window-background` - The background of a window.
* `window-frame-text` - The text in the window's titlebar area.
Returns `string` - The system color setting in RGBA hexadecimal form (`#RRGGBBAA`).
Returns `string` - The system color setting in RGB hexadecimal form (`#ABCDEF`).
See the [Windows docs][windows-colors] and the [macOS docs][macos-colors] for more details.
The following colors are only available on macOS 10.14: `find-highlight`, `selected-content-background`, `separator`, `unemphasized-selected-content-background`, `unemphasized-selected-text-background`, and `unemphasized-selected-text`.
@@ -338,6 +339,21 @@ Returns `string` - Can be `dark`, `light` or `unknown`.
Gets the macOS appearance setting that is currently applied to your application,
maps to [NSApplication.effectiveAppearance](https://developer.apple.com/documentation/appkit/nsapplication/2967171-effectiveappearance?language=objc)
### `systemPreferences.getAppLevelAppearance()` _macOS_ _Deprecated_
Returns `string` | `null` - Can be `dark`, `light` or `unknown`.
Gets the macOS appearance setting that you have declared you want for
your application, maps to [NSApplication.appearance](https://developer.apple.com/documentation/appkit/nsapplication/2967170-appearance?language=objc).
You can use the `setAppLevelAppearance` API to set this value.
### `systemPreferences.setAppLevelAppearance(appearance)` _macOS_ _Deprecated_
* `appearance` string | null - Can be `dark` or `light`
Sets the appearance setting for your application, this should override the
system default and override the value of `getEffectiveAppearance`.
### `systemPreferences.canPromptTouchID()` _macOS_
Returns `boolean` - whether or not this device has the ability to use Touch ID.
@@ -348,7 +364,7 @@ Returns `boolean` - whether or not this device has the ability to use Touch ID.
Returns `Promise<void>` - resolves if the user has successfully authenticated with Touch ID.
```js
```javascript
const { systemPreferences } = require('electron')
systemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {
@@ -401,9 +417,15 @@ Returns an object with system animation settings.
## Properties
### `systemPreferences.accessibilityDisplayShouldReduceTransparency()` _macOS_
### `systemPreferences.appLevelAppearance` _macOS_ _Deprecated_
A `boolean` property which determines whether the app avoids using semitransparent backgrounds. This maps to [NSWorkspace.accessibilityDisplayShouldReduceTransparency](https://developer.apple.com/documentation/appkit/nsworkspace/1533006-accessibilitydisplayshouldreduce)
A `string` property that can be `dark`, `light` or `unknown`. It determines the macOS appearance setting for
your application. This maps to values in: [NSApplication.appearance](https://developer.apple.com/documentation/appkit/nsapplication/2967170-appearance?language=objc). Setting this will override the
system default as well as the value of `getEffectiveAppearance`.
Possible values that can be set are `dark` and `light`, and possible return values are `dark`, `light`, and `unknown`.
This property is only available on macOS 10.14 Mojave or newer.
### `systemPreferences.effectiveAppearance` _macOS_ _Readonly_

View File

@@ -79,7 +79,7 @@ immediately updates the escape item in the touch bar.
Below is an example of a simple slot machine touch bar game with a button
and some labels.
```js
```javascript
const { app, BrowserWindow, TouchBar } = require('electron')
const { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar

View File

@@ -8,7 +8,7 @@ Process: [Main](../glossary.md#main-process)
`Tray` is an [EventEmitter][event-emitter].
```js
```javascript
const { app, Menu, Tray } = require('electron')
let tray = null
@@ -39,7 +39,7 @@ app.whenReady().then(() => {
* In order for changes made to individual `MenuItem`s to take effect,
you have to call `setContextMenu` again. For example:
```js
```javascript
const { app, Menu, Tray } = require('electron')
let appIcon = null
@@ -111,15 +111,6 @@ Returns:
Emitted when the tray icon is double clicked.
#### Event: 'middle-click' _Windows_
Returns:
* `event` [KeyboardEvent](structures/keyboard-event.md)
* `bounds` [Rectangle](structures/rectangle.md) - The bounds of tray icon.
Emitted when the tray icon is middle clicked.
#### Event: 'balloon-show' _Windows_
Emitted when the tray balloon shows.
@@ -187,7 +178,7 @@ Returns:
Emitted when the mouse clicks the tray icon.
#### Event: 'mouse-enter' _macOS_ _Windows_
#### Event: 'mouse-enter' _macOS_
Returns:
@@ -196,7 +187,7 @@ Returns:
Emitted when the mouse enters the tray icon.
#### Event: 'mouse-leave' _macOS_ _Windows_
#### Event: 'mouse-leave' _macOS_
Returns:

View File

@@ -28,9 +28,8 @@ Process: [Main](../glossary.md#main-process)<br />
* `ignore`: equivalent to \['ignore', 'ignore', 'ignore']
* `inherit`: equivalent to \['ignore', 'inherit', 'inherit']
* `serviceName` string (optional) - Name of the process that will appear in `name` property of
[`ProcessMetric`](structures/process-metric.md) returned by [`app.getAppMetrics`](app.md#appgetappmetrics)
and [`child-process-gone` event of `app`](app.md#event-child-process-gone).
Default is `Node Utility Process`.
[`child-process-gone` event of `app`](app.md#event-child-process-gone).
Default is `node.mojom.NodeService`.
* `allowLoadingUnsignedLibraries` boolean (optional) _macOS_ - With this flag, the utility process will be
launched via the `Electron Helper (Plugin).app` helper executable on macOS, which can be
codesigned with `com.apple.security.cs.disable-library-validation` and

View File

@@ -9,7 +9,7 @@ It is responsible for rendering and controlling a web page and is a property of
the [`BrowserWindow`](browser-window.md) object. An example of accessing the
`webContents` object:
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 1500 })
@@ -53,7 +53,7 @@ If you want to also observe navigations in `<iframe>`s, use [`will-frame-navigat
These methods can be accessed from the `webContents` module:
```js
```javascript
const { webContents } = require('electron')
console.log(webContents)
```
@@ -439,7 +439,7 @@ Emitted when a `beforeunload` event handler is attempting to cancel a page unloa
Calling `event.preventDefault()` will ignore the `beforeunload` event handler
and allow the page to be unloaded.
```js
```javascript
const { BrowserWindow, dialog } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('will-prevent-unload', (event) => {
@@ -541,7 +541,7 @@ and the menu shortcuts.
To only prevent the menu shortcuts, use
[`setIgnoreMenuShortcuts`](#contentssetignoremenushortcutsignore):
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
@@ -783,18 +783,9 @@ Returns:
word and spellchecker is enabled.
* `frameCharset` string - The character encoding of the frame on which the
menu was invoked.
* `formControlType` string - The source that the context menu was invoked on.
Possible values include `none`, `button-button`, `field-set`,
`input-button`, `input-checkbox`, `input-color`, `input-date`,
`input-datetime-local`, `input-email`, `input-file`, `input-hidden`,
`input-image`, `input-month`, `input-number`, `input-password`, `input-radio`,
`input-range`, `input-reset`, `input-search`, `input-submit`, `input-telephone`,
`input-text`, `input-time`, `input-url`, `input-week`, `output`, `reset-button`,
`select-list`, `select-list`, `select-multiple`, `select-one`, `submit-button`,
and `text-area`,
* `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`.
* `inputFieldType` string - 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`.
@@ -851,7 +842,7 @@ Due to the nature of bluetooth, scanning for devices when
`select-bluetooth-device` to fire multiple times until `callback` is called
with either a device id or an empty string to cancel the request.
```js title='main.js'
```javascript title='main.js'
const { app, BrowserWindow } = require('electron')
let win = null
@@ -886,7 +877,7 @@ Returns:
Emitted when a new frame is generated. Only the dirty area is passed in the
buffer.
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ webPreferences: { offscreen: true } })
@@ -1018,7 +1009,7 @@ Loads the `url` in the window. The `url` must contain the protocol prefix,
e.g. the `http://` or `file://`. If the load should bypass http cache then
use the `pragma` header to achieve it.
```js
```javascript
const win = new BrowserWindow()
const options = { extraHeaders: 'pragma: no-cache\n' }
win.webContents.loadURL('https://github.com', options)
@@ -1068,7 +1059,7 @@ Initiates a download of the resource at `url` without navigating. The
Returns `string` - The URL of the current web page.
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com').then(() => {
@@ -1220,7 +1211,7 @@ Returns `string` - The user agent for this web page.
* `css` string
* `options` Object (optional)
* `cssOrigin` string (optional) - Can be 'user' or 'author'. Sets the [cascade origin](https://www.w3.org/TR/css3-cascade/#cascade-origin) of the inserted stylesheet. Default is 'author'.
* `cssOrigin` string (optional) - Can be either 'user' or 'author'. Sets the [cascade origin](https://www.w3.org/TR/css3-cascade/#cascade-origin) of the inserted stylesheet. Default is 'author'.
Returns `Promise<string>` - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via `contents.removeInsertedCSS(key)`.
@@ -1517,7 +1508,7 @@ can be obtained by subscribing to [`found-in-page`](web-contents.md#event-found-
Stops any `findInPage` request for the `webContents` with the provided `action`.
```js
```javascript
const win = new BrowserWindow()
win.webContents.on('found-in-page', (event, result) => {
if (result.finalUpdate) win.webContents.stopFindInPage('clearSelection')
@@ -1637,7 +1628,7 @@ The `landscape` will be ignored if `@page` CSS at-rule is used in the web page.
An example of `webContents.printToPDF`:
```js
```javascript
const { BrowserWindow } = require('electron')
const fs = require('node:fs')
const path = require('node:path')
@@ -1669,7 +1660,7 @@ See [Page.printToPdf](https://chromedevtools.github.io/devtools-protocol/tot/Pag
Adds the specified path to DevTools workspace. Must be used after DevTools
creation:
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.webContents.on('devtools-opened', () => {
@@ -1992,7 +1983,7 @@ the cursor when dragging.
Returns `Promise<void>` - resolves if the page is saved.
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

View File

@@ -8,7 +8,7 @@ The `webFrameMain` module can be used to lookup frames across existing
[`WebContents`](web-contents.md) instances. Navigation events are the common
use case.
```js
```javascript
const { BrowserWindow, webFrameMain } = require('electron')
const win = new BrowserWindow({ width: 800, height: 1500 })
@@ -29,7 +29,7 @@ win.webContents.on(
You can also access frames of existing pages by using the `mainFrame` property
of [`WebContents`](web-contents.md).
```js
```javascript
const { BrowserWindow } = require('electron')
async function main () {

View File

@@ -10,7 +10,7 @@ certain properties and methods (e.g. `webFrame.firstChild`).
An example of zooming current page to 200%.
```js
```javascript
const { webFrame } = require('electron')
webFrame.setZoomFactor(2)
@@ -96,7 +96,7 @@ with an array of misspelt words when complete.
An example of using [node-spellchecker][spellchecker] as provider:
```js @ts-expect-error=[2,6]
```javascript @ts-expect-error=[2,6]
const { webFrame } = require('electron')
const spellChecker = require('spellchecker')
webFrame.setSpellCheckProvider('en-US', {
@@ -113,7 +113,7 @@ webFrame.setSpellCheckProvider('en-US', {
* `css` string
* `options` Object (optional)
* `cssOrigin` string (optional) - Can be 'user' or 'author'. Sets the [cascade origin](https://www.w3.org/TR/css3-cascade/#cascade-origin) of the inserted stylesheet. Default is 'author'.
* `cssOrigin` string (optional) - Can be either 'user' or 'author'. Sets the [cascade origin](https://www.w3.org/TR/css3-cascade/#cascade-origin) of the inserted stylesheet. Default is 'author'.
Returns `string` - A key for the inserted CSS that can later be used to remove
the CSS via `webFrame.removeInsertedCSS(key)`.
@@ -205,14 +205,14 @@ Returns `Object`:
Returns an object describing usage information of Blink's internal memory
caches.
```js
```javascript
const { webFrame } = require('electron')
console.log(webFrame.getResourceUsage())
```
This will generate:
```js
```javascript
{
images: {
count: 22,

View File

@@ -23,7 +23,7 @@ called with a `response` object when `listener` has done its work.
An example of adding `User-Agent` header for requests:
```js
```javascript
const { session } = require('electron')
// Modify the user agent for all requests to the following urls.

View File

@@ -255,7 +255,7 @@ The `webview` tag has the following methods:
**Example**
```js @ts-expect-error=[3]
```javascript @ts-expect-error=[3]
const webview = document.querySelector('webview')
webview.addEventListener('dom-ready', () => {
webview.openDevTools()
@@ -802,7 +802,7 @@ Fired when the guest window logs a console message.
The following example code forwards all log messages to the embedder's console
without regard for log level or other properties.
```js @ts-expect-error=[3]
```javascript @ts-expect-error=[3]
const webview = document.querySelector('webview')
webview.addEventListener('console-message', (e) => {
console.log('Guest page logged a message:', e.message)
@@ -823,7 +823,7 @@ Returns:
Fired when a result is available for
[`webview.findInPage`](#webviewfindinpagetext-options) request.
```js @ts-expect-error=[3,6]
```javascript @ts-expect-error=[3,6]
const webview = document.querySelector('webview')
webview.addEventListener('found-in-page', (e) => {
webview.stopFindInPage('keepSelection')
@@ -948,7 +948,7 @@ Fired when the guest page attempts to close itself.
The following example code navigates the `webview` to `about:blank` when the
guest attempts to close itself.
```js @ts-expect-error=[3]
```javascript @ts-expect-error=[3]
const webview = document.querySelector('webview')
webview.addEventListener('close', () => {
webview.src = 'about:blank'
@@ -968,7 +968,7 @@ Fired when the guest page has sent an asynchronous message to embedder page.
With `sendToHost` method and `ipc-message` event you can communicate
between guest page and embedder page:
```js @ts-expect-error=[4,7]
```javascript @ts-expect-error=[4,7]
// In embedder page.
const webview = document.querySelector('webview')
webview.addEventListener('ipc-message', (event) => {
@@ -978,7 +978,7 @@ webview.addEventListener('ipc-message', (event) => {
webview.send('ping')
```
```js
```javascript
// In guest page.
const { ipcRenderer } = require('electron')
ipcRenderer.on('ping', () => {
@@ -1106,18 +1106,9 @@ Returns:
word and spellchecker is enabled.
* `frameCharset` string - The character encoding of the frame on which the
menu was invoked.
* `formControlType` string - The source that the context menu was invoked on.
Possible values include `none`, `button-button`, `field-set`,
`input-button`, `input-checkbox`, `input-color`, `input-date`,
`input-datetime-local`, `input-email`, `input-file`, `input-hidden`,
`input-image`, `input-month`, `input-number`, `input-password`, `input-radio`,
`input-range`, `input-reset`, `input-search`, `input-submit`, `input-telephone`,
`input-text`, `input-time`, `input-url`, `input-week`, `output`, `reset-button`,
`select-list`, `select-list`, `select-multiple`, `select-one`, `submit-button`,
and `text-area`,
* `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`.
* `inputFieldType` string - 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`.

View File

@@ -80,7 +80,7 @@ window will not close when the opener window closes. The default value is `false
### Native `Window` example
```js
```javascript
// main.js
const mainWindow = new BrowserWindow()
@@ -104,7 +104,7 @@ mainWindow.webContents.setWindowOpenHandler(({ url }) => {
})
```
```js
```javascript
// renderer process (mainWindow)
const childWindow = window.open('', 'modal')
childWindow.document.write('<h1>Hello</h1>')

View File

@@ -14,11 +14,6 @@ This document uses the following convention to categorize breaking changes:
## Planned Breaking API Changes (28.0)
### Behavior Changed: `WebContents.backgroundThrottling` set to false affects all `WebContents` in the host `BrowserWindow`
`WebContents.backgroundThrottling` set to false will disable frames throttling
in the `BrowserWindow` for all `WebContents` displayed by it.
### Removed: `BrowserWindow.setTrafficLightPosition(position)`
`BrowserWindow.setTrafficLightPosition(position)` has been removed, the
@@ -63,65 +58,6 @@ The `ipcRenderer.sendTo()` API has been removed. It should be replaced by settin
The `senderId` and `senderIsMainFrame` properties of `IpcRendererEvent` have been removed as well.
### Removed: `app.runningUnderRosettaTranslation`
The `app.runningUnderRosettaTranslation` property has been removed.
Use `app.runningUnderARM64Translation` instead.
```js
// Removed
console.log(app.runningUnderRosettaTranslation)
// Replace with
console.log(app.runningUnderARM64Translation)
```
### Deprecated: `renderer-process-crashed` event on `app`
The `renderer-process-crashed` event on `app` has been deprecated.
Use the new `render-process-gone` event instead.
```js
// Deprecated
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })
// Replace with
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })
```
### Deprecated: `params.inputFormType` property on `context-menu` on `WebContents`
The `inputFormType` property of the params object in the `context-menu`
event from `WebContents` has been deprecated. Use the new `formControlType`
property instead.
### Deprecated: `crashed` event on `WebContents` and `<webview>`
The `crashed` events on `WebContents` and `<webview>` have been deprecated.
Use the new `render-process-gone` event instead.
```js
// Deprecated
win.webContents.on('crashed', (event, killed) => { /* ... */ })
webview.addEventListener('crashed', (event) => { /* ... */ })
// Replace with
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
webview.addEventListener('render-process-gone', (event) => { /* ... */ })
```
### Deprecated: `gpu-process-crashed` event on `app`
The `gpu-process-crashed` event on `app` has been deprecated.
Use the new `child-process-gone` event instead.
```js
// Deprecated
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })
// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })
```
## Planned Breaking API Changes (27.0)
### Removed: macOS 10.13 / 10.14 support
@@ -171,41 +107,6 @@ w.webContents.getPrintersAsync().then((printers) => {
})
```
### Removed: `systemPreferences.{get,set}AppLevelAppearance` and `systemPreferences.appLevelAppearance`
The `systemPreferences.getAppLevelAppearance` and `systemPreferences.setAppLevelAppearance`
methods have been removed, as well as the `systemPreferences.appLevelAppearance` property.
Use the `nativeTheme` module instead.
```js
// Removed
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors
// Removed
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors
// Removed
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'
```
### Removed: `alternate-selected-control-text` value for `systemPreferences.getColor`
The `alternate-selected-control-text` value for `systemPreferences.getColor`
has been removed. Use `selected-content-background` instead.
```js
// Removed
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')
```
## Planned Breaking API Changes (26.0)
### Deprecated: `webContents.getPrinters`
@@ -534,7 +435,7 @@ The `new-window` event of `<webview>` has been removed. There is no direct repla
webview.addEventListener('new-window', (event) => {})
```
```js
```javascript fiddle='docs/fiddles/ipc/webview-new-window'
// Replace with
// main.js
@@ -780,18 +681,6 @@ to open synchronously scriptable child windows, among other incompatibilities.
See the documentation for [window.open in Electron](api/window-open.md)
for more details.
### Deprecated: `app.runningUnderRosettaTranslation`
The `app.runningUnderRosettaTranslation` property has been deprecated.
Use `app.runningUnderARM64Translation` instead.
```js
// Deprecated
console.log(app.runningUnderRosettaTranslation)
// Replace with
console.log(app.runningUnderARM64Translation)
```
## Planned Breaking API Changes (14.0)
### Removed: `remote` module
@@ -1199,7 +1088,7 @@ module](https://medium.com/@nornagon/electrons-remote-module-considered-harmful-
The APIs are now synchronous and the optional callback is no longer needed.
```js
```javascript
// Deprecated
protocol.unregisterProtocol(scheme, () => { /* ... */ })
// Replace with
@@ -1228,7 +1117,7 @@ protocol.unregisterProtocol(scheme)
The APIs are now synchronous and the optional callback is no longer needed.
```js
```javascript
// Deprecated
protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
// Replace with
@@ -1243,7 +1132,7 @@ until navigation happens.
This API is deprecated and users should use `protocol.isProtocolRegistered`
and `protocol.isProtocolIntercepted` instead.
```js
```javascript
// Deprecated
protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
// Replace with

View File

@@ -164,7 +164,7 @@ An example of the contents of this file can be found [here](https://github.com/e
Add your module to the module list found at `"lib/browser/api/module-list.ts"` like so:
```ts title='lib/browser/api/module-list.ts' @ts-nocheck
```typescript title='lib/browser/api/module-list.ts' @ts-nocheck
export const browserModuleList: ElectronInternal.ModuleEntry[] = [
{ name: 'apiName', loader: () => require('./api-name') },
];

View File

@@ -65,7 +65,7 @@ If you encounter this problem, the following articles may prove helpful:
If you want a quick fix, you can make the variables global by changing your
code from this:
```js
```javascript
const { app, Tray } = require('electron')
app.whenReady().then(() => {
const tray = new Tray('/path/to/icon.png')
@@ -75,7 +75,7 @@ app.whenReady().then(() => {
to this:
```js
```javascript
const { app, Tray } = require('electron')
let tray = null
app.whenReady().then(() => {
@@ -92,7 +92,7 @@ for some libraries since they want to insert the symbols with the same names.
To solve this, you can turn off node integration in Electron:
```js
```javascript
// In the main process.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
@@ -141,7 +141,7 @@ Sub-pixel anti-aliasing needs a non-transparent background of the layer containi
To achieve this goal, set the background in the constructor for [BrowserWindow][browser-window]:
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
backgroundColor: '#fff'

View File

@@ -7,20 +7,14 @@ function createWindow () {
height: 600
})
win.setRepresentedFilename(os.homedir())
win.setDocumentEdited(true)
win.loadFile('index.html')
}
app.whenReady().then(() => {
createWindow()
const win = new BrowserWindow()
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) {
createWindow()
}
})
win.setRepresentedFilename(os.homedir())
win.setDocumentEdited(true)
})
app.on('window-all-closed', () => {
@@ -28,3 +22,9 @@ app.on('window-all-closed', () => {
app.quit()
}
})
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) {
createWindow()
}
})

View File

@@ -1,6 +1,5 @@
const { contextBridge, ipcRenderer } = require('electron/renderer')
contextBridge.exposeInMainWorld('electronAPI', {
onUpdateCounter: (callback) => ipcRenderer.on('update-counter', (_event, value) => callback(value)),
counterValue: (value) => ipcRenderer.send('counter-value', value)
handleCounter: (callback) => ipcRenderer.on('update-counter', () => callback())
})

View File

@@ -1,8 +1,8 @@
const counter = document.getElementById('counter')
window.electronAPI.onUpdateCounter((value) => {
window.electronAPI.handleCounter((event, value) => {
const oldValue = Number(counter.innerText)
const newValue = oldValue + value
counter.innerText = newValue.toString()
window.electronAPI.counterValue(newValue)
counter.innerText = newValue
event.sender.send('counter-value', newValue)
})

View File

@@ -44,7 +44,7 @@
<h3>Packaging</h3>
<p>This feature will only work on macOS when your app is packaged. It will not work when you're launching it in
development from the command-line. When you package your app you'll need to make sure the macOS <code>plist</code>
for the app is updated to include the new protocol handler. If you're using <code>@electron/packager</code> then you
for the app is updated to include the new protocol handler. If you're using <code>electron-packager</code> then you
can add the flag <code>--extend-info</code> with a path to the <code>plist</code> you've created. The one for this
app is below:</p>

View File

@@ -12,7 +12,7 @@ including instances of `BrowserWindow`, `BrowserView`, and `WebView`. You
can open them programmatically by calling the `openDevTools()` API on the
`webContents` of the instance:
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

View File

@@ -41,27 +41,27 @@ $ asar list /path/to/example.asar
Read a file in the ASAR archive:
```js
```javascript
const fs = require('node:fs')
fs.readFileSync('/path/to/example.asar/file.txt')
```
List all files under the root of the archive:
```js
```javascript
const fs = require('node:fs')
fs.readdirSync('/path/to/example.asar')
```
Use a module from the archive:
```js @ts-nocheck
```javascript @ts-nocheck
require('./path/to/example.asar/dir/module.js')
```
You can also display a web page in an ASAR archive with `BrowserWindow`:
```js
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
@@ -90,7 +90,7 @@ For some cases like verifying the ASAR archive's checksum, we need to read the
content of an ASAR archive as a file. For this purpose you can use the built-in
`original-fs` module which provides original `fs` APIs without `asar` support:
```js
```javascript
const originalFs = require('original-fs')
originalFs.readFileSync('/path/to/example.asar')
```
@@ -98,7 +98,7 @@ originalFs.readFileSync('/path/to/example.asar')
You can also set `process.noAsar` to `true` to disable the support for `asar` in
the `fs` module:
```js
```javascript
const fs = require('node:fs')
process.noAsar = true
fs.readFileSync('/path/to/example.asar')

View File

@@ -13,7 +13,7 @@ Currently ASAR integrity checking is only supported on macOS.
### Electron Forge / Electron Packager
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).
If you are using `>= 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).
### Other build systems

View File

@@ -22,101 +22,34 @@ There are a few ways that you can set up testing using WebDriver.
Node.js package for testing with WebDriver. Its ecosystem also includes various plugins
(e.g. reporter and services) that can help you put together your test setup.
If you already have an existing WebdriverIO setup, it is recommended to update your dependencies and validate your existing configuration with how it is [outlined in the docs](https://webdriver.io/docs/desktop-testing/electron#configuration).
#### Install the test runner
If you don't use WebdriverIO in your project yet, you can add it by running the starter toolkit in your project root directory:
First you need to run the WebdriverIO starter toolkit in your project root directory:
```sh npm2yarn
npm init wdio@latest ./
npx wdio . --yes
```
This starts a configuration wizard that helps you put together the right setup, installs all necessary packages, and generates a `wdio.conf.js` configuration file. Make sure to select _"Desktop Testing - of Electron Applications"_ on one of the first questions asking _"What type of testing would you like to do?"_.
This installs all necessary packages for you and generates a `wdio.conf.js` configuration file.
#### Connect WDIO to your Electron app
After running the configuration wizard, your `wdio.conf.js` should include roughly the following content:
Update the capabilities in your configuration file to point to your Electron app binary:
```js title='wdio.conf.js' @ts-nocheck
export const config = {
```javascript title='wdio.conf.js'
exports.config = {
// ...
services: ['electron'],
capabilities: [{
browserName: 'electron',
'wdio:electronServiceOptions': {
// WebdriverIO can automatically find your bundled application
// if you use Electron Forge or electron-builder, otherwise you
// can define it here, e.g.:
// appBinaryPath: './path/to/bundled/application.exe',
appArgs: ['foo', 'bar=baz']
browserName: 'chrome',
'goog:chromeOptions': {
binary: '/path/to/your/electron/binary', // Path to your Electron binary.
args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/
}
}]
// ...
}
```
#### Write your tests
Use the [WebdriverIO API](https://webdriver.io/docs/api) to interact with elements on the screen. The framework provides custom "matchers" that make asserting the state of your application easy, e.g.:
```js @ts-nocheck
import { browser, $, expect } from '@wdio/globals'
describe('keyboard input', () => {
it('should detect keyboard input', async () => {
await browser.keys(['y', 'o'])
await expect($('keypress-count')).toHaveText('YO')
})
})
```
Furthermore, WebdriverIO allows you to access Electron APIs to get static information about your application:
```js @ts-nocheck
import { browser, $, expect } from '@wdio/globals'
describe('when the make smaller button is clicked', () => {
it('should decrease the window height and width by 10 pixels', async () => {
const boundsBefore = await browser.electron.browserWindow('getBounds')
expect(boundsBefore.width).toEqual(210)
expect(boundsBefore.height).toEqual(310)
await $('.make-smaller').click()
const boundsAfter = await browser.electron.browserWindow('getBounds')
expect(boundsAfter.width).toEqual(200)
expect(boundsAfter.height).toEqual(300)
})
})
```
or to retrieve other Electron process information:
```js @ts-nocheck
import fs from 'node:fs'
import path from 'node:path'
import { browser, expect } from '@wdio/globals'
const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), { encoding: 'utf-8' }))
const { name, version } = packageJson
describe('electron APIs', () => {
it('should retrieve app metadata through the electron API', async () => {
const appName = await browser.electron.app('getName')
expect(appName).toEqual(name)
const appVersion = await browser.electron.app('getVersion')
expect(appVersion).toEqual(version)
})
it('should pass args through to the launched application', async () => {
// custom args are set in the wdio.conf.js file as they need to be set before WDIO starts
const argv = await browser.electron.mainProcess('argv')
expect(argv).toContain('--foo')
expect(argv).toContain('--bar=baz')
})
})
```
#### Run your tests
To run your tests:
@@ -125,12 +58,6 @@ To run your tests:
$ npx wdio run wdio.conf.js
```
WebdriverIO helps launch and shut down the application for you.
#### More documentation
Find more documentation on Mocking Electron APIs and other useful resources in the [official WebdriverIO documentation](https://webdriver.io/docs/desktop-testing/electron).
### With Selenium
[Selenium](https://www.selenium.dev/) is a web automation framework that

View File

@@ -30,7 +30,7 @@ Electron Forge is a tool for packaging and publishing Electron applications. It
into a single extensible interface so that anyone can jump right into making Electron apps.
Forge comes with [a ready-to-use template](https://electronforge.io/templates) using Webpack as a bundler. It includes an example typescript configuration and provides two configuration files to enable easy customization. It uses the same core modules used by the
greater Electron community (like [`@electron/packager`](https://github.com/electron/packager))
greater Electron community (like [`electron-packager`](https://github.com/electron/electron-packager))
changes made by Electron maintainers (like Slack) benefit Forge's users, too.
You can find more information and documentation on [electronforge.io](https://electronforge.io/).

View File

@@ -51,7 +51,7 @@ ways to get your application signed and notarized.
If you're using Electron's favorite build tool, getting your application signed
and notarized requires a few additions to your configuration. [Forge](https://electronforge.io) is a
collection of the official Electron tools, using [`@electron/packager`][],
collection of the official Electron tools, using [`electron-packager`][],
[`@electron/osx-sign`][], and [`@electron/notarize`][] under the hood.
Detailed instructions on how to configure your application can be found in the
@@ -61,14 +61,14 @@ the Electron Forge docs.
### Using Electron Packager
If you're not using an integrated build pipeline like Forge, you
are likely using [`@electron/packager`][], which includes [`@electron/osx-sign`][] and
are likely using [`electron-packager`][], which includes [`@electron/osx-sign`][] and
[`@electron/notarize`][].
If you're using Packager's API, you can pass [in configuration that both signs
and notarizes your application](https://electron.github.io/packager/main/interfaces/electronpackager.options.html).
and notarizes your application](https://electron.github.io/electron-packager/main/interfaces/electronpackager.options.html).
```js @ts-nocheck
const packager = require('@electron/packager')
const packager = require('electron-packager')
packager({
dir: '/path/to/my/app',
@@ -190,7 +190,7 @@ See the [Windows Store Guide][].
[apple developer program]: https://developer.apple.com/programs/
[`@electron/osx-sign`]: https://github.com/electron/osx-sign
[`@electron/packager`]: https://github.com/electron/packager
[`electron-packager`]: https://github.com/electron/electron-packager
[`@electron/notarize`]: https://github.com/electron/notarize
[`electron-winstaller`]: https://github.com/electron/windows-installer
[`electron-wix-msi`]: https://github.com/electron-userland/electron-wix-msi

View File

@@ -16,7 +16,7 @@ Context isolation has been enabled by default since Electron 12, and it is a rec
Exposing APIs from your preload script to a loaded website in the renderer process is a common use-case. With context isolation disabled, your preload script would share a common global `window` object with the renderer. You could then attach arbitrary properties to a preload script:
```js title='preload.js' @ts-nocheck
```javascript title='preload.js' @ts-nocheck
// preload with contextIsolation disabled
window.myAPI = {
doAThing: () => {}
@@ -25,7 +25,7 @@ window.myAPI = {
The `doAThing()` function could then be used directly in the renderer process:
```js title='renderer.js' @ts-nocheck
```javascript title='renderer.js' @ts-nocheck
// use the exposed API in the renderer
window.myAPI.doAThing()
```
@@ -34,7 +34,7 @@ window.myAPI.doAThing()
There is a dedicated module in Electron to help you do this in a painless way. The [`contextBridge`](../api/context-bridge.md) module can be used to **safely** expose APIs from your preload script's isolated context to the context the website is running in. The API will also be accessible from the website on `window.myAPI` just like it was before.
```js title='preload.js'
```javascript title='preload.js'
// preload with contextIsolation enabled
const { contextBridge } = require('electron')
@@ -43,7 +43,7 @@ contextBridge.exposeInMainWorld('myAPI', {
})
```
```js title='renderer.js' @ts-nocheck
```javascript title='renderer.js' @ts-nocheck
// use the exposed API in the renderer
window.myAPI.doAThing()
```
@@ -54,7 +54,7 @@ Please read the `contextBridge` documentation linked above to fully understand i
Just enabling `contextIsolation` and using `contextBridge` does not automatically mean that everything you do is safe. For instance, this code is **unsafe**.
```js title='preload.js'
```javascript title='preload.js'
// ❌ Bad code
contextBridge.exposeInMainWorld('myAPI', {
send: ipcRenderer.send
@@ -63,7 +63,7 @@ contextBridge.exposeInMainWorld('myAPI', {
It directly exposes a powerful API without any kind of argument filtering. This would allow any website to send arbitrary IPC messages, which you do not want to be possible. The correct way to expose IPC-based APIs would instead be to provide one method per IPC message.
```js title='preload.js'
```javascript title='preload.js'
// ✅ Good code
contextBridge.exposeInMainWorld('myAPI', {
loadPreferences: () => ipcRenderer.invoke('load-prefs')
@@ -76,7 +76,7 @@ If you're building your Electron app with TypeScript, you'll want to add types t
For example, given this `preload.ts` script:
```ts title='preload.ts'
```typescript title='preload.ts'
contextBridge.exposeInMainWorld('electronAPI', {
loadPreferences: () => ipcRenderer.invoke('load-prefs')
})
@@ -84,7 +84,7 @@ contextBridge.exposeInMainWorld('electronAPI', {
You can create a `renderer.d.ts` declaration file and globally augment the `Window` interface:
```ts title='renderer.d.ts' @ts-noisolate
```typescript title='renderer.d.ts' @ts-noisolate
export interface IElectronAPI {
loadPreferences: () => Promise<void>,
}
@@ -98,7 +98,7 @@ declare global {
Doing so will ensure that the TypeScript compiler will know about the `electronAPI` property on your global `window` object when writing scripts in your renderer process:
```ts title='renderer.ts'
```typescript title='renderer.ts'
window.electronAPI.loadPreferences()
```

View File

@@ -50,7 +50,7 @@ of this theming, due to the use of the macOS 10.14 SDK.
This example demonstrates an Electron application that derives its theme colors from the
`nativeTheme`. Additionally, it provides theme toggle and reset controls using IPC channels.
```fiddle docs/fiddles/features/dark-mode
```javascript fiddle='docs/fiddles/features/dark-mode'
```
@@ -199,7 +199,7 @@ Run the example using Electron Fiddle and then click the "Toggle Dark Mode" butt
[system-wide-dark-mode]: https://developer.apple.com/design/human-interface-guidelines/macos/visual-design/dark-mode/
[electron-forge]: https://www.electronforge.io/
[electron-packager]: https://github.com/electron/packager
[packager-darwindarkmode-api]: https://electron.github.io/packager/main/interfaces/electronpackager.options.html#darwindarkmodesupport
[electron-packager]: https://github.com/electron/electron-packager
[packager-darwindarkmode-api]: https://electron.github.io/electron-packager/main/interfaces/electronpackager.options.html#darwindarkmodesupport
[prefers-color-scheme]: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
[event-listeners]: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener

View File

@@ -14,10 +14,10 @@ process:
Electron will listen for V8 inspector protocol messages on the specified `port`,
an external debugger will need to connect on this port. The default `port` is
`9229`.
`5858`.
```shell
electron --inspect=9229 your/app
electron --inspect=5858 your/app
```
### `--inspect-brk=[port]`

View File

@@ -26,7 +26,7 @@ This example demonstrates an Electron application that automatically selects
the first available bluetooth device when the `Test Bluetooth` button is
clicked.
```fiddle docs/fiddles/features/web-bluetooth
```javascript fiddle='docs/fiddles/features/web-bluetooth'
```
@@ -61,7 +61,7 @@ By default Electron employs the same [blocklist](https://github.com/WICG/webhid/
used by Chromium. If you wish to override this behavior, you can do so by
setting the `disable-hid-blocklist` flag:
```js
```javascript
app.commandLine.appendSwitch('disable-hid-blocklist')
```
@@ -72,7 +72,7 @@ HID devices through [`ses.setDevicePermissionHandler(handler)`](../api/session.m
and through [`select-hid-device` event on the Session](../api/session.md#event-select-hid-device)
when the `Test WebHID` button is clicked.
```fiddle docs/fiddles/features/web-hid
```javascript fiddle='docs/fiddles/features/web-hid'
```
@@ -112,7 +112,7 @@ as well as demonstrating selecting the first available Arduino Uno serial device
[`select-serial-port` event on the Session](../api/session.md#event-select-serial-port)
when the `Test Web Serial` button is clicked.
```fiddle docs/fiddles/features/web-serial
```javascript fiddle='docs/fiddles/features/web-serial'
```
@@ -152,6 +152,6 @@ USB devices (if they are attached) through [`ses.setDevicePermissionHandler(hand
and through [`select-usb-device` event on the Session](../api/session.md#event-select-usb-device)
when the `Test WebUSB` button is clicked.
```fiddle docs/fiddles/features/web-usb
```javascript fiddle='docs/fiddles/features/web-usb'
```

View File

@@ -33,7 +33,7 @@ Using the [React Developer Tools][react-devtools] as an example:
1. Pass the location of the extension to the [`ses.loadExtension`][load-extension]
API. For React Developer Tools `v4.9.0`, it looks something like:
```js
```javascript
const { app, session } = require('electron')
const path = require('node:path')
const os = require('node:os')

View File

@@ -9,14 +9,12 @@ check out our [Electron Versioning](./electron-versioning.md) doc.
| Electron | Alpha | Beta | Stable | EOL | Chrome | Node | Supported |
| ------- | ----- | ------- | ------ | ------ | ---- | ---- | ---- |
| 29.0.0 | 2023-Dec-07 | 2024-Jan-24 | 2024-Feb-20 | 2024-Aug-20 | M122 | v18.19 | ✅ |
| 28.0.0 | 2023-Oct-11 | 2023-Nov-06 | 2023-Dec-05 | 2024-Jun-11 | M120 | v18.18 | ✅ |
| 27.0.0 | 2023-Aug-17 | 2023-Sep-13 | 2023-Oct-10 | 2024-Apr-16 | M118 | v18.17 | ✅ |
| 26.0.0 | 2023-Jun-01 | 2023-Jun-27 | 2023-Aug-15 | 2024-Feb-20 | M116 | v18.16 | ✅ |
| 25.0.0 | 2023-Apr-10 | 2023-May-02 | 2023-May-30 | 2023-Dec-05 | M114 | v18.15 | 🚫 |
| 24.0.0 | 2023-Feb-09 | 2023-Mar-07 | 2023-Apr-04 | 2023-Oct-10 | M112 | v18.14 | 🚫 |
| 27.0.0 | 2023-Aug-17 | 2023-Sep-13 | 2023-Oct-10 | TBD | M118 | TBD | ✅ |
| 26.0.0 | 2023-Jun-01 | 2023-Jun-27 | 2023-Aug-15 | 2024-Feb-27 | M116 | v18.16 | ✅ |
| 25.0.0 | 2023-Apr-10 | 2023-May-02 | 2023-May-30 | 2024-Jan-02 | M114 | v18.15 | ✅ |
| 24.0.0 | 2022-Feb-09 | 2023-Mar-07 | 2023-Apr-04 | 2023-Oct-10 | M112 | v18.14 | ✅ |
| 23.0.0 | 2022-Dec-01 | 2023-Jan-10 | 2023-Feb-07 | 2023-Aug-15 | M110 | v18.12 | 🚫 |
| 22.0.0 | 2022-Sep-29 | 2022-Oct-25 | 2022-Nov-29 | 2023-Oct-10 | M108 | v16.17 | 🚫 |
| 22.0.0 | 2022-Sep-29 | 2022-Oct-25 | 2022-Nov-29 | 2023-Oct-10 | M108 | v16.17 | |
| 21.0.0 | 2022-Aug-04 | 2022-Aug-30 | 2022-Sep-27 | 2023-Apr-04 | M106 | v16.16 | 🚫 |
| 20.0.0 | 2022-May-26 | 2022-Jun-21 | 2022-Aug-02 | 2023-Feb-07 | M104 | v16.15 | 🚫 |
| 19.0.0 | 2022-Mar-31 | 2022-Apr-26 | 2022-May-24 | 2022-Nov-29 | M102 | v16.14 | 🚫 |
@@ -50,6 +48,12 @@ check out our [Electron Versioning](./electron-versioning.md) doc.
* Since Electron 6, Electron major versions have been targeting every other Chromium major version. Each Electron stable should happen on the same day as Chrome stable ([see blog post](https://www.electronjs.org/blog/12-week-cadence)).
* Since Electron 16, Electron has been releasing major versions on an 8-week cadence in accordance to Chrome's change to a 4-week release cadence ([see blog post](https://www.electronjs.org/blog/8-week-cadence)).
:::info Chrome release dates
Chromium has the own public release schedule [here](https://chromiumdash.appspot.com/schedule).
:::
## Version support policy
:::info
@@ -74,38 +78,6 @@ and the version prior to that receives the vast majority of those fixes
as time and bandwidth warrants. The oldest supported release line will receive
only security fixes directly.
### Chromium version support
:::info Chromium release schedule
Chromium's public release schedule is [here](https://chromiumdash.appspot.com/schedule).
:::
Electron targets Chromium even-number versions, releasing every 8 weeks in concert
with Chromium's 4-week release schedule. For example, Electron 26 uses Chromium 116, while Electron 27 uses Chromium 118.
### Node.js version support
Electron upgrades its `main` branch to even-number versions of Node.js when they enter Active LTS. The schedule
is as follows:
<img src="https://raw.githubusercontent.com/nodejs/Release/main/schedule.svg?sanitize=true" alt="Releases">
As a rule, stable branches of Electron do not receive Node.js upgrades after they have been cut.
If Electron has recently updated its `main` branch to a new major version of Node.js, the next stable
branch to be cut will be released with the new version.
Patch upgrades of Node that contain significant security or bug fixes, and are submitted
more than 2 weeks prior to a stable release date, will be accepted into an Electron alpha
or beta release branch.
Minor upgrades of Node that contain significant security or bug fixes, and are submitted
more than 2 weeks prior to a stable release date may be accepted into an Electron alpha or
beta release branch on a case-by-case basis. These requests will be reviewed and voted on
by the [Releases Working Group](https://github.com/electron/governance/tree/main/wg-releases),
to ensure minimal disruption for developers who may be consuming alpha or beta releases.
### Breaking API changes
When an API is changed or removed in a way that breaks existing functionality, the

View File

@@ -0,0 +1,38 @@
# ESM Limitations
This document serves to outline the limitations / differences between ESM in Electron and ESM in Node.js and Chromium.
## ESM Support Matrix
This table gives a general overview of where ESM is supported and most importantly which ESM loader is used.
| | Supported | Loader | Supported in Preload | Loader in Preload | Applicable Requirements |
|-|-|-|-|-|-|
| Main Process | Yes | Node.js | N/A | N/A | <ul><li> [You must `await` generously in the main process to avoid race conditions](#you-must-use-await-generously-in-the-main-process-to-avoid-race-conditions) </li></ul> |
| Sandboxed Renderer | Yes | Chromium | No | | <ul><li> [Sandboxed preload scripts can't use ESM imports](#sandboxed-preload-scripts-cant-use-esm-imports) </li></ul> |
| Node.js Renderer + Context Isolation | Yes | Chromium | Yes | Node.js | <ul><li> [Node.js ESM Preload Scripts will run after page load on pages with no content](#nodejs-esm-preload-scripts-will-run-after-page-load-on-pages-with-no-content) </li> <li>[ESM Preload Scripts must have the `.mjs` extension](#esm-preload-scripts-must-have-the-mjs-extension)</li></ul> |
| Node.js Renderer + No Context Isolation | Yes | Chromium | Yes | Node.js | <ul><li> [Non-context-isolated renderers can't use dynamic Node.js ESM imports](#non-context-isolated-renderers-cant-use-dynamic-nodejs-esm-imports) </li> <li>[ESM Preload Scripts must have the `.mjs` extension](#esm-preload-scripts-must-have-the-mjs-extension)</li></ul> |
## Requirements
### You must use `await` generously in the main process to avoid race conditions
Certain APIs in Electron (`app.setPath` for instance) are documented as needing to be called **before** the `app.on('ready')` event is emitted. When using ESM in the main process it is only guaranteed that the `ready` event hasn't been emitted while executing the side-effects of the primary import. i.e. if `index.mjs` calls `import('./set-up-paths.mjs')` at the top level the app will likely already be "ready" by the time that dynamic import resolves. To avoid this you should `await import('./set-up-paths.mjs')` at the top level of `index.mjs`. It's not just import calls you should await, if you are reading files asynchronously or performing other asynchronous actions you must await those at the top-level as well to ensure the app does not resume initialization and become ready too early.
### Sandboxed preload scripts can't use ESM imports
Sandboxed preload scripts are run as plain javascript without an ESM context. It is recommended that preload scripts are bundled via something like `webpack` or `vite` for performance reasons regardless, so your preload script should just be a single file that doesn't need to use ESM imports. Loading the `electron` API is still done via `require('electron')`.
### Node.js ESM Preload Scripts will run after page load on pages with no content
If the response body for the page is **completely** empty, i.e. `Content-Length: 0`, the preload script will not block the page load, which may result in race conditions. If this impacts you, change your response body to have _something_ in it, for example an empty `html` tag (`<html></html>`) or swap back to using a CommonJS preload script (`.js` or `.cjs`) which will block the page load.
### ESM Preload Scripts must have the `.mjs` extension
In order to load an ESM preload script it must have a `.mjs` file extension. Using `type: module` in a nearby package.json is not sufficient. Please also note the limitation above around not blocking page load if the page is empty.
### Non-context-isolated renderers can't use dynamic Node.js ESM imports
If your renderer process does not have `contextIsolation` enabled you can not `import()` ESM files via the Node.js module loader. This means that you can't `import('fs')` or `import('./foo')`. If you want to be able to do so you must enable context isolation. This is because in the renderer Chromium's `import()` function takes precedence and without context isolation there is no way for Electron to know which loader to route the request to.
If you enable context isolation `import()` from the isolated preload context will use the Node.js loader and `import()` from the main context will continue using Chromium's loader.

View File

@@ -1,172 +0,0 @@
---
title: "ES Modules (ESM) in Electron"
description: "The ES module (ESM) format is the standard way of loading JavaScript packages."
slug: esm
hide_title: false
---
# ES Modules (ESM) in Electron
## Introduction
The ECMAScript module (ESM) format is [the standard way of loading JavaScript packages](https://tc39.es/ecma262/#sec-modules).
Chromium and Node.js have their own implementations of the ESM specification, and Electron
chooses which module loader to use depending on the context.
This document serves to outline the limitations of ESM in Electron and the differences between
ESM in Electron and ESM in Node.js and Chromium.
:::info
This feature was added in `electron@28.0.0`.
:::
## Summary: ESM support matrix
This table gives a general overview of where ESM is supported and which ESM loader is used.
| Process | ESM Loader | ESM Loader in Preload | Applicable Requirements |
|----------------------|------------|-----------------------|-------------------------|
| Main | Node.js | N/A | <ul><li> [You must use `await` generously before the app's `ready` event](#you-must-use-await-generously-before-the-apps-ready-event) </li></ul> |
| Renderer (Sandboxed) | Chromium | Unsupported | <ul><li> [Sandboxed preload scripts can't use ESM imports](#sandboxed-preload-scripts-cant-use-esm-imports) </li></ul> |
| Renderer (Unsandboxed & Context Isolated) | Chromium | Node.js | <ul><li> [Unsandboxed ESM preload scripts will run after page load on pages with no content](#unsandboxed-esm-preload-scripts-will-run-after-page-load-on-pages-with-no-content) </li> <li>[ESM Preload Scripts must have the `.mjs` extension](#esm-preload-scripts-must-have-the-mjs-extension)</li></ul> |
| Renderer (Unsandboxed & Non Context Isolated) | Chromium | Node.js | <ul><li>[Unsandboxed ESM preload scripts will run after page load on pages with no content](#unsandboxed-esm-preload-scripts-will-run-after-page-load-on-pages-with-no-content)</li><li>[ESM Preload Scripts must have the `.mjs` extension](#esm-preload-scripts-must-have-the-mjs-extension)</li><li>[ESM preload scripts must be context isolated to use dynamic Node.js ESM imports](#esm-preload-scripts-must-be-context-isolated-to-use-dynamic-nodejs-esm-imports)</li></ul> |
## Main process
Electron's main process runs in a Node.js context and uses its ESM loader. Usage should follow
[Node's ESM documentation](https://nodejs.org/api/esm.html). To enable ESM in a file in the
main process, one of the following conditions must be met:
- The file ends with the `.mjs` extension
- The nearest parent package.json has `"type": "module"` set
See Node's [Determining Module System](https://nodejs.org/api/packages.html#determining-module-system)
doc for more details.
### Caveats
#### You must use `await` generously before the app's `ready` event
ES Modules are loaded **asynchronously**. This means that only side effects
from the main process entry point's imports will execute before the `ready` event.
This is important because certain Electron APIs (e.g. [`app.setPath`](../api/app.md#appsetpathname-path))
need to be called **before** the app's `ready` event is emitted.
With top-level `await` available in Node.js ESM, make sure to `await` every Promise that you need to
execute before the `ready` event. Otherwise, your app may be `ready` before your code executes.
This is particularly important to keep in mind for dynamic ESM import statmements (static imports are unaffected).
For example, if `index.mjs` calls `import('./set-up-paths.mjs')` at the top level, the app will
likely already be `ready` by the time that dynamic import resolves.
```js @ts-expect-error=[2] title='index.mjs (Main Process)'
// add an await call here to guarantee that path setup will finish before `ready`
import('./set-up-paths.mjs')
app.whenReady().then(() => {
console.log('This code may execute before the above import')
})
```
:::caution Transpiler translations
JavaScript transpilers (e.g. Babel, TypeScript) have historically supported ES Module
syntax before Node.js supported ESM imports by turning these calls to CommonJS
`require` calls.
<details><summary>Example: @babel/plugin-transform-modules-commonjs</summary>
The `@babel/plugin-transform-modules-commonjs` plugin will transform
ESM imports down to `require` calls. The exact syntax will depend on the
[`importInterop` setting](https://babeljs.io/docs/babel-plugin-transform-modules-commonjs#importinterop).
```js @nolint @ts-nocheck title='@babel/plugin-transform-modules-commonjs'
import foo from "foo";
import { bar } from "bar";
foo;
bar;
// with "importInterop: node", compiles to ...
"use strict";
var _foo = require("foo");
var _bar = require("bar");
_foo;
_bar.bar;
```
</details>
These CommonJS calls load module code synchronously. If you are migrating transpiled CJS code
to native ESM, be careful about the timing differences between CJS and ESM.
:::
## Renderer process
Electron's renderer processes run in a Chromium context and will use Chromium's ESM loader.
In practice, this means that `import` statements:
- will not have access to Node.js built-in modules
- will not be able to load npm packages from `node_modules`
```html
<script type="module">
import { exists } from 'node:fs' // ❌ will not work!
</script>
```
If you wish to load JavaScript packages via npm directly into the renderer process, we recommend
using a bundler such as webpack or Vite to compile your code for client-side consumption.
## Preload scripts
A renderer's preload script will use the Node.js ESM loader _when available_.
ESM availability will depend on the values of its renderer's `sandbox` and `contextIsolation`
preferences, and comes with a few other caveats due to the asynchronous nature of ESM loading.
### Caveats
#### ESM preload scripts must have the `.mjs` extension
Preload scripts will ignore `"type": "module"` fields, so you _must_ use the `.mjs` file
extension in your ESM preload scripts.
#### Sandboxed preload scripts can't use ESM imports
Sandboxed preload scripts are run as plain JavaScript without an ESM context. If you need to
use external modules, we recommend using a bundler for your preload code. Loading the
`electron` API is still done via `require('electron')`.
For more information on sandboxing, see the [Process Sandboxing](./sandbox.md) docs.
#### Unsandboxed ESM preload scripts will run after page load on pages with no content
If the response body for a renderer's loaded page is _completely_ empty (i.e. `Content-Length: 0`),
its preload script will not block the page load, which may result in race conditions.
If this impacts you, change your response body to have _something_ in it
(e.g. an empty `html` tag (`<html></html>`)) or swap back to using a CommonJS preload script
(`.js` or `.cjs`), which will block the page load.
### ESM preload scripts must be context isolated to use dynamic Node.js ESM imports
If your unsandboxed renderer process does not have the `contextIsolation` flag enabled,
you cannot dynamically `import()` files via Node's ESM loader.
```js @ts-nocheck title='preload.mjs'
// ❌ these won't work without context isolation
const fs = await import('node:fs')
await import('./foo')
```
This is because Chromium's dynamic ESM `import()` function usually takes precedence in the
renderer process and without context isolation, there is no way of knowing if Node.js is available
in a dynamic import statement. If you enable context isolation, `import()` statements
from the renderer's isolated preload context can be routed to the Node.js module loader.

View File

@@ -16,7 +16,16 @@ Once Fiddle is installed, you can press on the "Open in Fiddle" button that you
will find below code samples like the following one:
```fiddle docs/fiddles/quick-start
window.addEventListener('DOMContentLoaded', () => {
const replaceText = (selector, text) => {
const element = document.getElementById(selector)
if (element) element.innerText = text
}
for (const type of ['chrome', 'node', 'electron']) {
replaceText(`${type}-version`, process.versions[type])
}
})
```
If there is still something that you do not know how to do, please take a look at the [API][app]

View File

@@ -34,7 +34,7 @@ To test In-App Purchase in development with Electron you'll have to change the `
Here is an example that shows how to use In-App Purchases in Electron. You'll have to replace the product ids by the identifiers of the products created with iTunes Connect (the identifier of `com.example.app.product1` is `product1`). Note that you have to listen to the `transactions-updated` event as soon as possible in your app.
```js
```javascript
// Main process
const { inAppPurchase } = require('electron')
const PRODUCT_IDS = ['id1', 'id2']

View File

@@ -66,7 +66,7 @@ You can use environment variables to override the base URL, the path at which to
look for Electron binaries, and the binary filename. The URL used by `@electron/get`
is composed as follows:
```js @ts-nocheck
```javascript @ts-nocheck
url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME
```

View File

@@ -50,7 +50,7 @@ sections.
In the main process, set an IPC listener on the `set-title` channel with the `ipcMain.on` API:
```js {6-10,22} title='main.js (Main Process)'
```javascript {6-10,22} title='main.js (Main Process)'
const { app, BrowserWindow, ipcMain } = require('electron')
const path = require('node:path')
@@ -96,7 +96,7 @@ you need to choose which APIs to expose from your preload script using the `cont
In your preload script, add the following code, which will expose a global `window.electronAPI`
variable to your renderer process.
```js title='preload.js (Preload Script)'
```javascript title='preload.js (Preload Script)'
const { contextBridge, ipcRenderer } = require('electron')
contextBridge.exposeInMainWorld('electronAPI', {
@@ -138,7 +138,7 @@ To make these elements interactive, we'll be adding a few lines of code in the i
`renderer.js` file that leverages the `window.electronAPI` functionality exposed from the preload
script:
```js title='renderer.js (Renderer Process)' @ts-expect-error=[4,5]
```javascript title='renderer.js (Renderer Process)' @ts-expect-error=[4,5]
const setButton = document.getElementById('btn')
const titleInput = document.getElementById('title')
setButton.addEventListener('click', () => {
@@ -181,7 +181,7 @@ provided to the renderer process. Please refer to
[#24427](https://github.com/electron/electron/issues/24427) for details.
:::
```js {6-13,25} title='main.js (Main Process)'
```javascript {6-13,25} title='main.js (Main Process)'
const { app, BrowserWindow, dialog, ipcMain } = require('electron')
const path = require('node:path')
@@ -225,7 +225,7 @@ In the preload script, we expose a one-line `openFile` function that calls and r
`ipcRenderer.invoke('dialog:openFile')`. We'll be using this API in the next step to call the
native dialog from our renderer's user interface.
```js title='preload.js (Preload Script)'
```javascript title='preload.js (Preload Script)'
const { contextBridge, ipcRenderer } = require('electron')
contextBridge.exposeInMainWorld('electronAPI', {
@@ -263,7 +263,7 @@ The UI consists of a single `#btn` button element that will be used to trigger o
a `#filePath` element that will be used to display the path of the selected file. Making these
pieces work will take a few lines of code in the renderer process script:
```js title='renderer.js (Renderer Process)' @ts-expect-error=[5]
```javascript title='renderer.js (Renderer Process)' @ts-expect-error=[5]
const btn = document.getElementById('btn')
const filePathElement = document.getElementById('filePath')
@@ -299,7 +299,7 @@ The `ipcRenderer.send` API that we used for single-way communication can also be
perform two-way communication. This was the recommended way for asynchronous two-way communication
via IPC prior to Electron 7.
```js title='preload.js (Preload Script)'
```javascript title='preload.js (Preload Script)'
// You can also put expose this code to the renderer
// process with the `contextBridge` API
const { ipcRenderer } = require('electron')
@@ -310,7 +310,7 @@ ipcRenderer.on('asynchronous-reply', (_event, arg) => {
ipcRenderer.send('asynchronous-message', 'ping')
```
```js title='main.js (Main Process)'
```javascript title='main.js (Main Process)'
ipcMain.on('asynchronous-message', (event, arg) => {
console.log(arg) // prints "ping" in the Node console
// works like `send`, but returning a message back
@@ -332,7 +332,7 @@ channels, you would need to add additional app code to track each call and respo
The `ipcRenderer.sendSync` API sends a message to the main process and waits _synchronously_ for a
response.
```js title='main.js (Main Process)'
```javascript title='main.js (Main Process)'
const { ipcMain } = require('electron')
ipcMain.on('synchronous-message', (event, arg) => {
console.log(arg) // prints "ping" in the Node console
@@ -340,7 +340,7 @@ ipcMain.on('synchronous-message', (event, arg) => {
})
```
```js title='preload.js (Preload Script)'
```javascript title='preload.js (Preload Script)'
// You can also put expose this code to the renderer
// process with the `contextBridge` API
const { ipcRenderer } = require('electron')
@@ -376,7 +376,7 @@ For this demo, we'll need to first build a custom menu in the main process using
module that uses the `webContents.send` API to send an IPC message from the main process to the
target renderer.
```js {11-26} title='main.js (Main Process)'
```javascript {11-26} title='main.js (Main Process)'
const { app, BrowserWindow, Menu, ipcMain } = require('electron')
const path = require('node:path')
@@ -412,7 +412,7 @@ function createWindow () {
For the purposes of the tutorial, it's important to note that the `click` handler
sends a message (either `1` or `-1`) to the renderer process through the `update-counter` channel.
```js @ts-type={mainWindow:Electron.BrowserWindow}
```javascript @ts-type={mainWindow:Electron.BrowserWindow}
click: () => mainWindow.webContents.send('update-counter', -1)
```
@@ -425,11 +425,11 @@ Make sure you're loading the `index.html` and `preload.js` entry points for the
Like in the previous renderer-to-main example, we use the `contextBridge` and `ipcRenderer`
modules in the preload script to expose IPC functionality to the renderer process:
```js title='preload.js (Preload Script)'
```javascript title='preload.js (Preload Script)'
const { contextBridge, ipcRenderer } = require('electron')
contextBridge.exposeInMainWorld('electronAPI', {
onUpdateCounter: (callback) => ipcRenderer.on('update-counter', (_event, value) => callback(value))
onUpdateCounter: (callback) => ipcRenderer.on('update-counter', callback)
})
```
@@ -439,15 +439,13 @@ After loading the preload script, your renderer process should have access to th
:::caution Security warning
We don't directly expose the whole `ipcRenderer.on` API for [security reasons][]. Make sure to
limit the renderer's access to Electron APIs as much as possible.
Also don't just pass the callback to `ipcRenderer.on` as this will leak `ipcRenderer` via `event.sender`.
Use a custom handler that invoke the `callback` only with the desired arguments.
:::
:::info
In the case of this minimal example, you can call `ipcRenderer.on` directly in the preload script
rather than exposing it over the context bridge.
```js title='preload.js (Preload Script)'
```javascript title='preload.js (Preload Script)'
const { ipcRenderer } = require('electron')
window.addEventListener('DOMContentLoaded', () => {
@@ -488,10 +486,10 @@ To tie it all together, we'll create an interface in the loaded HTML file that c
Finally, to make the values update in the HTML document, we'll add a few lines of DOM manipulation
so that the value of the `#counter` element is updated whenever we fire an `update-counter` event.
```js title='renderer.js (Renderer Process)' @ts-window-type={electronAPI:{onUpdateCounter:(callback:(value:number)=>void)=>void}}
```javascript title='renderer.js (Renderer Process)' @ts-window-type={electronAPI:{onUpdateCounter:(callback:(event:Electron.IpcRendererEvent,value:number)=>void)=>void}}
const counter = document.getElementById('counter')
window.electronAPI.onUpdateCounter((value) => {
window.electronAPI.onUpdateCounter((_event, value) => {
const oldValue = Number(counter.innerText)
const newValue = oldValue + value
counter.innerText = newValue.toString()
@@ -508,32 +506,23 @@ There's no equivalent for `ipcRenderer.invoke` for main-to-renderer IPC. Instead
send a reply back to the main process from within the `ipcRenderer.on` callback.
We can demonstrate this with slight modifications to the code from the previous example. In the
renderer process, expose another API to send a reply back to the main process through the
renderer process, use the `event` parameter to send a reply back to the main process through the
`counter-value` channel.
```js title='preload.js (Preload Script)'
const { contextBridge, ipcRenderer } = require('electron')
contextBridge.exposeInMainWorld('electronAPI', {
onUpdateCounter: (callback) => ipcRenderer.on('update-counter', (_event, value) => callback(value)),
counterValue: (value) => ipcRenderer.send('counter-value', value)
})
```
```js title='renderer.js (Renderer Process)' @ts-window-type={electronAPI:{onUpdateCounter:(callback:(value:number)=>void)=>void,counterValue:(value:number)=>void}}
```javascript title='renderer.js (Renderer Process)' @ts-window-type={electronAPI:{onUpdateCounter:(callback:(event:Electron.IpcRendererEvent,value:number)=>void)=>void}}
const counter = document.getElementById('counter')
window.electronAPI.onUpdateCounter((value) => {
window.electronAPI.onUpdateCounter((event, value) => {
const oldValue = Number(counter.innerText)
const newValue = oldValue + value
counter.innerText = newValue.toString()
window.electronAPI.counterValue(newValue)
event.sender.send('counter-value', newValue)
})
```
In the main process, listen for `counter-value` events and handle them appropriately.
```js title='main.js (Main Process)'
```javascript title='main.js (Main Process)'
// ...
ipcMain.on('counter-value', (_event, value) => {
console.log(value) // will print value to Node console

View File

@@ -14,19 +14,11 @@ To configure a local keyboard shortcut, you need to specify an [`accelerator`][]
property when creating a [MenuItem][] within the [Menu][] module.
Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` to be:
[Quick Start Guide](quick-start.md), update the `main.js` file with the
following lines:
```fiddle docs/fiddles/features/keyboard-shortcuts/local
const { app, BrowserWindow, Menu, MenuItem } = require('electron/main')
function createWindow () {
const win = new BrowserWindow({
width: 800,
height: 600
})
win.loadFile('index.html')
}
```javascript fiddle='docs/fiddles/features/keyboard-shortcuts/local'
const { Menu, MenuItem } = require('electron')
const menu = new Menu()
menu.append(new MenuItem({
@@ -39,20 +31,6 @@ menu.append(new MenuItem({
}))
Menu.setApplicationMenu(menu)
app.whenReady().then(createWindow)
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') {
app.quit()
}
})
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) {
createWindow()
}
})
```
> NOTE: In the code above, you can see that the accelerator differs based on the
@@ -75,37 +53,17 @@ module to detect keyboard events even when the application does not have
keyboard focus.
Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` to be:
[Quick Start Guide](quick-start.md), update the `main.js` file with the
following lines:
```fiddle docs/fiddles/features/keyboard-shortcuts/global
const { app, BrowserWindow, globalShortcut } = require('electron/main')
function createWindow () {
const win = new BrowserWindow({
width: 800,
height: 600
})
win.loadFile('index.html')
}
```javascript fiddle='docs/fiddles/features/keyboard-shortcuts/global' @ts-type={createWindow:()=>void}
const { app, globalShortcut } = require('electron')
app.whenReady().then(() => {
globalShortcut.register('Alt+CommandOrControl+I', () => {
console.log('Electron loves global shortcuts!')
})
}).then(createWindow)
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') {
app.quit()
}
})
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) {
createWindow()
}
})
```
> NOTE: In the code above, the `CommandOrControl` combination uses `Command`
@@ -123,8 +81,8 @@ If you want to handle keyboard shortcuts within a [BrowserWindow][], you can
listen for the `keyup` and `keydown` [DOM events][dom-events] inside the
renderer process using the [addEventListener() API][addEventListener-api].
```fiddle docs/fiddles/features/keyboard-shortcuts/web-apis|focus=renderer.js
function handleKeyPress (event) {
```javascript fiddle='docs/fiddles/features/keyboard-shortcuts/web-apis|focus=renderer.js'
const handleKeyPress = (event) => {
// You can put code here to handle the keypress.
document.getElementById('last-keypress').innerText = event.key
console.log(`You pressed ${event.key}`)
@@ -147,8 +105,8 @@ Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file with the
following lines:
```fiddle docs/fiddles/features/keyboard-shortcuts/interception-from-main
const { app, BrowserWindow } = require('electron/main')
```javascript fiddle='docs/fiddles/features/keyboard-shortcuts/interception-from-main'
const { app, BrowserWindow } = require('electron')
app.whenReady().then(() => {
const win = new BrowserWindow({ width: 800, height: 600 })

View File

@@ -25,14 +25,14 @@ we will use will be "`electron-fiddle://`".
First, we will import the required modules from `electron`. These modules help
control our application lifecycle and create a native browser window.
```js
```javascript
const { app, BrowserWindow, shell } = require('electron')
const path = require('node:path')
```
Next, we will proceed to register our application to handle all "`electron-fiddle://`" protocols.
```js
```javascript
if (process.defaultApp) {
if (process.argv.length >= 2) {
app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])
@@ -44,7 +44,7 @@ if (process.defaultApp) {
We will now define the function in charge of creating our browser window and load our application's `index.html` file.
```js
```javascript
let mainWindow
const createWindow = () => {
@@ -67,7 +67,7 @@ This code will be different in Windows and Linux compared to MacOS. This is due
#### Windows and Linux code:
```js @ts-type={mainWindow:Electron.BrowserWindow} @ts-type={createWindow:()=>void}
```javascript @ts-type={mainWindow:Electron.BrowserWindow} @ts-type={createWindow:()=>void}
const gotTheLock = app.requestSingleInstanceLock()
if (!gotTheLock) {
@@ -92,7 +92,7 @@ if (!gotTheLock) {
#### MacOS code:
```js @ts-type={createWindow:()=>void}
```javascript @ts-type={createWindow:()=>void}
// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
@@ -108,7 +108,7 @@ app.on('open-url', (event, url) => {
Finally, we will add some additional code to handle when someone closes our application.
```js
```javascript
// Quit when all windows are closed, except on macOS. There, it's common
// for applications and their menu bar to stay active until the user quits
// explicitly with Cmd + Q.
@@ -159,7 +159,7 @@ shows the bare minimum needed to add the configuration changes)_:
}
```
#### [Electron Packager](https://github.com/electron/packager)
#### [Electron Packager](https://github.com/electron/electron-packager)
For macOS support:
@@ -167,8 +167,8 @@ If you're using Electron Packager's API, adding support for protocol handlers is
Electron Forge is handled, except
`protocols` is part of the Packager options passed to the `packager` function.
```js @ts-nocheck
const packager = require('@electron/packager')
```javascript @ts-nocheck
const packager = require('electron-packager')
packager({
// ...other options...

View File

@@ -23,10 +23,10 @@ To set your custom dock menu, you need to use the
[`app.dock.setMenu`](../api/dock.md#docksetmenumenu-macos) API,
which is only available on macOS.
```fiddle docs/fiddles/features/macos-dock-menu
const { app, BrowserWindow, Menu } = require('electron/main')
```javascript fiddle='docs/fiddles/features/macos-dock-menu'
const { app, BrowserWindow, Menu } = require('electron')
function createWindow () {
const createWindow = () => {
const win = new BrowserWindow({
width: 800,
height: 600

View File

@@ -365,7 +365,7 @@ window.onmessage = (event) => {
// process.
port.onmessage = (event) => {
console.log('from main process:', event.data)
port.postMessage(event.data.test * 2)
port.postMessage(event.data * 2)
}
}
}

View File

@@ -9,7 +9,7 @@ It is possible to use Node.js features in Electron's Web Workers, to do
so the `nodeIntegrationInWorker` option should be set to `true` in
`webPreferences`.
```js
```javascript
const win = new BrowserWindow({
webPreferences: {
nodeIntegrationInWorker: true
@@ -42,7 +42,7 @@ safe.
The only way to load a native module safely for now, is to make sure the app
loads no native modules after the Web Workers get started.
```js @ts-expect-error=[1]
```javascript @ts-expect-error=[1]
process.dlopen = () => {
throw new Error('Load native module is not safe')
}

View File

@@ -44,7 +44,7 @@ Add a draggable element to `index.html`, and reference your renderer script:
In `renderer.js` set up the renderer process to handle drag events by calling the method you added via the [`contextBridge`][] above.
```js @ts-expect-error=[3]
```javascript @ts-expect-error=[3]
document.getElementById('drag').ondragstart = (event) => {
event.preventDefault()
window.electron.startDrag('drag-and-drop.md')
@@ -56,55 +56,15 @@ document.getElementById('drag').ondragstart = (event) => {
In the Main process (`main.js` file), expand the received event with a path to the file that is
being dragged and an icon:
```fiddle docs/fiddles/features/drag-and-drop
const { app, BrowserWindow, ipcMain } = require('electron/main')
const path = require('node:path')
const fs = require('node:fs')
const https = require('node:https')
function createWindow () {
const win = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
preload: path.join(__dirname, 'preload.js')
}
})
win.loadFile('index.html')
}
const iconName = path.join(__dirname, 'iconForDragAndDrop.png')
const icon = fs.createWriteStream(iconName)
// Create a new file to copy - you can also copy existing files.
fs.writeFileSync(path.join(__dirname, 'drag-and-drop-1.md'), '# First file to test drag and drop')
fs.writeFileSync(path.join(__dirname, 'drag-and-drop-2.md'), '# Second file to test drag and drop')
https.get('https://img.icons8.com/ios/452/drag-and-drop.png', (response) => {
response.pipe(icon)
})
app.whenReady().then(createWindow)
```javascript fiddle='docs/fiddles/features/drag-and-drop'
const { ipcMain } = require('electron')
ipcMain.on('ondragstart', (event, filePath) => {
event.sender.startDrag({
file: path.join(__dirname, filePath),
icon: iconName
file: filePath,
icon: '/path/to/icon.png'
})
})
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') {
app.quit()
}
})
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) {
createWindow()
}
})
```
After launching the Electron application, try dragging and dropping

View File

@@ -30,38 +30,16 @@ new Notification({
Here's a full example that you can open with Electron Fiddle:
```fiddle docs/fiddles/features/notifications/main
const { app, BrowserWindow, Notification } = require('electron/main')
function createWindow () {
const win = new BrowserWindow({
width: 800,
height: 600
})
win.loadFile('index.html')
}
```javascript fiddle='docs/fiddles/features/notifications/main'
const { Notification } = require('electron')
const NOTIFICATION_TITLE = 'Basic Notification'
const NOTIFICATION_BODY = 'Notification from the Main process'
function showNotification () {
new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()
}
app.whenReady().then(createWindow).then(showNotification)
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') {
app.quit()
}
})
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) {
createWindow()
}
})
new Notification({
title: NOTIFICATION_TITLE,
body: NOTIFICATION_BODY
}).show()
```
### Show notifications in the renderer process
@@ -81,13 +59,14 @@ new Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY }).onclick =
Here's a full example that you can open with Electron Fiddle:
```fiddle docs/fiddles/features/notifications/renderer|focus=renderer.js
```javascript fiddle='docs/fiddles/features/notifications/renderer'
const NOTIFICATION_TITLE = 'Title'
const NOTIFICATION_BODY = 'Notification from the Renderer process. Click to log to console.'
const CLICK_MESSAGE = 'Notification clicked!'
const NOTIFICATION_BODY =
'Notification from the Renderer process. Click to log to console.'
const CLICK_MESSAGE = 'Notification clicked'
new window.Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY })
.onclick = () => { document.getElementById('output').innerText = CLICK_MESSAGE }
new Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY }).onclick =
() => console.log(CLICK_MESSAGE)
```
## Platform considerations

View File

@@ -39,44 +39,22 @@ To enable this mode, GPU acceleration has to be disabled by calling the
## Example
```fiddle docs/fiddles/features/offscreen-rendering
const { app, BrowserWindow } = require('electron/main')
```javascript fiddle='docs/fiddles/features/offscreen-rendering'
const { app, BrowserWindow } = require('electron')
const fs = require('node:fs')
const path = require('node:path')
app.disableHardwareAcceleration()
function createWindow () {
const win = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
offscreen: true
}
})
let win
app.whenReady().then(() => {
win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.loadURL('https://github.com')
win.webContents.on('paint', (event, dirty, image) => {
fs.writeFileSync('ex.png', image.toPNG())
})
win.webContents.setFrameRate(60)
console.log(`The screenshot has been successfully saved to ${path.join(process.cwd(), 'ex.png')}`)
}
app.whenReady().then(() => {
createWindow()
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) {
createWindow()
}
})
})
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') {
app.quit()
}
})
```

Some files were not shown because too many files have changed in this diff Show More