时序控制 useLockFn / useDebounceFn / useThrottleFn

业务侧最高频的三类时序问题各给一个最小 hook：防重复提交（useLockFn）、防抖（useDebounceFn，停顿才算数）、节流（useThrottleFn，高频按节奏放行）。零依赖、作用域销毁自动清理（防抖 / 节流）。

useLockFn：提交防重

执行期间（及可选反馈保持期）忽略后续调用，loading 直接绑定按钮——比手动 :loading 收敛在函数维度，多入口（按钮 + 回车）调用同一函数也只放行一次。

const { run: submit, loading } = useLockFn(async (values) => {
  await api.save(values)
  ElMessage.success('已提交')
})
// 模板：<el-button :loading="loading" @click="submit(form)">提交</el-button>

连点按钮或输入框内回车，1.5s 内只发一次。

连点按钮或输入框内回车，1.5s 请求期内只放行一次。

<script setup lang="ts">
/** 场景：提交防重——执行期间连点/回车都只放行一次，loading 自动绑定 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { useLockFn } from 'vue3-ep-biz-lib'

const form = ref({ name: '', amount: 100 })
let submitCount = 0

const { run: submit, loading } = useLockFn(async (values: { name: string; amount: number }) => {
  submitCount += 1
  await new Promise((r) => setTimeout(r, 1500))
  ElMessage.success(`第 ${submitCount} 次提交成功：${values.name} / ${values.amount}`)
})
</script>

<template>
  <div style="display: flex; gap: 12px; align-items: center; max-width: 480px">
    <el-input v-model="form.name" placeholder="单据名称" style="width: 200px" @keyup.enter="submit(form)" />
    <el-button type="primary" :loading="loading" @click="submit(form)">
      {{ loading ? '提交中…' : '提交（防重）' }}
    </el-button>
    <span style="font-size: 13px; color: var(--el-text-color-secondary)">连点按钮或输入框内回车，1.5s 内只发一次。</span>
  </div>
</template>

显示代码

已支付：¥0（连点不会多扣）

支付确认防重：确认弹窗取消不触发支付，支付期间按钮锁定杜绝重复扣款。

<script setup lang="ts">
/** 场景：付款确认防重——确认弹窗 + 支付接口执行期锁定，杜绝重复扣款 */
import { ref } from 'vue'
import { ElMessage, ElMessageBox } from 'element-plus'
import { useLockFn } from 'vue3-ep-biz-lib'

const paid = ref(0)

const { run: pay, loading } = useLockFn(async () => {
  try {
    await ElMessageBox.confirm('确认支付 ¥1,280.00？付款期间按钮将锁定。', '支付确认', { type: 'warning' })
  } catch {
    /* 用户取消确认 */
    return
  }
  await new Promise((r) => setTimeout(r, 2000))
  paid.value += 1280
  ElMessage.success(`支付成功，累计 ¥${paid.value.toLocaleString()}`)
})

const onPay = (): void => {
  void pay()
}
</script>

<template>
  <div style="display: flex; gap: 12px; align-items: center">
    <el-button type="danger" :loading="loading" @click="onPay">
      {{ loading ? '支付处理中，请勿重复操作' : '立即支付 ¥1,280.00' }}
    </el-button>
    <span style="font-size: 13px; color: var(--el-text-color-secondary)">已支付：¥{{ paid.toLocaleString() }}（连点不会多扣）</span>
  </div>
</template>

显示代码

已完成：—；执行期间再次点击不会启动第二批。

批量审批逐条 await，整体流程锁定，避免两批并发交叉执行。

<script setup lang="ts">
/** 场景：批量审批防重——逐条 await 的批量流程整体锁定，避免两批并发交叉 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { useLockFn } from 'vue3-ep-biz-lib'

const orders = ['SO-1001', 'SO-1002', 'SO-1003', 'SO-1004']
const done = ref<string[]>([])

const { run: approveAll, loading } = useLockFn(async () => {
  done.value = []
  for (const order of orders) {
    await new Promise((r) => setTimeout(r, 500))
    done.value = [...done.value, order]
  }
  ElMessage.success(`已批量审批 ${orders.length} 单`)
})
</script>

<template>
  <div style="max-width: 420px">
    <el-button type="primary" :loading="loading" @click="approveAll">
      {{ loading ? `审批中 ${done.length}/${orders.length}…` : '批量审批 4 单' }}
    </el-button>
    <div style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      已完成：{{ done.length > 0 ? done.join('、') : '—' }}；执行期间再次点击不会启动第二批。
    </div>
  </div>
</template>

显示代码

已保存 0 次；接口 0.6s 即回，但按钮锁到 2.1s 才放开。

{ lockDuring: 1500 } 成功后额外锁 1.5s：成功提示期防误触二次提交。

<script setup lang="ts">
/** 场景：lockDuring 反馈保持——成功后额外锁 1.5s，防止用户在成功提示期误触二次提交 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { useLockFn } from 'vue3-ep-biz-lib'

const count = ref(0)

const { run: save, loading } = useLockFn(
  async () => {
    await new Promise((r) => setTimeout(r, 600))
    count.value += 1
    ElMessage.success('保存成功（1.5s 反馈期内保持锁定）')
  },
  { lockDuring: 1500 },
)
</script>

<template>
  <div style="display: flex; gap: 12px; align-items: center">
    <el-button type="primary" :loading="loading" @click="save">保存（含反馈保持）</el-button>
    <span style="font-size: 13px; color: var(--el-text-color-secondary)">已保存 {{ count }} 次；接口 0.6s 即回，但按钮锁到 2.1s 才放开。</span>
  </div>
</template>

显示代码

useDebounceFn：防抖（trailing）

最后一次调用后 delay ms 触发一次；cancel 取消等待、flush 立即触发等待中的值（「立即应用」按钮场景）。

const { run: search, cancel, flush, pending } = useDebounceFn((kw: string) => {
  void api.suggest(kw)
}, 400)

请求 0 次（快速连续输入只在停顿后发 1 次）

搜索联想：快速连续输入只在停顿后发一次请求（请求计数对比）。

<script setup lang="ts">
/** 场景：搜索联想防抖——停止输入 400ms 才发请求，请求次数计数对比 */
import { ref } from 'vue'
import { useDebounceFn } from 'vue3-ep-biz-lib'

const keyword = ref('')
const suggestions = ref<string[]>([])
const requestCount = ref(0)

const ALL = ['阿里巴巴', '阿拉尔', '埃及', '爱尔兰', '埃尔切', '鄂尔多斯', '俄罗斯', '日本', '瑞士']

const { run: search } = useDebounceFn((kw: string) => {
  requestCount.value += 1
  suggestions.value = kw.trim() === '' ? [] : ALL.filter((item) => item.includes(kw.trim()))
}, 400)

const onInput = (value: string): void => {
  keyword.value = value
  search(value)
}
</script>

<template>
  <div style="max-width: 360px">
    <el-input v-model="keyword" placeholder="输入 阿 / 埃 / 俄 体验联想" clearable @update:model-value="onInput" />
    <p style="margin: 8px 0 4px; font-size: 12px; color: var(--el-text-color-secondary)">
      请求 {{ requestCount }} 次（快速连续输入只在停顿后发 1 次）
    </p>
    <el-tag v-for="item in suggestions" :key="item" style="margin: 0 6px 6px 0">{{ item }}</el-tag>
  </div>
</template>

显示代码

价格 ≤ 100 元

已按 ≤100 元查询（共 0 次）；flush 可不等停顿立即触发等待中的值。

筛选联动：滑块拖动过程不查，停 300ms 才触发；flush 演示立即应用等待中的值。

<script setup lang="ts">
/** 场景：筛选联动防抖——滑块拖动过程不查，停 300ms 才触发列表查询 */
import { ref } from 'vue'
import { useDebounceFn } from 'vue3-ep-biz-lib'

const price = ref(100)
const appliedPrice = ref(100)
const queryCount = ref(0)

const { run: applyFilter, flush } = useDebounceFn((value: number) => {
  appliedPrice.value = value
  queryCount.value += 1
}, 300)

const onSlide = (value: number | number[]): void => {
  price.value = Array.isArray(value) ? (value[0] ?? 0) : value
  applyFilter(price.value)
}
</script>

<template>
  <div style="max-width: 460px">
    <div style="display: flex; align-items: center; gap: 12px">
      <span style="font-size: 13px">价格 ≤ {{ price }} 元</span>
      <el-button size="small" @click="flush">立即应用</el-button>
    </div>
    <el-slider :model-value="price" :max="500" style="margin: 0 8px" @update:model-value="onSlide" />
    <p style="margin: 0; font-size: 12px; color: var(--el-text-color-secondary)">
      已按 ≤{{ appliedPrice }} 元查询（共 {{ queryCount }} 次）；flush 可不等停顿立即触发等待中的值。
    </p>
  </div>
</template>

显示代码

useThrottleFn：节流（leading + trailing）

interval 内至多触发一次：首次立即响应，间隔内的末次参数在间隔尾补发（最后一次调用不丢）。

