shell(shell模块)

shell

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

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

API 必须添加到 tauri.conf.json 中的 tauri.allowlist.shell 中：


{
  "tauri": {
    "allowlist": {
      "shell": {
        "all": true, // 启用所有shell API
        "execute": true, // 启用进程生成API
        "sidecar": true, // 启用生成辅助进程
        "open": true // 启用使用默认程序打开文件/URL
      }
    }
  }
}

建议只允许列出您使用的 API，以优化程序包的大小和安全性。

安全

该 API 有一个作用域配置，可强制限制可使用的程序和参数。

限制访问`open` API

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

拒绝访问`Command` APIs

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

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

scope配置示例

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'])

尝试使用未在scope上配置的程序执行任何 API，都会因拒绝访问而导致promise被reject。

类别

`Child`

自1.1.0版本起

Constructors

`constructor`

new Child(pid: number): Child

参数

名称	类型
`pid`	`number`

定义在: shell.ts:325

属性

`pid`

pid: number

子进程pid。

定义在: shell.ts:323

方法

`kill`

kill(): Promise<void>

杀掉子进程。

返回值: Promise<void>

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

`write`

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

将数据写入 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]);

参数

名称	类型	描述
`data`	`string` \| `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版本起

层级

EventEmitter<"close" | "error">
- Command

构造函数

`constructor`

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

创建一个新的Command实例。

参数

名称	类型	默认值	描述
`program`	`string`	`undefined`	要执行的程序名称。必须在 `tauri.conf.json > tauri > allowlist > shell > scope` 上配置。
`args`	`string` \| `string`[]	`[]`	程序参数。
`options?`	`SpawnOptions`	`undefined`	生成选项。

重写: EventEmitter.constructor

定义在: shell.ts:413

属性

`stderr`

Readonly stderr: EventEmitter<"data">

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

定义在: shell.ts:403

`stdout`

Readonly stdout: EventEmitter<"data">

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

定义在: shell.ts:401

方法

`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是否已被添加。多次调用eventName和listener的相同组合将导致listener被多次添加和调用。

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

自1.0.0版本起

参数

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

返回值: Command

`once`

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

为名为eventName的事件添加一个单次监听器函数。下次事件名称被触发时，该监听器将被移除，然后再被调用。

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

自1.1.0版本起

参数

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

返回值: Command

`prependListener`

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

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

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

自1.1.0版本起

参数

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

返回值: Command

`prependOnceListener`

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

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

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

自1.1.0版本起

参数

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

返回值: Command

`removeAllListeners`

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

移除所有监听器或指定事件名称的监听器。

返回对 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();

示例

名称	类型	默认值	描述
`program`	`string`	`undefined`	要执行的程序。必须在 `tauri.conf.json > tauri > allowlist > shell > scope` 上配置。
`args`	`string` \| `string`[]	`[]`	-
`options?`	`SpawnOptions`	`undefined`	-

返回值: Command

`EventEmitter<E>`

自1.0.0版本起

类型参数

E extends string

层级

EventEmitter
- Command

构造函数

`constructor`

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

类型参数

E extends string

方法

`addListener`

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

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

自1.1.0版本起

参数

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

返回值: EventEmitter<E>

`listenerCount`

listenerCount(eventName: E): number

返回监听名为 eventName 的事件的监听者数量。

自1.1.0版本起

参数

名称	类型
`eventName`	`E`

返回值: number

`off`

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

从eventName事件的监听器数组中移除所有指定的监听器返回 EventEmitter 的引用，以便连锁调用。

自1.1.0版本起

参数

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

返回值: EventEmitter<E>

`on`

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

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

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

自1.0.0版本起

参数

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

返回值: EventEmitter<E>

`once`

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

为名为 eventName 的事件添加一个单次监听器函数。下次eventName被触发时，该监听器将被移除，然后再被调用。

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

自1.1.0版本起

参数

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

返回值: EventEmitter<E>

`prependListener`

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

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

自1.1.0版本起

参数

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

返回值: EventEmitter<E>

`prependOnceListener`

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

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

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

自1.1.0版本起

参数

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

返回值: EventEmitter<E>

`removeAllListeners`

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

移除所有监听器或指定事件名称的监听器。

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

自1.1.0版本起

参数

名称	类型
`event?`	`E`

返回值: EventEmitter<E>

`removeListener`

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

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

自1.1.0版本起

参数

名称	类型
`eventName`	`E`
`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`

Optional cwd: string

当前工作目录。

定义在: shell.ts:88

`encoding`

Optional encoding: string

stdout/stderr 的字符编码

自1.1.0版本起

定义在: shell.ts:96

`env`

Optional env: Record<string, string>

环境变量，设为null则清除进程 env。

定义在: shell.ts:90

方法

`open`

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

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

openWith的值必须是firefox, google chrome, chromium safari,
open, start, xdg-open, gio, gnome-open, kde-open or wslview其中的一个。

示例


import { open } from '@tauri-apps/api/shell';
// 在默认浏览器上打开给定的URL：
await open('https://github.com/tauri-apps/tauri');
// 用`firefox`浏览器打开给定的URL:
await open('https://github.com/tauri-apps/tauri', 'firefox');
// 用默认程序打开一个文件:
await open('/path/to/file');

自1.0.0版本起

参数

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

返回值: Promise<void>

process(进程模块)

tauri(tauri模块)

安全
- 限制访问open API
- 限制访问Command APIs
类别
接口
- ChildProcess
- SpawnOptions
方法
- open

shell

安全

限制访问open API

拒绝访问Command APIs

scope配置示例

类别

Child

Constructors

constructor

属性

pid

方法

kill

write

Command

构造函数

constructor

属性

stderr

stdout

方法

addListener

execute

listenerCount

off

on

once

prependListener

prependOnceListener

removeAllListeners

removeListener

spawn

sidecar

EventEmitter<E>

构造函数

constructor

方法

addListener

listenerCount

off

on

once

prependListener

prependOnceListener

removeAllListeners

removeListener

接口

ChildProcess

属性

code

signal

stderr

stdout

SpawnOptions

属性

cwd

encoding

env

方法

open

限制访问`open` API

拒绝访问`Command` APIs

`Child`

`constructor`

`pid`

`kill`

`write`

`Command`

`constructor`

`stderr`

`stdout`

`addListener`

`execute`

`listenerCount`

`off`

`on`

`once`

`prependListener`

`prependOnceListener`

`removeAllListeners`

`removeListener`

`spawn`

`sidecar`

`EventEmitter<E>`

`constructor`

`addListener`

`listenerCount`

`off`

`on`

`once`

`prependListener`

`prependOnceListener`

`removeAllListeners`

`removeListener`

`ChildProcess`

`code`

`signal`

`stderr`

`stdout`

`SpawnOptions`

`cwd`

`encoding`

`env`

`open`