# @cssninja/nuxt-toaster 中文文档

规范地址：https://npmcn.com/package/%40cssninja/nuxt-toaster/

版本：0\.5\.0
npm 元数据更新时间：2025-07-18T14:16:49.039Z
中文译文更新时间：2026-11-11T03:59:09.181Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cssninja/nuxt-toaster
原文对照：https://npmcn.com/package/%40cssninja/nuxt-toaster/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：31.9 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2022-09-23T00:33:17.210Z
- 最新版本发布：2025-07-18T14:16:48.788Z
- 近 30 天下载量：3947（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 0 个）

## 中文简介

Nuxt.js 的简单烤面包机( 通知器)处理器

## 安装

```sh
npm install @cssninja/nuxt-toaster
```

也可以使用：`pnpm add @cssninja/nuxt-toaster`、`yarn add @cssninja/nuxt-toaster`、`bun add @cssninja/nuxt-toaster`

## README

# @cssninja/nuxt-烤面包机

Nuxt.js 的简单烤面包机( 通知器)处理器

[![npm](https://img.shields.io/npm/v/@cssninja/nuxt-toaster.svg)](https://www.npmjs.com/package/@cssninja/nuxt-toaster)

## 特征

-   默认取消
-   将任何组件作为祝酒词
-   完全自定义
-   简单的使用

## 安装

1.  添加 `@cssninja/nuxt-toaster` 对您的项目的依赖性

```bash
# Using pnpm
pnpm add -D @cssninja/nuxt-toaster

# Using yarn
pnpm add -D @cssninja/nuxt-toaster

# Using npm
npm install --save-dev @cssninja/nuxt-toaster
```

2.  添加 `@cssninja/nuxt-toaster` 页:1 `modules` 节 `nuxt.config.js`

```ts
export default defineNuxtConfig({
  modules: [
    '@cssninja/nuxt-toaster'
  ]
})
```

## 基本用途

### 举起手来

```ts
// get the ninjaToaster instance
const { $nt } = useNuxtApp()

// show a toast with a string as content
$nt.show('Hello world')
```

### 显示带有自定义组件的祝酒词

```ts
// define or import a component
const MyToast = defineComponent({
  /* ... */
})

// get the ninjaToaster instance
const { $nt } = useNuxtApp()

// show a toast with render function as content
$nt.show(() => h(MyToast))
```

## 配置

### 使用 `ninjaToaster.show` 选项

```ts
// get the ninjaToaster instance
const { $nt } = useNuxtApp()

$nt.show({
  /**
   * The content of the toast, can be a render function (a.k.a stateless component)
   * 
   * @type {string | number | Record<string, any> | (() => Component)}
   * @required
   */
  content: 'Hello world',

  /**
   * The duration of the toast
   * 
   * @default 5000
   */
  duration: 5000,

  /**
   * Pause the duration timer on hover, or focus
   * 
   * @default true
   */
  pauseOnHover: true,

  /**
   * Whereas the toast can be closed on click,
   * or on pressing Enter/Space keys when focused
   * 
   * @default true
   */
  dismissible: false,

  /**
   * Maximum number of toasts to show 
   * on the same `theme.containerId`
   * 
   * @default Infinity
   */
  maxToasts: 5,

  /**
   * Transition property for the toast
   * 
   * @see https://vuejs.org/api/built-in-components.html#transition
   */
  transition: {
    name: 'fadeIn',
  },

  /**
   * The theme used for the toast
   */
  theme: {
    /**
     * The container id where the toast will be rendered
     * If not exists, it will be created automatically
     * 
     * @default 'nt-container'
     */
    containerId: 'nt-container',
    /**
     * The class name for the toaster container (applyed to toast container)
     * 
     * @type {string | string[]}
     * @default ''
     */
    containerClass: 'nt-container-class',
    /**
     * The class name for the toast wrapper (applyed to each toast)
     * 
     * @type {string | string[]}
     * @default ''
     */
    wrapperClass: 'nt-wrapper-class',
  }
})
```

> 这将用以下的 HTML 结构创建祝酒:
> 
> ```html
> <body>
>   <!-- ... -->
>   <div id="nt-container" class="nt-container-class">
>     <div
>       class="nt-wrapper-class"
>       role="alert"
>       tabindex="0"
>     >
>       Hello world
>     </div>
>   </div>
> </body>
> ```
> 
> **注释 :** 页:1 `theme` 属性用于定制烤面包机行为。 每个 `theme.containerId` 将有自己的背景(例如: `maxToasts` 将计算在容器中可看到多少个配有标识的烤面包机.

### 使用 `toaster` 应用程序配置

为避免自己重复,可以设置忍者toaster的默认值. 在 nuxt 中显示方法 `app.config.ts` 在您的项目根部.

```ts
// app.config.ts
export default defineAppConfig({
  toaster: {
    // default options for ninjaToaster.show
  }
})
```

### 使用自定义插件

默认情况下,模块创建实例 `ninjaToaster` 并在 nuxt 语境中注入 `useNuxtApp().$nt`。 。 。 .

您可以使用自定义插件创建自己的实例并在上下文中注入。 这里我们用尾风来做土司.

1.  禁用默认插件 `nuxt.config.ts` 模块选项

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@cssninja/nuxt-toaster'
  ],
  toaster: {
    // disable the default plugin 
    installPlugin: false
  }
})
```

2.  创建自定义土司组件

```vue
<script setup lang="ts">
// components/MyToast.vue
const props = defineProps<{
  title: string
  message?: string
  type: 'info' | 'error'
}>()