const { run: onScroll } = useThrottleFn(() => {
  if (nearBottom()) loadMore()
}, 500)

条目 1

条目 2

条目 3

条目 4

条目 5

条目 6

条目 7

条目 8

条目 9

条目 10

条目 11

条目 12

条目 13

条目 14

条目 15

条目 16

条目 17

条目 18

条目 19

条目 20

条目 21

条目 22

条目 23

条目 24

条目 25

条目 26

条目 27

条目 28

条目 29

条目 30

触发检查 0 次 / 加载 0 次（滚动到底部连续触发也被限到 500ms 一次）

滚动加载：scroll 高频事件按 500ms 节奏触发到底检查。

<script setup lang="ts">
/** 场景：滚动加载节流——高频 scroll 事件 500ms 至多触发一次检查 */
import { ref } from 'vue'
import { useThrottleFn } from 'vue3-ep-biz-lib'

const items = ref(Array.from({ length: 30 }, (_, i) => i + 1))
const scrollCount = ref(0)
const loadCount = ref(0)

const { run: onScroll } = useThrottleFn(() => {
  scrollCount.value += 1
  if (items.value.length < 90) {
    loadCount.value += 1
    const base = items.value.length
    items.value = [...items.value, ...Array.from({ length: 30 }, (_, i) => base + i + 1)]
  }
}, 500)

const onWrapperScroll = (event: Event): void => {
  const el = event.target as HTMLElement
  if (el.scrollTop + el.clientHeight >= el.scrollHeight - 40) onScroll()
}
</script>

<template>
  <div>
    <div
      style="height: 180px; overflow-y: auto; border: 1px solid var(--el-border-color-lighter); border-radius: 6px; padding: 8px 14px"
      @scroll.passive="onWrapperScroll"
    >
      <div v-for="item in items" :key="item" style="line-height: 28px; font-size: 13px; border-bottom: 1px dashed var(--el-border-color-extra-light)">
        条目 {{ item }}
      </div>
    </div>
    <p style="margin: 8px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      触发检查 {{ scrollCount }} 次 / 加载 {{ loadCount }} 次（滚动到底部连续触发也被限到 500ms 一次）
    </p>
  </div>
</template>

显示代码

窗口：0 × 0已按节流更新 0 次——拖拽浏览器窗口边缘试试。

窗口 resize：拖拽窗口边缘按 400ms 节奏更新尺寸。

<script setup lang="ts">
/** 场景：窗口 resize 节流——拖拽窗口时按 400ms 节奏更新尺寸展示 */
import { onMounted, onBeforeUnmount, ref } from 'vue'
import { useThrottleFn } from 'vue3-ep-biz-lib'

const size = ref({ w: 0, h: 0 })
const updateCount = ref(0)

const { run: onResize } = useThrottleFn(() => {
  size.value = { w: window.innerWidth, h: window.innerHeight }
  updateCount.value += 1
}, 400)

onMounted(() => {
  onResize()
  window.addEventListener('resize', onResize)
})
onBeforeUnmount(() => {
  window.removeEventListener('resize', onResize)
})
</script>

<template>
  <div style="display: flex; gap: 16px; align-items: center; font-size: 13px">
    <el-tag type="info">窗口：{{ size.w }} × {{ size.h }}</el-tag>
    <span style="color: var(--el-text-color-secondary)">已按节流更新 {{ updateCount }} 次——拖拽浏览器窗口边缘试试。</span>
  </div>
</template>

显示代码

API

useLockFn(fn, options?)

成员	类型	说明
run	(...args) => Promise | undefined	锁定期间调用返回 undefined（不排队不重入）
loading	Ref<boolean>	执行中（含 lockDuring 保持期），绑定按钮 loading / disabled

选项	类型	默认	说明
lockDuring	number	0	成功/失败后继续锁定 ms（反馈期防误触）

useDebounceFn(fn, delay = 300)

成员	类型	说明
run	(...args) => void	停止调用 delay ms 后触发一次
cancel	() => void	取消未触发的等待
flush	() => void	立即触发等待中的调用（无等待不动作）
pending	() => boolean	是否有待触发的等待

useThrottleFn(fn, interval = 300)

成员	类型	说明
run	(...args) => void	间隔内首次立即触发，末次参数间隔尾补发
cancel	() => void	取消待补发的末次调用
pending	() => boolean	是否处于节流间隔内

选型

• 会写库 / 会付钱 / 会发消息的动作 → useLockFn（一次都不许多）；
• 等用户停（联想、联动查询、草稿保存）→ useDebounceFn；
• 高频事件按节奏（scroll / resize / mousemove）→ useThrottleFn。