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
参数
名称 | 类型 |
---|---|
pid | number |
**定义于:** 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]);
参数
名称 | 类型 | 描述 |
---|---|---|
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: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
。多次调用传递相同的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
函数到监听器数组的开头。下次触发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
将命令作为子进程执行,并返回其句柄。
解析为子进程句柄的 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
扩展string
继承关系
- EventEmitter
构造函数
constructor
new EventEmitter<
E
>():EventEmitter
<E
>
类型参数
E
扩展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
>
将listener
函数添加到名为eventName
的事件的侦听器数组的末尾。不会检查是否已添加listener
。多次调用传递相同的eventName
和listener
组合将导致listener
被多次添加和调用。
返回对 EventEmitter 的引用,以便可以链接调用。
自: 1.0.0
参数
名称 | 类型 |
---|---|
eventName | E |
listener | (...args : any []) => void |
返回值: EventEmitter
<E
>
once
once(
eventName
:E
,listener
:fn
):EventEmitter
<E
>
为名为eventName
的事件添加一个**一次性**的listener
函数。下次触发eventName
时,此侦听器将被移除,然后被调用。
返回对 EventEmitter 的引用,以便可以链接调用。
自: 1.1.0
参数
名称 | 类型 |
---|---|
eventName | E |
listener | (...args : any []) => void |
返回值: EventEmitter
<E
>
prependListener
prependListener(
eventName
:E
,listener
:fn
):EventEmitter
<E
>
将listener
函数添加到名为eventName
的事件的监听器数组的开头。不会检查listener
是否已添加。多次调用传递相同的eventName
和listener
组合将导致listener
被多次添加和调用。
返回对 EventEmitter 的引用,以便可以链接调用。
自: 1.1.0
参数
名称 | 类型 |
---|---|
eventName | E |
listener | (...args : any []) => void |
返回值: EventEmitter
<E
>
prependOnceListener
prependOnceListener(
eventName
:E
,listener
:fn
):EventEmitter
<E
>
为名为eventName
的事件添加一个一次性listener
函数到监听器数组的开头。下次触发eventName
时,此监听器将被移除,然后调用。
返回对 EventEmitter 的引用,以便可以链接调用。
自: 1.1.0
参数
名称 | 类型 |
---|---|
eventName | E |
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
参数
名称 | 类型 |
---|---|
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
可选
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
>