docs: add the expose option and expose function (#1251)

Author: skirtles-code

src/api/composition-api.md

@@ -41,6 +41,7 @@ A component option that is executed **before** the component is created, once th
     attrs: Data
     slots: Slots
     emit: (event: string, ...args: unknown[]) => void
+    expose: (exposed?: Record<string, any>) => void
   }
 
   function setup(props: Data, context: SetupContext): Data
@@ -89,12 +90,37 @@ A component option that is executed **before** the component is created, once th
     setup() {
       const readersNumber = ref(0)
       const book = reactive({ title: 'Vue 3 Guide' })
-      // Please note that we need to explicitly expose ref value here
+      // Please note that we need to explicitly use ref value here
       return () => h('div', [readersNumber.value, book.title])
     }
   }
   ```
 
+  If you return a render function then you can't return any other properties. If you need to expose properties so that they can be accessed externally, e.g. via a `ref` in the parent, you can use `expose`:
+
+  ```js
+  // MyBook.vue
+
+  import { h } from 'vue'
+
+  export default {
+    setup(props, { expose }) {
+      const reset = () => {
+        // Some reset logic
+      }
+
+      // If you need to expose multiple properties they must all
+      // be included in the object passed to expose. expose can
+      // only be called once.
+      expose({
+        reset
+      })
+
+      return () => h('div')
+    }
+  }
+  ```
+
 - **See also**: [Composition API `setup`](../guide/composition-api-setup.html)
 
 ## Lifecycle Hooks

src/api/options-composition.md

@@ -286,26 +286,29 @@
     },
     setup({ name }) {
       watchEffect(() => {
-        console.log(`name is: ` + name) // Will not be reactive!
+        console.log(`name is: ` + name) // リアクティブではないでしょう！
       })
     }
   }
   ```
 
   `props` オブジェクトは、開発中のユーザランドのコードにとってはイミュータブルです（ユーザのコードがそれを変更しようとすると警告を表示します）。
 
-  第 2 引数は、`this` で以前に公開されていたプロパティの選択的な一覧を公開するコンテキストオブジェクトを提供します:
+  第 2 引数は、`setup` で便利だと思われる様々なオブジェクトや関数を公開するコンテキストオブジェクトを提供します:
 
   ```js
   const MyComponent = {
     setup(props, context) {
       context.attrs
       context.slots
       context.emit
+      context.expose
     }
   }
   ```
 
