share-menu
Version:
A complete and simple to use share menu.
272 lines (271 loc) • 8.99 kB
TypeScript
export interface ShareMenuParams {
text?: string;
title?: string;
url?: string;
image?: string;
}
export interface ShareTarget extends HTMLElement {
readonly displayName: string;
readonly hint?: string;
readonly color: string;
readonly outline?: string;
readonly icon: string;
readonly share: (shareMenu: ShareMenu) => unknown;
}
/**
* `share-menu` is a complete and simple to use share menu that uses
* [Web Share API](https://developers.google.com/web/updates/2016/10/navigator-share) when possible,
* with a fallback to a nice share menu that tries to emulate the experience of the native one.
*
* -----------------------------------------------------------------------------------------------------------------
*
* Here you can see the list of the supported targets, as well as the limitations that each one gives:
*
* - Copy to clipboard
* - Blogger
* - Bluesky
* - Diaspora - _URL and title only_
* - Douban
* - Email
* - Evernote - _URL and title only_
* - Facebook - _URL only if not using [Facebook JS SDK](https://developers.facebook.com/docs/javascript) or not providing a Facebook App ID_
* - Flipboard - _URL and title only_
* - Gmail
* - Google Translate - _Only translates the page at the given URL_
* - Hacker News - _URL and title only_
* - Instapaper
* - LINE - _URL only_
* - LinkedIn - _URL only_
* - LiveJournal
* - Mastodon
* - Messenger - _URL only, requires a Facebook App ID_
* - Mix - _URL only_
* - Odnoklassniki (OK.ru)
* - Pinterest
* - Pocket - _URL only_
* - Print - _Only prints the page at the given URL_
* - QZone
* - Reddit - _Shares an URL if there is no text provided, otherwise a text with the URL appended at the end_
* - Skype
* - SMS
* - Snapchat - _URL only_
* - Substack Notes
* - KakaoTalk - _URL only_
* - Telegram
* - Tumblr
* - X (Twitter)
* - VKontakte (VK)
* - Weibo
* - WhatsApp
* - XING - _URL only_
* - Yahoo Mail
*
* -----------------------------------------------------------------------------------------------------------------
*
* Example usage:
* ```html
* <share-menu title="Ohai!" text="Hello, World!" url="https://www.example.com/"></share-menu>
* ```
*
* -----------------------------------------------------------------------------------------------------------------
*
* _Browse the [API docs](https://www.webcomponents.org/element/Dabolus/share-menu) for a fully working example._
*
* @customElement
* @demo demo/index.html
*/
export declare class ShareMenu extends HTMLElement {
/**
* Fired when the content is shared (i.e. when a target is clicked).
* The event payload contains an `origin` field that will be equal
* to `native` if the native share menu has been triggered, or to
* `fallback` if the fallback share menu has been used instead.
* If the fallback share menu is used, the event payload will also
* have a `target` field, that contains the ID of the share target
* chosen by the user.
*
* @event share
*/
/**
* Fired when the share menu closes (either because the user shared
* some content or closed the share menu).
* The event payload contains an `origin` field that will be equal
* to `native` if the native share menu has been triggered, or to
* `fallback` if the fallback share menu has been used instead.
*
* @event close
*/
/**
* Fired when there is an error while sharing.
* The reason of the error can be found in the `message` field of
* the event payload.
*
* @event error
*/
/**
* Whether the fallback dialog is currently opened or not.
*
* @return {boolean}
*/
get opened(): boolean;
set opened(val: boolean);
/**
* The title of the dialog displayed if the user browser does not support the Web Share API.
* Defaults to "Share".
*
* @return {string | null}
*/
get dialogTitle(): string | null;
set dialogTitle(val: string | null | undefined);
/**
* The hint to show below the copy to clipboard button.
* Defaults to "Copy".
*
* @return {string | null}
*/
get copyHint(): string | null;
set copyHint(val: string | null | undefined);
/**
* The body of the content you want to share.
* Defaults to your description meta tag.
*
* @return {string | null}
*/
get text(): string | null;
set text(val: string | null | undefined);
/**
* The title of the content you want to share.
* Defaults to your page title.
*
* @return {string | null}
*/
get title(): string | null;
set title(val: string | null | undefined);
/**
* The URL of the content you want to share.
* Defaults to your canonical URL if available, otherwise to your page `window.location.href`.
*
* @return {string | null}
*/
get url(): string | null;
set url(val: string | null | undefined);
/**
* The URL of the image you want to share.
*
* @return {string | null}
*/
get image(): string | null;
set image(val: string | null | undefined);
/**
* Set to true if you want to hide the fallback dialog backdrop.
*
* @return {boolean}
*/
get noBackdrop(): boolean;
set noBackdrop(val: boolean);
/**
* Whether to show the handle or not.
* It can have three different values:
*
* - "auto" _(default)_ - only show the handle on touchscreen devices (i.e. when device pointer is coarse);
* - "always" - always show the handle;
* - "never" - never show the handle.
*
* @return {string | null}
*/
get handle(): string | null;
set handle(val: string | null | undefined);
/**
* The list of share targets displayed in the fallback dialog.
*
* @return {ShareTarget[]}
*/
get targets(): ShareTarget[];
static readonly observedAttributes: string[];
static stylesheet?: CSSStyleSheet;
/** @private */
private static readonly _supportsAdoptingStyleSheets;
/** @private */
private readonly _styles;
/** @private */
private readonly _template;
/** @private */
private _previousFocus;
/** @private */
private _firstFocusableElRef;
/** @private */
private _lastFocusableElRef;
/** @private */
private _backdropRef;
/** @private */
private _dialogRef;
/** @private */
private _dialogTitleRef;
/** @private */
private _targetsContainerRef;
/** @private */
private _clipboardImagePreviewRef;
/** @private */
private _clipboardPreviewRef;
/** @private */
private _clipboardButtonRef;
/** @private */
private _targets;
/** @private */
private _filePromise;
constructor();
/**
* Displays the share dialog with the `title`, `text`, and `url` provided as attributes/properties.
* You can also override their values by passing them as a parameter to this method. This can be particularly
* useful if you are creating the dialog directly from JavaScript.
*
* @param {{ text: string, title: string, url: string }=} props An object containing `text`, `title`, and `url`, that will override the element attributes/properties.
* @return {Promise<void>} A promise that resolves when the user selects a share target.
*/
share({ text, title, url, image, }?: ShareMenuParams): Promise<void>;
/** @private */
private connectedCallback;
/** @private */
private attributeChangedCallback;
/** @private */
private _copyToClipboard;
/** @private */
private _extractFileFromUrl;
/** @private */
private _renderTargets;
openWindow(url: string, query?: Record<string, string | number | boolean | null | undefined>, replace?: boolean): Window;
/** @private */
private _computeContrastColor;
/** @private */
private _emitCustomEvent;
/** @private */
private _showFallbackShare;
/** @private */
private _close;
/** @private */
private _handleScroll;
/** @private */
private _handleKeyDown;
}
export type ShareMenuEventOrigin = 'fallback' | 'native';
export interface ShareMenuShareEventPayload {
target?: string;
origin: ShareMenuEventOrigin;
}
export type ShareMenuShareEvent = CustomEvent<ShareMenuShareEventPayload>;
export interface ShareMenuCloseEventPayload {
origin: ShareMenuEventOrigin;
}
export type ShareMenuCloseEvent = CustomEvent<ShareMenuCloseEventPayload>;
export interface ShareMenuEventMap extends HTMLElementEventMap {
share: ShareMenuShareEvent;
close: ShareMenuCloseEvent;
}
export declare interface ShareMenu {
addEventListener<K extends keyof ShareMenuEventMap>(type: K, listener: (this: ShareMenu, ev: ShareMenuEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
}
declare global {
interface HTMLElementTagNameMap {
'share-menu': ShareMenu;
}
}