@tauri-apps/plugin-shell
访问系统外壳。允许您使用默认应用程序 spawning 子进程和管理文件和 URL。
安全
此 API 具有作用域配置,该配置强制您限制可使用的程序和参数。
限制对 open
API 的访问
在配置对象中,open: true
表示可以与任何 URL 使用 open API,因为参数将通过 ^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+
正则表达式进行验证。您可以通过将布尔值更改为字符串来更改该正则表达式,例如 open: ^https://github.com/
。
限制对 Command
API 的访问
插件权限对象有一个 scope
字段,它定义了一个可以使用的一组 CLIs。每个 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'])
尝试执行任何不在作用域上配置的程序,会导致由于拒绝访问而导致的 promise 拒绝。
类
子类
自
2.0.0
构造函数
new Child()
new Child(pid): Child
参数
参数 | 类型 |
---|---|
进程ID | 数量 |
返回值
来源: 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
>
表示操作成功或失败的山现。
自
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
。
参数
参数 | 类型 | 描述 |
---|---|---|
数据 | IOPayload | number [] | 要写入的消息,可以是字符串或字节数组。 |
返回值
Promise
<void
>
表示操作成功或失败的山现。
示例
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
扩展
类型参数
类型参数 |
---|
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 |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (arg ) => void |
返回值
this
自
2.0.0
继承自
来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L118
execute()
execute(): Promise<ChildProcess<O>>
以子进程的方式执行命令,等待其完成并收集所有输出。
返回值
Promise
<ChildProcess
<O
>>
解析为子进程输出的山现。
示例
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 |
参数
参数 | 类型 |
---|---|
事件名 | 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 keyof CommandEvents |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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 keyof CommandEvents |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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 keyof CommandEvents |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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 keyof CommandEvents |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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 keyof CommandEvents |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (arg ) => void |
返回值
this
自
2.0.0
继承自
EventEmitter
.prependOnceListener
来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L280
removeAllListeners()
removeAllListeners<N>(event?): this
移除所有监听器或指定的事件名的那些监听器。
返回对EventEmitter
的引用,以便可以进行链式调用。
类型参数
类型参数 |
---|
N extends keyof CommandEvents |
参数
参数 | 类型 |
---|---|
事件 ? | N |
返回值
this
自
2.0.0
继承自
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 |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (arg ) => void |
返回值
this
自
2.0.0
继承自
来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L130
spawn()
spawn(): Promise<Child>
作为子进程执行命令,返回对此进程的句柄。
返回值
一个解析为子进程句柄的承诺。
自
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();
参数
要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope
中配置。
create(program, args)
static create(program, args?): Command<string>
创建一个执行给定程序的命令。
参数
参数 | 类型 |
---|---|
program | 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();
参数
要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope
中配置。
来源: 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<ArrayBufferLike>>
创建一个执行给定程序的命令。
参数
参数 | 类型 |
---|---|
program | string |
args ? | string | string [] |
options ? | SpawnOptions & object |
返回值
Command
<Uint8Array
<ArrayBufferLike
>>
示例
import { Command } from '@tauri-apps/plugin-shell';const command = Command.create('my-app', ['run', 'tauri']);const output = await command.execute();
参数
要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope
中配置。
来源: 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>
创建一个执行给定程序的命令。
参数
参数 | 类型 |
---|---|
program | string |
args ? | string | string [] |
options ? | SpawnOptions |
返回值
Command
<string
>
示例
import { Command } from '@tauri-apps/plugin-shell';const command = Command.create('my-app', ['run', 'tauri']);const output = await command.execute();
参数
要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope
中配置。
来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L412
sidecar()
创建一个执行给定辅助程序的命令。
示例
import { Command } from '@tauri-apps/plugin-shell';const command = Command.sidecar('my-sidecar');const output = await command.execute();
参数
要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope
中配置。
sidecar(program, args)
static sidecar(program, args?): Command<string>
创建一个执行给定辅助程序的命令。
参数
参数 | 类型 |
---|---|
program | string |
args ? | string | string [] |
返回值
Command
<string
>
示例
import { Command } from '@tauri-apps/plugin-shell';const command = Command.sidecar('my-sidecar');const output = await command.execute();
参数
要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope
中配置。
来源: 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<ArrayBufferLike>>
创建一个执行给定辅助程序的命令。
参数
参数 | 类型 |
---|---|
program | string |
args ? | string | string [] |
options ? | SpawnOptions & object |
返回值
Command
<Uint8Array
<ArrayBufferLike
>>
示例
import { Command } from '@tauri-apps/plugin-shell';const command = Command.sidecar('my-sidecar');const output = await command.execute();
参数
要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope
中配置。
来源: 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>
创建一个执行给定辅助程序的命令。
参数
参数 | 类型 |
---|---|
program | string |
args ? | string | string [] |
options ? | SpawnOptions |
返回值
Command
<string
>
示例
import { Command } from '@tauri-apps/plugin-shell';const command = Command.sidecar('my-sidecar');const output = await command.execute();
参数
要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope
中配置。
来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L444
EventEmitter<E>
自
2.0.0
由...扩展
类型参数
类型参数 |
---|
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 |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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 |
参数
参数 | 类型 |
---|---|
事件名 | 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 |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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 |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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 |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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 |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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 |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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
移除所有监听器或指定的事件名的那些监听器。
返回对EventEmitter
的引用,以便可以进行链式调用。
类型参数
类型参数 |
---|
N extends string | number | symbol |
参数
参数 | 类型 |
---|---|
事件 ? | 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 |
参数
参数 | 类型 |
---|---|
事件名 | N |
监听器 | (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
属性
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 | 标准输出/标准错误字符编码 自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
命令事件的有效负载。
属性
属性 | 类型 | 描述 | 定义于 |
---|---|---|---|
code | null | number | 进程的退出码。在Unix上,如果进程被信号终止,则为 null 。 | 源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L560 |
signal | null | number | 如果进程被信号终止,表示该信号。 | 源: 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
。
参数
参数 | 类型 | 描述 |
---|---|---|
路径 | 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
© 2025 Tauri 贡献者。CC-BY / MIT