Vue useTemplateRefの使い方 - ref()との違い・TypeScript型付け・実践パターンまで網羅

function useTemplateRef<T>(key: string): Readonly<ShallowRef<T | null>>

<script setup>
import { useTemplateRef, onMounted } from 'vue'

const inputRef = useTemplateRef('my-input')

onMounted(() => {
  inputRef.value.focus()
})
</script>

<template>
  <input ref="my-input" />
</template>

<script setup>
import { ref, onMounted } from 'vue'

// 変数名「input」がテンプレートの ref="input" と一致する必要がある
const input = ref(null)

onMounted(() => {
  input.value.focus()
})
</script>

<template>
  <input ref="input" />
</template>

const canvasRef = useTemplateRef<HTMLCanvasElement>('canvas')

import { useTemplateRef } from 'vue'
import MyDialog from './MyDialog.vue'

type MyDialogInstance = InstanceType<typeof MyDialog>
const dialogRef = useTemplateRef<MyDialogInstance>('dialog')

import type { ComponentExposed } from 'vue-component-type-helpers'
import MyGenericModal from './MyGenericModal.vue'

const modalRef = useTemplateRef<ComponentExposed<typeof MyGenericModal>>('modal')

<script setup>
import { ref, useTemplateRef, onMounted } from 'vue'

const items = ref(['Apple', 'Banana', 'Cherry'])
const itemRefs = useTemplateRef('item-el')

onMounted(() => {
  // itemRefs.value は HTMLLIElement[] 型
  console.log(itemRefs.value)
  itemRefs.value.forEach(el => {
    console.log(el.textContent)
  })
})
</script>

<template>
  <ul>
    <li v-for="item in items" :key="item" ref="item-el">
      {{ item }}
    </li>
  </ul>
</template>

<script setup>
import { ref, useTemplateRef, watchEffect } from 'vue'

const isVisible = ref(false)
const panelRef = useTemplateRef('panel')

watchEffect(() => {
  if (panelRef.value) {
    // パネルがDOMにマウントされた時点で実行される
    panelRef.value.scrollIntoView({ behavior: 'smooth' })
  }
})
</script>

<template>
  <button @click="isVisible = !isVisible">切り替え</button>
  <div v-if="isVisible" ref="panel">
    条件付きコンテンツ
  </div>
</template>

// composables/useAutoFocus.ts
import { useTemplateRef, onMounted } from 'vue'

export function useAutoFocus(refKey: string) {
  const el = useTemplateRef<HTMLElement>(refKey)

  onMounted(() => {
    el.value?.focus()
  })

  return { el }
}

<script setup>
import { useAutoFocus } from '@/composables/useAutoFocus'

useAutoFocus('search-input')
</script>

<template>
  <input ref="search-input" placeholder="検索..." />
</template>

// composables/useScrollObserver.ts
import { useTemplateRef, onMounted, onUnmounted, ref } from 'vue'

export function useScrollObserver(refKey: string) {
  const el = useTemplateRef<HTMLElement>(refKey)
  const scrollTop = ref(0)

  function handleScroll() {
    if (el.value) {
      scrollTop.value = el.value.scrollTop
    }
  }

  onMounted(() => {
    el.value?.addEventListener('scroll', handleScroll)
  })

  onUnmounted(() => {
    el.value?.removeEventListener('scroll', handleScroll)
  })

  return { scrollTop }
}

<!-- Parent.vue -->
<script setup>
import { useTemplateRef, onMounted } from 'vue'
import ChildForm from './ChildForm.vue'

const formRef = useTemplateRef('child-form')

onMounted(() => {
  // ChildFormが公開したメソッドを呼び出す
  formRef.value?.validate()
})
</script>

<template>
  <ChildForm ref="child-form" />
</template>

<!-- ChildForm.vue -->
<script setup>
import { ref } from 'vue'

const formData = ref({ name: '', email: '' })

function validate() {
  // バリデーションロジック
  return formData.value.name.length > 0
}

function reset() {
  formData.value = { name: '', email: '' }
}

// 親コンポーネントから呼び出せるメソッドを公開
defineExpose({ validate, reset })
</script>

const el = useTemplateRef('target')
// NG: setup時点ではまだDOMが存在しない
console.log(el.value) // null

onMounted(() => {
  // OK: マウント後なら値が入っている
  console.log(el.value)
})

// script側
const el = useTemplateRef('myInput')

<!-- template側: キー名が違う -->
<input ref="my-input" />  <!-- 'my-input' ≠ 'myInput' -->

# Vueのバージョン確認
npm list vue

npm install vue@latest

const inputRef = useTemplateRef<HTMLInputElement>('input')

onMounted(() => {
  // NG: null の可能性がある
  // inputRef.value.focus()

  // OK: オプショナルチェーン
  inputRef.value?.focus()

  // OK: nullガード
  if (inputRef.value) {
    inputRef.value.focus()
  }
})

<template>
  <input :ref="(el) => { /* el を変数に保存 */ }" />
</template>

# Nuxtが使用するVueバージョンの確認
npx nuxi info

npm install vue@^3.5.0

- import { ref, onMounted } from 'vue'
+ import { useTemplateRef, onMounted } from 'vue'

- const input = ref(null)
+ const inputRef = useTemplateRef('input')