Kurs Vue.js · Moduł 9: Composables i VueUse
VueUse - Biblioteka Composables
W tej lekcji8
VueUse to kolekcja 200+ gotowych composables - jak biblioteka standardowych protokołów badawczych NOVA LAB! Po co taka biblioteka? W każdym projekcie wracają te same zadania: zapamiętać ustawienia w localStorage, śledzić rozmiar okna, pozycję myszy albo tryb ciemny, opóźnić wyszukiwanie do chwili, gdy użytkownik przestanie pisać. Każde z nich wymaga nasłuchu zdarzeń przeglądarki i sprzątania po sobie. Możesz pisać to od zera w każdym projekcie albo sięgnąć po sprawdzone, przetestowane funkcje z pakietu @vueuse/core. Do paczki aplikacji trafiają przy tym tylko te, które faktycznie importujesz.
Instalacja VueUse
Bibliotekę instalujesz jak każdy pakiet npm. Aktualna wersja VueUse wymaga Vue 3.5 lub nowszego:
npm install @vueuse/corePo instalacji importujesz pojedyncze funkcje z '@vueuse/core', dokładnie tak jak ref czy computed z 'vue'. Żadnej rejestracji pluginu nie potrzeba.
useLocalStorage
Pierwszy protokół zapisuje ustawienia laboratorium tak, by przetrwały odświeżenie strony. useLocalStorage przyjmuje klucz i wartość domyślną, a zwraca ref zsynchronizowany z localStorage przeglądarki:
<script setup>
import { useLocalStorage } from '@vueuse/core'
// Automatycznie synchronizuje z localStorage
const labSettings = useLocalStorage('lab-settings', {
mode: 'exploration',
sensorsPerView: 12,
sortBy: 'temperature'
})
// Zmiana automatycznie zapisuje w localStorage
labSettings.value.mode = 'research'
</script>
<template>
<div>
<p>Tryb: {{ labSettings.mode }}</p>
<button @click="labSettings.mode = 'maintenance'">
Zmień tryb
</button>
</div>
</template>Wartość domyślna trafia do użytku tylko wtedy, gdy pod kluczem lab-settings nic jeszcze nie ma. Obiekty są zapisywane jako JSON, a zmiana pojedynczego pola też trafia do pamięci, bo VueUse obserwuje obiekt w głąb.
useMouseInElement
Ten composable śledzi mysz względem konkretnego elementu. Zwraca między innymi elementX i elementY, czyli pozycję liczoną od lewego górnego rogu elementu, oraz isOutside, które mówi, czy kursor jest poza nim. Zwykłe x i y to współrzędne na całej stronie:
<script setup>
import { ref } from 'vue'
import { useMouseInElement } from '@vueuse/core'
const sensorPanel = ref(null)
const { elementX, elementY, isOutside } = useMouseInElement(sensorPanel)
</script>
<template>
<div ref="sensorPanel" class="sensor-panel">
<img src="/sensor-display.jpg" />
<div v-if="!isOutside" class="tooltip" :style="{ left: elementX + 'px', top: elementY + 'px' }">
Pozycja: {{ elementX }}, {{ elementY }}
</div>
</div>
</template>Ref sensorPanel łączy się z elementem przez atrybut ref; od Vue 3.5 możesz też użyć useTemplateRef('sensorPanel'). Żeby tooltip wisiał przy kursorze, panel potrzebuje w CSS position: relative, a tooltip position: absolute.
useIntersectionObserver
Kolejny protokół sprawdza, czy element jest widoczny w oknie przeglądarki. To podstawa leniwego ładowania obrazów i animacji uruchamianych przy przewijaniu. Callback dostaje listę obserwowanych wpisów, a pole isIntersecting mówi, czy element wszedł w obszar widoku:
<script setup>
import { ref } from 'vue'
import { useIntersectionObserver } from '@vueuse/core'
const experimentPanel = ref(null)
const isVisible = ref(false)
useIntersectionObserver(
experimentPanel,
([{ isIntersecting }]) => {
isVisible.value = isIntersecting
}
)
</script>
<template>
<div ref="experimentPanel">
<Transition name="fade">
<img v-if="isVisible" src="/experiment-data.jpg" />
</Transition>
</div>
</template>Obraz pobiera się dopiero wtedy, gdy panel pojawi się na ekranie. VueUse sam odłączy obserwatora przy odmontowaniu komponentu, więc nie musisz pisać własnego sprzątania.
useWindowSize
useWindowSize zwraca reaktywne width i height okna, które aktualizują się przy każdej zmianie jego rozmiaru. Z nich łatwo wyliczyć przez computed progi widoku:
<script setup>
import { useWindowSize } from '@vueuse/core'
import { computed } from 'vue'
const { width, height } = useWindowSize()
const isMobile = computed(() => width.value < 768)
const isTablet = computed(() => width.value >= 768 && width.value < 1024)
const isDesktop = computed(() => width.value >= 1024)
</script>
<template>
<div>
<p v-if="isMobile">Widok mobilny</p>
<p v-else-if="isTablet">Widok tabletowy</p>
<p v-else>Widok desktopowy</p>
<p>Wymiary: {{ width }} x {{ height }}</p>
</div>
</template>Szablon przełącza komunikat bez żadnego ręcznego nasłuchu resize. Jeśli progów jest więcej, VueUse oferuje do tego wyspecjalizowane useBreakpoints.
useDark & useToggle
useDark zwraca ref z wartością logiczną trybu ciemnego. Domyślnie startuje od ustawienia systemu, dodaje klasę dark do elementu <html> i zapamiętuje wybór w localStorage. useToggle zamienia taki ref w funkcję przełączającą:
<script setup>
import { useDark, useToggle } from '@vueuse/core'
const isDark = useDark()
const toggleDark = useToggle(isDark)
</script>
<template>
<div :class="{ dark: isDark }">
<button @click="toggleDark()">
{{ isDark ? 'Jasny' : 'Ciemny' }} motyw
</button>
</div>
</template>
<style>
body {
transition: background 0.3s, color 0.3s;
}
.dark {
background: #1a1a1a;
color: #f5f5f5;
}
</style>Po kliknięciu klasa dark pojawi się na <html> i na divie z wiązaniem :class. Wiązanie nie jest konieczne, bo klasę na <html> dodaje sam useDark; zostawiamy je, żeby było widać, skąd bierze się styl.
refDebounced i refThrottled
Debounce czeka, aż wartość przestanie się zmieniać przez zadany czas, a throttle przepuszcza zmianę najwyżej raz na określony odstęp. W VueUse robią to refDebounced i refThrottled, które zwracają opóźnioną kopię refa. Starsze nazwy useDebounce i useThrottle nadal działają, ale są oznaczone jako przestarzałe:
<script setup>
import { ref } from 'vue'
import { refDebounced, refThrottled } from '@vueuse/core'
// Debounce - czeka aż użytkownik przestanie pisać
const searchQuery = ref('')
const debouncedQuery = refDebounced(searchQuery, 500)
// Throttle - maksymalnie raz na X ms
const scrollPosition = ref(0)
const throttledScroll = refThrottled(scrollPosition, 100)
</script>
<template>
<input v-model="searchQuery" placeholder="Szukaj..." />
<p>Wyszukiwanie: {{ debouncedQuery }}</p>
</template>Gdy wpiszesz "oxy", debouncedQuery zmieni się dopiero pół sekundy po ostatnim klawiszu, więc zapytanie do serwera poleci raz, a nie trzy razy. scrollPosition aktualizowałbyś w obsłudze przewijania. Do opóźniania wywołań funkcji VueUse ma jeszcze useDebounceFn i useThrottleFn.
Popularne Composables z VueUse
Na koniec ściągawka z funkcjami, po które sięgniesz najczęściej:
| Composable | Opis |
|---|---|
useLocalStorage | LocalStorage reaktywnie |
useFetch | Fetch z reaktywnością |
useIntersectionObserver | Wykrywanie widoczności |
useMouseInElement | Pozycja myszy w elemencie |
useWindowSize | Rozmiar okna |
useDark | Tryb ciemny |
refDebounced | Opóźniona reaktywność (debounce) |
useClipboard | Kopiowanie do schowka |
Moja rada: zanim napiszesz własny composable do obsługi przeglądarki, zajrzyj na vueuse.org. Jeśli funkcja już tam jest, dostajesz kod z testami i poprawnym sprzątaniem. W edytorze poniżej zobaczysz, jak taki composable wygląda od środka: useConnectionMonitor sam uruchamia timery w onMounted i sprząta je w onUnmounted - dokładnie tę pracę VueUse wykonuje za Ciebie.
Zapamiętaj: VueUse to magazyn gotowych protokołów stacji - zanim zbudujesz nowy przyrząd, sprawdź, czy nie leży już na półce.
Kod do tej lekcji: App.vue
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
// Composable z hookami cyklu życia: useConnectionMonitor
function useConnectionMonitor(serverUrl) {
const isConnected = ref(false)
const connectionTime = ref(null)
const disconnectionTime = ref(null)
const reconnectAttempts = ref(0)
const latency = ref(0)
const messages = ref([])
let intervalId = null
let connectionCheckId = null
function addMessage(type, text) {
messages.value.unshift({
id: Date.now(),
type,
text,
timestamp: new Date().toLocaleTimeString()
})
if (messages.value.length > 10) {
messages.value.pop()
}
}
function connect() {
isConnected.value = true
connectionTime.value = new Date()
reconnectAttempts.value = 0
addMessage('success', `Połączono: ${serverUrl}`)
// Symulacja pomiaru opóźnienia
intervalId = setInterval(() => {
latency.value = Math.floor(Math.random() * 100) + 20
}, 2000)
}
function disconnect() {
isConnected.value = false
disconnectionTime.value = new Date()
addMessage('warning', `Rozłączono: ${serverUrl}`)
if (intervalId) {
clearInterval(intervalId)
intervalId = null
}
}
function attemptReconnect() {
if (isConnected.value) return
reconnectAttempts.value++
addMessage('info', `Próba ponownego połączenia #${reconnectAttempts.value}`)
setTimeout(() => {
if (reconnectAttempts.value <= 3) {
connect()
addMessage('success', 'Ponowne połączenie udane!')
} else {
addMessage('error', 'Osiągnięto limit prób połączenia')
}
}, 1500)
}
// Cykl życia: montowanie
onMounted(() => {
addMessage('info', 'Monitor połączenia uruchomiony')
// Automatyczne połączenie po zamontowaniu
setTimeout(() => {
connect()
}, 1000)
// Symulacja losowych rozłączeń
connectionCheckId = setInterval(() => {
if (isConnected.value && Math.random() < 0.1) {
addMessage('warning', 'Utracono połączenie - zdarzenie losowe')
disconnect()
setTimeout(attemptReconnect, 2000)
}
}, 5000)
})
// Cykl życia: odmontowanie
onUnmounted(() => {
addMessage('info', 'Monitor połączenia się wyłącza')
if (intervalId) clearInterval(intervalId)
if (connectionCheckId) clearInterval(connectionCheckId)
disconnect()
})
return {
isConnected,
connectionTime,
disconnectionTime,
reconnectAttempts,
latency,
messages,
connect,
disconnect,
attemptReconnect
}
}
// Monitory połączeń dla różnych serwerów
const earthConnection = useConnectionMonitor('Centrum Dowodzenia na Ziemi')
const marsConnection = useConnectionMonitor('Baza Mars Alfa')
const satelliteConnection = useConnectionMonitor('Satelita orbitalny')
</script>
<template>
<div class="connection-lab">
<div class="header">
<h1>Monitor Połączeń - NOVA LAB</h1>
<p class="subtitle">Moduł 3: composables z hookami cyklu życia</p>
</div>
<div class="connections-grid">
<!-- Połączenie z Ziemią -->
<div class="connection-card" :class="{ connected: earthConnection.isConnected }">
<div class="connection-header">
<h3>Dowództwo na Ziemi</h3>
<div class="status-indicator" :class="{ active: earthConnection.isConnected }">
{{ earthConnection.isConnected ? 'ONLINE' : 'OFFLINE' }}
</div>
</div>
<div class="connection-stats">
<div class="stat-item">
<span class="stat-label">Opóźnienie:</span>
<span class="stat-value" :class="{ good: earthConnection.latency < 50 }">
{{ earthConnection.latency }}ms
</span>
</div>
<div class="stat-item">
<span class="stat-label">Próby połączenia:</span>
<span class="stat-value">{{ earthConnection.reconnectAttempts }}</span>
</div>
</div>
<div class="connection-times">
<div v-if="earthConnection.connectionTime" class="time-info">
Połączono: {{ earthConnection.connectionTime.toLocaleTimeString() }}
</div>
<div v-if="earthConnection.disconnectionTime" class="time-info">
Rozłączono: {{ earthConnection.disconnectionTime.toLocaleTimeString() }}
</div>
</div>
<div class="connection-controls">
<button
@click="earthConnection.connect"
:disabled="earthConnection.isConnected"
class="btn btn-success"
>
Połącz
</button>
<button
@click="earthConnection.disconnect"
:disabled="!earthConnection.isConnected"
class="btn btn-danger"
>
Rozłącz
</button>
<button
@click="earthConnection.attemptReconnect"
:disabled="earthConnection.isConnected"
class="btn btn-warning"
>
Ponów
</button>
</div>
<div class="messages-log">
<div
v-for="msg in earthConnection.messages.slice(0, 5)"
:key="msg.id"
class="log-message"
:class="'msg-' + msg.type"
>
<span class="msg-time">{{ msg.timestamp }}</span>
<span class="msg-text">{{ msg.text }}</span>
</div>
</div>
</div>
<!-- Połączenie z Marsem -->
<div class="connection-card" :class="{ connected: marsConnection.isConnected }">
<div class="connection-header">
<h3>Baza Mars Alfa</h3>
<div class="status-indicator" :class="{ active: marsConnection.isConnected }">
{{ marsConnection.isConnected ? 'ONLINE' : 'OFFLINE' }}
</div>
</div>
<div class="connection-stats">
<div class="stat-item">
<span class="stat-label">Opóźnienie:</span>
<span class="stat-value" :class="{ good: marsConnection.latency < 50 }">
{{ marsConnection.latency }}ms
</span>
</div>
<div class="stat-item">
<span class="stat-label">Próby połączenia:</span>
<span class="stat-value">{{ marsConnection.reconnectAttempts }}</span>
</div>
</div>
<div class="connection-times">
<div v-if="marsConnection.connectionTime" class="time-info">
Połączono: {{ marsConnection.connectionTime.toLocaleTimeString() }}
</div>
<div v-if="marsConnection.disconnectionTime" class="time-info">
Rozłączono: {{ marsConnection.disconnectionTime.toLocaleTimeString() }}
</div>
</div>
<div class="connection-controls">
<button
@click="marsConnection.connect"
:disabled="marsConnection.isConnected"
class="btn btn-success"
>
Połącz
</button>
<button
@click="marsConnection.disconnect"
:disabled="!marsConnection.isConnected"
class="btn btn-danger"
>
Rozłącz
</button>
<button
@click="marsConnection.attemptReconnect"
:disabled="marsConnection.isConnected"
class="btn btn-warning"
>
Ponów
</button>
</div>
<div class="messages-log">
<div
v-for="msg in marsConnection.messages.slice(0, 5)"
:key="msg.id"
class="log-message"
:class="'msg-' + msg.type"
>
<span class="msg-time">{{ msg.timestamp }}</span>
<span class="msg-text">{{ msg.text }}</span>
</div>
</div>
</div>
<!-- Połączenie z satelitą -->
<div class="connection-card" :class="{ connected: satelliteConnection.isConnected }">
<div class="connection-header">
<h3>Satelita orbitalny</h3>
<div class="status-indicator" :class="{ active: satelliteConnection.isConnected }">
{{ satelliteConnection.isConnected ? 'ONLINE' : 'OFFLINE' }}
</div>
</div>
<div class="connection-stats">
<div class="stat-item">
<span class="stat-label">Opóźnienie:</span>
<span class="stat-value" :class="{ good: satelliteConnection.latency < 50 }">
{{ satelliteConnection.latency }}ms
</span>
</div>
<div class="stat-item">
<span class="stat-label">Próby połączenia:</span>
<span class="stat-value">{{ satelliteConnection.reconnectAttempts }}</span>
</div>
</div>
<div class="connection-times">
<div v-if="satelliteConnection.connectionTime" class="time-info">
Połączono: {{ satelliteConnection.connectionTime.toLocaleTimeString() }}
</div>
<div v-if="satelliteConnection.disconnectionTime" class="time-info">
Rozłączono: {{ satelliteConnection.disconnectionTime.toLocaleTimeString() }}
</div>
</div>
<div class="connection-controls">
<button
@click="satelliteConnection.connect"
:disabled="satelliteConnection.isConnected"
class="btn btn-success"
>
Połącz
</button>
<button
@click="satelliteConnection.disconnect"
:disabled="!satelliteConnection.isConnected"
class="btn btn-danger"
>
Rozłącz
</button>
<button
@click="satelliteConnection.attemptReconnect"
:disabled="satelliteConnection.isConnected"
class="btn btn-warning"
>
Ponów
</button>
</div>
<div class="messages-log">
<div
v-for="msg in satelliteConnection.messages.slice(0, 5)"
:key="msg.id"
class="log-message"
:class="'msg-' + msg.type"
>
<span class="msg-time">{{ msg.timestamp }}</span>
<span class="msg-text">{{ msg.text }}</span>
</div>
</div>
</div>
</div>
<div class="info-panel">
<h3>Hooki cyklu życia w composables</h3>
<div class="info-content">
<p><strong>useConnectionMonitor()</strong> pokazuje, jak używać hooków cyklu życia:</p>
<ul>
<li><strong>onMounted()</strong> - automatyczne połączenie i start monitoringu</li>
<li><strong>onUnmounted()</strong> - czyszczenie interwałów i rozłączenie</li>
<li>Każda instancja composable ma własne hooki cyklu życia</li>
<li>Automatyczne zarządzanie zasobami (timery, połączenia)</li>
<li>Zapobieganie wyciekom pamięci przez sprzątanie w onUnmounted</li>
</ul>
<div class="code-example">
<code>
function useConnectionMonitor(url) {
onMounted(() => {
// Start: automatyczne połączenie, start monitoringu
})
onUnmounted(() => {
// Sprzątanie: wyczyść timery, rozłącz
})
return { isConnected, connect, disconnect }
}
</code>
</div>
</div>
</div>
</div>
</template>
<style scoped>
.connection-lab {
background: linear-gradient(135deg, #0a0e27 0%, #1a1e3f 100%);
min-height: 100vh;
padding: 2rem;
color: #ffffff;
font-family: 'Courier New', monospace;
}
.header {
text-align: center;
margin-bottom: 2rem;
padding-bottom: 1rem;
border-bottom: 2px solid #00ff88;
}
.header h1 {
font-size: 2.5rem;
color: #00ff88;
text-shadow: 0 0 20px rgba(0, 255, 136, 0.5);
margin: 0;
}
.subtitle {
color: #00b4d8;
font-size: 1.2rem;
margin-top: 0.5rem;
}
.connections-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
gap: 1.5rem;
margin-bottom: 2rem;
}
.connection-card {
background: rgba(255, 0, 85, 0.1);
border: 2px solid #ff0055;
border-radius: 10px;
padding: 1.5rem;
transition: all 0.3s ease;
}
.connection-card.connected {
background: rgba(0, 255, 136, 0.1);
border-color: #00ff88;
}
.connection-header {
display: flex;
justify-content: space-between;
align-items: center;
margin-bottom: 1.5rem;
}
.connection-header h3 {
color: #00ff88;
margin: 0;
font-size: 1.3rem;
}
.status-indicator {
padding: 0.5rem 1rem;
border-radius: 20px;
background: rgba(255, 0, 85, 0.3);
color: #ff0055;
font-weight: bold;
font-size: 0.9rem;
}
.status-indicator.active {
background: rgba(0, 255, 136, 0.3);
color: #00ff88;
animation: pulse 2s infinite;
}
.connection-stats {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 1rem;
margin-bottom: 1rem;
}
.stat-item {
background: rgba(0, 0, 0, 0.3);
padding: 1rem;
border-radius: 5px;
text-align: center;
}
.stat-label {
display: block;
color: #00b4d8;
font-size: 0.8rem;
margin-bottom: 0.5rem;
}
.stat-value {
display: block;
color: #ffb400;
font-size: 1.5rem;
font-weight: bold;
}
.stat-value.good {
color: #00ff88;
}
.connection-times {
background: rgba(0, 0, 0, 0.3);
padding: 1rem;
border-radius: 5px;
margin-bottom: 1rem;
min-height: 60px;
}
.time-info {
color: #ffffff;
font-size: 0.9rem;
margin: 0.25rem 0;
}
.connection-controls {
display: flex;
gap: 0.5rem;
margin-bottom: 1rem;
}
.messages-log {
background: rgba(0, 0, 0, 0.5);
border-radius: 5px;
padding: 1rem;
max-height: 200px;
overflow-y: auto;
}
.log-message {
display: flex;
gap: 1rem;
padding: 0.5rem;
margin: 0.25rem 0;
border-left: 3px solid;
border-radius: 3px;
font-size: 0.85rem;
}
.msg-success {
border-color: #00ff88;
background: rgba(0, 255, 136, 0.1);
}
.msg-warning {
border-color: #ffb400;
background: rgba(255, 180, 0, 0.1);
}
.msg-error {
border-color: #ff0055;
background: rgba(255, 0, 85, 0.1);
}
.msg-info {
border-color: #00b4d8;
background: rgba(0, 180, 216, 0.1);
}
.msg-time {
color: #00b4d8;
min-width: 80px;
font-size: 0.75rem;
}
.msg-text {
color: #ffffff;
flex: 1;
}
.btn {
flex: 1;
padding: 0.75rem;
border: none;
border-radius: 5px;
font-weight: bold;
cursor: pointer;
font-family: 'Courier New', monospace;
transition: all 0.3s ease;
font-size: 0.9rem;
}
.btn:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.btn-success {
background: #00ff88;
color: #0a0e27;
}
.btn-danger {
background: #ff0055;
color: #ffffff;
}
.btn-warning {
background: #ffb400;
color: #0a0e27;
}
.btn:not(:disabled):hover {
transform: scale(1.05);
box-shadow: 0 5px 15px rgba(0, 255, 136, 0.3);
}
.info-panel {
background: rgba(0, 180, 216, 0.05);
border: 2px solid #00b4d8;
border-radius: 10px;
padding: 2rem;
}
.info-panel h3 {
color: #00ff88;
margin-top: 0;
margin-bottom: 1.5rem;
}
.info-content ul {
list-style: none;
padding: 0;
}
.info-content li {
padding: 0.5rem 0;
color: #ffffff;
line-height: 1.6;
}
.code-example {
background: rgba(0, 0, 0, 0.5);
border-left: 4px solid #00ff88;
border-radius: 5px;
padding: 1rem;
margin-top: 1rem;
}
.code-example code {
color: #00ff88;
font-size: 0.9rem;
white-space: pre;
display: block;
}
@keyframes pulse {
0%, 100% { opacity: 1; }
50% { opacity: 0.6; }
}
</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. Co oferuje biblioteka VueUse?
2. Do czego służy useLocalStorage z VueUse?
To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Stwórz responsywny komponent z computed properties isMobile, isTablet, isDesktop.
- Układanie w pionie
Ułóż kroki instalacji i użycia VueUse:
- Klikanie w kolejności
Ułóż import composable z VueUse:
- Edytor kodu
Użyj useDark i useToggle do stworzenia przełącznika dark mode z odpowiednią klasą CSS.
- Układanie w poziomie
Ułóż destrukturyzację useWindowSize: