useTemplateRef() الحصول على مرجع القالب (الصيغة الموصى بها في 3.5+)
آخر تحديث: 2026-10-22
useTemplateRef() الحصول على مرجع القالب (الصيغة الموصى بها في 3.5+)
تحصل useTemplateRef() على مرجع القالب الخاصية ref التي تحمل الاسم نفسه عبر مفتاح نصي، متجنّبةً الشيفرة النمطية لـ «التصريح بمتغير يحمل الاسم نفسه».
| المجموعة | القوالب والمساعدات |
|---|---|
| النوع | API |
| النطاق | داخل المكوّن |
| إصدار Vue | 3.5+ |
| دعم SSR | مدعوم |
📝 الصيغة
const inputEl = useTemplateRef('my-input')
// القالب: <input ref="my-input">⚙️ الوسائط
| key | نص مطابق لقيمة خاصية ref في القالب |
|---|
القيمة المُرجعة：ref للقراءة فقط، قيمتها null قبل التحميل
▶ مثال
عدّل الشيفرة أدناه وشاهد النتيجة مباشرة:
المخرجات：
Clicking focuses the input.💡 نقاط مهمة
💡 نصيحة الصيغة الموصى بها في 3.5+؛ ولا تزال الصيغة القديمة (متغير ref بالاسم نفسه + الجمع التلقائي) قابلة للاستخدام كاملة.
⚠️ تحذير قيمتها null قبل التحميل: تحقّق من عدم الفراغ قبل الوصول، أو استخدمها بعد onMounted.
ℹ️ ملاحظة داخل v-for تحصل على مصفوفة من المكوّنات/العناصر.
🏷️ القوالب والمساعدات ذات صلة
💡 حالات ذات صلة
المزيد من الحالات قريباً.
📚 دروس ذات صلة
❓ الأسئلة الشائعة
س ما الفرق بينها وبين التصريح المباشر بمتغير ref يحمل الاسم نفسه؟
ج الوظيفة نفسها؛ إذ تُغني useTemplateRef عن قيد التسمية وكونها أوضح دلالةً تناسب سيناريوهات المراجع المتعددة.
س هل يمكنها الحصول على نسخة مكوّن ابن؟
ج نعم، فهي تشير إلى نسخة المكوّن؛ وللاتصال بأساليبه يلزم تعرية الأبناء عبر defineExpose.
س ماذا عن الإصدارات الأقدم من 3.5؟
ج استخدم الصيغة الكلاسيكية: const txt = ref(null) مع ref="txt" في القالب (تُجمع تلقائيًا وقت التجميع).