+  `attrs` と `slots` と `emit` はそれぞれ、インスタンスプロパティの [`$attrs`](/api/instance-properties.html#attrs) と [`$slots`](/api/instance-properties.html#slots) と [`$emit`](/api/instance-methods.html#emit) と同じです。
+
   `attrs` と `slots` は内部コンポーネントインスタンスの対応する値へのプロキシです。これは更新後も常に最新の値が公開されることを保証するので、古くなった参照へのアクセスを心配することなく、構造を変更することができます:
 
   ```js
@@ -319,6 +322,26 @@
   }
   ```
 
+  Vue 3.2 で追加された `expose` は、特定のプロパティをパブリックなコンポーネントインスタンスを介して公開することができる関数です。デフォルトでは、refs や `$parent` や `$root` を使って取得したパブリックなインスタンスは、テンプレートが使う内部インスタンスと同じです。`expose` を呼び出すと、指定したプロパティを持つ別のパブリックなインスタンスが作成されます:
+
+  ```js
+  const MyComponent = {
+    setup(props, { expose }) {
+      const count = ref(0)
+      const reset = () => count.value = 0
+      const increment = () => count.value++
+
+      // reset だけが、例えば $refs を介して、外部から利用できるようになります
+      expose({
+        reset
+      })
+
+      // 内部的には、テンプレートは count と increment にアクセスできます
+      return { count, increment }
+    }
+  }
+  ```
+
   `props` がコンテキストに含まれる代わりに、別の第 1 引数として置かれている理由はいくつかあります:
 
   - コンポーネントが `props` を使うことが、他のプロパティよりもずっと一般的であること、そしてコンポーネントが `props` のみを扱うことがとても頻繁にあることです。

src/api/options-data.md

@@ -252,7 +252,6 @@
   _ウォッチャの定義にアロー関数を使ってはいけない_ ということに注意してください（例: `searchQuery: newValue => this.updateAutocomplete(newValue)`）。その理由は、アロー関数が親のコンテキストを束縛するため、`this` は期待したとおりのコンポーネントインスタンスにはならないのと、`this.updateAutocomplete` が未定義になるからです。
   :::
 
-
 - **参照:** [ウォッチャ](../guide/computed.html#ウォッチャ)
 
 ## emits
@@ -302,3 +301,39 @@
   :::
 
 * **参照:** [属性の継承](../guide/component-attrs.html#属性の継承)
+
+## expose <Badge text="3.2+" />
+
+- **型:** `Array<string>`
+
+- **詳細:**
+
+  パブリックなコンポーネントインスタンスで公開するプロパティのリストです。
+
+  デフォルトでは、[`$refs`](/api/instance-properties.html#refs) や [`$parent`](/api/instance-properties.html#parent) や [`$root`](/api/instance-properties.html#root) からアクセスされるパブリックなインスタンスは、テンプレートで使われる内部コンポーネントのインスタンスと同じです。`expose` オプションは、パブリックなインスタンスからアクセス可能なプロパティを制限します。
+
+  Vue 自身が定義した `$el` や `$parent` などのプロパティは、常にパブリックなインスタンスで利用可能で、このリストに加える必要はありません。
+
+- **使用方法:**
+
+  ```js
+  export default {
+    // increment は公開されますが、
+    // count は内部的にしかアクセスできません
+    expose: ['increment'],
+
+    data() {
+      return {
+        count: 0
+      }
+    },
+
+    methods: {
+      increment() {
+        this.count++
+      }
+    }
+  }
+  ```
+
+- **参照:** [defineExpose](/api/sfc-script-setup.html#defineexpose)

src/guide/composition-api-setup.md

@@ -2,7 +2,7 @@
 
 > このセクションではコード例に[単一ファイルコンポーネント](single-file-component.html)の構文を使います。
 
-> このガイドは[Composition API の導入](composition-api-introduction.html)と[リアクティブの基礎](reactivity-fundamentals.html)を既に読んでいることを想定しています。 Composition API に初めて触れる方は、まずそちらを読んでみてください。
+> このガイドは [Composition API の導入](composition-api-introduction.html) と [リアクティブの基礎](reactivity-fundamentals.html) を既に読んでいることを想定しています。Composition API に初めて触れる方は、まずそちらを読んでみてください。
 
 ## 引数
 
@@ -15,7 +15,7 @@
 
 ### プロパティ
 
-`setup` 関数の第 1 引数は `props` 引数です。 標準コンポーネントで期待するように、`setup` 関数内の `props` はリアクティブで、新しい props が渡されたら更新されます。
+`setup` 関数の第 1 引数は `props` 引数です。標準コンポーネントで期待するように、`setup` 関数内の `props` はリアクティブで、新しい props が渡されたら更新されます。
 
 ```js
 // MyBook.vue
@@ -64,21 +64,24 @@ setup(props) {
 
 ### コンテキスト
 
-`setup` 関数に渡される第 2 引数は `context` です。`context` は 3 つのコンポーネントプロパティを公開する一般的な JavaScript オブジェクトです。:
+`setup` 関数に渡される第 2 引数は `context` です。`context` は一般的な JavaScript オブジェクトで、`setup` の中で便利と思われる他の値を公開します:
 
 ```js
 // MyBook.vue
 
 export default {
   setup(props, context) {
-    // Attributes (Non-reactive object)
+    // Attributes (Non-reactive object, equivalent to $attrs)
     console.log(context.attrs)
 
-    // Slots (Non-reactive object)
+    // Slots (Non-reactive object, equivalent to $slots)
     console.log(context.slots)
 
-    // Emit Events (Method)
+    // Emit events (Function, equivalent to $emit)
     console.log(context.emit)
+
+    // Expose public properties (Function)
+    console.log(context.expose)
   }
 }
 ```
@@ -88,13 +91,15 @@ export default {
 ```js
 // MyBook.vue
 export default {
-  setup(props, { attrs, slots, emit }) {
+  setup(props, { attrs, slots, emit, expose }) {
     ...
   }
 }
 ```
 
-`attrs` と `slots` はステートフルなオブジェクトです。コンポーネント自身が更新されたとき、常に更新されます。 つまり、分割代入の使用を避け、`attrs.x` や `slots.x` のようにプロパティを常に参照する必要があります。 また、`props` とは異なり、 `attrs` と `slots` はリアクティブ**ではない**ということに注意してください。 もし、`attrs` か `slots` の変更による副作用を適用したいのなら、`onUpdated` ライフサイクルフックの中で行うべきです。
+`attrs` と `slots` はステートフルなオブジェクトです。コンポーネント自身が更新されたとき、常に更新されます。つまり、分割代入の使用を避け、`attrs.x` や `slots.x` のようにプロパティを常に参照する必要があります。また、`props` とは異なり、`attrs` と `slots` のプロパティは **リアクティブではない** ということに注意してください。もし、`attrs` か `slots` の変更による副作用を適用したいのなら、`onBeforeUpdate` ライフサイクルフックの中で行うべきです。
+
+`expose` の役割については後で説明します。
 
 ## コンポーネントプロパティへのアクセス
 
@@ -105,7 +110,7 @@ export default {
 - `slots`
 - `emit`
 
-言い換えると、以下のコンポーネントオプションには**アクセスできません**:
+言い換えると、以下のコンポーネントオプションには **アクセスできません**:
 
 - `data`
 - `computed`
@@ -157,12 +162,35 @@ export default {
   setup() {
     const readersNumber = ref(0)
     const book = reactive({ title: 'Vue 3 Guide' })
-    // ここでは明示的に ref の値を公開する必要があることに注意してください。
+    // ここでは明示的に ref の値を使用する必要があることに注意してください。
     return () => h('div', [readersNumber.value, book.title])
   }
 }
 ```
 
+レンダリング関数を返すことで、他のものを返すことができなくなります。内部的には問題ありませんが、このコンポーネントのメソッドをテンプレート参照から親コンポーネントに公開したい場合には、問題となります。
+
+この問題を解決するには、`expose` を呼び出して、外部コンポーネントのインスタンスで利用可能なプロパティを定義したオブジェクトを渡します:
+
+```js
+import { h, ref } from 'vue'
+
+export default {
+  setup(props, { expose }) {
+    const count = ref(0)
+    const increment = () => ++count.value
+
+    expose({
+      increment
+    })
+
+    return () => h('div', count.value)
+  }
+}
+```
+
+この `increment` メソッドは、親コンポーネントでテンプレート参照を介して利用可能になります。
+
 ## `this` の使用
 
 **`setup()` 内では、`this` は現在のアクティブなインスタンスへの参照にはなりません。** `setup()` は他のコンポーネントオプションが解決される前に呼び出されるので、`setup()` 内の `this` は他のオプション内の `this` とは全く異なる振る舞いをします。 これは、`setup()` を他のオプション API と一緒に使った場合に混乱を引き起こす可能性があります。

src/style-guide/README.md

@@ -1284,6 +1284,7 @@ HTML では、空白を含まない属性値は引用符でくくらなくても
     - `inheritAttrs`
     - `props`
     - `emits`
+    - `expose`
 
 6. **コンポジション API** (コンポジション API を使用するためのエントリポイント)
     - `setup`