更新记录

1.0.0（2026-07-15） 下载此版本

gb-long-toast 长文本 Toast 提示

介绍

微信小程序真机上 uni.showToast 对长文本有截断问题，超过约 10 个汉字的内容无法完整显示。本插件通过 monkey-patch 方式重构 uni.showToast / uni.hideToast，所有页面无需修改任何调用代码即可自动支持长文本完整显示。

核心特性

• 零侵入：直接 patch uni.showToast，现有代码无需改动
• 长文本自动切换：title 超过 10 个字符时自动使用自定义组件，短文本仍走原生
• 多页面栈管理：支持 tabBar 页面切换、二级页面跳转返回等场景
• 智能降级：当前页面无组件或组件不属于当前页面时，自动降级走原生 toast（截断但至少有提示）
• API 完全兼容：支持 icon、duration、mask、image、success、complete 等全部参数
• easycom 自动注册：组件无需手动 import

目录结构

uni_modules/gb-long-toast/
├── components/gb-long-toast/
│   └── gb-long-toast.vue    # 自定义 Toast 组件
├── js/
│   └── toast.js             # 核心 patch 逻辑
├── package.json
└── readme.md

快速上手

第一步：在 main.js 中初始化

// main.js
import Vue from 'vue';
import { patchToast, setupPageShow } from '@/uni_modules/gb-long-toast/js/toast.js';

// 重构 uni.showToast / uni.hideToast
patchToast();

// 注入 Vue.mixin onShow 钩子，支持页面切换自动检测
setupPageShow(Vue);

第二步：在需要长文本 Toast 的页面模板中添加组件

<template>
  <view>
    <!-- 页面内容 -->
    <gb-long-toast />
  </view>
</template>

组件通过 easycom 自动注册，无需手动 import 和 components 声明。

第三步：正常调用 uni.showToast

// 长文本会自动使用自定义组件显示，无需任何修改
uni.showToast({
  title: '您的操作已成功，系统将在3秒后自动跳转到首页',
  icon: 'none'
});

API 说明

调用方式与原生 uni.showToast / uni.hideToast 完全一致，无需学习新 API。

uni.showToast(OBJECT)

uni.hideToast()

隐藏正在显示的 Toast 提示，与原生行为一致。

显示规则

使用案例

基础用法 - 纯文本提示

uni.showToast({
  title: '操作成功，请在我的页面查看领取记录',
  icon: 'none'
});

带 success 图标

uni.showToast({
  title: '订单已提交成功，请耐心等待审核结果通知',
  icon: 'success'
});

带 error 图标

uni.showToast({
  title: '网络请求失败，请检查网络连接后重试',
  icon: 'error'
});

loading 模式（不自动关闭）

// 显示 loading
uni.showToast({
  title: '正在加载数据，请稍候...',
  icon: 'loading',
  mask: true  // 防止触摸穿透
});

// 手动关闭
uni.showToast({
  title: '加载完成',
  icon: 'success'
});
// 或
uni.hideToast();

防止触摸穿透（mask）

uni.showToast({
  title: '正在处理中，请勿进行其他操作以免数据丢失',
  icon: 'none',
  mask: true
});

自定义显示时长

uni.showToast({
  title: '这是一条持续3秒的提示信息',
  icon: 'none',
  duration: 3000
});

使用回调函数

uni.showToast({
  title: '提交成功，即将跳转到订单详情页面',
  icon: 'success',
  success() {
    console.log('toast 显示成功');
  },
  complete() {
    console.log('toast 调用完成');
  }
});

自定义图标（降级原生）

uni.showToast({
  title: '这个提示有自定义图标',
  icon: 'none',
  image: '/static/custom-icon.png'
});
// 注意：使用 image 参数时会降级走原生 toast，长文本仍可能被截断

多页面场景说明

tabBar 页面切换

插件通过 Vue.mixin 注入全局 onShow 钩子，tabBar 页面切换时自动激活当前页面的 Toast 组件，无需额外处理。

前提条件： 切换到的 tabBar 页面模板中必须包含 <gb-long-toast /> 组件。

<!-- pages/index/index.vue（首页 tabBar） -->
<template>
  <view>
    <gb-long-toast />
    <!-- 页面内容 -->
  </view>
</template>

<!-- pages/user/user.vue（我的 tabBar） -->
<template>
  <view>
    <gb-long-toast />
    <!-- 页面内容 -->
  </view>
</template>

二级页面跳转与返回

从 tabBar 页面进入二级页面再返回时，插件自动处理组件切换：

