跳至主要内容

shell

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

当 `tauri.conf.json` 文件中的 build.withGlobalTauri 设置为 true 时,也可以通过 `window.__TAURI__.shell` 访问此包。

必须将 API 添加到 `tauri.conf.json` 文件中的 tauri.allowlist.shell

{
"tauri": {
"allowlist": {
"shell": {
"all": true, // enable all shell APIs
"execute": true, // enable process spawn APIs
"sidecar": true, // enable spawning sidecars
"open": true // enable opening files/URLs using the default program
}
}
}
}

建议只允许列出你使用的 API,以优化包大小和安全性。

安全

此 API 具有作用域配置,强制你限制可以使用哪些程序和参数。

限制对 open API 的访问

在允许列表中,open: true 表示可以使用任何 URL 使用 open API,因为参数使用正则表达式 ^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+ 进行验证。你可以通过将布尔值更改为字符串来更改该正则表达式,例如 open: ^https://github.com/

限制对 Command API 的访问

shell 允许列表对象具有一个 scope 字段,该字段定义可以使用哪些 CLI 的数组。每个 CLI 都是一个配置对象 { name: string, cmd: string, sidecar?: bool, args?: boolean | Arg[] }

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

示例作用域配置

CLI:git commit -m "the commit message"

配置

{
"scope": [
{
"name": "run-git-commit",
"cmd": "git",
"args": ["commit", "-m", { "validator": "\\S+" }]
}
]
}

用法

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

尝试使用作用域中未配置的程序执行任何 API 将导致由于拒绝访问而导致 Promise 拒绝。

Child

: 1.1.0

构造函数

constructor

**new Child**(pid: number): Child

参数

名称类型
pidnumber

**定义于:** shell.ts:293

属性

pid

**pid**: number

子进程的 `pid`。

**定义于:** shell.ts:291

方法

kill

**kill**(): Promise<void>

杀死子进程。

**返回:** Promise<void>

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

write

**write**(data: string| Uint8Array): Promise<void>

data写入stdin

示例

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

参数

名称类型描述
datastring | Uint8Array要写入的消息,可以是字符串或字节数组。

**返回:** Promise<void>

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

Command

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

示例

