From 975ae1d0263325312b78d37c8fc0626d364c3e2c Mon Sep 17 00:00:00 2001
From: Vida Xie <vida_2020@163.com>
Date: Thu, 6 Nov 2025 00:54:01 +0800
Subject: [PATCH] feat: introduce `WatchEffectOptions#signal`

---
 src/api/options-state.md   |  2 ++
 src/api/reactivity-core.md | 13 +++++++++++++
 2 files changed, 15 insertions(+)

diff --git a/src/api/options-state.md b/src/api/options-state.md
index 4aa176a250..1cc6361e61 100644
--- a/src/api/options-state.md
+++ b/src/api/options-state.md
@@ -275,6 +275,7 @@ Declare watch callbacks to be invoked on data change.
 
   type ObjectWatchOptionItem = {
     handler: WatchCallback | string
+    signal?: AbortSignal
     immediate?: boolean // default: false
     deep?: boolean // default: false
     flush?: 'pre' | 'post' | 'sync' // default: 'pre'
@@ -293,6 +294,7 @@ Declare watch callbacks to be invoked on data change.
 
   The value can also be a string of a method name (declared via `methods`), or an object that contains additional options. When using the object syntax, the callback should be declared under the `handler` field. Additional options include:
 
+  - **`signal`**: stop the watcher when the given [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) is aborted.
   - **`immediate`**: trigger the callback immediately on watcher creation. Old value will be `undefined` on the first call.
   - **`deep`**: force deep traversal of the source if it is an object or an array, so that the callback fires on deep mutations. See [Deep Watchers](/guide/essentials/watchers#deep-watchers).
   - **`flush`**: adjust the callback's flush timing. See [Callback Flush Timing](/guide/essentials/watchers#callback-flush-timing) and [`watchEffect()`](/api/reactivity-core#watcheffect).
diff --git a/src/api/reactivity-core.md b/src/api/reactivity-core.md
index 61195ed0f2..e176664c05 100644
--- a/src/api/reactivity-core.md
+++ b/src/api/reactivity-core.md
@@ -243,6 +243,7 @@ Runs a function immediately while reactively tracking its dependencies and re-ru
   type OnCleanup = (cleanupFn: () => void) => void
 
   interface WatchEffectOptions {
+    signal?: AbortSignal
     flush?: 'pre' | 'post' | 'sync' // default: 'pre'
     onTrack?: (event: DebuggerEvent) => void
     onTrigger?: (event: DebuggerEvent) => void
@@ -328,6 +329,18 @@ Runs a function immediately while reactively tracking its dependencies and re-ru
   })
   ```
 
+  Stopping the watchers with `AbortController`: <sup class="vt-badge" data-text="3.6+" />
+
+  ```js
+  const controller = new AbortController()
+
+  watchEffect(() => {}, { signal: controller.signal })
+  watchEffect(() => {}, { signal: controller.signal })
+
+  // when the watchers are no longer needed:
+  controller.abort()
+  ```
+
   Options:
 
   ```js