跳至主要内容

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 表示 open API 可用于任何 URL，因为参数使用 ^((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：命令的唯一标识符，传递给 命令构造函数。如果它是 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:325

属性​

pid​

pid: number

子进程 pid。

定义于： shell.ts:323

方法​

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 实例。

参数

名称类型默认值说明
programstring未定义要执行的程序名称。
它必须在 tauri.conf.json > tauri > allowlist > shell > scope 中配置。
argsstring | string[][]程序参数。
options?SpawnOptions未定义Spawn 选项。

覆盖： 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 的事件添加一次性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 是否已添加。多次调用传递相同的 eventName 和 listener 组合将导致添加 listener 并多次调用它。

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

自: 1.1.0

参数

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

返回： Command

prependOnceListener​

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

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

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

自: 1.1.0

参数

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

返回： Command

removeAllListeners​

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

移除所有 listener，或移除指定 eventName 的 listener。

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

参数

名称类型默认值说明
programstring未定义要执行的程序。
它必须在 tauri.conf.json > tauri > allowlist > shell > scope 中配置。
argsstring | string[][]-
options?SpawnOptions未定义-

返回： Command

EventEmitter<E>​

自: 1.0.0

类型参数

  • E extends string

层次结构

构造函数​

constructor​

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

类型参数

  • E extends 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 是否已添加。多次调用传递相同的 eventName 和 listener 组合将导致添加 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 是否已添加。多次调用传递相同的 eventName 和 listener 组合将导致添加 listener 并多次调用它。

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

自: 1.1.0

参数

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

返回: EventEmitter<E>

prependOnceListener​

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

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

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

自: 1.1.0

参数

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

返回: EventEmitter<E>

removeAllListeners​

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

移除所有 listener，或移除指定 eventName 的 listener。

返回对 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 值必须为 firefox、google chrome、chromium safari、open、start、xdg-open、gio、gnome-open、kde-open 或 wslview 之一。

示例

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>