Kurs Vue.js · Moduł 2: Składnia szablonów
Template Refs
W tej lekcji5
Czasem potrzebujesz bezpośredniego dostępu do elementu DOM - jak inżynier, który musi sprawdzić fizyczny sensor.
Szablony opisują, jak panel ma wyglądać, a Vue sam dba o elementy strony. Są jednak zadania, których deklaratywnie nie zapiszesz: ustawić kursor w polu komendy zaraz po otwarciu panelu, zmierzyć kontener albo przekazać element <canvas> zewnętrznej bibliotece wykresów. Wtedy potrzebujesz uchwytu do prawdziwego elementu - i to dają template refs. W drugiej części lekcji poznasz też kilka dyrektyw specjalnych do zadań nietypowych.
Podstawowe Template Refs
Specjalny atrybut ref oznacza element w szablonie. W skrypcie deklarujesz ref o tej samej nazwie z wartością null, a po zamontowaniu komponentu Vue wkłada do niego element. Moment zamontowania łapie funkcja onMounted - hak cyklu życia, który Vue wywołuje, gdy komponent trafił już na stronę; cykl życia omówimy w module 6.
<template>
<div class="input-panel" style="background: #0a0e27; padding: 1rem;">
<input ref="inputRef" type="text" placeholder="Kod modułu"
style="background: #0a0e27; border: 1px solid #00b4d8; color: #00ff88; padding: 0.5rem;">
<button @click="focusInput" class="btn-focus">Ustaw fokus</button>
</div>
</template>
<script setup>
import { ref, onMounted } from 'vue'
// Nazwa musi odpowiadać atrybutowi ref w template
const inputRef = ref(null)
function focusInput() {
inputRef.value?.focus()
}
onMounted(() => {
// Element jest dostępny po zamontowaniu
inputRef.value?.focus()
})
</script>Kolejność jest zawsze taka sama: deklaracja ref(null), atrybut ref="inputRef" na elemencie, zamontowanie i dopiero wtedy użycie. Przed montażem, a także po usunięciu elementu przez v-if, ref zawiera null, dlatego ?. chroni przed błędem. To ta sama funkcja ref() co przy danych - kontener trzyma tu po prostu element zamiast liczby.
Od Vue 3.5 zalecany jest pomocnik useTemplateRef. Jego argument musi odpowiadać wartości atrybutu ref, a zmienna może nazywać się dowolnie:
<script setup>
import { useTemplateRef, onMounted } from 'vue'
const commandInput = useTemplateRef('command-input')
onMounted(() => {
commandInput.value?.focus()
})
</script>
<template>
<input ref="command-input" placeholder="Kod modułu">
</template>Działa identycznie, a w TypeScripcie typ elementu zostanie wywnioskowany sam. Starszy zapis nadal działa i spotkasz go w istniejącym kodzie oraz w zadaniach, ale w nowych projektach polecam useTemplateRef.
Refs w v-for
Gdy ref stoi na elemencie z v-for, po zamontowaniu dostajesz tablicę elementów, a nie pojedynczy element:
<template>
<div class="modules-list">
<ul style="list-style: none; background: #0a0e27;">
<li v-for="module in modules" :key="module.id" ref="itemRefs"
style="color: #00b4d8; padding: 0.5rem; border-left: 2px solid #00ff88;">
{{ module.name }}
</li>
</ul>
</div>
</template>
<script setup>
import { ref, onMounted } from 'vue'
const modules = ref([
{ id: 1, name: 'Oxygen Generator' },
{ id: 2, name: 'Water Recycler' }
])
const itemRefs = ref([])
onMounted(() => {
console.log(itemRefs.value) // Tablica elementów LI
})
</script>Konsola pokaże dwa elementy li. Dokumentacja zastrzega jednak, że kolejność tej tablicy nie musi odpowiadać kolejności danych, więc nie zakładaj, że element o indeksie 0 to pierwszy moduł.
Function Refs
Zamiast nazwy możesz podać funkcję, używając dynamicznego wiązania :ref. Vue wywoła ją z elementem przy każdej aktualizacji komponentu, a przy odmontowaniu z null:
<template>
<input :ref="setInputRef" type="text"
style="background: #0a0e27; border: 1px solid #00ff88; color: #00b4d8;">
</template>
<script setup>
import { ref } from 'vue'
const dynamicRef = ref(null)
function setInputRef(el) {
dynamicRef.value = el
console.log('Element ustawiony:', el)
}
</script>Sam decydujesz, gdzie zapisać element, na przykład w mapie według identyfikatora. Pamiętaj tylko o przypadku null.
Refs na Komponentach
Atrybut ref na komponencie daje dostęp do jego instancji. SensorPanel.vue to osobny plik komponentu, importowany jak zwykły moduł - komponentami zajmiemy się w module 6. Rodzic wywołuje metodę dziecka po zamontowaniu:
<template>
<SensorPanel ref="sensorRef" />
</template>
<script setup>
import { ref, onMounted } from 'vue'
import SensorPanel from './SensorPanel.vue'
const sensorRef = ref(null)
onMounted(() => {
// Dostęp do metod i właściwości komponentu
sensorRef.value?.refreshData()
})
</script>Komponenty z <script setup> są domyślnie prywatne: rodzic nie zobaczy niczego, dopóki dziecko samo nie udostępni tego makrem defineExpose, którego nie trzeba importować:
<!-- SensorPanel.vue - musi eksponować metody -->
<script setup>
import { ref } from 'vue'
const sensorData = ref({})
function refreshData() {
console.log('Odświeżanie danych z sensorów!')
}
// defineExpose - udostępnij rodzicowi
defineExpose({
refreshData,
sensorData
})
</script>defineExpose trzeba wywołać przed pierwszym await. Takie połączenie wiąże komponenty ciasno, więc używaj go oszczędnie - zwykle lepsze są propsy i zdarzenia.
Dyrektywy Specjalne
Kilka wbudowanych dyrektyw rozwiązuje zadania rzadsze, ale warto je znać. v-text ustawia textContent elementu, więc zastępuje całą jego zawartość, a wąsy podmieniają tylko swój fragment:
<template>
<p v-text="statusMessage"></p>
<p>Status: {{ statusMessage }}</p>
</template>Oba akapity pokażą komunikat, ale tylko drugi zachowa napis Status. v-once renderuje element raz i potem traktuje go jak statyczny. v-memo (Vue 3.2+) zapamiętuje fragment szablonu i aktualizuje go tylko wtedy, gdy zmieni się któraś wartość z tablicy:
<template>
<p v-once>Kod misji: {{ missionCode }}</p>
<div v-for="module in modules" :key="module.id" v-memo="[module.id === selectedId]">
{{ module.name }} - wybrany: {{ module.id === selectedId }}
</div>
</template>Późniejsza zmiana missionCode nie odświeży akapitu. Po zmianie selectedId przerysują się tylko dwa moduły, którym zmieniła się flaga. v-memo="[]" działa jak v-once, a źle dobrane zależności zostawią na ekranie nieaktualne dane, dlatego to narzędzie do bardzo długich list. Dwie ostatnie dyrektywy dotyczą kompilacji:
<template>
<code v-pre>{{ to nie zostanie skompilowane }}</code>
</template>
<style>
[v-cloak] {
display: none;
}
</style>v-pre pomija kompilację elementu i jego dzieci, więc wąsy zobaczysz dosłownie. v-cloak jest potrzebny tylko bez kroku budowania, gdy Vue kompiluje szablon zapisany wprost w HTML: razem z tą regułą CSS ukrywa surowe {{ }} do chwili zamontowania aplikacji. W projekcie Vite nie jest potrzebny.
Traktuj template refs jako ostateczność - najpierw sprawdź, czy wystarczy szablon. W projekcie modułu połączysz wszystkie te narzędzia w jeden panel hologramów.
Zapamiętaj: template ref to klucz serwisowy do jednego urządzenia - sięgasz po niego dopiero po montażu i tylko wtedy, gdy panel sterowania nie wystarcza.
Kod do tej lekcji: App.vue
<script setup>
import { ref, onMounted } from 'vue'
// Template refs (uchwyty do elementów)
const inputRef = ref(null)
const containerRef = ref(null)
const canvasRef = ref(null)
// Dane
const focusCount = ref(0)
const containerInfo = ref({})
const canvasDrawn = ref(false)
// Dane reaktywne do pokazu v-once
const staticData = ref({
launchDate: '2087-03-15',
missionCode: 'NOVA-MARS-001',
initialCrew: 6
})
const dynamicCounter = ref(0)
// Funkcje
function focusInput() {
if (inputRef.value) {
inputRef.value.focus()
focusCount.value++
}
}
function getContainerDimensions() {
if (containerRef.value) {
const rect = containerRef.value.getBoundingClientRect()
containerInfo.value = {
width: Math.round(rect.width),
height: Math.round(rect.height),
top: Math.round(rect.top),
left: Math.round(rect.left)
}
}
}
function drawOnCanvas() {
if (canvasRef.value) {
const ctx = canvasRef.value.getContext('2d')
const canvas = canvasRef.value
// Wyczyść canvas
ctx.fillStyle = '#0a0e27'
ctx.fillRect(0, 0, canvas.width, canvas.height)
// Narysuj Marsa
ctx.beginPath()
ctx.arc(200, 150, 80, 0, Math.PI * 2)
ctx.fillStyle = '#ff6600'
ctx.fill()
// Narysuj kratery
ctx.beginPath()
ctx.arc(180, 130, 20, 0, Math.PI * 2)
ctx.fillStyle = '#cc5500'
ctx.fill()
ctx.beginPath()
ctx.arc(220, 160, 15, 0, Math.PI * 2)
ctx.fill()
// Narysuj bazę NOVA LAB
ctx.fillStyle = '#00ff88'
ctx.fillRect(150, 220, 100, 40)
// Narysuj kopułę
ctx.beginPath()
ctx.arc(200, 220, 50, Math.PI, 0)
ctx.strokeStyle = '#00b4d8'
ctx.lineWidth = 3
ctx.stroke()
// Dodaj napis
ctx.fillStyle = '#00ff88'
ctx.font = 'bold 16px Courier'
ctx.fillText('NOVA LAB', 160, 245)
canvasDrawn.value = true
}
}
function incrementCounter() {
dynamicCounter.value++
}
onMounted(() => {
getContainerDimensions()
// Automatyczny fokus po zamontowaniu
setTimeout(() => {
focusInput()
}, 500)
})
</script>
<template>
<div class="advanced-lab">
<h1>Zaawansowane Dyrektywy - NOVA LAB</h1>
<!-- Sekcja template refs -->
<section class="lab-section">
<h2>Template Refs - Dostęp do elementów DOM</h2>
<!-- Przykład: ref na polu input -->
<div class="demo-card">
<h3>ref na input - Fokus ustawiany z kodu</h3>
<div class="ref-demo">
<input
ref="inputRef"
type="text"
placeholder="Fokus w tym polu ustawisz z kodu..."
class="input-field"
>
<button @click="focusInput" class="btn btn-primary">
Ustaw fokus
</button>
</div>
<p class="info-text">Liczba wywołań focus: {{ focusCount }}</p>
<code class="code-hint">ref="inputRef" → inputRef.value.focus()</code>
</div>
<!-- Przykład: ref na kontenerze -->
<div class="demo-card">
<h3>ref na kontener - Odczyt wymiarów</h3>
<div ref="containerRef" class="ref-container">
<p>Ten kontener ma ref="containerRef"</p>
<p>Kliknij przycisk aby odczytać jego wymiary</p>
</div>
<button @click="getContainerDimensions" class="btn btn-success">
Odczytaj wymiary
</button>
<div v-if="containerInfo.width" class="dimensions-info">
<p>Szerokość: {{ containerInfo.width }}px</p>
<p>Wysokość: {{ containerInfo.height }}px</p>
<p>Pozycja: ({{ containerInfo.left }}px, {{ containerInfo.top }}px)</p>
</div>
</div>
<!-- Przykład: ref na canvasie -->
<div class="demo-card">
<h3>ref na canvas - Rysowanie</h3>
<canvas
ref="canvasRef"
width="400"
height="300"
class="canvas-field"
></canvas>
<button @click="drawOnCanvas" class="btn btn-warning">
{{ canvasDrawn ? 'Przerysuj' : 'Narysuj' }} bazę na Marsie
</button>
<code class="code-hint">ref="canvasRef" → canvasRef.value.getContext('2d')</code>
</div>
</section>
<!-- Sekcja v-once -->
<section class="lab-section">
<h2>v-once - Jednorazowe renderowanie</h2>
<div class="demo-card">
<h3>Statyczne dane (v-once)</h3>
<div v-once class="static-content">
<p><strong>Data startu:</strong> {{ staticData.launchDate }}</p>
<p><strong>Kod misji:</strong> {{ staticData.missionCode }}</p>
<p><strong>Załoga startowa:</strong> {{ staticData.initialCrew }}</p>
<p class="info-text">Te dane są renderowane tylko raz i nie będą się aktualizować</p>
</div>
</div>
<div class="demo-card">
<h3>Porównanie: v-once i zwykłe wiązanie</h3>
<div class="comparison-grid">
<div class="comparison-item">
<h4>Z v-once (nie aktualizuje się)</h4>
<div v-once class="counter-display static">
{{ dynamicCounter }}
</div>
</div>
<div class="comparison-item">
<h4>Bez v-once (aktualizuje się)</h4>
<div class="counter-display dynamic">
{{ dynamicCounter }}
</div>
</div>
</div>
<button @click="incrementCounter" class="btn btn-primary">
Zwiększ licznik ({{ dynamicCounter }})
</button>
<p class="info-text">
Lewy licznik zostaje przy wartości początkowej, a prawy się aktualizuje
</p>
</div>
</section>
<!-- Sekcja v-cloak -->
<section class="lab-section">
<h2>v-cloak - Ukrywanie niezrenderowanych szablonów</h2>
<div class="demo-card">
<h3>v-cloak - Zapobiega pokazywaniu <code v-pre>{{ }}</code></h3>
<div v-cloak class="cloak-demo">
<p>Ta sekcja używa v-cloak</p>
<p>Przy powolnym ładowaniu użytkownik nie zobaczy surowych wąsów <code v-pre>{{ }}</code></p>
<p>Dane: {{ staticData.missionCode }}</p>
</div>
<code class="code-hint">
v-cloak + CSS: [v-cloak] { display: none; }
</code>
</div>
</section>
<!-- Ramka z podsumowaniem -->
<div class="info-box">
<h3>Zaawansowane dyrektywy Vue</h3>
<div class="info-grid">
<div>
<h4>Template Refs:</h4>
<ul>
<li><strong>ref="name"</strong> - Tworzy referencję do elementu</li>
<li><strong>const name = ref(null)</strong> - Deklaracja w script setup</li>
<li><strong>name.value</strong> - Dostęp do elementu DOM</li>
<li>Dostępne po onMounted()</li>
</ul>
</div>
<div>
<h4>v-once:</h4>
<ul>
<li>Renderuje element/komponent tylko raz</li>
<li>Pomija wszystkie kolejne aktualizacje</li>
<li>Optymalizacja dla statycznych treści</li>
<li>Przydatne dla dużych danych, które się nie zmieniają</li>
</ul>
</div>
<div>
<h4>v-cloak:</h4>
<ul>
<li>Ukrywa niezrenderowane szablony</li>
<li>Wymaga CSS: [v-cloak] { display: none; }</li>
<li>Zapobiega „błyskaniu” <code v-pre>{{ }}</code></li>
<li>Automatycznie usuwane po kompilacji</li>
</ul>
</div>
<div>
<h4>Zastosowania ref:</h4>
<ul>
<li>Ustawianie fokusu z kodu</li>
<li>Integracja z bibliotekami DOM</li>
<li>Rysowanie na canvasie i praca z SVG</li>
<li>Przewijanie do elementu</li>
<li>Odczyt wymiarów elementu</li>
</ul>
</div>
</div>
</div>
</div>
</template>
<style scoped>
/* v-cloak CSS */
[v-cloak] {
display: none;
}
.advanced-lab {
background: linear-gradient(135deg, #0a0e27 0%, #1a1e3f 100%);
min-height: 100vh;
padding: 2rem;
color: #ffffff;
font-family: 'Courier New', monospace;
}
h1 {
text-align: center;
color: #00ff88;
text-shadow: 0 0 20px rgba(0, 255, 136, 0.5);
margin-bottom: 3rem;
}
h2 {
color: #00b4d8;
margin-bottom: 1.5rem;
border-bottom: 2px solid #00b4d8;
padding-bottom: 0.5rem;
}
h3 {
color: #00ff88;
font-size: 1.1rem;
margin-bottom: 1rem;
}
h4 {
color: #00b4d8;
font-size: 1rem;
margin-bottom: 0.75rem;
}
.lab-section {
background: rgba(0, 255, 136, 0.05);
border: 2px solid #00ff88;
border-radius: 10px;
padding: 2rem;
margin-bottom: 2rem;
}
.demo-card {
background: rgba(0, 180, 216, 0.1);
border: 2px solid #00b4d8;
border-radius: 8px;
padding: 1.5rem;
margin-bottom: 1.5rem;
}
.ref-demo {
display: flex;
gap: 1rem;
margin-bottom: 1rem;
flex-wrap: wrap;
}
.input-field {
background: rgba(0, 0, 0, 0.3);
border: 2px solid #00b4d8;
border-radius: 5px;
padding: 0.75rem;
color: #ffffff;
font-family: 'Courier New', monospace;
font-size: 1rem;
flex: 1;
min-width: 250px;
}
.input-field:focus {
outline: none;
border-color: #00ff88;
box-shadow: 0 0 15px rgba(0, 255, 136, 0.5);
animation: focusPulse 0.5s ease;
}
@keyframes focusPulse {
0%, 100% { transform: scale(1); }
50% { transform: scale(1.02); }
}
.ref-container {
background: rgba(0, 255, 136, 0.1);
border: 2px dashed #00ff88;
border-radius: 8px;
padding: 2rem;
text-align: center;
margin: 1rem 0;
}
.dimensions-info {
background: rgba(0, 0, 0, 0.3);
border-left: 4px solid #00ff88;
border-radius: 5px;
padding: 1rem;
margin-top: 1rem;
}
.dimensions-info p {
margin: 0.5rem 0;
color: #00ff88;
}
.canvas-field {
display: block;
width: 100%;
max-width: 400px;
background: #0a0e27;
border: 2px solid #00b4d8;
border-radius: 8px;
margin: 1rem 0;
}
.static-content {
background: rgba(0, 255, 136, 0.1);
border: 2px solid #00ff88;
border-radius: 8px;
padding: 1.5rem;
}
.static-content p {
margin: 0.75rem 0;
color: #ffffff;
}
.static-content strong {
color: #00b4d8;
}
.comparison-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
gap: 1.5rem;
margin: 1.5rem 0;
}
.comparison-item {
background: rgba(0, 0, 0, 0.3);
border-radius: 8px;
padding: 1.5rem;
text-align: center;
}
.counter-display {
font-size: 3rem;
font-weight: bold;
padding: 2rem;
border-radius: 8px;
margin: 1rem 0;
}
.counter-display.static {
background: rgba(255, 180, 0, 0.2);
border: 2px solid #ffb400;
color: #ffb400;
}
.counter-display.dynamic {
background: rgba(0, 255, 136, 0.2);
border: 2px solid #00ff88;
color: #00ff88;
animation: pulse 2s infinite;
}
.cloak-demo {
background: rgba(0, 180, 216, 0.1);
border: 2px solid #00b4d8;
border-radius: 8px;
padding: 1.5rem;
}
.btn {
padding: 0.75rem 1.5rem;
border: none;
border-radius: 5px;
font-size: 1rem;
font-weight: bold;
cursor: pointer;
transition: all 0.3s ease;
font-family: 'Courier New', monospace;
margin: 0.5rem;
}
.btn-primary {
background: #00ff88;
color: #0a0e27;
}
.btn-success {
background: #00b4d8;
color: #ffffff;
}
.btn-warning {
background: #ffb400;
color: #0a0e27;
}
.btn:hover {
transform: scale(1.05);
box-shadow: 0 5px 15px rgba(0, 255, 136, 0.4);
}
.code-hint {
display: block;
background: rgba(0, 0, 0, 0.5);
border-left: 4px solid #00ff88;
padding: 0.75rem;
border-radius: 5px;
color: #00ff88;
font-family: 'Courier New', monospace;
font-size: 0.9rem;
margin-top: 1rem;
}
.info-text {
color: #00b4d8;
font-size: 0.9rem;
margin-top: 1rem;
}
.info-box {
background: rgba(0, 255, 136, 0.05);
border: 2px solid #00ff88;
border-radius: 10px;
padding: 2rem;
}
.info-box h3 {
margin-top: 0;
margin-bottom: 1.5rem;
}
.info-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
gap: 2rem;
}
.info-box ul {
list-style: none;
padding: 0;
}
.info-box li {
padding: 0.5rem 0;
color: #ffffff;
border-left: 3px solid #00b4d8;
padding-left: 1rem;
margin: 0.5rem 0;
}
.info-box strong {
color: #00ff88;
}
@keyframes pulse {
0%, 100% { opacity: 1; }
50% { opacity: 0.7; }
}
</style>Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Jaki mechanizm Vue daje bezpośredni dostęp do elementu DOM z szablonu komponentu?
2. Jaka jest różnica między {{ }} a v-text?
3. Co robi v-pre?
4. Co robi dyrektywa v-once w Vue.js?
5. missionCode zmienia się z 'A-1' na 'B-2'. Co pokaże wtedy <p v-once>Kod: {{ missionCode }}</p>?
6. Po co używać v-cloak?
7. Dlaczego trzeba ostrożnie używać v-html?
8. Która dyrektywa Vue służy do optymalizacji wydajności przez memoizację?
9. Który modyfikator klawisza w Vue.js służy do wykrywania klawisza Escape?
10. Co robić gdy template staje się zbyt złożony?
11. Co robi v-memo w Vue 3?
12. Który zapis wywoła onSelf tylko wtedy, gdy kliknięto sam element, a nie jego dziecko?
13. Która praktyka jest zalecana w Vue templates?
Zadania praktyczne w grze
- Edytor kodu
Użyj template ref, aby po zamontowaniu komponentu automatycznie ustawić fokus w polu input.
- Układanie w pionie
Uporządkuj kroki użycia template ref:
- Układanie w pionie
Ułóż fragmenty kodu template ref w kolejności, w jakiej zaczynają działać:
- Klikanie w kolejności
Ułóż kod template ref z auto-focus:
- Układanie w pionie
Ułóż sposoby wiązania stylów od prostego do zaawansowanego:
- Układanie w pionie
Uporządkuj etapy działania v-if w Vue:
- Układanie w poziomie
Ułóż poprawną składnię v-for z dostępem do indeksu:
Zadania po tej lekcji
- PytanieDostęp do DOM przez template ref
- PytanieDyrektywa v-text
- Zadanie z kodemPraktyka: Template refs
- Ułóż w kolejnościCykl życia template ref
- Ułóż w kolejnościSkładnia template ref
- PytanieDyrektywa v-pre
- PytanieDyrektywa v-once
- Kliknij w kolejnościSkładnia template ref z onMounted
- Pytaniev-once po zmianie danych
- PytanieDyrektywa v-cloak
- Ułóż w kolejnościSposoby wiązania stylów inline
- PytanieBezpieczeństwo v-html
- PytanieDyrektywa do memoizacji
- PytanieModyfikator klawisza Escape
- Ułóż w kolejnościProces renderowania warunkowego
- PytanieZłożoność template
- Pytaniev-memo w Vue 3
- Ułóż w kolejnościSkładnia v-for z indeksem
- PytanieModyfikator .self
- PytanieNajlepsze praktyki template