import { Command } from '@tauri-apps/api/shell';
const command = new Command('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);

: 1.1.0

继承关系

构造函数

constructor

**new Command**(program: string, args?: string| string[], options?: SpawnOptions): Command

创建一个新的Command实例。

参数

名称类型默认值描述
programstringundefined要执行的程序名称。
它必须在tauri.conf.json > tauri > allowlist > shell > scope中配置。
argsstring | string[][]程序参数。
options?SpawnOptionsundefined生成选项。

**重写:** EventEmitter.constructor

**定义于:** shell.ts:381

属性

stderr

Readonly stderr: EventEmitter<"data">

stderr的事件发射器。发出data事件。

**定义于:** shell.ts:371

stdout

Readonly stdout: EventEmitter<"data">

stdout的事件发射器。发出data事件。

**定义于:** shell.ts:369

方法

addListener

**addListener**(eventName: "error"| "close", listener: fn): Command

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

: 1.1.0

参数

名称类型
eventName"error" | "close"
listener(...args: any[]) => void

**返回:** Command

execute

**execute**(): Promise<ChildProcess>

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

示例

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

**返回:** Promise<ChildProcess>

解析为子进程输出的 Promise。

listenerCount

**listenerCount**(eventName: "error"| "close"): number

返回侦听名为eventName的事件的侦听器数量。

: 1.1.0

参数

名称类型
eventName"error" | "close"

**返回:** number

off

**off**(eventName: "error"| "close", listener: fn): Command

从事件 eventName 的侦听器数组中移除所有指定的侦听器。返回对 EventEmitter 的引用,以便可以链接调用。

: 1.1.0

参数

名称类型
eventName"error" | "close"
listener(...args: any[]) => void

**返回:** Command

on

**on**(eventName: "error"| "close", listener: fn): Command

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

返回对 EventEmitter 的引用,以便可以链接调用。

: 1.0.0

参数

名称类型
eventName"error" | "close"
listener(...args: any[]) => void

**返回:** Command

once

**once**(eventName: "error"| "close", listener: fn): Command

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

返回对 EventEmitter 的引用,以便可以链接调用。

: 1.1.0

参数

名称类型
eventName"error" | "close"
listener(...args: any[]) => void

**返回:** Command

prependListener

**prependListener**(eventName: "error"| "close", listener: fn): Command

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

返回对 EventEmitter 的引用,以便可以链接调用。

: 1.1.0

参数

名称类型
eventName"error" | "close"
listener(...args: any[]) => void

**返回:** Command

prependOnceListener

prependOnceListener(eventName: "error"| "close", listener: fn): Command

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

返回对 EventEmitter 的引用,以便可以链接调用。

: 1.1.0

参数

名称类型
eventName"error" | "close"
listener(...args: any[]) => void

**返回:** Command

removeAllListeners

removeAllListeners(event?: "error"| "close"): Command

移除所有监听器,或指定 eventName 的监听器。

返回对 EventEmitter 的引用,以便可以链接调用。

: 1.1.0

参数

名称类型
event?"error" | "close"

**返回:** Command

removeListener

removeListener(eventName: "error"| "close", listener: fn): Command

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

: 1.1.0

参数

名称类型
eventName"error" | "close"
listener(...args: any[]) => void

**返回:** Command

spawn

spawn(): Promise<Child>

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

返回值: Promise<Child>

解析为子进程句柄的 Promise。

sidecar

Static sidecar(program: string, args?: string| string[], options?: SpawnOptions): Command

创建一个命令来执行给定的 sidecar 程序。

示例

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

参数

名称类型默认值描述
programstringundefined要执行的程序。
它必须在tauri.conf.json > tauri > allowlist > shell > scope中配置。
argsstring | string[][]-
options?SpawnOptionsundefined-

**返回:** Command

EventEmitter<E>

: 1.0.0

类型参数

  • E 扩展 string

继承关系

构造函数

constructor

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

类型参数

  • E 扩展 string

方法

addListener

addListener(eventName: E, listener: fn): EventEmitter<E>

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

: 1.1.0

参数

名称类型
eventNameE
listener(...args: any[]) => void

返回值: EventEmitter<E>

listenerCount

listenerCount(eventName: E): number

返回侦听名为eventName的事件的侦听器数量。

: 1.1.0

参数

名称类型
eventNameE

**返回:** number

off

off(eventName: E, listener: fn): EventEmitter<E>

从事件 eventName 的侦听器数组中移除所有指定的侦听器。返回对 EventEmitter 的引用,以便可以链接调用。

: 1.1.0

参数

名称类型
eventNameE
listener(...args: any[]) => void

返回值: EventEmitter<E>

on

on(eventName: E, listener: fn): EventEmitter<E>

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

返回对 EventEmitter 的引用,以便可以链接调用。

: 1.0.0

参数

名称类型
eventNameE
listener(...args: any[]) => void

返回值: EventEmitter<E>

once

once(eventName: E, listener: fn): EventEmitter<E>

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

返回对 EventEmitter 的引用,以便可以链接调用。

: 1.1.0

参数

名称类型
eventNameE
listener(...args: any[]) => void

返回值: EventEmitter<E>

prependListener

prependListener(eventName: E, listener: fn): EventEmitter<E>

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

返回对 EventEmitter 的引用,以便可以链接调用。

: 1.1.0

参数

名称类型
eventNameE
listener(...args: any[]) => void

返回值: EventEmitter<E>

prependOnceListener

prependOnceListener(eventName: E, listener: fn): EventEmitter<E>

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

返回对 EventEmitter 的引用,以便可以链接调用。

: 1.1.0

参数

名称类型
eventNameE
listener(...args: any[]) => void

返回值: EventEmitter<E>

removeAllListeners

removeAllListeners(event?: E): EventEmitter<E>

移除所有监听器,或指定 eventName 的监听器。

返回对 EventEmitter 的引用,以便可以链接调用。

: 1.1.0

参数

名称类型
event?E

返回值: EventEmitter<E>

removeListener

removeListener(eventName: E, listener: fn): EventEmitter<E>

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

: 1.1.0

参数

名称类型
eventNameE
listener(...args: any[]) => void

返回值: EventEmitter<E>

接口

ChildProcess

: 1.0.0

属性

code

code: null| number

进程的退出代码。如果进程在 Unix 上被信号终止,则为 null

定义于: shell.ts:109

signal

signal: null| number

如果进程被信号终止,则表示该信号。

定义于: shell.ts:111

stderr

stderr: string

进程写入 stderr 的数据。

定义于: shell.ts:115

stdout

stdout: string

进程写入 stdout 的数据。

定义于: shell.ts:113

SpawnOptions

: 1.0.0

属性

cwd

可选 cwd: string

当前工作目录。

定义于: shell.ts:88

encoding

可选 encoding: string

stdout/stderr 的字符编码

: 1.1.0

定义于: shell.ts:96

env

可选 env: Record<string, string>

环境变量。设置为 null 以清除进程环境。

定义于: shell.ts:90

函数

open

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

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

openWith值必须是firefoxgoogle chromechromiumsafariopenstartxdg-opengiognome-openkde-openwslview之一。

示例

import { open } from '@tauri-apps/api/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');

: 1.0.0

参数

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

**返回:** Promise<void>