# Toast

当发生异步操作或引发错误时，通常最好让用户了解情况。Toast 就是为此而做的。

此外，Toast 可以有一些与其相关操作相关的操作。例如，您可以提供一种方法来取消异步操作、撤消操作或复制错误的堆栈跟踪。

![](https://1964008511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYERqqbndxGykbCZ2IQg%2Fuploads%2Fgit-blob-cc894e046e9535f419e102973ca783b0ca520026%2Ftoast.png?alt=media)

## API 参考

### showToast

创建并显示具有给定 [选项](#toast.options) 的 Toast。

#### 签名

```typescript
async function showToast(options: Toast.Options): Promise<Toast>;
```

#### 例子

```typescript
import { showToast, Toast } from "@raycast/api";

export default async function Command() {
  const success = false;

  if (success) {
    await showToast({ title: "Dinner is ready", message: "Pizza margherita" });
  } else {
    await showToast({
      style: Toast.Style.Failure,
      title: "Dinner isn't ready",
      message: "Pizza dropped on the floor",
    });
  }
}
```

当显示动画 Toast 时，您可以稍后更新它：

```typescript
import { showToast, Toast } from "@raycast/api";
import { setTimeout } from "timers/promises";

export default async function Command() {
  const toast = await showToast({
    style: Toast.Style.Animated,
    title: "Uploading image",
  });

  try {
    // upload the image
    await setTimeout(1000);

    toast.style = Toast.Style.Success;
    toast.title = "Uploaded image";
  } catch (err) {
    toast.style = Toast.Style.Failure;
    toast.title = "Failed to upload image";
    if (err instanceof Error) {
      toast.message = err.message;
    }
  }
}
```

#### 参数

| 名称                                        | 描述             | 类型                                                                                   |
| ----------------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
| options<mark style="color:red;">\*</mark> | 自定义 Toast 的选项。 | [`Alert.Options`](https://raycast-doc.gitbook.io/zh/api-can-kao/alert#alert.options) |

#### 返回

展示 Toast  状态为 resolves 的 Promise， Toast 可用于更改或隐藏它。

## 类型

### Toast

具有特定样式、标题和消息的 Toast。

使用 [showToast](#showtoast) 创建并显示 Toast。

#### 属性

| 名称                                                | 描述                                   | 类型                                                                                               |
| ------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| message<mark style="color:red;">\*</mark>         | Toast 的附加消息。有助于显示更多信息，例如新创建的资源的标识符。  | `string`                                                                                         |
| primaryAction<mark style="color:red;">\*</mark>   | 用户将鼠标悬停在 Toast 上时可以执行的 primary 操作。   | [`Alert.ActionOptions`](https://raycast-doc.gitbook.io/zh/api-can-kao/alert#alert.actionoptions) |
| secondaryAction<mark style="color:red;">\*</mark> | 用户将鼠标悬停在 Toast 上时可以执行的 secondary 操作。 | [`Alert.ActionOptions`](https://raycast-doc.gitbook.io/zh/api-can-kao/alert#alert.actionoptions) |
| style<mark style="color:red;">\*</mark>           | Toast 的样式。                           | [`Action.Style`](https://raycast-doc.gitbook.io/zh/user-interface/actions#action.style)          |
| title<mark style="color:red;">\*</mark>           | Toast 的标题，显示在顶部。                     | `string`                                                                                         |

#### 方法

| 名称   | 类型                    | 描述       |
| ---- | --------------------- | -------- |
| hide | `() => Promise<void>` | 隐藏 Toast |
| show | `() => Promise<void>` | 显示 Toast |

### Toast.Options

创建 Toast 的配置项。

#### 例子

```typescript
import { showToast, Toast } from "@raycast/api";

export default async function Command() {
  const options: Toast.Options = {
    style: Toast.Style.Success,
    title: "Finished cooking",
    message: "Delicious pasta for lunch",
    primaryAction: {
      title: "Do something",
      onAction: (toast) => {
        console.log("The toast action has been triggered");
        toast.hide();
      },
    },
  };
  await showToast(options);
}
```

#### 属性

| 名称                                      | 描述                                   | 类型                                                                                               |
| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| title<mark style="color:red;">\*</mark> | Toast 的标题，显示在顶部。                     | `string`                                                                                         |
| message                                 | Toast 的附加消息。有助于显示更多信息，例如新创建的资源的标识符。  | `string`                                                                                         |
| primaryAction                           | 用户将鼠标悬停在 Toast 上时可以执行的 primary 操作。   | [`Alert.ActionOptions`](https://raycast-doc.gitbook.io/zh/api-can-kao/alert#alert.actionoptions) |
| secondaryAction                         | 用户将鼠标悬停在 Toast 上时可以执行的 secondary 操作。 | [`Alert.ActionOptions`](https://raycast-doc.gitbook.io/zh/api-can-kao/alert#alert.actionoptions) |
| style                                   | Toast 的样式。                           | [`Action.Style`](https://raycast-doc.gitbook.io/zh/user-interface/actions#action.style)          |

### Toast.Style

定义 Toast 的样式。

使用 [Toast.Style.Success](#toast.style) 进行确认，使用 [Toast.Style.Failure](#toast.style) 显示错误。当您的 Toast 显示到进程完成时，请使用 [Toast.Style.Animated](#toast.style)。您可以稍后使用 Toast.hide 隐藏它或更新现有 Toast 的属性。

#### 枚举成员

| 名称       | 值                                                                                                                                                                                                             |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Animated | ![](https://1964008511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYERqqbndxGykbCZ2IQg%2Fuploads%2Fgit-blob-8f8f930be5fe78ff06945fcc32ce7ced694fe923%2Ftoast-animated.png?alt=media) |
| Success  | ![](https://1964008511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYERqqbndxGykbCZ2IQg%2Fuploads%2Fgit-blob-4548b3fc0c71e9ad637cac11531d400b56ee378c%2Ftoast-success.png?alt=media)  |
| Failure  | ![](https://1964008511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYERqqbndxGykbCZ2IQg%2Fuploads%2Fgit-blob-9198357d9ce11ebd0ab47d1f900b249855b31cb7%2Ftoast-failure.png?alt=media)  |

### Toast.ActionOptions

用于创建 Toast 操作的选项。

#### 属性

| 名称                                         | 描述          | 类型                                                                                  |
| ------------------------------------------ | ----------- | ----------------------------------------------------------------------------------- |
| title<mark style="color:red;">\*</mark>    | 操作的标题。      | `string`                                                                            |
| onAction<mark style="color:red;">\*</mark> | 触发操作时调用的回调。 | `(toast:` [`Toast`](#toast)`) => void`                                              |
| shortcut                                   | 操作的键盘快捷键。   | [`Keyboard.Shortcut`](https://raycast-doc.gitbook.io/zh/keyboard#keyboard.shortcut) |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://raycast-doc.gitbook.io/zh/api-can-kao/feedback/toast.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.