Electron
/
electron
зеркало из https://github.com/electron/electron.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

docs: expand dialog window to `BaseWindow` (#43334) 

docs: expand dialog window to BaseWindow
This commit is contained in:
Shelley Vohr 2024-08-16 16:49:10 +02:00 коммит произвёл GitHub
Родитель b497700e36
Коммит d7689bb9b5
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: B5690EEEBB952194
3 изменённых файлов: 44 добавлений и 29 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

54
docs/api/dialog.md
Просмотреть файл

@ -15,9 +15,9 @@ console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections']
The `dialog` module has the following methods:
### `dialog.showOpenDialogSync([browserWindow, ]options)`
### `dialog.showOpenDialogSync([window, ]options)`
* `browserWindow` [BrowserWindow](browser-window.md) (optional)
* `window` [BaseWindow](base-window.md) (optional)
* `options` Object
* `title` string (optional)
* `defaultPath` string (optional)
@ -47,7 +47,7 @@ The `dialog` module has the following methods:
Returns `string[] | undefined`, the file paths chosen by the user; if the dialog is cancelled it returns `undefined`.
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
The `window` argument allows the dialog to attach itself to a parent window, making it modal.
The `filters` specifies an array of file types that can be displayed or
selected when you want to limit the user to a specific type. For example:
@ -72,15 +72,15 @@ and a directory selector, so if you set `properties` to
`['openFile', 'openDirectory']` on these platforms, a directory selector will be
shown.
```js @ts-type={mainWindow:Electron.BrowserWindow}
```js @ts-type={mainWindow:Electron.BaseWindow}
dialog.showOpenDialogSync(mainWindow, {
properties: ['openFile', 'openDirectory']
})
```
### `dialog.showOpenDialog([browserWindow, ]options)`
### `dialog.showOpenDialog([window, ]options)`
* `browserWindow` [BrowserWindow](browser-window.md) (optional)
* `window` [BaseWindow](base-window.md) (optional)
* `options` Object
* `title` string (optional)
* `defaultPath` string (optional)
@ -114,7 +114,7 @@ Returns `Promise<Object>` - Resolve with an object containing the following:
* `filePaths` string[] - An array of file paths chosen by the user. If the dialog is cancelled this will be an empty array.
* `bookmarks` string[]&#32;(optional) _macOS_ _mas_ - An array matching the `filePaths` array of base64 encoded strings which contains security scoped bookmark data. `securityScopedBookmarks` must be enabled for this to be populated. (For return values, see [table here](#bookmarks-array).)
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
The `window` argument allows the dialog to attach itself to a parent window, making it modal.
The `filters` specifies an array of file types that can be displayed or
selected when you want to limit the user to a specific type. For example:
@ -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 @ts-type={mainWindow:Electron.BrowserWindow}
```js @ts-type={mainWindow:Electron.BaseWindow}
dialog.showOpenDialog(mainWindow, {
properties: ['openFile', 'openDirectory']
}).then(result => {
@ -150,9 +150,9 @@ dialog.showOpenDialog(mainWindow, {
})
```
### `dialog.showSaveDialogSync([browserWindow, ]options)`
### `dialog.showSaveDialogSync([window, ]options)`
* `browserWindow` [BrowserWindow](browser-window.md) (optional)
* `window` [BaseWindow](base-window.md) (optional)
* `options` Object
* `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments.
* `defaultPath` string (optional) - Absolute directory path, absolute file
@ -176,14 +176,14 @@ dialog.showOpenDialog(mainWindow, {
Returns `string`, the path of the file chosen by the user; if the dialog is cancelled it returns an empty string.
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
The `window` argument allows the dialog to attach itself to a parent window, making it modal.
The `filters` specifies an array of file types that can be displayed, see
`dialog.showOpenDialog` for an example.
### `dialog.showSaveDialog([browserWindow, ]options)`
### `dialog.showSaveDialog([window, ]options)`
* `browserWindow` [BrowserWindow](browser-window.md) (optional)
* `window` [BaseWindow](base-window.md) (optional)
* `options` Object
* `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments.
* `defaultPath` string (optional) - Absolute directory path, absolute file
@ -210,7 +210,7 @@ Returns `Promise<Object>` - Resolve with an object containing the following:
* `filePath` string - If the dialog is canceled, this will be an empty string.
* `bookmark` string (optional) _macOS_ _mas_ - Base64 encoded string which contains the security scoped bookmark data for the saved file. `securityScopedBookmarks` must be enabled for this to be present. (For return values, see [table here](#bookmarks-array).)
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
The `window` argument allows the dialog to attach itself to a parent window, making it modal.
The `filters` specifies an array of file types that can be displayed, see
`dialog.showOpenDialog` for an example.
@ -218,9 +218,9 @@ The `filters` specifies an array of file types that can be displayed, see
**Note:** On macOS, using the asynchronous version is recommended to avoid issues when
expanding and collapsing the dialog.
### `dialog.showMessageBoxSync([browserWindow, ]options)`
### `dialog.showMessageBoxSync([wndow, ]options)`
* `browserWindow` [BrowserWindow](browser-window.md) (optional)
* `window` [BaseWindow](base-window.md) (optional)
* `options` Object
* `message` string - Content of the message box.
* `type` string (optional) - Can be `none`, `info`, `error`, `question` or
@ -258,12 +258,12 @@ Returns `Integer` - the index of the clicked button.
Shows a message box, it will block the process until the message box is closed.
It returns the index of the clicked button.
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
If `browserWindow` is not shown dialog will not be attached to it. In such case it will be displayed as an independent window.
The `window` argument allows the dialog to attach itself to a parent window, making it modal.
If `window` is not shown dialog will not be attached to it. In such case it will be displayed as an independent window.
### `dialog.showMessageBox([browserWindow, ]options)`
### `dialog.showMessageBox([window, ]options)`
* `browserWindow` [BrowserWindow](browser-window.md) (optional)
* `window` [BaseWindow](base-window.md) (optional)
* `options` Object
* `message` string - Content of the message box.
* `type` string (optional) - Can be `none`, `info`, `error`, `question` or
@ -313,7 +313,7 @@ Returns `Promise<Object>` - resolves with a promise containing the following pro
Shows a message box.
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
The `window` argument allows the dialog to attach itself to a parent window, making it modal.
### `dialog.showErrorBox(title, content)`
@ -327,9 +327,9 @@ it is usually used to report errors in early stage of startup. If called
before the app `ready`event on Linux, the message will be emitted to stderr,
and no GUI dialog will appear.
### `dialog.showCertificateTrustDialog([browserWindow, ]options)` _macOS_ _Windows_
### `dialog.showCertificateTrustDialog([window, ]options)` _macOS_ _Windows_
* `browserWindow` [BrowserWindow](browser-window.md) (optional)
* `window` [BaseWindow](base-window.md) (optional)
* `options` Object
* `certificate` [Certificate](structures/certificate.md) - The certificate to trust/import.
* `message` string - The message to display to the user.
@ -338,14 +338,14 @@ Returns `Promise<void>` - resolves when the certificate trust dialog is shown.
On macOS, this displays a modal dialog that shows a message and certificate
information, and gives the user the option of trusting/importing the
certificate. If you provide a `browserWindow` argument the dialog will be
certificate. If you provide a `window` argument the dialog will be
attached to the parent window, making it modal.
On Windows the options are more limited, due to the Win32 APIs used:
* The `message` argument is not used, as the OS provides its own confirmation
dialog.
* The `browserWindow` argument is ignored since it is not possible to make
* The `window` argument is ignored since it is not possible to make
this confirmation dialog modal.
## Bookmarks array
@ -362,10 +362,10 @@ On Windows the options are more limited, due to the Win32 APIs used:
## Sheets
On macOS, dialogs are presented as sheets attached to a window if you provide
a [`BrowserWindow`](browser-window.md) reference in the `browserWindow` parameter, or modals if no
a [`BaseWindow`](base-window.md) reference in the `window` parameter, or modals if no
window is provided.
You can call `BrowserWindow.getCurrentWindow().setSheetOffset(offset)` to change
You can call `BaseWindow.getCurrentWindow().setSheetOffset(offset)` to change
the offset from the window frame where sheets are attached.
[AbortSignal]: https://nodejs.org/api/globals.html#globals_class_abortsignal

2
docs/breaking-changes.md
Просмотреть файл

@ -1827,7 +1827,7 @@ In Electron 7, this now returns a `FileList` with a `File` object for:
Note that `webkitdirectory` no longer exposes the path to the selected folder.
If you require the path to the selected folder rather than the folder contents,
see the `dialog.showOpenDialog` API ([link](api/dialog.md#dialogshowopendialogbrowserwindow-options)).
see the `dialog.showOpenDialog` API ([link](api/dialog.md#dialogshowopendialogwindow-options)).
### API Changed: Callback-based versions of promisified APIs

17
spec/api-dialog-spec.ts
Просмотреть файл

@ -1,5 +1,5 @@
import { expect } from 'chai';
import { dialog, BrowserWindow } from 'electron/main';
import { dialog, BaseWindow, BrowserWindow } from 'electron/main';
import { closeAllWindows } from './lib/window-helpers';
import { ifit } from './lib/spec-helpers';
import { setTimeout } from 'node:timers/promises';
@ -16,6 +16,11 @@ describe('dialog module', () => {
const w = new BrowserWindow();
dialog.showOpenDialog(w, { title: 'i am title' });
}).to.not.throw();
expect(() => {
const w = new BaseWindow();
dialog.showOpenDialog(w, { title: 'i am title' });
}).to.not.throw();
});
it('throws errors when the options are invalid', () => {
@ -52,6 +57,11 @@ describe('dialog module', () => {
const w = new BrowserWindow();
dialog.showSaveDialog(w, { title: 'i am title' });
}).to.not.throw();
expect(() => {
const w = new BaseWindow();
dialog.showSaveDialog(w, { title: 'i am title' });
}).to.not.throw();
});
it('throws errors when the options are invalid', () => {
@ -93,6 +103,11 @@ describe('dialog module', () => {
const w = new BrowserWindow();
dialog.showMessageBox(w, { message: 'i am message' });
}).to.not.throw();
expect(() => {
const w = new BaseWindow();
dialog.showMessageBox(w, { message: 'i am message' });
}).to.not.throw();
});
it('throws errors when the options are invalid', () => {