@tauri-apps/plugin-shell

访问系统 shell。允许您生成子进程并使用其默认应用程序管理文件和 URL。

安全

此 API 具有范围配置，强制您限制可使用的程序和参数。

限制对 open API 的访问

在配置对象上，open: true 表示 open API 可与任何 URL 一起使用，因为参数通过 `^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+` 正则表达式进行验证。您可以通过将布尔值更改为字符串来更改该正则表达式，例如 open: ^https://github.com/。

限制对 Command API 的访问

插件权限对象有一个 scope 字段，它定义了可以使用的 CLI 数组。每个 CLI 都是一个配置对象 { name: string, cmd: string, sidecar?: bool, args?: boolean | Arg[] }。

• name: 命令的唯一标识符，传递给 Command.create 函数。如果是 sidecar，这必须是 tauri.conf.json > bundle > externalBin 中定义的值。
• cmd: 在此配置上执行的程序。如果是 sidecar，则此值将被忽略。
• sidecar: 对象是配置 sidecar 还是系统程序。
• args: 可以传递给程序的参数。默认情况下不允许任何参数。
  • true 表示允许任何参数列表。
  • false 表示不允许任何参数。
  • 否则可以配置一个数组。每个项都是表示固定参数值的字符串，或者定义正则表达式验证参数值的 { validator: string }。

作用域配置示例

CLI: git commit -m "the commit message"

功能

{
  "permissions": [
    {
      "identifier": "shell:allow-execute",
      "allow": [
        {
          "name": "run-git-commit",
          "cmd": "git",
          "args": ["commit", "-m", { "validator": "\\S+" }]
        }
      ]
    }
  ]
}

用法

import { Command } from '@tauri-apps/plugin-shell'
Command.create('run-git-commit', ['commit', '-m', 'the commit message'])

尝试使用未在作用域中配置的程序执行任何 API 将导致因拒绝访问而拒绝承诺。

类

Child

始于

2.0.0

构造函数

new Child()

new Child(pid): Child

参数

参数	类型
pid	数字

返回

Child

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L301

属性

属性	类型	描述	定义于
pid	数字	子进程 pid。	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L299

方法

kill()

kill(): Promise<void>

终止子进程。

返回

Promise<void>

表示操作成功或失败的 Promise。

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L336

write()

write(data): Promise<void>

将 data 写入 stdin。

参数

参数	类型	描述
data	IOPayload | number[]	要写入的消息，可以是字符串或字节数组。

返回

Promise<void>

表示操作成功或失败的 Promise。

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
const child = await command.spawn();
await child.write('message');
await child.write([0, 1, 2, 3, 4, 5]);

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L322

---

Command<O>

用于生成子进程的入口点。它发出 close 和 error 事件。

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.on('close', data => {
  console.log(`command finished with code ${data.code} and signal ${data.signal}`)
});
command.on('error', error => console.error(`command error: "${error}"`));
command.stdout.on('data', line => console.log(`command stdout: "${line}"`));
command.stderr.on('data', line => console.log(`command stderr: "${line}"`));

const child = await command.spawn();
console.log('pid:', child.pid);

始于

2.0.0

继承 (Extends)

• EventEmitter<CommandEvents>

类型参数

类型参数
O extends IOPayload

属性

属性	修饰符	类型	描述	定义于
stderr	只读	EventEmitter<OutputEvents<O>>	stderr 的事件发射器。发出 data 事件。	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L384
stdout	只读	EventEmitter<OutputEvents<O>>	stdout 的事件发射器。发出 data 事件。	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L382

方法

addListener()

addListener<N>(eventName, listener): this

emitter.on(eventName, listener) 的别名。

类型参数

类型参数
N extends keyof CommandEvents

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

继承自 (Inherited from)

EventEmitter.addListener

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L118

execute()

execute(): Promise<ChildProcess<O>>

将命令作为子进程执行，等待其完成并收集所有输出。

返回

Promise<ChildProcess<O>>

解析为子进程输出的 Promise。

示例

import { Command } from '@tauri-apps/plugin-shell';
const output = await Command.create('echo', 'message').execute();
assert(output.code === 0);
assert(output.signal === null);
assert(output.stdout === 'message');
assert(output.stderr === '');

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L530

listenerCount()

listenerCount<N>(eventName): number

返回监听事件 eventName 的监听器数量。

类型参数

类型参数
N extends keyof CommandEvents

参数

参数	类型
eventName	N

返回

数字

始于

2.0.0

继承自 (Inherited from)

EventEmitter.listenerCount

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L241

off()

off<N>(eventName, listener): this

