Um Guia Completo sobre Eventos de Janela e Bindings Reativos

O objeto window do navegador funciona como a porta de entrada entre sua aplicação e o viewport do usuário, os dispositivos de entrada e a sessão de navegação. No desenvolvimento JavaScript tradicional, interagir com window exige um gerenciamento cuidadoso do ciclo de vida — adicionar event listeners no momento certo, removê-los para evitar vazamentos de memória e lidar com as particularidades da renderização no servidor, onde window simplesmente não existe.

O elemento especial <svelte:window> do Svelte 5 abstrai elegantemente essas complexidades, fornecendo uma interface declarativa que se encaixa naturalmente no modelo de componentes, ao mesmo tempo em que lida automaticamente com a limpeza e a segurança em SSR.

Este tutorial examina o <svelte:window> desde seus conceitos fundamentais até padrões arquiteturais avançados. Vamos explorar não apenas como usar este elemento, mas também quando recorrer a ele em vez de alternativas como o módulo svelte/reactivity/window, e como arquitetar componentes que respondam graciosamente a mudanças no estado da janela sem introduzir gargalos de desempenho ou anti-padrões arquiteturais.

Entendendo o Espaço do Problema

Por Que o Tratamento Especial de Window é Importante

Antes de mergulhar no <svelte:window> em si, vamos entender os desafios que ele resolve. Considere o que acontece quando você deseja responder a atalhos de teclado em uma aplicação JavaScript tradicional:

// Traditional approach - fraught with potential issues
class KeyboardHandler {
	constructor(callback) {
		this.callback = callback
		this.handleKeydown = this.handleKeydown.bind(this)
		window.addEventListener('keydown', this.handleKeydown)
	}

	handleKeydown(event) {
		if (event.key === 'Escape') {
			this.callback('escape-pressed')
		}
	}

	destroy() {
		// Easy to forget this, leading to memory leaks
		window.removeEventListener('keydown', this.handleKeydown)
	}
}

Este padrão introduz vários modos de falha que os desenvolvedores encontram com frequência. O método destroy precisa ser chamado explicitamente, e esquecê-lo cria vazamentos de memória onde os event listeners persistem mesmo após o componente não existir mais conceitualmente.

Em contextos de renderização no servidor, esse código lança erros porque window é indefinido. O padrão de binding com this adiciona sobrecarga cognitiva, e gerenciar múltiplos tipos de eventos multiplica essa complexidade.

Os elementos especiais do Svelte transformam essa complexidade imperativa em simplicidade declarativa, mantendo a abordagem característica do framework para limpeza automática.

A Anatomia do `<svelte:window>`

Acesso Declarativo ao Window

O elemento <svelte:window> existe puramente em tempo de compilação — ele não produz nenhuma saída no DOM e não pode conter filhos. Seu único propósito é fornecer uma superfície declarativa para anexar event handlers e bindings ao objeto window:

<svelte:window onevent={handler} />
<svelte:window bind:property={value} />

O elemento deve aparecer no nível superior do seu componente, o que significa que não pode estar aninhado dentro de blocos condicionais, loops ou outros elementos. Essa restrição existe porque o Svelte precisa configurar e desmontar esses bindings durante a inicialização e a destruição do componente, respectivamente.

Vamos examinar um exemplo fundamental que demonstra a mecânica central:

<script>
	let lastKeyPressed = $state('')
	let keyPressCount = $state(0)

	function handleKeydown(event) {
		lastKeyPressed = event.key
		keyPressCount += 1
	}
</script>

<svelte:window onkeydown={handleKeydown} />

<div class="keyboard-monitor">
	<p>Last key pressed: <code>{lastKeyPressed || 'None'}</code></p>
	<p>Total key presses: {keyPressCount}</p>
</div>

Quando o Svelte compila este componente, ele gera código que adiciona o event listener quando o componente é montado e o remove quando o componente é desmontado. Isso acontece automaticamente — não há limpeza manual necessária, nenhum método de ciclo de vida para lembrar, nenhuma oportunidade para vazamentos de memória causados por limpeza esquecida.

Padrões de Tratamento de Eventos

O <svelte:window> suporta todos os eventos DOM padrão que o objeto window emite. Isso inclui eventos de teclado (keydown, keyup), eventos de mouse (scroll, resize), eventos de foco (focus, blur), entre muitos outros.

Entendendo as Assinaturas dos Event Handlers

Os event handlers de window recebem o objeto de evento DOM padrão, permitindo que você acesse todas as propriedades e métodos nativos. A convenção de nomenclatura de eventos do Svelte 5 usa o prefixo on seguido do nome do evento em letras minúsculas:

<script>
	let scrollY = $state(0)
	let scrollDirection = $state('none')
	let previousScrollY = 0

	function handleScroll(event) {
		// event.currentTarget is window in this context
		const currentScrollY = window.scrollY

		if (currentScrollY > previousScrollY) {
			scrollDirection = 'down'
		} else if (currentScrollY < previousScrollY) {
			scrollDirection = 'up'
		}

		previousScrollY = currentScrollY
		scrollY = currentScrollY
	}
</script>

<svelte:window onscroll={handleScroll} />

