Merge branch 'main' into issue-2258-2261

src/api/application.md

@@ -90,6 +90,18 @@
   }
   ```
 
+## app.onUnmount() <sup class="vt-badge" data-text="3.5+" /> {#app-onunmount}
+
+アプリケーションがアンマウントされたときに呼び出されるコールバックを登録します。
+
+- **型**
+
+  ```ts
+  interface App {
+    onUnmount(callback: () => any): void
+  }
+  ```
+
 ## app.component() {#app-component}
 
 名称文字列とコンポーネント定義を両方渡す場合、グローバルコンポーネントとして登録し、名称のみ渡す場合、登録済みのコンポーネントを取得します。
@@ -627,3 +639,21 @@ Vue からの実行時警告に対して、カスタムハンドラーを割り
   const id1 = useId() // 'my-app:0'
   const id2 = useId() // 'my-app:1'
   ```
+
+## app.config.throwUnhandledErrorInProduction <sup class="vt-badge" data-text="3.5+" /> {#app-config-throwunhandlederrorinproduction}
+
+プロダクションモードで未処理のエラーを強制的にスローします。
+
+- **型:** `boolean`
+
+- **デフォルト:** `false`
+
+- **詳細**
+
+  デフォルトでは、Vue アプリケーション内でスローされたが明示的に処理されていないエラーは、開発モードとプロダクションモードで異なる動作をします:
+
+  - 開発中は、エラーがスローされ、アプリケーションがクラッシュする可能性があります。これは、エラーを目立たせることで、開発中に気づいて修正できるようにするためです。
+
+  - プロダクションでは、エンドユーザーへの影響を最小限に抑えるため、エラーはコンソールにログ出力されるだけです。ただし、これによりプロダクションでのみ発生するエラーがエラー監視サービスで捕捉されない可能性があります。
+
+  `app.config.throwUnhandledErrorInProduction` を `true` に設定することで、プロダクションモードでも未処理のエラーがスローされるようになります。

src/api/reactivity-advanced.md

@@ -336,8 +336,10 @@ Vue で作成されたプロキシの、未加工の元のオブジェクトを
 
 各 Vue コンポーネントの `setup()` 関数はエフェクトスコープでも呼び出されるので、このメソッドは再利用可能なコンポジション関数において、コンポーネントに結合しない `onUnmounted` の代替として使用できます。
 
+アクティブなエフェクトスコープがない状態でこの関数を呼び出すと、警告が表示されます。バージョン 3.5 以上では、第二引数に `true` を渡すことで、警告を抑制することができます。
+
 - **型**
 
   ```ts
-  function onScopeDispose(fn: () => void): void
+  function onScopeDispose(fn: () => void, failSilently?: boolean): void
   ```

src/api/reactivity-core.md

@@ -238,7 +238,7 @@
   function watchEffect(
     effect: (onCleanup: OnCleanup) => void,
     options?: WatchEffectOptions
-  ): StopHandle
+  ): WatchHandle
 
   type OnCleanup = (cleanupFn: () => void) => void
 
@@ -248,7 +248,12 @@
     onTrigger?: (event: DebuggerEvent) => void
   }
 
-  type StopHandle = () => void
+  interface WatchHandle {
+    (): void // 呼び出し可能、`stop` と同様
+    pause: () => void
+    resume: () => void
+    stop: () => void
+  }
   ```
 
 - **詳細**
@@ -295,6 +300,47 @@
   stop()
   ```
 