• 当前页面有组件 → 使用自定义组件完整显示
• 当前页面无组件 → 降级走原生 toast（截断但有提示）

页面未放置组件

如果某个页面没有放置 <gb-long-toast /> 组件，长文本 Toast 会自动降级走原生 uni.showToast。虽然文本会被截断，但至少保证了提示不会丢失。

建议： 所有需要长文本 Toast 的页面都应放置 <gb-long-toast /> 组件，以获得完整显示效果。

工作原理

┌──────────────────────────────────────────────────────────────────┐
│                       uni.showToast (已被 patch)                  │
├─────────────┬──────────────────────┬─────────────────────────────┤
│  title ≤ 10 │  title > 10          │  image 有值                 │
│  走原生     │  无 image             │  走原生（降级）             │
│             ├──────────────────────┤                              │
│             │  组件属于当前页面     │  组件不属于当前页面/无组件   │
│             │  调用组件 show()     │  降级走原生（截断但有提示）  │
│             │  完整显示            │                              │
└─────────────┴──────────────────────┴─────────────────────────────┘

页面可见性追踪：
  currentVisiblePageVm    // 当前可见页面的 VM 实例
  pageToastMap            // 页面→组件映射
  toastStack              // 组件实例栈，栈顶为当前活跃组件

  页面切换时（onShow）：
  1. 记录 currentVisiblePageVm = this
  2. pageToastMap.get(this) → activateToast(instance) → 提升到栈顶
  3. showToast 时校验 top._pageVm === currentVisiblePageVm

注意事项

1. 建议所有页面都放置 <gb-long-toast /> 组件，未放置组件的页面长文本 Toast 会降级走原生，仍可能被截断
2. image 参数有值时会降级走原生 Toast，长文本仍可能被截断，建议短文本才使用自定义图标
3. icon: 'loading' 模式下 Toast 不会自动关闭，需手动调用 uni.hideToast() 或再次调用 uni.showToast() 覆盖
4. 插件内部使用 Vue.mixin 注入 onShow，如项目已有全局 mixin 的 onShow，两者会合并执行，不会冲突
5. 从子页面返回当前页面时，如果当前页面没有组件，Toast 会自动降级走原生，确保提示不会丢失

平台兼容性

uni-app(4.23)

gb-long-toast 长文本 Toast 提示

介绍

微信小程序真机上 uni.showToast 对长文本有截断问题，超过约 10 个汉字的内容无法完整显示。本插件通过 monkey-patch 方式重构 uni.showToast / uni.hideToast，所有页面无需修改任何调用代码即可自动支持长文本完整显示。

核心特性

• 零侵入：直接 patch uni.showToast，现有代码无需改动
• 长文本自动切换：title 超过 10 个字符时自动使用自定义组件，短文本仍走原生
• 多页面栈管理：支持 tabBar 页面切换、二级页面跳转返回等场景
• 智能降级：当前页面无组件或组件不属于当前页面时，自动降级走原生 toast（截断但至少有提示）
• API 完全兼容：支持 icon、duration、mask、image、success、complete 等全部参数
• easycom 自动注册：组件无需手动 import

目录结构

uni_modules/gb-long-toast/
├── components/gb-long-toast/
│   └── gb-long-toast.vue    # 自定义 Toast 组件
├── js/
│   └── toast.js             # 核心 patch 逻辑
├── package.json
└── readme.md

快速上手

第一步：在 main.js 中初始化

// main.js
import Vue from 'vue';
import { patchToast, setupPageShow } from '@/uni_modules/gb-long-toast/js/toast.js';

// 重构 uni.showToast / uni.hideToast
patchToast();

// 注入 Vue.mixin onShow 钩子，支持页面切换自动检测
setupPageShow(Vue);

第二步：在需要长文本 Toast 的页面模板中添加组件

<template>
  <view>
    <!-- 页面内容 -->
    <gb-long-toast />
  </view>
</template>

组件通过 easycom 自动注册，无需手动 import 和 components 声明。

第三步：正常调用 uni.showToast

// 长文本会自动使用自定义组件显示，无需任何修改
uni.showToast({
  title: '您的操作已成功，系统将在3秒后自动跳转到首页',
  icon: 'none'
});

API 说明

调用方式与原生 uni.showToast / uni.hideToast 完全一致，无需学习新 API。

uni.showToast(OBJECT)

uni.hideToast()

隐藏正在显示的 Toast 提示，与原生行为一致。

显示规则

