627 lines
15 KiB
TypeScript
627 lines
15 KiB
TypeScript
/// <reference types="node" />
|
|
declare module "@gluon-framework/gluon";
|
|
|
|
type V8CacheBuildOptions = {
|
|
/**
|
|
* Path to save the V8 Cache to. Defaults to v8Cache.json in Gluon's browser data.
|
|
*/
|
|
path?: string,
|
|
|
|
/**
|
|
* Use eager compilation.
|
|
* @default true
|
|
*/
|
|
eager?: boolean,
|
|
|
|
/**
|
|
* URLs of scripts to cache. Defaults to automatically detecting currently loaded scripts in the page.
|
|
*/
|
|
urls?: string[],
|
|
|
|
/**
|
|
* Reload the page to force script compilation.
|
|
* @default true
|
|
*/
|
|
reload?: boolean,
|
|
|
|
/**
|
|
* Include preload scripts in automatic detection.
|
|
* @default true
|
|
*/
|
|
includePreload?: boolean
|
|
};
|
|
|
|
type V8CacheApi = {
|
|
/** Build a V8 Cache. */
|
|
build(
|
|
/** Build options. */
|
|
options?: V8CacheBuildOptions
|
|
): Promise<void>,
|
|
|
|
/** Load a V8 Cache. */
|
|
load(
|
|
/**
|
|
* Path to load. Defaults to v8Cache.json in Gluon's browser data.
|
|
*/
|
|
path?: string
|
|
): Promise<boolean>
|
|
|
|
/** Check if a V8 Cache exists with a given path. */
|
|
exists(
|
|
/** Path to check. */
|
|
path: string
|
|
): Promise<boolean>
|
|
};
|
|
|
|
type PrintToPDFOptions = {
|
|
/**
|
|
* Paper orientation.
|
|
* @default false
|
|
*/
|
|
landscape?: boolean,
|
|
|
|
/**
|
|
* Display header and footer.
|
|
* @default false
|
|
*/
|
|
displayHeaderFooter?: boolean,
|
|
|
|
/**
|
|
* Print background graphics.
|
|
* @default false
|
|
*/
|
|
printBackground?: boolean,
|
|
|
|
/**
|
|
* Scale of the webpage rendering.
|
|
* @default 1
|
|
*/
|
|
scale?: number,
|
|
|
|
/**
|
|
* Paper width in inches.
|
|
* @default 8.5
|
|
*/
|
|
paperWidth?: number,
|
|
|
|
/**
|
|
* Paper height in inches.
|
|
* @default 11
|
|
*/
|
|
paperHeight?: number,
|
|
|
|
/**
|
|
* Set the margins of the PDF (inches).
|
|
* @default 0.4 for all
|
|
*/
|
|
margins?: {
|
|
/**
|
|
* Top margin in inches.
|
|
* @default 0.4 (1cm)
|
|
*/
|
|
top?: number,
|
|
|
|
/**
|
|
* Bottom margin in inches.
|
|
* @default 0.4 (1cm)
|
|
*/
|
|
bottom?: number,
|
|
|
|
/**
|
|
* Left margin in inches.
|
|
* @default 0.4 (1cm)
|
|
*/
|
|
left?: number,
|
|
|
|
/**
|
|
* Right margin in inches.
|
|
* @default 0.4 (1cm)
|
|
*/
|
|
right?: number
|
|
},
|
|
|
|
/**
|
|
* Paper ranges to print, one based, (eg '1-5, 8, 11-13').
|
|
* Pages are printed in the document order, not in the order specified, and no more than once.
|
|
* Defaults to an empty string, which implies all pages available are printed.
|
|
* @default ''
|
|
*/
|
|
pageRanges?: string,
|
|
|
|
/**
|
|
* HTML template for the print header.
|
|
* You can use the following classes which will have the relevant print data injected into the contents:
|
|
* - `date` - formatted print date
|
|
* - `title` - document title
|
|
* - `url` - document location
|
|
* - `pageNumber` - current page number
|
|
* - `totalPages` - total pages in the document
|
|
* @example `<span class=title></span>` would create a span containing the document title.
|
|
*/
|
|
headerTemplate?: string,
|
|
|
|
/**
|
|
* HTML template for the print footer.
|
|
* You can use the following classes which will have the relevant print data injected into the contents:
|
|
* - `date` - formatted print date
|
|
* - `title` - document title
|
|
* - `url` - document location
|
|
* - `pageNumber` - current page number
|
|
* - `totalPages` - total pages in the document
|
|
* @example `<span class=title></span>` would create a span containing the document title.
|
|
*/
|
|
footerTemplate?: string,
|
|
|
|
/**
|
|
* Prefer the page size defined by the page's CSS.
|
|
* When set to false, it will scale to fit the paper size.
|
|
* @default false
|
|
*/
|
|
preferCSSPageSize?: boolean,
|
|
};
|
|
|
|
type PageApi = {
|
|
/**
|
|
* Evaluate a string or function in the web context.
|
|
* @returns Return value of expression given.
|
|
*/
|
|
eval(
|
|
/** String or function to evaluate. */
|
|
expression: string|Function
|
|
): Promise<any>,
|
|
|
|
/** Promise for waiting until the page has loaded. */
|
|
loaded: Promise<void>,
|
|
|
|
/**
|
|
* Get or set the title of the page.
|
|
* Use no arguments to get the title, or provide a string to set it.
|
|
*/
|
|
title(
|
|
/** Set the page title to a new title. */
|
|
newTitle: string
|
|
): Promise<string>,
|
|
|
|
/**
|
|
* Reload the page.
|
|
*/
|
|
reload(
|
|
/**
|
|
* Optionally ignore the cache for the reload.
|
|
* @default false
|
|
*/
|
|
ignoreCache?: boolean
|
|
): Promise<void>,
|
|
|
|
/**
|
|
* Print (export) the page as a PDF.
|
|
* @returns Buffer of PDF data.
|
|
*/
|
|
printToPDF(
|
|
/** Optional print options (based on Chromium's headless standard). */
|
|
options?: PrintToPDFOptions
|
|
): Promise<Buffer>
|
|
};
|
|
|
|
type IPCStoreApi = {
|
|
/** Get a key from the IPC store. */
|
|
get(
|
|
/** Key to get. */
|
|
key: string
|
|
): any,
|
|
|
|
/** Set a key to the provided value in the IPC store (has to be serializable to JSON). */
|
|
set<T>(
|
|
/** Key to set to. */
|
|
key: string,
|
|
|
|
/** Value to set. */
|
|
value: T
|
|
): T,
|
|
|
|
/** Get or set a key from the IPC Store (has to be serializable to JSON). */
|
|
[key: string]: any,
|
|
};
|
|
|
|
type IPCApi = {
|
|
/**
|
|
* Send an IPC event to the web context.
|
|
* @returns Replied event data (null by default).
|
|
*/
|
|
send(
|
|
/** Type of event to send. */
|
|
type: string,
|
|
|
|
/** Data of event to send. */
|
|
data: any
|
|
): Promise<any>,
|
|
|
|
/**
|
|
* Subscribe to IPC events of a specific type with a callback.
|
|
*/
|
|
on(
|
|
/** Type of event to handle. */
|
|
type: string,
|
|
|
|
/**
|
|
* Ran whenever an IPC event of type specified is received. Should return optionally with what to reply with.
|
|
* @returns Optionally with what to reply with, otherwise null by default.
|
|
*/
|
|
callback: (data: any) => any
|
|
): void,
|
|
|
|
/**
|
|
* Unsubscribe an IPC event listener callback with a specific type.
|
|
*/
|
|
removeListener(
|
|
/** Type of event which was subscribed to. */
|
|
type: string,
|
|
|
|
/** Callback function to unsubscribe. */
|
|
callback: Function
|
|
): void,
|
|
|
|
/**
|
|
* Expose a Node function to the web context, acts as a wrapper around IPC events.
|
|
* Can be ran in window with Gluon.ipc[key](...args)
|
|
*/
|
|
expose(
|
|
/** Key name to expose to. */
|
|
key: string,
|
|
|
|
/** Handler function which is called from the web context. */
|
|
handler: Function
|
|
): void,
|
|
|
|
/**
|
|
* Unexpose (remove) a Node function previously exposed using expose().
|
|
*/
|
|
unexpose(
|
|
/** Key name to unexpose (remove). */
|
|
key: string
|
|
): void,
|
|
|
|
/** IPC Store API. */
|
|
store: IPCStoreApi,
|
|
|
|
/**
|
|
* Expose a Node function to the web context, acts as a wrapper around IPC events.
|
|
* Can be ran in window with Gluon.ipc[key](...args)
|
|
*/
|
|
[key: string]: any,
|
|
};
|
|
|
|
type CDPApi = {
|
|
/**
|
|
* Send a CDP command to the browser.
|
|
* {@link https://chromedevtools.github.io/devtools-protocol/ Chrome DevTools Protocol Documentation}
|
|
* @returns Result of command from browser.
|
|
*/
|
|
send(
|
|
/** Method of CDP command. */
|
|
method: string,
|
|
|
|
/** Parameters of CDP command. */
|
|
params?: object,
|
|
|
|
/**
|
|
* Send session ID with the command (default true).
|
|
* @default true
|
|
*/
|
|
useSessionId?: boolean
|
|
): Promise<any>,
|
|
|
|
/**
|
|
* Hook into a specific CDP method being emitted.
|
|
* @returns Function to unhook/unsubscribe.
|
|
*/
|
|
on(
|
|
/** Method of CDP event to hook into. */
|
|
method: string,
|
|
|
|
/** Callback to run when the given method is emitted. */
|
|
callback: (message: any) => void,
|
|
|
|
/**
|
|
* Unhook once the callback is called the first time.
|
|
* @default false
|
|
*/
|
|
once: boolean
|
|
): (() => void)
|
|
};
|
|
|
|
type IdleAutoOptions = {
|
|
/**
|
|
* How long the window should be minimized before hibernating, in seconds.
|
|
* @default 5
|
|
*/
|
|
timeMinimizedToHibernate?: number
|
|
};
|
|
|
|
type IdleApi = {
|
|
/**
|
|
* Put the window into hibernation.
|
|
* Internally kills the browser to save the most resources possible. Loses page state.
|
|
*/
|
|
hibernate(): Promise<void>,
|
|
|
|
/**
|
|
* Put the window to sleep.
|
|
* Uses a screenshot of the page instead of the actual page. Loses page state.
|
|
*/
|
|
sleep(): Promise<void>,
|
|
|
|
/**
|
|
* Freeze the window.
|
|
* Keeps the page but halts most execution and background work. Keeps page state.
|
|
*/
|
|
freeze(): Promise<void>,
|
|
|
|
/** Wake up the window from hibernation or sleep. */
|
|
wake(): Promise<void>,
|
|
|
|
/** Enable/disable automatic idle management, and set its options. */
|
|
auto(
|
|
/** Whether to use automatic idle management. */
|
|
enabled: boolean,
|
|
|
|
/** Set options for automatic behavior. */
|
|
options?: IdleAutoOptions
|
|
): void
|
|
};
|
|
|
|
type VersionInfo = {
|
|
/** Name of component. */
|
|
name: string,
|
|
|
|
/** Full version of component. */
|
|
version: string,
|
|
|
|
/** Major version of component as a number. */
|
|
major: number
|
|
};
|
|
|
|
type BrowserVersions = {
|
|
/**
|
|
* Product (browser) version and name.
|
|
* @example
|
|
* Window.versions.product // { name: 'Chrome Canary', version: '111.0.5513.0', major: 111 }
|
|
*/
|
|
product: VersionInfo,
|
|
|
|
/**
|
|
* Browser engine (Chromium/Firefox) version and name.
|
|
* @example
|
|
* Window.versions.engine // { name: 'chromium', version: '111.0.5513.0', major: 111 }
|
|
*/
|
|
engine: VersionInfo,
|
|
|
|
/**
|
|
* JS engine (V8/SpiderMonkey) version and name.
|
|
* @example
|
|
* Window.versions.jsEngine // { name: 'v8', version: '11.1.86', major: 11 }
|
|
*/
|
|
jsEngine: VersionInfo
|
|
};
|
|
|
|
type WindowBounds = {
|
|
/** The offset from the left edge of the screen to the window in pixels. */
|
|
left?: number,
|
|
|
|
/** The offset from the top edge of the screen to the window in pixels. */
|
|
top?: number,
|
|
|
|
/** The window width in pixels. */
|
|
width?: number,
|
|
|
|
/** The window height in pixels. */
|
|
height?: number
|
|
};
|
|
|
|
type ControlsApi = {
|
|
/** Minimize the browser window. */
|
|
minimize(): Promise<void>,
|
|
|
|
/**
|
|
* Maximize the browser window.
|
|
* Doesn't make the window appear (use show() before as well).
|
|
*/
|
|
maximize(): Promise<void>,
|
|
|
|
/** Show (unminimize) the browser window and optionally set the bounds (position/size). */
|
|
show(
|
|
/** Set the bounds (position and/or size) of the browser window optionally as well. */
|
|
bounds?: WindowBounds
|
|
): Promise<void>
|
|
};
|
|
|
|
type CSSResource = {
|
|
/** Remove the CSS previously added from the current page and future page loads. */
|
|
remove(): Promise<void>,
|
|
|
|
/** Update the CSS previously added to new code given in the current page and future page loads. */
|
|
modify(newCode: string): Promise<void>
|
|
};
|
|
|
|
type JSResource = {
|
|
/** Remove the JS previously added so it no longer executes in new page loads. */
|
|
remove(): Promise<void>
|
|
};
|
|
|
|
type ResourcesApi = {
|
|
/** Inject CSS to the current page and future page loads (refresh, navigations, etc). */
|
|
css(code: string): Promise<CSSResource>,
|
|
|
|
/** Inject JS to the current page and future page loads (refresh, navigations, etc). */
|
|
js(code: string): Promise<JSResource>
|
|
};
|
|
|
|
type Window = {
|
|
/** API for the page of the window. */
|
|
page: PageApi,
|
|
|
|
/** API for IPC. */
|
|
ipc: IPCApi,
|
|
|
|
/** API for manually using CDP with the browser. */
|
|
cdp: CDPApi,
|
|
|
|
/** API for injecting resources like CSS and JS. */
|
|
resources: ResourcesApi,
|
|
|
|
/**
|
|
* API for Gluon idle management (like hibernation). Chromium only.
|
|
* @experimental
|
|
*/
|
|
idle: IdleApi,
|
|
|
|
/** Browser version info of the window: product (browser), engine (Chromium/Firefox), and JS engine (V8/SpiderMonkey). */
|
|
versions: BrowserVersions,
|
|
|
|
/** Control (minimize, maximize, etc) the browser window. */
|
|
controls: ControlsApi,
|
|
|
|
/**
|
|
* Interface with V8's Compilation Cache. Chromium only.
|
|
* @experimental
|
|
*/
|
|
v8Cache: V8CacheApi,
|
|
|
|
/** Close the Gluon window. */
|
|
close(): void,
|
|
|
|
/** If the window has been closed or not. */
|
|
closed: boolean
|
|
};
|
|
|
|
|
|
/** A browser that Gluon supports. */
|
|
type Browser =
|
|
'chrome'|'chrome_beta'|'chrome_dev'|'chrome_canary'|
|
|
'chromium'|'chromium_snapshot'|
|
|
'edge'|'edge_beta'|'edge_dev'|'edge_canary'|
|
|
'firefox'|'firefox_nightly'|
|
|
'thorium'|
|
|
'librewolf';
|
|
|
|
/** A browser engine that Gluon supports. */
|
|
type BrowserEngine = 'chromium'|'firefox';
|
|
|
|
|
|
/** Additional options for opening */
|
|
type OpenOptions = {
|
|
/** Force Gluon to use a specific browser instead of automatically finding one itself. */
|
|
forceBrowser?: Browser,
|
|
|
|
/** Force Gluon to use a specific browser engine instead of automatically finding a browser itself. */
|
|
forceEngine?: BrowserEngine,
|
|
|
|
/** Size of Gluon window in [width, height]. */
|
|
windowSize?: [number, number],
|
|
|
|
/**
|
|
* Opt-in to allowing HTTP. Not recommended to use, always keep `false` where possible. Primarily to support custom localhost servers.
|
|
* Options:
|
|
* - `false`: HTTP is **completely disabled**. Recommended.
|
|
* - `mixed`: HTTP is **enabled for mixed content**, but not as window URL. **Not recommended.**
|
|
* - `true`: HTTP is **completely enabled**. **Not recommended.**
|
|
* @default false
|
|
*/
|
|
allowHTTP?: false | 'mixed' | true,
|
|
|
|
/**
|
|
* Set what top-level navigation is allowed in the window.
|
|
* Options:
|
|
* - `false`: **No** navigation is allowed.
|
|
* - `same-origin`: Navigation is allowed **if the redirect URL is the same origin** (as the URL given to `open()`).
|
|
* - `true`: **All** navigation is allowed. **Not recommended.**
|
|
* @default 'same-origin'
|
|
*/
|
|
allowNavigation?: false | 'same-origin' | true,
|
|
|
|
/**
|
|
* Set the Content Security Policy when using Local (giving open() a path).
|
|
* Defaults to allowing almost everything remote except dangerous parts like JS or frames (see detailed default value).
|
|
* Set to blank (`''`) to use no CSP, or provide your own to use (as a string).
|
|
* @default "upgrade-insecure-requests; default-src 'self' 'unsafe-inline'; connect-src https: data: blob: 'unsafe-inline'; prefetch-src https: data: blob: 'unsafe-inline'; font-src https: data: blob: 'unsafe-inline'; img-src https: data: blob: 'unsafe-inline'; media-src https: data: blob: 'unsafe-inline'; style-src https: data: blob: 'unsafe-inline'; form-action https: data: blob: 'unsafe-inline'"
|
|
*/
|
|
localCSP?: string,
|
|
|
|
/**
|
|
* Whether DevTools (Ctrl+Shift+I etc) is enabled/disabled in the Gluon window. Enabled by default.
|
|
* @default true
|
|
*/
|
|
devtools?: boolean,
|
|
|
|
/** Set a custom user agent for the browser engine to use. */
|
|
userAgent?: string,
|
|
|
|
/**
|
|
* Do not persist browser data in the regular data directory.
|
|
* @default false
|
|
*/
|
|
incognito?: boolean,
|
|
};
|
|
|
|
/**
|
|
* Open a new Gluon window.
|
|
*/
|
|
export function open(
|
|
/** URL to load in the window. */
|
|
url: string,
|
|
|
|
/** Additional options for opening. */
|
|
options: OpenOptions
|
|
): Promise<Window>;
|
|
|
|
type Extension = {
|
|
/** Path to unpacked Chromium extension. */
|
|
chromium?: string | Promise<string>,
|
|
|
|
/** Path to Firefox extension as an XPI file, with the correct filename. */
|
|
firefox?: string | Promise<string>
|
|
};
|
|
|
|
type ExtensionsAPI = {
|
|
/** Add browser extensions to be used when opening new Gluon windows. */
|
|
add(...extensions: Extension[]): void,
|
|
|
|
/** Remove browser extensions to be used when opening new Gluon windows. */
|
|
remove(...extensions: Extension[]): void,
|
|
};
|
|
|
|
/** Manage browser extensions to use. */
|
|
export const extensions: ExtensionsAPI;
|
|
|
|
type Link = {
|
|
href: string,
|
|
text: string
|
|
};
|
|
|
|
type OpenAboutOptions = {
|
|
/** Name of the app to display. */
|
|
name: string,
|
|
|
|
/** URL icon of the app to use. */
|
|
icon: string,
|
|
|
|
/** Description of the app to display. Supports HTML. */
|
|
description?: string,
|
|
|
|
/** Version of the app to display. */
|
|
version?: string,
|
|
|
|
/** Links to display in the window. */
|
|
links?: Link[],
|
|
|
|
/** Gluon versions from a Window to display (Gluon, Node, Browser). */
|
|
gluonVersions?: BrowserVersions
|
|
};
|
|
|
|
/**
|
|
* Open a new Gluon about window.
|
|
*/
|
|
export function openAbout(
|
|
/** Options for what to display in the about window. */
|
|
options: OpenAboutOptions
|
|
): Promise<Window>; |