跳到正文

我所理解的 Vue 最佳实践(6):保留 click 写法,让按钮自动防连点和 loading

我所理解的 Vue 最佳实践

  1. Vue watch 的 cleanup 到底清理了什么
  2. Vue 的 script setup 泛型组件到底解决了什么
  3. defineModel 已经声明了什么:避免重复 v-model 契约和默认值分叉
  4. 用插槽选择器 slotted 给传入内容设样式
  5. 用模板 ref 连接 Teleport 挂载点
  6. 保留 click 写法,让按钮自动防连点和 loading(当前)

保存按钮经常需要一个 loading 变量。点击时设为 true,请求结束后在 finally 里恢复,模板再绑定 :loading。状态由整个表单或多个操作入口共享时,这样做很直接;如果任务只属于一个按钮,每个页面重复写这段状态管理就有些繁琐。

按钮本身能不能拿到点击回调返回的 Promise,在执行期间自动显示 loading,同时让调用方继续写 @click="save"?Vue 3 可以做到。接口仍用模板里的事件写法,组件内部则将 onClick 声明为回调 prop,直接取得执行结果。

同步冷却与异步任务分别判断

「打开弹窗」通常是同步操作,第一次点击应该立即响应,随后一小段时间里的连点可以忽略。「保存文档」则可能持续数秒,按钮需要一直等到任务结束。固定禁用 300 毫秒只能覆盖前一种需求,无法判断后一次保存是否会与前一次重叠。

这里采用两个可以组合的条件:从接受点击的时刻计算最小间隔;如果回调返回可等待对象,还要等它完成。普通同步返回值不触发 loading。计数器、翻页等允许连续操作的按钮,把最小间隔设为 0 即可。

同步点击按间隔冷却,异步点击还需等待任务结束

图中的 300 毫秒是组件策略,不是 Vue 或浏览器规定的时间。80 毫秒完成的异步任务还处于冷却窗口,持续 1200 毫秒的任务则会把锁延长到完成时。后续点击直接忽略,窗口结束时不补执行一次。

@click 可以由回调 prop 接收

在 Vue 的渲染函数接口中,onClick 对应模板里的 @click。调用方可以保留熟悉的写法:

<template>
  <sh-button @click="save">保存</sh-button>
</template>

按钮显式声明 onClick,就能像普通函数一样调用它并取得返回值。下面只展示单个监听器的入口,完整按钮还需要处理锁定、异常和多个监听器:

<script setup lang="ts">
const props = defineProps<{
  onClick?: (event: MouseEvent) => unknown;
}>();

// 回调返回值留给按钮判断,原始事件继续传给业务函数。
function invokeClick(event: MouseEvent) {
  return props.onClick?.(event);
}
</script>

<template>
  <button type="button" @click="invokeClick"><slot /></button>
</template>

声明这个 prop 还有一个作用:监听器会被组件消费。根据 Vue 的属性透传规则,已声明的 prop 不会继续自动传给根元素。组件直接调用一次 onClick,避免业务回调又通过根按钮监听器执行一次。其他原生属性、class 和未接管的监听器仍可以按单根组件的规则透传。

同一份 click 监听器,经 emit 分发与作为回调直接调用的返回路径不同

emit('click', event) 也会找到调用方注册的监听器,但它提供的是组件事件分发接口。$emit 的公开返回类型是 void,不会把监听器返回的 Promise 作为自己的结果。写 await emit('click'),并不能等待父组件里的保存任务。

因此,两种写法只在「让监听器执行」这件事上相似。Vue 的事件分发还处理事件校验、一次性监听器、多个监听器和错误处理;直接调用函数时,需要按组件承诺补齐对应行为。也不应在直接调用以后,再 emit 同一个事件,否则会重复执行业务逻辑。

需要向父组件报告状态变化、选择结果时,普通 emit 仍然合适。需要依据调用方的返回值控制流程时,函数回调的契约更清楚。这种区分也适用于弹窗关闭前校验、菜单动作和上传前检查。

自动识别的是返回值

普通函数也能返回 Promise,async 函数则总是返回 Promise。按钮判断的应当是这一次调用的结果,而不是函数有没有 async 关键字。

thenable 是带有可调用 then 方法的对象或函数。除了原生 Promise,一些库也会提供这种可等待对象。判断后用 Promise.resolve() 归一化,可以等待它最终完成;instanceof Promise 无法覆盖所有这种输入,也可能漏掉其他窗口创建的 Promise。

识别之后,按钮同步设置内部执行状态,并把最终清理放进 finally。业务回调必须把完整任务返回出来:

// 请求成功后还要更新索引,两步都属于按钮这次任务。
async function save() {
  await saveDocument();
  await refreshIndex();
}

@click="save" 和 @click="() => save()" 都保留返回值。下面的包装函数则会丢掉它:

<template>
  <sh-button
    @click="
      () => {
        save();
      }
    "
  >
    保存
  </sh-button>
</template>

这个回调返回 undefined,按钮只能把它当作同步操作。异步任务已经在后台运行,但组件没有可以等待的结果。包装函数需要 return save(),或者写成带 await 的 async 函数。

在 ShButton 中保留手动控制

这里的 ShButton 是自有基础按钮,下面的默认值属于这个组件的接口设计。组件在 Vue 3.6.0-rc.14 的 Vapor 模式下验证;前面所讲的 onClick 回调与 emit 返回值差异,也在 Vue 3.5.44 下做过最小运行验证。