<header class={{ scrolled: scrollY > 50, hide: scrollDirection === 'down' && scrollY > 100 }}>
	<nav>Navigation content</nav>
</header>

<style>
	header {
		position: fixed;
		top: 0;
		transition: transform 0.3s ease;
	}

	header.scrolled {
		background: rgba(255, 255, 255, 0.95);
		box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
	}

	header.hide {
		transform: translateY(-100%);
	}
</style>

Este padrão implementa um "cabeçalho inteligente" que se esconde ao rolar para baixo e reaparece ao rolar para cima — um padrão de UX comum que exige rastrear não apenas a posição de rolagem, mas também a direção.

Múltiplos Event Handlers e Composição de Eventos

Você pode anexar múltiplos handlers ao mesmo elemento listando-os separadamente ou combinando-os. O Svelte 5 permite múltiplos handlers para o mesmo tipo de evento:

<script>
  import { analyticsTracker } from './analytics.js';

  let windowFocused = $state(true);
  let lastActivity = $state(Date.now());

  function handleFocus() {
    windowFocused = true;
    lastActivity = Date.now();
  }

  function handleBlur() {
    windowFocused = false;
  }

  function handleActivity() {
    lastActivity = Date.now();
  }

  function trackInteraction(event) {
    analyticsTracker.recordInteraction({
      type: event.type,
      timestamp: Date.now(),
      windowFocused
    });
  }
</script>

<svelte:window
  onfocus={handleFocus}
  onblur={handleBlur}
  onmousemove={handleActivity}
  onkeydown={handleActivity}
  onclick={trackInteraction}
  onkeydown={trackInteraction}
/>

