更新记录

1.0.0（2026-07-21）

新增

• 首次发布，提供轮询能力
• 支持 interval、immediate、maxRetries 配置项
• 支持 start、stop、pause、resume 控制器方法
• 支持 onData、onError、onStop 回调
• 调用 poll() 后自动启动轮询
• 支持 stop() 后通过 start() 重新启动
• 支持 pause() / resume() 临时暂停/恢复
• 失败次数连续计数，成功一次即重置
• 完整的 TypeScript 类型定义

平台兼容性

uni-app(3.8.0)

uni-app x(3.8.0)

mh-request-polling

为 mh-request 提供轮询能力的插件，支持自动按间隔请求、启停控制、暂停/恢复、错误重试限制。

本插件是 mh-request 的配套插件，需配合使用。

特性

• 🔁 自动轮询：按指定间隔自动发起请求，无需手动循环
• 🎮 灵活控制：提供 start / stop / pause / resume 方法，随时操控轮询任务
• 🛡️ 错误容错：支持最大连续失败次数，超限自动停止，避免无效请求
• 📦 零侵入：在 mh-request 实例上挂载 poll 方法，不影响原有请求

快速开始

import { Request } from '@/uni_modules/mh-request'
import { pollPlugin } from '@/uni_modules/mh-request-polling'

const request = new Request({
  baseURL: 'https://api.example.com',
  plugins: [
    {
      plugin: pollPlugin
      // 轮询插件无需额外配置
    }
  ]
})

// 开始轮询，每 3 秒获取一次订单状态
const poller = request.poll('/order/status', { data: { id: 123 } }, {
  interval: 3000,
  onData: (data) => {
    console.log('订单状态:', data.status)
  },
  onError: (err) => {
    console.warn('轮询出错:', err)
  }
})

配置项

PollConfig

Poller 控制器

request.poll() 返回一个控制器对象：

工作原理

轮询流程

调用 poll() → 自动启动 → 发起请求
                    ↓
              请求成功 → 触发 onData → 等待 interval → 发起下一次请求
                    ↓
              请求失败 → 触发 onError → 失败计数 +1
                    ↓
              达到 maxRetries → 自动停止，触发 onStop
                    ↓
              未达上限 → 等待 interval → 继续重试

状态说明

高级用法

条件停止轮询

在 onData 回调中根据业务逻辑主动停止：

const poller = request.poll('/task/status', {}, {
  onData: (data) => {
    if (data.status === 'completed') {
      poller.stop('任务已完成')
    }
  }
})

错误重试限制

连续失败 3 次后自动停止轮询：

request.poll('/unstable-api', {}, {
  maxRetries: 3,
  onError: (err) => console.warn('请求失败，剩余重试次数:'),
  onStop: (reason) => console.log('轮询已停止:', reason)
})

延迟启动

不立即执行第一次请求，等待一个间隔后再发起：

request.poll('/api/data', {}, {
  interval: 5000,
  immediate: false   // 5 秒后执行第一次请求
})

手动控制轮询

const poller = request.poll('/api/updates', {}, { interval: 2000 })

// 页面不可见时暂停（uni-app 页面生命周期）
onHide(() => poller.pause())

// 页面可见时恢复
onShow(() => poller.resume())

注意事项

连续失败计数

maxRetries 统计的是连续失败次数，只要有一次成功即重置为 0。这意味着偶尔的网络抖动不会导致轮询停止，只有持续不可恢复的失败才会触发停止。

请求方法默认 GET

options 中的 method 默认为 GET，如需 POST 请求：

request.poll('/api/submit', {
  method: 'POST',
  data: { name: 'test' }
}, {
  interval: 5000
})

避免无限轮询

当 maxRetries: 0（默认）时，轮询不会因失败而停止，会无限重试。建议根据业务场景设置合理的 maxRetries，或在 onData 中通过条件调用 stop()。

停止后重新启动

stop() 是彻底终止，调用后轮询任务结束。如需重新开始，调用 start() 即可：

poller.stop()
// 稍后重新启动
poller.start()

而 pause() / resume() 用于临时暂停/恢复，保留当前状态（如失败计数），适合页面切后台等场景。