+  ウォッチャーの一時停止 / 再開: <sup class="vt-badge" data-text="3.5+" />
+
+  ```js
+  const { stop, pause, resume } = watchEffect(() => {})
+
+  // ウォッチャーを一時停止する
+  pause()
+
+  // あとで再開する
+  resume()
+
+  // 停止する
+  stop()
+  ```
+
+  副作用のクリーンアップ:
+
+  ```js
+  watchEffect(async (onCleanup) => {
+    const { response, cancel } = doAsyncWork(newId)
+    // `id` が変更されると `cancel` が呼ばれ、
+    // 前のリクエストがまだ完了していない場合はキャンセルされます
+    onCleanup(cancel)
+    data.value = await response
+  })
+  ```
+
+  3.5+ での副作用のクリーンアップ:
+
+  ```js
+  import { onWatcherCleanup } from 'vue'
+
+  watchEffect(async () => {
+    const { response, cancel } = doAsyncWork(newId)
+    // `id` が変更されると `cancel` が呼ばれ、
+    // 前のリクエストがまだ完了していない場合はキャンセルされます
+    onWatcherCleanup(cancel)
+    data.value = await response
+  })
+  ```
+
   オプション:
 
   ```js
@@ -333,14 +379,14 @@
     source: WatchSource<T>,
     callback: WatchCallback<T>,
     options?: WatchOptions
-  ): StopHandle
+  ): WatchHandle
 
   // 複数ソースの監視
   function watch<T>(
     sources: WatchSource<T>[],
     callback: WatchCallback<T[]>,
     options?: WatchOptions
-  ): StopHandle
+  ): WatchHandle
 
   type WatchCallback<T> = (
     value: T,
@@ -357,12 +403,19 @@
 
   interface WatchOptions extends WatchEffectOptions {
     immediate?: boolean // 初期値: false
-    deep?: boolean // 初期値: false
+    deep?: boolean | number // 初期値: false
     flush?: 'pre' | 'post' | 'sync' // 初期値: 'pre'
     onTrack?: (event: DebuggerEvent) => void
     onTrigger?: (event: DebuggerEvent) => void
     once?: boolean // 初期値: false
   }
+
+  interface WatchHandle {
+    (): void // 呼び出し可能、`stop` と同様
+    pause: () => void
+    resume: () => void
+    stop: () => void
+  }
   ```
 
   > 読みやすくするため、型は単純化されています。
@@ -385,7 +438,7 @@
   省略可能な第 3 引数は、以下のオプションをサポートするオプションオブジェクトです:
 
   - **`immediate`**: ウォッチャーが作成されたら、すぐにコールバックを起動します。最初の呼び出しでは、古い値は `undefined` になります。