从事件 eventName 的监听器数组中删除所有指定的监听器。返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends keyof CommandEvents

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

继承自 (Inherited from)

EventEmitter.off

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L186

on()

on<N>(eventName, listener): this

将 listener 函数添加到事件 eventName 的监听器数组的末尾。不检查 listener 是否已添加。多次调用传入相同的 eventName 和 listener 组合将导致 listener 被多次添加和调用。

返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends keyof CommandEvents

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

继承自 (Inherited from)

EventEmitter.on

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L147

once()

once<N>(eventName, listener): this

为事件 eventName 添加一个**一次性** listener 函数。下次触发 eventName 时，此监听器将被移除，然后被调用。

返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends keyof CommandEvents

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

继承自 (Inherited from)

EventEmitter.once

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L169

prependListener()

prependListener<N>(eventName, listener): this

将 listener 函数添加到事件 eventName 的监听器数组的开头。不检查 listener 是否已添加。多次调用传入相同的 eventName 和 listener 组合将导致 listener 被多次添加和调用。

返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends keyof CommandEvents

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

继承自 (Inherited from)

EventEmitter.prependListener

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L258

prependOnceListener()

prependOnceListener<N>(eventName, listener): this

为事件 eventName 添加一个**一次性** listener 函数到监听器数组的_开头_。下次触发 eventName 时，此监听器将被移除，然后被调用。

返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends keyof CommandEvents

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

继承自 (Inherited from)

EventEmitter.prependOnceListener

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L280

removeAllListeners()

removeAllListeners<N>(event?): this

删除所有监听器，或指定 eventName 的监听器。

返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends keyof CommandEvents

参数

参数	类型
event?	N

返回

this

始于

2.0.0

继承自 (Inherited from)

EventEmitter.removeAllListeners

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L206

removeListener()

removeListener<N>(eventName, listener): this

emitter.off(eventName, listener) 的别名。

类型参数

类型参数
N extends keyof CommandEvents

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

继承自 (Inherited from)

EventEmitter.removeListener

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L130

spawn()

spawn(): Promise<Child>

将命令作为子进程执行，返回其句柄。

返回

Promise<Child>

解析为子进程句柄的 Promise。

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L479

create()

创建命令以执行给定程序。

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri']);
const output = await command.execute();

参数

要执行的程序。它必须在您的项目功能中配置。

create(program, args)

static create(program, args?): Command<string>

创建命令以执行给定程序。

参数

参数	类型
程序	string
args?	string | string[]

返回

Command<string>

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri']);
const output = await command.execute();

参数

要执行的程序。它必须在您的项目功能中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L406

create(program, args, options)

static create(
   program,
   args?,
options?): Command<Uint8Array>

创建命令以执行给定程序。

参数

参数	类型
程序	string
args?	string | string[]
选项?	SpawnOptions & object

返回

Uint8Array<Command>

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri']);
const output = await command.execute();

参数

要执行的程序。它必须在您的项目功能中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L407

create(program, args, options)

static create(
   program,
   args?,
options?): Command<string>

创建命令以执行给定程序。

参数

参数	类型
程序	string
args?	string | string[]
选项?	SpawnOptions

返回

Command<string>

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri']);
const output = await command.execute();

参数

要执行的程序。它必须在您的项目功能中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L412

sidecar()

创建命令以执行给定的 sidecar 程序。

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar');
const output = await command.execute();

参数

要执行的程序。它必须在您的项目功能中配置。

sidecar(program, args)

static sidecar(program, args?): Command<string>

创建命令以执行给定的 sidecar 程序。

参数

参数	类型
程序	string
args?	string | string[]

返回

Command<string>

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar');
const output = await command.execute();

参数

要执行的程序。它必须在您的项目功能中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L438

sidecar(program, args, options)

static sidecar(
   program,
   args?,
options?): Command<Uint8Array>

创建命令以执行给定的 sidecar 程序。

参数

参数	类型
程序	string
args?	string | string[]
选项?	SpawnOptions & object

返回

Uint8Array<Command>

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar');
const output = await command.execute();

参数

要执行的程序。它必须在您的项目功能中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L439

sidecar(program, args, options)

static sidecar(
   program,
   args?,
options?): Command<string>

创建命令以执行给定的 sidecar 程序。

参数

参数	类型
程序	string
args?	string | string[]
选项?	SpawnOptions

返回

Command<string>

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar');
const output = await command.execute();

参数

要执行的程序。它必须在您的项目功能中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L444

---

EventEmitter<E>

始于

2.0.0

扩展自

• Command

类型参数

类型参数
E extends Record<string, any>

构造函数

new EventEmitter()