{#if !windowFocused}
  <div class="pause-overlay">
    <p>Application paused</p>
    <p>Click to resume</p>
  </div>
{/if}

Observe que onkeydown aparece duas vezes — uma para rastreamento de atividade e outra para analytics. O Svelte 5 lida com isso chamando ambos os handlers quando o evento é disparado. Esse padrão de composição permite separar responsabilidades sem criar funções de handler que fazem coisas demais.

Modificadores de Eventos e Tratamento na Fase de Captura

Os modificadores de evento do Svelte funcionam com <svelte:window> da mesma forma que com elementos regulares. O modificador capture é particularmente útil para eventos de window quando você precisa interceptar eventos antes que eles alcancem seus alvos:

<script>
	let interceptedKeys = $state([])

	function interceptKeydown(event) {
		// Capture phase fires before the target receives the event
		if (event.key === 'Tab' && event.shiftKey) {
			// Implement custom focus management
			event.preventDefault()
			handleReverseFocusNavigation()
		}

		interceptedKeys = [...interceptedKeys.slice(-9), event.key]
	}

	function handleReverseFocusNavigation() {
		// Custom focus logic here
	}
</script>

<svelte:window onkeydowncapture={interceptKeydown} />

<div class="key-log">
	<h3>Recent keys (captured):</h3>
	<ul>
		{#each interceptedKeys as key}
			<li><kbd>{key}</kbd></li>
		{/each}
	</ul>
</div>

A fase de captura é essencial ao criar componentes acessíveis que precisam gerenciar o foco antes que o comportamento padrão do navegador ocorra. Ao usar onkeydowncapture em vez de onkeydown, o handler é disparado durante a fase de captura, dando a você acesso prioritário ao evento.

Bindings Reativos de Window:

Sincronizando o Estado do Componente com o Estado do Navegador

Além do tratamento de eventos, o <svelte:window> fornece bindings para propriedades específicas do window. Esses bindings se dividem em duas categorias: bindings somente leitura que refletem o estado do navegador, e bindings bidirecionais que tanto leem quanto podem modificar o estado do navegador.

Entendendo as Propriedades Vinculáveis

As seguintes propriedades podem ser vinculadas ao <svelte:window>:

Bindings somente leitura (refletindo o estado atual do window):

innerWidth - A largura interior da janela em pixels
innerHeight - A altura interior da janela em pixels
outerWidth - A largura total da janela do navegador, incluindo elementos da interface
outerHeight - A altura total da janela do navegador, incluindo elementos da interface
online - Um alias para navigator.onLine, indicando conectividade de rede
devicePixelRatio - A proporção entre pixels físicos e CSS

Bindings bidirecionais (podem ser lidos e modificados):

scrollX - Posição de rolagem horizontal (pode ser definida para rolar programaticamente)
scrollY - Posição de rolagem vertical (pode ser definida para rolar programaticamente)

A natureza somente leitura da maioria dos bindings reflete uma verdade fundamental: seu componente não pode alterar as dimensões da janela nem o status de rede do usuário. Você só pode observar esses valores e responder de acordo.

Criando Componentes Responsivos com Bindings de Dimensão

Os bindings de dimensão habilitam comportamento responsivo que vai além das media queries CSS. Considere um cenário onde você precisa renderizar estruturas de componentes diferentes com base no tamanho do viewport:

<script>
	let innerWidth = $state(0)
	let innerHeight = $state(0)

	// Derived breakpoint logic
	let breakpoint = $derived(
		innerWidth < 640
			? 'mobile'
			: innerWidth < 1024
				? 'tablet'
				: innerWidth < 1440
					? 'desktop'
					: 'wide'
	)

	let orientation = $derived(innerHeight > innerWidth ? 'portrait' : 'landscape')

	// Calculate optimal grid columns based on actual width
	let optimalColumns = $derived(Math.max(1, Math.floor(innerWidth / 300)))
</script>

<svelte:window bind:innerWidth bind:innerHeight />

<div class="dashboard" style:--columns={optimalColumns}>
	{#if breakpoint === 'mobile'}
		<MobileNavigation />
	{:else}
		<DesktopSidebar collapsed={breakpoint === 'tablet'} />
	{/if}

	<main class="content">
		<header class="metrics">
			<span>Viewport: {innerWidth}×{innerHeight}</span>
			<span>Breakpoint: {breakpoint}</span>
			<span>Orientation: {orientation}</span>
		</header>

		<div class="grid">
			{#each items as item}
				<GridItem {item} compact={breakpoint === 'mobile'} />
			{/each}
		</div>
	</main>
</div>

<style>
	.grid {
		display: grid;
		grid-template-columns: repeat(var(--columns), 1fr);
		gap: 1rem;
	}
</style>

Este padrão oferece diversas vantagens em relação às abordagens puramente CSS. Primeiro, você pode renderizar condicionalmente árvores de componentes completamente diferentes em vez de apenas ocultar elementos. Segundo, você pode passar informações de breakpoint para componentes filhos como props, habilitando comportamento responsivo coordenado. Terceiro, você pode calcular valores derivados como contagens ideais de colunas que dependem de dimensões exatas em pixels.

Bindings de Posição de Rolagem: Implementando Comportamentos de Rolagem Complexos

Os bindings scrollX e scrollY merecem atenção especial porque são bidirecionais — você pode tanto ler a posição de rolagem atual quanto defini-la para rolar programaticamente:

<script>
	let scrollY = $state(0)
	let targetSection = $state(null)

	// Section positions would typically be calculated dynamically
	const sections = [
		{ id: 'intro', name: 'Introduction', offset: 0 },
		{ id: 'features', name: 'Features', offset: 800 },
		{ id: 'pricing', name: 'Pricing', offset: 1600 },
		{ id: 'contact', name: 'Contact', offset: 2400 }
	]

	// Determine active section based on scroll position
	let activeSection = $derived(
		sections.reduce((active, section) => {
			if (scrollY >= section.offset - 100) {
				return section
			}
			return active
		}, sections[0])
	)

	function scrollToSection(section) {
		// Setting scrollY programmatically scrolls the window
		targetSection = section
		scrollY = section.offset
	}

	// Smooth scroll effect using $effect
	$effect(() => {
		if (targetSection) {
			// For smooth scrolling, you might use window.scrollTo instead
			window.scrollTo({
				top: targetSection.offset,
				behavior: 'smooth'
			})
			targetSection = null
		}
	})
</script>

<svelte:window bind:scrollY />

<nav class="section-nav">
	{#each sections as section}
		<button
			class={{ active: activeSection?.id === section.id }}
			onclick={() => scrollToSection(section)}
		>
			{section.name}
		</button>
	{/each}
</nav>

<div class="scroll-indicator">
	<div class="progress" style:height="{(scrollY / 2400) * 100}%"></div>
</div>

A natureza bidirecional dos bindings de rolagem cria possibilidades interessantes, mas também armadilhas em potencial. Definir scrollY diretamente causa um salto imediato para essa posição — para rolagem suave, você deve usar window.scrollTo com a opção behavior: 'smooth' em vez disso.

Monitorando o Status de Rede com o Binding `online`

O binding online reflete navigator.onLine, fornecendo uma forma reativa de responder a mudanças na conectividade de rede:

<script>
	let online = $state(true)
	let offlineQueue = $state([])
	let reconnectAttempts = $state(0)

	// React to connectivity changes
	$effect(() => {
		if (online && offlineQueue.length > 0) {
			processOfflineQueue()
		}
	})

	async function processOfflineQueue() {
		const queue = [...offlineQueue]
		offlineQueue = []

		for (const action of queue) {
			try {
				await action.execute()
			} catch (error) {
				// Re-queue failed actions
				offlineQueue = [...offlineQueue, action]
			}
		}
	}

	function queueAction(action) {
		if (online) {
			action.execute()
		} else {
			offlineQueue = [...offlineQueue, action]
		}
	}
</script>

<svelte:window bind:online />

{#if !online}
	<div class="offline-banner" role="alert">
		<span class="icon">📡</span>
		<span>You're offline. Changes will sync when connected.</span>
		{#if offlineQueue.length > 0}
			<span class="badge">{offlineQueue.length} pending</span>
		{/if}
	</div>
{/if}

O binding online fornece uma abstração conveniente, mas lembre-se de que navigator.onLine tem limitações. Ele indica se o navegador acredita ter acesso à rede, não se essa rede consegue realmente alcançar seus servidores. Para um tratamento robusto de modo offline, combine este binding com a detecção real de sucesso/falha nas requisições.

Suporte a Displays de Alta Densidade com `devicePixelRatio`

O binding devicePixelRatio permite renderização adaptativa para displays de alta densidade (High-DPI):

<script>
	let devicePixelRatio = $state(1)
	let canvas

	// Reactive canvas sizing based on DPR
	$effect(() => {
		if (!canvas) return

		const rect = canvas.getBoundingClientRect()
		const ctx = canvas.getContext('2d')

		// Scale canvas for high-DPI displays
		canvas.width = rect.width * devicePixelRatio
		canvas.height = rect.height * devicePixelRatio

		ctx.scale(devicePixelRatio, devicePixelRatio)

		// Redraw content at appropriate resolution
		drawVisualization(ctx, rect.width, rect.height)
	})

	function drawVisualization(ctx, width, height) {
		// Drawing code here renders at native resolution
		ctx.fillStyle = '#3b82f6'
		ctx.fillRect(10, 10, width - 20, height - 20)
	}
</script>

<svelte:window bind:devicePixelRatio />

<div class="canvas-container">
	<canvas bind:this={canvas}></canvas>
	<p class="dpr-info">Device Pixel Ratio: {devicePixelRatio}</p>
</div>

<style>
	canvas {
		width: 100%;
		height: 300px;
	}
</style>

Note que o comportamento do devicePixelRatio varia entre navegadores. O Chrome atualiza esse valor em resposta a mudanças no nível de zoom, enquanto Firefox e Safari normalmente refletem apenas a densidade de pixels nativa do display.

O Módulo `svelte/reactivity/window`

Uma Abordagem Alternativa

O Svelte 5.11.0 introduziu o svelte/reactivity/window, um módulo que fornece versões reativas dos valores do window sem precisar do elemento <svelte:window>. Essa abordagem alternativa oferece diferentes trade-offs que vale entender.

Entendendo os Valores Reativos do Window

O módulo exporta objetos com uma propriedade reativa current:

<script>
	import {
		innerWidth,
		innerHeight,
		outerWidth,
		outerHeight,
		scrollX,
		scrollY,
		online,
		devicePixelRatio,
		screenLeft,
		screenTop
	} from 'svelte/reactivity/window'
</script>

<div class="viewport-info">
	<p>Window size: {innerWidth.current}×{innerHeight.current}</p>
	<p>Outer size: {outerWidth.current}×{outerHeight.current}</p>
	<p>Scroll position: ({scrollX.current}, {scrollY.current})</p>
	<p>Screen position: ({screenLeft.current}, {screenTop.current})</p>
	<p>Network status: {online.current ? 'Online' : 'Offline'}</p>
	<p>Pixel ratio: {devicePixelRatio.current}</p>
</div>

screenLeft e screenTop rastreiam a posição da janela do navegador na tela e são atualizados dentro de um callback requestAnimationFrame. Todos os valores são undefined durante SSR.

A propriedade .current é reativa, o que significa que ela é atualizada automaticamente quando o valor subjacente do window muda. Esses valores reativos funcionam perfeitamente em templates, valores derivados e efeitos.

Quando Usar `svelte/reactivity/window` vs `<svelte:window>`

Prefira svelte/reactivity/window quando:

Você só precisa ler valores, não lidar com eventos. O módulo fornece valores reativos, mas sem capacidade de tratamento de eventos.
Você está trabalhando em um arquivo .svelte.js ou .svelte.ts. Como esses arquivos não podem conter sintaxe de template, você não pode usar <svelte:window>, mas pode importar do módulo.
Você quer compartilhar o estado reativo do window entre múltiplos componentes. As exportações do módulo são singletons, tornando-os ideais para cenários de estado compartilhado.

// lib/window-state.svelte.js
import { innerWidth, innerHeight } from 'svelte/reactivity/window'

export function useResponsive() {
	let breakpoint = $derived(
		innerWidth.current < 640 ? 'mobile' : innerWidth.current < 1024 ? 'tablet' : 'desktop'
	)

	let isCompact = $derived(innerWidth.current < 640 || innerHeight.current < 480)

	return {
		get breakpoint() {
			return breakpoint
		},
		get isCompact() {
			return isCompact
		},
		get width() {
			return innerWidth.current
		},
		get height() {
			return innerHeight.current
		}
	}
}

Prefira <svelte:window> quando:

Você precisa lidar com eventos do window. O módulo não suporta tratamento de eventos — apenas <svelte:window> fornece essa capacidade.
Você precisa de bindings de scroll bidirecionais. Embora o módulo forneça scrollX e scrollY, eles são somente leitura. Apenas os bindings de <svelte:window> permitem rolagem programática por atribuição.
Você prefere manter as interações com o window explícitas no seu template. O elemento torna as dependências do window visíveis na marcação do componente.

Combinando as Duas Abordagens

Às vezes, a solução ideal combina as duas abordagens:

<script>
	import { innerWidth, innerHeight } from 'svelte/reactivity/window'

	let lastScrollDirection = $state('none')
	let previousScrollY = 0

	// Use module for reactive values
	let isMobile = $derived(innerWidth.current < 640)

	// Use element for event handling
	function handleScroll() {
		const currentY = window.scrollY
		lastScrollDirection = currentY > previousScrollY ? 'down' : 'up'
		previousScrollY = currentY
	}
</script>

<!-- Event handling requires the element -->
<svelte:window onscroll={handleScroll} />

<header class={{ mobile: isMobile, scrolled: lastScrollDirection === 'down' }}>
	<!-- Header content -->
</header>

Considerações sobre Renderização no Lado do Servidor

Um dos recursos mais valiosos do <svelte:window> é sua segurança com SSR. O elemento não produz saída durante a renderização no servidor, e seus bindings resolvem para undefined no servidor:

<script>
	let innerWidth = $state(undefined)
	let innerHeight = $state(undefined)

	// These will be undefined during SSR
	let isClient = $derived(innerWidth !== undefined)
</script>

<svelte:window bind:innerWidth bind:innerHeight />

{#if isClient}
	<div class="client-only-ui">
		Viewport: {innerWidth}×{innerHeight}
	</div>
{:else}
	<div class="placeholder">Loading viewport information...</div>
{/if}

O módulo svelte/reactivity/window segue o mesmo padrão — todos os valores .current são undefined no servidor:

<script>
	import { innerWidth } from 'svelte/reactivity/window'

	// innerWidth.current is undefined during SSR
	let greeting = $derived(
		innerWidth.current === undefined
			? 'Welcome!'
			: innerWidth.current < 640
				? 'Hello, mobile user!'
				: 'Hello, desktop user!'
	)
</script>

<h1>{greeting}</h1>

Lidando com Incompatibilidades de Hidratação

Uma armadilha comum ocorre quando o conteúdo renderizado no servidor não corresponde à renderização inicial no cliente. Considere este padrão problemático:

<script>
	import { innerWidth } from 'svelte/reactivity/window'

	// PROBLEM: Server renders default, client renders actual
	let columns = $derived(
		innerWidth.current === undefined
			? 3 // Server default
			: Math.floor(innerWidth.current / 300)
	)
</script>

<div class="grid" style:--columns={columns}>
	<!-- Grid items -->
</div>

Se o servidor renderiza com 3 colunas, mas a viewport do cliente resulta em 4 colunas, a hidratação detectará uma incompatibilidade. As soluções incluem:

Aceitar a incompatibilidade inicial com um estado de carregamento:

<script>
	import { innerWidth } from 'svelte/reactivity/window'

	let mounted = $state(false)

	$effect(() => {
		mounted = true
	})

	let columns = $derived(!mounted ? 3 : Math.floor((innerWidth.current ?? 900) / 300))
</script>

Usar CSS para o layout inicial, JavaScript para aprimoramento:

<script>
	import { innerWidth } from 'svelte/reactivity/window'

	let calculatedColumns = $derived(innerWidth.current ? Math.floor(innerWidth.current / 300) : null)
</script>

<div class="grid" style:--columns={calculatedColumns}>
	<!-- Grid items -->
</div>

<style>
	.grid {
		display: grid;
		/* CSS default, overridden by JS when available */
		grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
	}

	.grid[style*='--columns'] {
		grid-template-columns: repeat(var(--columns), 1fr);
	}
</style>

Padrões Avançados e Considerações Arquiteturais

Construindo um Gerenciador de Estado do Window

Para aplicações complexas, centralizar o gerenciamento de estado do window proporciona consistência e reduz listeners redundantes:

// lib/window-manager.svelte.js
import { innerWidth, innerHeight, online } from 'svelte/reactivity/window'

class WindowManager {
	// Breakpoint definitions
	breakpoints = {
		mobile: 640,
		tablet: 1024,
		desktop: 1440
	}

	get width() {
		return innerWidth.current
	}

	get height() {
		return innerHeight.current
	}

	get isOnline() {
		return online.current
	}

	get currentBreakpoint() {
		const width = this.width
		if (width === undefined) return 'unknown'
		if (width < this.breakpoints.mobile) return 'mobile'
		if (width < this.breakpoints.tablet) return 'tablet'
		if (width < this.breakpoints.desktop) return 'desktop'
		return 'wide'
	}

	get isMobile() {
		return this.currentBreakpoint === 'mobile'
	}

	get isTablet() {
		return this.currentBreakpoint === 'tablet'
	}

	get isDesktop() {
		return ['desktop', 'wide'].includes(this.currentBreakpoint)
	}

	get orientation() {
		if (this.width === undefined || this.height === undefined) {
			return 'unknown'
		}
		return this.height > this.width ? 'portrait' : 'landscape'
	}

	get aspectRatio() {
		if (this.width === undefined || this.height === undefined) {
			return undefined
		}
		return this.width / this.height
	}
}

export const windowManager = new WindowManager()

O uso nos componentes se torna notavelmente limpo:

<script>
	import { windowManager } from '$lib/window-manager.svelte.js'
</script>

{#if windowManager.isMobile}
	<MobileLayout />
{:else if windowManager.isTablet}
	<TabletLayout />
{:else}
	<DesktopLayout />
{/if}

<footer>
	{windowManager.currentBreakpoint} | {windowManager.orientation}
</footer>

Implementando Sistemas de Atalhos de Teclado

O tratamento de teclado em nível de window permite atalhos em toda a aplicação. Um sistema bem arquitetado evita conflitos e suporta a descoberta de atalhos:

<script>
	import { getContext, setContext } from 'svelte'

	// Shortcut registry
	let shortcuts = $state(new Map())

	function registerShortcut(key, modifiers, handler, description) {
		const id = `${modifiers.sort().join('+')}+${key}`
		shortcuts.set(id, { key, modifiers, handler, description })

		return () => shortcuts.delete(id)
	}

	function handleKeydown(event) {
		const modifiers = []
		if (event.ctrlKey || event.metaKey) modifiers.push('ctrl')
		if (event.shiftKey) modifiers.push('shift')
		if (event.altKey) modifiers.push('alt')

		const id = `${modifiers.sort().join('+')}+${event.key.toLowerCase()}`
		const shortcut = shortcuts.get(id)

		if (shortcut) {
			event.preventDefault()
			shortcut.handler(event)
		}
	}

	// Provide context for child components
	setContext('shortcuts', { register: registerShortcut, shortcuts })

	// Built-in shortcuts
	registerShortcut('k', ['ctrl'], () => openCommandPalette(), 'Open command palette')
	registerShortcut('/', [], () => focusSearch(), 'Focus search')
	registerShortcut('escape', [], () => closeModals(), 'Close modal')
</script>

<svelte:window onkeydown={handleKeydown} />

<slot />

<!-- Optional: Shortcut help modal -->
{#if showShortcutHelp}
	<div class="shortcut-help">
		<h2>Keyboard Shortcuts</h2>
		<dl>
			{#each [...shortcuts.values()] as shortcut}
				<dt>
					{#each shortcut.modifiers as mod}
						<kbd>{mod}</kbd> +
					{/each}
					<kbd>{shortcut.key}</kbd>
				</dt>
				<dd>{shortcut.description}</dd>
			{/each}
		</dl>
	</div>
{/if}

Componentes filhos podem então registrar seus próprios atalhos:

<script>
	import { getContext, onDestroy } from 'svelte'

	const { register } = getContext('shortcuts')

	// Register component-specific shortcuts
	const unregisterSave = register('s', ['ctrl'], handleSave, 'Save document')
	const unregisterUndo = register('z', ['ctrl'], handleUndo, 'Undo')

	onDestroy(() => {
		unregisterSave()
		unregisterUndo()
	})
</script>

Debouncing e Throttling de Eventos do Window

Alguns eventos do window disparam com alta frequência, especialmente scroll e resize. Sem limitação de taxa, os handlers podem causar problemas de desempenho:

<script>
	let scrollY = $state(0)
	let innerWidth = $state(0)

	// Throttle scroll handler (fires at most once per frame)
	let scrollTicking = false
	function handleScroll() {
		if (!scrollTicking) {
			requestAnimationFrame(() => {
				scrollY = window.scrollY
				scrollTicking = false
			})
			scrollTicking = true
		}
	}

	// Debounce resize handler (fires after resizing stops)
	let resizeTimeout
	function handleResize() {
		clearTimeout(resizeTimeout)
		resizeTimeout = setTimeout(() => {
			innerWidth = window.innerWidth
			recalculateLayout()
		}, 150)
	}

	function recalculateLayout() {
		// Expensive layout calculations here
	}
</script>

<svelte:window onscroll={handleScroll} onresize={handleResize} />

Para os bindings do svelte:window (em oposição a handlers de eventos), o Svelte já lida com atualizações de forma eficiente. Os bindings usam o sistema de eventos nativo do navegador e atualizam reativamente — você não precisa aplicar debounce manualmente.

Coordenando Múltiplos Componentes que Dependem do Window

Quando múltiplos componentes precisam do estado do window, evite duplicar elementos <svelte:window>. Em vez disso, eleve a interação com o window para um componente pai compartilhado ou use o módulo svelte/reactivity/window:

<!-- Layout.svelte - Single source of window state -->
<script>
	let { children } = $props()
	let innerWidth = $state(0)
	let innerHeight = $state(0)
	let scrollY = $state(0)

	// Provide via context
	import { setContext } from 'svelte'

	setContext('viewport', {
		get width() {
			return innerWidth
		},
		get height() {
			return innerHeight
		},
		get scrollY() {
			return scrollY
		}
	})
</script>

<svelte:window bind:innerWidth bind:innerHeight bind:scrollY />

{@render children()}

<!-- ChildComponent.svelte - Consumes via context -->
<script>
	import { getContext } from 'svelte'

	const viewport = getContext('viewport')

	// Use viewport.width, viewport.height, viewport.scrollY
</script>

Comparação com Elementos Especiais Relacionados

O Svelte fornece uma família de elementos especiais para diferentes alvos do DOM. Entender suas distinções ajuda você a escolher a ferramenta certa:

`<svelte:window>` vs `<svelte:document>`

<svelte:document> faz binding ao document em vez do window:

<svelte:document
	onvisibilitychange={handleVisibilityChange}
	bind:activeElement
	bind:fullscreenElement
	bind:visibilityState
/>

O document fornece propriedades diferentes — activeElement para rastreamento de foco, visibilityState para visibilidade de aba, e fullscreenElement para detecção de tela cheia. Alguns eventos, como visibilitychange, disparam no document em vez do window.

`<svelte:window>` vs `<svelte:body>`

<svelte:body> se conecta ao document.body:

<svelte:body onmouseenter={handleMouseEnter} onmouseleave={handleMouseLeave} />

Eventos como mouseenter e mouseleave não propagam (bubble) até o window, tornando o <svelte:body> necessário para detectar quando o mouse entra ou sai da área da viewport.

Armadilhas Comuns e Como Evitá-las

1. Acessando Window na Fase Errada do Ciclo de Vida

Problema: Acessar o objeto global window diretamente no escopo do script de nível superior ou durante a inicialização do componente.

Consequências: O objeto window é uma API específica do navegador. Aplicações SvelteKit normalmente são executadas primeiro no servidor (SSR), onde window não existe. Acessá-lo diretamente faz a aplicação falhar com erros "window is not defined" durante a renderização no servidor.

Como Evitar: Use bindings de <svelte:window>, que são automaticamente seguros para SSR, ou envolva o acesso manual ao window dentro de $effect (que só é executado no navegador).

<script>
	// WRONG: window doesn't exist during SSR
	let currentWidth = window.innerWidth

	// CORRECT: use binding or check for existence
	let innerWidth = $state(0)

	// Or check manually
	$effect(() => {
		if (typeof window !== 'undefined') {
			// Safe to access window
		}
	})
</script>

<svelte:window bind:innerWidth />

2. Criando Múltiplos Listeners para o Mesmo Evento

Problema: Colocar <svelte:window> dentro de um componente que é instanciado múltiplas vezes, como dentro de um bloco {#each}.

Consequências: Cada instância do componente adiciona seu próprio listener de evento ao objeto window global. Se você renderizar uma lista de 100 itens, inadvertidamente cria 100 listeners de scroll separados. Isso desperdiça memória e degrada o desempenho, pois o navegador precisa executar 100 funções para cada evento.

Como Evitar: Mova a interação com o window para um único componente pai (como um layout ou contêiner de lista) e passe os dados relevantes para os filhos via props ou contexto.

<!-- WRONG: Each instance creates redundant listeners -->
{#each items as item}
	<ItemComponent />
{/each}

<!-- Where ItemComponent has: -->
<svelte:window onscroll={handleScroll} />

3. Operações Pesadas em Handlers de Alta Frequência

Problema: Executar cálculos intensos, consultas ao DOM (document.querySelector) ou leituras que disparam layout (offsetWidth) dentro de handlers para eventos de alta frequência como scroll, resize ou mousemove.

Consequências: Esses eventos podem disparar dezenas de vezes por segundo (até a taxa de atualização da tela). Operações pesadas bloqueiam a thread principal, causando "jank" (queda de frames), interface não responsiva e alto uso de CPU.

Como Evitar: Use throttling para limitar a frequência de execução, ou requestAnimationFrame para sincronizar as atualizações com o ciclo de renderização do navegador.

<script>
	// WRONG: DOM measurement on every scroll event
	function handleScroll() {
		const elements = document.querySelectorAll('.item')
		elements.forEach((el) => {
			// Expensive operations
		})
	}

	// CORRECT: Throttle and cache
	let items = []
	let ticking = false

	function handleScroll() {
		if (!ticking) {
			requestAnimationFrame(() => {
				// Process cached items
				ticking = false
			})
			ticking = true
		}
	}
</script>

<svelte:window onscroll={handleScroll} />

4. Esquecendo as Implicações do SSR em Valores Derivados

Problema: Criar estado derivado que realiza cálculos sobre bindings do window sem tratar o estado inicial undefined durante o SSR.

Consequências: Durante a Renderização no Lado do Servidor, bindings do window como innerWidth são undefined. Operações matemáticas sobre undefined (como undefined / 200) resultam em NaN ou lançam erros. Isso pode fazer a renderização no servidor falhar ou produzir HTML inválido com valores NaN.

Como Evitar: Sempre forneça um valor de fallback ou verifique explicitamente a existência de undefined na sua lógica derivada para garantir um estado padrão válido para o HTML renderizado no servidor.

<script>
	let innerWidth = $state(undefined)

	// WRONG: Fails when innerWidth is undefined
	let columnCount = $derived(Math.floor(innerWidth / 200))

	// CORRECT: Handle undefined case
	let columnCount = $derived(innerWidth !== undefined ? Math.floor(innerWidth / 200) : 3)
</script>

<svelte:window bind:innerWidth />

Boas Práticas de Desempenho

1. Minimize os Bindings Reativos

Cada propriedade que você vincula ao <svelte:window> cria um listener de evento interno e uma sincronização de estado reativo. Vincular propriedades que você não utiliza adiciona overhead desnecessário.

Boa Prática: Vincule apenas as propriedades específicas que sua lógica requer.

<!-- WRONG: Over-binding creates unnecessary listeners and updates -->
<svelte:window
  bind:innerWidth
  bind:innerHeight
  bind:scrollX
  bind:scrollY
/>

<!-- CORRECT: Bind only what is needed -->
<svelte:window bind:scrollY />

2. Prefira CSS para Responsividade Visual

A responsividade baseada em JavaScript (usando innerWidth) força o navegador a executar código, recalcular estilos e repintar a cada evento de resize. Isso é significativamente mais lento do que as media queries CSS nativas, que são otimizadas pelo motor do navegador.

Boa Prática: Use media queries CSS para mudanças de layout. Reserve os bindings de <svelte:window> para lógica que não pode ser expressa em CSS (como renderização condicional de componentes pesados ou dimensionamento de canvas).

<style>
	/* FAST: Handled by the browser's layout engine */
	.sidebar {
		width: 100%;
	}
	@media (min-width: 768px) {
		.sidebar {
			width: 300px;
		}
	}
</style>

3. Use Estado Derivado para Cálculos com Window

Evite usar $effect para atualizar manualmente o estado com base em mudanças do window. Isso dispara uma segunda passagem de renderização. Em vez disso, use $derived para computar valores derivados dos bindings do window. A reatividade de granularidade fina do Svelte garante que esses valores só sejam recalculados quando as dependências específicas mudarem.

Boa Prática: Compute valores dependentes do window usando $derived.

<script>
	let innerWidth = $state(0)
	let innerHeight = $state(0)

	// EFFICIENT: Calculates lazily and only when dependencies change
	let viewport = $derived({
		width: innerWidth,
		height: innerHeight,
		aspectRatio: innerWidth / innerHeight,
		isLandscape: innerWidth > innerHeight,
		breakpoint: innerWidth < 640 ? 'mobile' : 'desktop'
	})
</script>

<svelte:window bind:innerWidth bind:innerHeight />

Essa abordagem é mais eficiente do que usar $effect porque aproveita o sistema de reatividade do Svelte para computar valores apenas quando as dependências mudam, sem disparar ciclos de renderização adicionais.

Conclusão

O elemento especial <svelte:window> exemplifica a filosofia do Svelte de tornar tarefas comuns trivialmente fáceis, mantendo os casos de uso avançados possíveis. Ao abstrair a complexidade do gerenciamento do ciclo de vida dos listeners de evento e da segurança no SSR, ele permite que você se concentre no que importa: construir aplicações responsivas e interativas que respondam graciosamente ao ambiente do usuário.

A introdução do svelte/reactivity/window no Svelte 5.11 oferece uma abordagem complementar para cenários onde você precisa de valores reativos do window sem a sintaxe de binding baseada em template.

Ao construir componentes que interagem com o window, lembre-se destes princípios arquiteturais: centralize o estado do window quando múltiplos componentes precisarem dele, escolha a estratégia de limitação de taxa adequada para eventos de alta frequência, projete para SSR desde o início e prefira CSS para responsividade puramente visual.

Os padrões explorados aqui—gerenciadores centralizados de window, sistemas de atalhos de teclado e gerenciamento coordenado de estado—demonstram que a interação com o window não é apenas sobre mecânica técnica, mas sobre arquitetura cuidadosa.

Em conjunto, essas ferramentas e padrões permitem construir aplicações que não são apenas funcionais, mas otimizadas para os diversos ambientes onde os usuários as experimentam. A janela do navegador é o frame da sua aplicação—<svelte:window> fornece as ferramentas para tornar esse frame um participante ativo na experiência do seu usuário.

Principais Conclusões

<svelte:window> fornece tratamento declarativo e seguro para SSR de eventos do window com limpeza automática, eliminando a necessidade de gerenciamento manual de listeners e prevenindo vazamentos de memória
Handlers de evento suportam eventos DOM padrão (onkeydown, onscroll, onresize) com tratamento opcional da fase de captura usando o sufixo capture (ex.: onkeydowncapture)
Bindings reativos habilitam fluxo de dados bidirecional com propriedades somente leitura (innerWidth, innerHeight, outerWidth, outerHeight, online, devicePixelRatio) e propriedades de scroll graváveis (scrollX, scrollY)
O módulo svelte/reactivity/window oferece uma alternativa para ler valores do window em arquivos .svelte.js ou compartilhar estado entre componentes, mas não possui capacidades de tratamento de eventos nem de rolagem programática
A segurança para SSR é incorporada - todos os bindings resolvem para undefined no servidor, exigindo valores de fallback na lógica derivada para evitar incompatibilidades de hidratação
A otimização de desempenho requer throttling de eventos de alta frequência (scroll, resize, mousemove) usando requestAnimationFrame ou debouncing, e preferir media queries CSS sobre JavaScript para responsividade visual
Os padrões arquiteturais incluem gerenciamento centralizado de estado via contexto ou módulos reativos, gerenciadores hierárquicos de window para lógica de breakpoints e registros de atalhos de teclado com tratamento de prioridade
As armadilhas comuns envolvem acesso durante SSR, criação de listeners redundantes em loops, operações pesadas em handlers de eventos e esquecimento de tratar undefined em cálculos derivados

Veja Também

Documentação Oficial do Svelte 5 - <svelte:window>
MDN Web Docs - Interface Window
<svelte:document> - Elemento especial similar para eventos em nível de documento
<svelte:body> - Tratamento de eventos em nível de body para diferentes cenários de propagação de eventos
Svelte 5 Runes - $derived - Computações reativas baseadas no estado do window
Renderização no Lado do Servidor (SSR) no SvelteKit - Entendendo as restrições do SSR com APIs do navegador
Design Responsivo com Media Queries CSS - Quando preferir CSS em vez de responsividade com JavaScript