使用案例

基础用法 - 纯文本提示

uni.showToast({
  title: '操作成功，请在我的页面查看领取记录',
  icon: 'none'
});

带 success 图标

uni.showToast({
  title: '订单已提交成功，请耐心等待审核结果通知',
  icon: 'success'
});

带 error 图标

uni.showToast({
  title: '网络请求失败，请检查网络连接后重试',
  icon: 'error'
});

loading 模式（不自动关闭）

// 显示 loading
uni.showToast({
  title: '正在加载数据，请稍候...',
  icon: 'loading',
  mask: true  // 防止触摸穿透
});

// 手动关闭
uni.showToast({
  title: '加载完成',
  icon: 'success'
});
// 或
uni.hideToast();

防止触摸穿透（mask）

uni.showToast({
  title: '正在处理中，请勿进行其他操作以免数据丢失',
  icon: 'none',
  mask: true
});

自定义显示时长

uni.showToast({
  title: '这是一条持续3秒的提示信息',
  icon: 'none',
  duration: 3000
});

使用回调函数

uni.showToast({
  title: '提交成功，即将跳转到订单详情页面',
  icon: 'success',
  success() {
    console.log('toast 显示成功');
  },
  complete() {
    console.log('toast 调用完成');
  }
});

自定义图标（降级原生）

uni.showToast({
  title: '这个提示有自定义图标',
  icon: 'none',
  image: '/static/custom-icon.png'
});
// 注意：使用 image 参数时会降级走原生 toast，长文本仍可能被截断

多页面场景说明

tabBar 页面切换

插件通过 Vue.mixin 注入全局 onShow 钩子，tabBar 页面切换时自动激活当前页面的 Toast 组件，无需额外处理。

前提条件： 切换到的 tabBar 页面模板中必须包含 <gb-long-toast /> 组件。

<!-- pages/index/index.vue（首页 tabBar） -->
<template>
  <view>
    <gb-long-toast />
    <!-- 页面内容 -->
  </view>
</template>

<!-- pages/user/user.vue（我的 tabBar） -->
<template>
  <view>
    <gb-long-toast />
    <!-- 页面内容 -->
  </view>
</template>

二级页面跳转与返回

从 tabBar 页面进入二级页面再返回时，插件自动处理组件切换：

• 当前页面有组件 → 使用自定义组件完整显示
• 当前页面无组件 → 降级走原生 toast（截断但有提示）

页面未放置组件

如果某个页面没有放置 <gb-long-toast /> 组件，长文本 Toast 会自动降级走原生 uni.showToast。虽然文本会被截断，但至少保证了提示不会丢失。

建议： 所有需要长文本 Toast 的页面都应放置 <gb-long-toast /> 组件，以获得完整显示效果。

工作原理

┌──────────────────────────────────────────────────────────────────┐
│                       uni.showToast (已被 patch)                  │
├─────────────┬──────────────────────┬─────────────────────────────┤
│  title ≤ 10 │  title > 10          │  image 有值                 │
│  走原生     │  无 image             │  走原生（降级）             │
│             ├──────────────────────┤                              │
│             │  组件属于当前页面     │  组件不属于当前页面/无组件   │
│             │  调用组件 show()     │  降级走原生（截断但有提示）  │
│             │  完整显示            │                              │
└─────────────┴──────────────────────┴─────────────────────────────┘

页面可见性追踪：
  currentVisiblePageVm    // 当前可见页面的 VM 实例
  pageToastMap            // 页面→组件映射
  toastStack              // 组件实例栈，栈顶为当前活跃组件

  页面切换时（onShow）：
  1. 记录 currentVisiblePageVm = this
  2. pageToastMap.get(this) → activateToast(instance) → 提升到栈顶
  3. showToast 时校验 top._pageVm === currentVisiblePageVm

注意事项

1. 建议所有页面都放置 <gb-long-toast /> 组件，未放置组件的页面长文本 Toast 会降级走原生，仍可能被截断
2. image 参数有值时会降级走原生 Toast，长文本仍可能被截断，建议短文本才使用自定义图标
3. icon: 'loading' 模式下 Toast 不会自动关闭，需手动调用 uni.hideToast() 或再次调用 uni.showToast() 覆盖
4. 插件内部使用 Vue.mixin 注入 onShow，如项目已有全局 mixin 的 onShow，两者会合并执行，不会冲突
5. 从子页面返回当前页面时，如果当前页面没有组件，Toast 会自动降级走原生，确保提示不会丢失