new EventEmitter<E>(): EventEmitter<E>

返回

EventEmitter<E>

方法

addListener()

addListener<N>(eventName, listener): this

emitter.on(eventName, listener) 的别名。

类型参数

类型参数
N extends string | number | symbol

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L118

listenerCount()

listenerCount<N>(eventName): number

返回监听事件 eventName 的监听器数量。

类型参数

类型参数
N extends string | number | symbol

参数

参数	类型
eventName	N

返回

数字

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L241

off()

off<N>(eventName, listener): this

从事件 eventName 的监听器数组中删除所有指定的监听器。返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends string | number | symbol

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L186

on()

on<N>(eventName, listener): this

将 listener 函数添加到事件 eventName 的监听器数组的末尾。不检查 listener 是否已添加。多次调用传入相同的 eventName 和 listener 组合将导致 listener 被多次添加和调用。

返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends string | number | symbol

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L147

once()

once<N>(eventName, listener): this

为事件 eventName 添加一个**一次性** listener 函数。下次触发 eventName 时，此监听器将被移除，然后被调用。

返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends string | number | symbol

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L169

prependListener()

prependListener<N>(eventName, listener): this

将 listener 函数添加到事件 eventName 的监听器数组的开头。不检查 listener 是否已添加。多次调用传入相同的 eventName 和 listener 组合将导致 listener 被多次添加和调用。

返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends string | number | symbol

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L258

prependOnceListener()

prependOnceListener<N>(eventName, listener): this

为事件 eventName 添加一个**一次性** listener 函数到监听器数组的_开头_。下次触发 eventName 时，此监听器将被移除，然后被调用。

返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends string | number | symbol

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L280

removeAllListeners()

removeAllListeners<N>(event?): this

删除所有监听器，或指定 eventName 的监听器。

返回对 EventEmitter 的引用，以便可以链式调用。

类型参数

类型参数
N extends string | number | symbol

参数

参数	类型
event?	N

返回

this

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L206

removeListener()

removeListener<N>(eventName, listener): this

emitter.off(eventName, listener) 的别名。

类型参数

类型参数
N extends string | number | symbol

参数

参数	类型
eventName	N
listener	(arg) => void

返回

this

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L130

接口

ChildProcess<O>

始于

2.0.0

类型参数

类型参数
O extends IOPayload

属性

属性	类型	描述	定义于
code	null | number	进程的退出代码。如果进程在 Unix 上被信号终止，则为 null。	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L94
signal	null | number	如果进程被信号终止，则表示该信号。	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L96
stderr	O	进程写入 stderr 的数据。	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L100
stdout	O	进程写入 stdout 的数据。	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L98

---

CommandEvents

属性

属性	类型	定义于
close	TerminatedPayload	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L345
error	string	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L346

---

OutputEvents<O>

类型参数

类型参数
O extends IOPayload

属性

属性	类型	定义于
data	O	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L350

---

SpawnOptions

始于

2.0.0

属性

属性	类型	描述	定义于
cwd?	string	当前工作目录。	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L73
encoding?	string	stdout/stderr 的字符编码 自 2.0.0	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L81
env?	Record<string, string>	环境变量。设置为 null 以清除进程环境。	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L75

---

TerminatedPayload

针对 Terminated 命令事件的 Payload。

属性

属性	类型	描述	定义于
code	null | number	进程的退出代码。如果进程在 Unix 上被信号终止，则为 null。	来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L560
signal	null | number	如果进程被信号终止，则表示该信号。	如果进程被信号终止，则表示该信号。

类型别名 (Type Aliases)

https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L562

IOPayload

type IOPayload: string | Uint8Array;

事件载荷类型

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L566

函数

open()

function open(path, openWith?): Promise<void>

使用系统的默认应用程序或通过 openWith 指定的应用程序打开路径或 URL。

openWith 的值必须是 firefox、google chrome、chromium safari、open、start、xdg-open、gio、gnome-open、kde-open 或 wslview 之一。

参数

参数	类型	描述
path	string	要打开的路径或 URL。此值与 tauri.conf.json > plugins > shell > open 中定义的字符串正则表达式匹配，默认为 `^((mailto:\w+)
openWith?	string	用于打开文件或 URL 的应用程序。默认为指定路径类型的系统默认应用程序。

返回

Promise<void>

示例

import { open } from '@tauri-apps/plugin-shell';
// opens the given URL on the default browser:
await open('https://github.com/tauri-apps/tauri');
// opens the given URL using `firefox`:
await open('https://github.com/tauri-apps/tauri', 'firefox');
// opens a file using the default program:
await open('/path/to/file');

始于

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L601