Window Open Helper Documentation

windowOpenHelper 是一个用于解决异步操作后 window.open 被浏览器拦截问题的通用工具。它允许你在执行异步请求（如 API 调用）之前先同步打开一个带有加载状态的窗口，待异步操作完成后再重定向该窗口。

引入方式

import { openLoadingWindow } from '@/utils/windowOpenHelper';

API 使用

openLoadingWindow(options)

参数 (Options)

接收一个对象 WindowOpenOptions，包含以下属性：

| 属性名 | 类型 | 默认值 | 必填 | 说明 | | :--- | :--- | :--- | :--- | :--- | | title | string | 'Loading...' | 否 | 新窗口的标题（<title>标签内容）。 | | loadingStyle | 'spinner' | 'pulse' | 'dots' | 'telegram' | 'spinner' | 否 | 加载动画的样式。支持：- spinner: 经典的旋转圆圈- pulse: 脉冲动画- dots: 三个跳动的点- telegram: Telegram 风格的全屏渐变加载页 | | loadingText | string | 'Loading...' | 否 | 显示在加载动画下方的提示文字。 | | customHtml | string | undefined | 否 | 完全自定义 HTML 内容。如果提供此参数，将忽略 title、loadingStyle 和 loadingText，直接将此 HTML 写入新窗口。适用于高度定制化的加载页。 |

示例：

// 简单使用
const win = openLoadingWindow();

// 定制样式
const win = openLoadingWindow({
  title: 'Payment Processing',
  loadingText: 'Please wait while we secure your connection...',
  loadingStyle: 'pulse'
});

// 使用 Telegram 风格
const win = openLoadingWindow({
  loadingStyle: 'telegram'
});

返回值 (Return)

返回一个 WindowController 对象，用于控制已打开的窗口：

| 属性/方法名 | 类型 | 说明 | | :--- | :--- | :--- | | isBlocked | boolean | 关键属性。如果在打开窗口瞬间被浏览器拦截（popup blocked），此值为 true。调用方应检查此属性并告知用户允许弹窗。 | | window | Window \| null | 原生 Window 对象引用。如果被拦截可能为 null。 | | redirect(url) | (url: string) => void | 核心方法。将窗口重定向到目标 URL。通常在异步操作成功后调用。 | | close() | () => void | 关闭窗口。通常在用户取消、异步操作失败或完成特定流程后调用。 |

完整流程示例

async function handlePayment() {
  // 1. 在 await 之前同步打开窗口
  const winController = openLoadingWindow({
    title: 'Processing Payment',
    loadingStyle: 'spinner'
  });

  // 2. 检查是否被拦截
  if (winController.isBlocked) {
    alert('请允许本站弹出窗口以继续支付');
    return;
  }

  try {
    // 3. 执行异步操作
    const res = await createPaymentApi();

    if (res.success) {
      // 4. 成功：重定向到支付链接
      winController.redirect(res.paymentUrl);
    } else {
      // 5. 失败：关闭窗口
      winController.close();
      alert('支付创建失败: ' + res.message);
    }
  } catch (err) {
    // 异常：关闭窗口
    winController.close();
  }
}