3.5: useTemplateRef()

yyx990803 · yyx990803 · commit 71cec8136523 · 2024-09-03T21:15:28.000+08:00
diff --git a/src/api/composition-api-helpers.md b/src/api/composition-api-helpers.md
@@ -4,18 +4,45 @@
 
 Returns the `attrs` object from the [Setup Context](/api/composition-api-setup#setup-context), which includes the [fallthrough attributes](/guide/components/attrs#fallthrough-attributes) of the current component. This is intended to be used in `<script setup>` where the setup context object is not available.
 
+- **Type**
+
+  ```ts
+  function useAttrs(): Record<string, unknown>
+  ```
+
 ## useSlots() {#useslots}
 
 Returns the `slots` object from the [Setup Context](/api/composition-api-setup#setup-context), which includes parent passed slots as callable functions that return Virtual DOM nodes. This is intended to be used in `<script setup>` where the setup context object is not available.
 
 If using TypeScript, [`defineSlots()`](/api/sfc-script-setup#defineslots) should be preferred instead.
 
+- **Type**
+
+  ```ts
+  function useSlots(): Record<string, (...args: any[]) => VNode[]>
+  ```
+
 ## useModel() <sup class="vt-badge" data-text="3.4+" /> {#usemodel}
 
 This is the underlying helper that powers [`defineModel()`](/api/sfc-script-setup#definemodel). If using `<script setup>`, `defineModel()` should be preferred instead.
 
 `useModel()` can be used in non-SFC components, e.g. when using raw `setup()` function. It expects the `props` object as the first argument, and the model name as the second argument. The optional third argument can be used to declare custom getter and setter for the resulting model ref. Note that unlike `defineModel()`, you are responsible for declaring the props and emits yourself.
 
+- **Type**
+
+  ```ts
+  function useModel(
+    props: Record<string, any>,
+    key: string,
+    options?: DefineModelOptions
+  )
+
+  type DefineModelOptions<T = any> = {
+    get?: (v: T) => any
+    set?: (v: T) => any
+  }
+  ```
+
 - **Example**
 
   ```js
@@ -31,9 +58,46 @@ This is the underlying helper that powers [`defineModel()`](/api/sfc-script-setu
 
 ## useTemplateRef() <sup class="vt-badge" data-text="3.5+" /> {#usetemplateref}
 
+Returns a shallow ref whose value will be synced with the template element or component with a matching ref attribute.
+
+- **Type**
+
+  ```ts
+  function useTemplateRef<T>(key: string): Readonly<ShallowRef<T | null>>
+  ```
+
+- **Example**
+
+  ```vue
+  <script setup>
+  import { useTemplateRef, onMounted } from 'vue'
+
+  const inputRef = useTemplateRef('input')
+
+  onMounted(() => {
+    inputRef.value.focus()
+  })
+  </script>
+
+  <template>
+    <input ref="input" />
+  </template>
+  ```
+
+- **See also**
+  - [Guide - Template Refs](/guide/essentials/template-refs)
+  - [Guide - Typing Template Refs](/guide/typescript/composition-api#typing-template-refs) <sup class="vt-badge ts" />
+  - [Guide - Typing Component Template Refs](/guide/typescript/composition-api#typing-component-template-refs) <sup class="vt-badge ts" />
+
 ## useId() <sup class="vt-badge" data-text="3.5+" /> {#useid}
 
-`useId()` is an API that can be used to generate unique-per-application IDs.
+Used to generate unique-per-application IDs for accessibility attributes or form elements.
+
+- **Type**
+
+  ```ts
+  function useId(): string
+  ```
 
 - **Example**
 
@@ -55,7 +119,7 @@ This is the underlying helper that powers [`defineModel()`](/api/sfc-script-setu
 - **Details**
 
   IDs generated by `useId()` are unique-per-application. It can be used to generate IDs for form elements and accessibility attributes. Multiple calls in the same component will generate different IDs; multiple instances of the same component calling `useId()` will also have different IDs.
-  
+
   IDs generated by `useId()` are also guaranteed to be stable across the server and client renders, so they can be used in SSR applications without leading to hydration mismatches.
 
   If you have more than one Vue application instance of the same page, you can avoid ID conflicts by giving each app an ID prefix via [`app.config.idPrefix`](/api/application#app-config-idprefix).
diff --git a/src/guide/essentials/template-refs.md b/src/guide/essentials/template-refs.md
@@ -12,7 +12,32 @@ While Vue's declarative rendering model abstracts away most of the direct DOM op
 
 <div class="composition-api">
 
-To obtain the reference with Composition API, we need to declare a ref with a name that matches the template ref attribute's value:
+To obtain the reference with Composition API, we can use the [`useTemplateRef()`](/api/composition-api-helpers#usetemplateref) <sup class="vt-badge" data-text=
+"3.5+" /> helper:
+
+```vue
+<script setup>
+import { useTemplateRef, onMounted } from 'vue'
+
+// the first argument must match the ref value in the template
+const input = useTemplateRef('my-input')
+
+onMounted(() => {
+  input.value.focus()
+})
+</script>
+
+<template>
+  <input ref="my-input" />
+</template>
+```
+
+When using TypeScript, Vue's IDE support and `vue-tsc` will automatically infer the type of `inputRef.value` based on what element or component the matching `ref` attribute is used on.
+
+<details>
+<summary>Usage before 3.5</summary>
+
+In versions before 3.5 where `useTemplateRef()` was not introduced, we need to declare a ref with a name that matches the template ref attribute's value:
 
 ```vue
 <script setup>
@@ -46,6 +71,8 @@ export default {
 }
 ```
 
+</details>
+
 </div>
 <div class="options-api">
 
@@ -95,6 +122,33 @@ See also: [Typing Template Refs](/guide/typescript/composition-api#typing-templa
 
 When `ref` is used inside `v-for`, the corresponding ref should contain an Array value, which will be populated with the elements after mount:
 
+```vue
+<script setup>
+import { ref, useTemplateRef, onMounted } from 'vue'
+
+const list = ref([
+  /* ... */
+])
+
+const itemRefs = useTemplateRef('items')
+
+onMounted(() => console.log(itemRefs.value))
+</script>
+
+<template>
+  <ul>
+    <li v-for="item in list" ref="items">
+      {{ item }}
+    </li>
+  </ul>
+</template>
+```
+
+[Try it in the Playground](https://play.vuejs.org/#eNp9UsluwjAQ/ZWRLwQpDepyQoDUIg6t1EWUW91DFAZq6tiWF4oU5d87dtgqVRyyzLw3b+aN3bB7Y4ptQDZkI1dZYTw49MFMuBK10dZDAxZXOQSHC6yNLD3OY6zVsw7K4xJaWFldQ49UelxxVWnlPEhBr3GszT6uc7jJ4fazf4KFx5p0HFH+Kme9CLle4h6bZFkfxhNouAIoJVqfHQSKbSkDFnVpMhEpovC481NNVcr3SaWlZzTovJErCqgydaMIYBRk+tKfFLC9Wmk75iyqg1DJBWfRxT7pONvTAZom2YC23QsMpOg0B0l0NDh2YjnzjpyvxLrYOK1o3ckLZ5WujSBHr8YL2gxnw85lxEop9c9TynkbMD/kqy+svv/Jb9wu5jh7s+jQbpGzI+ZLu0byEuHZ+wvt6Ays9TJIYl8A5+i0DHHGjvYQ1JLGPuOlaR/TpRFqvXCzHR2BO5iKg0Zmm/ic0W2ZXrB+Gve2uEt1dJKs/QXbwePE)
+
+<details>
+<summary>Usage before 3.5</summary>
+
 ```vue
 <script setup>
 import { ref, onMounted } from 'vue'
@@ -117,7 +171,7 @@ onMounted(() => console.log(itemRefs.value))
 </template>
 ```
 
-[Try it in the Playground](https://play.vuejs.org/#eNpFjs1qwzAQhF9l0CU2uDZtb8UOlJ576bXqwaQyCGRJyCsTEHr3rGwnOehnd2e+nSQ+vW/XqMSH6JdL0J6wKIr+LK2evQuEhKCmBs5+u2hJ/SNjCm7GiV0naaW9OLsQjOZrKNrq97XBW4P3v/o51qTmHzUtd8k+e0CrqsZwRpIWGI0KVN0N7TqaqNp59JUuEt2SutKXY5elmimZT9/t2Tk1F+z0ZiTFFdBHs738Mxrry+TCIEWhQ9sttRQl0tEsK6U4HEBKW3LkfDA6o3dst3H77rFM5BtTfm/P)
+</details>
 
 </div>
 <div class="options-api">
@@ -173,6 +227,26 @@ Note we are using a dynamic `:ref` binding so we can pass it a function instead
 
 <div class="composition-api">
 
+```vue
+<script setup>
+import { useTemplateRef, onMounted } from 'vue'
+import Child from './Child.vue'
+
+const childRef = useTemplateRef('child')
+
+onMounted(() => {
+  // childRef.value will hold an instance of <Child />
+})
+</script>
+
+<template>
+  <Child ref="child" />
+</template>
+```
+
+<details>
+<summary>Usage before 3.5</summary>
+
 ```vue
 <script setup>
 import { ref, onMounted } from 'vue'
@@ -190,6 +264,8 @@ onMounted(() => {
 </template>
 ```
 
+</details>
+
 </div>
 <div class="options-api">
 
diff --git a/src/guide/typescript/composition-api.md b/src/guide/typescript/composition-api.md
@@ -371,6 +371,17 @@ const foo = inject('foo') as string
 
 ## Typing Template Refs {#typing-template-refs}
 
+With Vue 3.5 and `@vue/language-tools` 2.1 (powering both the IDE language service and `vue-tsc`), the type of refs created by `useTemplateRef()` in SFCs can be **automatically inferred** for static refs based on what element the matching `ref` attribute is used on.
+
+In cases where auto-inference is not possible, you can still cast the template ref to an explicit type via the generic argument:
+
+```ts
+const el = useTemplateRef<HTMLInputElement>(null)
+```
+
+<details>
+<summary>Usage before 3.5</summary>
+
 Template refs should be created with an explicit generic type argument and an initial value of `null`:
 
 ```vue
@@ -389,50 +400,45 @@ onMounted(() => {
 </template>
 ```
 
+</details>
+
 To get the right DOM interface you can check pages like [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#technical_summary).
 
 Note that for strict type safety, it is necessary to use optional chaining or type guards when accessing `el.value`. This is because the initial ref value is `null` until the component is mounted, and it can also be set to `null` if the referenced element is unmounted by `v-if`.
 
 ## Typing Component Template Refs {#typing-component-template-refs}
 
-Sometimes you might need to annotate a template ref for a child component in order to call its public method. For example, we have a `MyModal` child component with a method that opens the modal:
-
-```vue
-<!-- MyModal.vue -->
-<script setup lang="ts">
-import { ref } from 'vue'
-
-const isContentShown = ref(false)
-const open = () => (isContentShown.value = true)
+With Vue 3.5 and `@vue/language-tools` 2.1 (powering both the IDE language service and `vue-tsc`), the type of refs created by `useTemplateRef()` in SFCs can be **automatically inferred** for static refs based on what element or component the matching `ref` attribute is used on.
 
-defineExpose({
-  open
-})
-</script>
-```
+In cases where auto-inference is not possible (e.g. non-SFC usage or dynamic components), you can still cast the template ref to an explicit type via the generic argument.
 
-In order to get the instance type of `MyModal`, we need to first get its type via `typeof`, then use TypeScript's built-in `InstanceType` utility to extract its instance type:
+In order to get the instance type of an imported component, we need to first get its type via `typeof`, then use TypeScript's built-in `InstanceType` utility to extract its instance type:
 
 ```vue{5}
 <!-- App.vue -->
 <script setup lang="ts">
-import MyModal from './MyModal.vue'
+import { useTemplateRef } from 'vue'
+import Foo from './Foo.vue'
+import Bar from './Bar.vue'
 
-const modal = ref<InstanceType<typeof MyModal> | null>(null)
+type FooType = InstanceType<typeof Foo>
+type BarType = InstanceType<typeof Bar>
 
-const openModal = () => {
-  modal.value?.open()
-}
+const compRef = useTemplateRef<FooType | BarType>('comp')
 </script>
+
+<template>
+  <component :is="Math.random() > 0.5 ? Foo : Bar" ref="comp" />
+</template>
 ```
 
 In cases where the exact type of the component isn't available or isn't important, `ComponentPublicInstance` can be used instead. This will only include properties that are shared by all components, such as `$el`:
 
 ```ts
-import { ref } from 'vue'
+import { useTemplateRef } from 'vue'
 import type { ComponentPublicInstance } from 'vue'
 
-const child = ref<ComponentPublicInstance | null>(null)
+const child = useTemplateRef<ComponentPublicInstance | null>(null)
 ```
 
 In cases where the component referenced is a [generic component](/guide/typescript/overview.html#generic-components), for instance `MyGenericModal`:
@@ -457,15 +463,16 @@ It needs to be referenced using `ComponentExposed` from the [`vue-component-type
 ```vue
 <!-- App.vue -->
 <script setup lang="ts">
+import { useTemplateRef } from 'vue'
 import MyGenericModal from './MyGenericModal.vue'
+import type { ComponentExposed } from 'vue-component-type-helpers'
 
-import type { ComponentExposed } from 'vue-component-type-helpers';
-
-const modal = ref<ComponentExposed<typeof MyModal> | null>(null)
+const modal = useTemplateRef<ComponentExposed<typeof MyModal>>(null)
 
 const openModal = () => {
   modal.value?.open('newValue')
 }
 </script>
 ```
 
+Note that with `@vue/language-tools` 2.1+, static template refs' types can be automatically inferred and the above is only needed in edge cases.
