feat: add support for share menu on macOS (#25629)

This commit is contained in:
Cheng Zhao 2020-10-20 10:33:06 +09:00 committed by GitHub
parent 89c04b3c6c
commit 6b6ffbdd10
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 316 additions and 6 deletions

View file

@ -14,7 +14,7 @@ See [`Menu`](menu.md) for examples.
* `menuItem` MenuItem
* `browserWindow` [BrowserWindow](browser-window.md) | undefined - This will not be defined if no window is open.
* `event` [KeyboardEvent](structures/keyboard-event.md)
* `role` String (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu` - Define the action of the menu item, when specified the
* `role` String (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `shareMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu` - Define the action of the menu item, when specified the
`click` property will be ignored. See [roles](#roles).
* `type` String (optional) - Can be `normal`, `separator`, `submenu`, `checkbox` or
`radio`.
@ -31,6 +31,7 @@ See [`Menu`](menu.md) for examples.
menu items.
* `registerAccelerator` Boolean (optional) _Linux_ _Windows_ - If false, the accelerator won't be registered
with the system, but it will still be displayed. Defaults to true.
* `sharingItem` SharingItem (optional) _macOS_ - The item to share when the `role` is `shareMenu`.
* `submenu` (MenuItemConstructorOptions[] | [Menu](menu.md)) (optional) - Should be specified
for `submenu` type menu items. If `submenu` is specified, the `type: 'submenu'` can be omitted.
If the value is not a [`Menu`](menu.md) then it will be automatically converted to one using
@ -112,6 +113,7 @@ The following additional roles are available on _macOS_:
* `services` - The submenu is a ["Services"](https://developer.apple.com/documentation/appkit/nsapplication/1428608-servicesmenu?language=objc) menu. This is only intended for use in the Application Menu and is *not* the same as the "Services" submenu used in context menus in macOS apps, which is not implemented in Electron.
* `recentDocuments` - The submenu is an "Open Recent" menu.
* `clearRecentDocuments` - Map to the `clearRecentDocuments` action.
* `shareMenu` - The submenu is [share menu][ShareMenu]. The `sharingItem` property must also be set to indicate the item to share.
When specifying a `role` on macOS, `label` and `accelerator` are the only
options that will affect the menu item. All other options will be ignored.
@ -200,6 +202,12 @@ system or just displayed.
This property can be dynamically changed.
#### `menuItem.sharingItem` _macOS_
A `SharingItem` indicating the item to share when the `role` is `shareMenu`.
This property can be dynamically changed.
#### `menuItem.commandId`
A `Number` indicating an item's sequential unique id.
@ -207,3 +215,5 @@ A `Number` indicating an item's sequential unique id.
#### `menuItem.menu`
A `Menu` that the item is a part of.
[ShareMenu]: https://developer.apple.com/design/human-interface-guidelines/macos/extensions/share-extensions/

45
docs/api/share-menu.md Normal file
View file

@ -0,0 +1,45 @@
## Class: ShareMenu
> Create share menu on macOS.
Process: [Main](../glossary.md#main-process)
The `ShareMenu` class creates [Share Menu][share-menu] on macOS, which can be
used to share information from the current context to apps, social media
accounts, and other services.
For including the share menu as a submenu of other menus, please use the
`shareMenu` role of [`MenuItem`](menu-item.md).
### `new ShareMenu(sharingItem)`
* `sharingItem` SharingItem - The item to share.
Creates a new share menu.
### Instance Methods
The `shareMenu` object has the following instance methods:
#### `shareMenu.popup([options])`
* `options` PopupOptions (optional)
* `browserWindow` [BrowserWindow](browser-window.md) (optional) - Default is the focused window.
* `x` Number (optional) - Default is the current mouse cursor position.
Must be declared if `y` is declared.
* `y` Number (optional) - Default is the current mouse cursor position.
Must be declared if `x` is declared.
* `positioningItem` Number (optional) _macOS_ - The index of the menu item to
be positioned under the mouse cursor at the specified coordinates. Default
is -1.
* `callback` Function (optional) - Called when menu is closed.
Pops up this menu as a context menu in the [`BrowserWindow`](browser-window.md).
#### `shareMenu.closePopup([browserWindow])`
* `browserWindow` [BrowserWindow](browser-window.md) (optional) - Default is the focused window.
Closes the context menu in the `browserWindow`.
[share-menu]: https://developer.apple.com/design/human-interface-guidelines/macos/extensions/share-extensions/

View file

@ -0,0 +1,5 @@
# SharingItem Object
* `texts` String[] (optional) - An array of text to share.
* `filePaths` String[] (optional) - An array of files to share.
* `urls` String[] (optional) - An array of URLs to share.