213 lines
3.8 KiB
Markdown
213 lines
3.8 KiB
Markdown
---
|
|
name: template-refs
|
|
description: Access DOM elements and child component instances directly
|
|
---
|
|
|
|
# Template Refs
|
|
|
|
Template refs provide direct access to DOM elements and child component instances.
|
|
|
|
## Basic Usage (3.5+)
|
|
|
|
Use `useTemplateRef()` for type-safe refs:
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
import { useTemplateRef, onMounted } from 'vue'
|
|
|
|
const inputRef = useTemplateRef<HTMLInputElement>('input')
|
|
|
|
onMounted(() => {
|
|
inputRef.value?.focus()
|
|
})
|
|
</script>
|
|
|
|
<template>
|
|
<input ref="input" />
|
|
</template>
|
|
```
|
|
|
|
## Legacy Approach (Pre-3.5)
|
|
|
|
Use a ref with matching name:
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
import { ref, onMounted } from 'vue'
|
|
|
|
const inputRef = ref<HTMLInputElement | null>(null)
|
|
|
|
onMounted(() => {
|
|
inputRef.value?.focus()
|
|
})
|
|
</script>
|
|
|
|
<template>
|
|
<input ref="inputRef" />
|
|
</template>
|
|
```
|
|
|
|
## Refs in v-for
|
|
|
|
Collect multiple refs into an array:
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
import { ref, onMounted } from 'vue'
|
|
|
|
const items = ref([1, 2, 3])
|
|
const itemRefs = ref<HTMLLIElement[]>([])
|
|
</script>
|
|
|
|
<template>
|
|
<ul>
|
|
<li v-for="item in items" ref="itemRefs">
|
|
{{ item }}
|
|
</li>
|
|
</ul>
|
|
</template>
|
|
```
|
|
|
|
> Note: ref array order is not guaranteed to match source array order.
|
|
|
|
## Function Refs
|
|
|
|
Use a function for full control:
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
const elements = new Map<number, HTMLElement>()
|
|
|
|
function setItemRef(el: HTMLElement | null, id: number) {
|
|
if (el) {
|
|
elements.set(id, el)
|
|
} else {
|
|
elements.delete(id)
|
|
}
|
|
}
|
|
</script>
|
|
|
|
<template>
|
|
<div v-for="item in items" :ref="(el) => setItemRef(el, item.id)">
|
|
{{ item.name }}
|
|
</div>
|
|
</template>
|
|
```
|
|
|
|
## Component Refs
|
|
|
|
Access child component instance:
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
import { useTemplateRef, onMounted } from 'vue'
|
|
import Child from './Child.vue'
|
|
|
|
type ChildInstance = InstanceType<typeof Child>
|
|
const childRef = useTemplateRef<ChildInstance>('child')
|
|
|
|
onMounted(() => {
|
|
// Access exposed properties/methods
|
|
childRef.value?.someMethod()
|
|
})
|
|
</script>
|
|
|
|
<template>
|
|
<Child ref="child" />
|
|
</template>
|
|
```
|
|
|
|
### Exposing Component Properties
|
|
|
|
By default, `<script setup>` components are closed. Use `defineExpose`:
|
|
|
|
```vue
|
|
<!-- Child.vue -->
|
|
<script setup lang="ts">
|
|
import { ref } from 'vue'
|
|
|
|
const count = ref(0)
|
|
const increment = () => count.value++
|
|
|
|
// Only these are accessible via ref
|
|
defineExpose({
|
|
count,
|
|
increment
|
|
})
|
|
</script>
|
|
```
|
|
|
|
## Common Use Cases
|
|
|
|
### Focus Management
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
import { useTemplateRef } from 'vue'
|
|
|
|
const inputRef = useTemplateRef<HTMLInputElement>('input')
|
|
|
|
function focusInput() {
|
|
inputRef.value?.focus()
|
|
}
|
|
</script>
|
|
```
|
|
|
|
### Scroll Control
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
import { useTemplateRef } from 'vue'
|
|
|
|
const containerRef = useTemplateRef<HTMLDivElement>('container')
|
|
|
|
function scrollToBottom() {
|
|
const el = containerRef.value
|
|
if (el) {
|
|
el.scrollTop = el.scrollHeight
|
|
}
|
|
}
|
|
</script>
|
|
```
|
|
|
|
### Third-Party Library Integration
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
import { useTemplateRef, onMounted, onUnmounted } from 'vue'
|
|
import Chart from 'chart.js'
|
|
|
|
const canvasRef = useTemplateRef<HTMLCanvasElement>('canvas')
|
|
let chart: Chart | null = null
|
|
|
|
onMounted(() => {
|
|
if (canvasRef.value) {
|
|
chart = new Chart(canvasRef.value, {
|
|
// options
|
|
})
|
|
}
|
|
})
|
|
|
|
onUnmounted(() => {
|
|
chart?.destroy()
|
|
})
|
|
</script>
|
|
|
|
<template>
|
|
<canvas ref="canvas"></canvas>
|
|
</template>
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
1. **Refs are null before mount** - access in `onMounted` or later
|
|
2. **Conditional refs can be null** - elements with `v-if` may not exist
|
|
3. **Use optional chaining** - `ref.value?.method()` for safety
|
|
4. **Avoid overusing** - prefer declarative approaches when possible
|
|
|
|
<!--
|
|
Source references:
|
|
- https://vuejs.org/guide/essentials/template-refs.html
|
|
- https://vuejs.org/guide/typescript/composition-api.html#typing-template-refs
|
|
-->
|