CalvinBackup/tauri-plugins-workspace
1
0
Fork 0
mirror of https://github.com/tauri-apps/plugins-workspace.git synced 2026-09-22 21:30:44 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore: update documentation

Browse Source
This commit is contained in:
Lucas Nogueira
2026-09-22 11:30:47 -03:00
parent d869c162a7
commit a87a3c7d44
104 changed files with 4875 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/shell/guest-js/index.ts
+336 -24
View File
@@ -66,6 +66,8 @@
import { invoke, Channel } from '@tauri-apps/api/core'
/**
* Options that configure how a child process is spawned.
*
* @since 2.0.0
*/
interface SpawnOptions {
@@ -87,6 +89,8 @@ interface InternalSpawnOptions extends SpawnOptions {
}
/**
* The output collected from a child process that ran to completion.
*
* @since 2.0.0
*/
interface ChildProcess<O extends IOPayload> {
@@ -101,6 +105,9 @@ interface ChildProcess<O extends IOPayload> {
}
/**
* A minimal event emitter modeled after Node.js' `EventEmitter`, used by
* {@link Command} and by its `stdout` and `stderr` streams.
*
* @since 2.0.0
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -113,6 +120,18 @@ class EventEmitter<E extends Record<string, any>> {
/**
* Alias for `emitter.on(eventName, listener)`.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* command.addListener('error', (error) => console.error(error));
* ```
*
* @param eventName The name of the event to listen to.
* @param listener The callback invoked with the event payload.
*
* @returns A reference to the `EventEmitter`, so that calls can be chained.
*
* @since 2.0.0
*/
addListener<N extends keyof E>(
@@ -125,6 +144,20 @@ class EventEmitter<E extends Record<string, any>> {
/**
* Alias for `emitter.off(eventName, listener)`.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* const listener = (error: string) => console.error(error);
* command.addListener('error', listener);
* command.removeListener('error', listener);
* ```
*
* @param eventName The name of the event to stop listening to.
* @param listener The exact callback that was registered before.
*
* @returns A reference to the `EventEmitter`, so that calls can be chained.
*
* @since 2.0.0
*/
removeListener<N extends keyof E>(
@@ -142,6 +175,20 @@ class EventEmitter<E extends Record<string, any>> {
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* command.on('close', (data) => {
* console.log(`command finished with code ${data.code}`);
* });
* ```
*
* @param eventName The name of the event to listen to.
* @param listener The callback invoked with the event payload.
*
* @returns A reference to the `EventEmitter`, so that calls can be chained.
*
* @since 2.0.0
*/
on<N extends keyof E>(
@@ -164,6 +211,20 @@ class EventEmitter<E extends Record<string, any>> {
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* command.once('close', (data) => {
* console.log(`command finished with code ${data.code}`);
* });
* ```
*
* @param eventName The name of the event to listen to once.
* @param listener The callback invoked with the event payload.
*
* @returns A reference to the `EventEmitter`, so that calls can be chained.
*
* @since 2.0.0
*/
once<N extends keyof E>(
@@ -181,6 +242,20 @@ class EventEmitter<E extends Record<string, any>> {
* Removes the all specified listener from the listener array for the event eventName
* Returns a reference to the `EventEmitter`, so that calls can be chained.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* const listener = (error: string) => console.error(error);
* command.on('error', listener);
* command.off('error', listener);
* ```
*
* @param eventName The name of the event to stop listening to.
* @param listener The exact callback that was registered before.
*
* @returns A reference to the `EventEmitter`, so that calls can be chained.
*
* @since 2.0.0
*/
off<N extends keyof E>(
@@ -201,6 +276,19 @@ class EventEmitter<E extends Record<string, any>> {
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* command.on('error', (error) => console.error(error));
* command.removeAllListeners('error');
* ```
*
* @param event The name of the event to remove the listeners of.
* When omitted, the listeners of every event are removed.
*
* @returns A reference to the `EventEmitter`, so that calls can be chained.
*
* @since 2.0.0
*/
removeAllListeners<N extends keyof E>(event?: N): this {
@@ -215,10 +303,23 @@ class EventEmitter<E extends Record<string, any>> {
}
/**
* @ignore
* Synchronously calls each of the listeners registered for the event named`eventName`, in the order they were registered, passing the supplied arguments
* Synchronously calls each of the listeners registered for the event named
* `eventName`, in the order they were registered, passing the supplied arguments
* to each.
*
* @ignore
*
* @example
* ```typescript
* import { EventEmitter } from '@tauri-apps/plugin-shell';
* const emitter = new EventEmitter<{ data: string }>();
* emitter.on('data', (line) => console.log(line));
* emitter.emit('data', 'hello');
* ```
*
* @param eventName The name of the event to emit.
* @param arg The payload passed to every registered listener.
*
* @returns `true` if the event had listeners, `false` otherwise.
*
* @since 2.0.0
@@ -236,6 +337,18 @@ class EventEmitter<E extends Record<string, any>> {
/**
* Returns the number of listeners listening to the event named `eventName`.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* command.on('close', () => {});
* console.log(command.listenerCount('close')); // 1
* ```
*
* @param eventName The name of the event to count the listeners of.
*
* @returns The number of listeners registered for the given event.
*
* @since 2.0.0
*/
listenerCount<N extends keyof E>(eventName: N): number {
@@ -253,6 +366,18 @@ class EventEmitter<E extends Record<string, any>> {
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* command.prependListener('error', (error) => console.error(error));
* ```
*
* @param eventName The name of the event to listen to.
* @param listener The callback invoked with the event payload.
*
* @returns A reference to the `EventEmitter`, so that calls can be chained.
*
* @since 2.0.0
*/
prependListener<N extends keyof E>(
@@ -275,6 +400,18 @@ class EventEmitter<E extends Record<string, any>> {
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* command.prependOnceListener('error', (error) => console.error(error));
* ```
*
* @param eventName The name of the event to listen to once.
* @param listener The callback invoked with the event payload.
*
* @returns A reference to the `EventEmitter`, so that calls can be chained.
*
* @since 2.0.0
*/
prependOnceListener<N extends keyof E>(
@@ -292,12 +429,30 @@ class EventEmitter<E extends Record<string, any>> {
}
/**
* A handle to a child process spawned with {@link Command.spawn},
* which can be used to write to its `stdin` or to kill it.
*
* @since 2.0.0
*/
class Child {
/** The child process `pid`. */
pid: number
/**
* Creates a handle to the child process with the given process id.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* // a `Child` is usually obtained by spawning a command:
* const child = await Command.create('node').spawn();
* console.log(child.pid);
* ```
*
* @param pid The process id of the child process.
*
* @since 2.0.0
*/
constructor(pid: number) {
this.pid = pid
}
@@ -329,6 +484,14 @@ class Child {
/**
* Kills the child process.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* const child = await command.spawn();
* await child.kill();
* ```
*
* @returns A promise indicating the success or failure of the operation.
*
* @since 2.0.0
@@ -341,12 +504,25 @@ class Child {
}
}
/**
* The events emitted by a {@link Command} instance.
*
* @since 2.0.0
*/
interface CommandEvents {
/** Emitted when the child process terminated, carrying its exit code and signal. */
close: TerminatedPayload
/** Emitted when the child process could not be spawned or failed unexpectedly, carrying the error message. */
error: string
}
/**
* The events emitted by the `stdout` and `stderr` streams of a {@link Command}.
*
* @since 2.0.0
*/
interface OutputEvents<O extends IOPayload> {
/** Emitted for each line the process wrote to the stream, or for each raw chunk when the `raw` encoding is used. */
data: O
}
@@ -403,20 +579,9 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
this.options = options ?? {}
}
static create(program: string, args?: string | string[]): Command<string>
static create(
program: string,
args?: string | string[],
options?: SpawnOptions & { encoding: 'raw' }
): Command<Uint8Array>
static create(
program: string,
args?: string | string[],
options?: SpawnOptions
): Command<string>
/**
* Creates a command to execute the given program.
* Creates a command to execute the given program, decoding its output as text.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
@@ -426,6 +591,77 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
*
* @param program The program to execute.
* It must be configured in your project's capabilities.
* @param args The arguments to pass to the program. Defaults to no arguments.
*
* @returns The command instance, ready to be spawned or executed.
*
* @since 2.0.0
*/
static create(program: string, args?: string | string[]): Command<string>
/**
* Creates a command to execute the given program, keeping its output as raw bytes.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('my-app', ['run', 'tauri'], { encoding: 'raw' });
* const output = await command.execute();
* console.log(output.stdout); // a Uint8Array
* ```
*
* @param program The program to execute.
* It must be configured in your project's capabilities.
* @param args The arguments to pass to the program. Defaults to no arguments.
* @param options Spawn options using the `raw` encoding, which makes the process
* output be delivered as `Uint8Array` instead of `string`.
*
* @returns The command instance, ready to be spawned or executed.
*
* @since 2.0.0
*/
static create(
program: string,
args?: string | string[],
options?: SpawnOptions & { encoding: 'raw' }
): Command<Uint8Array>
/**
* Creates a command to execute the given program with the given spawn options.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('my-app', ['run', 'tauri'], { cwd: '/path/to/project' });
* const output = await command.execute();
* ```
*
* @param program The program to execute.
* It must be configured in your project's capabilities.
* @param args The arguments to pass to the program. Defaults to no arguments.
* @param options Spawn options such as the working directory, the environment
* variables and the character encoding of the process output.
*
* @returns The command instance, ready to be spawned or executed.
*
* @since 2.0.0
*/
static create(
program: string,
args?: string | string[],
options?: SpawnOptions
): Command<string>
/**
* Creates a command to execute the given program.
*
* @param program The program to execute.
* It must be configured in your project's capabilities.
* @param args The arguments to pass to the program. Defaults to no arguments.
* @param options Spawn options such as the working directory, the environment
* variables and the character encoding of the process output.
*
* @returns The command instance, ready to be spawned or executed.
*
* @since 2.0.0
*/
static create<O extends IOPayload>(
program: string,
@@ -435,12 +671,74 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
return new Command(program, args, options)
}
/**
* Creates a command to execute the given sidecar program, decoding its output as text.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.sidecar('my-sidecar');
* const output = await command.execute();
* ```
*
* @param program The sidecar program to execute.
* It must be configured in your project's capabilities
* and defined on `tauri.conf.json > bundle > externalBin`.
* @param args The arguments to pass to the program. Defaults to no arguments.
*
* @returns The command instance, ready to be spawned or executed.
*
* @since 2.0.0
*/
static sidecar(program: string, args?: string | string[]): Command<string>
/**
* Creates a command to execute the given sidecar program, keeping its output as raw bytes.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.sidecar('my-sidecar', [], { encoding: 'raw' });
* const output = await command.execute();
* console.log(output.stdout); // a Uint8Array
* ```
*
* @param program The sidecar program to execute.
* It must be configured in your project's capabilities
* and defined on `tauri.conf.json > bundle > externalBin`.
* @param args The arguments to pass to the program. Defaults to no arguments.
* @param options Spawn options using the `raw` encoding, which makes the process
* output be delivered as `Uint8Array` instead of `string`.
*
* @returns The command instance, ready to be spawned or executed.
*
* @since 2.0.0
*/
static sidecar(
program: string,
args?: string | string[],
options?: SpawnOptions & { encoding: 'raw' }
): Command<Uint8Array>
/**
* Creates a command to execute the given sidecar program with the given spawn options.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.sidecar('my-sidecar', [], { cwd: '/path/to/project' });
* const output = await command.execute();
* ```
*
* @param program The sidecar program to execute.
* It must be configured in your project's capabilities
* and defined on `tauri.conf.json > bundle > externalBin`.
* @param args The arguments to pass to the program. Defaults to no arguments.
* @param options Spawn options such as the working directory, the environment
* variables and the character encoding of the process output.
*
* @returns The command instance, ready to be spawned or executed.
*
* @since 2.0.0
*/
static sidecar(
program: string,
args?: string | string[],
@@ -449,15 +747,17 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
/**
* Creates a command to execute the given sidecar program.
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.sidecar('my-sidecar');
* const output = await command.execute();
* ```
*
* @param program The program to execute.
* It must be configured in your project's capabilities.
* @param program The sidecar program to execute.
* It must be configured in your project's capabilities
* and defined on `tauri.conf.json > bundle > externalBin`.
* @param args The arguments to pass to the program. Defaults to no arguments.
* @param options Spawn options such as the working directory, the environment
* variables and the character encoding of the process output.
*
* @returns The command instance, ready to be spawned or executed.
*
* @since 2.0.0
*/
static sidecar<O extends IOPayload>(
program: string,
@@ -472,6 +772,15 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
/**
* Executes the command as a child process, returning a handle to it.
*
* @example
* ```typescript
* import { Command } from '@tauri-apps/plugin-shell';
* const command = Command.create('node');
* command.stdout.on('data', (line) => console.log(line));
* const child = await command.spawn();
* console.log('pid:', child.pid);
* ```
*
* @returns A promise resolving to the child process handle.
*
* @since 2.0.0
@@ -562,7 +871,10 @@ interface TerminatedPayload {
signal: number | null
}
/** Event payload type */
/**
* The type of the data a child process writes to `stdout` and `stderr`:
* a `string`, or a `Uint8Array` when the `raw` encoding is configured.
*/
type IOPayload = string | Uint8Array
/** Events emitted by the child process. */
plugins/shell/guest-js/init.ts
+11
View File
@@ -2,6 +2,17 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT
/**
* Webview script injected by the shell plugin on every page load.
*
* It installs a `click` listener on `document.body` that intercepts clicks on
* `<a target="_blank">` elements whose `href` starts with `http://`, `https://`,
* `mailto:` or `tel:`, cancels the navigation and opens the link with the
* system's default application through the `plugin:shell|open` command instead.
*
* @module
*/
import { invoke } from '@tauri-apps/api/core'
// open <a href="..."> links with the API