-  - **`deep`**: オブジェクトの場合、深い変更の際にコールバックが発生するように、ソースの深い探索を強制します。詳しくは[ディープ・ウォッチャー](/guide/essentials/watchers#deep-watchers)をご参照ください。
+  - **`deep`**: オブジェクトの場合、深い変更の際にコールバックが発生するように、ソースの深い探索を強制します。3.5+ では、どこまで深くオブジェクトを監視するかを数値で指定することもできます。詳しくは[ディープ・ウォッチャー](/guide/essentials/watchers#deep-watchers)をご参照ください。
   - **`flush`**: コールバックのフラッシュタイミングを調整します。詳しくは[コールバックが実行されるタイミング](/guide/essentials/watchers#callback-flush-timing)や [`watchEffect()`](/api/reactivity-core#watcheffect) をご参照ください。
   - **`onTrack / onTrigger`**: ウォッチャーの依存関係をデバッグします。詳しくは[ウォッチャーのデバッグ](/guide/extras/reactivity-in-depth#watcher-debugging)をご参照ください。
   - **`once`**: コールバックを一度だけ実行します。最初のコールバックが実行されると、ウォッチャーは自動的に停止します。<sup class="vt-badge" data-text="3.4+" />
@@ -472,6 +525,21 @@
   stop()
   ```
 
+  ウォッチャーの一時停止 / 再開: <sup class="vt-badge" data-text="3.5+" />
+
+  ```js
+  const { stop, pause, resume } = watchEffect(() => {})
+
+  // ウォッチャーを一時停止する
+  pause()
+
+  // あとで再開する
+  resume()
+
+  // 停止する
+  stop()
+  ```
+
   副作用のクリーンアップ:
 
   ```js
@@ -484,7 +552,45 @@
   })
   ```
 
+  3.5+ での副作用のクリーンアップ:
+
+  ```js
+  import { onWatcherCleanup } from 'vue'
+
+  watch(id, async (newId) => {
+    const { response, cancel } = doAsyncWork(newId)
+    onWatcherCleanup(cancel)
+    data.value = await response
+  })
+  ```
+
 - **参照**
 
   - [ガイド - ウォッチャー](/guide/essentials/watchers)
   - [ガイド - ウォッチャーのデバッグ](/guide/extras/reactivity-in-depth#watcher-debugging)
+
+## onWatcherCleanup() <sup class="vt-badge" data-text="3.5+" /> {#onwatchercleanup}
+
+現在のウォッチャーが再実行される直前に実行されるクリーンアップ関数を登録します。`watchEffect` エフェクト関数または `watch` コールバック関数の同期実行中にのみ呼び出すことができます（つまり、非同期関数内の `await` ステートメントの後には呼び出すことができません）。
+
+- **型**
+
+  ```ts
+  function onWatcherCleanup(
+    cleanupFn: () => void,
+    failSilently?: boolean
+  ): void
+  ```
+
+- **例**
+
+  ```ts
+  import { watch, onWatcherCleanup } from 'vue'
+
+  watch(id, (newId) => {
+    const { response, cancel } = doAsyncWork(newId)
+    // `id` が変更されると `cancel` が呼ばれ、
+    // 前のリクエストがまだ完了していない場合はキャンセルされます
+    onWatcherCleanup(cancel)
+  })
+  ```

src/api/sfc-script-setup.md

@@ -209,12 +209,48 @@ const emit = defineEmits<{
 
   この制限は 3.3 で解決されました。Vue の最新バージョンは型引数の位置でインポートされた複雑な型の限定されたセットを参照することをサポートしています。しかし、型からランタイムへの変換は依然として AST ベースであるため、実際の型解析を必要とするいくつかの複雑な型、例えば条件型など、はサポートされていません。条件型は単一の props の型には使用できますが、props オブジェクト全体の型には使用できません。
 
-### 型宣言を使用時のデフォルトの props 値 {#default-props-values-when-using-type-declaration}
+### リアクティブな props の分割代入 <sup class="vt-badge" data-text="3.5+" /> {#reactive-props-destructure}
 
-型のみの `defineProps` 宣言の欠点は、props のデフォルト値を提供する方法がないことです。この問題を解決するために、`withDefaults` コンパイラーマクロも用意されています:
+Vue 3.5 以降、`defineProps` の戻り値から分割代入された変数はリアクティブです。同じ `<script setup>` ブロック内で `defineProps` から分割代入された変数にアクセスするコードがあると、Vue のコンパイラーは自動的に `props.` を先頭に追加します:
 
 ```ts
-export interface Props {
+const { foo } = defineProps(['foo'])
+
+watchEffect(() => {
+  // 3.5 以前は 1 回だけ実行されます。
+  // 3.5 以降は "foo" が変更されるたびに再実行されます。
+  console.log(foo)
+})
+```
+
+上記のコードがコンパイルされると以下のようになります:
+
+```js {5}
+const props = defineProps(['foo'])
+
+watchEffect(() => {
+  // `foo` はコンパイラーによって `props.foo` に変換されました。
+  console.log(props.foo)
+})
+```
+
+さらに、JavaScript のネイティブなデフォルト値構文を使用して、props のデフォルト値を宣言できます。これは型ベースの props 宣言を使用する場合に特に便利です:
+
+```ts
+interface Props {
+  msg?: string
+  labels?: string[]
+}
+
+const { msg = 'hello', labels = ['one', 'two'] } = defineProps<Props>()
+```
+
+### 型宣言を使用時のデフォルトの props 値 <sup class="vt-badge ts" /> {#default-props-values-when-using-type-declaration}
+
+3.5 以降では、リアクティブな props の分割代入を使用すると、自然な形でデフォルト値を宣言できます。しかし、3.4 以前では、リアクティブな props の分割代入はデフォルトで有効になっていません。型ベースの宣言で props のデフォルト値を宣言するには、`withDefaults` コンパイラーマクロが必要です:
+
+```ts
+interface Props {
   msg?: string
   labels?: string[]
 }
@@ -228,7 +264,7 @@ const props = withDefaults(defineProps<Props>(), {
 これは、同等なランタイム props の `default` オプションにコンパイルされます。さらに、`withDefaults` ヘルパーは、デフォルト値の型チェックを行います。また、返される `props` の型が、デフォルト値が宣言されているプロパティに対して、省略可能フラグが削除されていることを保証します。
 
 :::info
-変更可能な参照型（配列やオブジェクトなど）のデフォルト値は、偶発的な変更や外部からの副作用を避けるために、関数でラップする必要があることに注意してください。こうすることで、各コンポーネントのインスタンスがデフォルト値のコピーを取得することが保証されます。
+変更可能な参照型（配列やオブジェクトなど）のデフォルト値は、偶発的な変更や外部からの副作用を避けるために `withDefaults` を使う時は、関数でラップする必要があることに注意してください。こうすることで、各コンポーネントのインスタンスがデフォルト値のコピーを取得することが保証されます。これは分割代入でデフォルト値を使う時は**不要**です。
 :::
 
 ## defineModel() <sup class="vt-badge" data-text="3.4+" /> {#definemodel}
@@ -487,7 +523,6 @@ ref<InstanceType<typeof componentWithoutGenerics>>();
 ref<ComponentExposed<typeof genericComponent>>();
 ```
 
-
 ## 制限 {#restrictions}
 
 - モジュールの実行セマンティクスの違いにより、`<script setup>` 内のコードは、SFC のコンテキストに依存しています。外部の `.js` や `.ts` ファイルに移動すると、開発者とツールの両方に混乱を招く可能性があります。そのため、**`<script setup>`** は、`src` 属性と一緒に使うことはできません。