ارجاع از طریق تمپلیت - Template Refs ​

درحالیکه مدل رندر اعلامی Vue بیشتر عملیات های مرتبط با DOM را برای شما جدا می‌کند، در مواردی پیش می‌آید که نیاز داریم به المنت های DOM دسترسی مستقیم داشته باشیم. برای رسیدن به این هدف، می‌توانیم از ویژگی به خصوص ref بهره ببریم:

<input ref="input">

ویژگی ref همانند ویژگی key که در بخش v-for مورد بحث قرار گرفت، یک ویژگی به خصوص است. این ویژگی به ما اجازه می‌دهد ارجاعی مستقیم، به المنت مشخصی از DOM یا کامپوننت فرزند بعد از اینکه در DOM قرار گرفت (mount شد) بدست بیاوریم. به عنوان مثال، این ویژگی ممکن است هنگامی مفید باشد که شما بخواهید توسط کد عمل فوکس را بر روی یک input درون کامپوننتی که مانت شده انجام دهید یا یک کتابخانه شخص ثالث را بر روی المنتی مقدار دهی اولیه کنید.

دسترسی به ارجاع ​

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

// در تمپلیت مطابقت داشته باشد ref آرگومان اول باید با مقدار  
const input = useTemplateRef('my-input')

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

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

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

// برای نگهداری از ارجاع المنت تعریف کن ref یک
// باید با مقدار ارجاع تمپلیت یکسان باشد ref نام
const input = ref(null)

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

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

export default {
  setup() {
    const input = ref(null)
    // ...
    return {
      input
    }
  }
}

<script>
export default {
  mounted() {
    this.$refs.input.focus()
  }
}
</script>

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

توجه داشته باشید که شما فقط بعد از اینکه کامپوننت mount شد می‌توانید به ref دسترسی داشته باشید. اگر شما سعی کنید که به ‎$refs.inputinput درون یک عبارت تمپلیت دسترسی داشته باشید، در اولین رندر مقدار undefinednull را خواهد داشت. این به این دلیل است که المنت تا بعد از اولین رندر موجود نمی‌باشد.

watchEffect(() => {
  if (input.value) {
    input.value.focus()
  } else {
    // (v-if برای مثال توسط) قرار دارد unmounted نشده یا در حالت mount المنت هنوز
  }
})

استفاده از ارجاع‌ها درون v-for ​

به نسخه v3.5 یا بالاتر نیاز دارد

<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>

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

const list = ref([
  /* ... */
])

const itemRefs = ref([])

onMounted(() => console.log(itemRefs.value))
</script>

<template>
  <ul>
    <li v-for="item in list" ref="itemRefs">
      {{ item }}
    </li>
  </ul>
</template>

<script>
export default {
  data() {
    return {
      list: [
        /* ... */
      ]
    }
  },
  mounted() {
    console.log(this.$refs.items)
  }
}
</script>

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

باید توجه داشت که آرایه ساخته شده از ارجاع‌ها تضمین نمی‌کند که به همان ترتیب آرایه مبدا باشد.

ارجاع با استفاده از تابع ​

ویژگی ref همچنین می‌تواند به جای استفاده از یک کلید استرینگ به یک تابع وصل شود، که در هر بروزرسانی کامپوننت صدا زده می‌شود و به شما انعطاف کامل درباره اینکه کجا المنت را نگه دارید می‌دهد. تابع ارجاع دهنده، المنت را به عنوان اولین آرگومان دریافت می‌کند:

<input :ref="(el) => { /* اختصاص دهید ref را به یک پراپرتی یا el */ }">

توجه داشته باشید ما داریم از یک اتصال ‎:ref پویا استفاده می‌کنیم تا بتوانیم یک تابع را به جای یک رشته برای نام ارجاع ارسال کنیم. هنگامی که المنت unmounted می‌شود، آرگومان null خواهد بود. البته که شما می‌توانید از یک متد به جای تابع خطی استفاده کنید.

استفاده از ارجاع در کامپوننت ​

این قسمت دانش Components را فرض می‌کند. راحت از آن صرف نظر کنید و بعداً برگردید.

ref همچنین می‌تواند بر روی کامپوننت فرزند استفاده شود. در این مورد ارجاع، نمونه‌ای از کامپوننت فرزند خواهد بود:

<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>

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

const child = ref(null)

onMounted(() => {
  // را نگه می‌دارد <Child /> نمونه‌ای از child.value 
})
</script>

<template>
  <Child ref="child" />
</template>

<script>
import Child from './Child.vue'

export default {
  components: {
    Child
  },
  mounted() {
    // را نگه می‌دارد <Child /> نمونه‌ای از this.$refs.child 
  }
}
</script>

<template>
  <Child ref="child" />
</template>

اگر کامپوننت فرزند از Options API استفاده می‌کند یا از <script setup> استفاده نمی‌کند، نمونه دریافت شده از ارجاع با کلمه کلیدی this کامپوننت فرزند یکسان خواهد بود، این به این معنی است که کامپوننت والد به هر پراپرتی و متد کامپوننت فرزند دسترسی خواهد داشت. این کار را آسان می‌کند که جزئیات پیاده سازی کاملا محکمی بین کامپوننت والد و فرزند ایجاد شود، بنابراین می‌توان از ارجاع کامپوننت‌ها در صورت لزوم استفاده کرد - در بیشتر موارد، ابتدا باید سعی کنید که تعاملات بین والد و فرزند را با استفاده از رابط های props و emit به کار ببرید. نمونه ارجاع با کلمه کلیدی this کامپوننت فرزند یکسان خواهد بود، این به این معنی است که کامپوننت والد به هر پراپرتی و متد کامپوننت فرزند دسترسی خواهد داشت. این کار را آسان می‌کند که جزئیات پیاده سازی کاملا محکمی بین کامپوننت والد و فرزند ایجاد شود، بنابراین باید از ارجاع کامپوننت‌ها در صورت لزوم استفاده کرد - در بیشتر موارد، ابتدا باید سعی کنید که تعاملات بین والد و فرزند را با استفاده از رابط های props و emit به کار ببرید.

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

const a = 1
const b = ref(2)

// نیاز به ایمپورت شدن ندارند defineExpose ماکروهای کامپایلر، مانند 
defineExpose({
  a,
  b
})
</script>

export default {
  expose: ['publicData', 'publicMethod'],
  data() {
    return {
      publicData: 'foo',
      privateData: 'bar'
    }
  },
  methods: {
    publicMethod() {
      /* ... */
    },
    privateMethod() {
      /* ... */
    }
  }
}