我在 ShButton 中将点击间隔、内部任务状态和外部 loading 分开管理。调用方可以直接使用自动行为,也可以按操作需要调整策略:

<template>
  <sh-button @click="openDialog">打开</sh-button>
  <sh-button @click="save">保存</sh-button>
  <sh-button :click-interval="0" @click="count++">增加</sh-button>
  <sh-button :auto-loading="false" :loading="saving" @click="save">手动控制进度</sh-button>
</template>

最小间隔默认是 300 毫秒,auto-loading 默认开启。手动 loading 与自动指示取逻辑或;其中任意一项仍然成立,就继续显示指示器。外部把 loading 改成 false,也不能提前解除内部尚未完成的任务锁。

关闭 auto-loading 只关闭自动指示器,返回的任务仍然受到保护。此时按钮仍禁用并保留 aria-busy,需要的视觉反馈可以由外部 loading 或页面自己的进度区提供。按钮文字留在布局里,只隐藏其可见内容,再覆盖加载图标,避免加载时宽度缩成一个圆圈。

这套接口还需要保护几处容易遗漏的边界:

  • 内部锁在调用回调前设置,阻止回调同步重入。是否延迟展示动画属于视觉策略,不能跟着延迟加锁。
  • @click.once 对应独立的 onClickOnce,在第一次有效执行时消费。普通监听器与一次性监听器共享任务状态。
  • 多个监听器返回任务时,用 Promise.allSettled() 等待全部结束。某个任务提前失败,不代表其余任务已经停止;Promise.all() 的提前拒绝会使直接解锁过早。
  • 成功、同步异常、异步拒绝都走清理路径。异常交回 Vue 错误处理链,由业务提示或统一错误处理决定怎样展示,不在组件里假装保存成功。多项失败时报告第一个收集到的错误。

组件只能跟踪自己调用并取得返回值的任务。原生 type="submit" 触发的是表单提交,表单 @submit 返回的 Promise 不会自动成为按钮 @click 的返回值。提交状态由表单持有时,继续绑定手动 loading,并在表单提交函数中保护重复执行。

首次有效点击仍保留原生默认动作;冷却期被拒绝的点击会取消默认动作。按钮卸载也不会自动取消网络请求,取消能力仍由发起任务的一方负责。

表单通过校验后再防重复提交

在 PDF 导出对话框里,页边距限定为 0 至 40 毫米。输入 41 毫米后按 Enter,浏览器先触发提交按钮的 click,再校验页边距。校验失败时表单没有发出 submit,按钮的 300 毫秒冷却已经开始。如果立刻改成 16 毫米再按 Enter,第二次点击可能被冷却拦下,表单连校验都没机会执行。浏览器的处理顺序见 HTML 规范中的隐式提交和表单提交算法。

这个提交按钮设置 :click-interval="0"。鼠标点击和按 Enter 都由浏览器先校验,再交给表单的 @submit。处理器检查业务约束与对话框的打开状态,随即关闭对话框并交付导出参数。同一次打开只会交付一次。如果表单需要留在原处等请求完成,可以在校验通过后同步设置 submitting,让处理器拒绝重入,并用同一个状态禁用提交按钮。

Git 审阅的「标为已审」也是一个适合单独设置点击间隔的入口。审阅状态写入期间,按钮禁用,操作本身也有进行中检查。写入失败时,finally 会释放这次操作的锁。给这个按钮设置 :click-interval="0",用户看到错误就能重试,而不必等一个从第一次点击算起的固定窗口。

这两个问题只在快速纠正或重试时出现。浏览器回归因此要保留连续动作的时序。PDF 输入非法页边距后提交,马上改为合法值并按 Enter,确认只收到一次导出。Git 审阅让第一次写入失败,看到错误后立即再点,确认第二次写入成功。

组件库已经提供了哪些能力

截至 2026 年 11 月 18 日核对的文档和源码,自动等待回调已经有实际采用,不过不同库将能力放在不同组件上。

组件 自动处理的内容 使用边界
Varlet Button 开启 auto-loading 后,取得 onClick 返回值并等待,内部 pending 控制指示和点击拦截。 普通 Button 的可选能力;接口见其按钮文档。
Bitboss UI BbButton 点击处理函数返回 Promise 后自动 loading,完成前阻止重复点击。 当前文档版本为 3.0.0-beta.64;可通过 disableAutoLoading 关闭自动状态,外部任务仍可绑定 loading。
Arco Design Vue Popconfirm onBeforeOk 支持 Promise,确认按钮跟随等待过程显示 loading。 能力位于确认框的前置回调,普通 Button 仍是独立的 loading 接口。

需要特别区分「接受 Promise」和「自动显示 loading」。例如 Naive UI Popconfirm 会等待 onPositiveClick 的结果再决定是否关闭;从这条源码路径不能推出它同时自动管理了按钮 loading。选型时要继续看状态由谁设置、何时恢复,以及拒绝路径有没有完整处理。

自动能力适合由一个按钮拥有的独立任务。状态来自表单、Store 或多个入口时,手动 loading 仍然有明确用途。把这两种状态来源保留下来,调用方就能在简单操作里省掉样板代码,也能在复杂流程里明确管理任务。