const {
  isHovered,
  isActive,
  timer,
  duration,
  click,
  close,
} = useNinjaToasterState()

const {
  percent,
  endAt,
  closeIn
} = useNinjaToasterProgress()
</script>

<template>
  <div
    class="rounded p-4"
    :class="[
      props.type === 'info' && 'bg-indigo-600 text-indigo-500'
      props.type === 'error' && 'bg-rose-600 text-rose-500'
    ]"
  >
    <h1>{{ props.title }}</h1>
    <p v-if="props.message">{{ props.message }}</p>
    <button @click="close()">Close</button>
  </div>
</template>
```

3.  创建自定义插件

```ts
// plugins/toaster.ts
import MyToast from '~/components/MyToast.vue'

interface ToasterOptions {
  message: string
  title?: string
}

export default defineNuxtPlugin(() => {
  // define or import a theme
  const theme = {
    containerId: 'nt-container-bottom-right',
    containerClass: [
      'absolute',
      'inset-0',
      'pointer-events-none',
      'p-4',
      'flex',
      'flex-col-reverse',
      'items-start',
      'gap-2'
    ],
    wrapperClass: [
      'pointer-events-auto',
      'cursor-pointer',
    ],
  }

  // set default show options here
  const nt = createNinjaToaster({
    theme,
    maxToasts: 5,
    transition: {
      enterActiveClass: 'transition duration-300 ease-out',
      enterFromClass: 'transform translate-x-full opacity-0',
      enterToClass: 'transform translate-x-0 opacity-100',
      leaveActiveClass: 'transition duration-300 ease-in',
      leaveFromClass: 'transform translate-x-0 opacity-100',
      leaveToClass: 'transform translate-x-full opacity-0'
    }
  })

  const toaster = {
    info (options: ToasterOptions) {
      nt.show(() => h(MyToast, {
        ...options,
        type: 'info'
      }))
    },
    async error (options: ToasterOptions) {
      // wait for the toast to be mounted
      const { el, close } = await nt.show(() => h(MyToastError, {
        ...options,
        type: 'error'
      }))

      // focus the toast once it's mounted
      el.focus()
    },
    close() {
      // close all toasts
      nt.closeAll()

      // or close toasts in a specific containerId
      nt.close('nt-container-bottom-right') 

      // or close toasts using a theme
      nt.close(theme)
    },
  }

  return {
    provide {
      toaster
    }
  }
})
```

3.  用你们的 `toaster` 应用程序中的实例

```ts
// pages/index.vue
const { $toaster } = useNuxtApp()

$toaster.info({
  title: 'Hello world',
  message: 'This is a toaster info message'
})
$toaster.error({
  title: 'Hello world',
  message: 'This is a toaster error message'
})
```

## 他们

### 最小 CSS 主题

```css
#nt-container {
  /* make container fit the screen */
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  overflow: hidden;
  z-index: 100;
  pointer-events: none;

  /* position the toasts using flexbox */
  display: flex;
  
  /**
   * position all toasts in bottom of the screen 
   * - use "flex-direction: column;" to position in top screen
   */
  flex-direction: column-reverse;

  /**
   * align all toasts to the center
   * - use "align-items: start" to aling to the left
   * - use "align-items: end" to aling to the right
   */
  align-items: center;

  /* add some space between toasts and screen */
  padding: 2rem;
  gap: 1rem;
}

#nt-container [role='alert'] {
  /* allow toasts to be interactive */
  pointer-events: auto;

  /* add styles to toasts */
  padding: 1rem;
  border-radius: 0.5rem;
  background-color: #fff;
  box-shadow: 0 0 1rem rgba(0, 0, 0, 0.1);
}


@media (max-width: 767px) {
  #nt-container {
    /* fit toasts to screen on mobile */
    padding: 0;
  }
}

```

## 发展

-   运行 `npm run dev:prepare` 生成类型根.
-   使用 `npm run dev` 开始 [游乐场](https://npmcn.com/package/%40cssninja/nuxt-toaster/playground) 在开发模式中.

## 常见问题

### @cssninja/nuxt-toaster 是什么？

Nuxt\.js 的简单烤面包机\( 通知器\)处理器

### 如何安装 @cssninja/nuxt-toaster？

在项目目录运行 npm install @cssninja/nuxt-toaster，或使用 pnpm add / yarn add / bun add。

### @cssninja/nuxt-toaster 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cssninja/nuxt-toaster 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cssninja/nuxt-toaster 可以商用吗？

@cssninja/nuxt-toaster 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cssninja/nuxt-toaster 的下载量有多少？

根据 npm 官方下载统计，@cssninja/nuxt-toaster 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,947 次，日均约 132 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cssninja/nuxt-toaster 还在维护吗？

最新版本 0\.5\.0 发布于 2025/07/18（1\.3 年前）；至今共发布 21 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/09/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。