> For the complete documentation index, see [llms.txt](https://raycast-doc.gitbook.io/zh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://raycast-doc.gitbook.io/zh/api-can-kao/feedback/toast.md).

# 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/feedback/pages/NxG6bLeaPvyFs9FCC3jm#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/feedback/pages/NxG6bLeaPvyFs9FCC3jm#alert.actionoptions) |
| secondaryAction<mark style="color:red;">\*</mark> | 用户将鼠标悬停在 Toast 上时可以执行的 secondary 操作。 | [`Alert.ActionOptions`](https://raycast-doc.gitbook.io/zh/api-can-kao/feedback/pages/NxG6bLeaPvyFs9FCC3jm#alert.actionoptions) |
| style<mark style="color:red;">\*</mark>           | Toast 的样式。                           | [`Action.Style`](https://raycast-doc.gitbook.io/zh/api-can-kao/feedback/pages/rkMpUek70RrFgMedLUE1#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/feedback/pages/NxG6bLeaPvyFs9FCC3jm#alert.actionoptions) |
| secondaryAction                         | 用户将鼠标悬停在 Toast 上时可以执行的 secondary 操作。 | [`Alert.ActionOptions`](https://raycast-doc.gitbook.io/zh/api-can-kao/feedback/pages/NxG6bLeaPvyFs9FCC3jm#alert.actionoptions) |
| style                                   | Toast 的样式。                           | [`Action.Style`](https://raycast-doc.gitbook.io/zh/api-can-kao/feedback/pages/rkMpUek70RrFgMedLUE1#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/api-can-kao/feedback/pages/eG3XofwHgHGjEJ4IlcYK#keyboard.shortcut) |