chore: type check JS in docs (#38600)

This commit is contained in:
David Sanders
2023-06-06 16:14:07 +08:00
committed by GitHub
parent bd0e65292f
commit 4845dd7a71
49 changed files with 284 additions and 348 deletions

View File

@@ -960,7 +960,7 @@ app.setJumpList([
title: 'Tool A',
program: process.execPath,
args: '--run-tool-a',
icon: process.execPath,
iconPath: process.execPath,
iconIndex: 0,
description: 'Runs Tool A'
},
@@ -969,7 +969,7 @@ app.setJumpList([
title: 'Tool B',
program: process.execPath,
args: '--run-tool-b',
icon: process.execPath,
iconPath: process.execPath,
iconIndex: 0,
description: 'Runs Tool B'
}
@@ -1407,8 +1407,8 @@ const fs = require('fs')
let filepath
let bookmark
dialog.showOpenDialog(null, { securityScopedBookmarks: true }, (filepaths, bookmarks) => {
filepath = filepaths[0]
dialog.showOpenDialog(null, { securityScopedBookmarks: true }).then(({ filePaths, bookmarks }) => {
filepath = filePaths[0]
bookmark = bookmarks[0]
fs.readFileSync(filepath)
})

View File

@@ -104,6 +104,7 @@ window, you have to set both `parent` and `modal` options:
```javascript
const { BrowserWindow } = require('electron')
const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top, modal: true, show: false })
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
@@ -887,7 +888,7 @@ On Linux the setter is a no-op, although the getter returns `true`.
A `boolean` property that determines whether the window is excluded from the applications Windows menu. `false` by default.
```js
```js @ts-expect-error=[11]
const win = new BrowserWindow({ height: 600, width: 600 })
const template = [
@@ -1490,6 +1491,9 @@ Node's [`url.format`](https://nodejs.org/api/url.html#url_url_format_urlobject)
method:
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
const url = require('url').format({
protocol: 'file',
slashes: true,
@@ -1503,6 +1507,9 @@ You can load a URL using a `POST` request with URL-encoded data by doing
the following:
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.loadURL('http://localhost:8000/post', {
postData: [{
type: 'rawData',

View File

@@ -95,7 +95,7 @@ The `callback` function is expected to be called back with user credentials:
* `username` string
* `password` string
```javascript
```javascript @ts-type={request:Electron.ClientRequest}
request.on('login', (authInfo, callback) => {
callback('username', 'password')
})
@@ -104,7 +104,7 @@ request.on('login', (authInfo, callback) => {
Providing empty credentials will cancel the request and report an authentication
error on the response object:
```javascript
```javascript @ts-type={request:Electron.ClientRequest}
request.on('response', (response) => {
console.log(`STATUS: ${response.statusCode}`)
response.on('error', (error) => {

View File

@@ -148,10 +148,7 @@ clipboard.
```js
const { clipboard } = require('electron')
clipboard.writeBookmark({
text: 'https://electronjs.org',
bookmark: 'Electron Homepage'
})
clipboard.writeBookmark('Electron Homepage', 'https://electronjs.org')
```
### `clipboard.readFindText()` _macOS_
@@ -226,7 +223,7 @@ clipboard.writeBuffer('public/utf8-plain-text', buffer)
const ret = clipboard.readBuffer('public/utf8-plain-text')
console.log(buffer.equals(out))
console.log(buffer.equals(ret))
// true
```

View File

@@ -18,7 +18,7 @@ contextBridge.exposeInMainWorld(
)
```
```javascript
```javascript @ts-nocheck
// Renderer (Main World)
window.electron.doThing()
@@ -104,7 +104,7 @@ contextBridge.exposeInIsolatedWorld(
)
```
```javascript
```javascript @ts-nocheck
// Renderer (In isolated world id1004)
window.electron.doThing()

View File

@@ -10,7 +10,9 @@ title is `Electron`:
```javascript
// In the main process.
const { desktopCapturer } = require('electron')
const { BrowserWindow, desktopCapturer } = require('electron')
const mainWindow = new BrowserWindow()
desktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources => {
for (const source of sources) {
@@ -22,7 +24,7 @@ desktopCapturer.getSources({ types: ['window', 'screen'] }).then(async sources =
})
```
```javascript
```javascript @ts-nocheck
// In the preload script.
const { ipcRenderer } = require('electron')

View File

@@ -72,7 +72,7 @@ and a directory selector, so if you set `properties` to
`['openFile', 'openDirectory']` on these platforms, a directory selector will be
shown.
```js
```js @ts-type={mainWindow:Electron.BrowserWindow}
dialog.showOpenDialogSync(mainWindow, {
properties: ['openFile', 'openDirectory']
})
@@ -139,7 +139,7 @@ and a directory selector, so if you set `properties` to
`['openFile', 'openDirectory']` on these platforms, a directory selector will be
shown.
```js
```js @ts-type={mainWindow:Electron.BrowserWindow}
dialog.showOpenDialog(mainWindow, {
properties: ['openFile', 'openDirectory']
}).then(result => {

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.
```javascript
```javascript @ts-type={response:Electron.IncomingMessage}
// Prints something like:
//
// [ 'user-agent',
@@ -100,5 +100,5 @@ duplicates are not merged.
// '127.0.0.1:8000',
// 'ACCEPT',
// '*/*' ]
console.log(request.rawHeaders)
console.log(response.rawHeaders)
```

View File

@@ -83,14 +83,14 @@ If `listener` returns a Promise, the eventual result of the promise will be
returned as a reply to the remote caller. Otherwise, the return value of the
listener will be used as the value of the reply.
```js title='Main Process'
```js title='Main Process' @ts-type={somePromise:(...args:unknown[])=>Promise<unknown>}
ipcMain.handle('my-invokable-ipc', async (event, ...args) => {
const result = await somePromise(...args)
return result
})
```
```js title='Renderer Process'
```js title='Renderer Process' @ts-type={arg1:unknown} @ts-type={arg2:unknown}
async () => {
const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)
// ...

View File

@@ -101,7 +101,7 @@ The main process should listen for `channel` with
For example:
```javascript
```javascript @ts-type={someArgument:unknown} @ts-type={doSomeWork:(arg:unknown)=>Promise<unknown>}
// Renderer process
ipcRenderer.invoke('some-name', someArgument).then((result) => {
// ...

View File

@@ -147,7 +147,7 @@ can have a submenu.
An example of creating the application menu with the simple template API:
```javascript
```javascript @ts-expect-error=[107]
const { app, Menu } = require('electron')
const isMac = process.platform === 'darwin'
@@ -267,7 +267,7 @@ menu on behalf of the renderer.
Below is an example of showing a menu when the user right clicks the page:
```js
```js @ts-expect-error=[21]
// renderer
window.addEventListener('contextmenu', (e) => {
e.preventDefault()
@@ -289,7 +289,7 @@ ipcMain.on('show-context-menu', (event) => {
{ label: 'Menu Item 2', type: 'checkbox', checked: true }
]
const menu = Menu.buildFromTemplate(template)
menu.popup(BrowserWindow.fromWebContents(event.sender))
menu.popup({ window: BrowserWindow.fromWebContents(event.sender) })
})
```

View File

@@ -17,7 +17,8 @@ Example:
```js
// Main process
const { MessageChannelMain } = require('electron')
const { BrowserWindow, MessageChannelMain } = require('electron')
const w = new BrowserWindow()
const { port1, port2 } = new MessageChannelMain()
w.webContents.postMessage('port', null, [port2])
port1.postMessage({ some: 'message' })
@@ -26,9 +27,9 @@ port1.postMessage({ some: 'message' })
const { ipcRenderer } = require('electron')
ipcRenderer.on('port', (e) => {
// e.ports is a list of ports sent along with this message
e.ports[0].on('message', (messageEvent) => {
e.ports[0].onmessage = (messageEvent) => {
console.log(messageEvent.data)
})
}
})
```

View File

@@ -5,7 +5,7 @@
Process: [Main](../glossary.md#main-process)
```javascript
const { netLog } = require('electron')
const { app, netLog } = require('electron')
app.whenReady().then(async () => {
await netLog.startLogging('/path/to/net-log')

View File

@@ -36,7 +36,7 @@ To have your custom protocol work in combination with a custom session, you need
to register it to that session explicitly.
```javascript
const { session, app, protocol } = require('electron')
const { app, BrowserWindow, net, protocol, session } = require('electron')
const path = require('path')
app.whenReady().then(() => {
@@ -48,7 +48,7 @@ app.whenReady().then(() => {
callback({ path: path.normalize(path.join(__dirname, url)) })
})
mainWindow = new BrowserWindow({ webPreferences: { partition } })
const mainWindow = new BrowserWindow({ webPreferences: { partition } })
})
```

View File

@@ -82,7 +82,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.
```javascript
```javascript @ts-expect-error=[4]
const { session } = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
event.preventDefault()
@@ -198,7 +198,7 @@ cancel the request. Additionally, permissioning on `navigator.hid` can
be further managed by using [`ses.setPermissionCheckHandler(handler)`](#sessetpermissioncheckhandlerhandler)
and [`ses.setDevicePermissionHandler(handler)`](#sessetdevicepermissionhandlerhandler).
```javascript
```javascript @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)}
const { app, BrowserWindow } = require('electron')
let win = null
@@ -237,7 +237,7 @@ app.whenReady().then(() => {
win.webContents.session.on('select-hid-device', (event, details, callback) => {
event.preventDefault()
const selectedDevice = details.deviceList.find((device) => {
return device.vendorId === '9025' && device.productId === '67'
return device.vendorId === 9025 && device.productId === 67
})
callback(selectedDevice?.deviceId)
})
@@ -304,7 +304,7 @@ cancel the request. Additionally, permissioning on `navigator.serial` can
be managed by using [ses.setPermissionCheckHandler(handler)](#sessetpermissioncheckhandlerhandler)
with the `serial` permission.
```javascript
```javascript @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)}
const { app, BrowserWindow } = require('electron')
let win = null
@@ -447,7 +447,7 @@ cancel the request. Additionally, permissioning on `navigator.usb` can
be further managed by using [`ses.setPermissionCheckHandler(handler)`](#sessetpermissioncheckhandlerhandler)
and [`ses.setDevicePermissionHandler(handler)`](#sessetdevicepermissionhandlerhandler).
```javascript
```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
@@ -486,7 +486,7 @@ app.whenReady().then(() => {
win.webContents.session.on('select-usb-device', (event, details, callback) => {
event.preventDefault()
const selectedDevice = details.deviceList.find((device) => {
return device.vendorId === '9025' && device.productId === '67'
return device.vendorId === 9025 && device.productId === 67
})
if (selectedDevice) {
// Optionally, add this to the persisted devices (updateGrantedDevices needs to be implemented by developer to persist permissions)
@@ -741,15 +741,17 @@ Sets download saving directory. By default, the download directory will be the
Emulates network with the given configuration for the `session`.
```javascript
const win = new BrowserWindow()
// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
window.webContents.session.enableNetworkEmulation({
win.webContents.session.enableNetworkEmulation({
latency: 500,
downloadThroughput: 6400,
uploadThroughput: 6400
})
// To emulate a network outage.
window.webContents.session.enableNetworkEmulation({ offline: true })
win.webContents.session.enableNetworkEmulation({ offline: true })
```
#### `ses.preconnect(options)`
@@ -967,7 +969,7 @@ Additionally, the default behavior of Electron is to store granted device permis
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`.
```javascript
```javascript @ts-type={fetchGrantedDevices:()=>(Array<Electron.DevicePermissionHandlerHandlerDetails['device']>)}
const { app, BrowserWindow } = require('electron')
let win = null
@@ -1015,9 +1017,9 @@ app.whenReady().then(() => {
win.webContents.session.on('select-hid-device', (event, details, callback) => {
event.preventDefault()
const selectedDevice = details.deviceList.find((device) => {
return device.vendorId === '9025' && device.productId === '67'
return device.vendorId === 9025 && device.productId === 67
})
callback(selectedPort?.deviceId)
callback(selectedDevice?.deviceId)
})
})
```
@@ -1105,32 +1107,32 @@ macOS does not require a handler because macOS handles the pairing
automatically. To clear the handler, call `setBluetoothPairingHandler(null)`.
```javascript
const { app, BrowserWindow, ipcMain, session } = require('electron')
let bluetoothPinCallback = null
const { app, BrowserWindow, session } = require('electron')
const path = require('path')
function createWindow () {
let bluetoothPinCallback = null
const mainWindow = new BrowserWindow({
webPreferences: {
preload: path.join(__dirname, 'preload.js')
}
})
mainWindow.webContents.session.setBluetoothPairingHandler((details, callback) => {
bluetoothPinCallback = callback
// Send a IPC message to the renderer to prompt the user to confirm the pairing.
// Note that this will require logic in the renderer to handle this message and
// display a prompt to the user.
mainWindow.webContents.send('bluetooth-pairing-request', details)
})
// Listen for an IPC message from the renderer to get the response for the Bluetooth pairing.
mainWindow.webContents.ipc.on('bluetooth-pairing-response', (event, response) => {
bluetoothPinCallback(response)
})
}
// Listen for an IPC message from the renderer to get the response for the Bluetooth pairing.
ipcMain.on('bluetooth-pairing-response', (event, response) => {
bluetoothPinCallback(response)
})
mainWindow.webContents.session.setBluetoothPairingHandler((details, callback) => {
bluetoothPinCallback = callback
// Send a IPC message to the renderer to prompt the user to confirm the pairing.
// Note that this will require logic in the renderer to handle this message and
// display a prompt to the user.
mainWindow.webContents.send('bluetooth-pairing-request', details)
})
app.whenReady().then(() => {
createWindow()
})

View File

@@ -87,12 +87,12 @@ const { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar
let spinning = false
// Reel labels
const reel1 = new TouchBarLabel()
const reel2 = new TouchBarLabel()
const reel3 = new TouchBarLabel()
const reel1 = new TouchBarLabel({ label: '' })
const reel2 = new TouchBarLabel({ label: '' })
const reel3 = new TouchBarLabel({ label: '' })
// Spin result label
const result = new TouchBarLabel()
const result = new TouchBarLabel({ label: '' })
// Spin button
const spin = new TouchBarButton({

View File

@@ -68,7 +68,7 @@ async function lookupTargetId (browserWindow) {
await wc.debugger.attach('1.3')
const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
const { targetId } = targetInfo
const targetWebContents = await webContents.fromDevToolsTargetId(targetId)
const targetWebContents = await wc.fromDevToolsTargetId(targetId)
}
```
@@ -906,9 +906,9 @@ e.g. the `http://` or `file://`. If the load should bypass http cache then
use the `pragma` header to achieve it.
```javascript
const { webContents } = require('electron')
const win = new BrowserWindow()
const options = { extraHeaders: 'pragma: no-cache\n' }
webContents.loadURL('https://github.com', options)
win.webContents.loadURL('https://github.com', options)
```
#### `contents.loadFile(filePath[, options])`
@@ -938,6 +938,7 @@ an app structure like this:
Would require code like this
```js
const win = new BrowserWindow()
win.loadFile('src/index.html')
```
@@ -1074,7 +1075,9 @@ when this process is unstable or unusable, for instance in order to recover
from the `unresponsive` event.
```js
contents.on('unresponsive', async () => {
const win = new BrowserWindow()
win.webContents.on('unresponsive', async () => {
const { response } = await dialog.showMessageBox({
message: 'App X has become unresponsive',
title: 'Do you want to try forcefully reloading the app?',
@@ -1082,8 +1085,8 @@ contents.on('unresponsive', async () => {
cancelId: 1
})
if (response === 0) {
contents.forcefullyCrashRenderer()
contents.reload()
win.webContents.forcefullyCrashRenderer()
win.webContents.reload()
}
})
```
@@ -1110,8 +1113,9 @@ Injects CSS into the current web page and returns a unique key for the inserted
stylesheet.
```js
contents.on('did-finish-load', () => {
contents.insertCSS('html, body { background-color: #f00; }')
const win = new BrowserWindow()
win.webContents.on('did-finish-load', () => {
win.webContents.insertCSS('html, body { background-color: #f00; }')
})
```
@@ -1125,9 +1129,11 @@ Removes the inserted CSS from the current web page. The stylesheet is identified
by its key, which is returned from `contents.insertCSS(css)`.
```js
contents.on('did-finish-load', async () => {
const key = await contents.insertCSS('html, body { background-color: #f00; }')
contents.removeInsertedCSS(key)
const win = new BrowserWindow()
win.webContents.on('did-finish-load', async () => {
const key = await win.webContents.insertCSS('html, body { background-color: #f00; }')
win.webContents.removeInsertedCSS(key)
})
```
@@ -1148,7 +1154,9 @@ this limitation.
Code execution will be suspended until web page stop loading.
```js
contents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
const win = new BrowserWindow()
win.webContents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
.then((result) => {
console.log(result) // Will be the JSON object from the fetch call
})
@@ -1259,7 +1267,8 @@ Sets the maximum and minimum pinch-to-zoom level.
> **NOTE**: Visual zoom is disabled by default in Electron. To re-enable it, call:
>
> ```js
> contents.setVisualZoomLevelLimits(1, 3)
> const win = new BrowserWindow()
> win.webContents.setVisualZoomLevelLimits(1, 3)
> ```
#### `contents.undo()`
@@ -1350,12 +1359,12 @@ 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`.
```javascript
const { webContents } = require('electron')
webContents.on('found-in-page', (event, result) => {
if (result.finalUpdate) webContents.stopFindInPage('clearSelection')
const win = new BrowserWindow()
win.webContents.on('found-in-page', (event, result) => {
if (result.finalUpdate) win.webContents.stopFindInPage('clearSelection')
})
const requestId = webContents.findInPage('api')
const requestId = win.webContents.findInPage('api')
console.log(requestId)
```
@@ -1435,6 +1444,7 @@ Use `page-break-before: always;` CSS style to force to print to a new page.
Example usage:
```js
const win = new BrowserWindow()
const options = {
silent: true,
deviceName: 'My-Printer',
@@ -1731,8 +1741,9 @@ For example:
```js
// Main process
const win = new BrowserWindow()
const { port1, port2 } = new MessageChannelMain()
webContents.postMessage('port', { message: 'hello' }, [port1])
win.webContents.postMessage('port', { message: 'hello' }, [port1])
// Renderer process
ipcRenderer.on('port', (e, msg) => {

View File

@@ -128,8 +128,9 @@ For example:
```js
// Main process
const win = new BrowserWindow()
const { port1, port2 } = new MessageChannelMain()
webContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])
win.webContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])
// Renderer process
ipcRenderer.on('port', (e, msg) => {

View File

@@ -96,13 +96,12 @@ with an array of misspelt words when complete.
An example of using [node-spellchecker][spellchecker] as provider:
```javascript
```javascript @ts-expect-error=[2,6]
const { webFrame } = require('electron')
const spellChecker = require('spellchecker')
webFrame.setSpellCheckProvider('en-US', {
spellCheck (words, callback) {
setTimeout(() => {
const spellchecker = require('spellchecker')
const misspelled = words.filter(x => spellchecker.isMisspelled(x))
callback(misspelled)
}, 0)

View File

@@ -255,7 +255,7 @@ The `webview` tag has the following methods:
**Example**
```javascript
```javascript @ts-expect-error=[3]
const webview = document.querySelector('webview')
webview.addEventListener('dom-ready', () => {
webview.openDevTools()
@@ -776,7 +776,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.
```javascript
```javascript @ts-expect-error=[3]
const webview = document.querySelector('webview')
webview.addEventListener('console-message', (e) => {
console.log('Guest page logged a message:', e.message)
@@ -797,7 +797,7 @@ Returns:
Fired when a result is available for
[`webview.findInPage`](#webviewfindinpagetext-options) request.
```javascript
```javascript @ts-expect-error=[3,6]
const webview = document.querySelector('webview')
webview.addEventListener('found-in-page', (e) => {
webview.stopFindInPage('keepSelection')
@@ -900,7 +900,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.
```javascript
```javascript @ts-expect-error=[3]
const webview = document.querySelector('webview')
webview.addEventListener('close', () => {
webview.src = 'about:blank'
@@ -920,7 +920,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:
```javascript
```javascript @ts-expect-error=[4,7]
// In embedder page.
const webview = document.querySelector('webview')
webview.addEventListener('ipc-message', (event) => {